@avocadostudio-ai/preview-adapter 0.3.3 → 0.4.0

package/dist/bridge-functions.d.ts

@@ -71,6 +71,51 @@ export declare function findEditableNode(parent: HTMLElement, editablePath: stri
  *      precise, and still the difference between "that one" and nothing.
  */
 export declare function resolveEditableNode(parent: HTMLElement, editablePath: string): HTMLElement | null;
+/**
+ * Does this marked node draw an image?
+ *
+ * Ask the node first. `data-editable-kind`, which `editableProps` emits from
+ * whatever the site's own block manifest says, is a statement by the only party
+ * that knows. `isImagePath` is a guess from the prop's *name* against Avocado's
+ * naming for its own catalogue — `imageUrl`, `*.src` — and it is right about
+ * Avocado's blocks for the circular reason that Avocado named them. A site
+ * calling the field `photoUrl` or `heroSrc` gets an image picker in the
+ * property panel, which reads the manifest, and no button in the preview, which
+ * does not; nothing anywhere reports a disagreement.
+ *
+ * The guess stays as the fallback: every built-in renderer, and every
+ * integration written before the attribute existed, emits a path and no kind.
+ */
+export declare function isImageEditable(node: HTMLElement, editablePath: string): boolean;
+/**
+ * May this marked node be typed into?
+ *
+ * The other half of `inlineEditable: false`, which until now existed only in the
+ * property panel: the manifest could say a string is not something anybody edits
+ * on the page, and the preview had no way to hear it. Marking such a field was
+ * therefore all-or-nothing — mark it and accept that a double-click starts a
+ * text edit, or leave it unmarked and lose the hover pill, the field selection
+ * and, when it holds a picture, the Change button.
+ *
+ * The field this was written for is the built-in blocks' `icon`: an emoji, a
+ * symbol, or the URL of a small image. Everything else renders as nothing at
+ * all, so typing the word the planner reaches for — "rocket" — into a marked
+ * emoji makes the icon disappear, with the value stored and invisible.
+ *
+ * The attribute is read from the marked element, so a site declares it once
+ * where it declares the target.
+ */
+export declare function isInlineEditable(node: HTMLElement): boolean;
+/**
+ * Should Enter insert a newline rather than committing the edit?
+ *
+ * `body` is grandfathered: it is the name Avocado's own long-text fields use,
+ * and it was the entire rule before `data-editable-multiline` existed — the same
+ * shape of mistake as guessing an image from `imageUrl`, and a site whose prose
+ * field is called `intro` or `beschreibung` got a single-line editor for a
+ * paragraph. A node that states its own answer is believed either way.
+ */
+export declare function isMultilineEditable(node: HTMLElement, editablePath: string): boolean;
 /**
  * True when React rendered this editable field as block-level element children
  * (parsed markdown), not a plain text node.
@@ -131,6 +176,45 @@ export declare function removeSkeletons(): void;
  * per-field attributes by accident. Say so once, loudly, in development.
  */
 export declare function missingBlockWrapperWarning(blockCount: number, editableCount: number): string | null;
+/**
+ * The other half of a half-finished integration — and the likelier half.
+ *
+ * `missingBlockWrapperWarning` names the case where the fields are marked and
+ * the blocks are not. This names its mirror, which is what following the
+ * integration guide to its end and stopping one step early actually produces:
+ * every block wrapped, no field marked. Wrapping blocks is a single call in the
+ * preview route; marking fields means touching the site's own components, so it
+ * is the step that gets deferred and then forgotten.
+ *
+ * What it costs is invisible rather than broken. Selection works. Highlighting,
+ * scroll-to-block, the badges, the property panel and every edit made through
+ * it all work, because the panel is built from the block manifest and never
+ * looks at the page. What is silently off is everything the overlay finds by
+ * walking the DOM: inline text editing, the field pills on hover, the image
+ * Change/Remove buttons, and the live-draft path that streams a field into the
+ * node that draws it. A reviewer sees a preview that responds to clicks and
+ * concludes it is wired.
+ *
+ * Like its mirror this is an all-or-nothing test, not a coverage check: one
+ * marked field means the integrator knows the attribute exists, and which of
+ * their fields deserve it is their call, not ours.
+ */
+export declare function missingEditableTargetsWarning(blockCount: number, editableCount: number): string | null;
+/** Every integration problem the overlay can diagnose from the page alone. */
+export declare function previewIntegrationWarnings(blockCount: number, editableCount: number): string[];
+/**
+ * Put the diagnosis where the person is looking.
+ *
+ * Both warnings above describe a preview that looks like it works, so the
+ * console they would print to is the one nobody opens — and in the editor it is
+ * the *iframe's* console, two context menus away from the window in front of
+ * the user. The symptom is "the button is missing from the preview"; the
+ * explanation has to be in the preview.
+ *
+ * Development only, and dismissible: it sits over the site's own design, and
+ * once read it has done its work.
+ */
+export declare function showIntegrationWarnings(messages: string[]): void;
 export declare function ensureBlockBadges(): void;
 export declare function clearListItemSelection(scope?: ParentNode): void;
 export declare function removeOverlayControls(deleteConfirmTimer: {

package/dist/bridge-functions.js

@@ -289,6 +289,63 @@ export function resolveEditableNode(parent, editablePath) {
     }
     return null;
 }
+/**
+ * Does this marked node draw an image?
+ *
+ * Ask the node first. `data-editable-kind`, which `editableProps` emits from
+ * whatever the site's own block manifest says, is a statement by the only party
+ * that knows. `isImagePath` is a guess from the prop's *name* against Avocado's
+ * naming for its own catalogue — `imageUrl`, `*.src` — and it is right about
+ * Avocado's blocks for the circular reason that Avocado named them. A site
+ * calling the field `photoUrl` or `heroSrc` gets an image picker in the
+ * property panel, which reads the manifest, and no button in the preview, which
+ * does not; nothing anywhere reports a disagreement.
+ *
+ * The guess stays as the fallback: every built-in renderer, and every
+ * integration written before the attribute existed, emits a path and no kind.
+ */
+export function isImageEditable(node, editablePath) {
+    const declared = node.getAttribute("data-editable-kind");
+    if (declared)
+        return declared === "image";
+    return isImagePath(editablePath);
+}
+/**
+ * May this marked node be typed into?
+ *
+ * The other half of `inlineEditable: false`, which until now existed only in the
+ * property panel: the manifest could say a string is not something anybody edits
+ * on the page, and the preview had no way to hear it. Marking such a field was
+ * therefore all-or-nothing — mark it and accept that a double-click starts a
+ * text edit, or leave it unmarked and lose the hover pill, the field selection
+ * and, when it holds a picture, the Change button.
+ *
+ * The field this was written for is the built-in blocks' `icon`: an emoji, a
+ * symbol, or the URL of a small image. Everything else renders as nothing at
+ * all, so typing the word the planner reaches for — "rocket" — into a marked
+ * emoji makes the icon disappear, with the value stored and invisible.
+ *
+ * The attribute is read from the marked element, so a site declares it once
+ * where it declares the target.
+ */
+export function isInlineEditable(node) {
+    return node.getAttribute("data-editable-inline") !== "false";
+}
+/**
+ * Should Enter insert a newline rather than committing the edit?
+ *
+ * `body` is grandfathered: it is the name Avocado's own long-text fields use,
+ * and it was the entire rule before `data-editable-multiline` existed — the same
+ * shape of mistake as guessing an image from `imageUrl`, and a site whose prose
+ * field is called `intro` or `beschreibung` got a single-line editor for a
+ * paragraph. A node that states its own answer is believed either way.
+ */
+export function isMultilineEditable(node, editablePath) {
+    const declared = node.getAttribute("data-editable-multiline");
+    if (declared)
+        return declared !== "false";
+    return editablePath === "body";
+}
 // Block-level tags that signal a field React rendered as parsed-markdown element
 // children (e.g. RichText `body`, Tabs `content`) rather than a single text node.
 const RICH_EDITABLE_SELECTOR = "p,ul,ol,li,blockquote,pre,table,h1,h2,h3,h4,h5,h6,hr";
@@ -499,6 +556,88 @@ export function missingBlockWrapperWarning(blockCount, editableCount) {
         "@avocadostudio-ai/site-sdk/editor — it sets data-block-id, data-block-type and the " +
         "editor-selectable class that the field pills are scoped to.");
 }
+/**
+ * The other half of a half-finished integration — and the likelier half.
+ *
+ * `missingBlockWrapperWarning` names the case where the fields are marked and
+ * the blocks are not. This names its mirror, which is what following the
+ * integration guide to its end and stopping one step early actually produces:
+ * every block wrapped, no field marked. Wrapping blocks is a single call in the
+ * preview route; marking fields means touching the site's own components, so it
+ * is the step that gets deferred and then forgotten.
+ *
+ * What it costs is invisible rather than broken. Selection works. Highlighting,
+ * scroll-to-block, the badges, the property panel and every edit made through
+ * it all work, because the panel is built from the block manifest and never
+ * looks at the page. What is silently off is everything the overlay finds by
+ * walking the DOM: inline text editing, the field pills on hover, the image
+ * Change/Remove buttons, and the live-draft path that streams a field into the
+ * node that draws it. A reviewer sees a preview that responds to clicks and
+ * concludes it is wired.
+ *
+ * Like its mirror this is an all-or-nothing test, not a coverage check: one
+ * marked field means the integrator knows the attribute exists, and which of
+ * their fields deserve it is their call, not ours.
+ */
+export function missingEditableTargetsWarning(blockCount, editableCount) {
+    if (editableCount > 0 || blockCount === 0)
+        return null;
+    return (`[avocado] The overlay found ${blockCount} [data-block-id] wrapper(s) and no ` +
+        "data-editable-target attribute. Selection and the property panel work; inline text " +
+        "editing, the field pills and the image Change/Remove buttons are all off, because every " +
+        "one of them is found by walking the marked fields in the page.\n" +
+        "Mark the element that draws each editable prop with editableProps(path, { kind }) from " +
+        "@avocadostudio-ai/site-sdk/editor — e.g. editableProps(\"imageUrl\", { kind: \"image\" }) " +
+        "on the wrapper around an image, editableProps(\"heading\") on the element holding it.");
+}
+/** Every integration problem the overlay can diagnose from the page alone. */
+export function previewIntegrationWarnings(blockCount, editableCount) {
+    return [
+        missingBlockWrapperWarning(blockCount, editableCount),
+        missingEditableTargetsWarning(blockCount, editableCount),
+    ].filter((w) => w !== null);
+}
+/**
+ * Put the diagnosis where the person is looking.
+ *
+ * Both warnings above describe a preview that looks like it works, so the
+ * console they would print to is the one nobody opens — and in the editor it is
+ * the *iframe's* console, two context menus away from the window in front of
+ * the user. The symptom is "the button is missing from the preview"; the
+ * explanation has to be in the preview.
+ *
+ * Development only, and dismissible: it sits over the site's own design, and
+ * once read it has done its work.
+ */
+export function showIntegrationWarnings(messages) {
+    document.querySelector(".editor-integration-warning")?.remove();
+    if (messages.length === 0)
+        return;
+    const banner = document.createElement("div");
+    banner.className = "editor-integration-warning";
+    banner.setAttribute("role", "alert");
+    for (const message of messages) {
+        const [headline, ...rest] = message.replace(/^\[avocado] /, "").split("\n");
+        const item = document.createElement("div");
+        item.className = "editor-integration-warning__item";
+        const title = document.createElement("strong");
+        title.textContent = headline ?? "";
+        item.append(title);
+        for (const line of rest) {
+            const p = document.createElement("p");
+            p.textContent = line;
+            item.append(p);
+        }
+        banner.append(item);
+    }
+    const dismiss = document.createElement("button");
+    dismiss.type = "button";
+    dismiss.className = "editor-integration-warning__dismiss";
+    dismiss.textContent = "Dismiss";
+    dismiss.addEventListener("click", () => banner.remove());
+    banner.append(dismiss);
+    document.body.append(banner);
+}
 export function ensureBlockBadges() {
     document.querySelectorAll("[data-block-id]").forEach((node) => {
         const blockType = node.getAttribute("data-block-type") ?? "Block";
@@ -605,7 +744,9 @@ export function applyAiFieldLoading(blockId, editablePath, active) {
     }
 }
 export function cleanupOverlayElements() {
-    document.querySelectorAll(".aifx-shimmer-overlay, .aifx-shimmer-sparkle, .editor-image-change-btn").forEach((el) => el.remove());
+    document
+        .querySelectorAll(".aifx-shimmer-overlay, .aifx-shimmer-sparkle, .editor-image-change-btn, .editor-integration-warning")
+        .forEach((el) => el.remove());
     document.documentElement.removeAttribute("data-editor-active");
     document.documentElement.removeAttribute("data-editor-selection-mode");
 }
@@ -706,11 +847,11 @@ export function createBridgeFunctions(state, callbacks, config) {
             }
         }
         for (const [path, value] of Object.entries(fields)) {
-            if (isImagePath(path))
-                continue;
             const node = findEditableNode(block, path);
             if (!node)
                 continue;
+            if (isImageEditable(node, path))
+                continue;
             // Rich fields (RichText body, Tabs content, etc.) render as block-level
             // React children. Writing innerHTML here desyncs React's vdom and the
             // final router.refresh() then mis-reconciles the subtree (truncated text
@@ -905,6 +1046,8 @@ export function createBridgeFunctions(state, callbacks, config) {
     const startInlineEdit = (args) => {
         if (!supportsInlineEditablePath(args.editablePath))
             return;
+        if (!isInlineEditable(args.node))
+            return;
         if (args.node.children.length > 0)
             return;
         const existing = state.inlineEditing;
@@ -919,7 +1062,7 @@ export function createBridgeFunctions(state, callbacks, config) {
             blockType: args.blockType,
             editablePath: args.editablePath,
             initialValue,
-            isMultiline: args.editablePath === "body"
+            isMultiline: isMultilineEditable(args.node, args.editablePath)
         };
         args.node.setAttribute("contenteditable", "true");
         args.node.classList.add("editor-inline-editing");
@@ -1208,7 +1351,7 @@ export function createBridgeFunctions(state, callbacks, config) {
         }
         document.querySelectorAll(".editor-selectable [data-editable-target]").forEach((el) => {
             const path = el.getAttribute("data-editable-target") ?? "";
-            if (!isImagePath(path))
+            if (!isImageEditable(el, path))
                 return;
             const block = el.closest("[data-block-id]");
             if (!block)
@@ -1638,7 +1781,7 @@ export function createBridgeFunctions(state, callbacks, config) {
         }
         applyBlockFocus(blockId, false, editablePath, { scrollIntoView: false });
         let editableValue = null;
-        if (editablePath && isImagePath(editablePath) && childNode) {
+        if (editablePath && childNode && isImageEditable(childNode, editablePath)) {
             const img = childNode.querySelector("img");
             if (img?.src)
                 editableValue = img.src;

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/preview-bridge-core.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
-import { createBridgeFunctions, createBridgeState, findBlockNode, isProgrammaticScroll, parseListItemPath, ensureBlockBadges, missingBlockWrapperWarning, scrollBlockIntoView, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
+import { createBridgeFunctions, createBridgeState, findBlockNode, isProgrammaticScroll, parseListItemPath, ensureBlockBadges, previewIntegrationWarnings, showIntegrationWarnings, scrollBlockIntoView, setNestedLabelsVisibility, showSkeleton, removeSkeletons, clearChildFocus, clearAllHighlights, clearListItemSelection, applyAiFieldLoading, cleanupOverlayElements, withPreviewParams, } from "./bridge-functions.js";
 export function PreviewBridgeCore(props) {
     // When running standalone (no editor origin) or not embedded in an iframe, render nothing.
     if (!props.editorOrigin || typeof window !== "undefined" && window.parent === window)
@@ -56,9 +56,12 @@ function PreviewBridgeCoreInner({ slug, editorOrigin, navigate, refresh, pathnam
          */
         if (process.env.NODE_ENV !== "production") {
             requestAnimationFrame(() => {
-                const warning = missingBlockWrapperWarning(document.querySelectorAll("[data-block-id]").length, document.querySelectorAll("[data-editable-target]").length);
-                if (warning)
+                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 -------------------------------------------------

package/package.json

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

package/src/styles.css

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