@jini-ai/ui 0.3.8 → 0.3.10

package/dist/features/html-editor/react/hooks/useInteractiveHtmlEditor.js

@@ -1,9 +1,10 @@
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import grapesjs, {} from 'grapesjs';
 import { applyCanvasContentWrapper } from '../../canvas-content-wrapper.js';
 import { applyCanvasEmbedPlaceholders } from '../../canvas-embed-placeholders.js';
-import { buildCanvasStyleConfig } from '../../canvas-style.js';
+import { buildCanvasStyleConfig, CANVAS_STYLES_PENDING_CLASS } from '../../canvas-style.js';
 import { prettifyCss } from '../../css.js';
+import { indexElementSourceRanges, pathKey, spliceElementInner } from '../../source-splice.js';
 /**
  * @file `InteractiveHtmlEditor`'s GrapesJS lifecycle: construct the editor once per mount against
  * the container ref, wire content-change notifications out, and tear the editor down on unmount.
@@ -38,10 +39,13 @@ const PROTECTED_ELEMENT_TYPE = 'protected-element';
 const RTE_ACTIONS = ['bold', 'italic', 'link'];
 /**
  * Registers the `protected-element` component type so any parsed element `isProtectedElement`
- * recognizes is locked out of every GrapesJS interaction that could mutate or move it: not editable
- * (excluded from RTE content-editing, including as a nested island inside a `text` component), not
- * draggable/droppable/removable, and hidden from the layers/style/settings panels this component's
- * minimal chrome does not render anyway. Passed as a `plugins` entry so it registers before
+ * recognizes becomes one atomic block: its content can never be edited (excluded from RTE
+ * content-editing, including as a nested island inside a `text` component), dropped into, or styled,
+ * but the element itself is selectable and can be deliberately moved, copied or deleted like any other
+ * block. Selectable matters for safety: a non-selectable element hands a click to its nearest
+ * selectable ancestor, so clicking an embed selected the block around it and Delete then removed that
+ * block together with the embed. Pair it with `applyCanvasEmbedPlaceholders`, which makes the marker
+ * the clickable surface of its card. Passed as a `plugins` entry so it registers before
  * `editor.setComponents` parses the initial `html` (see `initInteractiveHtmlEditor` below).
  *
  * @complexity O(1) — one type registration; the per-element check GrapesJS then runs during parsing
@@ -54,15 +58,16 @@ function registerProtectedElementType(editor, isProtectedElement) {
         model: {
             defaults: {
                 editable: false,
-                draggable: false,
                 droppable: false,
-                removable: false,
-                selectable: false,
-                highlightable: false,
-                hoverable: false,
+                stylable: false,
                 layerable: false,
                 badgable: false,
-                stylable: false,
+                selectable: true,
+                hoverable: true,
+                highlightable: true,
+                removable: true,
+                draggable: true,
+                copyable: true,
             },
         },
     });
@@ -77,34 +82,262 @@ function initInteractiveHtmlEditor(container, html, isProtectedElement, canvasSt
         panels: { defaults: [] },
         blockManager: { blocks: [] },
         richTextEditor: { actions: RTE_ACTIONS },
+        // Default `true`. Left `true`, GrapesJS rewrites every inline `style="…"` into a generated
+        // `#iXXXX` CSS rule the moment ANY edit triggers a re-sync — including on elements the operator
+        // never touched — which is one of Bug C's root-cause symptoms (see this repo's `pages-redo` plan,
+        // "Bug C"). `false` here is the editor-wide config half of that fix; `serializeCleaned` below is
+        // the other half (the splice path does not depend on this at all, since it never re-serializes
+        // untouched elements from the component model in the first place).
+        avoidInlineStyle: false,
         canvas: buildCanvasStyleConfig(canvasStyling),
         plugins: isProtectedElement
             ? [(editor) => registerProtectedElementType(editor, isProtectedElement)]
             : [],
     });
 }
+/** Mirrors `source-splice.ts`'s own `UNINDEXED_TAGS` filter, but for GrapesJS's live component tree
+ *  rather than a parsed HTML string: `textnode` and `comment` components never consume a path slot,
+ *  matching how `indexElementSourceRanges` numbers the original string. No equivalent check is needed
+ *  for `style`/`script` here — GrapesJS never represents either as a tree component in the first
+ *  place (moved into `CssComposer`, or dropped outright), so a live sibling list already excludes
+ *  them without this hook's help. */
+function isPathableComponent(component) {
+    return !component.is('textnode') && !component.is('comment');
+}
+/**
+ * `component`'s element-only child path from the editor's wrapper root, in the exact numbering
+ * scheme `indexElementSourceRanges` uses for the original HTML string — so a path computed here can
+ * be looked up directly against that index. Returns `null` only if `component` (or an ancestor)
+ * cannot be found in its own parent's `components()` collection, which is not reachable for a live
+ * component an actual GrapesJS event just handed this hook; kept as a defensive guard rather than
+ * assumed away, the same convention `canvas-embed-placeholders.ts`'s own "Unreachable ... defensive
+ * only" comment uses for its analogous case.
+ *
+ * @complexity O(d + s) — d = depth from the wrapper, s = total siblings visited across every
+ * ancestor level. Editor documents in this product are shallow; not a hot path.
+ */
+function computeComponentPath(component) {
+    const path = [];
+    let current = component;
+    for (;;) {
+        const parent = current.parent();
+        if (!parent)
+            return path;
+        const siblings = parent.components().models;
+        const at = siblings.indexOf(current);
+        if (at === -1)
+            return null; // Unreachable for a live component; defensive only.
+        const elementIndex = siblings.slice(0, at).filter(isPathableComponent).length;
+        path.unshift(elementIndex);
+        current = parent;
+    }
+}
 /**
- * `editor.getHtml()` and `editor.getCss()` are separate outputs in GrapesJS — the component tree
- * and its CSS rules live in independent models (`CodeManager` vs `CssComposer`). Confirmed live, the
- * hard way: calling `getHtml()` alone silently drops every CSS rule the moment a real edit triggers
- * GrapesJS's component-tree re-sync (before any edit, GrapesJS passes an unparsed `<style>` block
- * through untouched, masking this; after one real edit, `getHtml()`'s output is built fresh from the
- * component model, which has no CSS in it at all — reproduced with a real page's content: one text
- * edit took `getHtml()`'s output from 8215 characters down to 3160, `<style>` block and all rules
- * gone, the typed edit itself the only thing that survived). `keepUnusedStyles: true` on `getCss()`
- * matters here specifically: real documents commonly carry `@media` blocks and `::before`/`::after`
- * rules that don't correspond to any single "matched" component in the tree — GrapesJS's default CSS
- * export can drop rules it doesn't consider currently referenced, which would silently re-lose exactly
- * the kind of rule a real design (dark-mode variants, decorative pseudo-elements) depends on.
+ * Records (or overwrites) the latest inner HTML for the nearest `text` component whose content
+ * changed, keyed by its element-only path. Silently ignores anything that is not a `text` component
+ * — this is the mechanism that keeps a non-text element (a host's embed marker `<div>`, an image, a
+ * plain container) from ever becoming a splice target, even if some other GrapesJS event happens to
+ * name it as its argument — and anything whose path cannot be resolved from the live tree.
  */
-function serializeEditorContent(editor) {
-    const css = editor.getCss({ keepUnusedStyles: true });
-    const html = editor.getHtml();
+function recordDirtyTextEdit(component, dirty) {
+    if (!component || !component.is('text'))
+        return;
+    const path = computeComponentPath(component);
+    if (!path)
+        return;
+    dirty.set(pathKey(path), { path, tagName: component.tagName.toLowerCase(), component });
+}
+/**
+ * True when `component` sits inside a `text` component: the inline and textnode children GrapesJS's
+ * `syncContent` removes and re-adds every time an RTE session closes. That churn is part of a text
+ * edit, which the splice already covers, not a block edit. A just-removed component has no `parent()`
+ * any more, so the walk starts from `prevColl.parent` (the collection it was removed from).
+ *
+ * @complexity O(d) in the component's depth.
+ */
+function isInsideTextComponent(component) {
+    let current = component.parent() ?? component.prevColl?.parent;
+    while (current) {
+        if (current.is('text'))
+            return true;
+        current = current.parent();
+    }
+    return false;
+}
+/** Dev-only, so a fallback is never silent — see `serializeWithSplice` for each trigger this names. */
+function warnFallback(reason) {
+    if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[useInteractiveHtmlEditor] falling back to full re-serialization: ${reason}`);
+    }
+}
+/**
+ * Fallback whole-document serialization for when the lossless splice (see `serializeWithSplice`)
+ * cannot be trusted. This is the "cleaned" formula from this repo's `pages-redo` plan ("Bug C"), and
+ * differs from the whole-document serialization this hook used before the splice existed:
+ * `avoidProtected: true` on `getCss()` drops GrapesJS's own `* { box-sizing: border-box; } body
+ * {margin: 0;}` block, which GrapesJS otherwise prepends even to a page with no CSS of its own; and
+ * `getWrapper().getInnerHTML()` — the wrapper's INNER content — omits the `<body>` tag `editor.
+ * getHtml()` serializes the wrapper component itself as. Combined with `avoidInlineStyle: false` on
+ * the editor's own config (see `initInteractiveHtmlEditor`), inline `style="…"` attributes also
+ * survive here instead of being rewritten into generated `#iXXXX` CSS rules. Still not a byte-
+ * identical round trip — this is a full re-serialization from GrapesJS's component model, which
+ * cannot recover the original string's entities or authored formatting — just the least-lossy shape
+ * available when a true splice is not possible.
+ *
+ * `keepUnusedStyles: true` carries over unchanged from the serialization this replaces: real
+ * documents commonly carry `@media` blocks and `::before`/`::after` rules that don't correspond to
+ * any single "matched" component in the tree, which GrapesJS's default CSS export can otherwise drop.
+ */
+function serializeCleaned(editor) {
+    const css = editor.getCss({ avoidProtected: true, keepUnusedStyles: true });
+    const wrapper = editor.getWrapper();
+    // `wrapper` is undefined only before/without a successful init, which cannot be true once this
+    // hook's `editor` has fired `update` — defensive only, mirroring `serializeCleaned`'s own doc.
+    const html = wrapper ? wrapper.getInnerHTML() : editor.getHtml();
     return css ? `<style>${prettifyCss(css)}</style>${html}` : html;
 }
+/**
+ * Builds this edit cycle's exported HTML. The default path splices every accumulated dirty text edit
+ * (see `recordDirtyTextEdit`) back into the ORIGINAL source string via `spliceElementInner` (see
+ * `source-splice.ts`), so every other byte — entities, attribute quoting, an untouched embed marker,
+ * unrelated formatting — passes through unchanged instead of being rebuilt from GrapesJS's component
+ * model. Falls back to `serializeCleaned` (and warns via `warnFallback`, so it is never silent)
+ * whenever that guarantee cannot be trusted:
+ *  - `structuralChange` — a block was added or removed since mount (a block move, clone, or delete;
+ *    a move fires a remove then an add). Its value names the first such event, for the warning. The
+ *    child churn inside a text component that every RTE close causes does not count (see
+ *    `isInsideTextComponent`); that is a text edit, which the splice covers. Every dirty path's offset was computed against the
+ *    pristine `original` string; once the LIVE tree's shape has diverged from it, those offsets (and
+ *    even the paths themselves) can silently address the wrong element instead of failing loudly, so
+ *    this is checked first and unconditionally, regardless of what is or isn't in `dirty`. There is no
+ *    path back to `false` once this flips — a later purely-textual edit still cannot trust offsets
+ *    computed before the structural change, so the whole rest of the mount stays on the cleaned path.
+ *  - `dirty` is empty — `update` fired (a real content/style/attribute mutation happened) but no
+ *    text-component edit was ever recorded for it. Nothing addressable means nothing spliceable.
+ *  - any individual `spliceElementInner` call returns `null` — that path's element is no longer where
+ *    it was, or its tag no longer matches what the live component believes.
+ *
+ * Dirty edits are applied in descending original-offset order (highest first): a splice at a later
+ * offset never shifts the byte positions of anything before it, so replaying strictly back-to-front
+ * lets every subsequent `spliceElementInner` call re-locate its own (still-untouched-until-its-turn)
+ * range correctly without this function tracking running offset deltas itself.
+ *
+ * @complexity O(n·k) where n = size of `original` (each of up to k dirty splices re-indexes the
+ * current string internally) and k = number of dirty edits accumulated this mount — small in
+ * practice (an operator edits a handful of elements per session), never a hot loop here.
+ */
+function serializeWithSplice(editor, original, dirty, structuralChange) {
+    if (structuralChange) {
+        warnFallback(`a block was added, moved, copied or deleted since mount (first: ${structuralChange})`);
+        return serializeCleaned(editor);
+    }
+    if (dirty.size === 0) {
+        warnFallback('no text edit was recorded for this change');
+        return serializeCleaned(editor);
+    }
+    const originalIndex = indexElementSourceRanges(original);
+    const ordered = [...dirty.values()].sort((a, b) => {
+        const aStart = originalIndex.get(pathKey(a.path))?.start ?? -1;
+        const bStart = originalIndex.get(pathKey(b.path))?.start ?? -1;
+        return bStart - aStart;
+    });
+    let result = original;
+    for (const edit of ordered) {
+        const spliced = spliceElementInner(result, edit.path, edit.tagName, edit.component.getInnerHTML());
+        if (spliced === null) {
+            warnFallback(`element at path "${pathKey(edit.path)}" could not be spliced (removed, or its tag drifted)`);
+            return serializeCleaned(editor);
+        }
+        result = spliced;
+    }
+    return result;
+}
+/**
+ * Ends whatever RTE session is currently open, so its pending edit syncs into the component model
+ * before `flush` reads it — GrapesJS only writes an RTE session's edited text into the model when
+ * that session closes (`disableEditing`/`syncContent`), never on every keystroke, so a save or
+ * unmount that skips this step silently loses the last, still-open edit. A throw from
+ * `disableEditing` (e.g. GrapesJS internals mid-teardown) must never block `flush` from still
+ * returning whatever was already recorded, so it is swallowed here rather than propagated.
+ *
+ * @complexity O(1) plus whatever the editor's own `disableEditing` costs.
+ */
+async function disableActiveTextEditing(editor) {
+    const editing = editor.getEditing();
+    if (!editing)
+        return;
+    try {
+        await editing.getView()?.disableEditing?.();
+    }
+    catch {
+        // Swallowed intentionally — see this function's doc.
+    }
+}
+/** Hard cap on how long the canvas can stay hidden waiting for its theme stylesheet(s) (Bug B, Slice
+ *  B1, this repo's `pages-redo` plan) — a dead URL or a hung dev-server reload must never hide the
+ *  editor forever. */
+const STYLESHEET_SETTLE_TIMEOUT_MS = 3000;
+/**
+ * Hides `body` behind {@link CANVAS_STYLES_PENDING_CLASS} until every `<link rel="stylesheet">`
+ * GrapesJS's `canvas.styles` config put in the canvas document (`editor.Canvas.getDocument()`) has
+ * fired `load` or `error`, or {@link STYLESHEET_SETTLE_TIMEOUT_MS} has elapsed — whichever comes first.
+ * Every Interactive mount re-fetches the theme stylesheet (see this repo's `pages-redo` plan, Bug B)
+ * with no guaranteed cache short-circuit; GrapesJS's own `FrameView` renders the canvas body without
+ * waiting for `<link>`s in `<head>` to resolve, so without this the operator sees raw browser-default
+ * styling (Times New Roman, blue links) for however long that fetch takes, or forever if the API is
+ * mid-restart. The cap is unconditional, independent of how many stylesheets are still pending.
+ *
+ * Must be called from `handleLoad`, AFTER the content wrapper and embed placeholder decoration have
+ * already run against the same `body` — so even the zero-stylesheet case (this function reveals in the
+ * same synchronous call) never shows an undecorated canvas for even one frame.
+ *
+ * @returns A cleanup callback that cancels the pending timer and detaches any still-registered
+ *   `load`/`error` listeners. Idempotent — safe to call again (from effect cleanup) after the canvas
+ *   has already revealed; a no-op then.
+ * @complexity O(n) in the number of `<link rel="stylesheet">` elements found — one listener pair per
+ *   link, no polling.
+ */
+function revealCanvasWhenStylesheetsSettle(editor, body) {
+    body.classList.add(CANVAS_STYLES_PENDING_CLASS);
+    const canvasDocument = editor.Canvas.getDocument();
+    // `getDocument()` returning null is not reachable once `load` has fired on a real editor — defensive
+    // only, same convention as this file's other "Unreachable ... defensive only" guards.
+    const links = canvasDocument ? Array.from(canvasDocument.querySelectorAll('link[rel="stylesheet"]')) : [];
+    let settled = false;
+    let timeoutId;
+    const pending = new Set();
+    const reveal = () => {
+        if (settled)
+            return;
+        settled = true;
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+        for (const link of pending) {
+            link.removeEventListener('load', handleSettle);
+            link.removeEventListener('error', handleSettle);
+        }
+        pending.clear();
+        body.classList.remove(CANVAS_STYLES_PENDING_CLASS);
+    };
+    function handleSettle(event) {
+        pending.delete(event.currentTarget);
+        if (pending.size === 0)
+            reveal();
+    }
+    for (const link of links) {
+        pending.add(link);
+        link.addEventListener('load', handleSettle);
+        link.addEventListener('error', handleSettle);
+    }
+    if (pending.size === 0)
+        reveal();
+    else
+        timeoutId = setTimeout(reveal, STYLESHEET_SETTLE_TIMEOUT_MS);
+    return reveal;
+}
 /**
  * Owns one GrapesJS `Editor` instance for the lifetime of the calling component's mount. `onChange`
- * fires with the editor's current serialized content (see `serializeEditorContent`) on every content
+ * fires with the editor's current serialized content (see `serializeWithSplice`) on every content
  * mutation (GrapesJS's `update` event — components, styles, or attributes changing); it is not
  * debounced, so a caller replacing an existing uncontrolled `<textarea>` (which already pushes a full
  * value on every keystroke) sees matching behavior.
@@ -124,6 +357,15 @@ function serializeEditorContent(editor) {
  * `class="frame"` forever, inert and unrendered. `.gjs-frame` — the class `FrameView.render()`
  * assigns — is what callers should select on, never a bare `iframe` under the wrapper.)
  *
+ * **`flush()` exists because GrapesJS's RTE only syncs on `disableEditing`, and `update` is
+ * double-debounced and never fires after `off()`.** A host that calls `onChange` on every keystroke
+ * (like an uncontrolled `<textarea>`) still misses the operator's last edit if they click Save or
+ * navigate away while an RTE session is still open: GrapesJS writes that session's text into the
+ * component model only when it closes, and by the time a host's save handler runs, this hook has
+ * already stopped listening (or the debounce hasn't fired yet). `flush` closes any open RTE session,
+ * computes and emits the current content the same way `handleUpdate` does, and hands the result back
+ * directly — see its own doc below for exactly what it returns and when.
+ *
  * @complexity O(1) setup/teardown. Steady-state cost is GrapesJS's own serialization per edit,
  * proportional to document size — not something this hook controls or should hide a note about
  * beyond that.
@@ -133,6 +375,9 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
     const wrapperRef = useRef(null);
     const onChangeRef = useRef(onChange);
     onChangeRef.current = onChange;
+    // Delegated to by the stable `flush` callback returned below. Reset to a no-op on cleanup, before
+    // `destroy()` — see the effect's cleanup for why the order matters.
+    const flushRef = useRef(async () => undefined);
     useEffect(() => {
         const wrapper = wrapperRef.current;
         if (!wrapper)
@@ -141,8 +386,73 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         mountEl.style.height = '100%';
         wrapper.appendChild(mountEl);
         const editor = initInteractiveHtmlEditor(mountEl, html, isProtectedElement, canvasStyling);
-        const handleUpdate = () => onChangeRef.current(serializeEditorContent(editor));
+        // Splice bookkeeping — see `serializeWithSplice`'s own doc for how these two are used. Plain
+        // closure state scoped to this one mount-only effect run (like `editor`/`mountEl` above), not
+        // `useRef`: nothing outside this effect ever reads them.
+        const dirty = new Map();
+        let structuralChange;
+        // True once `update` has fired at least once this mount — see `flush`'s "nothing to flush" guard
+        // below for why this is tracked separately from `dirty`/`structuralChange` (a style/attribute-only
+        // edit fires `update` with neither of those set, and still must not be silently dropped).
+        let changed = false;
+        // Set inside `handleLoad`, once the canvas body exists — see `revealCanvasWhenStylesheetsSettle`.
+        // `undefined` until then (or if `load` never fires before unmount), so cleanup below guards it.
+        let cancelStylesheetWait;
+        // Embed placeholder cards live only in the canvas DOM, so a structural edit (delete, move, clone,
+        // undo) can leave one stale. Repaired on the tick after the edit, once GrapesJS has rendered it;
+        // see `applyCanvasEmbedPlaceholders`. Only after `load`: before it, adds are the initial parse.
+        let loaded = false;
+        let cardRepair;
+        const scheduleCardRepair = () => {
+            if (!loaded || !describeEmbedPlaceholder || cardRepair !== undefined)
+                return;
+            cardRepair = setTimeout(() => {
+                cardRepair = undefined;
+                applyCanvasEmbedPlaceholders(editor.Canvas.getBody(), describeEmbedPlaceholder);
+            }, 0);
+        };
+        const handleUpdate = () => {
+            changed = true;
+            onChangeRef.current(serializeWithSplice(editor, html, dirty, structuralChange));
+        };
+        // `component:update:content` fires with the changed component itself as its argument (GrapesJS's
+        // general `component:update:{propertyName}` pattern); `rte:disable` fires with `(view, rte)` —
+        // the view whose RTE session just closed, `view.model` being the component it edited. Both name
+        // the SAME kind of thing (a text component whose content just changed) through two different
+        // GrapesJS code paths (a direct model update vs. the RTE toolbar's close), so both feed the one
+        // `recordDirtyTextEdit` sink rather than each growing their own tracking.
+        const handleContentUpdate = (component) => recordDirtyTextEdit(component, dirty);
+        const handleRteDisable = (view) => recordDirtyTextEdit(view?.model, dirty);
+        // A block move, copy or delete (the Interactive tab keeps all three, owner decision 2026-09-23)
+        // fires `component:add`/`component:remove` on the live tree. Once one fires outside a text
+        // component, `serializeWithSplice` stops trusting any offset computed against the original string
+        // for the rest of this mount; see its own doc for why this never resets.
+        const handleStructuralChange = (event) => (component) => {
+            scheduleCardRepair();
+            if (structuralChange || (component && isInsideTextComponent(component)))
+                return;
+            structuralChange = `${event} <${component?.tagName?.toLowerCase() || 'unknown'}>`;
+        };
+        const handleAdd = handleStructuralChange('component:add');
+        const handleRemove = handleStructuralChange('component:remove');
         editor.on('update', handleUpdate);
+        editor.on('component:update:content', handleContentUpdate);
+        editor.on('rte:disable', handleRteDisable);
+        editor.on('component:add', handleAdd);
+        editor.on('component:remove', handleRemove);
+        // See `flush`'s own doc for why this exists. Closes any open RTE session first (so its pending
+        // edit syncs into the model), then emits and returns the current content the same way
+        // `handleUpdate` does — except when nothing has changed since mount, matching `serializeWithSplice`'s
+        // own "nothing to flush" case: no `update` was ever seen, no text edit was recorded, and no
+        // structural change happened either.
+        flushRef.current = async () => {
+            await disableActiveTextEditing(editor);
+            if (!changed && dirty.size === 0 && !structuralChange)
+                return undefined;
+            const next = serializeWithSplice(editor, html, dirty, structuralChange);
+            onChangeRef.current(next);
+            return next;
+        };
         // `load` fires once the canvas's initial component render is done (`editor.Canvas.getBody()` is
         // populated) — see `applyCanvasContentWrapper`'s own file header for why the wrap has to happen
         // here, against the live canvas, rather than folded into `components` above. Embed placeholders
@@ -155,16 +465,32 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
             applyCanvasContentWrapper(body, canvasStyling.contentWrapper);
             if (describeEmbedPlaceholder)
                 applyCanvasEmbedPlaceholders(body, describeEmbedPlaceholder);
+            // Runs LAST, after both decorations above — see `revealCanvasWhenStylesheetsSettle`'s own doc
+            // for why that order matters even in the zero-stylesheet case.
+            cancelStylesheetWait = revealCanvasWhenStylesheetsSettle(editor, body);
+            loaded = true;
         };
         editor.on('load', handleLoad);
         return () => {
+            // FIRST, before `destroy()` — a `flush()` call racing (or arriving after) unmount must resolve
+            // `undefined` without ever touching the about-to-be-destroyed `editor`.
+            flushRef.current = async () => undefined;
             editor.off('update', handleUpdate);
+            editor.off('component:update:content', handleContentUpdate);
+            editor.off('rte:disable', handleRteDisable);
+            editor.off('component:add', handleAdd);
+            editor.off('component:remove', handleRemove);
             editor.off('load', handleLoad);
+            cancelStylesheetWait?.();
+            clearTimeout(cardRepair);
             editor.destroy();
             mountEl.remove();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally mount-only, see file header
     }, []);
-    return { containerRef: wrapperRef };
+    // Stable across renders (the effect above mutates `flushRef.current`, not this callback's identity)
+    // so a caller can safely pass `flush` into a `useCallback`/`useImperativeHandle` dependency array.
+    const flush = useCallback(() => flushRef.current(), []);
+    return { containerRef: wrapperRef, flush };
 }
 //# sourceMappingURL=useInteractiveHtmlEditor.js.map

package/dist/features/html-editor/source-splice.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An element's position among its ancestors' **element-only** children, ignoring text nodes,
+ * comments, and `style`/`script` elements at every level. `[0, 1]` means "the second element
+ * child of the first element child of the fragment root".
+ */
+export type ElementPath = readonly number[];
+/** One element's source byte range, as located in the original HTML string that was indexed. */
+export interface ElementSourceRange {
+    /** Byte offset of the first character of the element's inner content (just after `startTag`). */
+    readonly start: number;
+    /** Byte offset just past the element's inner content (just before `endTag`, if any). */
+    readonly end: number;
+    /** The element's tag name, so a caller can detect drift between what it expects and what parsed. */
+    readonly tagName: string;
+}
+/** Canonical string key for a path, for use as a `Map` key (`Map<pathKey(path), ...>`). */
+export declare function pathKey(path: ElementPath): string;
+/**
+ * Parses `html` once and indexes every reachable element's inner-content source range by its
+ * element-only child path (see `ElementPath`). The same `html` string must be re-indexed after
+ * any splice — a returned index is only valid against the exact string it was built from, since
+ * every offset is a byte position into that specific string.
+ *
+ * @param html Source HTML to index. Parsed as a fragment (`parse5.parseFragment`), so a leading
+ *   `<html>`/`<body>` wrapper is not assumed and is not specially handled here.
+ * @returns A map from `pathKey(path)` to that element's source range. `style`/`script` elements,
+ *   comments, and text nodes are never present as entries or path slots.
+ * @complexity O(n) in the size of `html` (parse5's own parse cost dominates; indexing itself is
+ *   a single linear tree walk).
+ * @overallScore 100
+ */
+export declare function indexElementSourceRanges(html: string): Map<string, ElementSourceRange>;
+/**
+ * Replaces only the inner-content bytes of the element at `path` with `newInner`, leaving every
+ * other byte of `html` — including whitespace, attribute quoting, and entities — untouched.
+ *
+ * Returns `null`, never a wrong splice, when the address cannot be trusted: `path` does not
+ * resolve to any indexed element (the document's shape changed since the path was computed), or
+ * it resolves to an element whose tag does not match `expectedTagName` (the caller's own model
+ * and the source string have drifted apart). Callers must treat `null` as a signal to fall back
+ * to a full re-serialization — never retry with a guessed range.
+ *
+ * @param html Original source string (not a previously-spliced one — see this module's file
+ *   header on re-splicing from the original on every edit rather than compounding offsets).
+ * @param path Element-only child path of the element to edit, as produced by
+ *   `indexElementSourceRanges`.
+ * @param expectedTagName Tag name the caller believes lives at `path` (e.g. the GrapesJS
+ *   component's own tag). A mismatch is treated the same as an unresolved path.
+ * @param newInner Replacement inner HTML for the addressed element.
+ * @returns The spliced string, or `null` if `path` could not be located or its tag disagreed.
+ * @complexity O(n) — dominated by re-indexing `html` (see `indexElementSourceRanges`); the splice
+ *   itself is two string slices and a concatenation.
+ * @overallScore 100
+ */
+export declare function spliceElementInner(html: string, path: ElementPath, expectedTagName: string, newInner: string): string | null;
+//# sourceMappingURL=source-splice.d.ts.map

package/dist/features/html-editor/source-splice.js

@@ -0,0 +1,89 @@
+import { parseFragment } from 'parse5';
+/** Tags GrapesJS never represents as ordinary tree components — never indexed, never a path slot. */
+const UNINDEXED_TAGS = new Set(['style', 'script']);
+/** Canonical string key for a path, for use as a `Map` key (`Map<pathKey(path), ...>`). */
+export function pathKey(path) {
+    return path.join('.');
+}
+function isElement(node) {
+    return 'tagName' in node;
+}
+function hasChildNodes(node) {
+    return 'childNodes' in node;
+}
+/**
+ * Walks one level of element-only children (recursing into each), assigning each a path and
+ * recording its source range. `style`/`script` children are skipped without consuming a path slot.
+ *
+ * @complexity O(n) over the fragment's total node count — each node is visited exactly once.
+ */
+function indexChildren(children, parentPath, out) {
+    let elementIndex = 0;
+    for (const node of children) {
+        if (!isElement(node))
+            continue;
+        if (UNINDEXED_TAGS.has(node.tagName))
+            continue;
+        const currentPath = [...parentPath, elementIndex];
+        const location = node.sourceCodeLocation;
+        if (location) {
+            // Void elements (`<br>`, `<img>`) have no `endTag` and no inner content: their range is
+            // empty (`start === end`), anchored at the end of the start tag.
+            const start = location.startTag ? location.startTag.endOffset : location.endOffset;
+            const end = location.endTag ? location.endTag.startOffset : start;
+            out.set(pathKey(currentPath), { start, end, tagName: node.tagName });
+        }
+        if (hasChildNodes(node))
+            indexChildren(node.childNodes, currentPath, out);
+        elementIndex++;
+    }
+}
+/**
+ * Parses `html` once and indexes every reachable element's inner-content source range by its
+ * element-only child path (see `ElementPath`). The same `html` string must be re-indexed after
+ * any splice — a returned index is only valid against the exact string it was built from, since
+ * every offset is a byte position into that specific string.
+ *
+ * @param html Source HTML to index. Parsed as a fragment (`parse5.parseFragment`), so a leading
+ *   `<html>`/`<body>` wrapper is not assumed and is not specially handled here.
+ * @returns A map from `pathKey(path)` to that element's source range. `style`/`script` elements,
+ *   comments, and text nodes are never present as entries or path slots.
+ * @complexity O(n) in the size of `html` (parse5's own parse cost dominates; indexing itself is
+ *   a single linear tree walk).
+ * @overallScore 100
+ */
+export function indexElementSourceRanges(html) {
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const index = new Map();
+    indexChildren(fragment.childNodes, [], index);
+    return index;
+}
+/**
+ * Replaces only the inner-content bytes of the element at `path` with `newInner`, leaving every
+ * other byte of `html` — including whitespace, attribute quoting, and entities — untouched.
+ *
+ * Returns `null`, never a wrong splice, when the address cannot be trusted: `path` does not
+ * resolve to any indexed element (the document's shape changed since the path was computed), or
+ * it resolves to an element whose tag does not match `expectedTagName` (the caller's own model
+ * and the source string have drifted apart). Callers must treat `null` as a signal to fall back
+ * to a full re-serialization — never retry with a guessed range.
+ *
+ * @param html Original source string (not a previously-spliced one — see this module's file
+ *   header on re-splicing from the original on every edit rather than compounding offsets).
+ * @param path Element-only child path of the element to edit, as produced by
+ *   `indexElementSourceRanges`.
+ * @param expectedTagName Tag name the caller believes lives at `path` (e.g. the GrapesJS
+ *   component's own tag). A mismatch is treated the same as an unresolved path.
+ * @param newInner Replacement inner HTML for the addressed element.
+ * @returns The spliced string, or `null` if `path` could not be located or its tag disagreed.
+ * @complexity O(n) — dominated by re-indexing `html` (see `indexElementSourceRanges`); the splice
+ *   itself is two string slices and a concatenation.
+ * @overallScore 100
+ */
+export function spliceElementInner(html, path, expectedTagName, newInner) {
+    const range = indexElementSourceRanges(html).get(pathKey(path));
+    if (!range || range.tagName !== expectedTagName)
+        return null;
+    return html.slice(0, range.start) + newInner + html.slice(range.end);
+}
+//# sourceMappingURL=source-splice.js.map

package/dist/features/i18n/dictionaries/settings-dialog.ar.js

@@ -48,6 +48,8 @@ export const SETTINGS_DIALOG_AR = {
     'Copy': 'نسخ',
     'Copy to clipboard': 'نسخ إلى الحافظة',
     'Could not load live models: {message}': 'تعذّر تحميل النماذج المباشرة: {message}',
+    'No API key — connection test needs the key from this browser.': 'لا يوجد مفتاح API — يحتاج اختبار الاتصال إلى المفتاح من هذا المتصفح.',
+    'No API key — model discovery needs the key from this browser.': 'لا يوجد مفتاح API — يحتاج اكتشاف النماذج إلى المفتاح من هذا المتصفح.',
     'Could not load skills: {error}': 'تعذّر تحميل المهارات: {error}',
     'Could not reach the daemon: {error}': 'تعذّر الوصول إلى الخدمة الخلفية: {error}',
     'Could not reach the server. Showing local changes only.': 'تعذّر الوصول إلى الخادم. تُعرض التغييرات المحلية فقط.',
@@ -177,7 +179,9 @@ export const SETTINGS_DIALOG_AR = {
     'Test notification sent.': 'تم إرسال إشعار الاختبار.',
     'Test successful': 'نجح الاختبار',
     'Testing…': 'جارٍ الاختبار…',
+    'This is shorter than any provider API key — check that the whole key was pasted. You can still save and test it.': 'هذا أقصر من أي مفتاح API لأي مزوّد — تحقق من لصق المفتاح كاملاً. لا يزال بإمكانك حفظه واختباره.',
     'This is what a completion notification looks like.': 'هذا شكل إشعار الاكتمال.',
+    'This looks like an API key for {vendor}, not {provider}. You can still save and test it.': 'يبدو هذا مفتاح API خاصًا بـ {vendor}، وليس {provider}. لا يزال بإمكانك حفظه واختباره.',
     'This skill ships with the host. Editing it creates your own copy — the original is unaffected.': 'تأتي هذه المهارة مع المضيف. يؤدي تعديلها إلى إنشاء نسختك الخاصة — لا يتأثر الأصل.',
     'Tool details unavailable ({count})': 'تفاصيل الأداة غير متاحة ({count})',
     'Tools': 'الأدوات',