---
name: elementor-niwa-native-editing
description: "Use when editing WordPress Elementor pages inside Niwa without shell/process access: inspect Elementor pages with native tools, update widgets or full _elementor_data through WordPress APIs, clear caches, and verify live output without WP-CLI or proc_open."
triggers: []
scope: "general"
version: 1
source: "bundled"
bundle_signature: "elementor-niwa-native-editing-v1"
license: MIT
metadata:
  author: Eclips
  hermes:
    tags: [wordpress, elementor, no-shell, proc-open-off, native-tools, cache, verification]
    related_skills: [elementor-wp-cli-editing, osam-rs-wordpress-workflow, web-runtime-ops-playbooks]
---

# Elementor Niwa Native Editing

## Runtime Gate

Use this skill when Niwa must edit Elementor without WP-CLI, shell, or `proc_open`.

This is the correct route when `main_coding_shell_run`, `main_coding_test_run`, or `code_scan_run` are unavailable. Do not try pseudo shell calls. Use the WordPress-native tools already exposed by Niwa.

If `main_coding_shell_run` is available and the task is a deep structural rebuild that is easier through WP-CLI scripts, you may use `elementor-wp-cli-editing` instead. For ordinary Elementor text, image, link, style, and data writes, stay on this native route.

## Tool Map

Read/discovery tools:

- `elementor_list_pages`
- `elementor_get_page_structure`
- `elementor_get_page_data`
- `elementor_find_widgets`
- `elementor_get_widget_by_id`
- `elementor_search_text`
- `read_post_field`
- `search_text_in_post`
- `wp_search_posts`
- `wp_get_post`

Write tools:

- `elementor_update_widget_content`
- `elementor_update_widget_image`
- `elementor_update_widget_link`
- `elementor_update_widget_styles`
- `elementor_assign_global_color`
- `replace_text_in_post`
- `elementor_update_page_data`
- `elementor_restore_or_repair`
- `cache_flush`
- `rollback_last_action`

`elementor_update_page_data` is the native full-page JSON write path. It writes `_elementor_data` with WordPress APIs, can update `post_content`, deletes Elementor caches, stores backups, and supports rollback. Use it only after you have read the current JSON and validated the replacement JSON.

## Workflow

### 1. Identify the target page

Use one of:

- `elementor_list_pages` for Elementor-built pages.
- `elementor_search_text` when you know visible text but not the page.
- `wp_search_posts` when the page is not confirmed as Elementor yet.
- `search_text_in_post` when you need to know whether text lives in `post_content`, `_elementor_data`, or another meta key.

Confirm the exact `post_id` before writes.

### 2. Read current structure

For structure:

```text
elementor_get_page_structure
post_id: <ID>
include_settings: true
max_depth: 20
```

For full raw Elementor JSON:

```text
elementor_get_page_data
post_id: <ID>
include_raw: true
max_chars: 500000
```

For readable text nodes:

```text
read_post_field
target_type: post_id
target_value: <ID>
field: elementor_data
extract_text: true
```

Record the returned `raw_sha256` if you will use `elementor_update_page_data`. If `raw_truncated` is true, do not perform a full structure edit from that payload; increase `max_chars` or ask for shell/proc_open temporarily.

### 3. Pick the narrowest native write

Use widget-level tools when possible:

- Text in heading/button/text-editor: `elementor_update_widget_content`.
- Button URL: `elementor_update_widget_link`.
- Image widget: `elementor_update_widget_image`.
- Colors, typography, padding, margin: `elementor_update_widget_styles`.
- Kit color reference: `elementor_assign_global_color`.

Use `replace_text_in_post` when exact text replacement across a known field is enough:

1. Call `search_text_in_post`.
2. Take `field_for_replace` from the result.
3. Call `replace_text_in_post` with that exact field.
4. For Elementor V4 atomic content, update both `post_content` and `meta:_elementor_data` when the search result says both are required.

Use `elementor_update_page_data` only for full structure operations:

- clone/reorder a container or card;
- insert a new section built from an existing Elementor node;
- remove or reorder nested Elementor elements;
- make a JSON transformation not covered by widget-level tools.

### 4. Full structure edit with no shell

Read raw `elementor_data` with `elementor_get_page_data`. Treat it as structured JSON, not text. Build a replacement JSON object mentally or through available no-shell reasoning, preserving:

- existing styling/settings unless the task explicitly changes them;
- all non-target nodes;
- valid Elementor nesting;
- unique IDs for every cloned node.

When cloning, generate new 7-character lowercase hex Elementor IDs and ensure they do not exist elsewhere in the tree.

Then call:

```text
elementor_update_page_data
post_id: <ID>
elementor_data_json: <full replacement JSON string>
expected_current_sha256: <optional current raw JSON sha256>
post_content: <optional updated fallback HTML>
```

Use `post_content` only when the fallback/SEO/snapshot content should be synchronized. Do not invent fallback HTML if the page has no meaningful fallback content.

### 5. Cache handling

Elementor native write tools clear Elementor data caches automatically:

- `_elementor_css`
- `_elementor_element_cache`
- `uploads/elementor/css/post-<ID>.css`
- Elementor files manager cache when available
- WordPress object/post cache

If the site still serves stale public output, call `cache_flush`.

### 6. Verify

Use at least one storage verification and one live verification.

Storage:

- `read_post_field field=elementor_data extract_text=true`
- `elementor_get_page_structure include_settings=true`
- `elementor_get_widget_by_id` for exact changed widget IDs

Live:

- `read_post_field field=rendered` for rendered server HTML.
- Browser/mobile verification if layout, spacing, section order, or responsive behavior changed.

Do not claim success until the changed content/order/link/style is visible in verified output.

## Failure Handling

- If the current `_elementor_data` is invalid JSON, use `elementor_restore_or_repair`.
- If a widget-level write is not expressive enough, use `elementor_update_page_data`.
- If a structural edit cannot be represented safely from available context because raw JSON is truncated or missing, report the blocker and ask for shell/proc_open to be enabled temporarily or request a new native tool extension.
- If a write breaks layout, use `rollback_last_action` or `elementor_restore_or_repair` depending on the returned rollback state.

## Safety Rules

- Never choose the WP-CLI skill just because this task mentions Elementor. Choose it only when the current runtime has shell capability or external SSH is being used.
- Never duplicate Elementor IDs.
- Never raw-replace JSON punctuation.
- Never rely on language-specific keywords to identify intent or targets; use post IDs, widget IDs, fields, meta keys, and tool-returned paths.
- Keep no-shell edits inside Niwa native tools. They do not require `proc_open`.
