@zalify/storefront-kit 0.3.2 → 0.5.0

package/dist/react/useEditorTemplate.js

@@ -1,16 +1,19 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
 import { getThemeStore, setThemePreview } from "./engine/store";
-import { resolveEditorOrigin } from "./editor-origin";
+import { resolveEditorOrigin, ZALIFY_EDITOR_ORIGINS } from "./editor-origin";
+export { ZALIFY_EDITOR_ORIGINS };
+import { enterDesignMode } from "./design-mode";
 /** No editor code or schema is fetched outside an explicitly allowed preview. */
 export function useEditorTemplate(name, options) {
     const [draft, setDraft] = useState(null);
     const controller = useRef(null);
     useEffect(() => {
         setDraft(null);
-        const parentOrigin = resolveEditorOrigin(options.origins);
+        const parentOrigin = resolveEditorOrigin(options.origins ?? ZALIFY_EDITOR_ORIGINS);
         if (!parentOrigin)
             return;
+        const leaveDesignMode = enterDesignMode();
         let disposed = false;
         const owner = getThemeStore();
         void Promise.all([
@@ -93,6 +96,7 @@ export function useEditorTemplate(name, options) {
         });
         return () => {
             disposed = true;
+            leaveDesignMode();
             controller.current?.unmount();
             controller.current = null;
             setThemePreview(owner, null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.3.2",
+  "version": "0.5.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",
@@ -18,6 +18,10 @@
       "types": "./dist/editor/index.d.ts",
       "default": "./dist/editor/index.js"
     },
+    "./editor/bootstrap": {
+      "types": "./dist/editor/bootstrap.d.ts",
+      "default": "./dist/editor/bootstrap.js"
+    },
     "./editor/frame": {
       "types": "./dist/editor/frame.d.ts",
       "default": "./dist/editor/frame.js"
@@ -26,16 +30,29 @@
       "types": "./dist/editor/host.d.ts",
       "default": "./dist/editor/host.js"
     },
+    "./editor/selection": {
+      "types": "./dist/editor/selection.d.ts",
+      "default": "./dist/editor/selection.js"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "default": "./dist/react/index.js"
     },
+    "./react/preview": {
+      "types": "./dist/react/server-preview.d.ts",
+      "default": "./dist/react/server-preview.js"
+    },
     "./react/server": {
       "types": "./dist/react/server.d.ts",
       "default": "./dist/react/server.js"
     }
   },
+  "bin": {
+    "storefront-kit": "./bin/storefront-kit.mjs"
+  },
   "files": [
+    "bin",
+    "skills",
     "dist",
     "src",
     "!src/**/*.test.ts"
@@ -44,17 +61,22 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.28",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "@types/react-dom": "^18.3.7"
   },
   "repository": {
     "type": "git",

package/skills/zalify-storefront-editor/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: zalify-storefront-editor
+description: Contract between a Zalify headless storefront and the Zalify Site Editor. Use before touching templates, section/block schemas, template routing, editor/preview integration, or anything under theme/ — and before writing any "editor glue" in a storefront repo.
+---
+
+# Zalify storefront ↔ editor contract
+
+This file ships inside `@zalify/storefront-kit` and is copied into the repo by
+`pnpm exec storefront-kit skills sync`. Do not edit the copy: change it in the
+kit and re-sync. Its version is the kit version in `package.json`.
+
+## 0. Infrastructure lives in the kit, not in this repo
+
+A storefront repo holds **content and brand**: templates, section/block
+components, schemas, styles, data loaders. Everything that talks to the editor
+is SDK code and must be imported, never re-implemented:
+
+| Need | Use | Never |
+| --- | --- | --- |
+| Editor bootstrap | `createEditorBootstrap` (via `useEditorTemplate`) | a hand-built `EditorBootstrap` object or template catalog |
+| Frame bridge, selection, rects, navigation, interaction modes | `useEditorTemplate` / `mountFrameBridge` | custom `postMessage` handlers |
+| Is this document inside the editor? | `resolveEditorOrigin` | reading `document.referrer` or the query param yourself |
+| Allowed editor origins | `ZALIFY_EDITOR_ORIGINS` (default) | a copied origin list |
+| Design-mode flag + `--editor-viewport-height` | set by `useEditorTemplate` | a per-repo effect that sets them |
+| Draft application | `createEditorDraft` | mutating template JSON in components |
+| Preview for server-rendered (RSC) storefronts | `EditorPreviewProvider`, `EditorTemplateRegion`, `EditorGroupRegion`, `useEditorPreview`, `useEditorSelection` from `@zalify/storefront-kit/react/preview` | a local provider, selection listener or visible-path observer |
+
+Two integration shapes exist, pick by how the storefront renders:
+
+- **Client theme engine** (`installTheme` + `ThemeTemplate`): call
+  `useEditorTemplate(name, {paths, previews, loadManifest})`.
+- **Server-rendered templates** (RSC): wrap the layout in
+  `<EditorPreviewProvider getBootstrap={…} renderTemplate={…}>`, where both
+  props are server functions of the app — `getBootstrap` returns
+  `createEditorBootstrap(...)`, `renderTemplate` renders a draft read-only —
+  and wrap each page in `<EditorTemplateRegion name="…">`, each header/footer
+  in `<EditorGroupRegion name="…">`.
+
+If the kit cannot express what the storefront needs, the fix is a kit change
+(open a PR on `zalify/zalify-theme-2026`, bump the version), not a local
+workaround. A local workaround silently diverges from every other storefront
+and from the editor.
+
+## 1. Templates
+
+- Names follow Shopify: `<type>` or `<type>.<suffix>` — `product`,
+  `product.drawing-projector`, `page.about`. The type is the part before the
+  first dot and must be one of `index, product, collection, list-collections,
+  page, blog, article, cart, search, 404, password, gift_card`. A name like
+  `product-drawing-projector` or `luka-features` is an unknown type: the editor
+  cannot group it, icon it, or offer an entity picker for it. Landing pages are
+  `page.<suffix>`.
+- Assert `templateNameProblems(names)` (from
+  `@zalify/storefront-kit/editor/bootstrap`) is empty in the repo's tests.
+- A type that has alternates also registers its default (`page` next to
+  `page.about`). The editor nests alternates under the default.
+- `writePath` is `<templates dir>/<name>.json`; the file on disk has the same
+  name. Renaming a template renames the file and every route that loads it.
+- Only advertise a preview route the app can really render. Resource routes
+  (`product`, `collection`, `page`, `blog`, `article`) are added by the hook
+  when visited; never fabricate handles.
+- `disabled: true` on a section or block means "kept in the template, not
+  rendered". The editor shows it as hidden and can toggle it. Do not use it as
+  a feature flag the merchant is not supposed to see.
+
+## 2. Schema, template and rendering agree
+
+- Components read section/block settings; a schema whose fields the component
+  ignores is a bug. Cover text, images, alt, button label/link, repeated items.
+- Clearing a value stays cleared: no silent fallback to a default, never an
+  empty `src`.
+- Repeated items have stable ids and `block_order`. After insert / delete /
+  duplicate / reorder, the serialized data and the DOM paths still match.
+- `data-z-path` matches the template structure for every block, including ones
+  added later — not just the default blocks.
+- Different structures get different block types (`feature-card`,
+  `timeline-entry`, `faq-item`), never a shared `item`.
+- Labels name the purpose ("Primary button link"), not the default value.
+- The first name-like setting (`heading`, `title`, `name`, `label`) is what the
+  editor shows in Layers. Give sections one.
+
+## 3. Links and images
+
+| Value | Meaning |
+| --- | --- |
+| `#contact` | in-page href, not an element id field |
+| `/products/example` | store-relative link |
+| full HTTPS URL | by the field's purpose |
+| `/images/example.jpg` | asset in `public/`; keep it root-relative |
+| empty image | render no image node |
+
+No preview or local origins in template defaults.
+
+## 4. Design mode (inside the editor)
+
+The editor sizes the iframe to the page's content. Therefore:
+
+- Any height derived from `100vh` / `100dvh` / `min-height: 100vh` grows with
+  every height report. Under `html[data-z-design-mode='1']`, base those heights
+  on `var(--editor-viewport-height)` instead. This applies to heroes, product
+  galleries, sticky columns, full-screen drawers — check every `vh` in the CSS.
+- Never clip the page (`max-height`, `overflow: hidden` on the root) to hide a
+  problem: later sections become unreachable.
+- Content revealed only by scroll (IntersectionObserver, scroll animations,
+  lazy sections) needs a visible, editable presentation in design mode.
+- Do not change the normal site's scrolling or animations to fix the preview.
+
+## 5. Editor mode must not leak into the business
+
+- Analytics, pixels and ad tags are skipped in editor mode (use
+  `resolveEditorOrigin` on the client, the `x-zalify-editor` header on the
+  server). An editing session is not a visitor.
+- Forms keep their real submit logic; styling changes never alter attribution,
+  subscription, validation or payment requests.
+- Drafts never reach public caches or production data. No unauthenticated
+  write endpoints.
+- The storefront works with the editor unreachable; editor code is lazy-loaded
+  only after `resolveEditorOrigin` returns an origin.
+
+## 6. Verify before shipping
+
+- Per route (home, product, collection, content, legal, landing pages): right
+  page, images loaded, real page height and section boundaries — not a
+  screenshot squeezed to match.
+- Per block type: edit, clear, insert, duplicate, delete, reorder; check the
+  DOM and the saved JSON.
+- Desktop and mobile. Normal visit and inside the editor.
+- Report what was run, what was skipped, and what is still a risk. Unverified
+  is not passed.
+
+## 7. Upgrading the kit
+
+1. Bump `@zalify/storefront-kit`, install, confirm the resolved version in the
+   lockfile.
+2. `pnpm exec storefront-kit skills sync` and commit the result.
+3. Delete any local code the new version makes redundant (see section 0).
+4. Typecheck, test, build; open the site inside the editor once.

package/src/editor/bootstrap.ts

@@ -8,6 +8,48 @@ export interface EditorDocuments {
   settings: string;
 }
 
+/** 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',
+] as const;
+
+/**
+ * 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: readonly string[]): string[] {
+  const problems: string[] = [];
+  const known = new Set(names);
+  const needsDefault = new Set<string>();
+  for (const name of names) {
+    if (name.startsWith('customers/')) continue;
+    const type = name.split('.')[0];
+    if (!(TEMPLATE_TYPES as readonly string[]).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: {
   schema: DraftSchema;

package/src/editor/selection.ts

@@ -0,0 +1,52 @@
+import {
+  BRIDGE_NAMESPACE,
+  CONTRACT_VERSION,
+  isCompatibleVersion,
+} from "../schemas/index.ts";
+
+/** 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: Window,
+  onSelect: (path: string | null) => void,
+) {
+  let origin: string | undefined;
+  const listener = (event: MessageEvent) => {
+    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: Event) => {
+    const target = event.target as Element | null;
+    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/src/editor/visible-paths.ts

@@ -0,0 +1,99 @@
+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: Document) {
+  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: Document) {
+  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: Window, onChange: () => void) {
+  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: string | null) =>
+    ["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 as Element;
+        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: MessageEvent) => {
+    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/src/react/design-mode.ts

@@ -0,0 +1,21 @@
+/** 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(): () => void {
+  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/src/react/editor-origin.ts

@@ -10,6 +10,13 @@
  */
 const STORAGE_KEY = "zalify-editor-origin";
 
+/** Editors allowed to frame a storefront unless the app narrows the list. */
+export const ZALIFY_EDITOR_ORIGINS: readonly string[] = [
+  "https://app.zalify.com",
+  "http://localhost:3000",
+];
+
+
 export function resolveEditorOrigin(
   origins: readonly string[],
   win: Window = window,

package/src/react/index.ts

@@ -78,5 +78,8 @@ export {
 // 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';