@zalify/storefront-kit 0.2.0 → 0.3.1

package/dist/editor/frame.d.ts

@@ -6,11 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * Editor mode neutralizes the page's own interactivity: clicks,
- * double/middle clicks, form submits, and context menus are captured
- * at the document root and suppressed, so selecting a node never
- * navigates a link, opens a drawer, or submits a form — a click is
- * only ever a selection. (Hover stays live for highlight tracking.)
+ * Editor mode has two interaction modes, switched by the host:
+ *
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `location.replace`
+ *   navigations that keep the editor-mode query param (so the next
+ *   document mounts the bridge again) and add no browser-history
+ *   entries; off-site links, new-tab links, modifier-clicks and
+ *   off-site paths (checkout, account) are blocked.
+ *
+ * Every click selects in both modes. Double/middle clicks and context
+ * menus stay suppressed. Each mount reports its URL as a `navigation`,
+ * which is how the editor follows in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -47,6 +60,26 @@ export interface FrameBridgeOptions {
 }
 /** True when this document should mount the editor bridge. */
 export declare function isEditorMode(win?: Window): boolean;
+export type NavigationDecision = {
+    kind: 'allow';
+    url: string;
+} | {
+    kind: 'block';
+    reason: 'off-origin' | 'new-tab' | 'modifier' | 'off-site' | 'download';
+};
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export declare function decideNavigation(href: string, base: string, flags: {
+    target?: string | null;
+    download?: boolean;
+    modifier?: boolean;
+}): NavigationDecision;
+/** The storefront path the editor should remember: no editor-mode param. */
+export declare function previewPathOf(href: string): string;
+export declare function isFormControl(target: EventTarget | null): boolean;
 export interface FrameBridgeController {
     unmount: () => void;
     /** Report that a persisted write round-tripped (HMR applied `hash`). */

package/dist/editor/frame.js

@@ -6,11 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * Editor mode neutralizes the page's own interactivity: clicks,
- * double/middle clicks, form submits, and context menus are captured
- * at the document root and suppressed, so selecting a node never
- * navigates a link, opens a drawer, or submits a form — a click is
- * only ever a selection. (Hover stays live for highlight tracking.)
+ * Editor mode has two interaction modes, switched by the host:
+ *
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `location.replace`
+ *   navigations that keep the editor-mode query param (so the next
+ *   document mounts the bridge again) and add no browser-history
+ *   entries; off-site links, new-tab links, modifier-clicks and
+ *   off-site paths (checkout, account) are blocked.
+ *
+ * Every click selects in both modes. Double/middle clicks and context
+ * menus stay suppressed. Each mount reports its URL as a `navigation`,
+ * which is how the editor follows in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -49,10 +62,70 @@ function visibleRectOf(element) {
     return { x: left, y: top, width: right - left, height: bottom - top };
 }
 function pathNodeOf(target) {
-    if (!(target instanceof Element))
+    if (!isElement(target))
         return null;
     return target.closest(`[${DATA_PATH_ATTR}]`);
 }
+function isElement(target) {
+    return (typeof Element !== 'undefined' && target instanceof Element);
+}
+/** Storefront paths that hand off to Shopify-hosted pages; never previewable. */
+const OFF_SITE_PATHS = [/^\/checkout(?:s)?(?:\/|$)/, /^\/cart\/c\//, /^\/account(?:\/|$)/, /^\/admin(?:\/|$)/];
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export function decideNavigation(href, base, flags) {
+    if (flags.modifier)
+        return { kind: 'block', reason: 'modifier' };
+    if (flags.download)
+        return { kind: 'block', reason: 'download' };
+    if (flags.target && flags.target !== '_self')
+        return { kind: 'block', reason: 'new-tab' };
+    let url;
+    try {
+        url = new URL(href, base);
+    }
+    catch {
+        return { kind: 'block', reason: 'off-origin' };
+    }
+    if (url.origin !== new URL(base).origin)
+        return { kind: 'block', reason: 'off-origin' };
+    if (OFF_SITE_PATHS.some((pattern) => pattern.test(url.pathname))) {
+        return { kind: 'block', reason: 'off-site' };
+    }
+    url.searchParams.set(EDITOR_MODE_PARAM, '1');
+    return { kind: 'allow', url: url.toString() };
+}
+/** The storefront path the editor should remember: no editor-mode param. */
+export function previewPathOf(href) {
+    const url = new URL(href);
+    url.searchParams.delete(EDITOR_MODE_PARAM);
+    return url.pathname + url.search;
+}
+/**
+ * Controls that keep their native behaviour in `select` mode: everything a
+ * form is made of, plus standalone inputs. Links and other buttons are the
+ * things a merchant reaches for to edit, so those stay selection-only.
+ */
+const FORM_CONTROL_SELECTOR = [
+    'input',
+    'textarea',
+    'select',
+    'option',
+    'label',
+    '[contenteditable=""]',
+    '[contenteditable="true"]',
+    'form button',
+    'form [role="button"]',
+].join(',');
+export function isFormControl(target) {
+    return isElement(target) && target.closest(FORM_CONTROL_SELECTOR) !== null;
+}
+function anchorOf(target) {
+    return isElement(target) ? target.closest('a[href]') : null;
+}
 /**
  * Mount the frame bridge. Returns a controller with an `unmount`
  * function. Call only when `isEditorMode()` is true.
@@ -61,6 +134,7 @@ export function mountFrameBridge(options) {
     const win = options.window ?? window;
     const doc = win.document;
     let editorOrigin = null;
+    let interaction = 'select';
     let lastHeight = 0;
     let selectedPath = null;
     const selectionHighlight = doc.createElement('div');
@@ -82,6 +156,15 @@ export function mountFrameBridge(options) {
             return;
         win.parent.postMessage({ z: BRIDGE_NAMESPACE, v: CONTRACT_VERSION, ...message }, target);
     };
+    // Every mount tells the editor where the preview is now: after an
+    // in-preview link or search the host would otherwise keep showing the
+    // page it originally asked for. Sent once the editor origin is pinned.
+    const reportNavigation = () => {
+        post({
+            type: 'navigation',
+            payload: { templateName: options.templateName, url: previewPathOf(win.location.href) },
+        });
+    };
     const setUnique = (attr, path) => {
         for (const node of doc.querySelectorAll(`[${attr}]`)) {
             node.removeAttribute(attr);
@@ -164,6 +247,7 @@ export function mountFrameBridge(options) {
                     editorOrigin = event.origin;
                 }
                 options.onDeviceChange?.(message.payload.device);
+                interaction = message.payload.interaction ?? 'select';
                 setSelection(message.payload.selectedPath);
                 // The first measurement can run before bridge:init arrives. It is
                 // intentionally not posted until the editor origin is pinned, so
@@ -171,6 +255,7 @@ export function mountFrameBridge(options) {
                 queueMicrotask(() => {
                     lastHeight = 0;
                     measure();
+                    reportNavigation();
                 });
                 break;
             }
@@ -220,6 +305,9 @@ export function mountFrameBridge(options) {
             case 'device:set':
                 options.onDeviceChange?.(message.payload.device);
                 break;
+            case 'interaction:set':
+                interaction = message.payload.mode;
+                break;
             case 'manifest:request': {
                 const manifest = await options.getManifest();
                 post({ type: 'manifest:response', payload: { manifest } });
@@ -244,14 +332,50 @@ export function mountFrameBridge(options) {
     };
     const handleClick = (event) => {
         const node = pathNodeOf(event.target);
-        // Editor mode owns clicks: no navigation, no dialogs.
+        if (node) {
+            const path = node.getAttribute(DATA_PATH_ATTR);
+            setSelection(path);
+            post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
+        }
+        if (interaction === 'select') {
+            // Selection only: nothing fires except form controls.
+            if (!isFormControl(event.target)) {
+                event.preventDefault();
+                event.stopPropagation();
+            }
+            return;
+        }
+        // Interact mode: the page keeps its interactivity; only navigation is
+        // policed.
+        const anchor = anchorOf(event.target);
+        if (!anchor)
+            return;
+        const decision = decideNavigation(anchor.getAttribute('href') ?? '', win.location.href, {
+            target: anchor.getAttribute('target'),
+            download: anchor.hasAttribute('download'),
+            modifier: event.metaKey || event.ctrlKey || event.shiftKey || event.altKey,
+        });
         event.preventDefault();
-        event.stopPropagation();
-        if (!node)
+        if (decision.kind === 'allow')
+            win.location.replace(decision.url);
+    };
+    const handleSubmit = (event) => {
+        const form = event.target;
+        if (!(form instanceof win.HTMLFormElement))
             return;
-        const path = node.getAttribute(DATA_PATH_ATTR);
-        setSelection(path);
-        post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
+        if ((form.getAttribute('method') ?? 'get').toLowerCase() !== 'get')
+            return;
+        // A GET form is a navigation: route it like a link so the editor-mode
+        // param survives and history stays clean. POST forms run as they are.
+        const action = new URL(form.getAttribute('action') || win.location.pathname, win.location.href);
+        for (const [key, value] of new FormData(form)) {
+            if (typeof value === 'string')
+                action.searchParams.set(key, value);
+        }
+        const decision = decideNavigation(action.toString(), win.location.href, {});
+        event.preventDefault();
+        if (decision.kind === 'allow')
+            win.location.replace(decision.url);
     };
     const handleWheel = (event) => {
         // Cross-origin iframe wheel events never reach the host canvas. Forward
@@ -274,12 +398,7 @@ export function mountFrameBridge(options) {
         event.preventDefault();
         event.stopPropagation();
     };
-    const SUPPRESSED_EVENTS = [
-        'dblclick',
-        'auxclick',
-        'submit',
-        'contextmenu',
-    ];
+    const SUPPRESSED_EVENTS = ['dblclick', 'auxclick', 'contextmenu'];
     const handleMouseMove = (() => {
         let lastPath = null;
         return (event) => {
@@ -315,6 +434,7 @@ export function mountFrameBridge(options) {
     win.addEventListener('resize', syncSelectionHighlight);
     win.addEventListener('scroll', syncSelectionHighlight, true);
     doc.addEventListener('click', handleClick, true);
+    doc.addEventListener('submit', handleSubmit, true);
     doc.addEventListener('mousemove', handleMouseMove, true);
     doc.addEventListener('wheel', handleWheel, { capture: true, passive: false });
     for (const type of SUPPRESSED_EVENTS) {
@@ -336,6 +456,7 @@ export function mountFrameBridge(options) {
             win.removeEventListener('resize', syncSelectionHighlight);
             win.removeEventListener('scroll', syncSelectionHighlight, true);
             doc.removeEventListener('click', handleClick, true);
+            doc.removeEventListener('submit', handleSubmit, true);
             doc.removeEventListener('mousemove', handleMouseMove, true);
             doc.removeEventListener('wheel', handleWheel, true);
             for (const type of SUPPRESSED_EVENTS) {

package/dist/schemas/bridge.d.ts

@@ -16,6 +16,12 @@ export declare const DATA_PATH_ATTR = "data-z-path";
 /** DOM attribute the bridge sets on the selected node. */
 export declare const DATA_SELECTED_ATTR = "data-z-selected";
 export type Device = 'desktop' | 'mobile';
+/**
+ * How clicks in the preview behave. `select` (default): a click selects the
+ * block; form controls still work but links and buttons do not fire.
+ * `interact`: the storefront is fully live and the editor follows navigation.
+ */
+export type InteractionMode = 'select' | 'interact';
 export type EditorCapability = 'editor-bootstrap-v1' | 'apply-template-v1' | 'apply-groups-v1' | 'apply-settings-v1' | 'preview-navigation-v1';
 export type PreviewResourceType = 'index' | 'product' | 'collection' | 'page' | 'blog' | 'article' | 'cart' | 'search' | 'list-collections' | '404';
 export interface PreviewContext {
@@ -79,6 +85,8 @@ export type HostMessage = BridgeEnvelope<'bridge:init', {
     editorOrigin: string;
     device: Device;
     selectedPath: string | null;
+    /** Omitted by older hosts: behaves as `select`. */
+    interaction?: InteractionMode;
 }> | BridgeEnvelope<'block:select', {
     path: string | null;
 }> | BridgeEnvelope<'block:hover', {
@@ -92,6 +100,8 @@ export type HostMessage = BridgeEnvelope<'bridge:init', {
     settingsData?: SettingsData;
 }> | BridgeEnvelope<'device:set', {
     device: Device;
+}> | BridgeEnvelope<'interaction:set', {
+    mode: InteractionMode;
 }> | BridgeEnvelope<'manifest:request', Record<string, never>> | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;
 export type FrameMessage = BridgeEnvelope<'bridge:ready', {
     contractVersion: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "The Zalify storefront SDK: framework-agnostic commerce logic (/commerce), the theme contract types and validators (/schemas), the canvas-editor bridge (/editor), and the React theme engine + shared components (/ui, /react/server). Consumed as TypeScript source inside the zalify-storefronts monorepo; published as compiled ESM + d.ts.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/editor/frame.ts

@@ -6,11 +6,24 @@
  * sync — and hands app-specific concerns (template hot-apply, device
  * emulation) to callbacks.
  *
- * Editor mode neutralizes the page's own interactivity: clicks,
- * double/middle clicks, form submits, and context menus are captured
- * at the document root and suppressed, so selecting a node never
- * navigates a link, opens a drawer, or submits a form — a click is
- * only ever a selection. (Hover stays live for highlight tracking.)
+ * Editor mode has two interaction modes, switched by the host:
+ *
+ * - `select` (default): a click selects the block under it and nothing
+ *   else happens — links and buttons do not fire, so a merchant can
+ *   reach for a nav link to edit it without leaving the page. Form
+ *   controls (inputs, selects, labels, buttons inside a form) still
+ *   work, so a search box or a sign-up form can be exercised.
+ * - `interact`: the storefront is fully live — drawers, variant
+ *   pickers, add to cart — and the bridge only polices navigation:
+ *   same-origin links and GET forms become `location.replace`
+ *   navigations that keep the editor-mode query param (so the next
+ *   document mounts the bridge again) and add no browser-history
+ *   entries; off-site links, new-tab links, modifier-clicks and
+ *   off-site paths (checkout, account) are blocked.
+ *
+ * Every click selects in both modes. Double/middle clicks and context
+ * menus stay suppressed. Each mount reports its URL as a `navigation`,
+ * which is how the editor follows in-preview browsing.
  *
  * Security: the first `bridge:init` pins the editor origin; every
  * later message must match it, and nothing but `bridge:ready` is ever
@@ -28,6 +41,7 @@ import {
   type DOMRectLike,
   type EditorBootstrap,
   type EditorCapability,
+  type InteractionMode,
   type FrameMessage,
   type HostMessage,
   type SectionGroupData,
@@ -102,10 +116,82 @@ function visibleRectOf(element: Element): DOMRectLike | null {
 }
 
 function pathNodeOf(target: EventTarget | null): HTMLElement | null {
-  if (!(target instanceof Element)) return null;
+  if (!isElement(target)) return null;
   return target.closest<HTMLElement>(`[${DATA_PATH_ATTR}]`);
 }
 
+function isElement(target: EventTarget | null): target is Element {
+  return (
+    typeof Element !== 'undefined' && target instanceof Element
+  );
+}
+
+/** Storefront paths that hand off to Shopify-hosted pages; never previewable. */
+const OFF_SITE_PATHS = [/^\/checkout(?:s)?(?:\/|$)/, /^\/cart\/c\//, /^\/account(?:\/|$)/, /^\/admin(?:\/|$)/];
+
+export type NavigationDecision =
+  | {kind: 'allow'; url: string}
+  | {kind: 'block'; reason: 'off-origin' | 'new-tab' | 'modifier' | 'off-site' | 'download'};
+
+/**
+ * Where a click on `anchor` may take the preview. Same-origin page loads are
+ * allowed (with the editor-mode param re-attached); anything that would leave
+ * the sandbox or open another window is blocked.
+ */
+export function decideNavigation(
+  href: string,
+  base: string,
+  flags: {target?: string | null; download?: boolean; modifier?: boolean},
+): NavigationDecision {
+  if (flags.modifier) return {kind: 'block', reason: 'modifier'};
+  if (flags.download) return {kind: 'block', reason: 'download'};
+  if (flags.target && flags.target !== '_self') return {kind: 'block', reason: 'new-tab'};
+  let url: URL;
+  try {
+    url = new URL(href, base);
+  } catch {
+    return {kind: 'block', reason: 'off-origin'};
+  }
+  if (url.origin !== new URL(base).origin) return {kind: 'block', reason: 'off-origin'};
+  if (OFF_SITE_PATHS.some((pattern) => pattern.test(url.pathname))) {
+    return {kind: 'block', reason: 'off-site'};
+  }
+  url.searchParams.set(EDITOR_MODE_PARAM, '1');
+  return {kind: 'allow', url: url.toString()};
+}
+
+/** The storefront path the editor should remember: no editor-mode param. */
+export function previewPathOf(href: string): string {
+  const url = new URL(href);
+  url.searchParams.delete(EDITOR_MODE_PARAM);
+  return url.pathname + url.search;
+}
+
+/**
+ * Controls that keep their native behaviour in `select` mode: everything a
+ * form is made of, plus standalone inputs. Links and other buttons are the
+ * things a merchant reaches for to edit, so those stay selection-only.
+ */
+const FORM_CONTROL_SELECTOR = [
+  'input',
+  'textarea',
+  'select',
+  'option',
+  'label',
+  '[contenteditable=""]',
+  '[contenteditable="true"]',
+  'form button',
+  'form [role="button"]',
+].join(',');
+
+export function isFormControl(target: EventTarget | null): boolean {
+  return isElement(target) && target.closest(FORM_CONTROL_SELECTOR) !== null;
+}
+
+function anchorOf(target: EventTarget | null): HTMLAnchorElement | null {
+  return isElement(target) ? target.closest<HTMLAnchorElement>('a[href]') : null;
+}
+
 export interface FrameBridgeController {
   unmount: () => void;
   /** Report that a persisted write round-tripped (HMR applied `hash`). */
@@ -126,6 +212,7 @@ export function mountFrameBridge(
   const win = options.window ?? window;
   const doc = win.document;
   let editorOrigin: string | null = null;
+  let interaction: InteractionMode = 'select';
   let lastHeight = 0;
   let selectedPath: string | null = null;
 
@@ -152,6 +239,16 @@ export function mountFrameBridge(
     );
   };
 
+  // Every mount tells the editor where the preview is now: after an
+  // in-preview link or search the host would otherwise keep showing the
+  // page it originally asked for. Sent once the editor origin is pinned.
+  const reportNavigation = (): void => {
+    post({
+      type: 'navigation',
+      payload: {templateName: options.templateName, url: previewPathOf(win.location.href)},
+    });
+  };
+
   const setUnique = (attr: string, path: string | null): void => {
     for (const node of doc.querySelectorAll(`[${attr}]`)) {
       node.removeAttribute(attr);
@@ -236,6 +333,7 @@ export function mountFrameBridge(
           editorOrigin = event.origin;
         }
         options.onDeviceChange?.(message.payload.device);
+        interaction = message.payload.interaction ?? 'select';
         setSelection(message.payload.selectedPath);
         // The first measurement can run before bridge:init arrives. It is
         // intentionally not posted until the editor origin is pinned, so
@@ -243,6 +341,7 @@ export function mountFrameBridge(
         queueMicrotask(() => {
           lastHeight = 0;
           measure();
+          reportNavigation();
         });
         break;
       }
@@ -291,6 +390,9 @@ export function mountFrameBridge(
       case 'device:set':
         options.onDeviceChange?.(message.payload.device);
         break;
+      case 'interaction:set':
+        interaction = message.payload.mode;
+        break;
       case 'manifest:request': {
         const manifest = await options.getManifest();
         post({type: 'manifest:response', payload: {manifest}});
@@ -316,13 +418,45 @@ export function mountFrameBridge(
 
   const handleClick = (event: MouseEvent): void => {
     const node = pathNodeOf(event.target);
-    // Editor mode owns clicks: no navigation, no dialogs.
+    if (node) {
+      const path = node.getAttribute(DATA_PATH_ATTR)!;
+      setSelection(path);
+      post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
+    }
+    if (interaction === 'select') {
+      // Selection only: nothing fires except form controls.
+      if (!isFormControl(event.target)) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      return;
+    }
+    // Interact mode: the page keeps its interactivity; only navigation is
+    // policed.
+    const anchor = anchorOf(event.target);
+    if (!anchor) return;
+    const decision = decideNavigation(anchor.getAttribute('href') ?? '', win.location.href, {
+      target: anchor.getAttribute('target'),
+      download: anchor.hasAttribute('download'),
+      modifier: event.metaKey || event.ctrlKey || event.shiftKey || event.altKey,
+    });
     event.preventDefault();
-    event.stopPropagation();
-    if (!node) return;
-    const path = node.getAttribute(DATA_PATH_ATTR)!;
-    setSelection(path);
-    post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
+    if (decision.kind === 'allow') win.location.replace(decision.url);
+  };
+
+  const handleSubmit = (event: Event): void => {
+    const form = event.target;
+    if (!(form instanceof win.HTMLFormElement)) return;
+    if ((form.getAttribute('method') ?? 'get').toLowerCase() !== 'get') return;
+    // A GET form is a navigation: route it like a link so the editor-mode
+    // param survives and history stays clean. POST forms run as they are.
+    const action = new URL(form.getAttribute('action') || win.location.pathname, win.location.href);
+    for (const [key, value] of new FormData(form)) {
+      if (typeof value === 'string') action.searchParams.set(key, value);
+    }
+    const decision = decideNavigation(action.toString(), win.location.href, {});
+    event.preventDefault();
+    if (decision.kind === 'allow') win.location.replace(decision.url);
   };
 
   const handleWheel = (event: WheelEvent): void => {
@@ -347,12 +481,7 @@ export function mountFrameBridge(
     event.preventDefault();
     event.stopPropagation();
   };
-  const SUPPRESSED_EVENTS = [
-    'dblclick',
-    'auxclick',
-    'submit',
-    'contextmenu',
-  ] as const;
+  const SUPPRESSED_EVENTS = ['dblclick', 'auxclick', 'contextmenu'] as const;
 
   const handleMouseMove = (() => {
     let lastPath: string | null = null;
@@ -390,6 +519,7 @@ export function mountFrameBridge(
   win.addEventListener('resize', syncSelectionHighlight);
   win.addEventListener('scroll', syncSelectionHighlight, true);
   doc.addEventListener('click', handleClick, true);
+  doc.addEventListener('submit', handleSubmit, true);
   doc.addEventListener('mousemove', handleMouseMove, true);
   doc.addEventListener('wheel', handleWheel, {capture: true, passive: false});
   for (const type of SUPPRESSED_EVENTS) {
@@ -413,6 +543,7 @@ export function mountFrameBridge(
       win.removeEventListener('resize', syncSelectionHighlight);
       win.removeEventListener('scroll', syncSelectionHighlight, true);
       doc.removeEventListener('click', handleClick, true);
+      doc.removeEventListener('submit', handleSubmit, true);
       doc.removeEventListener('mousemove', handleMouseMove, true);
       doc.removeEventListener('wheel', handleWheel, true);
       for (const type of SUPPRESSED_EVENTS) {

package/src/schemas/bridge.ts

@@ -25,6 +25,13 @@ export const DATA_SELECTED_ATTR = 'data-z-selected';
 
 export type Device = 'desktop' | 'mobile';
 
+/**
+ * How clicks in the preview behave. `select` (default): a click selects the
+ * block; form controls still work but links and buttons do not fire.
+ * `interact`: the storefront is fully live and the editor follows navigation.
+ */
+export type InteractionMode = 'select' | 'interact';
+
 export type EditorCapability =
   | 'editor-bootstrap-v1'
   | 'apply-template-v1'
@@ -139,6 +146,8 @@ export type HostMessage =
         editorOrigin: string;
         device: Device;
         selectedPath: string | null;
+        /** Omitted by older hosts: behaves as `select`. */
+        interaction?: InteractionMode;
       }
     >
   | BridgeEnvelope<'block:select', {path: string | null}>
@@ -154,6 +163,7 @@ export type HostMessage =
       }
     >
   | BridgeEnvelope<'device:set', {device: Device}>
+  | BridgeEnvelope<'interaction:set', {mode: InteractionMode}>
   | BridgeEnvelope<'manifest:request', Record<string, never>>
   | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;