@zalify/storefront-kit 0.1.13 → 0.2.0

package/dist/editor/bootstrap.d.ts

@@ -0,0 +1,15 @@
+import type { EditorBootstrap, PreviewContext } from '../schemas/bridge.ts';
+import type { ThemeEditorManifest } from '../schemas/manifest.ts';
+import type { DraftSchema } from './draft.ts';
+export interface EditorDocuments {
+    templates: string;
+    groups: string;
+    settings: string;
+}
+/** Only list routes the app can actually render; never fabricate handles. */
+export declare function createEditorBootstrap(options: {
+    schema: DraftSchema;
+    manifest: ThemeEditorManifest;
+    paths: EditorDocuments;
+    previews: Record<string, PreviewContext>;
+}): EditorBootstrap;

package/dist/editor/bootstrap.js

@@ -0,0 +1,42 @@
+/** Only list routes the app can actually render; never fabricate handles. */
+export function createEditorBootstrap(options) {
+    const { schema, manifest, paths, previews } = options;
+    for (const path of [paths.templates, paths.groups, paths.settings]) {
+        if (!path ||
+            path.startsWith('/') ||
+            path.includes('\\') ||
+            path.split('/').some((p) => p === '..' || p === '.')) {
+            throw new Error('Editor write paths must be repository-relative');
+        }
+    }
+    const templates = {
+        ...schema.templates,
+        ...Object.fromEntries(Object.entries(schema.customerTemplates ?? {}).map(([name, data]) => [
+            `customers/${name}`,
+            data,
+        ])),
+    };
+    return {
+        revision: manifest.hash,
+        manifest,
+        templates: Object.entries(templates)
+            .filter(([name]) => previews[name])
+            .map(([name, data]) => ({
+            name,
+            data: structuredClone(data),
+            writePath: `${paths.templates}/${name}.json`,
+            preview: previews[name],
+        })),
+        groups: Object.entries(schema.sectionGroups).map(([name, data]) => ({
+            name,
+            data: structuredClone(data),
+            writePath: `${paths.groups}/${name}.json`,
+        })),
+        settings: {
+            writePath: paths.settings,
+            schema: manifest.settingsSchema,
+            resolvedData: structuredClone(schema.settingsData),
+        },
+        previewContexts: {},
+    };
+}

package/dist/editor/draft.d.ts

@@ -0,0 +1,17 @@
+import type { SectionGroupData, SettingsData, TemplateData } from '../schemas/data.ts';
+export interface DraftSchema {
+    templates: Record<string, TemplateData>;
+    customerTemplates?: Record<string, TemplateData>;
+    sectionGroups: Record<string, SectionGroupData>;
+    settingsData: SettingsData;
+}
+export interface PreviewApply {
+    templateName: string;
+    template: TemplateData;
+    groups?: Record<string, SectionGroupData>;
+    settingsData?: SettingsData;
+}
+/** Immutable, per-preview data. Never writes into an installed source schema. */
+export declare function createEditorDraft(source: DraftSchema): {
+    apply(payload: PreviewApply): DraftSchema;
+};

package/dist/editor/draft.js

@@ -0,0 +1,32 @@
+/** Immutable, per-preview data. Never writes into an installed source schema. */
+export function createEditorDraft(source) {
+    let current = structuredClone(source);
+    return {
+        apply(payload) {
+            const template = structuredClone(payload.template);
+            const customer = payload.templateName.startsWith('customers/');
+            current = {
+                ...current,
+                ...(customer
+                    ? {
+                        customerTemplates: {
+                            ...current.customerTemplates,
+                            [payload.templateName.slice(10)]: template,
+                        },
+                    }
+                    : {
+                        templates: {
+                            ...current.templates,
+                            [payload.templateName]: template,
+                        },
+                    }),
+                sectionGroups: {
+                    ...current.sectionGroups,
+                    ...structuredClone(payload.groups ?? {}),
+                },
+                settingsData: structuredClone(payload.settingsData ?? current.settingsData),
+            };
+            return current;
+        },
+    };
+}

package/dist/editor/frame.js

@@ -254,10 +254,8 @@ export function mountFrameBridge(options) {
         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;
+        // Cross-origin iframe wheel events never reach the host canvas. Forward
+        // wheel gestures so the editor can pan its canvas.
         event.preventDefault();
         post({
             type: 'viewport:wheel',
@@ -265,6 +263,7 @@ export function mountFrameBridge(options) {
                 deltaX: event.deltaX,
                 deltaY: event.deltaY,
                 ctrlKey: event.ctrlKey,
+                shiftKey: event.shiftKey,
                 clientX: event.clientX,
                 clientY: event.clientY,
             },

package/dist/react/engine/CssVariables.js

@@ -8,9 +8,9 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * Static token scales (spacing, type, radii) live in the app's
  * critical.css (synced from the theme).
  */
-import { useMemo } from 'react';
+import { useMemo, useSyncExternalStore } from 'react';
 import { colorSchemes, themeSettings } from './settings';
-import { getThemeStoreVersion } from './store';
+import { getThemeStoreVersion, subscribePreview, getPreviewVersion, getServerPreviewVersion, hasThemePreview, } from './store';
 import { googleFontsHrefsFromSettings, parseFontHandle, } from "../../commerce/google-fonts.js";
 function buildCss() {
     const s = themeSettings;
@@ -107,14 +107,15 @@ const FONT_CSS_LOADER = [
     '})(l[i])}',
 ].join('');
 export function CssVariables({ nonce, fonts, } = {}) {
+    useSyncExternalStore(subscribePreview, getPreviewVersion, getServerPreviewVersion);
     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,
     // no FOUT, no request to fonts.googleapis.com at all.
-    if (fonts) {
+    if (fonts && !hasThemePreview()) {
         return (_jsxs(_Fragment, { children: [_jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), fonts.preloadUrls.map((href) => (_jsx("link", { rel: "preload", as: "font", type: "font/woff2", href: href, crossOrigin: "anonymous" }, href))), _jsx("style", { dangerouslySetInnerHTML: { __html: fonts.css } }), _jsx("style", { dangerouslySetInnerHTML: { __html: css } })] }));
     }
-    return (_jsxs(_Fragment, { children: [_jsx("link", { rel: "preconnect", href: "https://fonts.googleapis.com" }), _jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), links.map((href) => (_jsx("link", { rel: "preload", as: "style", href: href, "data-zfy-font-css": "" }, href))), _jsx("script", { nonce: nonce, dangerouslySetInnerHTML: { __html: FONT_CSS_LOADER } }), _jsx("noscript", { children: links.map((href) => (_jsx("link", { rel: "stylesheet", href: href }, href))) }), _jsx("style", { dangerouslySetInnerHTML: { __html: css } })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("link", { rel: "preconnect", href: "https://fonts.googleapis.com" }), _jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), links.map((href) => (_jsx("link", { rel: hasThemePreview() ? 'stylesheet' : 'preload', as: "style", href: href, "data-zfy-font-css": "" }, href))), _jsx("script", { nonce: nonce, dangerouslySetInnerHTML: { __html: FONT_CSS_LOADER } }), _jsx("noscript", { children: links.map((href) => (_jsx("link", { rel: "stylesheet", href: href }, href))) }), _jsx("style", { dangerouslySetInnerHTML: { __html: css } })] }));
 }

package/dist/react/engine/render.js

@@ -16,7 +16,8 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  * emitted unconditionally so server and client markup stay identical.
  */
 import { formatThemePath, DATA_PATH_ATTR } from "../../schemas/index.js";
-import { getSectionGroup, getTemplate, getThemeStore } from './store';
+import { getSectionGroup, getTemplate, getThemeStore, subscribePreview, getPreviewVersion, getServerPreviewVersion, } from './store';
+import { useSyncExternalStore } from 'react';
 import { SectionProvider, TemplateProvider } from './context';
 const warned = new Set();
 function warnMissing(kind, type) {
@@ -82,6 +83,7 @@ export function ThemeTemplate({ name, resources = {}, sectionData = {}, }) {
 }
 /** Mirror of `{% sections 'header-group' %}` in layout/theme.liquid. */
 export function SectionGroup({ name, sectionData = {}, }) {
+    useSyncExternalStore(subscribePreview, getPreviewVersion, getServerPreviewVersion);
     const group = getSectionGroup(name);
     return (_jsx(TemplateProvider, { value: { name, kind: 'group', resources: {}, sectionData }, children: _jsx(RenderSections, { template: group, scope: { kind: 'group', name } }) }));
 }

package/dist/react/engine/store.d.ts

@@ -49,6 +49,12 @@ export interface InstallThemeOptions {
 }
 interface ThemeStore extends InstallThemeOptions {
 }
+export declare function subscribePreview(listener: () => void): () => void;
+export declare function getPreviewVersion(): number;
+export declare function getServerPreviewVersion(): number;
+export declare function hasThemePreview(): boolean;
+/** Browser-only overlay; the installed schema and SSR state remain untouched. */
+export declare function setThemePreview(owner: ThemeStore, schema: ThemeSchema | null): void;
 export declare function installTheme(options: InstallThemeOptions): void;
 /** Monotonic install counter — lets derived caches detect re-installs. */
 export declare function getThemeStoreVersion(): number;

package/dist/react/engine/store.js

@@ -1,5 +1,34 @@
 let store = null;
 let version = 0;
+let preview = null;
+let previewVersion = 0;
+const previewListeners = new Set();
+export function subscribePreview(listener) {
+    previewListeners.add(listener);
+    return () => {
+        previewListeners.delete(listener);
+    };
+}
+export function getPreviewVersion() {
+    return previewVersion;
+}
+export function getServerPreviewVersion() {
+    return 0;
+}
+export function hasThemePreview() {
+    return (typeof window !== 'undefined' && preview !== null && preview.owner === store);
+}
+/** Browser-only overlay; the installed schema and SSR state remain untouched. */
+export function setThemePreview(owner, schema) {
+    if (typeof window === 'undefined' || owner !== store)
+        return;
+    preview = schema
+        ? { owner, value: { ...owner, schema, settingsOverride: undefined } }
+        : null;
+    previewVersion++;
+    for (const listener of previewListeners)
+        listener();
+}
 export function installTheme(options) {
     store = options;
     // Bump so derived caches (resolved settings) recompute — multi-tenant
@@ -8,14 +37,16 @@ export function installTheme(options) {
 }
 /** Monotonic install counter — lets derived caches detect re-installs. */
 export function getThemeStoreVersion() {
-    return version;
+    return version + (typeof window === 'undefined' ? 0 : previewVersion);
 }
 export function getThemeStore() {
     if (!store) {
-        throw new Error('[storefront-kit] installTheme() has not been called. Import your app\'s ' +
+        throw new Error("[storefront-kit] installTheme() has not been called. Import your app's " +
             'theme-setup module (which calls installTheme) before rendering.');
     }
-    return store;
+    return typeof window !== 'undefined' && preview?.owner === store
+        ? preview.value
+        : store;
 }
 /** Look up a page template ("index", "product", "customers/login"…). */
 export function getTemplate(name) {

package/dist/react/useEditorTemplate.d.ts

@@ -1,8 +1,14 @@
 import type { TemplateData } from "../schemas/data";
 import type { ThemeEditorManifest } from "../schemas/manifest";
+import type { PreviewContext } from "../schemas/bridge";
+import type { EditorDocuments } from "../editor/bootstrap";
 type Options = {
     origins: readonly string[];
     loadManifest: () => Promise<ThemeEditorManifest>;
+    /** Authoritative, repository-relative merchant data targets. */
+    paths: EditorDocuments;
+    /** Real route targets keyed by template name. */
+    previews: Record<string, PreviewContext>;
 };
 /** No editor code or schema is fetched outside an explicitly allowed preview. */
 export declare function useEditorTemplate(name: string, options: Options): TemplateData | null;

package/dist/react/useEditorTemplate.js

@@ -1,5 +1,6 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
+import { getThemeStore, setThemePreview } from "./engine/store";
 /** No editor code or schema is fetched outside an explicitly allowed preview. */
 export function useEditorTemplate(name, options) {
     const [draft, setDraft] = useState(null);
@@ -20,18 +21,77 @@ export function useEditorTemplate(name, options) {
         if (!options.origins.includes(parentOrigin))
             return;
         let disposed = false;
-        void Promise.all([import("../editor/frame"), options.loadManifest()])
-            .then(([bridge, manifest]) => {
+        const owner = getThemeStore();
+        void Promise.all([
+            import("../editor/frame"),
+            options.loadManifest(),
+            import("../editor/bootstrap"),
+            import("../editor/draft"),
+        ])
+            .then(([bridge, manifest, bootstrapModule, draftModule]) => {
             if (disposed)
                 return;
+            const settings = owner.schema.settingsData;
+            const current = typeof settings.current === "string"
+                ? (settings.presets?.[settings.current] ?? {})
+                : settings.current;
+            const schema = {
+                ...owner.schema,
+                settingsData: {
+                    ...settings,
+                    current: { ...current, ...owner.settingsOverride },
+                },
+            };
+            const previews = { ...options.previews };
+            // The currently rendered route is also a verified context, including locale.
+            const url = new URL(window.location.href);
+            url.searchParams.delete("zalify-editor");
+            const kind = name.split(".")[0];
+            const resourceType = ([
+                "index",
+                "product",
+                "collection",
+                "page",
+                "blog",
+                "article",
+                "cart",
+                "search",
+                "list-collections",
+                "404",
+            ].includes(kind)
+                ? kind
+                : "page");
+            previews[name] = {
+                ...previews[name],
+                id: name,
+                title: previews[name]?.title ?? name,
+                resourceType,
+                url: url.pathname + url.search,
+            };
+            const bootstrap = bootstrapModule.createEditorBootstrap({
+                schema,
+                manifest,
+                paths: options.paths,
+                previews,
+            });
+            const draft = draftModule.createEditorDraft(schema);
             controller.current = bridge.mountFrameBridge({
                 editorOrigin: parentOrigin,
                 templateName: name,
                 hash: manifest.hash,
                 getManifest: () => manifest,
+                capabilities: [
+                    "editor-bootstrap-v1",
+                    "apply-template-v1",
+                    "apply-groups-v1",
+                    "apply-settings-v1",
+                    "preview-navigation-v1",
+                ],
+                getBootstrap: () => bootstrap,
                 applyTemplate(payload) {
                     if (payload.templateName !== name)
                         return false;
+                    setThemePreview(owner, { ...schema, ...draft.apply(payload) });
                     setDraft({ name, template: payload.template });
                     return true;
                 },
@@ -44,6 +104,7 @@ export function useEditorTemplate(name, options) {
             disposed = true;
             controller.current?.unmount();
             controller.current = null;
+            setThemePreview(owner, null);
         };
     }, [name, options]);
     useEffect(() => {

package/dist/schemas/bridge.d.ts

@@ -121,6 +121,7 @@ export type FrameMessage = BridgeEnvelope<'bridge:ready', {
     deltaX: number;
     deltaY: number;
     ctrlKey: boolean;
+    shiftKey?: boolean;
     clientX: number;
     clientY: number;
 }> | BridgeEnvelope<'navigation', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "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/bootstrap.ts

@@ -0,0 +1,61 @@
+import type {EditorBootstrap, PreviewContext} from '../schemas/bridge.ts';
+import type {ThemeEditorManifest} from '../schemas/manifest.ts';
+import type {DraftSchema} from './draft.ts';
+
+export interface EditorDocuments {
+  templates: string;
+  groups: string;
+  settings: string;
+}
+
+/** Only list routes the app can actually render; never fabricate handles. */
+export function createEditorBootstrap(options: {
+  schema: DraftSchema;
+  manifest: ThemeEditorManifest;
+  paths: EditorDocuments;
+  previews: Record<string, PreviewContext>;
+}): EditorBootstrap {
+  const {schema, manifest, paths, previews} = options;
+  for (const path of [paths.templates, paths.groups, paths.settings]) {
+    if (
+      !path ||
+      path.startsWith('/') ||
+      path.includes('\\') ||
+      path.split('/').some((p) => p === '..' || p === '.')
+    ) {
+      throw new Error('Editor write paths must be repository-relative');
+    }
+  }
+  const templates = {
+    ...schema.templates,
+    ...Object.fromEntries(
+      Object.entries(schema.customerTemplates ?? {}).map(([name, data]) => [
+        `customers/${name}`,
+        data,
+      ]),
+    ),
+  };
+  return {
+    revision: manifest.hash,
+    manifest,
+    templates: Object.entries(templates)
+      .filter(([name]) => previews[name])
+      .map(([name, data]) => ({
+        name,
+        data: structuredClone(data),
+        writePath: `${paths.templates}/${name}.json`,
+        preview: previews[name],
+      })),
+    groups: Object.entries(schema.sectionGroups).map(([name, data]) => ({
+      name,
+      data: structuredClone(data),
+      writePath: `${paths.groups}/${name}.json`,
+    })),
+    settings: {
+      writePath: paths.settings,
+      schema: manifest.settingsSchema,
+      resolvedData: structuredClone(schema.settingsData),
+    },
+    previewContexts: {},
+  };
+}

package/src/editor/draft.ts

@@ -0,0 +1,54 @@
+import type {
+  SectionGroupData,
+  SettingsData,
+  TemplateData,
+} from '../schemas/data.ts';
+
+export interface DraftSchema {
+  templates: Record<string, TemplateData>;
+  customerTemplates?: Record<string, TemplateData>;
+  sectionGroups: Record<string, SectionGroupData>;
+  settingsData: SettingsData;
+}
+
+export interface PreviewApply {
+  templateName: string;
+  template: TemplateData;
+  groups?: Record<string, SectionGroupData>;
+  settingsData?: SettingsData;
+}
+
+/** Immutable, per-preview data. Never writes into an installed source schema. */
+export function createEditorDraft(source: DraftSchema) {
+  let current = structuredClone(source);
+  return {
+    apply(payload: PreviewApply): DraftSchema {
+      const template = structuredClone(payload.template);
+      const customer = payload.templateName.startsWith('customers/');
+      current = {
+        ...current,
+        ...(customer
+          ? {
+              customerTemplates: {
+                ...current.customerTemplates,
+                [payload.templateName.slice(10)]: template,
+              },
+            }
+          : {
+              templates: {
+                ...current.templates,
+                [payload.templateName]: template,
+              },
+            }),
+        sectionGroups: {
+          ...current.sectionGroups,
+          ...structuredClone(payload.groups ?? {}),
+        },
+        settingsData: structuredClone(
+          payload.settingsData ?? current.settingsData,
+        ),
+      };
+      return current;
+    },
+  };
+}

package/src/editor/frame.ts

@@ -326,9 +326,8 @@ export function mountFrameBridge(
   };
 
   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;
+    // Cross-origin iframe wheel events never reach the host canvas. Forward
+    // wheel gestures so the editor can pan its canvas.
     event.preventDefault();
     post({
       type: 'viewport:wheel',
@@ -336,6 +335,7 @@ export function mountFrameBridge(
         deltaX: event.deltaX,
         deltaY: event.deltaY,
         ctrlKey: event.ctrlKey,
+        shiftKey: event.shiftKey,
         clientX: event.clientX,
         clientY: event.clientY,
       },

package/src/react/engine/CssVariables.tsx

@@ -7,9 +7,15 @@
  * Static token scales (spacing, type, radii) live in the app's
  * critical.css (synced from the theme).
  */
-import {useMemo} from 'react';
+import {useMemo, useSyncExternalStore} from 'react';
 import {colorSchemes, themeSettings} from './settings';
-import {getThemeStoreVersion} from './store';
+import {
+  getThemeStoreVersion,
+  subscribePreview,
+  getPreviewVersion,
+  getServerPreviewVersion,
+  hasThemePreview,
+} from './store';
 import {
   googleFontsHrefsFromSettings,
   parseFontHandle,
@@ -35,7 +41,9 @@ function buildCss(): string {
   const lines: string[] = [];
   lines.push(':root {');
   lines.push(`  --font-body--family: ${bodyFamily};`);
-  lines.push(`  --font-body--style: ${bodyGoogle ? 'normal' : bodyFont.style};`);
+  lines.push(
+    `  --font-body--style: ${bodyGoogle ? 'normal' : bodyFont.style};`,
+  );
   lines.push(`  --font-body--weight: ${bodyGoogle ? 400 : bodyFont.weight};`);
   lines.push(`  --font-heading--family: ${headingFamily};`);
   if (monoGoogle) {
@@ -52,15 +60,23 @@ function buildCss(): string {
   }
   lines.push(`  --page-width: ${s.max_page_width ?? '90rem'};`);
   lines.push(`  --page-margin: ${s.min_page_margin ?? 20}px;`);
-  lines.push(`  --style-border-radius-inputs: ${s.input_corner_radius ?? 0}px;`);
-  lines.push(`  --style-border-radius-buttons: ${s.button_corner_radius ?? 0}px;`);
+  lines.push(
+    `  --style-border-radius-inputs: ${s.input_corner_radius ?? 0}px;`,
+  );
+  lines.push(
+    `  --style-border-radius-buttons: ${s.button_corner_radius ?? 0}px;`,
+  );
   lines.push(`  --style-border-radius-cards: ${s.card_corner_radius ?? 0}px;`);
-  lines.push(`  --style-badge-background: ${s.card_badge_background ?? '#F9EDEF'};`);
+  lines.push(
+    `  --style-badge-background: ${s.card_badge_background ?? '#F9EDEF'};`,
+  );
   lines.push(`  --style-badge-text: ${s.card_badge_text ?? '#1A1A1A'};`);
   lines.push(
     `  --style-badge-sale-background: ${s.card_badge_sale_background ?? '#F26B8A'};`,
   );
-  lines.push(`  --style-badge-sale-text: ${s.card_badge_sale_text ?? '#FFFFFF'};`);
+  lines.push(
+    `  --style-badge-sale-text: ${s.card_badge_sale_text ?? '#FFFFFF'};`,
+  );
   lines.push(
     `  --style-badge-1-background: ${s.badge_style_1_background ?? '#1A1A1A'};`,
   );
@@ -137,6 +153,11 @@ export function CssVariables({
   nonce,
   fonts,
 }: {nonce?: string; fonts?: ResolvedGoogleFontCss | null} = {}) {
+  useSyncExternalStore(
+    subscribePreview,
+    getPreviewVersion,
+    getServerPreviewVersion,
+  );
   const themeVersion = getThemeStoreVersion();
   const {css, links} = useMemo(
     () => ({css: buildCss(), links: googleFontsHrefs()}),
@@ -147,7 +168,7 @@ export function CssVariables({
   // inlined and the latin woff2 files preloaded, so the font downloads
   // with the HTML and usually beats first paint — no async stylesheet,
   // no FOUT, no request to fonts.googleapis.com at all.
-  if (fonts) {
+  if (fonts && !hasThemePreview()) {
     return (
       <>
         <link
@@ -182,13 +203,16 @@ export function CssVariables({
       {links.map((href) => (
         <link
           key={href}
-          rel="preload"
+          rel={hasThemePreview() ? 'stylesheet' : 'preload'}
           as="style"
           href={href}
           data-zfy-font-css=""
         />
       ))}
-      <script nonce={nonce} dangerouslySetInnerHTML={{__html: FONT_CSS_LOADER}} />
+      <script
+        nonce={nonce}
+        dangerouslySetInnerHTML={{__html: FONT_CSS_LOADER}}
+      />
       <noscript>
         {links.map((href) => (
           <link key={href} rel="stylesheet" href={href} />

package/src/react/engine/render.tsx

@@ -15,7 +15,15 @@
  * emitted unconditionally so server and client markup stay identical.
  */
 import {formatThemePath, DATA_PATH_ATTR} from '../../schemas/index.ts';
-import {getSectionGroup, getTemplate, getThemeStore} from './store';
+import {
+  getSectionGroup,
+  getTemplate,
+  getThemeStore,
+  subscribePreview,
+  getPreviewVersion,
+  getServerPreviewVersion,
+} from './store';
+import {useSyncExternalStore} from 'react';
 import {SectionProvider, TemplateProvider} from './context';
 import type {BlockData, SectionData, TemplateData} from './types';
 
@@ -181,6 +189,11 @@ export function SectionGroup({
   name: string;
   sectionData?: Record<string, unknown>;
 }) {
+  useSyncExternalStore(
+    subscribePreview,
+    getPreviewVersion,
+    getServerPreviewVersion,
+  );
   const group = getSectionGroup(name);
   return (
     <TemplateProvider value={{name, kind: 'group', resources: {}, sectionData}}>

package/src/react/engine/store.ts

@@ -26,7 +26,10 @@ export interface ThemeSchema {
   /** sections/*-group.json keyed by file name ("header-group"…). */
   sectionGroups: Record<string, SectionGroupData>;
   /** config/settings_schema.json. */
-  settingsSchema: Array<{name: string; settings?: Array<Record<string, unknown>>}>;
+  settingsSchema: Array<{
+    name: string;
+    settings?: Array<Record<string, unknown>>;
+  }>;
   /** config/settings_data.json. */
   settingsData: {
     current: string | Record<string, unknown>;
@@ -57,6 +60,40 @@ interface ThemeStore extends InstallThemeOptions {}
 
 let store: ThemeStore | null = null;
 let version = 0;
+let preview: {owner: ThemeStore; value: ThemeStore} | null = null;
+let previewVersion = 0;
+const previewListeners = new Set<() => void>();
+
+export function subscribePreview(listener: () => void): () => void {
+  previewListeners.add(listener);
+  return () => {
+    previewListeners.delete(listener);
+  };
+}
+export function getPreviewVersion(): number {
+  return previewVersion;
+}
+export function getServerPreviewVersion(): number {
+  return 0;
+}
+export function hasThemePreview(): boolean {
+  return (
+    typeof window !== 'undefined' && preview !== null && preview.owner === store
+  );
+}
+
+/** Browser-only overlay; the installed schema and SSR state remain untouched. */
+export function setThemePreview(
+  owner: ThemeStore,
+  schema: ThemeSchema | null,
+): void {
+  if (typeof window === 'undefined' || owner !== store) return;
+  preview = schema
+    ? {owner, value: {...owner, schema, settingsOverride: undefined}}
+    : null;
+  previewVersion++;
+  for (const listener of previewListeners) listener();
+}
 
 export function installTheme(options: InstallThemeOptions): void {
   store = options;
@@ -67,17 +104,19 @@ export function installTheme(options: InstallThemeOptions): void {
 
 /** Monotonic install counter — lets derived caches detect re-installs. */
 export function getThemeStoreVersion(): number {
-  return version;
+  return version + (typeof window === 'undefined' ? 0 : previewVersion);
 }
 
 export function getThemeStore(): ThemeStore {
   if (!store) {
     throw new Error(
-      '[storefront-kit] installTheme() has not been called. Import your app\'s ' +
+      "[storefront-kit] installTheme() has not been called. Import your app's " +
         'theme-setup module (which calls installTheme) before rendering.',
     );
   }
-  return store;
+  return typeof window !== 'undefined' && preview?.owner === store
+    ? preview.value
+    : store;
 }
 
 /** Look up a page template ("index", "product", "customers/login"…). */

package/src/react/useEditorTemplate.ts

@@ -3,10 +3,17 @@ import { useEffect, useRef, useState } from "react";
 import type { TemplateData } from "../schemas/data";
 import type { ThemeEditorManifest } from "../schemas/manifest";
 import type { FrameBridgeController } from "../editor/frame";
+import type { PreviewContext } from "../schemas/bridge";
+import type { EditorDocuments } from "../editor/bootstrap";
+import { getThemeStore, setThemePreview } from "./engine/store";
 
 type Options = {
   origins: readonly string[];
   loadManifest: () => Promise<ThemeEditorManifest>;
+  /** Authoritative, repository-relative merchant data targets. */
+  paths: EditorDocuments;
+  /** Real route targets keyed by template name. */
+  previews: Record<string, PreviewContext>;
 };
 
 /** No editor code or schema is fetched outside an explicitly allowed preview. */
@@ -35,16 +42,78 @@ export function useEditorTemplate(
     }
     if (!options.origins.includes(parentOrigin)) return;
     let disposed = false;
-    void Promise.all([import("../editor/frame"), options.loadManifest()])
-      .then(([bridge, manifest]) => {
+    const owner = getThemeStore();
+    void Promise.all([
+      import("../editor/frame"),
+      options.loadManifest(),
+      import("../editor/bootstrap"),
+      import("../editor/draft"),
+    ])
+      .then(([bridge, manifest, bootstrapModule, draftModule]) => {
         if (disposed) return;
+        const settings = owner.schema.settingsData;
+        const current =
+          typeof settings.current === "string"
+            ? (settings.presets?.[settings.current] ?? {})
+            : settings.current;
+        const schema = {
+          ...owner.schema,
+          settingsData: {
+            ...settings,
+            current: { ...current, ...owner.settingsOverride },
+          },
+        };
+        const previews = { ...options.previews };
+        // The currently rendered route is also a verified context, including locale.
+        const url = new URL(window.location.href);
+        url.searchParams.delete("zalify-editor");
+        const kind = name.split(".")[0];
+        const resourceType = (
+          [
+            "index",
+            "product",
+            "collection",
+            "page",
+            "blog",
+            "article",
+            "cart",
+            "search",
+            "list-collections",
+            "404",
+          ].includes(kind)
+            ? kind
+            : "page"
+        ) as PreviewContext["resourceType"];
+        previews[name] = {
+          ...previews[name],
+          id: name,
+          title: previews[name]?.title ?? name,
+          resourceType,
+          url: url.pathname + url.search,
+        };
+        const bootstrap = bootstrapModule.createEditorBootstrap({
+          schema,
+          manifest,
+          paths: options.paths,
+          previews,
+        });
+        const draft = draftModule.createEditorDraft(schema);
         controller.current = bridge.mountFrameBridge({
           editorOrigin: parentOrigin,
           templateName: name,
           hash: manifest.hash,
           getManifest: () => manifest,
+          capabilities: [
+            "editor-bootstrap-v1",
+            "apply-template-v1",
+            "apply-groups-v1",
+            "apply-settings-v1",
+            "preview-navigation-v1",
+          ],
+          getBootstrap: () => bootstrap,
           applyTemplate(payload) {
             if (payload.templateName !== name) return false;
+            setThemePreview(owner, { ...schema, ...draft.apply(payload) });
             setDraft({ name, template: payload.template });
             return true;
           },
@@ -57,6 +126,7 @@ export function useEditorTemplate(
       disposed = true;
       controller.current?.unmount();
       controller.current = null;
+      setThemePreview(owner, null);
     };
   }, [name, options]);
   useEffect(() => {

package/src/schemas/bridge.ts

@@ -185,6 +185,7 @@ export type FrameMessage =
         deltaX: number;
         deltaY: number;
         ctrlKey: boolean;
+        shiftKey?: boolean;
         clientX: number;
         clientY: number;
       }