/respira-builder-edits

name: respira-builder-edits
description: Use for any in-page content edit on a WordPress site with a page builder. Covers finding elements, applying surgical edits, duplicating before large changes, and verifying the result. Works across Elementor 3 + 4, Divi 4 + 5, Beaver Builder, Bricks, Oxygen Classic, Oxygen 6, Breakdance, WPBakery, Uncode, and Gutenberg.
license: MIT
metadata:
  short-description: Safe, builder-native in-page editing across all supported builders
  version: 1.2.1
  updated_at: 2026-05-17
  respira_min_version: 7.1.0

Respira Builder Edits

Common Mistakes

| Mistake | Correct approach | |---|---| | Using `respira_update_page` to change a heading, image, or button | Use `respira_find_element` then `respira_update_element`. The page tool replaces the whole body and the builder loses every node. | | Calling `respira_update_page` without checking `respira_get_builder_info` | Always identify the builder first. Update_page destroys builder JSON on builder-managed pages. | | Editing raw builder JSON by guessing field names | Read the current structure with `respira_read_page`, `respira_find_element`, or `respira_get_builder_inline_schemas` before writing. | | Making large changes without a snapshot | Always call `respira_create_page_duplicate` before multi-element edits. | | Assuming Divi 5 uses the same field as Divi 4 | Divi 4 stores shortcodes in `post_content`. Divi 5 stores blocks plus a per-node `attrs._nodeId` minted by the complexifier. By-id matching needs the `_nodeId` fallback (added in v7.0.30). | | Passing nested Divi 5 payloads through `children` only | Divi 5 also accepts Divi-vocabulary aliases `rows / cols / modules` (folded in v7.0.32). Pre-v7.0.32 these silently dropped. | | Using a non-existent Beaver Builder module type | The `content_field_map` covers Heading, Text, Button, Image, HTML, Video, Sidebar, and Box (added in v7.0.13). Unknown types fall through without an error. | | Passing flat `updates` like `{"button_text": "Go"}` | Pass either flat OR `{settings: {button_text: "Go"}}`. v7.0.16 deep-merges both into the settings object. v7.0.19 extended this through Divi 4. v7.0.29 extended it through `update_module` and `apply_builder_patch`. | | Skipping `respira_get_page_outline` for "what is on this page" reads | The outline is lighter than `extract_builder_content` and ships per-row child counts plus a primary heading. Use it before deciding which element to edit. |

Inputs

• The page or post URL, ID, or slug.
• A description of what to change (text, image URL, color, style, link).
• The builder in use, or unknown. Auto-detect with `respira_get_builder_info`.

Workflow

1. **Understand the site.** Call `respira_get_site_context` and `respira_get_builder_info` if you haven't already. 2. **Understand the page.** Call `respira_get_page_outline` for a fast structural read, or `respira_find_element` if you already know what to target. 3. **Live pages go through a duplicate.** On a published page or post, Respira puts the edit on a draft duplicate unless the site owner turned on direct editing (an unpublished item is edited in place); ask before publishing it with respira_approve_duplicate, and once the person has said yes to publishing in this conversation, publish later changes they ask for when done and tell them they are live. Every page write also saves a snapshot first, so there is nothing to create by hand. 4. **Find the element.** `respira_find_element` with the most specific selector available: text content, CSS class, widget type, or element ID. Bricks 2.3.x + Divi 5 surface both `id` and `attrs._nodeId`; either works. 5. **Apply the edit.** `respira_update_element` with only the fields that change. For multi-element edits on the same page, prefer `respira_batch_update`. 6. **Verify.** Re-read the element and confirm the change is reflected. For Divi 5, also check the front-end if it's a CSS or style-driven change because the renderer has its own paths. 7. **Report.** Tell the user what changed and where.

Builder-specific notes

• **Elementor 3.** Content lives in `_elementor_data`. Each widget has `id`, `widgetType`, and `settings`. The base path is mature.
• **Elementor 4 (Atomic Elements).** v7.1 added end-to-end write support across 9 atomic widgets (`e-heading`, `e-paragraph`, `e-button`, `e-image`, `e-svg`, `e-divider`, `e-youtube`, `e-self-hosted-video`, `e-component`) plus 11 atomic layout containers (`e-flexbox`, `e-div-block`, `e-grid`, the `e-tabs` family, the `e-form` family). Pre-v7.1 every atomic write returned 422 `respira_elementor_atomic_write_unsupported`. The v4 normaliser lifts shorthand to the canonical `$$type` envelopes; the v4 validator catches malformed nodes before they hit the DB. Unsupported atomic types still refuse fast with `supported_widgets` in the error body.
• **Divi 4.** Shortcodes in `post_content`. v7.0.19 + v7.0.29 fixed update_element, batch_update, apply_builder_patch, remove_element, inject_builder_content, and update_module. The kses bypass survives so `<script>` and `<style>` inside `et_pb_code` are preserved. Custom post types are supported.
• **Divi 5.** Blocks plus `attrs._nodeId`. v7.0.16 fixed the background overlay key (`overlay.enable` is what the renderer reads). v7.0.28 fixed the number-counter typed envelope and the button text colour dual-write. v7.0.30 added the `_nodeId` fallback for id matching. v7.0.32 added the children-aliases fold (`rows`, `cols`, `modules`) plus a hard-error on silent child drops.
• **Beaver Builder.** v7.0.13 added Box module mappings. v7.0.16 fixed typed-node normalisation (`{type:'row', columns:[…]}`). v7.0.17 defaults missing column `size` to "100" so columns render full-width when the agent omits it. v7.0.25 fixed the top-level font-field stdClass fatal. v7.0.26 expanded that to typography containers. Custom HTML in modules survives the kses bypass.
• **Bricks.** v7.0.23 fixed page-settings deep-merge and the CSS regen API. v7.0.24 close