@zalify/storefront-kit 0.1.9 → 0.1.12

package/dist/editor/frame.d.ts

@@ -16,7 +16,7 @@
  * later message must match it, and nothing but `bridge:ready` is ever
  * posted before the pin.
  */
-import { type Device, type SectionGroupData, type SettingsBag, type TemplateData, type ThemeEditorManifest } from '../schemas/index.ts';
+import { type Device, type EditorBootstrap, type EditorCapability, type SectionGroupData, type SettingsData, type TemplateData, type ThemeEditorManifest } from '../schemas/index.ts';
 export declare const DATA_HOVERED_ATTR = "data-z-hovered";
 export interface FrameBridgeOptions {
     /** Template currently rendered ("index", "product", …). */
@@ -25,6 +25,10 @@ export interface FrameBridgeOptions {
     hash: string;
     /** Serve the editor manifest (static import or dynamic build). */
     getManifest: () => ThemeEditorManifest | Promise<ThemeEditorManifest>;
+    /** Capabilities supported by this deployed storefront runtime. */
+    capabilities?: EditorCapability[];
+    /** Serve the complete Site Editor bootstrap payload. */
+    getBootstrap?: () => EditorBootstrap | Promise<EditorBootstrap>;
     /**
      * Hot-apply an updated template in memory (optimistic edit). Return
      * false (or throw) if the app cannot apply without a reload.
@@ -33,7 +37,7 @@ export interface FrameBridgeOptions {
         templateName: string;
         template: TemplateData;
         groups?: Record<string, SectionGroupData>;
-        settingsData?: SettingsBag;
+        settingsData?: SettingsData;
     }) => boolean | Promise<boolean>;
     onDeviceChange?: (device: Device) => void;
     /** Overrides for tests / non-browser hosts. */

package/dist/editor/frame.js

@@ -33,6 +33,21 @@ function rectOf(element) {
     const rect = element.getBoundingClientRect();
     return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
 }
+function visibleRectOf(element) {
+    const ownRect = rectOf(element);
+    if (ownRect.width > 0 && ownRect.height > 0)
+        return ownRect;
+    const childRects = [...element.children]
+        .map(rectOf)
+        .filter((rect) => rect.width > 0 && rect.height > 0);
+    if (childRects.length === 0)
+        return null;
+    const left = Math.min(...childRects.map((rect) => rect.x));
+    const top = Math.min(...childRects.map((rect) => rect.y));
+    const right = Math.max(...childRects.map((rect) => rect.x + rect.width));
+    const bottom = Math.max(...childRects.map((rect) => rect.y + rect.height));
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
 function pathNodeOf(target) {
     if (!(target instanceof Element))
         return null;
@@ -47,6 +62,19 @@ export function mountFrameBridge(options) {
     const doc = win.document;
     let editorOrigin = null;
     let lastHeight = 0;
+    let selectedPath = null;
+    const selectionHighlight = doc.createElement('div');
+    selectionHighlight.id = 'zalify-editor-highlight';
+    selectionHighlight.setAttribute('aria-hidden', 'true');
+    Object.assign(selectionHighlight.style, {
+        position: 'fixed',
+        display: 'none',
+        pointerEvents: 'none',
+        boxSizing: 'border-box',
+        border: '2px solid #2563eb',
+        zIndex: '2147483647',
+    });
+    (doc.body ?? doc.documentElement).append(selectionHighlight);
     const post = (message) => {
         // bridge:ready is the only pre-pin message; everything else waits.
         const target = editorOrigin ?? '*';
@@ -63,6 +91,43 @@ export function mountFrameBridge(options) {
         const selector = `[${DATA_PATH_ATTR}="${CSS.escape(path)}"]`;
         doc.querySelector(selector)?.setAttribute(attr, '1');
     };
+    const syncSelectionHighlight = () => {
+        if (selectedPath === null) {
+            selectionHighlight.style.display = 'none';
+            return;
+        }
+        const selector = `[${DATA_PATH_ATTR}="${CSS.escape(selectedPath)}"]`;
+        const node = doc.querySelector(selector);
+        const rect = node ? visibleRectOf(node) : null;
+        if (!rect) {
+            selectionHighlight.style.display = 'none';
+            return;
+        }
+        Object.assign(selectionHighlight.style, {
+            display: 'block',
+            left: `${rect.x}px`,
+            top: `${rect.y}px`,
+            width: `${rect.width}px`,
+            height: `${rect.height}px`,
+        });
+    };
+    const selectionResizeObserver = new win.ResizeObserver(syncSelectionHighlight);
+    const setSelection = (path) => {
+        setUnique(DATA_SELECTED_ATTR, path);
+        selectedPath = path;
+        selectionResizeObserver.disconnect();
+        if (path !== null) {
+            const selector = `[${DATA_PATH_ATTR}="${CSS.escape(path)}"]`;
+            const node = doc.querySelector(selector);
+            if (node) {
+                selectionResizeObserver.observe(node);
+                for (const child of node.children) {
+                    selectionResizeObserver.observe(child);
+                }
+            }
+        }
+        syncSelectionHighlight();
+    };
     const reportRects = () => {
         const rects = [...doc.querySelectorAll(`[${DATA_PATH_ATTR}]`)].map((node) => ({
             path: node.getAttribute(DATA_PATH_ATTR),
@@ -95,11 +160,18 @@ export function mountFrameBridge(options) {
                     editorOrigin = event.origin;
                 }
                 options.onDeviceChange?.(message.payload.device);
-                setUnique(DATA_SELECTED_ATTR, message.payload.selectedPath);
+                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
+                // invalidate the cached value and publish it now.
+                queueMicrotask(() => {
+                    lastHeight = 0;
+                    measure();
+                });
                 break;
             }
             case 'block:select':
-                setUnique(DATA_SELECTED_ATTR, message.payload.path);
+                setSelection(message.payload.path);
                 // Rects let the host scroll its full-height canvas to the
                 // selection (the frame itself has no scrollbar in that mode).
                 reportRects();
@@ -149,6 +221,21 @@ export function mountFrameBridge(options) {
                 post({ type: 'manifest:response', payload: { manifest } });
                 break;
             }
+            case 'editor:bootstrap:request': {
+                if (!options.getBootstrap) {
+                    post({
+                        type: 'bridge:error',
+                        payload: {
+                            code: 'bootstrap-unsupported',
+                            message: 'frame cannot provide Site Editor bootstrap data',
+                        },
+                    });
+                    break;
+                }
+                const bootstrap = await options.getBootstrap();
+                post({ type: 'editor:bootstrap:response', payload: { bootstrap } });
+                break;
+            }
         }
     };
     const handleClick = (event) => {
@@ -159,9 +246,26 @@ export function mountFrameBridge(options) {
         if (!node)
             return;
         const path = node.getAttribute(DATA_PATH_ATTR);
-        setUnique(DATA_SELECTED_ATTR, path);
+        setSelection(path);
         post({ type: 'block:clicked', payload: { path, rect: rectOf(node) } });
     };
+    const handleWheel = (event) => {
+        // Both previews are fixed device viewports. Let ordinary wheel gestures
+        // scroll the storefront; pinch/Ctrl+wheel remains a canvas zoom gesture.
+        if (!event.ctrlKey)
+            return;
+        event.preventDefault();
+        post({
+            type: 'viewport:wheel',
+            payload: {
+                deltaX: event.deltaX,
+                deltaY: event.deltaY,
+                ctrlKey: event.ctrlKey,
+                clientX: event.clientX,
+                clientY: event.clientY,
+            },
+        });
+    };
     /** Suppress the page's own interactivity (capture phase, doc root). */
     const suppress = (event) => {
         event.preventDefault();
@@ -188,7 +292,7 @@ export function mountFrameBridge(options) {
             });
         };
     })();
-    const measure = () => {
+    function measure() {
         // documentElement.scrollHeight never drops below the viewport, so a
         // full-height host iframe would ratchet upward forever; the body's
         // border box tracks actual content in both directions.
@@ -197,15 +301,19 @@ export function mountFrameBridge(options) {
         if (height === lastHeight || height <= 0)
             return;
         lastHeight = height;
+        syncSelectionHighlight();
         post({ type: 'height:changed', payload: { height } });
-    };
+    }
     const resizeObserver = new win.ResizeObserver(measure);
     resizeObserver.observe(doc.documentElement);
     if (doc.body)
         resizeObserver.observe(doc.body);
     win.addEventListener('message', handleMessage);
+    win.addEventListener('resize', syncSelectionHighlight);
+    win.addEventListener('scroll', syncSelectionHighlight, true);
     doc.addEventListener('click', handleClick, true);
     doc.addEventListener('mousemove', handleMouseMove, true);
+    doc.addEventListener('wheel', handleWheel, { capture: true, passive: false });
     for (const type of SUPPRESSED_EVENTS) {
         doc.addEventListener(type, suppress, true);
     }
@@ -215,20 +323,26 @@ export function mountFrameBridge(options) {
             contractVersion: CONTRACT_VERSION,
             templateName: options.templateName,
             hash: options.hash,
+            capabilities: options.capabilities ?? [],
         },
     });
     measure();
     return {
         unmount: () => {
             win.removeEventListener('message', handleMessage);
+            win.removeEventListener('resize', syncSelectionHighlight);
+            win.removeEventListener('scroll', syncSelectionHighlight, true);
             doc.removeEventListener('click', handleClick, true);
             doc.removeEventListener('mousemove', handleMouseMove, true);
+            doc.removeEventListener('wheel', handleWheel, true);
             for (const type of SUPPRESSED_EVENTS) {
                 doc.removeEventListener(type, suppress, true);
             }
             resizeObserver.disconnect();
-            setUnique(DATA_SELECTED_ATTR, null);
+            selectionResizeObserver.disconnect();
+            setSelection(null);
             setUnique(DATA_HOVERED_ATTR, null);
+            selectionHighlight.remove();
         },
         notifySynced: (hash) => {
             post({ type: 'template:synced', payload: { hash } });

package/dist/editor/host.d.ts

@@ -5,7 +5,7 @@
  * when the iframe reloads (sandbox HMR hard-refresh, crash recovery),
  * and exposes typed send/subscribe surfaces.
  */
-import { type Device, type FrameMessage, type HostMessage } from '../schemas/index.ts';
+import { type Device, type EditorCapability, type FrameMessage, type HostMessage } from '../schemas/index.ts';
 export interface HostBridgeOptions {
     iframe: HTMLIFrameElement;
     /** Origin the preview is served from (the sandbox preview URL). */
@@ -16,6 +16,10 @@ export interface HostBridgeOptions {
     onMessage?: (message: FrameMessage) => void;
     /** Called when the frame speaks an incompatible contract version. */
     onIncompatible?: (frameVersion: string) => void;
+    /** Capabilities that must be present before the frame becomes writable. */
+    requiredCapabilities?: EditorCapability[];
+    /** Called with the required capabilities missing from bridge:ready. */
+    onMissingCapabilities?: (capabilities: EditorCapability[]) => void;
     /** Overrides for tests / non-browser hosts. */
     window?: Window;
 }

package/dist/editor/host.js

@@ -38,6 +38,13 @@ export function createHostBridge(options) {
         }
         const message = data;
         if (message.type === 'bridge:ready') {
+            const offered = new Set(message.payload.capabilities ?? []);
+            const missing = (options.requiredCapabilities ?? []).filter((capability) => !offered.has(capability));
+            if (missing.length) {
+                ready = false;
+                options.onMissingCapabilities?.(missing);
+                return;
+            }
             // First load and every iframe reload land here: (re)init.
             ready = true;
             post({

package/dist/react/engine/CssVariables.js

@@ -10,6 +10,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  */
 import { useMemo } from 'react';
 import { colorSchemes, themeSettings } from './settings';
+import { getThemeStoreVersion } from './store';
 import { googleFontsHrefsFromSettings, parseFontHandle, } from "../../commerce/google-fonts.js";
 function buildCss() {
     const s = themeSettings;
@@ -106,7 +107,8 @@ const FONT_CSS_LOADER = [
     '})(l[i])}',
 ].join('');
 export function CssVariables({ nonce, fonts, } = {}) {
-    const { css, links } = useMemo(() => ({ css: buildCss(), links: googleFontsHrefs() }), []);
+    const themeVersion = getThemeStoreVersion();
+    const { css, links } = useMemo(() => ({ css: buildCss(), links: googleFontsHrefs() }), [themeVersion]);
     // Server-resolved fonts (the next/font pattern): @font-face rules are
     // inlined and the latin woff2 files preloaded, so the font downloads
     // with the HTML and usually beats first paint — no async stylesheet,

package/dist/react/index.d.ts

@@ -13,7 +13,7 @@
  * Server loaders: import {loadSectionData} from '@zalify/storefront-kit/react/server'.
  */
 export * from './engine/types';
-export { installTheme, getTemplate, getSectionGroup, parseThemeJson, } from './engine/store';
+export { installTheme, getTemplate, getSectionGroup, getThemeStoreVersion, parseThemeJson, } from './engine/store';
 export type { ThemeSchema, InstallThemeOptions } from './engine/store';
 export { themeSettings, colorSchemes, getColorScheme } from './engine/settings';
 export { t } from './engine/translate';

package/dist/react/index.js

@@ -14,7 +14,7 @@
  */
 // Engine
 export * from './engine/types';
-export { installTheme, getTemplate, getSectionGroup, parseThemeJson, } from './engine/store';
+export { installTheme, getTemplate, getSectionGroup, getThemeStoreVersion, parseThemeJson, } from './engine/store';
 export { themeSettings, colorSchemes, getColorScheme } from './engine/settings';
 export { t } from './engine/translate';
 export { ThemeTemplate, SectionGroup, RenderSection, RenderSections, } from './engine/render';

package/dist/schemas/bridge.d.ts

@@ -6,7 +6,7 @@
  * Both sides validate `event.origin` and the message envelope before
  * acting; versions negotiate on CONTRACT_VERSION's major component.
  */
-import type { SectionGroupData, SettingsBag, TemplateData } from './data.ts';
+import type { SectionGroupData, SettingsData, TemplateData } from './data.ts';
 import type { ThemeEditorManifest } from './manifest.ts';
 export declare const BRIDGE_NAMESPACE = "zalify-editor-bridge";
 /** Query param that switches a theme preview into editor mode. */
@@ -16,6 +16,35 @@ 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';
+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 {
+    id: string;
+    title: string;
+    url: string;
+    resourceType: PreviewResourceType;
+}
+export interface EditorBootstrap {
+    revision: string;
+    manifest: ThemeEditorManifest;
+    templates: Array<{
+        name: string;
+        writePath: string;
+        data: TemplateData;
+        preview?: PreviewContext;
+    }>;
+    groups: Array<{
+        name: string;
+        writePath: string;
+        data: SectionGroupData;
+    }>;
+    settings: {
+        writePath: string;
+        schema: ThemeEditorManifest['settingsSchema'];
+        resolvedData: SettingsData;
+    };
+    previewContexts: Partial<Record<'product' | 'collection' | 'page' | 'blog' | 'article', PreviewContext>>;
+}
 export interface DOMRectLike {
     x: number;
     y: number;
@@ -60,14 +89,15 @@ export type HostMessage = BridgeEnvelope<'bridge:init', {
     templateName: string;
     template: TemplateData;
     groups?: Record<string, SectionGroupData>;
-    settingsData?: SettingsBag;
+    settingsData?: SettingsData;
 }> | BridgeEnvelope<'device:set', {
     device: Device;
-}> | BridgeEnvelope<'manifest:request', Record<string, never>>;
+}> | BridgeEnvelope<'manifest:request', Record<string, never>> | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;
 export type FrameMessage = BridgeEnvelope<'bridge:ready', {
     contractVersion: string;
     templateName: string;
     hash: string;
+    capabilities: EditorCapability[];
 }> | BridgeEnvelope<'block:clicked', {
     path: string;
     rect: DOMRectLike;
@@ -81,10 +111,18 @@ export type FrameMessage = BridgeEnvelope<'bridge:ready', {
     }>;
 }> | BridgeEnvelope<'manifest:response', {
     manifest: ThemeEditorManifest;
+}> | BridgeEnvelope<'editor:bootstrap:response', {
+    bootstrap: EditorBootstrap;
 }> | BridgeEnvelope<'template:synced', {
     hash: string;
 }> | BridgeEnvelope<'height:changed', {
     height: number;
+}> | BridgeEnvelope<'viewport:wheel', {
+    deltaX: number;
+    deltaY: number;
+    ctrlKey: boolean;
+    clientX: number;
+    clientY: number;
 }> | BridgeEnvelope<'navigation', {
     templateName: string;
     url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "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

@@ -26,10 +26,12 @@ import {
   isCompatibleVersion,
   type Device,
   type DOMRectLike,
+  type EditorBootstrap,
+  type EditorCapability,
   type FrameMessage,
   type HostMessage,
   type SectionGroupData,
-  type SettingsBag,
+  type SettingsData,
   type TemplateData,
   type ThemeEditorManifest,
 } from '../schemas/index.ts';
@@ -45,6 +47,10 @@ export interface FrameBridgeOptions {
   getManifest: () =>
     | ThemeEditorManifest
     | Promise<ThemeEditorManifest>;
+  /** Capabilities supported by this deployed storefront runtime. */
+  capabilities?: EditorCapability[];
+  /** Serve the complete Site Editor bootstrap payload. */
+  getBootstrap?: () => EditorBootstrap | Promise<EditorBootstrap>;
   /**
    * Hot-apply an updated template in memory (optimistic edit). Return
    * false (or throw) if the app cannot apply without a reload.
@@ -53,7 +59,7 @@ export interface FrameBridgeOptions {
     templateName: string;
     template: TemplateData;
     groups?: Record<string, SectionGroupData>;
-    settingsData?: SettingsBag;
+    settingsData?: SettingsData;
   }) => boolean | Promise<boolean>;
   onDeviceChange?: (device: Device) => void;
   /** Overrides for tests / non-browser hosts. */
@@ -77,6 +83,22 @@ function rectOf(element: Element): DOMRectLike {
   return {x: rect.x, y: rect.y, width: rect.width, height: rect.height};
 }
 
+function visibleRectOf(element: Element): DOMRectLike | null {
+  const ownRect = rectOf(element);
+  if (ownRect.width > 0 && ownRect.height > 0) return ownRect;
+
+  const childRects = [...element.children]
+    .map(rectOf)
+    .filter((rect) => rect.width > 0 && rect.height > 0);
+  if (childRects.length === 0) return null;
+
+  const left = Math.min(...childRects.map((rect) => rect.x));
+  const top = Math.min(...childRects.map((rect) => rect.y));
+  const right = Math.max(...childRects.map((rect) => rect.x + rect.width));
+  const bottom = Math.max(...childRects.map((rect) => rect.y + rect.height));
+  return {x: left, y: top, width: right - left, height: bottom - top};
+}
+
 function pathNodeOf(target: EventTarget | null): HTMLElement | null {
   if (!(target instanceof Element)) return null;
   return target.closest<HTMLElement>(`[${DATA_PATH_ATTR}]`);
@@ -103,6 +125,20 @@ export function mountFrameBridge(
   const doc = win.document;
   let editorOrigin: string | null = null;
   let lastHeight = 0;
+  let selectedPath: string | null = null;
+
+  const selectionHighlight = doc.createElement('div');
+  selectionHighlight.id = 'zalify-editor-highlight';
+  selectionHighlight.setAttribute('aria-hidden', 'true');
+  Object.assign(selectionHighlight.style, {
+    position: 'fixed',
+    display: 'none',
+    pointerEvents: 'none',
+    boxSizing: 'border-box',
+    border: '2px solid #2563eb',
+    zIndex: '2147483647',
+  });
+  (doc.body ?? doc.documentElement).append(selectionHighlight);
 
   const post = (message: Omit<FrameMessage, 'z' | 'v'>): void => {
     // bridge:ready is the only pre-pin message; everything else waits.
@@ -123,6 +159,47 @@ export function mountFrameBridge(
     doc.querySelector(selector)?.setAttribute(attr, '1');
   };
 
+  const syncSelectionHighlight = (): void => {
+    if (selectedPath === null) {
+      selectionHighlight.style.display = 'none';
+      return;
+    }
+    const selector = `[${DATA_PATH_ATTR}="${CSS.escape(selectedPath)}"]`;
+    const node = doc.querySelector(selector);
+    const rect = node ? visibleRectOf(node) : null;
+    if (!rect) {
+      selectionHighlight.style.display = 'none';
+      return;
+    }
+    Object.assign(selectionHighlight.style, {
+      display: 'block',
+      left: `${rect.x}px`,
+      top: `${rect.y}px`,
+      width: `${rect.width}px`,
+      height: `${rect.height}px`,
+    });
+  };
+
+  const selectionResizeObserver = new win.ResizeObserver(
+    syncSelectionHighlight,
+  );
+  const setSelection = (path: string | null): void => {
+    setUnique(DATA_SELECTED_ATTR, path);
+    selectedPath = path;
+    selectionResizeObserver.disconnect();
+    if (path !== null) {
+      const selector = `[${DATA_PATH_ATTR}="${CSS.escape(path)}"]`;
+      const node = doc.querySelector(selector);
+      if (node) {
+        selectionResizeObserver.observe(node);
+        for (const child of node.children) {
+          selectionResizeObserver.observe(child);
+        }
+      }
+    }
+    syncSelectionHighlight();
+  };
+
   const reportRects = (): void => {
     const rects = [...doc.querySelectorAll(`[${DATA_PATH_ATTR}]`)].map(
       (node) => ({
@@ -155,11 +232,18 @@ export function mountFrameBridge(
           editorOrigin = event.origin;
         }
         options.onDeviceChange?.(message.payload.device);
-        setUnique(DATA_SELECTED_ATTR, message.payload.selectedPath);
+        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
+        // invalidate the cached value and publish it now.
+        queueMicrotask(() => {
+          lastHeight = 0;
+          measure();
+        });
         break;
       }
       case 'block:select':
-        setUnique(DATA_SELECTED_ATTR, message.payload.path);
+        setSelection(message.payload.path);
         // Rects let the host scroll its full-height canvas to the
         // selection (the frame itself has no scrollbar in that mode).
         reportRects();
@@ -208,6 +292,21 @@ export function mountFrameBridge(
         post({type: 'manifest:response', payload: {manifest}});
         break;
       }
+      case 'editor:bootstrap:request': {
+        if (!options.getBootstrap) {
+          post({
+            type: 'bridge:error',
+            payload: {
+              code: 'bootstrap-unsupported',
+              message: 'frame cannot provide Site Editor bootstrap data',
+            },
+          });
+          break;
+        }
+        const bootstrap = await options.getBootstrap();
+        post({type: 'editor:bootstrap:response', payload: {bootstrap}});
+        break;
+      }
     }
   };
 
@@ -218,10 +317,27 @@ export function mountFrameBridge(
     event.stopPropagation();
     if (!node) return;
     const path = node.getAttribute(DATA_PATH_ATTR)!;
-    setUnique(DATA_SELECTED_ATTR, path);
+    setSelection(path);
     post({type: 'block:clicked', payload: {path, rect: rectOf(node)}});
   };
 
+  const handleWheel = (event: WheelEvent): void => {
+    // Both previews are fixed device viewports. Let ordinary wheel gestures
+    // scroll the storefront; pinch/Ctrl+wheel remains a canvas zoom gesture.
+    if (!event.ctrlKey) return;
+    event.preventDefault();
+    post({
+      type: 'viewport:wheel',
+      payload: {
+        deltaX: event.deltaX,
+        deltaY: event.deltaY,
+        ctrlKey: event.ctrlKey,
+        clientX: event.clientX,
+        clientY: event.clientY,
+      },
+    });
+  };
+
   /** Suppress the page's own interactivity (capture phase, doc root). */
   const suppress = (event: Event): void => {
     event.preventDefault();
@@ -249,7 +365,7 @@ export function mountFrameBridge(
     };
   })();
 
-  const measure = (): void => {
+  function measure(): void {
     // documentElement.scrollHeight never drops below the viewport, so a
     // full-height host iframe would ratchet upward forever; the body's
     // border box tracks actual content in both directions.
@@ -259,15 +375,19 @@ export function mountFrameBridge(
     );
     if (height === lastHeight || height <= 0) return;
     lastHeight = height;
+    syncSelectionHighlight();
     post({type: 'height:changed', payload: {height}});
-  };
+  }
   const resizeObserver = new win.ResizeObserver(measure);
   resizeObserver.observe(doc.documentElement);
   if (doc.body) resizeObserver.observe(doc.body);
 
   win.addEventListener('message', handleMessage);
+  win.addEventListener('resize', syncSelectionHighlight);
+  win.addEventListener('scroll', syncSelectionHighlight, true);
   doc.addEventListener('click', handleClick, true);
   doc.addEventListener('mousemove', handleMouseMove, true);
+  doc.addEventListener('wheel', handleWheel, {capture: true, passive: false});
   for (const type of SUPPRESSED_EVENTS) {
     doc.addEventListener(type, suppress, true);
   }
@@ -278,6 +398,7 @@ export function mountFrameBridge(
       contractVersion: CONTRACT_VERSION,
       templateName: options.templateName,
       hash: options.hash,
+      capabilities: options.capabilities ?? [],
     },
   });
   measure();
@@ -285,14 +406,19 @@ export function mountFrameBridge(
   return {
     unmount: () => {
       win.removeEventListener('message', handleMessage);
+      win.removeEventListener('resize', syncSelectionHighlight);
+      win.removeEventListener('scroll', syncSelectionHighlight, true);
       doc.removeEventListener('click', handleClick, true);
       doc.removeEventListener('mousemove', handleMouseMove, true);
+      doc.removeEventListener('wheel', handleWheel, true);
       for (const type of SUPPRESSED_EVENTS) {
         doc.removeEventListener(type, suppress, true);
       }
       resizeObserver.disconnect();
-      setUnique(DATA_SELECTED_ATTR, null);
+      selectionResizeObserver.disconnect();
+      setSelection(null);
       setUnique(DATA_HOVERED_ATTR, null);
+      selectionHighlight.remove();
     },
     notifySynced: (hash) => {
       post({type: 'template:synced', payload: {hash}});

package/src/editor/host.ts

@@ -12,6 +12,7 @@ import {
   isBridgeMessage,
   isCompatibleVersion,
   type Device,
+  type EditorCapability,
   type FrameMessage,
   type HostMessage,
 } from '../schemas/index.ts';
@@ -26,6 +27,10 @@ export interface HostBridgeOptions {
   onMessage?: (message: FrameMessage) => void;
   /** Called when the frame speaks an incompatible contract version. */
   onIncompatible?: (frameVersion: string) => void;
+  /** Capabilities that must be present before the frame becomes writable. */
+  requiredCapabilities?: EditorCapability[];
+  /** Called with the required capabilities missing from bridge:ready. */
+  onMissingCapabilities?: (capabilities: EditorCapability[]) => void;
   /** Overrides for tests / non-browser hosts. */
   window?: Window;
 }
@@ -71,6 +76,15 @@ export function createHostBridge(options: HostBridgeOptions): HostBridge {
     }
     const message = data as FrameMessage;
     if (message.type === 'bridge:ready') {
+      const offered = new Set(message.payload.capabilities ?? []);
+      const missing = (options.requiredCapabilities ?? []).filter(
+        (capability) => !offered.has(capability),
+      );
+      if (missing.length) {
+        ready = false;
+        options.onMissingCapabilities?.(missing);
+        return;
+      }
       // First load and every iframe reload land here: (re)init.
       ready = true;
       post({

package/src/react/engine/CssVariables.tsx

@@ -9,6 +9,7 @@
  */
 import {useMemo} from 'react';
 import {colorSchemes, themeSettings} from './settings';
+import {getThemeStoreVersion} from './store';
 import {
   googleFontsHrefsFromSettings,
   parseFontHandle,
@@ -136,9 +137,10 @@ export function CssVariables({
   nonce,
   fonts,
 }: {nonce?: string; fonts?: ResolvedGoogleFontCss | null} = {}) {
+  const themeVersion = getThemeStoreVersion();
   const {css, links} = useMemo(
     () => ({css: buildCss(), links: googleFontsHrefs()}),
-    [],
+    [themeVersion],
   );
 
   // Server-resolved fonts (the next/font pattern): @font-face rules are

package/src/react/index.ts

@@ -19,6 +19,7 @@ export {
   installTheme,
   getTemplate,
   getSectionGroup,
+  getThemeStoreVersion,
   parseThemeJson,
 } from './engine/store';
 export type {ThemeSchema, InstallThemeOptions} from './engine/store';

package/src/schemas/bridge.ts

@@ -6,7 +6,11 @@
  * Both sides validate `event.origin` and the message envelope before
  * acting; versions negotiate on CONTRACT_VERSION's major component.
  */
-import type {SectionGroupData, SettingsBag, TemplateData} from './data.ts';
+import type {
+  SectionGroupData,
+  SettingsData,
+  TemplateData,
+} from './data.ts';
 import type {ThemeEditorManifest} from './manifest.ts';
 
 export const BRIDGE_NAMESPACE = 'zalify-editor-bridge';
@@ -21,6 +25,56 @@ export const DATA_SELECTED_ATTR = 'data-z-selected';
 
 export type Device = 'desktop' | 'mobile';
 
+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 {
+  id: string;
+  title: string;
+  url: string;
+  resourceType: PreviewResourceType;
+}
+
+export interface EditorBootstrap {
+  revision: string;
+  manifest: ThemeEditorManifest;
+  templates: Array<{
+    name: string;
+    writePath: string;
+    data: TemplateData;
+    preview?: PreviewContext;
+  }>;
+  groups: Array<{
+    name: string;
+    writePath: string;
+    data: SectionGroupData;
+  }>;
+  settings: {
+    writePath: string;
+    schema: ThemeEditorManifest['settingsSchema'];
+    resolvedData: SettingsData;
+  };
+  previewContexts: Partial<
+    Record<'product' | 'collection' | 'page' | 'blog' | 'article', PreviewContext>
+  >;
+}
+
 export interface DOMRectLike {
   x: number;
   y: number;
@@ -96,18 +150,24 @@ export type HostMessage =
         templateName: string;
         template: TemplateData;
         groups?: Record<string, SectionGroupData>;
-        settingsData?: SettingsBag;
+        settingsData?: SettingsData;
       }
     >
   | BridgeEnvelope<'device:set', {device: Device}>
-  | BridgeEnvelope<'manifest:request', Record<string, never>>;
+  | BridgeEnvelope<'manifest:request', Record<string, never>>
+  | BridgeEnvelope<'editor:bootstrap:request', Record<string, never>>;
 
 /* ------------------------- frame -> host ---------------------------- */
 
 export type FrameMessage =
   | BridgeEnvelope<
       'bridge:ready',
-      {contractVersion: string; templateName: string; hash: string}
+      {
+        contractVersion: string;
+        templateName: string;
+        hash: string;
+        capabilities: EditorCapability[];
+      }
     >
   | BridgeEnvelope<'block:clicked', {path: string; rect: DOMRectLike}>
   | BridgeEnvelope<'block:hovered', {path: string | null; rect?: DOMRectLike}>
@@ -116,8 +176,19 @@ export type FrameMessage =
       {rects: Array<{path: string; rect: DOMRectLike}>}
     >
   | BridgeEnvelope<'manifest:response', {manifest: ThemeEditorManifest}>
+  | BridgeEnvelope<'editor:bootstrap:response', {bootstrap: EditorBootstrap}>
   | BridgeEnvelope<'template:synced', {hash: string}>
   | BridgeEnvelope<'height:changed', {height: number}>
+  | BridgeEnvelope<
+      'viewport:wheel',
+      {
+        deltaX: number;
+        deltaY: number;
+        ctrlKey: boolean;
+        clientX: number;
+        clientY: number;
+      }
+    >
   | BridgeEnvelope<'navigation', {templateName: string; url: string}>
   | BridgeEnvelope<'bridge:error', {code: string; message: string}>;