@jini-ai/ui 0.4.7 → 0.4.8

package/dist/features/html-editor/editor-blocks.js

@@ -0,0 +1,185 @@
+import { sourceElementAttributeView } from './dom.js';
+import { indexSourceElements } from './source-splice.js';
+const LABELS = {
+    kuinetic: 'Animation · Kuinetic', canvas: 'Canvas', 'autoplay-video': 'Autoplay video',
+    scripted: 'Scripted section', embed: 'Content',
+};
+const INLINE_TAGS = new Set(['span', 'a', 'b', 'i', 'em', 'strong', 'small', 'mark', 's', 'u', 'sub', 'sup']);
+const UNSUPPORTED_CONTEXTS = new Set(['table', 'thead', 'tbody', 'tfoot', 'tr', 'td', 'th', 'select', 'option', 'svg', 'math', 'template']);
+// A Kuinetic entrance/decoration effect (fade-up, text-reveal, split-chars, count-up…)
+// only animates authored text the canvas never runs, so locking it hid Landing's headline, ledes and
+// buttons behind grey cards. Such elements stay editable; their data-kui attribute round-trips like
+// any other, including stagger lists and decorated containers. Layout/runtime effects (ring, pin…)
+// stay locked; unknown names retain the structural rule, and data-editor="block" still forces a lock.
+// Names follow Kuinetic's core entrance, text, numbers, media and interaction catalogs; the bare
+// fade/reveal/text-reveal/glow spellings are also part of the editor's authored-effect contract.
+const EDITABLE_EFFECTS = new Set([
+    'fade', 'fade-in', 'fade-up', 'fade-down', 'fade-left', 'fade-right', 'fade-blur-in', 'fade-blur-up',
+    'slide-up', 'slide-down', 'slide-left', 'slide-right', 'slide-inline-start', 'slide-inline-end', 'slide-block-start', 'slide-block-end',
+    'zoom-in', 'zoom-in-up', 'zoom-in-down', 'pop-in', 'flip-in-x', 'flip-in-y', 'rotate-in', 'rotate-in-left', 'rotate-in-right',
+    'roll-in', 'swing-in', 'blur-in', 'bounce-in', 'bounce-in-up', 'bounce-in-down', 'back-in-up', 'back-in-down', 'reveal', 'reveal-once',
+    'text-reveal', 'text-reveal-up', 'text-reveal-down', 'text-reveal-mask', 'split-chars', 'split-words', 'split-lines',
+    'count-up', 'count-down', 'count-currency', 'count-percent', 'count-compact', 'odometer-roll',
+    'wipe-up', 'wipe-down', 'wipe-left', 'wipe-right', 'wipe-circle', 'wipe-diagonal', 'mask-reveal', 'curtain-reveal', 'blur-up',
+    'magnetic', 'glow', 'glow-pulse', 'border-glow', 'border-draw', 'beam-border', 'beam-border-auto', 'proximity-glow',
+    'shine-sweep', 'lift', 'lift-shadow', 'pop', 'underline-slide', 'underline-center', 'icon-wiggle', 'icon-spin', 'icon-bounce',
+]);
+const RUNTIME_EFFECTS = new Set([
+    'ring', 'carousel', 'deck', 'slides', 'pin', 'pin-section', 'pin-until', 'pin-spacer', 'marquee', 'marquee-scroll-linked', 'accordion', 'tabs',
+    'carousel-3d', 'carousel-3d-high', 'carousel-3d-low', 'carousel-3d-inside', 'carousel-orbit', 'carousel-stack',
+    'carousel-fade', 'carousel-slide', 'slideshow', 'video-hero-slideshow', 'step-progress', 'stacking-cards', 'horizontal-scroll',
+    'flip-reorder', 'flip-filter', 'flip-sort', 'flip-shuffle', 'grid-to-list', 'masonry-reflow', 'expand-to-modal', 'accordion-height',
+    'card-flip-x', 'card-flip-y', 'flip-card', 'scroll-snap-x', 'scroll-snap-y',
+]);
+const TEXT_EFFECT_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'li', 'dt', 'dd', 'blockquote', 'figcaption', 'label']);
+const PHRASING_TAGS = new Set([...INLINE_TAGS, 'abbr', 'br', 'cite', 'code', 'data', 'dfn', 'img', 'kbd', 'q', 'samp', 'time', 'var', 'wbr']);
+const isPhrasingOnly = (el) => el.children.every(child => PHRASING_TAGS.has(child.tagName) && isPhrasingOnly(child));
+const isEditableEffect = (el) => {
+    if (el.attributes['data-editor'] === 'block')
+        return false;
+    // Quoted selectors and timing/color functions may contain commas, which are not effect separators.
+    const effects = (el.attributes['data-kui'] ?? '').replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\([^)]*\)/g, '')
+        .split(',').map(segment => segment.trim().split(/\s+/)[0]).filter(Boolean);
+    if (effects.some(effect => RUNTIME_EFFECTS.has(effect)))
+        return false;
+    if (effects.length > 0 && effects.every(effect => EDITABLE_EFFECTS.has(effect)))
+        return true;
+    if (el.attributes['data-kui'] === undefined && 'data-kui-stagger' in el.attributes)
+        return true;
+    return (TEXT_EFFECT_TAGS.has(el.tagName) || PHRASING_TAGS.has(el.tagName)) && isPhrasingOnly(el);
+};
+/** Outermost disjoint roots; explicit live islands veto aggregation but never host embed safety. */
+export function detectEditorBlocks({ html }, options = {}) {
+    const elements = indexSourceElements({ html }, {});
+    const blocks = [];
+    const liveIslands = new Map();
+    const annotate = (el) => {
+        const descendants = el.children.map(annotate).some(Boolean);
+        liveIslands.set(el, descendants);
+        return el.attributes['data-editor'] === 'live' || descendants;
+    };
+    elements.forEach(annotate);
+    let unsupported = false;
+    const walk = (el, live, invalidAncestor) => {
+        const mode = el.attributes['data-editor'];
+        const isLive = mode === 'live' || (mode !== 'block' && live);
+        const view = sourceElementAttributeView(el, {});
+        const host = options.describeHostElement?.(view);
+        const embed = !!host || !!options.isProtectedElement?.(view);
+        let reason;
+        if (!isLive) {
+            if (Object.keys(el.attributes).some(name => name.startsWith('data-kui')) && !isEditableEffect(el))
+                reason = 'kuinetic';
+            else if (el.tagName === 'canvas')
+                reason = 'canvas';
+            else if (el.tagName === 'video' && 'autoplay' in el.attributes)
+                reason = 'autoplay-video';
+            else if (mode === 'block')
+                reason = 'scripted';
+        }
+        if (reason && liveIslands.get(el))
+            reason = undefined;
+        if (!reason && embed)
+            reason = 'embed';
+        const invalid = invalidAncestor || !el.outerRange || UNSUPPORTED_CONTEXTS.has(el.tagName);
+        if (reason) {
+            if (invalid || !el.sourceSupported) {
+                unsupported = true;
+                return;
+            }
+            const t = options.translate ?? ((key) => key);
+            const id = el.attributes.id;
+            const identity = id ? `#${id}` : el.attributes.class ? `.${el.attributes.class.trim().split(/\s+/).slice(0, 2).join('.')}` : el.tagName;
+            blocks.push({
+                ...el.outerRange, tagName: el.tagName, ...(id ? { id } : {}), reason, element: el,
+                descriptor: reason === 'embed' && host ? host : {
+                    kindLabel: t(LABELS[reason]), identityLabel: identity.slice(0, 64), presentation: reason === 'embed' ? 'embed' : 'runtime',
+                    guidanceLabel: t('Locked · Edit in HTML · Preview plays it'), inline: INLINE_TAGS.has(el.tagName),
+                },
+            });
+            return;
+        }
+        el.children.forEach(child => walk(child, isLive, invalid));
+    };
+    elements.forEach(el => walk(el, false, false));
+    return unsupported || (blocks.length > 0 && elements.some(el => !el.sourceSupported))
+        ? { ok: false, problem: "Can't edit this source visually. Use HTML." } : { ok: true, blocks, elements };
+}
+const escapeAttribute = (value) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+/**
+ * Capture before GrapesJS parses. Only a mount-private lookup token reaches the parser; authored
+ * source stays in model metadata. Style/script atoms use inert spans, never executable source tags.
+ */
+export function prepareEditorSource({ html }, options = {}) {
+    const detected = detectEditorBlocks({ html }, options);
+    if (!detected.ok)
+        return { ...detected, html };
+    const instances = detected.blocks.map(block => ({
+        ...block, originalHtml: html.slice(block.outerStart, block.outerEnd),
+        openingTag: html.slice(block.outerStart, block.openingEnd), nonvisual: false,
+    }));
+    const blocked = new Set(detected.blocks.map(block => block.element));
+    const css = [];
+    let unsupported = false;
+    const walk = (el, enclosed, invalidAncestor) => {
+        const inside = enclosed || blocked.has(el);
+        const invalid = invalidAncestor || !el.outerRange;
+        if (el.tagName === 'style' && el.outerRange) {
+            const original = html.slice(el.outerRange.outerStart, el.outerRange.outerEnd);
+            const closingLength = original.length - (original.toLowerCase().lastIndexOf('</style'));
+            css.push(html.slice(el.outerRange.openingEnd, el.outerRange.outerEnd - closingLength));
+        }
+        if (!inside && (el.tagName === 'style' || el.tagName === 'script')) {
+            if (invalid)
+                unsupported = true;
+            else
+                instances.push({ ...el.outerRange, originalHtml: html.slice(el.outerRange.outerStart, el.outerRange.outerEnd),
+                    openingTag: html.slice(el.outerRange.outerStart, el.outerRange.openingEnd), tagName: el.tagName, nonvisual: true });
+        }
+        el.children.forEach(child => walk(child, inside, invalid));
+    };
+    detected.elements.forEach(el => walk(el, false, false));
+    if (unsupported || (instances.length > 0 && detected.elements.some(el => !el.sourceSupported))) {
+        return { ok: false, html, problem: "Can't edit this source visually. Use HTML." };
+    }
+    instances.sort((a, b) => a.outerStart - b.outerStart);
+    let markerAttribute = 'data-jini-raw-source-0';
+    let namespace = 0;
+    while (html.toLowerCase().includes(markerAttribute))
+        markerAttribute = `data-jini-raw-source-${++namespace}`;
+    let prepared = html;
+    const roots = new Map(detected.blocks.map(block => [block.outerStart, block]));
+    for (let i = instances.length - 1; i >= 0; i--) {
+        const instance = instances[i];
+        const block = roots.get(instance.outerStart);
+        const attrs = block?.element.attributes ?? {};
+        // Data selectors may declare the root's geometry. They are inert without page scripts; keep
+        // them alongside box attributes, while resource URLs, event handlers, autoplay and GrapesJS
+        // parser directives stay absent. Authored data-gjs flags must not override the protected type.
+        const layout = Object.keys(attrs).filter(name => ['id', 'class', 'style', 'height', 'width'].includes(name)
+            || (name.startsWith('data-') && !name.startsWith('data-gjs-')))
+            .map(name => ` ${name}="${escapeAttribute(attrs[name])}"`).join('');
+        const tag = instance.nonvisual ? 'span' : instance.tagName;
+        const voidTag = instance.openingEnd === instance.outerEnd;
+        const shell = `<${tag} ${markerAttribute}="${i}"${layout}>${voidTag && !instance.nonvisual ? '' : `</${tag}>`}`;
+        prepared = prepared.slice(0, instance.outerStart) + shell + prepared.slice(instance.outerEnd);
+    }
+    return { ok: true, html: prepared, markerAttribute, instances, canvasCss: css.join('\n') };
+}
+/** Exact authored opening tag and its source offsets; no regex-based HTML parsing or id guessing. */
+export function findEditorBlockOpening({ html, target }, _options = {}) {
+    let occurrence = 0;
+    let result;
+    const walk = (el) => {
+        if (el.tagName === target.tagName.toLowerCase() && (target.id === undefined || el.attributes.id === target.id)) {
+            if (occurrence++ === target.occurrenceIndex && el.outerRange) {
+                const { outerStart: start, openingEnd: end } = el.outerRange;
+                result = { start, end, openingTag: html.slice(start, end) };
+            }
+        }
+        el.children.forEach(walk);
+    };
+    indexSourceElements({ html }, {}).forEach(walk);
+    return result;
+}
+//# sourceMappingURL=editor-blocks.js.map

package/dist/features/html-editor/editor-serialization.d.ts

@@ -0,0 +1,24 @@
+import type { Component, Editor } from 'grapesjs';
+import { type ElementPath } from './source-splice.js';
+import type { PreparedEditorSource } from './editor-blocks.js';
+/** One accumulated text edit, keyed by `pathKey(path)` in the caller's `dirty` map: the element-only
+ *  path and tag name `spliceElementInner` needs to locate and verify the target, plus the edited
+ *  component itself. Its inner HTML is read at serialize time, not recorded here: GrapesJS fires
+ *  `rte:disable` BEFORE `syncContent` writes the edited text into the model, so a snapshot taken at
+ *  that event is the OLD text. See `serializeWithSplice`'s own doc for why the map accumulates across
+ *  the whole mount rather than resetting per edit. */
+export interface DirtyTextEdit {
+    readonly path: ElementPath;
+    readonly tagName: string;
+    readonly component: Component;
+}
+/** Existing text-splice/full-export owner, also usable without a rendered canvas in contract tests. */
+export declare function serializeEditorSource({ editor, html, edits, sourcePlan }: {
+    editor: Editor;
+    html: string;
+    edits: Map<string, DirtyTextEdit>;
+    sourcePlan: PreparedEditorSource;
+}, { structuralChange }?: {
+    structuralChange?: string | undefined;
+}): string;
+//# sourceMappingURL=editor-serialization.d.ts.map

package/dist/features/html-editor/editor-serialization.js

@@ -0,0 +1,110 @@
+import { prettifyCss } from './css.js';
+import { indexElementSourceRanges, pathKey, spliceElementInner } from './source-splice.js';
+import { assertProtectedSourceMetadata, EditorSourceError } from './protected-elements.js';
+/** 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. `avoidInlineStyle: false` and
+ * `forceClass: false` keep authored styles inline; `keepEmptyTextNodes: true` keeps whitespace gaps
+ * in the model (see `initInteractiveHtmlEditor`). JSON CSS export returns composed rule models,
+ * excluding the synthetic `#iXXXX` rules string export derives from those inline styles. Native
+ * `rule.toCSS()` retains composed rules' at-rule wrappers. 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.
+ * @complexity O(h + c) time and space for exported HTML h and composed CSS c.
+ */
+function serializeCleaned(editor) {
+    // GrapesJS's getCss typing omits its JSON return type; successful init supplies a wrapper.
+    const rules = editor.getCss({ json: true, avoidProtected: true, keepUnusedStyles: true });
+    const css = rules.map(rule => rule.toCSS()).join('');
+    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, sourcePlan) {
+    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 range = originalIndex.get(pathKey(edit.path));
+        if (range && sourcePlan?.instances.some(raw => range.start < raw.outerEnd && range.end > raw.outerStart)) {
+            warnFallback('text edit overlaps a protected source region');
+            return serializeCleaned(editor);
+        }
+        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;
+}
+/** Existing text-splice/full-export owner, also usable without a rendered canvas in contract tests. */
+export function serializeEditorSource({ editor, html, edits, sourcePlan }, { structuralChange } = {}) {
+    assertProtectedSourceMetadata({ editor }, {});
+    const result = serializeWithSplice(editor, html, edits, structuralChange, sourcePlan);
+    if (result.includes(sourcePlan.markerAttribute))
+        throw new EditorSourceError();
+    return result;
+}
+//# sourceMappingURL=editor-serialization.js.map

package/dist/features/html-editor/index.d.ts

@@ -5,4 +5,9 @@ export type { CanvasContentWrapperNode, CanvasStyling } from './canvas-style.js'
 export type { CanvasEmbedPlaceholderDescriptor } from './canvas-embed-placeholders.js';
 export { hasAttributeOnAnyNodeShape } from './dom.js';
 export { prettifyCss } from './css.js';
+export { detectEditorBlocks, prepareEditorSource, findEditorBlockOpening } from './editor-blocks.js';
+export type { EditorHtmlTarget, RequestEditHtml, EditorSourcePlan, PreparedEditorSource } from './editor-blocks.js';
+export { EditorSourceError, isEditorSourceError, registerProtectedElementType, protectTextAncestors } from './protected-elements.js';
+export { serializeEditorSource } from './editor-serialization.js';
+export type { DirtyTextEdit } from './editor-serialization.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/features/html-editor/index.js

@@ -2,4 +2,7 @@ export { InteractiveHtmlEditor } from './react/components/InteractiveHtmlEditor.
 export { useInteractiveHtmlEditor } from './react/hooks/useInteractiveHtmlEditor.js';
 export { hasAttributeOnAnyNodeShape } from './dom.js';
 export { prettifyCss } from './css.js';
+export { detectEditorBlocks, prepareEditorSource, findEditorBlockOpening } from './editor-blocks.js';
+export { EditorSourceError, isEditorSourceError, registerProtectedElementType, protectTextAncestors } from './protected-elements.js';
+export { serializeEditorSource } from './editor-serialization.js';
 //# sourceMappingURL=index.js.map

package/dist/features/html-editor/protected-elements.d.ts

@@ -0,0 +1,64 @@
+import type { Component, Editor } from 'grapesjs';
+import type { CanvasEmbedPlaceholderDescriptor } from './canvas-embed-placeholders.js';
+import { type PreparedEditorSource, type RequestEditHtml } from './editor-blocks.js';
+export declare const PROTECTED_ELEMENT_TYPE = "protected-element";
+/** Distinguishable from an ordinary best-effort RTE timeout: never persist a damaged raw shell. */
+export declare class EditorSourceError extends Error {
+    readonly code = "EDITOR_SOURCE_INTEGRITY";
+    constructor({ message }?: {
+        message?: string;
+    }, _options?: object);
+}
+export declare function isEditorSourceError({ error }: {
+    error: unknown;
+}, _options?: object): boolean;
+/** Source lives only on the component model, so clone and undo carry it with ordinary model state. */
+export declare function protectedElementHtml({ component }: {
+    component: Pick<Component, 'get'>;
+}, _options?: object): string;
+/** Check surviving instances before any export or no-op flush; deletion itself is allowed. */
+export declare function assertProtectedSourceMetadata({ editor }: {
+    editor: Editor;
+}, _options?: object): void;
+/** Verify initial parser ownership before the first visual edit; recovered/lost shells fail closed. */
+export declare function assertPreparedSourceModel({ editor, sourcePlan }: {
+    editor: Editor;
+    sourcePlan: PreparedEditorSource;
+}, _options?: object): void;
+/** Text ancestors must not sync canvas-only card chrome back into a model during RTE close. */
+export declare function protectTextAncestors({ editor }: {
+    editor: Editor;
+}, _options?: object): void;
+/** Same canvas card path, addressed through model metadata rather than authored/public selectors. */
+export declare function protectedCanvasDescriber({ editor }: {
+    editor: Editor;
+}, _options?: object): (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined;
+/**
+ * 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
+ */
+/**
+ * One protected type for runtime roots, host embeds and nonvisual atoms. Registration precedes
+ * parsing; isComponent resolves mount-private tokens to metadata and supplies empty children.
+ */
+export declare function registerProtectedElementType({ editor, sourcePlan }: {
+    editor: Editor;
+    sourcePlan: PreparedEditorSource;
+}, options?: {
+    onRequestEditHtml?: RequestEditHtml | undefined;
+    editHtmlLabel?: string | undefined;
+    beforeRequestEditHtml?: () => Promise<void>;
+    onSerializationError?: ((error: EditorSourceError) => void) | undefined;
+}): void;
+//# sourceMappingURL=protected-elements.d.ts.map

package/dist/features/html-editor/protected-elements.js

@@ -0,0 +1,189 @@
+import { findEditorBlockOpening } from './editor-blocks.js';
+export const PROTECTED_ELEMENT_TYPE = 'protected-element';
+/** Distinguishable from an ordinary best-effort RTE timeout: never persist a damaged raw shell. */
+export class EditorSourceError extends Error {
+    code = 'EDITOR_SOURCE_INTEGRITY';
+    constructor({ message = "Can't edit this source visually. Use HTML." } = {}, _options = {}) { super(message); this.name = 'EditorSourceError'; }
+}
+export function isEditorSourceError({ error }, _options = {}) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === 'EDITOR_SOURCE_INTEGRITY';
+}
+/** Source lives only on the component model, so clone and undo carry it with ordinary model state. */
+export function protectedElementHtml({ component }, _options = {}) {
+    const original = component.get('originalHtml');
+    if (typeof original !== 'string' || original.length === 0)
+        throw new EditorSourceError();
+    return original;
+}
+function visit(component, callback) {
+    callback(component);
+    component.components().models.forEach(child => visit(child, callback));
+}
+/** Check surviving instances before any export or no-op flush; deletion itself is allowed. */
+export function assertProtectedSourceMetadata({ editor }, _options = {}) {
+    const wrapper = editor.getWrapper();
+    if (wrapper)
+        visit(wrapper, component => {
+            if (component.is(PROTECTED_ELEMENT_TYPE))
+                protectedElementHtml({ component }, {});
+        });
+}
+/** Verify initial parser ownership before the first visual edit; recovered/lost shells fail closed. */
+export function assertPreparedSourceModel({ editor, sourcePlan }, _options = {}) {
+    const actual = [];
+    const wrapper = editor.getWrapper();
+    if (!wrapper)
+        throw new EditorSourceError();
+    visit(wrapper, component => {
+        if (component.is(PROTECTED_ELEMENT_TYPE))
+            actual.push(protectedElementHtml({ component }, {}));
+    });
+    if (actual.length !== sourcePlan.instances.length || actual.some((html, i) => html !== sourcePlan.instances[i].originalHtml)) {
+        throw new EditorSourceError();
+    }
+}
+/** Text ancestors must not sync canvas-only card chrome back into a model during RTE close. */
+export function protectTextAncestors({ editor }, _options = {}) {
+    const wrapper = editor.getWrapper();
+    if (!wrapper)
+        return;
+    visit(wrapper, component => {
+        if (!component.is(PROTECTED_ELEMENT_TYPE))
+            return;
+        for (let parent = component.parent(); parent; parent = parent.parent()) {
+            if (parent.is('text'))
+                parent.set('editable', false, { silent: true });
+        }
+    });
+}
+/** Same canvas card path, addressed through model metadata rather than authored/public selectors. */
+export function protectedCanvasDescriber({ editor }, _options = {}) {
+    const descriptors = new Map();
+    const wrapper = editor.getWrapper();
+    if (wrapper)
+        visit(wrapper, component => {
+            if (!component.is(PROTECTED_ELEMENT_TYPE) || component.get('sourceNonvisual'))
+                return;
+            const el = component.getEl();
+            const descriptor = component.get('placeholderDescriptor');
+            if (el && descriptor)
+                descriptors.set(el, descriptor);
+        });
+    return el => descriptors.get(el);
+}
+/**
+ * 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
+ */
+/**
+ * One protected type for runtime roots, host embeds and nonvisual atoms. Registration precedes
+ * parsing; isComponent resolves mount-private tokens to metadata and supplies empty children.
+ */
+export function registerProtectedElementType({ editor, sourcePlan }, options = {}) {
+    const command = 'jini:protected-edit-html';
+    const requestEditHtml = options.onRequestEditHtml;
+    if (requestEditHtml)
+        editor.Commands.add(command, {
+            async run() {
+                try {
+                    await options.beforeRequestEditHtml?.();
+                    const selected = editor.getSelected();
+                    const wrapper = editor.getWrapper();
+                    if (!selected?.is(PROTECTED_ELEMENT_TYPE) || !wrapper || selected.get('sourceNonvisual'))
+                        return;
+                    const original = protectedElementHtml({ component: selected }, {});
+                    const html = wrapper.getInnerHTML();
+                    // Search only exact authored slices. Copies share bytes, so count preceding equal instances
+                    // in model order; no mapping export mode or persistent source tokens are needed.
+                    let copiesBefore = 0;
+                    let reached = false;
+                    visit(wrapper, component => {
+                        if (component === selected)
+                            reached = true;
+                        else if (!reached && component.is(PROTECTED_ELEMENT_TYPE) && protectedElementHtml({ component }, {}) === original)
+                            copiesBefore++;
+                    });
+                    let start = -1;
+                    for (let i = 0; i <= copiesBefore; i++)
+                        start = html.indexOf(original, start + 1);
+                    if (start < 0)
+                        throw new EditorSourceError();
+                    const tagName = selected.get('sourceTagName');
+                    const id = selected.get('sourceId');
+                    let occurrenceIndex = 0;
+                    for (;;) {
+                        const range = findEditorBlockOpening({ html, target: { occurrenceIndex, tagName, ...(id ? { id } : {}) } }, {});
+                        if (!range || range.start > start)
+                            throw new EditorSourceError();
+                        if (range.start === start)
+                            break;
+                        occurrenceIndex++;
+                    }
+                    await requestEditHtml({ occurrenceIndex, tagName, ...(id ? { id } : {}) }, {});
+                }
+                catch (error) {
+                    options.onSerializationError?.(error instanceof EditorSourceError ? error : new EditorSourceError());
+                }
+            },
+        });
+    editor.Components.addType(PROTECTED_ELEMENT_TYPE, {
+        isComponent(el) {
+            const token = typeof el.getAttribute === 'function' ? el.getAttribute(sourcePlan.markerAttribute)
+                : el.attributes?.[sourcePlan.markerAttribute];
+            if (token === null || token === undefined)
+                return undefined;
+            const instance = sourcePlan.instances[Number(token)];
+            if (!instance || String(Number(token)) !== token)
+                throw new EditorSourceError();
+            return {
+                type: PROTECTED_ELEMENT_TYPE, originalHtml: instance.originalHtml, sourceTagName: instance.tagName,
+                sourceId: instance.id, sourceNonvisual: instance.nonvisual, placeholderDescriptor: instance.descriptor,
+                components: [], content: '',
+            };
+        },
+        model: {
+            defaults: {
+                editable: false, droppable: false, stylable: false, resizable: false, traits: [],
+                layerable: false, badgable: false, selectable: true, hoverable: true, highlightable: true,
+                removable: true, draggable: true, copyable: true,
+            },
+            init() {
+                // Keep default move/copy/delete toolbar commands, then append the host navigation action.
+                if (!this.get('sourceNonvisual') && options.onRequestEditHtml) {
+                    const toolbar = (this.get('toolbar') ?? []);
+                    this.set('toolbar', [...toolbar.filter(item => item.command !== command), {
+                            label: options.editHtmlLabel ?? 'Edit HTML', command,
+                            // GrapesJS sizes every toolbar item as a 26px icon square; a text label overflowed past the
+                            // toolbar (and the canvas edge on full-width blocks), so this item sizes to its label.
+                            attributes: {
+                                title: options.editHtmlLabel ?? 'Edit HTML', 'aria-label': options.editHtmlLabel ?? 'Edit HTML',
+                                style: 'width:auto;white-space:nowrap;padding:5px 8px',
+                            },
+                        }], { silent: true });
+                }
+                if (this.get('sourceNonvisual'))
+                    this.set({ selectable: false, draggable: false, hoverable: false, copyable: false }, { silent: true });
+            },
+            toHTML() { return protectedElementHtml({ component: this }, {}); },
+        },
+        view: {
+            onRender() {
+                this.el.setAttribute('contenteditable', 'false');
+                if (this.model.get('sourceNonvisual'))
+                    this.el.style.setProperty('display', 'none', 'important');
+            },
+        },
+    });
+}
+//# sourceMappingURL=protected-elements.js.map

package/dist/features/html-editor/react/components/InteractiveHtmlEditor.d.ts

@@ -1,6 +1,7 @@
 import 'grapesjs/dist/css/grapes.min.css';
 import type { CanvasEmbedPlaceholderDescriptor } from '../../canvas-embed-placeholders.js';
 import type { CanvasStyling } from '../../canvas-style.js';
+import { type InteractiveEditorOptions } from '../hooks/useInteractiveHtmlEditor.js';
 /**
  * @file A visual, click-into-text editing surface for a bespoke HTML document, built on GrapesJS
  * (MIT). Renders `html` like a live preview but lets the operator click into rendered text and edit
@@ -32,7 +33,8 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * is an optional predicate the caller supplies to turn specific elements (identified however the
  * caller likes) into atomic blocks: their content can never be edited, dropped into or styled, but a
  * click selects the element itself (never the block around it), and it can be deliberately moved,
- * copied or deleted. When omitted, no elements are protected.
+ * copied or deleted. Runtime/native and author-opted blocks are always protected; the predicate
+ * adds host-owned embed recognition.
  * `describeEmbedPlaceholder` is the same idea for a second, independent concern: recognizing an
  * unresolved embed marker and labeling it for `../../canvas-embed-placeholders.ts`'s explicit
  * placeholder card. See `@jini-ai/admin/react`'s `InteractiveHtmlEditor` for a worked example of both:
@@ -66,7 +68,7 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * guaranteed by WHEN it is applied (against the live canvas, after GrapesJS has already parsed
  * `html`), not by a strip-on-export step.
  */
-export interface InteractiveHtmlEditorProps {
+export interface InteractiveHtmlEditorProps extends InteractiveEditorOptions {
     /** The document to load into the editor. Read once, at mount — see this file's header and
      *  `react/hooks/useInteractiveHtmlEditor.ts` for why. */
     html: string;
@@ -79,7 +81,7 @@ export interface InteractiveHtmlEditorProps {
     /** Identifies elements whose content must never be edited or dropped into inside the editor. Each
      *  one is selectable as a single block that can be deliberately moved, copied or deleted. Read once, at mount, same as `html`. Predicates that check attributes should use
      *  `hasAttributeOnAnyNodeShape` (exported alongside this component) rather than `el.hasAttribute`
-     *  directly — see that helper's own doc for why. Omit to protect nothing. */
+     *  directly — see that helper's own doc for why. Omit for runtime/native blocks only. */
     isProtectedElement?: (el: Element) => boolean;
     /** CSS to render the edited document against inside the editing canvas, so the operator sees
      *  roughly what the document publishes as rather than browser defaults. Read once, at mount, same
@@ -90,7 +92,7 @@ export interface InteractiveHtmlEditorProps {
      *  fallback content it authored) — see `../../canvas-embed-placeholders.ts`'s own file header for
      *  the export-safety argument. Read once, at mount, same as `isProtectedElement`. Returning
      *  `undefined` for an element means "not a marker this host owns" — left completely untouched.
-     *  Omit to decorate nothing, the pre-existing behavior. This component has the same zero knowledge
+     *  Omit for runtime/native cards only. This component has the same zero knowledge
      *  of any host's marker convention that `isProtectedElement` documents above. */
     describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined;
 }