@avocadostudio-ai/preview-adapter 0.6.0 → 0.8.0

package/dist/bridge-controller.d.ts

@@ -0,0 +1,61 @@
+import type { LivePreviewBridgeApi } from "./live-preview-store-core.ts";
+export type BridgeControllerConfig = {
+    /** The CONTENT slug, not the browser pathname — see {@link postRouteChanged}. */
+    slug: string;
+    editorOrigin: string;
+    pathname: string;
+    /** Navigate within the preview, preserving the editor's query parameters. */
+    navigate: (href: string) => void;
+    /**
+     * Re-render the current page against the latest draft.
+     *
+     * **Not `location.reload()`.** `smoothRefresh()` schedules `restoreAndFocus()`
+     * behind two animation frames and then polls `applyBlockFocus` twenty times at
+     * 45 ms, so that the block being edited keeps focus and scroll position across
+     * the refresh. A full document reload destroys every one of those timers along
+     * with the DOM they were going to act on, and the editor's caret jumps to the
+     * top of the page on each keystroke that commits.
+     */
+    refresh: () => void;
+    /**
+     * When provided, streamed `liveDraft` content is pushed into this store and
+     * the host re-renders the blocks itself, instead of the bridge mutating
+     * `innerHTML`.
+     *
+     * The store exists because React's virtual DOM desynchronises when the overlay
+     * writes into a subtree React owns. A host with no virtual DOM has no such
+     * hazard, so passing `null` there is the *better* branch, not a degraded one:
+     * rich fields stream through the overlay with nothing to desynchronise.
+     */
+    liveStore?: LivePreviewBridgeApi | null;
+    /**
+     * Emit integration warnings for a preview that renders but is unmarked.
+     * @default `process.env.NODE_ENV !== "production"`
+     */
+    warnOnMissingMarkers?: boolean;
+};
+/**
+ * Attach the bridge to the current document. Returns the detach function.
+ *
+ * Call it once the page's markup is in the DOM, and call the returned function
+ * before that markup goes away. On a host with client-side routing that swaps
+ * the document — Astro's `<ClientRouter />`, for one — that means detaching and
+ * re-attaching per navigation: the listeners are bound to nodes that no longer
+ * exist, and the preview goes quietly inert while still looking correct.
+ */
+export declare function attachBridge(config: BridgeControllerConfig): () => void;
+/**
+ * Tell the editor which page the preview is showing.
+ *
+ * Report the CONTENT slug, not the browser pathname. They are identical for a
+ * root-mounted site and diverge the moment one is mounted under a subpath: the
+ * pathname is `/studio/home` while the orchestrator's draft is keyed `/home`, so
+ * reporting the pathname sends `/studio/home` to `/chat` and `/ops` and the
+ * planner answers "page not found".
+ */
+export declare function postRouteChanged(slug: string, editorOrigin: string): void;
+/**
+ * Reveal AI-generated images with a blur-to-sharp animation when the real file
+ * replaces its placeholder. Returns the detach function.
+ */
+export declare function attachImageRevealWatcher(): () => void;

package/dist/bridge-controller.js

@@ -0,0 +1,387 @@
+import { createBridgeFunctions, createBridgeState, findBlockNode, isProgrammaticScroll, parseListItemPath, ensureBlockBadges, previewIntegrationWarnings, showIntegrationWarnings, scrollBlockIntoView, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
+/**
+ * Attach the bridge to the current document. Returns the detach function.
+ *
+ * Call it once the page's markup is in the DOM, and call the returned function
+ * before that markup goes away. On a host with client-side routing that swaps
+ * the document — Astro's `<ClientRouter />`, for one — that means detaching and
+ * re-attaching per navigation: the listeners are bound to nodes that no longer
+ * exist, and the preview goes quietly inert while still looking correct.
+ */
+export function attachBridge(config) {
+    const { slug, editorOrigin, pathname, navigate, refresh, liveStore } = config;
+    const warnOnMissingMarkers = config.warnOnMissingMarkers ?? process.env.NODE_ENV !== "production";
+    // -- 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();
+    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();
+    /*
+     * 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 (warnOnMissingMarkers) {
+        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 = () => {
+        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(withPreviewParams(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;
+                scrollBlockIntoView(el, { behavior, block });
+                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 (isProgrammaticScroll())
+            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();
+    };
+}
+/**
+ * Tell the editor which page the preview is showing.
+ *
+ * Report the CONTENT slug, not the browser pathname. They are identical for a
+ * root-mounted site and diverge the moment one is mounted under a subpath: the
+ * pathname is `/studio/home` while the orchestrator's draft is keyed `/home`, so
+ * reporting the pathname sends `/studio/home` to `/chat` and `/ops` and the
+ * planner answers "page not found".
+ */
+export function postRouteChanged(slug, editorOrigin) {
+    window.parent.postMessage({ protocol: "site-editor/v1", type: "routeChanged", payload: { slug: slug || "/" } }, editorOrigin);
+}
+/**
+ * Reveal AI-generated images with a blur-to-sharp animation when the real file
+ * replaces its placeholder. Returns the detach function.
+ */
+export function attachImageRevealWatcher() {
+    const placeholderBlockIds = new Set();
+    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)) {
+                placeholderBlockIds.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)) {
+                        placeholderBlockIds.add(blockId);
+                    }
+                    else if (src.startsWith("http") && placeholderBlockIds.has(blockId)) {
+                        placeholderBlockIds.delete(blockId);
+                        applyReveal(img);
+                    }
+                }
+            }
+        }
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+    scanForPlaceholders();
+    return () => observer.disconnect();
+}

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

@@ -19,6 +19,20 @@ export type LivePreviewPage = {
     updatedAt: string;
     blocks: BlockInstance[];
 };
+/**
+ * Narrow API the preview bridge uses to push streamed values into the store.
+ *
+ * Declared here rather than beside the provider because the bridge controller
+ * takes one and must not import React to name its type.
+ */
+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;
+};
 /** blockId → (editablePath → streamed value). */
 export type LivePreviewDrafts = Map<string, Map<string, string>>;
 export type LivePreviewState = {

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

@@ -17,15 +17,8 @@ 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 type { LivePreviewBridgeApi } from "./live-preview-store-core.ts";
+import type { LivePreviewBridgeApi } from "./live-preview-store-core.ts";
 export declare function LivePreviewProvider({ initialPage, children, }: {
     initialPage: LivePreviewPage;
     children: ReactNode;

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

@@ -1,4 +1,4 @@
-import type { LivePreviewBridgeApi } from "./live-preview-store.tsx";
+import type { LivePreviewBridgeApi } from "./live-preview-store-core.ts";
 export type PreviewBridgeConfig = {
     navigate: (href: string) => void;
     refresh: () => void;
@@ -16,4 +16,14 @@ export type PreviewBridgeCoreProps = {
      */
     liveStore?: LivePreviewBridgeApi | null;
 };
+/**
+ * The preview bridge, mounted by React.
+ *
+ * It renders nothing and always did. Everything it does — the `site-editor/v1`
+ * protocol, the overlay, the listeners — is in `bridge-controller.ts`, which has
+ * no framework in it; React supplies a mount point, a teardown hook, and the
+ * four values below. This component is the adapter between those two facts, and
+ * a host without React (see `@avocadostudio-ai/astro`) calls the controller
+ * directly.
+ */
 export declare function PreviewBridgeCore(props: PreviewBridgeCoreProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/preview-bridge-core.js

@@ -1,388 +1,26 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef } from "react";
-import { createBridgeFunctions, createBridgeState, findBlockNode, isProgrammaticScroll, parseListItemPath, ensureBlockBadges, previewIntegrationWarnings, showIntegrationWarnings, scrollBlockIntoView, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
+import { useEffect } from "react";
+import { attachBridge, attachImageRevealWatcher, postRouteChanged } from "./bridge-controller.js";
+/**
+ * The preview bridge, mounted by React.
+ *
+ * It renders nothing and always did. Everything it does — the `site-editor/v1`
+ * protocol, the overlay, the listeners — is in `bridge-controller.ts`, which has
+ * no framework in it; React supplies a mount point, a teardown hook, and the
+ * four values below. This component is the adapter between those two facts, and
+ * a host without React (see `@avocadostudio-ai/astro`) calls the controller
+ * directly.
+ */
 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)
+    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);
-    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();
-        /*
-         * 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 = () => {
-            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(withPreviewParams(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;
-                    scrollBlockIntoView(el, { behavior, block });
-                    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 (isProgrammaticScroll())
-                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();
-    }, []);
+    useEffect(() => attachBridge({ slug, editorOrigin, pathname, navigate, refresh, liveStore }), [editorOrigin, navigate, refresh, slug, pathname, liveStore]);
+    useEffect(() => postRouteChanged(slug, editorOrigin), [editorOrigin, slug]);
+    useEffect(() => attachImageRevealWatcher(), []);
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/preview-adapter",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,13 +16,18 @@
       "import": "./dist/preview-bridge-core.js",
       "default": "./dist/preview-bridge-core.js"
     },
+    "./bridge": {
+      "types": "./dist/bridge-functions.d.ts",
+      "import": "./dist/bridge-functions.js",
+      "default": "./dist/bridge-functions.js"
+    },
+    "./bridge-controller": {
+      "types": "./dist/bridge-controller.d.ts",
+      "import": "./dist/bridge-controller.js",
+      "default": "./dist/bridge-controller.js"
+    },
     "./styles.css": "./src/styles.css"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/avocadostudio-ai/avocado.git",
-    "directory": "packages/preview-adapter"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -32,7 +37,7 @@
     "src/styles.css"
   ],
   "dependencies": {
-    "@avocadostudio-ai/shared": "^0.6.0"
+    "@avocadostudio-ai/shared": "^0.8.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
@@ -41,6 +46,9 @@
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -61,7 +69,7 @@
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
-    "url": "https://github.com/avocadostudio-ai/avocado/issues"
+    "url": "https://docs.avocadostudio.dev"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",