@shoppexio/builder-runtime 0.1.0 → 0.1.1

package/src/react.tsx

@@ -37,6 +37,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 +72,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 +90,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 +125,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 +146,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 +205,58 @@ 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,
+        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 +325,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 +342,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 +433,19 @@ export function useVisibleBuilderPageBlocks(pageId: string) {
   return getVisiblePageBlocks(useBuilderRuntime().settings, pageId);
 }
 
+export function useThemePageBlocks(pageId: string, defaultOrder: string[]): BlockInstance[] {
+  const { settings } = useBuilderRuntime();
+
+  return useMemo(() => {
+    const page = settings.theme.layout[pageId];
+    if (page) {
+      return page.blocks.filter((block) => block.visible);
+    }
+
+    return defaultOrder.map((type) => ({ id: type, type, visible: true, settings: {} }));
+  }, [defaultOrder, pageId, settings.theme.layout]);
+}
+
 export function useBuilderStyleSlot(
   slotId: StyleSlotId,
   input: { breakpoint?: Breakpoint; fallback?: unknown } = {},
@@ -358,6 +485,14 @@ function getNestedBuilderSetting(record: Record<string, unknown>, path: string):
   return current;
 }
 
+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,15 +534,56 @@ 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;
@@ -502,49 +678,428 @@ 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 = 16;
+
+/**
+ * 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.
+  const postInserter = (
+    index: number | null,
+    rect: DOMRect | null,
+  ) => {
+    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,
+            },
+    });
+  };
+
+  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);
+  };
+}