@shoppexio/builder-runtime 0.1.0 → 0.1.2

package/src/react.tsx

@@ -3,7 +3,9 @@ import {
   BuilderSettingsSchema,
   PreviewMessageSchema,
   createEmptyBuilderSettings,
+  isTrustedPreviewParentOrigin,
   migrateLegacyBuilderSettings,
+  normalizeDedicatedPageId,
 } from '@shoppex/builder-contracts';
 import {
   createElement,
@@ -13,6 +15,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ComponentPropsWithoutRef,
   type ComponentType,
   type ElementType,
   type ReactNode,
@@ -24,8 +27,14 @@ import {
   getBuilderContentString,
   getBuilderContentValue,
 } from './content.js';
+import { BUILDER_PREVIEW_REVIEWS } from './preview-fixtures.js';
 import { createBuilderCss } from './css-vars.js';
+import { builderBlock, type BuilderAttributeMap } from './attributes.js';
 import { getPageBlocks, getPageLayout, getVisiblePageBlocks } from './layout.js';
+import {
+  getNavigationHeaderSettings,
+  resolveSearchBarSettings,
+} from './search-bar-settings.js';
 import { resolveStyleSlotValue } from './style-slots.js';
 
 type BuilderRuntimeContextValue = {
@@ -37,6 +46,11 @@ const BUILDER_STATE_EVENT_NAME = 'shoppex:builder-state';
 const BUILDER_BLOCK_SELECTOR = '[data-builder-block]';
 const BUILDER_CONTENT_SELECTOR = '[data-builder-content]';
 const BUILDER_SELECTED_SELECTOR = '[data-builder-selected="true"]';
+const BUILDER_READY_HEALTH = {
+  reactMounted: true,
+  builderRuntimeProvider: true,
+  protocolVersion: 2,
+} as const;
 
 const BuilderRuntimeContext = createContext<BuilderRuntimeContextValue | null>(null);
 const BuilderBlockContext = createContext<BlockInstance | null>(null);
@@ -67,11 +81,14 @@ export function BuilderRuntimePreviewProvider({
   useEffect(() => {
     const currentWindow = window as Window & {
       __SHOPPEX_BUILDER_SETTINGS__?: BuilderSettings;
+      __SHOPPEX_PREVIEW_SESSION_PATH__?: string;
     };
-    const parentOrigin = getPreviewParentOrigin(document.referrer);
+    const parentOrigin = getPreviewParentOrigin(window.location, document.referrer);
     const isTrustedPreviewEmbed = isTrustedBuilderPreviewEmbed(window.location, parentOrigin);
     const removeInspectorStyles = isTrustedPreviewEmbed ? installBuilderPreviewInspectorStyles() : () => {};
     const removeHoverInspector = isTrustedPreviewEmbed ? installBuilderPreviewHoverInspector() : () => {};
+    let interactionMode: 'edit' | 'preview' = 'edit';
+    let removeDirectManipulation: () => void = () => {};
 
     const postToParent = (event: MessageEvent<unknown> | null, response: unknown) => {
       const target = event?.source && 'postMessage' in event.source ? event.source : window.parent;
@@ -82,6 +99,13 @@ export function BuilderRuntimePreviewProvider({
         targetOrigin || '*',
       );
     };
+    const postReady = (event: MessageEvent<unknown> | null) => {
+      postToParent(event, {
+        type: 'READY',
+        revision: settingsRevisionRef.current,
+        health: BUILDER_READY_HEALTH,
+      });
+    };
 
     const applySettings = (input: unknown): { status: 'applied'; settings: BuilderSettings } | { status: 'invalid' | 'stale' } => {
       const parsed = BuilderSettingsSchema.safeParse(input);
@@ -110,7 +134,7 @@ export function BuilderRuntimePreviewProvider({
       const message = parsed.data;
 
       if (message.type === 'REQUEST_READY') {
-        postToParent(event, { type: 'READY', revision: settingsRevisionRef.current });
+        postReady(event);
         return;
       }
 
@@ -131,20 +155,49 @@ export function BuilderRuntimePreviewProvider({
 
       if (message.type === 'RELOAD') {
         postToParent(event, { type: 'APPLIED', revision: message.revision });
-        window.setTimeout(() => window.location.reload(), 0);
+        const previewReloadTarget = resolvePreviewReloadTarget(
+          window.location,
+          currentWindow.__SHOPPEX_PREVIEW_SESSION_PATH__,
+        );
+        window.setTimeout(() => {
+          if (previewReloadTarget) {
+            window.location.href = previewReloadTarget;
+            return;
+          }
+          window.location.reload();
+        }, 0);
         return;
       }
 
       if (message.type === 'SELECT_ELEMENT') {
         selectBuilderElement(message.selection.blockId);
+        return;
+      }
+
+      if (message.type === 'SET_INTERACTION_MODE') {
+        interactionMode = message.mode;
+        document.documentElement.setAttribute(
+          'data-builder-interaction-mode',
+          interactionMode,
+        );
+        return;
       }
     };
 
     const handleBuilderClick = (event: MouseEvent) => {
       if (!isTrustedPreviewEmbed) return;
+      // In "preview" interaction mode let the storefront react to clicks
+      // naturally so the merchant can test buy-now flows or anchor links.
+      if (interactionMode === 'preview') return;
       const target = event.target;
       if (!(target instanceof Element)) return;
 
+      // Once an element is in inline-edit mode, clicks on it should
+      // place the caret instead of re-firing block selection. The
+      // mousedown handler in installBuilderDirectManipulation has
+      // already validated this is a legitimate edit interaction.
+      if (target.closest('[data-builder-inline-edit="true"]')) return;
+
       const blockElement = target.closest<HTMLElement>(BUILDER_BLOCK_SELECTOR);
       if (!blockElement) return;
 
@@ -161,19 +214,59 @@ export function BuilderRuntimePreviewProvider({
       });
     };
 
-    if (isTrustedPreviewEmbed) {
-      postToParent(null, { type: 'READY', revision: settingsRevisionRef.current });
-    }
+    const postPreviewError = (source: 'error' | 'unhandledrejection', error: unknown) => {
+      if (!isTrustedPreviewEmbed) return;
+      const normalized = normalizePreviewRuntimeError(error);
+      postToParent(null, {
+        type: 'PREVIEW_ERROR',
+        revision: settingsRevisionRef.current,
+        message: normalized.message,
+        ...(normalized.stack ? { stack: normalized.stack } : {}),
+        source,
+        phase: 'runtime',
+        diagnostics: {
+          name: normalized.name,
+          href: window.location.href,
+          referrer: document.referrer || undefined,
+          parentOrigin: parentOrigin ?? undefined,
+          previewMode: new URLSearchParams(window.location.search).get('shoppex-preview-mode') ?? undefined,
+          userAgent: navigator.userAgent,
+        },
+      });
+    };
+
+    const handleRuntimeError = (event: ErrorEvent) => {
+      postPreviewError('error', event.error ?? event.message);
+    };
+
+    const handleUnhandledRejection = (event: PromiseRejectionEvent) => {
+      postPreviewError('unhandledrejection', event.reason);
+    };
 
     window.addEventListener(BUILDER_STATE_EVENT_NAME, handleBuilderState);
     window.addEventListener('message', handlePreviewMessage);
     window.addEventListener('click', handleBuilderClick, true);
+    window.addEventListener('error', handleRuntimeError);
+    window.addEventListener('unhandledrejection', handleUnhandledRejection);
+    if (isTrustedPreviewEmbed) {
+      (window as Window & {
+        __SHOPPEX_PREVIEW_DISABLE_BOOTSTRAP_ERROR_BRIDGE__?: () => void;
+      }).__SHOPPEX_PREVIEW_DISABLE_BOOTSTRAP_ERROR_BRIDGE__?.();
+      removeDirectManipulation = installBuilderDirectManipulation(
+        (message) => postToParent(null, message),
+        () => settingsRevisionRef.current,
+      );
+      postReady(null);
+    }
     return () => {
       removeInspectorStyles();
       removeHoverInspector();
+      removeDirectManipulation();
       window.removeEventListener(BUILDER_STATE_EVENT_NAME, handleBuilderState);
       window.removeEventListener('message', handlePreviewMessage);
       window.removeEventListener('click', handleBuilderClick, true);
+      window.removeEventListener('error', handleRuntimeError);
+      window.removeEventListener('unhandledrejection', handleUnhandledRejection);
     };
   }, []);
 
@@ -242,7 +335,11 @@ export function BuilderPage<TContext = unknown>({
       {pageBlocks.map((block) => {
         const Component = registry[block.type];
         if (!Component) {
-          return fallback;
+          return (
+            <BuilderBlockProvider key={block.id} block={block}>
+              {fallback ?? renderMissingBuilderBlock(pageId, block)}
+            </BuilderBlockProvider>
+          );
         }
 
         return (
@@ -255,6 +352,33 @@ export function BuilderPage<TContext = unknown>({
   );
 }
 
+function renderMissingBuilderBlock(pageId: string, block: BlockInstance): ReactNode {
+  if (!isBuilderPreviewRuntime()) {
+    return null;
+  }
+
+  return createElement(
+    'div',
+    {
+      'data-page-id': pageId,
+      'data-builder-block': block.id,
+      'data-builder-block-type': block.type,
+      'data-builder-runtime-error': 'missing-block-component',
+      style: {
+        margin: '12px 0',
+        border: '1px solid #dc2626',
+        borderRadius: '8px',
+        background: '#fef2f2',
+        color: '#7f1d1d',
+        padding: '12px',
+        fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+        fontSize: '13px',
+      },
+    },
+    `Missing Builder component for block "${block.type}".`,
+  );
+}
+
 export function useBuilderRuntime(): BuilderRuntimeContextValue {
   const context = useContext(BuilderRuntimeContext);
   if (!context) {
@@ -319,6 +443,90 @@ export function useVisibleBuilderPageBlocks(pageId: string) {
   return getVisiblePageBlocks(useBuilderRuntime().settings, pageId);
 }
 
+export function useThemePageBlocks(pageId: string, defaultOrder: string[]): BlockInstance[] {
+  const { settings } = useBuilderRuntime();
+  const canonicalPageId = normalizeDedicatedPageId(pageId);
+
+  return useMemo(() => {
+    const page = settings.theme.layout[canonicalPageId];
+    if (page) {
+      return page.blocks.filter((block) => block.visible);
+    }
+
+    return defaultOrder.map((type) => ({ id: type, type, visible: true, settings: {} }));
+  }, [canonicalPageId, defaultOrder, settings.theme.layout]);
+}
+
+export function useThemePageBlockAttributes(
+  pageId: string,
+  defaultOrder: string[],
+): BuilderAttributeMap {
+  const canonicalPageId = normalizeDedicatedPageId(pageId);
+  const blocks = useThemePageBlocks(pageId, defaultOrder);
+  const block = blocks[0];
+
+  return useMemo(
+    () => ({
+      'data-page-id': canonicalPageId,
+      ...(block ? builderBlock(block.id, block.type) : {}),
+    }),
+    [block, canonicalPageId],
+  );
+}
+
+type DedicatedBuilderPageProps<T extends ElementType> = {
+  pageId: string;
+  defaultBlockOrder: string[];
+  as?: T;
+  children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<T>, 'as' | 'children'>;
+
+export function DedicatedBuilderPage<T extends ElementType = 'section'>({
+  pageId,
+  defaultBlockOrder,
+  as,
+  children,
+  ...rest
+}: DedicatedBuilderPageProps<T>) {
+  const attrs = useThemePageBlockAttributes(pageId, defaultBlockOrder);
+  const Component = (as ?? 'section') as ElementType;
+
+  return createElement(Component, { ...attrs, ...rest }, children);
+}
+
+export function useBuilderPreviewReviews<T>(input: {
+  reviews: T[];
+  isLoading: boolean;
+  error: unknown;
+  fixtures?: T[];
+}): {
+  reviews: T[];
+  isLoading: boolean;
+  error: unknown;
+  isUsingFixtures: boolean;
+} {
+  const fixtures = input.fixtures ?? (BUILDER_PREVIEW_REVIEWS as T[]);
+  const shouldUseFixtures = isBuilderPreviewRuntime() && Boolean(input.error);
+
+  return useMemo(() => {
+    if (!shouldUseFixtures) {
+      return {
+        reviews: input.reviews,
+        isLoading: input.isLoading,
+        error: input.error,
+        isUsingFixtures: false,
+      };
+    }
+
+    return {
+      reviews: fixtures,
+      isLoading: false,
+      error: null,
+      isUsingFixtures: true,
+    };
+  }, [fixtures, input.error, input.isLoading, input.reviews, shouldUseFixtures]);
+}
+
 export function useBuilderStyleSlot(
   slotId: StyleSlotId,
   input: { breakpoint?: Breakpoint; fallback?: unknown } = {},
@@ -358,6 +566,67 @@ function getNestedBuilderSetting(record: Record<string, unknown>, path: string):
   return current;
 }
 
+export function useSearchBarSettings(input: {
+  variant: 'hero' | 'navigation';
+  headerSettings?: Record<string, unknown>;
+}) {
+  const runtime = useBuilderRuntime();
+  const headerSettings = useMemo(
+    () => input.headerSettings ?? getNavigationHeaderSettings(runtime.settings),
+    [input.headerSettings, runtime.settings],
+  );
+
+  const heroPlaceholder = useBuilderContentValue('hero.search.placeholder');
+  const heroBackground = useBuilderContentValue('hero.search.background');
+  const heroBorderColor = useBuilderContentValue('hero.search.borderColor');
+  const heroBorderRadius = useBuilderContentValue('hero.search.borderRadius');
+  const heroMaxWidth = useBuilderContentValue('hero.search.maxWidth');
+  const heroShowShortcut = useBuilderContentValue('hero.search.showShortcut');
+  const heroShow = useBuilderContentValue('hero.search.show');
+
+  return useMemo(
+    () =>
+      resolveSearchBarSettings({
+        variant: input.variant,
+        headerSettings,
+        heroValues: {
+          'hero.search.placeholder': heroPlaceholder,
+          'hero.search.background': heroBackground,
+          'hero.search.borderColor': heroBorderColor,
+          'hero.search.borderRadius': heroBorderRadius,
+          'hero.search.maxWidth': heroMaxWidth,
+          'hero.search.showShortcut': heroShowShortcut,
+          'hero.search.show': heroShow,
+        },
+      }),
+    [
+      headerSettings,
+      heroBackground,
+      heroBorderColor,
+      heroBorderRadius,
+      heroMaxWidth,
+      heroPlaceholder,
+      heroShow,
+      heroShowShortcut,
+      input.variant,
+    ],
+  );
+}
+
+export {
+  buildSearchShellStyle,
+  getNavigationHeaderSettings,
+  resolveSearchBarSettings,
+} from './search-bar-settings.js';
+
+export function isBuilderPreviewRuntime(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  return window.location.search.includes('shoppex-preview-mode=theme');
+}
+
 function parseInitialBuilderSettings(input: unknown): BuilderSettings {
   const parsed = BuilderSettingsSchema.safeParse(input);
   if (parsed.success) return parsed.data;
@@ -399,19 +668,60 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function getPreviewParentOrigin(referrer: string): string | null {
-  if (!referrer) return null;
+export function resolvePreviewReloadTarget(
+  location: Pick<Location, 'search' | 'hash'>,
+  sessionPath: unknown,
+): string | null {
+  if (typeof sessionPath !== 'string' || !sessionPath.startsWith('/s/')) {
+    return null;
+  }
+
+  return `${sessionPath}${location.search}${location.hash}`;
+}
+
+function normalizePreviewRuntimeError(error: unknown): { message: string; stack?: string; name?: string } {
+  if (error instanceof Error) {
+    return {
+      message: error.message || error.name || 'Preview runtime error',
+      name: error.name,
+      ...(typeof error.stack === 'string' && error.stack ? { stack: error.stack } : {}),
+    };
+  }
+
+  if (typeof error === 'string') {
+    return { message: error || 'Preview runtime error' };
+  }
+
+  if (isRecord(error)) {
+    const message = typeof error.message === 'string' && error.message
+      ? error.message
+      : 'Preview runtime error';
+    const stack = typeof error.stack === 'string' && error.stack ? error.stack : undefined;
+    const name = typeof error.name === 'string' && error.name ? error.name : undefined;
+    return { message, ...(stack ? { stack } : {}), ...(name ? { name } : {}) };
+  }
+
+  return { message: 'Preview runtime error' };
+}
+
+function parseOrigin(value: string | null | undefined): string | null {
+  if (!value) return null;
   try {
-    return new URL(referrer).origin;
+    return new URL(value).origin;
   } catch {
     return null;
   }
 }
 
+function getPreviewParentOrigin(location: Location, referrer: string): string | null {
+  const explicitOrigin = new URLSearchParams(location.search).get('shoppex-preview-parent-origin');
+  return parseOrigin(explicitOrigin) ?? parseOrigin(referrer);
+}
+
 function isTrustedBuilderPreviewEmbed(location: Location, parentOrigin: string | null): boolean {
   if (window.parent === window || !parentOrigin) return false;
   if (!hasBuilderPreviewMode(location)) return false;
-  return isTrustedBuilderPreviewParentOrigin(parentOrigin);
+  return isTrustedPreviewParentOrigin(parentOrigin);
 }
 
 function hasBuilderPreviewMode(location: Location): boolean {
@@ -423,25 +733,6 @@ function hasBuilderPreviewMode(location: Location): boolean {
   );
 }
 
-function isTrustedBuilderPreviewParentOrigin(origin: string): boolean {
-  try {
-    const parsed = new URL(origin);
-    const hostname = parsed.hostname.toLowerCase();
-    return (
-      hostname === 'dashboard.shoppex.io'
-      || hostname === 'dashboard.shoppex.test'
-      || hostname === 'localhost'
-      || hostname === '127.0.0.1'
-      || hostname === '::1'
-      || hostname.endsWith('.localhost')
-      || hostname.endsWith('.vercel.app')
-      || hostname.endsWith('.vercel.run')
-    );
-  } catch {
-    return false;
-  }
-}
-
 function selectBuilderElement(blockId: string | undefined): void {
   document
     .querySelectorAll<HTMLElement>(BUILDER_SELECTED_SELECTOR)
@@ -455,7 +746,10 @@ function selectBuilderElement(blockId: string | undefined): void {
   if (!target) return;
 
   target.setAttribute('data-builder-selected', 'true');
-  target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  const pageId = target.getAttribute('data-page-id');
+  const scrollBlock =
+    pageId === 'footer' ? 'end' : pageId === 'navigation' ? 'start' : 'nearest';
+  target.scrollIntoView({ behavior: 'smooth', block: scrollBlock });
 }
 
 function createBuilderSelection(blockElement: HTMLElement, target: Element): BuilderSelection {
@@ -502,49 +796,479 @@ function installBuilderPreviewInspectorStyles(): () => void {
       position: relative;
     }
     [data-builder-block][data-builder-selected="true"] {
-      outline: 2px solid #2563eb;
+      outline: 1px solid rgba(124, 58, 237, 0.7);
       outline-offset: 4px;
     }
     [data-builder-block][data-builder-hovered="true"] {
-      outline: 1px dashed #2563eb;
+      outline: 1px dashed rgba(124, 58, 237, 0.5);
       outline-offset: 4px;
       cursor: pointer;
     }
+    /* Block-name tooltip in the upper-left corner of the hovered block.
+       Driven by a data-builder-block-label attribute the runtime sets
+       from manifest.blocks[type].label when available, falling back to
+       the block-type slug. */
+    [data-builder-block][data-builder-hovered="true"]::before {
+      content: attr(data-builder-block-label);
+      position: absolute;
+      top: -22px;
+      left: 0;
+      padding: 2px 6px;
+      font-size: 11px;
+      font-weight: 500;
+      line-height: 1.3;
+      color: #ffffff;
+      background: #7c3aed;
+      border-radius: 4px;
+      pointer-events: none;
+      white-space: nowrap;
+      z-index: 999;
+    }
+    /* Sub-element hover: thinner outline so a hover on a text or image
+       inside a block highlights only that target instead of the whole
+       block. Suppressed while the parent block is selected so the
+       merchant doesn't see double outlines. */
+    [data-builder-content][data-builder-content-hovered="true"] {
+      outline: 1px dashed rgba(124, 58, 237, 0.5);
+      outline-offset: 2px;
+      cursor: pointer;
+    }
+    [data-builder-block][data-builder-selected="true"] [data-builder-content][data-builder-content-hovered="true"] {
+      outline: none;
+    }
+    /* Inline-edit affordance: hover over editable text content reveals a
+       text cursor + subtle brand underline so the merchant can see what
+       a double-click would target. Images, links, and buttons stay
+       outside this rule — those have their own picker affordances. */
+    [data-builder-content][data-builder-content-hovered="true"]:not(img):not(a[href]):not(:has(a[href])):not(:has(button)) {
+      text-decoration: underline;
+      text-decoration-color: rgba(124, 58, 237, 0.55);
+      text-decoration-thickness: 2px;
+      text-underline-offset: 4px;
+      cursor: text;
+    }
+    /* Active inline-edit state: replaces the dashed outline with a
+       brand-tinted ring so the merchant gets unambiguous focus
+       feedback while typing. */
+    [data-builder-content][data-builder-inline-edit="true"] {
+      outline: 2px solid #7c3aed !important;
+      outline-offset: 4px !important;
+      border-radius: 4px;
+      background: rgba(124, 58, 237, 0.06);
+      text-decoration: none !important;
+      cursor: text !important;
+      caret-color: #7c3aed;
+    }
+    [data-builder-content][data-builder-inline-edit="true"]:focus {
+      outline: 2px solid #7c3aed !important;
+      outline-offset: 4px !important;
+    }
   `;
   document.head.appendChild(style);
   return () => style.remove();
 }
 
 function installBuilderPreviewHoverInspector(): () => void {
-  let hovered: HTMLElement | null = null;
+  let hoveredBlock: HTMLElement | null = null;
+  let hoveredContent: HTMLElement | null = null;
+
+  const clearHoveredBlock = () => {
+    hoveredBlock?.removeAttribute('data-builder-hovered');
+    hoveredBlock = null;
+  };
 
-  const clearHovered = () => {
-    hovered?.removeAttribute('data-builder-hovered');
-    hovered = null;
+  const clearHoveredContent = () => {
+    hoveredContent?.removeAttribute('data-builder-content-hovered');
+    hoveredContent = null;
   };
 
   const handleMouseOver = (event: MouseEvent) => {
     const target = event.target;
     if (!(target instanceof Element)) return;
     const blockElement = target.closest<HTMLElement>(BUILDER_BLOCK_SELECTOR);
-    if (blockElement === hovered) return;
-    clearHovered();
-    if (!blockElement) return;
-    hovered = blockElement;
-    hovered.setAttribute('data-builder-hovered', 'true');
+    const contentElement = target.closest<HTMLElement>(BUILDER_CONTENT_SELECTOR);
+
+    if (blockElement !== hoveredBlock) {
+      clearHoveredBlock();
+      if (blockElement) {
+        hoveredBlock = blockElement;
+        // Drive the ::before tooltip via a label attribute. Derive
+        // it from the block-type slug — pretty manifests already use
+        // capitalised labels, but we can't read manifest from here so
+        // we humanise the slug ("hero" → "Hero").
+        if (!blockElement.hasAttribute('data-builder-block-label')) {
+          const type = blockElement.getAttribute('data-builder-block-type') ?? '';
+          // Slugs whose Title-Cased form ("Custom Html") doesn't match the
+          // manifest's display label. We can't read manifest from here so
+          // we keep a small override table for these.
+          const SLUG_LABEL_OVERRIDES: Record<string, string> = {
+            'custom-html': 'Custom Embed',
+          };
+          const override = SLUG_LABEL_OVERRIDES[type];
+          const label = override ?? type
+            .replace(/[-_]/g, ' ')
+            .replace(/\b\w/g, (c) => c.toUpperCase());
+          if (label) blockElement.setAttribute('data-builder-block-label', label);
+        }
+        hoveredBlock.setAttribute('data-builder-hovered', 'true');
+      }
+    }
+
+    if (contentElement !== hoveredContent) {
+      clearHoveredContent();
+      if (contentElement && contentElement !== blockElement) {
+        hoveredContent = contentElement;
+        hoveredContent.setAttribute('data-builder-content-hovered', 'true');
+      }
+    }
   };
 
   const handleMouseOut = (event: MouseEvent) => {
     const relatedTarget = event.relatedTarget;
-    if (relatedTarget instanceof Node && hovered?.contains(relatedTarget)) return;
-    clearHovered();
+    if (relatedTarget instanceof Node) {
+      if (hoveredBlock?.contains(relatedTarget) && hoveredContent?.contains(relatedTarget)) return;
+      if (hoveredBlock?.contains(relatedTarget) && !hoveredContent) return;
+    }
+    clearHoveredBlock();
+    clearHoveredContent();
   };
 
   window.addEventListener('mouseover', handleMouseOver, true);
   window.addEventListener('mouseout', handleMouseOut, true);
   return () => {
-    clearHovered();
+    clearHoveredBlock();
+    clearHoveredContent();
     window.removeEventListener('mouseover', handleMouseOver, true);
     window.removeEventListener('mouseout', handleMouseOut, true);
   };
 }
+
+const INSERTER_HOVER_BAND_PX = 28;
+const INSERTER_CLEAR_DELAY_MS = 150;
+
+/**
+ * Direct-manipulation bridge: tracks the bounding rect of the selected
+ * block (for the floating toolbar), the inter-block gap currently
+ * hovered (for the "+" inserter), and inline-text-edit commits. All
+ * coordinates are reported in the iframe's viewport space; the
+ * dashboard maps them to its overlay layer.
+ */
+function installBuilderDirectManipulation(
+  postMessage: (message: unknown) => void,
+  getRevision: () => number,
+): () => void {
+  // Defensive: test environments may stub document/window without the
+  // observer APIs we rely on. In that case we silently no-op so the
+  // existing READY/APPLY handshake remains testable.
+  if (
+    typeof MutationObserver === 'undefined' ||
+    typeof window === 'undefined' ||
+    typeof document === 'undefined'
+  ) {
+    return () => {};
+  }
+
+  let trackedBlock: HTMLElement | null = null;
+  let lastRectKey: string | null = null;
+  let lastInserterKey: string | null = null;
+
+  const postBlockRect = () => {
+    if (!trackedBlock || !trackedBlock.isConnected) {
+      if (trackedBlock) {
+        postMessage({
+          type: 'BLOCK_RECT',
+          revision: getRevision(),
+          blockId: trackedBlock.getAttribute('data-builder-block') ?? '',
+          rect: null,
+        });
+      }
+      trackedBlock = null;
+      lastRectKey = null;
+      return;
+    }
+    const rect = trackedBlock.getBoundingClientRect();
+    const blockId = trackedBlock.getAttribute('data-builder-block') ?? '';
+    const next = `${blockId}|${rect.top}|${rect.left}|${rect.width}|${rect.height}`;
+    if (next === lastRectKey) return;
+    lastRectKey = next;
+    postMessage({
+      type: 'BLOCK_RECT',
+      revision: getRevision(),
+      blockId,
+      rect: {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+      },
+    });
+  };
+
+  const selectionObserver = new MutationObserver(() => {
+    const selected = document.querySelector(BUILDER_SELECTED_SELECTOR);
+    if (selected instanceof HTMLElement) {
+      trackedBlock = selected;
+      postBlockRect();
+    } else if (trackedBlock) {
+      // Selection cleared.
+      postMessage({
+        type: 'BLOCK_RECT',
+        revision: getRevision(),
+        blockId: trackedBlock.getAttribute('data-builder-block') ?? '',
+        rect: null,
+      });
+      trackedBlock = null;
+      lastRectKey = null;
+    }
+  });
+  selectionObserver.observe(document.body, {
+    attributes: true,
+    attributeFilter: ['data-builder-selected'],
+    subtree: true,
+  });
+
+  let rectFrame = 0;
+  const scheduleRectUpdate = () => {
+    if (rectFrame) return;
+    rectFrame = window.requestAnimationFrame(() => {
+      rectFrame = 0;
+      postBlockRect();
+    });
+  };
+
+  window.addEventListener('scroll', scheduleRectUpdate, true);
+  window.addEventListener('resize', scheduleRectUpdate);
+
+  // Inter-block gap inserter: detect mouse near the top/bottom edge of
+  // a tracked block stack. We don't try to be clever about which gap;
+  // every direct ancestor with a list of `[data-builder-block]` children
+  // contributes one gap per pair.
+  let inserterClearTimer: number | null = null;
+
+  const postInserter = (
+    index: number | null,
+    rect: DOMRect | null,
+  ) => {
+    const emitInserter = () => {
+      const key =
+        index === null || !rect
+          ? '__none__'
+          : `${index}|${rect.top}|${rect.left}|${rect.width}|${rect.height}`;
+      if (key === lastInserterKey) return;
+      lastInserterKey = key;
+      postMessage({
+        type: 'INSERTER_HOVER',
+        revision: getRevision(),
+        index,
+        rect:
+          rect === null
+            ? null
+            : {
+                top: rect.top,
+                left: rect.left,
+                width: rect.width,
+                height: rect.height,
+              },
+      });
+    };
+
+    if (index !== null && rect !== null) {
+      if (inserterClearTimer !== null) {
+        window.clearTimeout(inserterClearTimer);
+        inserterClearTimer = null;
+      }
+      emitInserter();
+      return;
+    }
+
+    if (inserterClearTimer !== null) return;
+    inserterClearTimer = window.setTimeout(() => {
+      inserterClearTimer = null;
+      emitInserter();
+    }, INSERTER_CLEAR_DELAY_MS);
+  };
+
+  const handleMouseMove = (event: MouseEvent) => {
+    const blocks = Array.from(
+      document.querySelectorAll<HTMLElement>(BUILDER_BLOCK_SELECTOR),
+    ).filter((el) => {
+      // Only consider top-level builder blocks inside the same parent.
+      const parent = el.parentElement;
+      return parent
+        ? Array.from(parent.children).some(
+            (child) =>
+              child instanceof HTMLElement &&
+              child.hasAttribute('data-builder-block'),
+          )
+        : false;
+    });
+
+    for (let i = 0; i < blocks.length - 1; i++) {
+      const top = blocks[i]!.getBoundingClientRect();
+      const bottom = blocks[i + 1]!.getBoundingClientRect();
+      const gapTop = top.bottom;
+      const gapBottom = bottom.top;
+      if (
+        event.clientY >= gapTop - INSERTER_HOVER_BAND_PX / 2 &&
+        event.clientY <= gapBottom + INSERTER_HOVER_BAND_PX / 2 &&
+        event.clientX >= top.left &&
+        event.clientX <= top.right
+      ) {
+        const rect = new DOMRect(
+          top.left,
+          gapTop,
+          top.width,
+          Math.max(gapBottom - gapTop, INSERTER_HOVER_BAND_PX),
+        );
+        postInserter(i + 1, rect);
+        return;
+      }
+    }
+    postInserter(null, null);
+  };
+  window.addEventListener('mousemove', handleMouseMove);
+
+  // Inline edit: double-click on an editable text content element flips
+  // it into contenteditable and gives the caret to the merchant.
+  //
+  // We don't bind the browser's native `dblclick` event because the
+  // dashboard's APPLY_STATE round-trip can rerender the iframe between
+  // the two clicks and the browser silently drops the dblclick.
+  // Instead we track two consecutive `mousedown` events on the same
+  // content element within a 500ms window — same behaviour as the
+  // native event but resilient to React re-mounts in between.
+  let lastDownContent: HTMLElement | null = null;
+  let lastDownAt = 0;
+  const DOUBLE_DOWN_WINDOW_MS = 500;
+
+  const beginInlineEdit = (contentElement: HTMLElement) => {
+    const blockElement = contentElement.closest<HTMLElement>(BUILDER_BLOCK_SELECTOR);
+    const blockId = blockElement?.getAttribute('data-builder-block');
+    const contentPath = contentElement.getAttribute('data-builder-content');
+    if (!blockId || !contentPath) return false;
+
+    // Skip inline edit for images/links/buttons — those are picked
+    // separately in the inspector. Only run on plain text containers.
+    if (
+      contentElement instanceof HTMLImageElement ||
+      contentElement.closest('a[href], button')
+    ) {
+      return false;
+    }
+
+    contentElement.setAttribute('contenteditable', 'plaintext-only');
+    contentElement.setAttribute('data-builder-inline-edit', 'true');
+    contentElement.focus();
+    const range = document.createRange();
+    range.selectNodeContents(contentElement);
+    const selection = window.getSelection();
+    selection?.removeAllRanges();
+    selection?.addRange(range);
+
+    const finish = (commit: boolean) => {
+      contentElement.removeAttribute('contenteditable');
+      contentElement.removeAttribute('data-builder-inline-edit');
+      contentElement.removeEventListener('blur', onBlur);
+      contentElement.removeEventListener('keydown', onKey);
+      if (commit) {
+        const value = contentElement.textContent ?? '';
+        postMessage({
+          type: 'INLINE_EDIT_COMMIT',
+          revision: getRevision(),
+          blockId,
+          contentPath,
+          value,
+        });
+      }
+    };
+
+    const onBlur = () => finish(true);
+    const onKey = (kev: KeyboardEvent) => {
+      if (kev.key === 'Enter' && !kev.shiftKey) {
+        kev.preventDefault();
+        contentElement.blur();
+      } else if (kev.key === 'Escape') {
+        kev.preventDefault();
+        finish(false);
+        contentElement.blur();
+      }
+    };
+    contentElement.addEventListener('blur', onBlur, { once: true });
+    contentElement.addEventListener('keydown', onKey);
+    return true;
+  };
+
+  const handleMouseDown = (event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof HTMLElement)) {
+      lastDownContent = null;
+      return;
+    }
+    // If we're already in an inline edit on this element, let the
+    // browser handle caret placement normally — no special handling.
+    if (target.closest('[data-builder-inline-edit="true"]')) return;
+
+    const contentElement = target.closest<HTMLElement>(BUILDER_CONTENT_SELECTOR);
+    if (!contentElement) {
+      lastDownContent = null;
+      lastDownAt = 0;
+      return;
+    }
+    const now = Date.now();
+    const isSecondDown =
+      lastDownContent === contentElement && now - lastDownAt < DOUBLE_DOWN_WINDOW_MS;
+    if (!isSecondDown) {
+      lastDownContent = contentElement;
+      lastDownAt = now;
+      return;
+    }
+    // Second mousedown on the same content element within the window —
+    // treat as the user asking to edit inline.
+    lastDownContent = null;
+    lastDownAt = 0;
+    if (!beginInlineEdit(contentElement)) return;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+  window.addEventListener('mousedown', handleMouseDown, true);
+
+  return () => {
+    selectionObserver.disconnect();
+    if (rectFrame) window.cancelAnimationFrame(rectFrame);
+    window.removeEventListener('scroll', scheduleRectUpdate, true);
+    window.removeEventListener('resize', scheduleRectUpdate);
+    window.removeEventListener('mousemove', handleMouseMove);
+    window.removeEventListener('mousedown', handleMouseDown, true);
+  };
+}
+
+export {
+  getBuilderBlockSettingText,
+  getBuilderProductBlockAttributes,
+  getLayoutPageBlockAttributes,
+  getProductBlockText,
+  getProductPageBlockAttributes,
+} from './product-page.js';
+export {
+  createStandardProductBlockRegistry,
+  splitStandardProductPageBlocks,
+  buildStandardProductInfoTabs,
+  resolveStandardBuyBoxLabels,
+  resolveStandardDetailsLabels,
+  resolveStandardRelatedProductsTitle,
+  resolveScopedBlockSettingText,
+  STANDARD_PRODUCT_BLOCK_TYPES,
+  STANDARD_PRODUCT_PRIMARY_BLOCK_TYPES,
+  STANDARD_PRODUCT_SECONDARY_BLOCK_TYPES,
+} from './standard-product-blocks.js';
+export type {
+  StandardBuyBoxLabels,
+  StandardDetailsLabels,
+  StandardProductBlockRegistryData,
+  StandardProductBlockRegistryOptions,
+  StandardProductBlockRegistrySlots,
+  StandardProductBlockType,
+  StandardProductSettingScope,
+  StandardProductTabSpec,
+} from './standard-product-blocks.js';
+export { getBuilderPreviewReviewFixtures } from './preview-fixtures.js';