@avocadostudio-ai/preview-adapter 0.3.2 → 0.3.3

package/dist/bridge-functions.d.ts

@@ -16,7 +16,61 @@ 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;
 /**
  * True when React rendered this editable field as block-level element children
  * (parsed markdown), not a plain text node.
@@ -61,6 +115,22 @@ 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;
 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,44 @@ 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;
+}
 // 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 +474,31 @@ 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.");
+}
 export function ensureBlockBadges() {
     document.querySelectorAll("[data-block-id]").forEach((node) => {
         const blockType = node.getAttribute("data-block-type") ?? "Block";
@@ -710,7 +875,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");
@@ -1103,7 +1268,7 @@ export function createBridgeFunctions(state, callbacks, config) {
                 state.pendingScrollAnchorY = null;
             }
             else {
-                match.scrollIntoView({ behavior: "smooth", block: "center" });
+                scrollBlockIntoView(match);
             }
         }
         if (shouldAnimate) {

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, } 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, } 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, missingBlockWrapperWarning, 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,18 @@ 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 warning = missingBlockWrapperWarning(document.querySelectorAll("[data-block-id]").length, document.querySelectorAll("[data-editable-target]").length);
+                if (warning)
+                    console.error(warning);
+            });
+        }
         // -- Mutation observer -------------------------------------------------
         let detectNewBlocksRaf = null;
         const scheduleDetectNewBlocks = () => {
@@ -255,10 +266,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 +279,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.3.3",
   "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.3.3"
   },
   "peerDependencies": {
     "next": ">=15.0.0",