@zalify/storefront-kit 0.3.1 → 0.4.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/react/editor-origin.d.ts

@@ -0,0 +1 @@
+export declare function resolveEditorOrigin(origins: readonly string[], win?: Window): string | null;

package/dist/react/editor-origin.js

@@ -0,0 +1,45 @@
+/**
+ * Which editor, if any, is framing this document.
+ *
+ * `document.referrer` names the editor only on the first document the editor
+ * loads. In `interact` mode the bridge navigates the frame with
+ * `location.replace`, so the next document's referrer is the storefront
+ * itself. The trusted origin is therefore remembered for the tab on first
+ * contact, and later documents accept it as long as the editor-mode param is
+ * still present — always checked against the allowlist, never trusted bare.
+ */
+const STORAGE_KEY = "zalify-editor-origin";
+export function resolveEditorOrigin(origins, win = window) {
+    if (!origins.length || win.self === win.top)
+        return null;
+    try {
+        if (new URL(win.location.href).searchParams.get("zalify-editor") !== "1")
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let referrer = null;
+    try {
+        referrer = new URL(win.document.referrer).origin;
+    }
+    catch {
+        referrer = null;
+    }
+    if (referrer && origins.includes(referrer)) {
+        try {
+            win.sessionStorage.setItem(STORAGE_KEY, referrer);
+        }
+        catch {
+            /* private mode: the first document still works */
+        }
+        return referrer;
+    }
+    try {
+        const remembered = win.sessionStorage.getItem(STORAGE_KEY);
+        return remembered && origins.includes(remembered) ? remembered : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/react/index.d.ts

@@ -36,4 +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,4 +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/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";
+/** Editors allowed to frame a storefront unless the app narrows the list. */
+export declare const ZALIFY_EDITOR_ORIGINS: readonly string[];
 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;

package/dist/react/useEditorTemplate.js

@@ -1,25 +1,39 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
 import { getThemeStore, setThemePreview } from "./engine/store";
+import { resolveEditorOrigin } from "./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",
+];
+/** 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.
+ */
+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");
+    };
+}
 /** 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);
-        if (!options.origins.length ||
-            window.self === window.top ||
-            new URL(window.location.href).searchParams.get("zalify-editor") !== "1")
-            return;
-        let parentOrigin;
-        try {
-            parentOrigin = new URL(document.referrer).origin;
-        }
-        catch {
-            return;
-        }
-        if (!options.origins.includes(parentOrigin))
+        const parentOrigin = resolveEditorOrigin(options.origins ?? ZALIFY_EDITOR_ORIGINS);
+        if (!parentOrigin)
             return;
+        const leaveDesignMode = enterDesignMode();
         let disposed = false;
         const owner = getThemeStore();
         void Promise.all([
@@ -102,6 +116,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.1",
+  "version": "0.4.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",
@@ -35,7 +35,12 @@
       "default": "./dist/react/server.js"
     }
   },
+  "bin": {
+    "storefront-kit": "./bin/storefront-kit.mjs"
+  },
   "files": [
+    "bin",
+    "skills",
     "dist",
     "src",
     "!src/**/*.test.ts"
@@ -78,7 +83,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "test": "node --test \"src/schemas/*.test.ts\" \"src/editor/*.test.ts\"",
+    "test": "node --test \"src/schemas/*.test.ts\" \"src/editor/*.test.ts\" \"src/react/*.test.ts\"",
     "typecheck": "tsc -p tsconfig.json"
   }
 }

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

@@ -0,0 +1,123 @@
+---
+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 |
+
+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>`.
+- 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/react/editor-origin.ts

@@ -0,0 +1,44 @@
+/**
+ * Which editor, if any, is framing this document.
+ *
+ * `document.referrer` names the editor only on the first document the editor
+ * loads. In `interact` mode the bridge navigates the frame with
+ * `location.replace`, so the next document's referrer is the storefront
+ * itself. The trusted origin is therefore remembered for the tab on first
+ * contact, and later documents accept it as long as the editor-mode param is
+ * still present — always checked against the allowlist, never trusted bare.
+ */
+const STORAGE_KEY = "zalify-editor-origin";
+
+export function resolveEditorOrigin(
+  origins: readonly string[],
+  win: Window = window,
+): string | null {
+  if (!origins.length || win.self === win.top) return null;
+  try {
+    if (new URL(win.location.href).searchParams.get("zalify-editor") !== "1")
+      return null;
+  } catch {
+    return null;
+  }
+  let referrer: string | null = null;
+  try {
+    referrer = new URL(win.document.referrer).origin;
+  } catch {
+    referrer = null;
+  }
+  if (referrer && origins.includes(referrer)) {
+    try {
+      win.sessionStorage.setItem(STORAGE_KEY, referrer);
+    } catch {
+      /* private mode: the first document still works */
+    }
+    return referrer;
+  }
+  try {
+    const remembered = win.sessionStorage.getItem(STORAGE_KEY);
+    return remembered && origins.includes(remembered) ? remembered : null;
+  } catch {
+    return null;
+  }
+}

package/src/react/index.ts

@@ -78,4 +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';

package/src/react/useEditorTemplate.ts

@@ -6,9 +6,39 @@ import type { FrameBridgeController } from "../editor/frame";
 import type { PreviewContext } from "../schemas/bridge";
 import type { EditorDocuments } from "../editor/bootstrap";
 import { getThemeStore, setThemePreview } from "./engine/store";
+import { resolveEditorOrigin } from "./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",
+];
+
+/** 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.
+ */
+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");
+  };
+}
 
 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;
@@ -28,19 +58,11 @@ export function useEditorTemplate(
   const controller = useRef<FrameBridgeController | null>(null);
   useEffect(() => {
     setDraft(null);
-    if (
-      !options.origins.length ||
-      window.self === window.top ||
-      new URL(window.location.href).searchParams.get("zalify-editor") !== "1"
-    )
-      return;
-    let parentOrigin: string;
-    try {
-      parentOrigin = new URL(document.referrer).origin;
-    } catch {
-      return;
-    }
-    if (!options.origins.includes(parentOrigin)) return;
+    const parentOrigin = resolveEditorOrigin(
+      options.origins ?? ZALIFY_EDITOR_ORIGINS,
+    );
+    if (!parentOrigin) return;
+    const leaveDesignMode = enterDesignMode();
     let disposed = false;
     const owner = getThemeStore();
     void Promise.all([
@@ -124,6 +146,7 @@ export function useEditorTemplate(
       });
     return () => {
       disposed = true;
+      leaveDesignMode();
       controller.current?.unmount();
       controller.current = null;
       setThemePreview(owner, null);