@avocadostudio-ai/preview-adapter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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, 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

@@ -0,0 +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, 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/live-preview-store-core.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure state transitions for the live-preview draft store.
+ *
+ * Kept React-free (no "use client") so the reducer is unit-testable in isolation.
+ * The provider in `live-preview-store.tsx` holds a `LivePreviewState` and dispatches
+ * to these functions; every function returns the SAME reference when nothing
+ * changed, so React/`useMemo` can short-circuit.
+ */
+import { type BlockInstance } from "@avocadostudio-ai/shared";
+/**
+ * Minimal structural page shape — intentionally NOT the exact `PageDoc` so the
+ * structurally-identical PageDoc definitions across shared / site-sdk / apps-site
+ * all pass without casts. Extra fields (`meta`, …) ride along untouched.
+ */
+export type LivePreviewPage = {
+    id: string;
+    slug: string;
+    title: string;
+    updatedAt: string;
+    blocks: BlockInstance[];
+};
+/** blockId → (editablePath → streamed value). */
+export type LivePreviewDrafts = Map<string, Map<string, string>>;
+export type LivePreviewState = {
+    committed: LivePreviewPage;
+    committedVersion: number;
+    drafts: LivePreviewDrafts;
+};
+/** Use the seed's `updatedAt` (bumped on every server mutation) as the version. */
+export declare function versionOf(page: LivePreviewPage): number;
+export declare function initLivePreviewState(page: LivePreviewPage): LivePreviewState;
+/** Layer the in-flight drafts over the committed blocks (copy-on-write per block). */
+export declare function selectEffectiveBlocks(state: LivePreviewState): BlockInstance[];
+/** Replace a block's in-flight draft fields with the full set streamed so far. */
+export declare function setFieldDrafts(state: LivePreviewState, blockId: string, fields: Record<string, string>): LivePreviewState;
+/**
+ * Fold a block's drafts into the committed baseline (server has applied the op),
+ * so the streamed values stay on screen until the authoritative seed catches up.
+ */
+export declare function commitFieldDrafts(state: LivePreviewState, blockId: string): LivePreviewState;
+/** Drop all in-flight drafts (stream cancelled / rolled back). */
+export declare function clearFieldDrafts(state: LivePreviewState): LivePreviewState;
+/**
+ * Adopt a fresh server render as the new committed baseline and drop optimistic
+ * drafts — the seed already reflects every op applied up to its version. A stale
+ * / out-of-order refresh (version <= current, same page) is ignored so it can't
+ * clobber a newer optimistic baseline.
+ */
+export declare function syncServerPage(state: LivePreviewState, page: LivePreviewPage): LivePreviewState;

package/dist/live-preview-store-core.js

@@ -0,0 +1,99 @@
+/**
+ * Pure state transitions for the live-preview draft store.
+ *
+ * Kept React-free (no "use client") so the reducer is unit-testable in isolation.
+ * The provider in `live-preview-store.tsx` holds a `LivePreviewState` and dispatches
+ * to these functions; every function returns the SAME reference when nothing
+ * changed, so React/`useMemo` can short-circuit.
+ */
+import { isImagePath, setPropAtPath } from "@avocadostudio-ai/shared";
+const EMPTY_DRAFTS = new Map();
+/** Use the seed's `updatedAt` (bumped on every server mutation) as the version. */
+export function versionOf(page) {
+    const t = Date.parse(page.updatedAt);
+    return Number.isNaN(t) ? 0 : t;
+}
+export function initLivePreviewState(page) {
+    return { committed: page, committedVersion: versionOf(page), drafts: EMPTY_DRAFTS };
+}
+/**
+ * Layer a block's streamed drafts over its committed props (copy-on-write).
+ *
+ * Image-path drafts are intentionally skipped. An image URL streams in character
+ * by character, so its in-flight value spends time as a truncated string like
+ * `"https://"` or `"https://images.unsplash."` — and `next/image` validates the
+ * URL + hostname *synchronously during render* and THROWS on a malformed one,
+ * which the error boundary turns into "Failed to render <Block> block" until the
+ * stream settles. Image fields gain nothing from char-by-char streaming anyway;
+ * the committed/authoritative value carries the final URL once the op closes and
+ * a fresh server seed is adopted (`syncServerPage`). The legacy innerHTML overlay
+ * skips image paths identically — see `applyLiveDraftFields` in bridge-functions.
+ */
+function applyBlockDrafts(props, blockDrafts) {
+    let next = props;
+    for (const [path, value] of blockDrafts) {
+        if (isImagePath(path))
+            continue;
+        next = setPropAtPath(next, path, value);
+    }
+    return next;
+}
+/** Layer the in-flight drafts over the committed blocks (copy-on-write per block). */
+export function selectEffectiveBlocks(state) {
+    const { drafts } = state;
+    const blocks = state.committed.blocks;
+    if (drafts.size === 0)
+        return blocks;
+    return blocks.map((block) => {
+        const blockDrafts = drafts.get(block.id);
+        if (!blockDrafts || blockDrafts.size === 0)
+            return block;
+        const props = applyBlockDrafts(block.props, blockDrafts);
+        return props === block.props ? block : { ...block, props };
+    });
+}
+/** Replace a block's in-flight draft fields with the full set streamed so far. */
+export function setFieldDrafts(state, blockId, fields) {
+    const drafts = new Map(state.drafts);
+    drafts.set(blockId, new Map(Object.entries(fields)));
+    return { ...state, drafts };
+}
+/**
+ * Fold a block's drafts into the committed baseline (server has applied the op),
+ * so the streamed values stay on screen until the authoritative seed catches up.
+ */
+export function commitFieldDrafts(state, blockId) {
+    if (!state.drafts.has(blockId))
+        return state;
+    const blockDrafts = state.drafts.get(blockId);
+    const drafts = new Map(state.drafts);
+    drafts.delete(blockId);
+    if (!blockDrafts || blockDrafts.size === 0)
+        return { ...state, drafts };
+    const blocks = state.committed.blocks.map((block) => {
+        if (block.id !== blockId)
+            return block;
+        const props = applyBlockDrafts(block.props, blockDrafts);
+        return props === block.props ? block : { ...block, props };
+    });
+    return { ...state, committed: { ...state.committed, blocks }, drafts };
+}
+/** Drop all in-flight drafts (stream cancelled / rolled back). */
+export function clearFieldDrafts(state) {
+    return state.drafts.size === 0 ? state : { ...state, drafts: EMPTY_DRAFTS };
+}
+/**
+ * Adopt a fresh server render as the new committed baseline and drop optimistic
+ * drafts — the seed already reflects every op applied up to its version. A stale
+ * / out-of-order refresh (version <= current, same page) is ignored so it can't
+ * clobber a newer optimistic baseline.
+ */
+export function syncServerPage(state, page) {
+    const v = versionOf(page);
+    const isNewer = page.id !== state.committed.id ||
+        page.slug !== state.committed.slug ||
+        v > state.committedVersion;
+    if (!isNewer)
+        return state;
+    return { committed: page, committedVersion: v, drafts: EMPTY_DRAFTS };
+}

package/dist/live-preview-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Client-authoritative live-preview draft store.
+ *
+ * During a streaming chat edit the orchestrator emits `field_draft` events; the
+ * editor forwards them to the iframe as `liveDraft` postMessages. Instead of
+ * mutating the DOM out-of-band (the legacy innerHTML overlay — which can't touch
+ * React-owned rich/markdown subtrees without desyncing the vdom), the bridge
+ * pushes each streamed field into THIS store, and the blocks re-render natively
+ * through the real renderers. Rich vs. plain fields stop being a distinction:
+ * a draft is just an optimistic `setPropAtPath` over the committed props.
+ *
+ * Lives in preview-adapter (the lowest shared layer) so both the bridge (same
+ * package) and the site app's RenderedBlocks/EditorPageWrapper can use it. The
+ * pure state transitions live in ./live-preview-store-core (unit-tested).
+ */
+import { type ReactNode } from "react";
+import type { BlockInstance } from "@avocadostudio-ai/shared";
+import { type LivePreviewPage } from "./live-preview-store-core.ts";
+export type { LivePreviewPage } from "./live-preview-store-core.ts";
+/** Narrow API the preview bridge uses to push streamed values into the store. */
+export type LivePreviewBridgeApi = {
+    /** Replace a block's in-flight draft fields (the full set streamed so far). */
+    setFieldDrafts: (blockId: string, fields: Record<string, string>) => void;
+    /** Fold a block's drafts into the committed baseline (server applied the op). */
+    commitFieldDrafts: (blockId: string) => void;
+    /** Drop all in-flight drafts (stream cancelled / rolled back). */
+    clearFieldDrafts: () => void;
+};
+export declare function LivePreviewProvider({ initialPage, children, }: {
+    initialPage: LivePreviewPage;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Effective blocks (committed ⊕ in-flight drafts). Null when no provider is mounted. */
+export declare function useLivePreviewBlocks(): BlockInstance[] | null;
+/** Narrow store API for the preview bridge. Null when no provider is mounted (legacy path). */
+export declare function useLivePreviewBridgeApi(): LivePreviewBridgeApi | null;

package/dist/live-preview-store.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Client-authoritative live-preview draft store.
+ *
+ * During a streaming chat edit the orchestrator emits `field_draft` events; the
+ * editor forwards them to the iframe as `liveDraft` postMessages. Instead of
+ * mutating the DOM out-of-band (the legacy innerHTML overlay — which can't touch
+ * React-owned rich/markdown subtrees without desyncing the vdom), the bridge
+ * pushes each streamed field into THIS store, and the blocks re-render natively
+ * through the real renderers. Rich vs. plain fields stop being a distinction:
+ * a draft is just an optimistic `setPropAtPath` over the committed props.
+ *
+ * Lives in preview-adapter (the lowest shared layer) so both the bridge (same
+ * package) and the site app's RenderedBlocks/EditorPageWrapper can use it. The
+ * pure state transitions live in ./live-preview-store-core (unit-tested).
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { initLivePreviewState, selectEffectiveBlocks, setFieldDrafts as coreSetFieldDrafts, commitFieldDrafts as coreCommitFieldDrafts, clearFieldDrafts as coreClearFieldDrafts, syncServerPage as coreSyncServerPage, } from "./live-preview-store-core.js";
+// Two contexts so the bridge (API only) never re-renders on a keystroke, while
+// RenderedBlocks (blocks) re-renders per draft.
+const BlocksContext = createContext(null);
+const ApiContext = createContext(null);
+export function LivePreviewProvider({ initialPage, children, }) {
+    const [state, setState] = useState(() => initLivePreviewState(initialPage));
+    const setFieldDrafts = useCallback((blockId, fields) => {
+        setState((prev) => coreSetFieldDrafts(prev, blockId, fields));
+    }, []);
+    const commitFieldDrafts = useCallback((blockId) => {
+        setState((prev) => coreCommitFieldDrafts(prev, blockId));
+    }, []);
+    const clearFieldDrafts = useCallback(() => {
+        setState((prev) => coreClearFieldDrafts(prev));
+    }, []);
+    const syncServerPage = useCallback((page) => {
+        setState((prev) => coreSyncServerPage(prev, page));
+    }, []);
+    // A fresh server render (router.refresh / navigation) arrives as a new
+    // `initialPage` prop. useState ignores prop changes post-mount, so adopt it
+    // here. Idempotent: same-version seeds are no-ops (first mount included).
+    useEffect(() => {
+        syncServerPage(initialPage);
+    }, [initialPage, syncServerPage]);
+    const api = useMemo(() => ({ setFieldDrafts, commitFieldDrafts, clearFieldDrafts, syncServerPage }), [setFieldDrafts, commitFieldDrafts, clearFieldDrafts, syncServerPage]);
+    const blocks = useMemo(() => selectEffectiveBlocks(state), [state]);
+    return (_jsx(ApiContext.Provider, { value: api, children: _jsx(BlocksContext.Provider, { value: blocks, children: children }) }));
+}
+/** Effective blocks (committed ⊕ in-flight drafts). Null when no provider is mounted. */
+export function useLivePreviewBlocks() {
+    return useContext(BlocksContext);
+}
+/** Narrow store API for the preview bridge. Null when no provider is mounted (legacy path). */
+export function useLivePreviewBridgeApi() {
+    return useContext(ApiContext);
+}

package/dist/preview-bridge-core.d.ts

@@ -0,0 +1,19 @@
+import type { LivePreviewBridgeApi } from "./live-preview-store.tsx";
+export type PreviewBridgeConfig = {
+    navigate: (href: string) => void;
+    refresh: () => void;
+};
+export type PreviewBridgeCoreProps = {
+    slug: string;
+    editorOrigin: string;
+    navigate: (href: string) => void;
+    refresh: () => void;
+    pathname: string;
+    /**
+     * When provided, streamed `liveDraft` content is pushed into this store (React
+     * re-renders the blocks natively) instead of via the innerHTML overlay. Absent
+     * (no provider mounted / flag off) → the legacy renderLiveDraft path runs.
+     */
+    liveStore?: LivePreviewBridgeApi | null;
+};
+export declare function PreviewBridgeCore(props: PreviewBridgeCoreProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/preview-bridge-core.js

@@ -0,0 +1,377 @@
+"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, } 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)
+        return null;
+    return _jsx(PreviewBridgeCoreInner, { ...props });
+}
+function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathname, liveStore }) {
+    const stateRef = useRef(null);
+    const programmaticScrollUntilRef = useRef(0);
+    useEffect(() => {
+        // -- postMessage helpers ------------------------------------------------
+        const postToEditor = (type, payload) => {
+            window.parent.postMessage({ protocol: "site-editor/v1", type, payload }, editorOrigin);
+        };
+        const emitPatchAck = (txId, accepted, reason) => {
+            const msg = { type: "patchAck", txId, accepted, reason };
+            window.parent.postMessage({ source: "site-editor/v1", ...msg }, editorOrigin);
+        };
+        // -- Bridge callbacks (postMessage transport) ---------------------------
+        const callbacks = {
+            onBlockClicked: (p) => postToEditor("blockClicked", p),
+            onBlockDeleteRequested: (p) => postToEditor("blockDeleteRequested", p),
+            onBlockReordered: (p) => postToEditor("blockReordered", p),
+            onBlockAddRequested: (p) => postToEditor("blockAddRequested", p),
+            onListItemRemoveRequested: (p) => postToEditor("listItemRemoveRequested", p),
+            onListItemAddRequested: (p) => postToEditor("listItemAddRequested", p),
+            onListItemMoveRequested: (p) => postToEditor("listItemMoveRequested", p),
+            onInlineTextCommitted: (p) => postToEditor("inlineTextCommitted", p),
+            onOpenImagePicker: (p) => postToEditor("openImagePicker", p),
+            onScroll: () => postToEditor("iframeScrolled", {}),
+        };
+        // -- State & functions -------------------------------------------------
+        const state = createBridgeState();
+        stateRef.current = state;
+        const bridge = createBridgeFunctions(state, callbacks, { slug, pathname, refresh, navigate });
+        // -- Initialization ----------------------------------------------------
+        setNestedLabelsVisibility(false);
+        document.documentElement.setAttribute("data-editor-active", "");
+        // Restore selection mode if it was active before effect re-run
+        if (state.selectionMode) {
+            document.documentElement.setAttribute("data-editor-selection-mode", "");
+        }
+        // Clear stale selection classes — Fast Refresh can preserve DOM across remounts.
+        clearAllHighlights();
+        clearChildFocus();
+        clearListItemSelection();
+        ensureBlockBadges();
+        bridge.mountGlobalImageButtons();
+        // -- Mutation observer -------------------------------------------------
+        let detectNewBlocksRaf = null;
+        const scheduleDetectNewBlocks = () => {
+            if (detectNewBlocksRaf !== null)
+                return;
+            detectNewBlocksRaf = requestAnimationFrame(() => {
+                detectNewBlocksRaf = null;
+                bridge.detectNewBlocks();
+            });
+        };
+        let imageButtonsRaf = null;
+        const scheduleImageButtons = () => {
+            if (imageButtonsRaf !== null)
+                return;
+            imageButtonsRaf = requestAnimationFrame(() => {
+                imageButtonsRaf = null;
+                bridge.mountGlobalImageButtons();
+            });
+        };
+        state.observer = new MutationObserver(() => {
+            ensureBlockBadges();
+            scheduleImageButtons();
+            scheduleDetectNewBlocks();
+        });
+        if (document.body)
+            state.observer.observe(document.body, { childList: true, subtree: true });
+        // -- postMessage handler -----------------------------------------------
+        const onMessage = (event) => {
+            if (event.origin !== editorOrigin)
+                return;
+            const msg = event.data;
+            if (!msg || msg.protocol !== "site-editor/v1")
+                return;
+            if (msg.type === "navigate") {
+                const rawHref = String(msg.payload.href ?? "").trim();
+                if (!rawHref)
+                    return;
+                const href = rawHref.startsWith("/") ? rawHref : `/${rawHref}`;
+                const currentHref = `${window.location.pathname}${window.location.search}`;
+                if (href === currentHref)
+                    return;
+                navigate(href);
+                return;
+            }
+            if (msg.type === "setSelectionMode") {
+                const enabled = !!msg.payload.enabled;
+                state.selectionMode = enabled;
+                if (enabled) {
+                    document.documentElement.setAttribute("data-editor-selection-mode", "");
+                    bridge.mountGlobalImageButtons();
+                }
+                else {
+                    document.documentElement.removeAttribute("data-editor-selection-mode");
+                    document.querySelectorAll(".editor-image-change-btn").forEach((el) => el.remove());
+                }
+                return;
+            }
+            if (msg.type === "applyPatch") {
+                if (state.serverVersion !== msg.fromVersion) {
+                    emitPatchAck(msg.txId, false, "version_mismatch");
+                    return;
+                }
+                state.serverVersion = msg.toVersion;
+                if (msg.focusBlockId) {
+                    state.pendingFocusId = msg.focusBlockId;
+                    const isStructural = msg.op?.op === "add_block" || msg.op?.op === "move_block";
+                    state.pendingScrollIntoView = isStructural || state.pendingScrollIntoView;
+                }
+                if (msg.op?.op === "move_item") {
+                    state.skipParentAnimationOnce = true;
+                }
+                state.expectingNewBlocks = msg.op?.op === "add_block";
+                bridge.smoothRefresh();
+                emitPatchAck(msg.txId, true);
+                return;
+            }
+            if (msg.type === "resetToServer") {
+                state.serverVersion = msg.toVersion;
+                state.expectingNewBlocks = true;
+                if (msg.focusBlockId) {
+                    state.pendingFocusId = msg.focusBlockId;
+                    state.pendingScrollIntoView = false;
+                }
+                state.pendingListItemMovePath = null;
+                bridge.setChildSelectionLock(null);
+                bridge.smoothRefresh(true);
+                return;
+            }
+            if (msg.type === "draftUpdated") {
+                const focusBlockId = String(msg.payload.focusBlockId ?? "");
+                state.pendingFocusId = focusBlockId || null;
+                // Opt-in: the editor sets this when the changed/added block should be
+                // scrolled into view after the refresh (a newly added block is only in
+                // the DOM now). Explicit so the other ~20 draftUpdated callers are unaffected.
+                state.pendingScrollIntoView = msg.payload.scrollIntoView === true;
+                state.expectingNewBlocks = true;
+                bridge.clearLiveDraft();
+                clearChildFocus();
+                state.selectedEditablePath = null;
+                state.pendingListItemMovePath = null;
+                bridge.setChildSelectionLock(null);
+                const navigateTo = typeof msg.payload.navigateTo === "string" ? msg.payload.navigateTo.trim() : "";
+                if (navigateTo) {
+                    const href = navigateTo.startsWith("/") ? navigateTo : `/${navigateTo}`;
+                    navigate(`${href}${window.location.search}`);
+                }
+                else {
+                    bridge.smoothRefresh();
+                }
+            }
+            if (msg.type === "highlightBlock") {
+                const blockId = String(msg.payload.blockId ?? "");
+                let editablePath = String(msg.payload.editablePath ?? "") || undefined;
+                if (!editablePath && state.pendingListItemMovePath && state.selectedBlockId === blockId) {
+                    editablePath = state.pendingListItemMovePath;
+                }
+                if (!editablePath) {
+                    state.selectedEditablePath = null;
+                    state.pendingListItemMovePath = null;
+                    bridge.setChildSelectionLock(null);
+                }
+                else if (state.pendingListItemMovePath === editablePath) {
+                    state.pendingListItemMovePath = null;
+                    const parsed = parseListItemPath(editablePath);
+                    if (parsed) {
+                        const existing = state.childSelectionLock;
+                        const position = existing && existing.blockId === blockId && existing.listKey === parsed.listKey
+                            ? existing.position
+                            : undefined;
+                        bridge.setChildSelectionLock({ blockId, listKey: parsed.listKey, index: parsed.index, position });
+                    }
+                }
+                else {
+                    const parsed = parseListItemPath(editablePath);
+                    if (parsed) {
+                        const existing = state.childSelectionLock;
+                        const position = existing && existing.blockId === blockId && existing.listKey === parsed.listKey
+                            ? existing.position
+                            : undefined;
+                        bridge.setChildSelectionLock({ blockId, listKey: parsed.listKey, index: parsed.index, position });
+                    }
+                    else {
+                        bridge.setChildSelectionLock(null);
+                    }
+                }
+                const wantsScroll = msg.payload.scrollIntoView === true;
+                bridge.applyBlockFocus(blockId, false, editablePath, { scrollIntoView: wantsScroll });
+            }
+            if (msg.type === "setNestedLabelsVisibility") {
+                setNestedLabelsVisibility(Boolean(msg.payload.visible));
+            }
+            if (msg.type === "liveDraft") {
+                const blockId = String(msg.payload.blockId ?? "");
+                const text = String(msg.payload.text ?? "");
+                const active = Boolean(msg.payload.active);
+                const commit = Boolean(msg.payload.commit);
+                const fields = (msg.payload.fields && typeof msg.payload.fields === "object")
+                    ? msg.payload.fields
+                    : undefined;
+                if (liveStore) {
+                    // Store path: push streamed values into React state; the blocks
+                    // re-render natively (rich/markdown fields included). The bridge only
+                    // paints the "Updating" chrome — no innerHTML mutation.
+                    if (!active) {
+                        if (commit)
+                            liveStore.commitFieldDrafts(blockId);
+                        else
+                            liveStore.clearFieldDrafts();
+                    }
+                    else if (fields) {
+                        liveStore.setFieldDrafts(blockId, fields);
+                    }
+                    bridge.renderLiveDraftChromeOnly(blockId, active);
+                }
+                else {
+                    bridge.renderLiveDraft(blockId, text, active, fields, commit);
+                }
+            }
+            if (msg.type === "showSkeleton") {
+                const afterBlockId = msg.payload.afterBlockId ? String(msg.payload.afterBlockId) : null;
+                const blockType = String(msg.payload.blockType ?? "Block");
+                showSkeleton(afterBlockId, blockType);
+            }
+            if (msg.type === "removeSkeleton") {
+                removeSkeletons();
+            }
+            if (msg.type === "aiFieldLoading") {
+                const blockId = String(msg.payload.blockId ?? "");
+                const editablePath = String(msg.payload.editablePath ?? "");
+                const active = Boolean(msg.payload.active);
+                state.activeShimmer = active ? { blockId, editablePath } : null;
+                applyAiFieldLoading(blockId, editablePath, active);
+            }
+            if (msg.type === "scrollToBlock") {
+                const blockId = String(msg.payload.blockId ?? "");
+                if (!blockId)
+                    return;
+                const behavior = msg.payload.behavior === "auto" ? "auto" : "smooth";
+                const block = ["start", "center", "end", "nearest"].includes(String(msg.payload.block))
+                    ? String(msg.payload.block)
+                    : "center";
+                const run = () => {
+                    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" });
+                    return true;
+                };
+                // The block may not yet be in the DOM if the iframe just re-rendered;
+                // retry on the next frame and again after a short delay.
+                if (!run())
+                    requestAnimationFrame(() => { if (!run())
+                        setTimeout(run, 120); });
+            }
+        };
+        // -- Scroll handler ----------------------------------------------------
+        const onScroll = () => {
+            // Swallow the scroll event if it originated from our own scrollIntoView.
+            if (Date.now() < programmaticScrollUntilRef.current)
+                return;
+            callbacks.onScroll();
+        };
+        // -- Attach event listeners --------------------------------------------
+        document.addEventListener("click", bridge.onClick, true);
+        document.addEventListener("dblclick", bridge.onDoubleClick, true);
+        document.addEventListener("pointermove", bridge.onPointerMove, true);
+        document.addEventListener("keydown", bridge.onKeyDown, true);
+        window.addEventListener("message", onMessage);
+        window.addEventListener("scroll", onScroll, { passive: true });
+        // -- Cleanup -----------------------------------------------------------
+        return () => {
+            if (detectNewBlocksRaf !== null)
+                cancelAnimationFrame(detectNewBlocksRaf);
+            if (imageButtonsRaf !== null)
+                cancelAnimationFrame(imageButtonsRaf);
+            bridge.cancelInlineEdit();
+            clearChildFocus();
+            bridge.restoreLiveDraftOriginals();
+            bridge.clearLiveDraft();
+            bridge.removeSelectedDeleteHandle();
+            state.observer?.disconnect();
+            document.removeEventListener("click", bridge.onClick, true);
+            document.removeEventListener("dblclick", bridge.onDoubleClick, true);
+            document.removeEventListener("pointermove", bridge.onPointerMove, true);
+            document.removeEventListener("keydown", bridge.onKeyDown, true);
+            window.removeEventListener("message", onMessage);
+            window.removeEventListener("scroll", onScroll);
+            cleanupOverlayElements();
+        };
+    }, [editorOrigin, navigate, refresh, slug, liveStore]);
+    useEffect(() => {
+        // Report the CONTENT slug, not the browser pathname. They're identical
+        // for root-mounted sites, but diverge when the site mounts Avocado pages
+        // under a subpath (e.g. /studio): pathname is "/studio/home" while the
+        // orchestrator's draft is keyed by the content slug "/home". Reporting
+        // pathname there makes the editor send "/studio/home" to /chat and /ops,
+        // which the planner can't resolve ("page not found").
+        window.parent.postMessage({
+            protocol: "site-editor/v1",
+            type: "routeChanged",
+            payload: { slug: slug || "/" }
+        }, editorOrigin);
+    }, [editorOrigin, slug]);
+    // Track placeholder→real image swaps for blur→sharp reveal animation
+    const placeholderBlockIdsRef = useRef(new Set());
+    useEffect(() => {
+        const PLACEHOLDER_PREFIX = "data:image/svg+xml";
+        function scanForPlaceholders() {
+            document.querySelectorAll(".hero__media img").forEach((img) => {
+                const src = img.getAttribute("src") ?? "";
+                const blockEl = img.closest("[data-block-id]");
+                if (!blockEl)
+                    return;
+                const blockId = blockEl.getAttribute("data-block-id") ?? "";
+                if (src.startsWith(PLACEHOLDER_PREFIX)) {
+                    placeholderBlockIdsRef.current.add(blockId);
+                }
+            });
+        }
+        function applyReveal(img) {
+            const doReveal = () => {
+                img.classList.add("ai-image-reveal");
+                img.addEventListener("animationend", () => img.classList.remove("ai-image-reveal"), { once: true });
+            };
+            if (img.complete && img.naturalWidth > 0)
+                doReveal();
+            else
+                img.addEventListener("load", doReveal, { once: true });
+        }
+        const observer = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                if (mutation.type !== "childList")
+                    continue;
+                for (const node of mutation.addedNodes) {
+                    if (!(node instanceof HTMLElement))
+                        continue;
+                    const imgs = node.matches?.(".hero__media img")
+                        ? [node]
+                        : Array.from(node.querySelectorAll(".hero__media img"));
+                    for (const img of imgs) {
+                        const src = img.getAttribute("src") ?? "";
+                        const blockEl = img.closest("[data-block-id]");
+                        if (!blockEl)
+                            continue;
+                        const blockId = blockEl.getAttribute("data-block-id") ?? "";
+                        if (src.startsWith(PLACEHOLDER_PREFIX)) {
+                            placeholderBlockIdsRef.current.add(blockId);
+                        }
+                        else if (src.startsWith("http") && placeholderBlockIdsRef.current.has(blockId)) {
+                            placeholderBlockIdsRef.current.delete(blockId);
+                            applyReveal(img);
+                        }
+                    }
+                }
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        scanForPlaceholders();
+        return () => observer.disconnect();
+    }, []);
+    return null;
+}

package/dist/preview-bridge.d.ts

@@ -0,0 +1,4 @@
+export declare function PreviewBridge({ slug, editorOrigin }: {
+    slug: string;
+    editorOrigin: string;
+}): import("react/jsx-runtime").JSX.Element | null;