@zalify/storefront-kit 0.3.2 → 0.5.0

package/README.md

@@ -61,3 +61,17 @@ the TypeScript source included (`src/`) for reference and sourcemaps.
 Source-available under the [Zalify Source Available License](./LICENSE.md):
 build, modify, and operate storefronts freely (including for clients);
 don't redistribute the SDK or use it to build competing theme products.
+
+## Agent skills
+
+The storefront ↔ editor contract ships with the package as an agent skill, so
+every storefront repo carries the rules for the kit version it has installed:
+
+```bash
+pnpm exec storefront-kit skills sync    # copy into .agents/skills and .claude/skills
+pnpm exec storefront-kit skills check   # CI: fail when the copies are stale
+```
+
+Run `sync` after every kit upgrade and commit the result. Editor plumbing
+(bootstrap, bridge, editor-mode detection, design-mode flags) belongs in this
+package — a storefront repo holds content and brand only.

package/bin/storefront-kit.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Installs the agent skills that ship with this version of the kit into the
+// storefront repo, so whoever (or whatever) edits the storefront works from
+// the same contract the SDK implements.
+//
+//   storefront-kit skills sync    copy skills into .agents/skills and .claude/skills
+//   storefront-kit skills check   exit 1 when the repo's copies are missing or stale
+import {cpSync, existsSync, readdirSync, readFileSync, rmSync} from 'node:fs';
+import {dirname, join, relative} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+const TARGETS = ['.agents/skills', '.claude/skills'];
+
+function files(dir, base = dir) {
+  return readdirSync(dir, {withFileTypes: true}).flatMap((entry) => {
+    const path = join(dir, entry.name);
+    return entry.isDirectory() ? files(path, base) : [relative(base, path)];
+  });
+}
+
+function stale(root) {
+  const out = [];
+  for (const target of TARGETS) {
+    for (const file of files(source)) {
+      const copy = join(root, target, file);
+      if (
+        !existsSync(copy) ||
+        !readFileSync(copy).equals(readFileSync(join(source, file)))
+      ) {
+        out.push(join(target, file));
+      }
+    }
+  }
+  return out;
+}
+
+const [group, command] = process.argv.slice(2);
+const root = process.cwd();
+
+if (group !== 'skills' || !['sync', 'check'].includes(command)) {
+  console.error('usage: storefront-kit skills <sync|check>');
+  process.exit(2);
+}
+
+if (command === 'check') {
+  const out = stale(root);
+  if (out.length) {
+    console.error(
+      `Kit skills are missing or out of date:\n${out.map((f) => `  ${f}`).join('\n')}\nRun: pnpm exec storefront-kit skills sync`,
+    );
+    process.exit(1);
+  }
+  console.log('Kit skills are up to date.');
+} else {
+  for (const target of TARGETS) {
+    for (const skill of readdirSync(source)) {
+      // Whole-directory replace: a file the kit dropped must not linger.
+      rmSync(join(root, target, skill), {recursive: true, force: true});
+      cpSync(join(source, skill), join(root, target, skill), {recursive: true});
+    }
+  }
+  console.log(
+    `Synced ${readdirSync(source).join(', ')} into ${TARGETS.join(' and ')}.`,
+  );
+}

package/dist/editor/bootstrap.d.ts

@@ -6,6 +6,14 @@ export interface EditorDocuments {
     groups: string;
     settings: string;
 }
+/** Template types the editor can group, icon and offer an entity picker for. */
+export declare const TEMPLATE_TYPES: readonly ["index", "product", "collection", "list-collections", "page", "blog", "article", "cart", "search", "404", "password", "gift_card"];
+/**
+ * What is wrong with a set of template names, for a storefront's own tests:
+ * names must be `<type>` or `<type>.<suffix>`, and a type that has alternates
+ * must also have its default. Empty means the editor can lay them out.
+ */
+export declare function templateNameProblems(names: readonly string[]): string[];
 /** Only list routes the app can actually render; never fabricate handles. */
 export declare function createEditorBootstrap(options: {
     schema: DraftSchema;

package/dist/editor/bootstrap.js

@@ -1,3 +1,43 @@
+/** Template types the editor can group, icon and offer an entity picker for. */
+export const TEMPLATE_TYPES = [
+    'index',
+    'product',
+    'collection',
+    'list-collections',
+    'page',
+    'blog',
+    'article',
+    'cart',
+    'search',
+    '404',
+    'password',
+    'gift_card',
+];
+/**
+ * What is wrong with a set of template names, for a storefront's own tests:
+ * names must be `<type>` or `<type>.<suffix>`, and a type that has alternates
+ * must also have its default. Empty means the editor can lay them out.
+ */
+export function templateNameProblems(names) {
+    const problems = [];
+    const known = new Set(names);
+    const needsDefault = new Set();
+    for (const name of names) {
+        if (name.startsWith('customers/'))
+            continue;
+        const type = name.split('.')[0];
+        if (!TEMPLATE_TYPES.includes(type)) {
+            problems.push(`"${name}": unknown template type "${type}" — use <type>.<suffix>, e.g. "page.${name.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}"`);
+        }
+        else if (name !== type && !known.has(type)) {
+            needsDefault.add(type);
+        }
+    }
+    for (const type of needsDefault) {
+        problems.push(`"${type}.*" alternates exist but the default "${type}" template is not registered`);
+    }
+    return problems;
+}
 /** Only list routes the app can actually render; never fabricate handles. */
 export function createEditorBootstrap(options) {
     const { schema, manifest, paths, previews } = options;

package/dist/editor/selection.d.ts

@@ -0,0 +1,3 @@
+/** Observe the same authenticated parent selection as the SDK. Components can
+ * reveal the selected tab/menu before the SDK measures its DOM node. */
+export declare function mountEditorSelection(win: Window, onSelect: (path: string | null) => void): () => void;

package/dist/editor/selection.js

@@ -0,0 +1,42 @@
+import { BRIDGE_NAMESPACE, CONTRACT_VERSION, isCompatibleVersion, } from "../schemas/index.js";
+/** Observe the same authenticated parent selection as the SDK. Components can
+ * reveal the selected tab/menu before the SDK measures its DOM node. */
+export function mountEditorSelection(win, onSelect) {
+    let origin;
+    const listener = (event) => {
+        if (event.source !== win.parent)
+            return;
+        const data = event.data;
+        if (!data ||
+            data.z !== BRIDGE_NAMESPACE ||
+            typeof data.v !== "string" ||
+            !isCompatibleVersion(CONTRACT_VERSION, data.v) ||
+            !data.payload)
+            return;
+        if (!origin &&
+            data.type === "bridge:init" &&
+            event.origin === data.payload.editorOrigin)
+            origin = event.origin;
+        if (!origin || event.origin !== origin)
+            return;
+        const path = data.type === "bridge:init"
+            ? data.payload.selectedPath
+            : data.type === "block:select"
+                ? data.payload.path
+                : undefined;
+        if (path === null || typeof path === "string")
+            onSelect(path);
+    };
+    const click = (event) => {
+        const target = event.target;
+        const path = target?.closest?.("[data-z-path]")?.getAttribute("data-z-path") ?? null;
+        if (path)
+            onSelect(path);
+    };
+    win.addEventListener("message", listener);
+    win.document.addEventListener("click", click, true);
+    return () => {
+        win.removeEventListener("message", listener);
+        win.document.removeEventListener("click", click, true);
+    };
+}

package/dist/editor/visible-paths.d.ts

@@ -0,0 +1,6 @@
+/** The SDK selects the first matching path. Responsive copies must not let a
+ * hidden desktop node shadow its visible mobile counterpart (or vice versa). */
+export declare function syncVisiblePaths(doc: Document): void;
+export declare function restoreHiddenPaths(doc: Document): void;
+/** Mounted only in the editor, before the SDK's message/resize listeners. */
+export declare function mountVisiblePaths(win: Window, onChange: () => void): () => void;

package/dist/editor/visible-paths.js

@@ -0,0 +1,88 @@
+const PATH = "data-z-path";
+const HIDDEN_PATH = "data-z-editor-hidden-path";
+/** The SDK selects the first matching path. Responsive copies must not let a
+ * hidden desktop node shadow its visible mobile counterpart (or vice versa). */
+export function syncVisiblePaths(doc) {
+    for (const node of doc.querySelectorAll(`[${PATH}], [${HIDDEN_PATH}]`)) {
+        const path = node.getAttribute(PATH) ?? node.getAttribute(HIDDEN_PATH);
+        if (!path)
+            continue;
+        // display:contents has no own box; a visible child still makes it selectable.
+        const visible = node.getClientRects().length > 0 ||
+            Array.from(node.children).some((child) => child.getClientRects().length > 0);
+        if (visible) {
+            if (node.getAttribute(PATH) !== path)
+                node.setAttribute(PATH, path);
+            if (node.getAttribute(HIDDEN_PATH) !== null)
+                node.removeAttribute(HIDDEN_PATH);
+        }
+        else {
+            if (node.getAttribute(HIDDEN_PATH) !== path)
+                node.setAttribute(HIDDEN_PATH, path);
+            if (node.getAttribute(PATH) !== null)
+                node.removeAttribute(PATH);
+        }
+    }
+}
+export function restoreHiddenPaths(doc) {
+    for (const node of doc.querySelectorAll(`[${HIDDEN_PATH}]`)) {
+        const path = node.getAttribute(HIDDEN_PATH);
+        if (path && !node.hasAttribute(PATH))
+            node.setAttribute(PATH, path);
+        node.removeAttribute(HIDDEN_PATH);
+    }
+}
+/** Mounted only in the editor, before the SDK's message/resize listeners. */
+export function mountVisiblePaths(win, onChange) {
+    let frame = 0;
+    const sync = () => syncVisiblePaths(win.document);
+    const schedule = () => {
+        if (frame)
+            return;
+        frame = win.requestAnimationFrame(() => {
+            frame = 0;
+            sync();
+            onChange();
+        });
+    };
+    // Transform/opacity animations do not change which responsive copy has a box.
+    // Scanning every path for each animation frame makes long previews expensive.
+    const boxStyle = (style) => ["display", "content-visibility"]
+        .map((property) => new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([^;]+)`, "i")
+        .exec(style ?? "")?.[1]
+        .trim() ?? "")
+        .join("|");
+    const observer = new MutationObserver((records) => {
+        if (records.some((record) => {
+            const target = record.target;
+            if (target.id === "zalify-editor-highlight")
+                return false;
+            if (record.type === "attributes" && record.attributeName === "style")
+                return (boxStyle(record.oldValue) !== boxStyle(target.getAttribute("style")));
+            return true;
+        }))
+            schedule();
+    });
+    observer.observe(win.document.documentElement, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeOldValue: true,
+        attributeFilter: [PATH, "class", "style", "hidden"],
+    });
+    const onMessage = (event) => {
+        if (event.data?.z === "zalify-editor-bridge" &&
+            ["bridge:init", "block:select", "device:set", "template:apply"].includes(event.data.type))
+            sync();
+    };
+    win.addEventListener("resize", sync);
+    win.addEventListener("message", onMessage);
+    sync();
+    return () => {
+        observer.disconnect();
+        win.cancelAnimationFrame(frame);
+        win.removeEventListener("resize", sync);
+        win.removeEventListener("message", onMessage);
+        restoreHiddenPaths(win.document);
+    };
+}

package/dist/react/design-mode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Design mode is the SDK's to declare, not each storefront's: the editor
+ * sizes the iframe to its content, so `100vh` inside it grows with every
+ * height report. Themes read `--editor-viewport-height` under
+ * `html[data-z-design-mode='1']` instead. Fixed per mount on purpose.
+ */
+export declare function enterDesignMode(): () => void;

package/dist/react/design-mode.js

@@ -0,0 +1,17 @@
+/** Cap for `--editor-viewport-height`: a tall editor pane is not a tall phone. */
+const MAX_EDITOR_VIEWPORT_HEIGHT = 1000;
+/**
+ * Design mode is the SDK's to declare, not each storefront's: the editor
+ * sizes the iframe to its content, so `100vh` inside it grows with every
+ * height report. Themes read `--editor-viewport-height` under
+ * `html[data-z-design-mode='1']` instead. Fixed per mount on purpose.
+ */
+export function enterDesignMode() {
+    const root = document.documentElement;
+    root.style.setProperty("--editor-viewport-height", `${Math.min(window.innerHeight, MAX_EDITOR_VIEWPORT_HEIGHT)}px`);
+    root.setAttribute("data-z-design-mode", "1");
+    return () => {
+        root.removeAttribute("data-z-design-mode");
+        root.style.removeProperty("--editor-viewport-height");
+    };
+}

package/dist/react/editor-origin.d.ts

@@ -1 +1,3 @@
+/** Editors allowed to frame a storefront unless the app narrows the list. */
+export declare const ZALIFY_EDITOR_ORIGINS: readonly string[];
 export declare function resolveEditorOrigin(origins: readonly string[], win?: Window): string | null;

package/dist/react/editor-origin.js

@@ -9,6 +9,11 @@
  * still present — always checked against the allowlist, never trusted bare.
  */
 const STORAGE_KEY = "zalify-editor-origin";
+/** Editors allowed to frame a storefront unless the app narrows the list. */
+export const ZALIFY_EDITOR_ORIGINS = [
+    "https://app.zalify.com",
+    "http://localhost:3000",
+];
 export function resolveEditorOrigin(origins, win = window) {
     if (!origins.length || win.self === win.top)
         return null;

package/dist/react/index.d.ts

@@ -36,5 +36,5 @@ export { ProductCard, PRODUCT_CARD_FRAGMENT } from './components/ProductCard';
 export * from './components/VideoModal';
 export { Facets, COLLECTION_SORT_OPTIONS, SEARCH_SORT_OPTIONS, } from './components/Facets';
 export { builtinSections, builtinBlocks } from './registries';
-export { useEditorTemplate } from './useEditorTemplate';
+export { useEditorTemplate, ZALIFY_EDITOR_ORIGINS, } from './useEditorTemplate';
 export { resolveEditorOrigin } from './editor-origin';

package/dist/react/index.js

@@ -37,5 +37,5 @@ export { Facets, COLLECTION_SORT_OPTIONS, SEARCH_SORT_OPTIONS, } from './compone
 // Built-in registries (spread into installTheme with app extras).
 // Server-only loaders live in '@zalify/storefront-kit/react/server'.
 export { builtinSections, builtinBlocks } from './registries';
-export { useEditorTemplate } from './useEditorTemplate';
+export { useEditorTemplate, ZALIFY_EDITOR_ORIGINS, } from './useEditorTemplate';
 export { resolveEditorOrigin } from './editor-origin';

package/dist/react/server-preview.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Editor preview for storefronts that render templates on the server (React
+ * Server Components) instead of through the client theme engine.
+ *
+ * The app supplies two server functions — one returning its bootstrap, one
+ * rendering a draft template to React nodes — and wraps each editable region.
+ * Everything else (trust, bridge, design mode, selection, responsive-copy
+ * paths, error surface) is here, so a storefront repo never writes it again.
+ *
+ *   <EditorPreviewProvider getBootstrap={…} renderTemplate={…}>
+ *     <EditorGroupRegion name="header-group">…</EditorGroupRegion>
+ *     <EditorTemplateRegion name="page.about">…</EditorTemplateRegion>
+ *   </EditorPreviewProvider>
+ */
+import { type ReactNode } from "react";
+import type { EditorBootstrap } from "../schemas/bridge";
+import type { SectionGroupData, SettingsData, TemplateData } from "../schemas/data";
+export interface RenderTemplateInput {
+    templateName: string;
+    template: TemplateData;
+    groups?: Record<string, SectionGroupData>;
+    /** Path + query of the page being previewed, without the editor param. */
+    pathname: string;
+}
+/** Keys are `template:<name>` and `group:<name>`. */
+export type RenderedRegions = Record<string, ReactNode>;
+export interface EditorPreviewProviderProps {
+    children: ReactNode;
+    /** Server function: the app's bootstrap (see `createEditorBootstrap`). */
+    getBootstrap: () => Promise<EditorBootstrap>;
+    /** Server function: render a draft. Must be read-only. */
+    renderTemplate: (input: RenderTemplateInput) => Promise<RenderedRegions>;
+    /** Map draft theme settings onto the page (CSS variables, usually). */
+    applySettings?: (settings: SettingsData, root: HTMLElement) => void;
+    /** Defaults to {@link ZALIFY_EDITOR_ORIGINS}. */
+    origins?: readonly string[];
+    /** A render slower than this fails the edit instead of hanging it. */
+    renderTimeoutMs?: number;
+}
+/** No bootstrap payload or bridge code is downloaded by ordinary visitors. */
+export declare function EditorPreviewProvider({ children, getBootstrap, renderTemplate, applySettings, origins, renderTimeoutMs, }: EditorPreviewProviderProps): import("react").JSX.Element;
+/** The page's template. Also tells the provider which template this route is. */
+export declare function EditorTemplateRegion({ name, children, }: {
+    name: string;
+    children: ReactNode;
+}): ReactNode;
+/** A section group (header-group, footer-group). */
+export declare function EditorGroupRegion({ name, children, }: {
+    name: string;
+    children: ReactNode;
+}): ReactNode;
+/** True inside a trusted editor frame, after hydration. */
+export declare function useEditorPreview(): boolean;
+/** The editor's selected `data-z-path`, so a component can reveal it. */
+export declare function useEditorSelection(): string | null;

package/dist/react/server-preview.js

@@ -0,0 +1,216 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Editor preview for storefronts that render templates on the server (React
+ * Server Components) instead of through the client theme engine.
+ *
+ * The app supplies two server functions — one returning its bootstrap, one
+ * rendering a draft template to React nodes — and wraps each editable region.
+ * Everything else (trust, bridge, design mode, selection, responsive-copy
+ * paths, error surface) is here, so a storefront repo never writes it again.
+ *
+ *   <EditorPreviewProvider getBootstrap={…} renderTemplate={…}>
+ *     <EditorGroupRegion name="header-group">…</EditorGroupRegion>
+ *     <EditorTemplateRegion name="page.about">…</EditorTemplateRegion>
+ *   </EditorPreviewProvider>
+ */
+import { createContext, useContext, useEffect, useRef, useState, } from "react";
+import { flushSync } from "react-dom";
+import { enterDesignMode } from "./design-mode";
+import { resolveEditorOrigin, ZALIFY_EDITOR_ORIGINS } from "./editor-origin";
+const PreviewContext = createContext(null);
+const CONNECT_TIMEOUT_MS = 30_000;
+const GUARDED_EVENTS = ["click", "auxclick", "dblclick", "submit"];
+async function withDeadline(request, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            request,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Preview update timed out. Retry the edit.")), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** No bootstrap payload or bridge code is downloaded by ordinary visitors. */
+export function EditorPreviewProvider({ children, getBootstrap, renderTemplate, applySettings, origins = ZALIFY_EDITOR_ORIGINS, renderTimeoutMs = 20_000, }) {
+    const [editorOrigin, setEditorOrigin] = useState(null);
+    const [selectedPath, setSelectedPath] = useState(null);
+    const [templateName, setTemplateName] = useState(null);
+    const [regions, setRegions] = useState({});
+    const [error, setError] = useState(null);
+    const [retry, setRetry] = useState(0);
+    const controllerRef = useRef(null);
+    const sequenceRef = useRef(0);
+    // Server functions and callbacks may be new identities on every render;
+    // they must not reconnect the bridge.
+    const handlers = useRef({ getBootstrap, renderTemplate, applySettings });
+    handlers.current = { getBootstrap, renderTemplate, applySettings };
+    const enabled = editorOrigin !== null;
+    useEffect(() => {
+        setEditorOrigin(resolveEditorOrigin(origins));
+    }, [origins]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const guard = (event) => {
+            if (event.type === "click" &&
+                event.target instanceof Element &&
+                event.target.closest("[data-z-editor-retry]")) {
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                setRetry((value) => value + 1);
+                return;
+            }
+            // The bridge owns clicks once connected. Until then nothing in the shop
+            // may run; and a preview never submits a real lead, order or login.
+            if (event.type === "submit" || !controllerRef.current) {
+                event.preventDefault();
+                event.stopImmediatePropagation();
+            }
+        };
+        for (const type of GUARDED_EVENTS)
+            document.addEventListener(type, guard, true);
+        return () => {
+            for (const type of GUARDED_EVENTS)
+                document.removeEventListener(type, guard, true);
+        };
+    }, [enabled]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: retry intentionally tears down and reconnects the bridge.
+    useEffect(() => {
+        if (!editorOrigin || !templateName)
+            return;
+        let disposed = false;
+        let unmountObservers = () => { };
+        const leaveDesignMode = enterDesignMode();
+        setError(null);
+        const timeout = window.setTimeout(() => setError("Editor connection timed out. Retry the preview connection."), CONNECT_TIMEOUT_MS);
+        void (async () => {
+            const [{ mountFrameBridge }, selection, visiblePaths, bootstrap] = await Promise.all([
+                import("../editor/frame"),
+                import("../editor/selection"),
+                import("../editor/visible-paths"),
+                handlers.current.getBootstrap(),
+            ]);
+            if (disposed)
+                return;
+            // Both must listen before the bridge does: selection so a component can
+            // reveal the selected tab before it is measured, visible paths so a
+            // hidden responsive copy never shadows the visible one.
+            const unmountSelection = selection.mountEditorSelection(window, (path) => flushSync(() => setSelectedPath(path)));
+            const unmountVisiblePaths = visiblePaths.mountVisiblePaths(window, () => controllerRef.current?.reportRects());
+            unmountObservers = () => {
+                unmountVisiblePaths();
+                unmountSelection();
+            };
+            window.clearTimeout(timeout);
+            setError(null);
+            controllerRef.current = mountFrameBridge({
+                editorOrigin,
+                templateName,
+                hash: bootstrap.manifest.hash,
+                capabilities: [
+                    "editor-bootstrap-v1",
+                    "apply-template-v1",
+                    "apply-groups-v1",
+                    "apply-settings-v1",
+                    "preview-navigation-v1",
+                ],
+                getManifest: () => bootstrap.manifest,
+                getBootstrap: () => bootstrap,
+                applyTemplate: async (payload) => {
+                    if (payload.templateName !== templateName)
+                        return false;
+                    const sequence = ++sequenceRef.current;
+                    try {
+                        const content = await withDeadline(handlers.current.renderTemplate({
+                            templateName,
+                            template: payload.template,
+                            groups: payload.groups,
+                            pathname: window.location.pathname + window.location.search,
+                        }), renderTimeoutMs);
+                        // A newer edit is already rendering: this result is stale.
+                        if (disposed || sequence !== sequenceRef.current)
+                            return true;
+                        setRegions((current) => ({ ...current, ...content }));
+                        if (payload.settingsData)
+                            handlers.current.applySettings?.(payload.settingsData, document.documentElement);
+                        setError(null);
+                        return true;
+                    }
+                    catch (cause) {
+                        if (!disposed && sequence === sequenceRef.current)
+                            setError(cause instanceof Error
+                                ? cause.message
+                                : "Preview could not update");
+                        throw cause;
+                    }
+                },
+            });
+        })().catch((cause) => {
+            window.clearTimeout(timeout);
+            if (!disposed)
+                setError(cause instanceof Error ? cause.message : "Editor connection failed");
+        });
+        return () => {
+            disposed = true;
+            sequenceRef.current++;
+            window.clearTimeout(timeout);
+            controllerRef.current?.unmount();
+            controllerRef.current = null;
+            unmountObservers();
+            leaveDesignMode();
+        };
+    }, [editorOrigin, templateName, retry, renderTimeoutMs]);
+    // Measure after each committed region replacement.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: regions is the trigger.
+    useEffect(() => {
+        controllerRef.current?.reportRects();
+    }, [regions]);
+    const register = (name) => {
+        setTemplateName(name);
+        return () => setTemplateName((current) => (current === name ? null : current));
+    };
+    return (_jsxs(PreviewContext.Provider, { value: { enabled, selectedPath, regions, register }, children: [children, enabled && error ? (_jsxs("div", { role: "alert", style: {
+                    position: "fixed",
+                    left: 16,
+                    right: 16,
+                    bottom: 16,
+                    zIndex: 2147483647,
+                    padding: 16,
+                    background: "#fff1f0",
+                    color: "#8b1b16",
+                    border: "1px solid #c63225",
+                }, children: [error, " ", _jsx("button", { type: "button", "data-z-editor-retry": true, onClick: () => setRetry((value) => value + 1), children: "Retry" })] })) : null] }));
+}
+function useRegion(key, children) {
+    const context = useContext(PreviewContext);
+    return context?.enabled && Object.hasOwn(context.regions, key)
+        ? context.regions[key]
+        : children;
+}
+/** The page's template. Also tells the provider which template this route is. */
+export function EditorTemplateRegion({ name, children, }) {
+    const context = useContext(PreviewContext);
+    // Registration follows route identity, not every update of preview state.
+    const registerRef = useRef(context?.register);
+    registerRef.current = context?.register;
+    useEffect(() => registerRef.current?.(name), [name]);
+    return useRegion(`template:${name}`, children);
+}
+/** A section group (header-group, footer-group). */
+export function EditorGroupRegion({ name, children, }) {
+    return useRegion(`group:${name}`, children);
+}
+/** True inside a trusted editor frame, after hydration. */
+export function useEditorPreview() {
+    return useContext(PreviewContext)?.enabled ?? false;
+}
+/** The editor's selected `data-z-path`, so a component can reveal it. */
+export function useEditorSelection() {
+    const context = useContext(PreviewContext);
+    return context?.enabled ? context.selectedPath : null;
+}

package/dist/react/useEditorTemplate.d.ts

@@ -2,8 +2,11 @@ import type { TemplateData } from "../schemas/data";
 import type { ThemeEditorManifest } from "../schemas/manifest";
 import type { PreviewContext } from "../schemas/bridge";
 import type { EditorDocuments } from "../editor/bootstrap";
+import { ZALIFY_EDITOR_ORIGINS } from "./editor-origin";
+export { ZALIFY_EDITOR_ORIGINS };
 type Options = {
-    origins: readonly string[];
+    /** Defaults to {@link ZALIFY_EDITOR_ORIGINS}. */
+    origins?: readonly string[];
     loadManifest: () => Promise<ThemeEditorManifest>;
     /** Authoritative, repository-relative merchant data targets. */
     paths: EditorDocuments;
@@ -12,4 +15,3 @@ type Options = {
 };
 /** No editor code or schema is fetched outside an explicitly allowed preview. */
 export declare function useEditorTemplate(name: string, options: Options): TemplateData | null;
-export {};