@avocadostudio-ai/preview-adapter 0.3.2 → 0.4.0

package/dist/bridge-functions.d.ts

@@ -16,7 +16,106 @@ export declare function markdownToHtml(md: string): string;
  */
 export declare function withPreviewParams(href: string, currentSearch: string): string;
 export declare function findBlockNode(blockId: string): HTMLElement | null;
+/**
+ * True while a scroll this module started is still running or being corrected.
+ *
+ * The editor treats an `iframeScrolled` report as the reader taking over —
+ * it drops the field anchor and stops following a running chat stream — so our
+ * own scrolling must not be reported. One flag for every scroll we initiate,
+ * rather than a marker at each call site, because the one call site that had no
+ * marker (block focus, which is what "Go to" uses) is exactly the one that
+ * scrolls in response to a click somewhere else.
+ */
+export declare function isProgrammaticScroll(): boolean;
+/**
+ * Bring a block on screen and *keep* it there while the page settles.
+ *
+ * One `scrollIntoView` cannot do this. It resolves its destination from the
+ * layout at the instant it is called, and the preview is hardly ever settled at
+ * that instant — selection chrome is mounting, hero images are swapping in,
+ * blocks above the target are still changing height. Measured against the demo
+ * site, the target moved 478–1152px between the call and the end of the
+ * animation, every time, which left it *entirely above the viewport*: "Go to"
+ * appeared to jump to a random section, and the block the panel was now editing
+ * was nowhere on screen.
+ *
+ * So: scroll, then watch. Correct whenever the block has drifted out of the
+ * band we aimed for, and stop as soon as it holds still. Corrections wait for
+ * the previous scroll to finish (a stable `scrollY`) so we never interrupt the
+ * smooth animation we started, and they use `auto` — a second smooth animation
+ * queued behind the first reads as a lurch.
+ *
+ * A reader who starts scrolling wins immediately. Being 300px off is a smaller
+ * insult than dragging the page back out from under someone's hand.
+ */
+export declare function scrollBlockIntoView(el: HTMLElement, options?: {
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+}): void;
 export declare function findEditableNode(parent: HTMLElement, editablePath: string): HTMLElement | null;
+/**
+ * The node to point at for a field, which is not always the field's own node.
+ *
+ * Plenty of editable props are never rendered as an element. Alt text is an
+ * attribute on an image; a link target is an attribute on an anchor. A renderer
+ * emits `data-editable-target` for what it *draws*, so `cards[0].imageAlt` and
+ * `cards[0].ctaHref` match nothing at all, and asking to show somebody where
+ * the problem is has so far shown them nothing.
+ *
+ * Three steps, most specific first:
+ *   1. the field's own node, when it has one
+ *   2. for alt text, the image it describes — the only thing on the page that
+ *      alt text *is* about, and the inverse of the `toAltPath` convention the
+ *      renderers already follow
+ *   3. the nearest enclosing node: the card, the list item, the block. Less
+ *      precise, and still the difference between "that one" and nothing.
+ */
+export declare function resolveEditableNode(parent: HTMLElement, editablePath: string): HTMLElement | null;
+/**
+ * Does this marked node draw an image?
+ *
+ * Ask the node first. `data-editable-kind`, which `editableProps` emits from
+ * whatever the site's own block manifest says, is a statement by the only party
+ * that knows. `isImagePath` is a guess from the prop's *name* against Avocado's
+ * naming for its own catalogue — `imageUrl`, `*.src` — and it is right about
+ * Avocado's blocks for the circular reason that Avocado named them. A site
+ * calling the field `photoUrl` or `heroSrc` gets an image picker in the
+ * property panel, which reads the manifest, and no button in the preview, which
+ * does not; nothing anywhere reports a disagreement.
+ *
+ * The guess stays as the fallback: every built-in renderer, and every
+ * integration written before the attribute existed, emits a path and no kind.
+ */
+export declare function isImageEditable(node: HTMLElement, editablePath: string): boolean;
+/**
+ * May this marked node be typed into?
+ *
+ * The other half of `inlineEditable: false`, which until now existed only in the
+ * property panel: the manifest could say a string is not something anybody edits
+ * on the page, and the preview had no way to hear it. Marking such a field was
+ * therefore all-or-nothing — mark it and accept that a double-click starts a
+ * text edit, or leave it unmarked and lose the hover pill, the field selection
+ * and, when it holds a picture, the Change button.
+ *
+ * The field this was written for is the built-in blocks' `icon`: an emoji, a
+ * symbol, or the URL of a small image. Everything else renders as nothing at
+ * all, so typing the word the planner reaches for — "rocket" — into a marked
+ * emoji makes the icon disappear, with the value stored and invisible.
+ *
+ * The attribute is read from the marked element, so a site declares it once
+ * where it declares the target.
+ */
+export declare function isInlineEditable(node: HTMLElement): boolean;
+/**
+ * Should Enter insert a newline rather than committing the edit?
+ *
+ * `body` is grandfathered: it is the name Avocado's own long-text fields use,
+ * and it was the entire rule before `data-editable-multiline` existed — the same
+ * shape of mistake as guessing an image from `imageUrl`, and a site whose prose
+ * field is called `intro` or `beschreibung` got a single-line editor for a
+ * paragraph. A node that states its own answer is believed either way.
+ */
+export declare function isMultilineEditable(node: HTMLElement, editablePath: string): boolean;
 /**
  * True when React rendered this editable field as block-level element children
  * (parsed markdown), not a plain text node.
@@ -61,6 +160,61 @@ export declare function setNestedLabelsVisibility(visible: boolean): void;
 export declare function clearChildFocus(): void;
 export declare function showSkeleton(afterBlockId: string | null, blockType: string): void;
 export declare function removeSkeletons(): void;
+/**
+ * The one misintegration the overlay can diagnose for itself.
+ *
+ * Selection is entirely `[data-block-id]`: a click resolves through
+ * `closest("[data-block-id]")`, and a null result is read as "clicked outside
+ * any block", which *clears* the selection. A site that added
+ * `data-editable-target` to its components but no block wrappers therefore
+ * frames, renders, styles and scrolls correctly, and silently deselects on
+ * every click — and the README has already trained the reader to expect a
+ * preview that ignores clicks, because that is what selection mode being off
+ * looks like.
+ *
+ * Editable targets with no wrapper around them is unambiguous: nobody adds the
+ * per-field attributes by accident. Say so once, loudly, in development.
+ */
+export declare function missingBlockWrapperWarning(blockCount: number, editableCount: number): string | null;
+/**
+ * The other half of a half-finished integration — and the likelier half.
+ *
+ * `missingBlockWrapperWarning` names the case where the fields are marked and
+ * the blocks are not. This names its mirror, which is what following the
+ * integration guide to its end and stopping one step early actually produces:
+ * every block wrapped, no field marked. Wrapping blocks is a single call in the
+ * preview route; marking fields means touching the site's own components, so it
+ * is the step that gets deferred and then forgotten.
+ *
+ * What it costs is invisible rather than broken. Selection works. Highlighting,
+ * scroll-to-block, the badges, the property panel and every edit made through
+ * it all work, because the panel is built from the block manifest and never
+ * looks at the page. What is silently off is everything the overlay finds by
+ * walking the DOM: inline text editing, the field pills on hover, the image
+ * Change/Remove buttons, and the live-draft path that streams a field into the
+ * node that draws it. A reviewer sees a preview that responds to clicks and
+ * concludes it is wired.
+ *
+ * Like its mirror this is an all-or-nothing test, not a coverage check: one
+ * marked field means the integrator knows the attribute exists, and which of
+ * their fields deserve it is their call, not ours.
+ */
+export declare function missingEditableTargetsWarning(blockCount: number, editableCount: number): string | null;
+/** Every integration problem the overlay can diagnose from the page alone. */
+export declare function previewIntegrationWarnings(blockCount: number, editableCount: number): string[];
+/**
+ * Put the diagnosis where the person is looking.
+ *
+ * Both warnings above describe a preview that looks like it works, so the
+ * console they would print to is the one nobody opens — and in the editor it is
+ * the *iframe's* console, two context menus away from the window in front of
+ * the user. The symptom is "the button is missing from the preview"; the
+ * explanation has to be in the preview.
+ *
+ * Development only, and dismissible: it sits over the site's own design, and
+ * once read it has done its work.
+ */
+export declare function showIntegrationWarnings(messages: string[]): void;
 export declare function ensureBlockBadges(): void;
 export declare function clearListItemSelection(scope?: ParentNode): void;
 export declare function removeOverlayControls(deleteConfirmTimer: {

package/dist/bridge-functions.js

@@ -6,7 +6,7 @@
  * communicate back to the editor through injectable callbacks, decoupled from any
  * specific transport (postMessage vs direct).
  */
-import { isImagePath, parseInline, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel } from "@avocadostudio-ai/shared";
+import { isAltPath, isImagePath, toImagePath, parseInline, parseRichTextBlocks, normalizeRichTextBody, resolveRichTextHeadingLevel } from "@avocadostudio-ai/shared";
 // ---------------------------------------------------------------------------
 // Markdown → HTML for the live-draft overlay
 // ---------------------------------------------------------------------------
@@ -141,6 +141,108 @@ export function findBlockNode(blockId) {
     }
     return document.querySelector(`[data-block-id='${blockId}']`);
 }
+/** How long we keep correcting a scroll after asking for it. */
+const SCROLL_SETTLE_BUDGET_MS = 1500;
+let programmaticScrollUntil = 0;
+/**
+ * True while a scroll this module started is still running or being corrected.
+ *
+ * The editor treats an `iframeScrolled` report as the reader taking over —
+ * it drops the field anchor and stops following a running chat stream — so our
+ * own scrolling must not be reported. One flag for every scroll we initiate,
+ * rather than a marker at each call site, because the one call site that had no
+ * marker (block focus, which is what "Go to" uses) is exactly the one that
+ * scrolls in response to a click somewhere else.
+ */
+export function isProgrammaticScroll() {
+    return Date.now() < programmaticScrollUntil;
+}
+/** Close enough to centred that another correction would only read as a twitch. */
+const SCROLL_SETTLE_TOLERANCE_PX = 32;
+/** Between samples: long enough that a smooth animation shows movement. */
+const SCROLL_SETTLE_INTERVAL_MS = 120;
+/**
+ * Bring a block on screen and *keep* it there while the page settles.
+ *
+ * One `scrollIntoView` cannot do this. It resolves its destination from the
+ * layout at the instant it is called, and the preview is hardly ever settled at
+ * that instant — selection chrome is mounting, hero images are swapping in,
+ * blocks above the target are still changing height. Measured against the demo
+ * site, the target moved 478–1152px between the call and the end of the
+ * animation, every time, which left it *entirely above the viewport*: "Go to"
+ * appeared to jump to a random section, and the block the panel was now editing
+ * was nowhere on screen.
+ *
+ * So: scroll, then watch. Correct whenever the block has drifted out of the
+ * band we aimed for, and stop as soon as it holds still. Corrections wait for
+ * the previous scroll to finish (a stable `scrollY`) so we never interrupt the
+ * smooth animation we started, and they use `auto` — a second smooth animation
+ * queued behind the first reads as a lurch.
+ *
+ * A reader who starts scrolling wins immediately. Being 300px off is a smaller
+ * insult than dragging the page back out from under someone's hand.
+ */
+export function scrollBlockIntoView(el, options) {
+    const block = options?.block ?? "center";
+    /** Where `block` wants the element's top edge, in viewport coordinates. */
+    const desiredTop = () => {
+        const height = Math.min(el.getBoundingClientRect().height, window.innerHeight);
+        if (block === "start")
+            return 0;
+        if (block === "end")
+            return Math.max(0, window.innerHeight - height);
+        return Math.max(0, Math.round((window.innerHeight - height) / 2));
+    };
+    /** `nearest` asks only that the block be on screen, so that is all we check. */
+    const offTarget = () => {
+        const rect = el.getBoundingClientRect();
+        if (block === "nearest")
+            return rect.bottom <= 0 || rect.top >= window.innerHeight;
+        return Math.abs(rect.top - desiredTop()) > SCROLL_SETTLE_TOLERANCE_PX;
+    };
+    const deadline = Date.now() + SCROLL_SETTLE_BUDGET_MS;
+    // A little past the last correction we could make, so the scroll it settles
+    // into is not reported to the editor as the reader's own.
+    programmaticScrollUntil = deadline + SCROLL_SETTLE_INTERVAL_MS * 3;
+    el.scrollIntoView({ behavior: options?.behavior ?? "smooth", block, inline: "nearest" });
+    let lastY = window.scrollY;
+    let timer = 0;
+    const stop = () => {
+        window.clearInterval(timer);
+        window.removeEventListener("wheel", handOver);
+        window.removeEventListener("touchstart", handOver);
+        window.removeEventListener("keydown", handOver);
+    };
+    // The reader took the wheel. Give the scroll position back to them at once,
+    // including the right to have their scrolling reported as theirs.
+    const handOver = () => {
+        programmaticScrollUntil = 0;
+        stop();
+    };
+    window.addEventListener("wheel", handOver, { passive: true });
+    window.addEventListener("touchstart", handOver, { passive: true });
+    window.addEventListener("keydown", handOver);
+    timer = window.setInterval(() => {
+        if (Date.now() > deadline || !el.isConnected)
+            return stop();
+        const y = window.scrollY;
+        const wasMoving = y !== lastY;
+        lastY = y;
+        // Still animating — let it land before judging where it landed.
+        if (wasMoving)
+            return;
+        if (!offTarget())
+            return stop();
+        el.scrollIntoView({ behavior: "auto", block, inline: "nearest" });
+        // No movement means the document cannot get any closer — a block near the
+        // end of the page can never be centred, and retrying would only burn the
+        // budget re-deciding that.
+        if (window.scrollY === y)
+            stop();
+        else
+            lastY = window.scrollY;
+    }, SCROLL_SETTLE_INTERVAL_MS);
+}
 export function findEditableNode(parent, editablePath) {
     const nodes = parent.querySelectorAll("[data-editable-target]");
     for (const node of nodes) {
@@ -149,6 +251,101 @@ export function findEditableNode(parent, editablePath) {
     }
     return null;
 }
+/** Drop the last `.segment` of a path: `cards[0].ctaHref` → `cards[0]`. */
+function parentPath(editablePath) {
+    const cut = editablePath.lastIndexOf(".");
+    return cut > 0 ? editablePath.slice(0, cut) : null;
+}
+/**
+ * The node to point at for a field, which is not always the field's own node.
+ *
+ * Plenty of editable props are never rendered as an element. Alt text is an
+ * attribute on an image; a link target is an attribute on an anchor. A renderer
+ * emits `data-editable-target` for what it *draws*, so `cards[0].imageAlt` and
+ * `cards[0].ctaHref` match nothing at all, and asking to show somebody where
+ * the problem is has so far shown them nothing.
+ *
+ * Three steps, most specific first:
+ *   1. the field's own node, when it has one
+ *   2. for alt text, the image it describes — the only thing on the page that
+ *      alt text *is* about, and the inverse of the `toAltPath` convention the
+ *      renderers already follow
+ *   3. the nearest enclosing node: the card, the list item, the block. Less
+ *      precise, and still the difference between "that one" and nothing.
+ */
+export function resolveEditableNode(parent, editablePath) {
+    const exact = findEditableNode(parent, editablePath);
+    if (exact)
+        return exact;
+    if (isAltPath(editablePath)) {
+        const image = findEditableNode(parent, toImagePath(editablePath));
+        if (image)
+            return image;
+    }
+    for (let path = parentPath(editablePath); path; path = parentPath(path)) {
+        const node = findEditableNode(parent, path);
+        if (node)
+            return node;
+    }
+    return null;
+}
+/**
+ * Does this marked node draw an image?
+ *
+ * Ask the node first. `data-editable-kind`, which `editableProps` emits from
+ * whatever the site's own block manifest says, is a statement by the only party
+ * that knows. `isImagePath` is a guess from the prop's *name* against Avocado's
+ * naming for its own catalogue — `imageUrl`, `*.src` — and it is right about
+ * Avocado's blocks for the circular reason that Avocado named them. A site
+ * calling the field `photoUrl` or `heroSrc` gets an image picker in the
+ * property panel, which reads the manifest, and no button in the preview, which
+ * does not; nothing anywhere reports a disagreement.
+ *
+ * The guess stays as the fallback: every built-in renderer, and every
+ * integration written before the attribute existed, emits a path and no kind.
+ */
+export function isImageEditable(node, editablePath) {
+    const declared = node.getAttribute("data-editable-kind");
+    if (declared)
+        return declared === "image";
+    return isImagePath(editablePath);
+}
+/**
+ * May this marked node be typed into?
+ *
+ * The other half of `inlineEditable: false`, which until now existed only in the
+ * property panel: the manifest could say a string is not something anybody edits
+ * on the page, and the preview had no way to hear it. Marking such a field was
+ * therefore all-or-nothing — mark it and accept that a double-click starts a
+ * text edit, or leave it unmarked and lose the hover pill, the field selection
+ * and, when it holds a picture, the Change button.
+ *
+ * The field this was written for is the built-in blocks' `icon`: an emoji, a
+ * symbol, or the URL of a small image. Everything else renders as nothing at
+ * all, so typing the word the planner reaches for — "rocket" — into a marked
+ * emoji makes the icon disappear, with the value stored and invisible.
+ *
+ * The attribute is read from the marked element, so a site declares it once
+ * where it declares the target.
+ */
+export function isInlineEditable(node) {
+    return node.getAttribute("data-editable-inline") !== "false";
+}
+/**
+ * Should Enter insert a newline rather than committing the edit?
+ *
+ * `body` is grandfathered: it is the name Avocado's own long-text fields use,
+ * and it was the entire rule before `data-editable-multiline` existed — the same
+ * shape of mistake as guessing an image from `imageUrl`, and a site whose prose
+ * field is called `intro` or `beschreibung` got a single-line editor for a
+ * paragraph. A node that states its own answer is believed either way.
+ */
+export function isMultilineEditable(node, editablePath) {
+    const declared = node.getAttribute("data-editable-multiline");
+    if (declared)
+        return declared !== "false";
+    return editablePath === "body";
+}
 // Block-level tags that signal a field React rendered as parsed-markdown element
 // children (e.g. RichText `body`, Tabs `content`) rather than a single text node.
 const RICH_EDITABLE_SELECTOR = "p,ul,ol,li,blockquote,pre,table,h1,h2,h3,h4,h5,h6,hr";
@@ -334,6 +531,113 @@ export function showSkeleton(afterBlockId, blockType) {
 export function removeSkeletons() {
     document.querySelectorAll(".editor-skeleton-block").forEach((node) => node.remove());
 }
+/**
+ * The one misintegration the overlay can diagnose for itself.
+ *
+ * Selection is entirely `[data-block-id]`: a click resolves through
+ * `closest("[data-block-id]")`, and a null result is read as "clicked outside
+ * any block", which *clears* the selection. A site that added
+ * `data-editable-target` to its components but no block wrappers therefore
+ * frames, renders, styles and scrolls correctly, and silently deselects on
+ * every click — and the README has already trained the reader to expect a
+ * preview that ignores clicks, because that is what selection mode being off
+ * looks like.
+ *
+ * Editable targets with no wrapper around them is unambiguous: nobody adds the
+ * per-field attributes by accident. Say so once, loudly, in development.
+ */
+export function missingBlockWrapperWarning(blockCount, editableCount) {
+    if (blockCount > 0 || editableCount === 0)
+        return null;
+    return (`[avocado] The overlay found ${editableCount} data-editable-target attribute(s) and no ` +
+        "[data-block-id] wrapper. Nothing on this page can be selected: every click resolves to " +
+        "no block and clears the selection, whether or not selection mode is on.\n" +
+        "Wrap each block with getPreviewWrapperProps(editorMode, block.id, block.type) from " +
+        "@avocadostudio-ai/site-sdk/editor — it sets data-block-id, data-block-type and the " +
+        "editor-selectable class that the field pills are scoped to.");
+}
+/**
+ * The other half of a half-finished integration — and the likelier half.
+ *
+ * `missingBlockWrapperWarning` names the case where the fields are marked and
+ * the blocks are not. This names its mirror, which is what following the
+ * integration guide to its end and stopping one step early actually produces:
+ * every block wrapped, no field marked. Wrapping blocks is a single call in the
+ * preview route; marking fields means touching the site's own components, so it
+ * is the step that gets deferred and then forgotten.
+ *
+ * What it costs is invisible rather than broken. Selection works. Highlighting,
+ * scroll-to-block, the badges, the property panel and every edit made through
+ * it all work, because the panel is built from the block manifest and never
+ * looks at the page. What is silently off is everything the overlay finds by
+ * walking the DOM: inline text editing, the field pills on hover, the image
+ * Change/Remove buttons, and the live-draft path that streams a field into the
+ * node that draws it. A reviewer sees a preview that responds to clicks and
+ * concludes it is wired.
+ *
+ * Like its mirror this is an all-or-nothing test, not a coverage check: one
+ * marked field means the integrator knows the attribute exists, and which of
+ * their fields deserve it is their call, not ours.
+ */
+export function missingEditableTargetsWarning(blockCount, editableCount) {
+    if (editableCount > 0 || blockCount === 0)
+        return null;
+    return (`[avocado] The overlay found ${blockCount} [data-block-id] wrapper(s) and no ` +
+        "data-editable-target attribute. Selection and the property panel work; inline text " +
+        "editing, the field pills and the image Change/Remove buttons are all off, because every " +
+        "one of them is found by walking the marked fields in the page.\n" +
+        "Mark the element that draws each editable prop with editableProps(path, { kind }) from " +
+        "@avocadostudio-ai/site-sdk/editor — e.g. editableProps(\"imageUrl\", { kind: \"image\" }) " +
+        "on the wrapper around an image, editableProps(\"heading\") on the element holding it.");
+}
+/** Every integration problem the overlay can diagnose from the page alone. */
+export function previewIntegrationWarnings(blockCount, editableCount) {
+    return [
+        missingBlockWrapperWarning(blockCount, editableCount),
+        missingEditableTargetsWarning(blockCount, editableCount),
+    ].filter((w) => w !== null);
+}
+/**
+ * Put the diagnosis where the person is looking.
+ *
+ * Both warnings above describe a preview that looks like it works, so the
+ * console they would print to is the one nobody opens — and in the editor it is
+ * the *iframe's* console, two context menus away from the window in front of
+ * the user. The symptom is "the button is missing from the preview"; the
+ * explanation has to be in the preview.
+ *
+ * Development only, and dismissible: it sits over the site's own design, and
+ * once read it has done its work.
+ */
+export function showIntegrationWarnings(messages) {
+    document.querySelector(".editor-integration-warning")?.remove();
+    if (messages.length === 0)
+        return;
+    const banner = document.createElement("div");
+    banner.className = "editor-integration-warning";
+    banner.setAttribute("role", "alert");
+    for (const message of messages) {
+        const [headline, ...rest] = message.replace(/^\[avocado] /, "").split("\n");
+        const item = document.createElement("div");
+        item.className = "editor-integration-warning__item";
+        const title = document.createElement("strong");
+        title.textContent = headline ?? "";
+        item.append(title);
+        for (const line of rest) {
+            const p = document.createElement("p");
+            p.textContent = line;
+            item.append(p);
+        }
+        banner.append(item);
+    }
+    const dismiss = document.createElement("button");
+    dismiss.type = "button";
+    dismiss.className = "editor-integration-warning__dismiss";
+    dismiss.textContent = "Dismiss";
+    dismiss.addEventListener("click", () => banner.remove());
+    banner.append(dismiss);
+    document.body.append(banner);
+}
 export function ensureBlockBadges() {
     document.querySelectorAll("[data-block-id]").forEach((node) => {
         const blockType = node.getAttribute("data-block-type") ?? "Block";
@@ -440,7 +744,9 @@ export function applyAiFieldLoading(blockId, editablePath, active) {
     }
 }
 export function cleanupOverlayElements() {
-    document.querySelectorAll(".aifx-shimmer-overlay, .aifx-shimmer-sparkle, .editor-image-change-btn").forEach((el) => el.remove());
+    document
+        .querySelectorAll(".aifx-shimmer-overlay, .aifx-shimmer-sparkle, .editor-image-change-btn, .editor-integration-warning")
+        .forEach((el) => el.remove());
     document.documentElement.removeAttribute("data-editor-active");
     document.documentElement.removeAttribute("data-editor-selection-mode");
 }
@@ -541,11 +847,11 @@ export function createBridgeFunctions(state, callbacks, config) {
             }
         }
         for (const [path, value] of Object.entries(fields)) {
-            if (isImagePath(path))
-                continue;
             const node = findEditableNode(block, path);
             if (!node)
                 continue;
+            if (isImageEditable(node, path))
+                continue;
             // Rich fields (RichText body, Tabs content, etc.) render as block-level
             // React children. Writing innerHTML here desyncs React's vdom and the
             // final router.refresh() then mis-reconciles the subtree (truncated text
@@ -710,7 +1016,7 @@ export function createBridgeFunctions(state, callbacks, config) {
         const parent = findBlockNode(parentBlockId);
         if (!parent)
             return;
-        const child = findEditableNode(parent, editablePath);
+        const child = resolveEditableNode(parent, editablePath);
         if (!child)
             return;
         child.classList.add("editor-child-highlight");
@@ -740,6 +1046,8 @@ export function createBridgeFunctions(state, callbacks, config) {
     const startInlineEdit = (args) => {
         if (!supportsInlineEditablePath(args.editablePath))
             return;
+        if (!isInlineEditable(args.node))
+            return;
         if (args.node.children.length > 0)
             return;
         const existing = state.inlineEditing;
@@ -754,7 +1062,7 @@ export function createBridgeFunctions(state, callbacks, config) {
             blockType: args.blockType,
             editablePath: args.editablePath,
             initialValue,
-            isMultiline: args.editablePath === "body"
+            isMultiline: isMultilineEditable(args.node, args.editablePath)
         };
         args.node.setAttribute("contenteditable", "true");
         args.node.classList.add("editor-inline-editing");
@@ -1043,7 +1351,7 @@ export function createBridgeFunctions(state, callbacks, config) {
         }
         document.querySelectorAll(".editor-selectable [data-editable-target]").forEach((el) => {
             const path = el.getAttribute("data-editable-target") ?? "";
-            if (!isImagePath(path))
+            if (!isImageEditable(el, path))
                 return;
             const block = el.closest("[data-block-id]");
             if (!block)
@@ -1103,7 +1411,7 @@ export function createBridgeFunctions(state, callbacks, config) {
                 state.pendingScrollAnchorY = null;
             }
             else {
-                match.scrollIntoView({ behavior: "smooth", block: "center" });
+                scrollBlockIntoView(match);
             }
         }
         if (shouldAnimate) {
@@ -1473,7 +1781,7 @@ export function createBridgeFunctions(state, callbacks, config) {
         }
         applyBlockFocus(blockId, false, editablePath, { scrollIntoView: false });
         let editableValue = null;
-        if (editablePath && isImagePath(editablePath) && childNode) {
+        if (editablePath && childNode && isImageEditable(childNode, editablePath)) {
             const img = childNode.querySelector("img");
             if (img?.src)
                 editableValue = img.src;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { PreviewBridge } from "./preview-bridge.tsx";
 export { PreviewBridgeCore } from "./preview-bridge-core.tsx";
 export type { PreviewBridgeConfig, PreviewBridgeCoreProps } from "./preview-bridge-core.tsx";
 export { getPreviewWrapperProps } from "./selectable.ts";
-export { createBridgeFunctions, createBridgeState, findBlockNode, findEditableNode, parseListItemPath, supportsInlineEditablePath, readNodeText, placeCaretAtEnd, orderedBlockNodes, blockOrderIndex, computeMoveAfter, computeInsertBefore, groupListItemNodes, commonItemRoot, markdownToHtml, withPreviewParams, setNestedLabelsVisibility, clearChildFocus, clearListItemSelection, removeOverlayControls, clearAllHighlights, showSkeleton, removeSkeletons, ensureBlockBadges, applyAiFieldLoading, cleanupOverlayElements, } from "./bridge-functions.ts";
+export { createBridgeFunctions, createBridgeState, findBlockNode, findEditableNode, scrollBlockIntoView, parseListItemPath, supportsInlineEditablePath, readNodeText, placeCaretAtEnd, orderedBlockNodes, blockOrderIndex, computeMoveAfter, computeInsertBefore, groupListItemNodes, commonItemRoot, markdownToHtml, withPreviewParams, setNestedLabelsVisibility, clearChildFocus, clearListItemSelection, removeOverlayControls, clearAllHighlights, showSkeleton, removeSkeletons, ensureBlockBadges, applyAiFieldLoading, cleanupOverlayElements, isImageEditable, isInlineEditable, isMultilineEditable, missingBlockWrapperWarning, missingEditableTargetsWarning, previewIntegrationWarnings, } from "./bridge-functions.ts";
 export type { BridgeCallbacks, BridgeState, BridgeFunctions } from "./bridge-functions.ts";
 export { LivePreviewProvider, useLivePreviewBlocks, useLivePreviewBridgeApi, } from "./live-preview-store.tsx";
 export type { LivePreviewPage, LivePreviewBridgeApi } from "./live-preview-store.tsx";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { PreviewBridge } from "./preview-bridge.js";
 export { PreviewBridgeCore } from "./preview-bridge-core.js";
 export { getPreviewWrapperProps } from "./selectable.js";
-export { createBridgeFunctions, createBridgeState, findBlockNode, findEditableNode, parseListItemPath, supportsInlineEditablePath, readNodeText, placeCaretAtEnd, orderedBlockNodes, blockOrderIndex, computeMoveAfter, computeInsertBefore, groupListItemNodes, commonItemRoot, markdownToHtml, withPreviewParams, setNestedLabelsVisibility, clearChildFocus, clearListItemSelection, removeOverlayControls, clearAllHighlights, showSkeleton, removeSkeletons, ensureBlockBadges, applyAiFieldLoading, cleanupOverlayElements, } from "./bridge-functions.js";
+export { createBridgeFunctions, createBridgeState, findBlockNode, findEditableNode, scrollBlockIntoView, parseListItemPath, supportsInlineEditablePath, readNodeText, placeCaretAtEnd, orderedBlockNodes, blockOrderIndex, computeMoveAfter, computeInsertBefore, groupListItemNodes, commonItemRoot, markdownToHtml, withPreviewParams, setNestedLabelsVisibility, clearChildFocus, clearListItemSelection, removeOverlayControls, clearAllHighlights, showSkeleton, removeSkeletons, ensureBlockBadges, applyAiFieldLoading, cleanupOverlayElements, isImageEditable, isInlineEditable, isMultilineEditable, missingBlockWrapperWarning, missingEditableTargetsWarning, previewIntegrationWarnings, } from "./bridge-functions.js";
 export { LivePreviewProvider, useLivePreviewBlocks, useLivePreviewBridgeApi, } from "./live-preview-store.js";

package/dist/preview-bridge-core.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
-import { createBridgeFunctions, createBridgeState, findBlockNode, parseListItemPath, ensureBlockBadges, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
+import { createBridgeFunctions, createBridgeState, findBlockNode, isProgrammaticScroll, parseListItemPath, ensureBlockBadges, previewIntegrationWarnings, showIntegrationWarnings, scrollBlockIntoView, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
 export function PreviewBridgeCore(props) {
     // When running standalone (no editor origin) or not embedded in an iframe, render nothing.
     if (!props.editorOrigin || typeof window !== "undefined" && window.parent === window)
@@ -10,7 +10,6 @@ export function PreviewBridgeCore(props) {
 }
 function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathname, liveStore }) {
     const stateRef = useRef(null);
-    const programmaticScrollUntilRef = useRef(0);
     useEffect(() => {
         // -- postMessage helpers ------------------------------------------------
         const postToEditor = (type, payload) => {
@@ -50,6 +49,21 @@ function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathnam
         clearListItemSelection();
         ensureBlockBadges();
         bridge.mountGlobalImageButtons();
+        /*
+         * Deferred a frame so a page still streaming in is not accused of having no
+         * blocks. Development only: in production the site owner cannot act on it
+         * and the visitor should never see it.
+         */
+        if (process.env.NODE_ENV !== "production") {
+            requestAnimationFrame(() => {
+                const warnings = previewIntegrationWarnings(document.querySelectorAll("[data-block-id]").length, document.querySelectorAll("[data-editable-target]").length);
+                for (const warning of warnings)
+                    console.error(warning);
+                // Both of these describe a preview that *looks* correct, so the iframe's
+                // console is the last place they would be found. Say it in the frame.
+                showIntegrationWarnings(warnings);
+            });
+        }
         // -- Mutation observer -------------------------------------------------
         let detectNewBlocksRaf = null;
         const scheduleDetectNewBlocks = () => {
@@ -255,10 +269,7 @@ function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathnam
                     const el = findBlockNode(blockId);
                     if (!el)
                         return false;
-                    // Mark that the next scroll event is programmatic so we don't
-                    // interpret our own scroll as a user cancel.
-                    programmaticScrollUntilRef.current = Date.now() + 800;
-                    el.scrollIntoView({ behavior, block, inline: "nearest" });
+                    scrollBlockIntoView(el, { behavior, block });
                     return true;
                 };
                 // The block may not yet be in the DOM if the iframe just re-rendered;
@@ -271,7 +282,7 @@ function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathnam
         // -- Scroll handler ----------------------------------------------------
         const onScroll = () => {
             // Swallow the scroll event if it originated from our own scrollIntoView.
-            if (Date.now() < programmaticScrollUntilRef.current)
+            if (isProgrammaticScroll())
                 return;
             callbacks.onScroll();
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/preview-adapter",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,7 +32,7 @@
     "src/styles.css"
   ],
   "dependencies": {
-    "@avocadostudio-ai/shared": "^0.3.2"
+    "@avocadostudio-ai/shared": "^0.4.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/styles.css

@@ -1152,6 +1152,27 @@
   box-shadow: 0 2px 6px rgba(15, 23, 42, 0.18);
 }
 
+/*
+ * Hovering the *block* reveals its image buttons, not hovering the image.
+ *
+ * An image is very often not the top thing over its own area, and both ways it
+ * happens are ordinary design, not mistakes. A full-bleed photo behind a
+ * headline has the copy column painted over it; a card that is one big click
+ * target has a stretched `::after` over the whole card, photo included. In
+ * both, the marked element never receives `:hover`, so the button it holds
+ * never became visible — the image simply had no Change button, which is
+ * exactly how this reads as a bug in the button.
+ *
+ * `:hover` propagates to ancestors, and whatever covers the image is inside
+ * the same block wrapper, so the wrapper is hovered in every one of these
+ * cases. On a grid this reveals each card's button at once, which is the
+ * better behaviour anyway: hover a block, see what it lets you change.
+ *
+ * Clicking then works without further help. The button carries z-index 24 and
+ * its marked element sets no z-index of its own, so it competes — and wins —
+ * in the block's own stacking context against the copy that covers it.
+ */
+[data-editor-active] .editor-selectable:hover .editor-image-change-btn,
 [data-editor-active] [data-editable-target]:hover > .editor-image-change-btn,
 [data-editor-active] [data-editable-target]:focus-within > .editor-image-change-btn {
   opacity: 1;
@@ -1205,3 +1226,61 @@
     animation: none !important;
   }
 }
+
+/* ---------------------------------------------------------------------------
+   Integration diagnostics
+
+   Development only, injected by the bridge. Both warnings it can raise describe
+   a preview that renders and responds to clicks and is missing half of what the
+   overlay does, so the message has to appear over the page itself rather than
+   in the iframe's console.
+   --------------------------------------------------------------------------- */
+
+.editor-integration-warning {
+  position: fixed;
+  z-index: 2147483000;
+  inset: 12px 12px auto 12px;
+  max-width: 720px;
+  margin-inline: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px 16px;
+  border-radius: 12px;
+  border: 1px solid rgba(180, 83, 9, 0.45);
+  background: #fffbeb;
+  color: #78350f;
+  font: 13px/1.45 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.18);
+}
+
+.editor-integration-warning__item {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.editor-integration-warning__item strong {
+  font-weight: 650;
+}
+
+.editor-integration-warning__item p {
+  margin: 0;
+  color: #92400e;
+}
+
+.editor-integration-warning__dismiss {
+  align-self: flex-start;
+  padding: 5px 12px;
+  border: 1px solid rgba(120, 53, 15, 0.35);
+  border-radius: 8px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.editor-integration-warning__dismiss:hover {
+  background: rgba(120, 53, 15, 0.08);
+}