@shoppexio/builder-runtime 0.1.0 → 0.1.1

package/dist/react.js

@@ -10,6 +10,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,
+};
 const BuilderRuntimeContext = createContext(null);
 const BuilderBlockContext = createContext(null);
 export function BuilderRuntimeProvider({ settings, children }) {
@@ -27,10 +32,12 @@ export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
     }, [settings.revision]);
     useEffect(() => {
         const currentWindow = window;
-        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';
+        let removeDirectManipulation = () => { };
         const postToParent = (event, response) => {
             const target = event?.source && 'postMessage' in event.source ? event.source : window.parent;
             if (!target || target === window)
@@ -38,6 +45,13 @@ export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
             const targetOrigin = parentOrigin ?? event?.origin ?? '*';
             target.postMessage(response, targetOrigin || '*');
         };
+        const postReady = (event) => {
+            postToParent(event, {
+                type: 'READY',
+                revision: settingsRevisionRef.current,
+                health: BUILDER_READY_HEALTH,
+            });
+        };
         const applySettings = (input) => {
             const parsed = BuilderSettingsSchema.safeParse(input);
             if (!parsed.success)
@@ -65,7 +79,7 @@ export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
                 return;
             const message = parsed.data;
             if (message.type === 'REQUEST_READY') {
-                postToParent(event, { type: 'READY', revision: settingsRevisionRef.current });
+                postReady(event);
                 return;
             }
             if (message.type === 'APPLY_STATE') {
@@ -81,19 +95,42 @@ export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
             }
             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) => {
             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(BUILDER_BLOCK_SELECTOR);
             if (!blockElement)
                 return;
@@ -108,18 +145,51 @@ export function BuilderRuntimePreviewProvider({ initialSettings, children, }) {
                 selection,
             });
         };
-        if (isTrustedPreviewEmbed) {
-            postToParent(null, { type: 'READY', revision: settingsRevisionRef.current });
-        }
+        const postPreviewError = (source, error) => {
+            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) => {
+            postPreviewError('error', event.error ?? event.message);
+        };
+        const handleUnhandledRejection = (event) => {
+            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.__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);
         };
     }, []);
     return _jsx(BuilderRuntimeProvider, { settings: settings, children: children });
@@ -145,11 +215,32 @@ export function BuilderPage({ pageId, blocks, registry, context, fallback = null
     return (_jsx(_Fragment, { children: pageBlocks.map((block) => {
             const Component = registry[block.type];
             if (!Component) {
-                return fallback;
+                return (_jsx(BuilderBlockProvider, { block: block, children: fallback ?? renderMissingBuilderBlock(pageId, block) }, block.id));
             }
             return (_jsx(BuilderBlockProvider, { block: block, children: _jsx(Component, { block: block, context: context }) }, block.id));
         }) }));
 }
+function renderMissingBuilderBlock(pageId, block) {
+    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() {
     const context = useContext(BuilderRuntimeContext);
     if (!context) {
@@ -202,6 +293,16 @@ export function useBuilderPageBlocks(pageId) {
 export function useVisibleBuilderPageBlocks(pageId) {
     return getVisiblePageBlocks(useBuilderRuntime().settings, pageId);
 }
+export function useThemePageBlocks(pageId, defaultOrder) {
+    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, input = {}) {
     return resolveStyleSlotValue(useBuilderRuntime().settings, slotId, input);
 }
@@ -232,6 +333,12 @@ function getNestedBuilderSetting(record, path) {
     }
     return current;
 }
+function isBuilderPreviewRuntime() {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    return window.location.search.includes('shoppex-preview-mode=theme');
+}
 function parseInitialBuilderSettings(input) {
     const parsed = BuilderSettingsSchema.safeParse(input);
     if (parsed.success)
@@ -270,16 +377,47 @@ function parseBuilderRevision(input) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function getPreviewParentOrigin(referrer) {
-    if (!referrer)
+export function resolvePreviewReloadTarget(location, sessionPath) {
+    if (typeof sessionPath !== 'string' || !sessionPath.startsWith('/s/')) {
+        return null;
+    }
+    return `${sessionPath}${location.search}${location.hash}`;
+}
+function normalizePreviewRuntimeError(error) {
+    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) {
+    if (!value)
         return null;
     try {
-        return new URL(referrer).origin;
+        return new URL(value).origin;
     }
     catch {
         return null;
     }
 }
+function getPreviewParentOrigin(location, referrer) {
+    const explicitOrigin = new URLSearchParams(location.search).get('shoppex-preview-parent-origin');
+    return parseOrigin(explicitOrigin) ?? parseOrigin(referrer);
+}
 function isTrustedBuilderPreviewEmbed(location, parentOrigin) {
     if (window.parent === window || !parentOrigin)
         return false;
@@ -361,48 +499,389 @@ function installBuilderPreviewInspectorStyles() {
       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() {
-    let hovered = null;
-    const clearHovered = () => {
-        hovered?.removeAttribute('data-builder-hovered');
-        hovered = null;
+    let hoveredBlock = null;
+    let hoveredContent = null;
+    const clearHoveredBlock = () => {
+        hoveredBlock?.removeAttribute('data-builder-hovered');
+        hoveredBlock = null;
+    };
+    const clearHoveredContent = () => {
+        hoveredContent?.removeAttribute('data-builder-content-hovered');
+        hoveredContent = null;
     };
     const handleMouseOver = (event) => {
         const target = event.target;
         if (!(target instanceof Element))
             return;
         const blockElement = target.closest(BUILDER_BLOCK_SELECTOR);
-        if (blockElement === hovered)
-            return;
-        clearHovered();
-        if (!blockElement)
-            return;
-        hovered = blockElement;
-        hovered.setAttribute('data-builder-hovered', 'true');
+        const contentElement = target.closest(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 = {
+                        '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) => {
         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, getRevision) {
+    // 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 = null;
+    let lastRectKey = null;
+    let lastInserterKey = 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, rect) => {
+        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) => {
+        const blocks = Array.from(document.querySelectorAll(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 = null;
+    let lastDownAt = 0;
+    const DOUBLE_DOWN_WINDOW_MS = 500;
+    const beginInlineEdit = (contentElement) => {
+        const blockElement = contentElement.closest(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) => {
+            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) => {
+            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) => {
+        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(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);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/builder-runtime",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Theme-side Builder v2 runtime helpers for Shoppex storefront themes",
   "type": "module",
   "repository": {