@jini-ai/ui 0.4.6 → 0.4.8

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

@@ -1,10 +1,12 @@
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import grapesjs, {} from 'grapesjs';
 import { applyCanvasContentWrapper } from '../../canvas-content-wrapper.js';
 import { applyCanvasEmbedPlaceholders } from '../../canvas-embed-placeholders.js';
 import { buildCanvasStyleConfig, CANVAS_STYLES_PENDING_CLASS } from '../../canvas-style.js';
-import { prettifyCss } from '../../css.js';
-import { indexElementSourceRanges, pathKey, spliceElementInner } from '../../source-splice.js';
+import { serializeEditorSource } from '../../editor-serialization.js';
+import { prepareEditorSource } from '../../editor-blocks.js';
+import { assertPreparedSourceModel, assertProtectedSourceMetadata, EditorSourceError, PROTECTED_ELEMENT_TYPE, protectedCanvasDescriber, protectTextAncestors, registerProtectedElementType } from '../../protected-elements.js';
+import { pathKey } 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.
@@ -22,87 +24,52 @@ import { indexElementSourceRanges, pathKey, spliceElementInner } from '../../sou
  * fresh document only mounts this component while it's active and remounts with fresh `html` — see
  * `@jini-ai/admin/react`'s `InteractiveHtmlEditor` adapter and its caller in the host product's `PageEditor.tsx`.
  *
- * **This module has zero knowledge of what "protected" means.** It only knows how to register a
- * locked GrapesJS component type for whatever `isProtectedElement` predicate its caller supplies —
- * see this file's `registerProtectedElementType`. The predicate itself (e.g. recognizing a host's own
- * embed-placeholder convention) belongs to the caller, not this primitive.
+ * **This module has zero knowledge of host embed conventions.** The shared source detector owns
+ * native/runtime blocks; the caller owns its embed predicate and descriptions. Both go through
+ * `../../protected-elements.ts`'s single raw-source type and the existing canvas card renderer.
  *
  * **`canvasStyling.contentWrapper` is applied on `load`, against the live canvas — never folded into
  * `components` above.** See `../../canvas-content-wrapper.ts`'s own file header for why: GrapesJS's
  * exported HTML/CSS are built from its component model, which `components` seeds and this wrapper
  * never touches, so it cannot leak into a save no matter how the canvas is edited afterward.
  */
-const PROTECTED_ELEMENT_TYPE = 'protected-element';
 /** Bold/italic/link only. GrapesJS's other built-in RTE actions (underline, strikethrough, wrap) are
  *  omitted, not merely unconfigured, by naming exactly these three rather than leaving the default
  *  action list in place. */
 const RTE_ACTIONS = ['bold', 'italic', 'link'];
-/**
- * Registers the `protected-element` component type so any parsed element `isProtectedElement`
- * 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
- * is O(1) per element (whatever `isProtectedElement` costs), not owned by this function.
- * @overallScore 100
- */
-function registerProtectedElementType(editor, isProtectedElement) {
-    editor.Components.addType(PROTECTED_ELEMENT_TYPE, {
-        isComponent: (el) => (isProtectedElement(el) ? { type: PROTECTED_ELEMENT_TYPE } : undefined),
-        model: {
-            defaults: {
-                editable: false,
-                droppable: false,
-                stylable: false,
-                layerable: false,
-                badgable: false,
-                selectable: true,
-                hoverable: true,
-                highlightable: true,
-                removable: true,
-                draggable: true,
-                copyable: true,
-            },
-        },
-    });
-}
-function initInteractiveHtmlEditor(container, html, isProtectedElement, canvasStyling) {
+function initInteractiveHtmlEditor(container, sourcePlan, canvasStyling, options) {
     return grapesjs.init({
         container,
         height: '100%',
         fromElement: false,
-        components: html,
+        components: sourcePlan.html,
         storageManager: { type: 'none' },
         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).
+        // Both default to `true`: avoidInlineStyle moves styles into ID rules; forceClass converts
+        // them to .cNNNN rules even with avoidInlineStyle disabled, including on untouched elements.
+        // Keep authored styles inline for structural saves (Bug C in this repo's `pages-redo` plan).
+        // serializeCleaned's JSON CSS export is the other half; the splice path already keeps bytes.
         avoidInlineStyle: false,
-        canvas: buildCanvasStyleConfig(canvasStyling),
-        plugins: isProtectedElement
-            ? [(editor) => registerProtectedElementType(editor, isProtectedElement)]
-            : [],
+        forceClass: false,
+        canvas: buildCanvasStyleConfig({ ...canvasStyling, css: [canvasStyling.css, sourcePlan.canvasCss].filter(Boolean).join('\n') }),
+        // Structural export can only preserve whitespace gaps the parser retained in the model.
+        parser: { optionsHtml: { allowScripts: false, keepEmptyTextNodes: true } },
+        plugins: [(editor) => registerProtectedElementType({ editor, sourcePlan }, {
+                onRequestEditHtml: options.onRequestEditHtml, editHtmlLabel: options.translate?.('Edit HTML'),
+                beforeRequestEditHtml: () => disableActiveTextEditing(editor), onSerializationError: options.onSerializationError,
+            })],
     });
 }
 /** 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. */
+ *  matching how `indexElementSourceRanges` numbers the original string. Raw style/script atoms
+ *  now stay in the tree, but their original source tag still excludes them from path slots; before
+ *  source preservation GrapesJS moved styles into CssComposer and dropped scripts outright. */
 function isPathableComponent(component) {
-    return !component.is('textnode') && !component.is('comment');
+    return !component.is('textnode') && !component.is('comment')
+        && !['style', 'script'].includes(component.get?.('sourceTagName'));
 }
 /**
  * `component`'s element-only child path from the editor's wrapper root, in the exact numbering
@@ -164,94 +131,6 @@ function isInsideTextComponent(component) {
     }
     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
@@ -297,7 +176,7 @@ const STYLESHEET_SETTLE_TIMEOUT_MS = 3000;
  * @complexity O(n) in the number of `<link rel="stylesheet">` elements found — one listener pair per
  *   link, no polling.
  */
-function revealCanvasWhenStylesheetsSettle(editor, body) {
+function revealCanvasWhenStylesheetsSettle(editor, body, onSettled) {
     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
@@ -317,6 +196,8 @@ function revealCanvasWhenStylesheetsSettle(editor, body) {
             link.removeEventListener('error', handleSettle);
         }
         pending.clear();
+        if (links.length > 0)
+            onSettled();
         body.classList.remove(CANVAS_STYLES_PENDING_CLASS);
     };
     function handleSettle(event) {
@@ -335,44 +216,9 @@ function revealCanvasWhenStylesheetsSettle(editor, body) {
         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 `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.
- *
- * **Mounts into a dedicated child node, not the wrapper div `containerRef` itself, and removes that
- * child node (not just its content) on cleanup.** Defensive, for React StrictMode's dev-time
- * double-invoke (mount -> cleanup -> mount again, synchronously): if a destroyed instance's canvas
- * were still mid-render when cleanup ran, clearing the container's *current* content at that moment
- * cannot remove DOM that does not exist yet, and a later async write from the discarded instance
- * would land after the fact. Detaching the whole per-instance node sidesteps that class of ordering
- * problem entirely — whatever a destroyed instance's async work later does, it mutates a node no
- * longer connected to `document`, so it can never become visible or queryable in the live page no
- * matter when it runs. (Investigated live via Playwright while chasing an unrelated symptom — two
- * canvas iframes coexisting after one mount — which turned out to be a separate, harmless GrapesJS
- * quirk unrelated to StrictMode: `Canvas`'s `FramesView` always constructs one `FrameView` that never
- * proceeds past construction to `render()`, alongside the real one; it keeps Backbone's default
- * `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.
- * @overallScore 100
- */
-export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling = {}, describeEmbedPlaceholder) {
+export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling = {}, describeEmbedPlaceholder, options = {}) {
     const wrapperRef = useRef(null);
+    const [sourceError, setSourceError] = useState();
     const onChangeRef = useRef(onChange);
     onChangeRef.current = onChange;
     // Delegated to by the stable `flush` callback returned below. Reset to a no-op on cleanup, before
@@ -382,10 +228,48 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         const wrapper = wrapperRef.current;
         if (!wrapper)
             return;
+        const sourcePlan = prepareEditorSource({ html }, { isProtectedElement, describeHostElement: describeEmbedPlaceholder, translate: options.translate });
+        let integrityFailure;
+        const reportSourceError = (error) => {
+            integrityFailure = error;
+            setSourceError(options.translate?.(error.message) ?? error.message);
+            options.onSerializationError?.(error);
+        };
+        if (!sourcePlan.ok) {
+            reportSourceError(new EditorSourceError({ message: sourcePlan.problem }, {}));
+            return;
+        }
         const mountEl = document.createElement('div');
         mountEl.style.height = '100%';
         wrapper.appendChild(mountEl);
-        const editor = initInteractiveHtmlEditor(mountEl, html, isProtectedElement, canvasStyling);
+        let editor;
+        try {
+            editor = initInteractiveHtmlEditor(mountEl, sourcePlan, canvasStyling, { ...options, onSerializationError: reportSourceError });
+        }
+        catch {
+            reportSourceError(new EditorSourceError());
+            mountEl.remove();
+            return;
+        }
+        const decorate = () => {
+            protectTextAncestors({ editor }, {});
+            const describe = sourcePlan.instances.length ? protectedCanvasDescriber({ editor }, {}) : describeEmbedPlaceholder;
+            if (describe)
+                applyCanvasEmbedPlaceholders(editor.Canvas.getBody(), describe);
+        };
+        const serialize = () => {
+            try {
+                const next = serializeEditorSource({ editor, html, edits: dirty, sourcePlan }, { structuralChange });
+                if (next.includes(sourcePlan.markerAttribute))
+                    throw new EditorSourceError();
+                return next;
+            }
+            catch (error) {
+                const failure = error instanceof EditorSourceError ? error : new EditorSourceError();
+                reportSourceError(failure);
+                throw failure;
+            }
+        };
         // 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.
@@ -398,22 +282,26 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         // 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;
+        let canvasWindow;
         // 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)
+            if (!loaded || cardRepair !== undefined)
                 return;
             cardRepair = setTimeout(() => {
                 cardRepair = undefined;
-                applyCanvasEmbedPlaceholders(editor.Canvas.getBody(), describeEmbedPlaceholder);
+                decorate();
             }, 0);
         };
         const handleUpdate = () => {
             changed = true;
-            onChangeRef.current(serializeWithSplice(editor, html, dirty, structuralChange));
+            try {
+                onChangeRef.current(serialize());
+            }
+            catch { /* Source error is already visible; retain the last intact working copy. */ }
         };
         // `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)` —
@@ -429,7 +317,7 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         // 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)))
+            if (structuralChange || (component && !component.is(PROTECTED_ELEMENT_TYPE) && isInsideTextComponent(component)))
                 return;
             structuralChange = `${event} <${component?.tagName?.toLowerCase() || 'unknown'}>`;
         };
@@ -447,9 +335,19 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         // structural change happened either.
         flushRef.current = async () => {
             await disableActiveTextEditing(editor);
+            if (integrityFailure)
+                throw integrityFailure;
+            try {
+                assertProtectedSourceMetadata({ editor }, {});
+            }
+            catch {
+                const failure = new EditorSourceError();
+                reportSourceError(failure);
+                throw failure;
+            }
             if (!changed && dirty.size === 0 && !structuralChange)
                 return undefined;
-            const next = serializeWithSplice(editor, html, dirty, structuralChange);
+            const next = serialize();
             onChangeRef.current(next);
             return next;
         };
@@ -461,14 +359,26 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
         // Applied AFTER the content wrapper so a placeholder can sit correctly however deep the wrapper
         // chain nests its marker, though nothing about either function actually depends on this order.
         const handleLoad = () => {
+            if (sourcePlan.instances.length) {
+                try {
+                    assertPreparedSourceModel({ editor, sourcePlan }, {});
+                }
+                catch {
+                    reportSourceError(new EditorSourceError());
+                    return;
+                }
+            }
             const body = editor.Canvas.getBody();
             applyCanvasContentWrapper(body, canvasStyling.contentWrapper);
-            if (describeEmbedPlaceholder)
-                applyCanvasEmbedPlaceholders(body, describeEmbedPlaceholder);
+            decorate();
             // 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);
+            cancelStylesheetWait = revealCanvasWhenStylesheetsSettle(editor, body, decorate);
             loaded = true;
+            // An iframe window's native resize event already covers canvas-width changes. Reuse it
+            // instead of maintaining a second ResizeObserver lifecycle for the same view geometry.
+            canvasWindow = editor.Canvas.getDocument()?.defaultView;
+            canvasWindow?.addEventListener('resize', scheduleCardRepair);
         };
         editor.on('load', handleLoad);
         return () => {
@@ -482,6 +392,7 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
             editor.off('component:remove', handleRemove);
             editor.off('load', handleLoad);
             cancelStylesheetWait?.();
+            canvasWindow?.removeEventListener('resize', scheduleCardRepair);
             clearTimeout(cardRepair);
             editor.destroy();
             mountEl.remove();
@@ -491,6 +402,6 @@ export function useInteractiveHtmlEditor(html, onChange, isProtectedElement, can
     // 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 };
+    return { containerRef: wrapperRef, flush, sourceError };
 }
 //# sourceMappingURL=useInteractiveHtmlEditor.js.map

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

@@ -53,4 +53,27 @@ export declare function indexElementSourceRanges(html: string): Map<string, Elem
  * @overallScore 100
  */
 export declare function spliceElementInner(html: string, path: ElementPath, expectedTagName: string, newInner: string): string | null;
+/** Verified offsets are JS string indexes (UTF-16), suitable for slice and textarea selection. */
+export interface ElementOuterRange {
+    readonly outerStart: number;
+    readonly outerEnd: number;
+    readonly openingEnd: number;
+}
+/** Source tree shared by block detection and preparation; raw atoms never consume a splice slot. */
+export interface SourceElement {
+    readonly tagName: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly path: ElementPath | null;
+    readonly outerRange: ElementOuterRange | null;
+    readonly sourceSupported: boolean;
+    readonly children: readonly SourceElement[];
+}
+/**
+ * Extends the inner-splice index without changing its published range shape. Missing end tags,
+ * implicit nodes and reordered/foster-parented children cannot establish an opaque source owner.
+ * Validation is linear in source nodes; ranges are checked against their immediate source parent.
+ */
+export declare function indexSourceElements({ html }: {
+    html: string;
+}, _options?: object): SourceElement[];
 //# sourceMappingURL=source-splice.d.ts.map

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

@@ -86,4 +86,49 @@ export function spliceElementInner(html, path, expectedTagName, newInner) {
         return null;
     return html.slice(0, range.start) + newInner + html.slice(range.end);
 }
+const VOID_TAGS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+/**
+ * Extends the inner-splice index without changing its published range shape. Missing end tags,
+ * implicit nodes and reordered/foster-parented children cannot establish an opaque source owner.
+ * Validation is linear in source nodes; ranges are checked against their immediate source parent.
+ */
+export function indexSourceElements({ html }, _options = {}) {
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const walk = (nodes, parentPath, parentStart, parentEnd) => {
+        let slot = 0;
+        const elements = nodes.filter(isElement).map(node => {
+            const atom = UNINDEXED_TAGS.has(node.tagName);
+            const path = atom ? null : [...parentPath, slot++];
+            const loc = node.sourceCodeLocation;
+            const start = loc?.startTag;
+            const end = loc?.endTag;
+            const voidTag = VOID_TAGS.has(node.tagName) || (node.namespaceURI !== 'http://www.w3.org/1999/xhtml'
+                && !!start && html.slice(start.startOffset, start.endOffset).endsWith('/>'));
+            const outerEnd = voidTag ? start?.endOffset : end?.endOffset;
+            const boundsValid = !!start && outerEnd !== undefined && start.startOffset >= parentStart && outerEnd <= parentEnd;
+            const children = walk(node.childNodes, path ?? parentPath, start?.endOffset ?? parentStart, end?.startOffset ?? parentEnd);
+            // Template content is a separate fragment; it has no ordinary component path/shell here.
+            const valid = boundsValid && node.tagName !== 'template';
+            return {
+                tagName: node.tagName,
+                attributes: Object.fromEntries(node.attrs.map(attr => [attr.name, attr.value])),
+                path,
+                outerRange: valid ? { outerStart: start.startOffset, outerEnd: outerEnd, openingEnd: start.endOffset } : null,
+                sourceSupported: valid && children.every(child => child.sourceSupported),
+                children,
+            };
+        });
+        // Foster parenting can move a valid-looking node ahead of a source-earlier table. Neither
+        // sibling can be trusted as a model-addressable source owner in that recovered ordering.
+        for (let i = 1; i < elements.length; i++) {
+            const previous = elements[i - 1];
+            const current = elements[i];
+            if (previous.outerRange && current.outerRange && previous.outerRange.outerEnd > current.outerRange.outerStart) {
+                previous.sourceSupported = current.sourceSupported = false;
+            }
+        }
+        return elements;
+    };
+    return walk(fragment.childNodes, [], 0, html.length);
+}
 //# sourceMappingURL=source-splice.js.map

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_AR = {
     'About': 'حول',
     'Accent color': 'لون التمييز',
     'Account': 'الحساب',
+    'Advanced': 'متقدّم',
     'Advanced: proxy & custom paths': 'متقدم: الوكيل والمسارات المخصصة',
     'Agent check failed': 'فشل التحقق من الوكيل',
     'Agent is ready.': 'الوكيل جاهز.',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_AR = {
     'Not available for this daemon.': 'غير متاح لهذه الخدمة الخلفية.',
     'Not configured': 'غير مهيّأ',
     'Not installed': 'غير مثبَّت',
+    'Show {count} not installed': 'إظهار {count} غير مثبَّتة',
+    'Hide not installed': 'إخفاء غير المثبَّتة',
+    'Show not-installed CLIs': 'إظهار واجهات CLI غير المثبَّتة',
     'Not sharing': 'لا تتم المشاركة',
     'Nothing is shared unless you opt in.': 'لا تتم مشاركة أي شيء ما لم تفعّل ذلك بنفسك.',
     'Off': 'إيقاف',

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_BN = {
     'About': 'সম্পর্কে',
     'Accent color': 'হাইলাইট রং',
     'Account': 'অ্যাকাউন্ট',
+    'Advanced': 'উন্নত',
     'Advanced: proxy & custom paths': 'উন্নত: প্রক্সি ও কাস্টম পাথ',
     'Agent check failed': 'এজেন্ট পরীক্ষা ব্যর্থ হয়েছে',
     'Agent is ready.': 'এজেন্ট প্রস্তুত।',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_BN = {
     'Not available for this daemon.': 'এই ডিমনের জন্য উপলব্ধ নয়।',
     'Not configured': 'কনফিগার করা হয়নি',
     'Not installed': 'ইনস্টল করা নেই',
+    'Show {count} not installed': '{count}টি ইনস্টল না করা দেখান',
+    'Hide not installed': 'ইনস্টল না করা লুকান',
+    'Show not-installed CLIs': 'ইনস্টল না করা CLI দেখান',
     'Not sharing': 'শেয়ার করা হচ্ছে না',
     'Nothing is shared unless you opt in.': 'আপনি সম্মতি না দেওয়া পর্যন্ত কিছুই শেয়ার করা হয় না।',
     'Off': 'বন্ধ',

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_DE = {
     'About': 'Info',
     'Accent color': 'Akzentfarbe',
     'Account': 'Konto',
+    'Advanced': 'Erweitert',
     'Advanced: proxy & custom paths': 'Erweitert: Proxy und benutzerdefinierte Pfade',
     'Agent check failed': 'Agentenprüfung fehlgeschlagen',
     'Agent is ready.': 'Agent ist bereit.',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_DE = {
     'Not available for this daemon.': 'Für diesen Daemon nicht verfügbar.',
     'Not configured': 'Nicht konfiguriert',
     'Not installed': 'Nicht installiert',
+    'Show {count} not installed': '{count} nicht installierte anzeigen',
+    'Hide not installed': 'Nicht installierte ausblenden',
+    'Show not-installed CLIs': 'Nicht installierte CLIs anzeigen',
     'Not sharing': 'Wird nicht geteilt',
     'Nothing is shared unless you opt in.': 'Es wird nichts geteilt, außer du stimmst ausdrücklich zu.',
     'Off': 'Aus',

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_EN = {
     'About': 'About',
     'Accent color': 'Accent color',
     'Account': 'Account',
+    'Advanced': 'Advanced',
     'Advanced: proxy & custom paths': 'Advanced: proxy & custom paths',
     'Agent check failed': 'Agent check failed',
     'Agent is ready.': 'Agent is ready.',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_EN = {
     'Not available for this daemon.': 'Not available for this daemon.',
     'Not configured': 'Not configured',
     'Not installed': 'Not installed',
+    'Show {count} not installed': 'Show {count} not installed',
+    'Hide not installed': 'Hide not installed',
+    'Show not-installed CLIs': 'Show not-installed CLIs',
     'Not sharing': 'Not sharing',
     'Nothing is shared unless you opt in.': 'Nothing is shared unless you opt in.',
     'Off': 'Off',

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_ES = {
     'About': 'Acerca de',
     'Accent color': 'Color de acento',
     'Account': 'Cuenta',
+    'Advanced': 'Avanzado',
     'Advanced: proxy & custom paths': 'Avanzado: proxy y rutas personalizadas',
     'Agent check failed': 'Falló la comprobación del agente',
     'Agent is ready.': 'El agente está listo.',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_ES = {
     'Not available for this daemon.': 'No disponible para este daemon.',
     'Not configured': 'No configurado',
     'Not installed': 'No instalado',
+    'Show {count} not installed': 'Mostrar {count} no instalados',
+    'Hide not installed': 'Ocultar no instalados',
+    'Show not-installed CLIs': 'Mostrar CLIs no instalados',
     'Not sharing': 'No se comparte',
     'Nothing is shared unless you opt in.': 'No se comparte nada a menos que lo actives.',
     'Off': 'Desactivado',

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

@@ -7,6 +7,7 @@ export const SETTINGS_DIALOG_FA = {
     'About': 'درباره',
     'Accent color': 'رنگ تأکیدی',
     'Account': 'حساب کاربری',
+    'Advanced': 'پیشرفته',
     'Advanced: proxy & custom paths': 'پیشرفته: پراکسی و مسیرهای سفارشی',
     'Agent check failed': 'بررسی عامل ناموفق بود',
     'Agent is ready.': 'عامل آماده است.',
@@ -131,6 +132,9 @@ export const SETTINGS_DIALOG_FA = {
     'Not available for this daemon.': 'برای این دیمون در دسترس نیست.',
     'Not configured': 'پیکربندی‌نشده',
     'Not installed': 'نصب‌نشده',
+    'Show {count} not installed': 'نمایش {count} مورد نصب‌نشده',
+    'Hide not installed': 'پنهان کردن موارد نصب‌نشده',
+    'Show not-installed CLIs': 'نمایش CLIهای نصب‌نشده',
     'Not sharing': 'اشتراک‌گذاری نمی‌شود',
     'Nothing is shared unless you opt in.': 'تا زمانی که خودتان فعال نکنید، چیزی به اشتراک گذاشته نمی‌شود.',
     'Off': 'خاموش',