@wocart/theme 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 2.3.0 — 2026-10-24
+
+### Added
+
+- `SurfacePageType` and the manifest's page types take `trackOrder`, the
+  storefront's new page type (`@wocart/storefront` 1.21.0, now the peer).
+
+## 2.2.0 — 2026-10-24
+
+What every theme used to write itself is now the package's: binding browser
+behaviour through page and section swaps, choosing what an editor's preview
+shows, and a marker for color schemes. Browser code takes only what builds no
+validator.
+
+### Added
+
+- `@wocart/theme/lifecycle`: `bindEach(selector, bind)` binds each element
+  once — when the page is ready, after Astro swaps a page, after the editor
+  swaps a section — and runs a bind's teardown when its element leaves;
+  `onEachPage(boot)`; `PREVIEW_SECTION_LOAD_EVENT`, without the bridge.
+- `@wocart/theme/messages`: the message functions for browser code.
+  `pluralMessageKeys` is now exported, here and from the root.
+- `previewTarget(theme, draft, client)` in `@wocart/theme/astro`: the surface,
+  route parameters and document an editor's preview renders, chosen by page
+  type, or null for a surface the theme does not declare.
+- `SCHEME_MARKER_CLASS`: `schemeClass(id)` gives `wc-scheme wc-scheme-<id>`,
+  so a theme derives its tokens on `:root, .wc-scheme`.
+- `defineCapabilities(capabilities)` for capabilities several components share,
+  and `componentsOf(theme)` to iterate a theme's components as definitions.
+
+### Changed
+
+- The rich-text types are plain JSON: a preset or a default holds a document
+  without a cast. `JsonValue` accepts read-only lists.
+- The style and rich-text helpers no longer bring Zod into a browser bundle.
+- The `@wocart/storefront` peer is `^1.20.0`: `previewTarget` uses its route
+  matcher and default collections.
+
 ## 2.1.0 — 2026-10-21
 
 The release check now sees where a section may be placed.

package/README.md

@@ -39,12 +39,19 @@ Node 22.12 or newer.
 | Import | What it holds |
 | --- | --- |
 | `@wocart/theme` | definitions, validation, page documents, resolution, document operations, rich text output, the manifest and its diff, languages and messages — framework-neutral |
-| `@wocart/theme/astro` | `createReadCache`, `themeManifestEndpoint` (the manifest as a build artifact), `hasBlocks`, `isPreview`, `THEME_LIMITS`, `themeStylesEndpoint`, the preview markers and the `BlocksHandle` and `RendererIssue` types |
+| `@wocart/theme/astro` | `createReadCache`, `themeManifestEndpoint` (the manifest as a build artifact), `hasBlocks`, `isPreview`, `THEME_LIMITS`, `themeStylesEndpoint`, `previewTarget`, the preview markers and the `BlocksHandle` and `RendererIssue` types |
 | `@wocart/theme/astro/InstanceView.astro` | the reference renderer component |
 | `@wocart/theme/astro/Blocks.astro`, `@wocart/theme/astro/Block.astro` | a slot's blocks and a fixed block, placed by a component (see [Blocks](#blocks)) |
 | `@wocart/theme/astro/ThemeStyles.astro` | the stylesheet link and the store's color schemes, for a layout's `<head>` (see [Style](#style)) |
 | `@wocart/theme/image-service` | `mediaImageService` — an Astro image service that resizes media-domain images on the media domain (any storefront host) |
 | `@wocart/theme/preview` | `startPreviewBridge` — the browser module of a theme's preview page (see [Preview](#preview)) |
+| `@wocart/theme/lifecycle` | `bindEach`, `onEachPage`, `PREVIEW_SECTION_LOAD_EVENT` — binding browser behaviour so it survives page and section swaps; tiny, without the bridge (see [Browser scripts](#browser-scripts)) |
+| `@wocart/theme/messages` | `formatMessage`, `messageForms`, `pluralMessageKeys`, `pluralFormIssues` for browser code (see [Messages](#messages-placeholders-and-plurals)) |
+
+Browser code imports only what builds no validator: `./lifecycle`,
+`./messages`, and from the root the style, rich-text and message helpers. A
+test of this package bundles each of them and fails if Zod or the editor's
+bridge reaches a shopper's page.
 
 ## Use
 
@@ -207,6 +214,9 @@ localize site links. `richTextToPlainText` gives the words for a meta
 description or an `aria-label`. A field's `formats` (`["bold", "link"]`)
 narrows what a merchant may use.
 
+The rich-text types are plain JSON (`RichTextDocument` is a `JsonObject`), so
+a preset or a default can hold a document without a cast.
+
 ### Lists
 
 ```ts
@@ -429,7 +439,21 @@ export const GET = themeStylesEndpoint(theme);
 
 The schemes become custom properties on `.wc-scheme-<id>`
 (`--wc-color-background`, `--wc-color-button-text`, …) with the background
-and text applied. On a page with a Content-Security-Policy, `ThemeStyles` adds
+and text applied. `schemeClass(id)` also gives the element `wc-scheme`
+(`SCHEME_MARKER_CLASS`), the one class every element wearing a scheme
+carries. Derive the theme's own tokens there and on the page, so they follow
+the scheme of the nearest element that wears one:
+
+```css
+:root, .wc-scheme {
+  --surface: var(--wc-color-background, #fff);
+  --ink: var(--wc-color-text, #1d1d1f);
+  --line: color-mix(in srgb, var(--wc-color-border, #e5e5e5) 70%, transparent);
+}
+```
+
+Without that rule a token computed once on `:root` keeps the page's colors
+inside a section that wears another scheme. On a page with a Content-Security-Policy, `ThemeStyles` adds
 its inline sheet's hash to the policy, so `style-src` needs no
 `'unsafe-inline'`. `contrastRatio(a, b)` gives the WCAG ratio an editor warns
 on (below 4.5 for text).
@@ -500,7 +524,13 @@ presets: [
 ```
 
 `instantiatePreset(theme, type, key, newId)` builds the instances, each with an
-id from `newId`. Presets are checked at assembly by building them.
+id from `newId`. Presets are checked at assembly by building them. A preset's
+props may hold rich text as it is written:
+
+```ts
+const welcome: RichTextDocument = { type: "doc", version: 1, content: [{ type: "paragraph", content: [{ type: "text", text: "Bienvenue" }] }] };
+presets: [{ key: "welcome", label: "Welcome", props: { body: welcome } }],
+```
 
 ## Hidden sections
 
@@ -622,12 +652,62 @@ later.
 A swapped section's scripts do not run again. A section with browser behavior
 binds it again on `PREVIEW_SECTION_LOAD_EVENT` (`wocart:section-load`,
 dispatched on `document` with `detail.id`) — also for a section a patch
-copied, restored or showed again. When the bridge replaces the whole
+copied, restored or showed again. `bindEach` (see [Browser scripts](#browser-scripts))
+does it for you. When the bridge replaces the whole
 page instead, it does what Astro's router does after a navigation — a new
 `<body>`, the root element's attributes, the title — and dispatches
 `astro:page-load`, so a script written for the router mounts again as it does
 there. Changed stylesheets are replaced in place; unchanged ones never reload.
 
+### Which page a preview shows
+
+`previewTarget(theme, draft, client)` from `@wocart/theme/astro` decides it
+for every theme: the surface to render, its route parameters and its
+document — or null, answered 404, for a surface the theme does not declare.
+
+- A template previews the resource the draft's path names, else the store's
+  first product, category, default collection or text page; a store with
+  none still previews, with empty `params`, so its sections can be arranged.
+- An area (`area:header`) previews on the page its path names when the theme
+  composes it, else home; `area` names it, and the page's own document is
+  the saved one.
+- The resource is chosen by the surface's `pageType`, so an alternate
+  (`product.compact`) previews like its base.
+
+```astro
+---
+const target = await previewTarget(theme, Astro.locals.preview.draft, Astro.locals.store.client);
+if (!target) return new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
+---
+<Sections surface={target.surface} params={target.params} document={target.document} preview={target.area === null} />
+```
+
+## Browser scripts
+
+A theme's browser behaviour meets markup three ways: the page loads, Astro's
+router swaps the page (`astro:page-load`), an editor's preview swaps one
+section (`PREVIEW_SECTION_LOAD_EVENT`). `@wocart/theme/lifecycle` binds it
+once per element whichever way it came:
+
+```ts
+import { bindEach, onEachPage } from "@wocart/theme/lifecycle";
+
+bindEach<HTMLFormElement>("[data-order-form]", (form) => {
+  const onResize = () => layout(form);
+  window.addEventListener("resize", onResize);
+  return () => window.removeEventListener("resize", onResize);
+});
+
+onEachPage(() => {
+  const timer = setInterval(tick, 1000);
+  return () => clearInterval(timer);
+});
+```
+
+A bind's teardown runs when its element leaves — before Astro swaps the page
+out, or when a later pass finds it gone — so document and window listeners
+never pile up. Both return a function that stops them.
+
 ## Theme manifest (serializable catalogue)
 
 A `ThemeDefinition` mixes data (types, fields, defaults) with runtime (the live
@@ -877,7 +957,10 @@ message rule — Shopify's locale-file model on the platform's own CLDR data
 - `pluralFormIssues(pack, locale)` lists the forms a pack is missing for its
   language, or carries but never uses — run it over every pack in a test.
 - `messageForms(pack, key)` collects one message's keys to hand a browser
-  script.
+  script; `pluralMessageKeys(pack)` names every plural message in a pack.
+
+Browser code imports the same functions from `@wocart/theme/messages`, an
+entry with nothing else in it.
 
 Packs stay `Record<string, string>`, so store overrides and the editor treat
 plural forms like any other key.
@@ -885,7 +968,17 @@ plural forms like any other key.
 ## Capabilities are advisory
 
 `ComponentDefinition.capabilities` (`insertable`, `surfaces`) is metadata for an **editor/CLI insertion
-surface**, not renderer enforcement. Neither `parsePageData` nor
+surface**, not renderer enforcement. Capabilities several components share go
+through `defineCapabilities`:
+
+```ts
+const ANY_PAGE = defineCapabilities({ surfaces: ["home", "product", "collection"] });
+const grid = defineComponent({ type: "product-grid", capabilities: ANY_PAGE, /* … */ });
+```
+
+A plain constant inferred from a literal (`{ surfaces: [...] as const }`) can
+make TypeScript read a definition's `fields` in two shapes when its `load`
+types its props from them; the error then names an unrelated field. Neither `parsePageData` nor
 `resolveInstance` consults it: a saved document containing a component marked
 `insertable: false` still renders, because the render path never second-guesses
 a document that was already saved. Any future enforcement belongs at insertion
@@ -962,7 +1055,9 @@ A theme proves it honors the contract with four checks in its own test suite:
 
 1. **The catalog assembles clean** — with its packs declared on the theme,
    its default documents and presets are checked too:
-   `expect(validateThemeDefinition(theme)).toEqual([])`.
+   `expect(validateThemeDefinition(theme)).toEqual([])`. To check something
+   of every component, iterate `componentsOf(theme)`, which lists them as
+   `ComponentDefinition`s.
 2. **The manifest survives a JSON round trip**:
    `validateThemeManifest(JSON.parse(JSON.stringify(themeManifest(theme))))`
    returns no issues.

package/dist/astro/index.d.ts

@@ -4,6 +4,8 @@ export { resolveInstance } from "../instances.js";
 export { THEME_LIMITS } from "../blocks.js";
 export { THEME_STYLES_PATH, colorSchemeCss } from "../style.js";
 export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
+export { previewTarget } from "../preview-target.js";
+export type { PreviewTarget } from "../preview-target.js";
 /**
  * The theme's manifest as a prerendered endpoint, the file a release and an
  * editor read (`THEME_MANIFEST_PATH`):

package/dist/astro/index.js

@@ -11,6 +11,8 @@
  *   `InstanceView`'s `onIssue` prop.
  * - `BlocksHandle` and `hasBlocks` — what a component receives as `blocks`,
  *   and whether one of its slots has anything to render.
+ * - `previewTarget` — which surface, resource and document an editor's
+ *   preview renders.
  * - `resolveInstance` and `THEME_LIMITS` — re-exported so `InstanceView.astro`'s
  *   co-located import (`./index.js`) resolves identically in the dev source
  *   layout and in the published `dist/astro` layout. The same values as the
@@ -26,6 +28,7 @@ export { resolveInstance } from "../instances.js";
 export { THEME_LIMITS } from "../blocks.js";
 export { THEME_STYLES_PATH, colorSchemeCss } from "../style.js";
 export { previewEndMarker, previewStartMarker } from "../preview-protocol.js";
+export { previewTarget } from "../preview-target.js";
 /**
  * The theme's manifest as a prerendered endpoint, the file a release and an
  * editor read (`THEME_MANIFEST_PATH`):

package/dist/definitions.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentDefinition, FieldDefinition, FieldValues, LoadContext, ThemeDefinition, ThemeDefinitionIssue, ThemeValidationOptions } from "./types.js";
+import type { ComponentCapabilities, ComponentDefinition, FieldDefinition, FieldValues, LoadContext, ThemeDefinition, ThemeDefinitionIssue, ThemeValidationOptions } from "./types.js";
 /**
  * Identity helper: returns the definition unchanged so literal types survive.
  * `load` receives the component's props typed from its own `fields`, so a
@@ -20,6 +20,21 @@ type ComponentBase = Omit<ComponentDefinition, "fields" | "load">;
 type FieldsPart<Fields extends readonly FieldDefinition[]> = [Fields] extends [readonly []] ? {} : {
     fields: Fields;
 };
+/**
+ * Identity helper for capabilities several components share:
+ *
+ * ```ts
+ * const ANY_PAGE = defineCapabilities({ surfaces: ["home", "product", "collection"] });
+ * ```
+ *
+ * Share them through it rather than as a plain constant. A constant inferred
+ * from a literal (`{ surfaces: [...] as const }`) can make TypeScript read a
+ * definition's `fields` twice in two shapes when its `load` types its props
+ * from them, and the error then names an unrelated field.
+ */
+export declare function defineCapabilities(capabilities: ComponentCapabilities): ComponentCapabilities;
+/** A theme's components as definitions, in its catalog's order — what a test or a tool iterates. */
+export declare function componentsOf(theme: Pick<ThemeDefinition, "components">): ComponentDefinition[];
 /** Identity helper for the catalog. */
 export declare function defineTheme<const T extends ThemeDefinition>(definition: T): T;
 /** Check the whole catalog: key/type identity, field rules, slot rules. */

package/dist/definitions.js

@@ -15,6 +15,25 @@ import { COLOR_PATTERN, MENU_HANDLE_PATTERN, COLLECTION_HANDLE_PATTERN, PAGE_TYP
 export function defineComponent(definition) {
     return definition;
 }
+/**
+ * Identity helper for capabilities several components share:
+ *
+ * ```ts
+ * const ANY_PAGE = defineCapabilities({ surfaces: ["home", "product", "collection"] });
+ * ```
+ *
+ * Share them through it rather than as a plain constant. A constant inferred
+ * from a literal (`{ surfaces: [...] as const }`) can make TypeScript read a
+ * definition's `fields` twice in two shapes when its `load` types its props
+ * from them, and the error then names an unrelated field.
+ */
+export function defineCapabilities(capabilities) {
+    return capabilities;
+}
+/** A theme's components as definitions, in its catalog's order — what a test or a tool iterates. */
+export function componentsOf(theme) {
+    return Object.values(theme.components);
+}
 /** Identity helper for the catalog. */
 export function defineTheme(definition) {
     return definition;

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  * This entry is framework-neutral. The reference Astro renderer lives in the
  * `./astro` subpath.
  */
-export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
+export { componentsOf, defineCapabilities, defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
 export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance, checkStoredValue as checkFieldValue } from "./instances.js";
 export type { CheckedValue as FieldValueCheck } from "./instances.js";
@@ -20,7 +20,7 @@ export { instantiatePreset, isInsertableOn } from "./composition.js";
 export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
 export { completePage, resolveSurfaceDocument } from "./surface-document.js";
 export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
-export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
+export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, SCHEME_MARKER_CLASS, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
 export type { SurfaceDocument, SurfaceDocumentReason } from "./surface-document.js";
 export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export type { DocumentEdit, DocumentIssue, DocumentIssueCode, InstanceLocation, InstancePlacement, } from "./operations.js";
@@ -28,7 +28,7 @@ export { THEME_SDK_VERSION } from "./version.js";
 export type { RichTextHtmlOptions } from "./rich-text.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
-export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";
 export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";
 export { diffThemeManifests } from "./manifest-diff.js";

package/dist/index.js

@@ -11,7 +11,7 @@
  * This entry is framework-neutral. The reference Astro renderer lives in the
  * `./astro` subpath.
  */
-export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
+export { componentsOf, defineCapabilities, defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
 export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance, checkStoredValue as checkFieldValue } from "./instances.js";
 export { RICH_TEXT_FORMATS, richTextToHtml, richTextToPlainText } from "./rich-text.js";
@@ -19,12 +19,12 @@ export { instantiatePreset, isInsertableOn } from "./composition.js";
 export { COMPONENT_PLACEMENTS, COMPONENT_ROLES, THEME_LIMITS, areaSurface, fixedBlockId } from "./blocks.js";
 export { completePage, resolveSurfaceDocument } from "./surface-document.js";
 export { CONDITION_DEPTH, isFieldVisible } from "./conditions.js";
-export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
+export { COLOR_ROLES, COLOR_SCHEMES_MAX, STYLE_BREAKPOINTS, STYLE_PANELS, STYLE_STEPS, STYLE_WIDTHS, THEME_STYLES_PATH, SCHEME_MARKER_CLASS, colorSchemeCss, contrastRatio, schemeClass, styleClasses, themeStyleSheet, } from "./style.js";
 export { checkPageData, duplicateInstance, findInstance, insertInstance, moveInstance, newInstanceId, removeInstance, setInstanceHidden, setInstanceProps, } from "./operations.js";
 export { THEME_SDK_VERSION } from "./version.js";
 export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
-export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";
 export { diffThemeManifests } from "./manifest-diff.js";
 export { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `@wocart/theme/lifecycle` — binding a theme's browser behaviour to its
+ * markup, so it survives the page being swapped.
+ *
+ * Markup arrives three ways: the page loads; Astro's router swaps the page
+ * (`astro:page-load`); an editor's preview swaps one section in
+ * (`PREVIEW_SECTION_LOAD_EVENT`). A script that binds once on import misses
+ * the last two, and one that binds on every event binds twice. `bindEach`
+ * binds each matching element exactly once, whichever way it arrived, and
+ * `onEachPage` runs a page's behaviour once per page.
+ *
+ * This module is tiny and loads nothing else: a shopper's page imports it, and
+ * the editor's bridge (`@wocart/theme/preview`) stays on the preview route.
+ */
+/**
+ * Dispatched on `document` for each section the editor's preview swapped in,
+ * with the instance id as `detail.id`. When the whole page was replaced, the
+ * preview dispatches Astro's own `astro:page-load` instead.
+ */
+export declare const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+/** What a bind may return: a function that undoes it — listeners on `document` or `window`, timers. */
+export type Teardown = void | (() => void);
+export interface LifecycleOptions {
+    /** The document to bind in; the page's own by default. */
+    document?: Document;
+}
+/**
+ * Runs `boot` for the page the shopper is on, and again for each page Astro's
+ * router swaps in. Its teardown runs just before the page is swapped out, so
+ * listeners on `document` or `window` never pile up from one page to the next.
+ * Returns a function that stops it.
+ */
+export declare function onEachPage(boot: () => Teardown, options?: LifecycleOptions): () => void;
+/**
+ * Runs `bind` once on every element `selector` matches: when the page is
+ * ready, after Astro's router swaps a page in, and after an editor's preview
+ * swaps a section in. A bind may return a teardown, run when its element
+ * leaves — before Astro swaps the page out, or when a later pass finds the
+ * element gone. Returns a function that stops it and runs every teardown.
+ *
+ * ```ts
+ * bindEach<HTMLFormElement>("[data-order-form]", (form) => {
+ *   const onResize = () => layout(form);
+ *   window.addEventListener("resize", onResize);
+ *   return () => window.removeEventListener("resize", onResize);
+ * });
+ * ```
+ */
+export declare function bindEach<T extends Element = HTMLElement>(selector: string, bind: (element: T) => Teardown, options?: LifecycleOptions): () => void;

package/dist/lifecycle.js

@@ -0,0 +1,120 @@
+/// <reference lib="dom" />
+/**
+ * `@wocart/theme/lifecycle` — binding a theme's browser behaviour to its
+ * markup, so it survives the page being swapped.
+ *
+ * Markup arrives three ways: the page loads; Astro's router swaps the page
+ * (`astro:page-load`); an editor's preview swaps one section in
+ * (`PREVIEW_SECTION_LOAD_EVENT`). A script that binds once on import misses
+ * the last two, and one that binds on every event binds twice. `bindEach`
+ * binds each matching element exactly once, whichever way it arrived, and
+ * `onEachPage` runs a page's behaviour once per page.
+ *
+ * This module is tiny and loads nothing else: a shopper's page imports it, and
+ * the editor's bridge (`@wocart/theme/preview`) stays on the preview route.
+ */
+/**
+ * Dispatched on `document` for each section the editor's preview swapped in,
+ * with the instance id as `detail.id`. When the whole page was replaced, the
+ * preview dispatches Astro's own `astro:page-load` instead.
+ */
+export const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+const PAGE_LOAD = "astro:page-load";
+const BEFORE_SWAP = "astro:before-swap";
+function whenReady(doc, run) {
+    if (doc.readyState === "loading")
+        doc.addEventListener("DOMContentLoaded", run, { once: true });
+    else
+        run();
+}
+/**
+ * Runs `boot` for the page the shopper is on, and again for each page Astro's
+ * router swaps in. Its teardown runs just before the page is swapped out, so
+ * listeners on `document` or `window` never pile up from one page to the next.
+ * Returns a function that stops it.
+ */
+export function onEachPage(boot, options = {}) {
+    const doc = options.document ?? document;
+    let mounted = null;
+    let teardown;
+    const unmount = () => {
+        const previous = teardown;
+        teardown = undefined;
+        if (typeof previous === "function")
+            previous();
+    };
+    const mount = () => {
+        mounted = doc.body;
+        teardown = boot();
+    };
+    const pageLoad = () => {
+        if (doc.body === mounted)
+            return;
+        unmount();
+        mount();
+    };
+    doc.addEventListener(BEFORE_SWAP, unmount);
+    doc.addEventListener(PAGE_LOAD, pageLoad);
+    whenReady(doc, () => {
+        if (mounted === null)
+            mount();
+    });
+    return () => {
+        doc.removeEventListener(BEFORE_SWAP, unmount);
+        doc.removeEventListener(PAGE_LOAD, pageLoad);
+        unmount();
+    };
+}
+/**
+ * Runs `bind` once on every element `selector` matches: when the page is
+ * ready, after Astro's router swaps a page in, and after an editor's preview
+ * swaps a section in. A bind may return a teardown, run when its element
+ * leaves — before Astro swaps the page out, or when a later pass finds the
+ * element gone. Returns a function that stops it and runs every teardown.
+ *
+ * ```ts
+ * bindEach<HTMLFormElement>("[data-order-form]", (form) => {
+ *   const onResize = () => layout(form);
+ *   window.addEventListener("resize", onResize);
+ *   return () => window.removeEventListener("resize", onResize);
+ * });
+ * ```
+ */
+export function bindEach(selector, bind, options = {}) {
+    const doc = options.document ?? document;
+    const bound = new WeakSet();
+    const teardowns = new Map();
+    const release = (element) => {
+        const teardown = teardowns.get(element);
+        teardowns.delete(element);
+        bound.delete(element);
+        teardown?.();
+    };
+    const run = () => {
+        for (const element of [...teardowns.keys()])
+            if (!element.isConnected)
+                release(element);
+        doc.querySelectorAll(selector).forEach((element) => {
+            if (bound.has(element))
+                return;
+            bound.add(element);
+            const teardown = bind(element);
+            if (typeof teardown === "function")
+                teardowns.set(element, teardown);
+        });
+    };
+    const leave = () => {
+        for (const element of [...teardowns.keys()])
+            release(element);
+    };
+    doc.addEventListener(PAGE_LOAD, run);
+    doc.addEventListener(PREVIEW_SECTION_LOAD_EVENT, run);
+    doc.addEventListener(BEFORE_SWAP, leave);
+    whenReady(doc, run);
+    return () => {
+        doc.removeEventListener(PAGE_LOAD, run);
+        doc.removeEventListener(PREVIEW_SECTION_LOAD_EVENT, run);
+        doc.removeEventListener(BEFORE_SWAP, leave);
+        leave();
+    };
+}

package/dist/messages-entry.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@wocart/theme/messages` — a content pack's messages, for browser code:
+ * placeholders and CLDR plurals, with nothing else from the theme contract.
+ * The same functions as the package's root entry.
+ */
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";
+export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";

package/dist/messages-entry.js

@@ -0,0 +1,6 @@
+/**
+ * `@wocart/theme/messages` — a content pack's messages, for browser code:
+ * placeholders and CLDR plurals, with nothing else from the theme contract.
+ * The same functions as the package's root entry.
+ */
+export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues, pluralMessageKeys } from "./messages.js";

package/dist/patterns.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A theme's key: lowercase kebab-case, at most 64 characters. The platform
+ * stores a merchant's text edits under it, so it is the theme's identity on the
+ * platform, and the server applies the same rule.
+ */
+export declare const THEME_KEY_PATTERN: RegExp;
+/** Type keys are lowercase kebab-case. */
+export declare const TYPE_KEY_PATTERN: RegExp;
+/**
+ * The page-document **surface** key — the address of a composed page
+ * (`home`, `product`, …; `area:<key>` is an area's document, and
+ * `page:<slug>` / `lp:<slug>` are reserved conventions).
+ *
+ * The server applies the same pattern. Module-level on purpose: it is part of
+ * the persisted-data contract,
+ * not of the package's curated public surface (`src/index.ts`).
+ */
+export declare const SURFACE_KEY_PATTERN: RegExp;
+/** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
+export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou", "trackOrder"];
+/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
+export declare const COLOR_PATTERN: RegExp;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export declare const MENU_HANDLE_PATTERN: RegExp;
+export declare const COLLECTION_HANDLE_PATTERN: RegExp;
+/**
+ * A `product` or `category` value: a handle or slug as the store's URLs use
+ * it. Merchants may type their own, so the rule only keeps out what cannot be
+ * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
+ * and `%`, and anything over 255 characters.
+ */
+export declare const RESOURCE_HANDLE_PATTERN: RegExp;
+/**
+ * A media object key in the store's bucket: a namespace and a name
+ * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
+ * that never start with a dot — so no `..`, no leading slash, no empty
+ * segment — and at most 512 characters.
+ */
+export declare const MEDIA_KEY_PATTERN: RegExp;
+export declare function isLocaleTag(value: string): boolean;
+/**
+ * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
+ * object with at least one entry, every key a locale tag, every value a string.
+ */
+export declare function isLocaleMap(value: unknown): value is Readonly<Record<string, string>>;
+/**
+ * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
+ * object with at least one entry, every key a locale tag.
+ */
+export declare function isLocaleMapOf<T>(value: unknown, isEntry: (entry: unknown) => entry is T): value is Readonly<Record<string, T>>;
+/**
+ * Whether a `url` field value is safe to render as an `href`: a site path,
+ * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects
+ * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
+ * backslashes (browsers read `/\host` as `//host`), whitespace and control
+ * characters, and anything over 2048 characters.
+ */
+export declare function isSafeLinkTarget(value: string): boolean;

package/dist/patterns.js

@@ -0,0 +1,105 @@
+/**
+ * A theme's key: lowercase kebab-case, at most 64 characters. The platform
+ * stores a merchant's text edits under it, so it is the theme's identity on the
+ * platform, and the server applies the same rule.
+ */
+export const THEME_KEY_PATTERN = /^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Type keys are lowercase kebab-case. */
+export const TYPE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * The page-document **surface** key — the address of a composed page
+ * (`home`, `product`, …; `area:<key>` is an area's document, and
+ * `page:<slug>` / `lp:<slug>` are reserved conventions).
+ *
+ * The server applies the same pattern. Module-level on purpose: it is part of
+ * the persisted-data contract,
+ * not of the package's curated public surface (`src/index.ts`).
+ */
+export const SURFACE_KEY_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+/** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
+export const PAGE_TYPES = [
+    "home",
+    "catalog",
+    "category",
+    "collection",
+    "product",
+    "page",
+    "landing",
+    "checkout",
+    "thankYou",
+    "trackOrder",
+];
+/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
+export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const COLLECTION_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * A `product` or `category` value: a handle or slug as the store's URLs use
+ * it. Merchants may type their own, so the rule only keeps out what cannot be
+ * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
+ * and `%`, and anything over 255 characters.
+ */
+export const RESOURCE_HANDLE_PATTERN = /^[^\s/\\?#%\u0000-\u001f\u007f]{1,255}$/u;
+/**
+ * A media object key in the store's bucket: a namespace and a name
+ * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
+ * that never start with a dot — so no `..`, no leading slash, no empty
+ * segment — and at most 512 characters.
+ */
+export const MEDIA_KEY_PATTERN = /^(?=.{3,512}$)[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)+$/;
+/**
+ * A BCP 47 language tag in canonical case: a 2–3 letter language, an optional
+ * 4-letter script, an optional 2-letter or 3-digit region (`ar`, `zgh`,
+ * `ar-DZ`, `zh-Hant-TW`, `es-419`). Canonical case keeps map keys unique:
+ * `fr` and `FR` can never both be present.
+ */
+const LOCALE_TAG_PATTERN = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/;
+export function isLocaleTag(value) {
+    return LOCALE_TAG_PATTERN.test(value);
+}
+/**
+ * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
+ * object with at least one entry, every key a locale tag, every value a string.
+ */
+export function isLocaleMap(value) {
+    return isLocaleMapOf(value, (entry) => typeof entry === "string");
+}
+/**
+ * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
+ * object with at least one entry, every key a locale tag.
+ */
+export function isLocaleMapOf(value, isEntry) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    return entries.length > 0 && entries.every(([key, entry]) => isLocaleTag(key) && isEntry(entry));
+}
+/**
+ * Whether a `url` field value is safe to render as an `href`: a site path,
+ * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects
+ * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
+ * backslashes (browsers read `/\host` as `//host`), whitespace and control
+ * characters, and anything over 2048 characters.
+ */
+export function isSafeLinkTarget(value) {
+    if (value.length === 0 || value.length > 2048)
+        return false;
+    if (/[\s\\\u0000-\u001f\u007f]/.test(value))
+        return false;
+    if (value.startsWith("/"))
+        return !value.startsWith("//");
+    if (value.startsWith("#") || value.startsWith("?"))
+        return true;
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+    if (scheme === "http" || scheme === "https") {
+        return /^https?:\/\/[a-z0-9.-]+(:\d{1,5})?([/?#]|$)/i.test(value);
+    }
+    if (scheme === "mailto" || scheme === "tel")
+        return value.length > scheme.length + 1;
+    return false;
+}

package/dist/preview-bridge.d.ts

@@ -1,3 +1,4 @@
+import { PREVIEW_SECTION_LOAD_EVENT } from "./lifecycle.js";
 export interface PreviewBridgeOptions {
     /** The editor's origin: the verified token's `editor` claim. */
     editorOrigin: string;
@@ -14,11 +15,12 @@ export interface PreviewBridge {
 }
 /**
  * Dispatched on `document` for each section the bridge swapped in, with the
- * instance id as `detail.id`: a section with browser behavior binds it again.
- * When the whole page was replaced instead, the bridge dispatches Astro's own
- * `astro:page-load`, as Astro's router does after it swaps a page.
+ * instance id as `detail.id`: a section with browser behavior binds it again
+ * (`bindEach` from `@wocart/theme/lifecycle` does). When the whole page was
+ * replaced instead, the bridge dispatches Astro's own `astro:page-load`, as
+ * Astro's router does after it swaps a page.
  */
-export declare const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+export { PREVIEW_SECTION_LOAD_EVENT };
 /**
  * Starts the bridge on a preview page. It posts `ready` with every marked
  * instance, `layout` as the page scrolls or resizes, `hover` as the merchant

package/dist/preview-bridge.js

@@ -14,13 +14,15 @@
  * from the framing window.
  */
 import { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";
+import { PREVIEW_SECTION_LOAD_EVENT } from "./lifecycle.js";
 /**
  * Dispatched on `document` for each section the bridge swapped in, with the
- * instance id as `detail.id`: a section with browser behavior binds it again.
- * When the whole page was replaced instead, the bridge dispatches Astro's own
- * `astro:page-load`, as Astro's router does after it swaps a page.
+ * instance id as `detail.id`: a section with browser behavior binds it again
+ * (`bindEach` from `@wocart/theme/lifecycle` does). When the whole page was
+ * replaced instead, the bridge dispatches Astro's own `astro:page-load`, as
+ * Astro's router does after it swaps a page.
  */
-export const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
+export { PREVIEW_SECTION_LOAD_EVENT };
 const ASTRO_PAGE_LOAD_EVENT = "astro:page-load";
 const SHOW_COMMENT = 0x80;
 const SHOW_TEXT = 0x4;

package/dist/preview-target.d.ts

@@ -0,0 +1,41 @@
+import type { PreviewDraft, StoreClient } from "@wocart/storefront/server";
+import type { SurfacePageType, ThemeDefinition } from "./types.js";
+/** What a preview renders. */
+export interface PreviewTarget {
+    /** The surface the page renders: the draft's own, or for an area the page it is shown on. */
+    surface: string;
+    /** That surface's page type, when it declares one. */
+    pageType: SurfacePageType | undefined;
+    /** The area the draft edits (`area:header`), or null when it edits the page itself. */
+    area: string | null;
+    /**
+     * The route's parameters for the resource a template previews — `{ handle }`
+     * for a product or collection, `{ slug }` for a category, page or landing
+     * page — or none when the store has none of its kind yet.
+     */
+    params: Record<string, string>;
+    /** The page's document: the draft's when the page is what is edited, else what the store saved (null for none). */
+    document: unknown;
+}
+/**
+ * What an editor's preview of `draft` renders, or null — answer 404 — for a
+ * surface the theme does not declare:
+ *
+ * - A template previews the resource the draft's `path` names
+ *   (`/products/robe`), else the store's first product, category, default
+ *   collection or text page. A store with none still previews: `params` is
+ *   empty and the template renders empty, so its sections can be arranged.
+ * - An area (the header, the footer) previews on the page its `path` names
+ *   when the theme composes that page, else on the home page.
+ * - The resource is chosen by the surface's `pageType`, never its key, so an
+ *   alternate (`product.compact`) previews like its base.
+ *
+ * ```astro
+ * ---
+ * const target = await previewTarget(theme, Astro.locals.preview.draft, Astro.locals.store.client);
+ * if (!target) return new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
+ * ---
+ * <Sections surface={target.surface} params={target.params} document={target.document} preview={target.area === null} />
+ * ```
+ */
+export declare function previewTarget(theme: ThemeDefinition, draft: PreviewDraft, client: StoreClient): Promise<PreviewTarget | null>;

package/dist/preview-target.js

@@ -0,0 +1,71 @@
+/**
+ * Which page an editor's preview shows, decided once for every theme: the
+ * surface a draft previews, the resource it previews it with, and the
+ * document it renders.
+ */
+import { DEFAULT_COLLECTION_HANDLES, matchStorefrontPath } from "@wocart/storefront";
+import { areaSurface } from "./blocks.js";
+/** The surface a page type is shown with: the one keyed by the type itself, else the first declaring it. */
+function surfaceFor(surfaces, pageType) {
+    return surfaces.find((surface) => surface.key === pageType) ?? surfaces.find((surface) => surface.pageType === pageType);
+}
+async function firstCollection(client) {
+    for (const handle of DEFAULT_COLLECTION_HANDLES)
+        if (await client.collections.get(handle))
+            return handle;
+    return undefined;
+}
+/** The resource a template of `pageType` previews: the one the path names, else the store's first of its kind. */
+async function resourceParams(pageType, named, client) {
+    const only = (key, value) => (value === undefined ? {} : { [key]: value });
+    switch (pageType) {
+        case "product":
+            return only("handle", named.handle ?? (await client.products.list({ limit: 1 }))[0]?.handle);
+        case "collection":
+            return only("handle", named.handle ?? (await firstCollection(client)));
+        case "category":
+            return only("slug", named.slug ?? (await client.categories.list())[0]?.slug);
+        case "page":
+            return only("slug", named.slug ?? (await client.config.get())?.pages[0]?.slug);
+        case "landing":
+            return only("slug", named.slug);
+        default:
+            return {};
+    }
+}
+/**
+ * What an editor's preview of `draft` renders, or null — answer 404 — for a
+ * surface the theme does not declare:
+ *
+ * - A template previews the resource the draft's `path` names
+ *   (`/products/robe`), else the store's first product, category, default
+ *   collection or text page. A store with none still previews: `params` is
+ *   empty and the template renders empty, so its sections can be arranged.
+ * - An area (the header, the footer) previews on the page its `path` names
+ *   when the theme composes that page, else on the home page.
+ * - The resource is chosen by the surface's `pageType`, never its key, so an
+ *   alternate (`product.compact`) previews like its base.
+ *
+ * ```astro
+ * ---
+ * const target = await previewTarget(theme, Astro.locals.preview.draft, Astro.locals.store.client);
+ * if (!target) return new Response(null, { status: 404, headers: { "Cache-Control": "no-store" } });
+ * ---
+ * <Sections surface={target.surface} params={target.params} document={target.document} preview={target.area === null} />
+ * ```
+ */
+export async function previewTarget(theme, draft, client) {
+    const surfaces = theme.surfaces ?? [];
+    const match = draft.path ? matchStorefrontPath(draft.path) : null;
+    const area = (theme.areas ?? []).some((candidate) => areaSurface(candidate.key) === draft.surface) ? draft.surface : null;
+    const shown = area === null ? surfaces.find((surface) => surface.key === draft.surface) : (match ? surfaceFor(surfaces, match.type) : undefined) ?? surfaceFor(surfaces, "home");
+    if (shown === undefined)
+        return null;
+    const pageType = shown.pageType;
+    const named = match !== null && match.type === pageType ? { ...match.params } : {};
+    const [params, document] = await Promise.all([
+        resourceParams(pageType, named, client),
+        area === null && draft.document !== undefined ? draft.document : client.pageData.get(shown.key),
+    ]);
+    return { surface: shown.key, pageType, area, params, document };
+}

package/dist/rich-text.js

@@ -7,7 +7,7 @@
  * value invalid. Rendering re-checks what it emits, so a value that skipped
  * validation still cannot produce markup.
  */
-import { isSafeLinkTarget } from "./schemas.js";
+import { isSafeLinkTarget } from "./patterns.js";
 /** Every format a rich-text field can allow, in the order an editor lists them. */
 export const RICH_TEXT_FORMATS = [
     "bold",

package/dist/schemas.d.ts

@@ -4,68 +4,8 @@
  */
 import { z } from "zod";
 import type { ComponentInstance, JsonValue } from "./types.js";
-/**
- * A theme's key: lowercase kebab-case, at most 64 characters. The platform
- * stores a merchant's text edits under it, so it is the theme's identity on the
- * platform, and the server applies the same rule.
- */
-export declare const THEME_KEY_PATTERN: RegExp;
-/** Type keys are lowercase kebab-case. */
-export declare const TYPE_KEY_PATTERN: RegExp;
-/**
- * The page-document **surface** key — the address of a composed page
- * (`home`, `product`, …; `area:<key>` is an area's document, and
- * `page:<slug>` / `lp:<slug>` are reserved conventions).
- *
- * The server applies the same pattern. Module-level on purpose: it is part of
- * the persisted-data contract,
- * not of the package's curated public surface (`src/index.ts`).
- */
-export declare const SURFACE_KEY_PATTERN: RegExp;
-/** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
-export declare const PAGE_TYPES: readonly ["home", "catalog", "category", "collection", "product", "page", "landing", "checkout", "thankYou"];
-/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
-export declare const COLOR_PATTERN: RegExp;
-/**
- * A `menu` field's value: the handle of one of the store's menus
- * (`main-menu`, `footer`). The server applies the same pattern to menu
- * handles; a menu that does not exist reads as no menu.
- */
-export declare const MENU_HANDLE_PATTERN: RegExp;
-export declare const COLLECTION_HANDLE_PATTERN: RegExp;
-/**
- * A `product` or `category` value: a handle or slug as the store's URLs use
- * it. Merchants may type their own, so the rule only keeps out what cannot be
- * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
- * and `%`, and anything over 255 characters.
- */
-export declare const RESOURCE_HANDLE_PATTERN: RegExp;
-/**
- * A media object key in the store's bucket: a namespace and a name
- * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
- * that never start with a dot — so no `..`, no leading slash, no empty
- * segment — and at most 512 characters.
- */
-export declare const MEDIA_KEY_PATTERN: RegExp;
-export declare function isLocaleTag(value: string): boolean;
-/**
- * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
- * object with at least one entry, every key a locale tag, every value a string.
- */
-export declare function isLocaleMap(value: unknown): value is Readonly<Record<string, string>>;
-/**
- * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
- * object with at least one entry, every key a locale tag.
- */
-export declare function isLocaleMapOf<T>(value: unknown, isEntry: (entry: unknown) => entry is T): value is Readonly<Record<string, T>>;
-/**
- * Whether a `url` field value is safe to render as an `href`: a site path,
- * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects
- * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
- * backslashes (browsers read `/\host` as `//host`), whitespace and control
- * characters, and anything over 2048 characters.
- */
-export declare function isSafeLinkTarget(value: string): boolean;
+import { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, MEDIA_KEY_PATTERN, MENU_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN } from "./patterns.js";
+export { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, MEDIA_KEY_PATTERN, MENU_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, };
 export declare const JsonValueSchema: z.ZodType<JsonValue>;
 export declare const ComponentInstanceSchema: z.ZodType<ComponentInstance>;
 /**

package/dist/schemas.js

@@ -3,110 +3,8 @@
  * validated. Definitions are typechecked code; page data is parsed data.
  */
 import { z } from "zod";
-/**
- * A theme's key: lowercase kebab-case, at most 64 characters. The platform
- * stores a merchant's text edits under it, so it is the theme's identity on the
- * platform, and the server applies the same rule.
- */
-export const THEME_KEY_PATTERN = /^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-/** Type keys are lowercase kebab-case. */
-export const TYPE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-/**
- * The page-document **surface** key — the address of a composed page
- * (`home`, `product`, …; `area:<key>` is an area's document, and
- * `page:<slug>` / `lp:<slug>` are reserved conventions).
- *
- * The server applies the same pattern. Module-level on purpose: it is part of
- * the persisted-data contract,
- * not of the package's curated public surface (`src/index.ts`).
- */
-export const SURFACE_KEY_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
-/** The platform page types a surface can render (`SurfacePageType`), mirrored from the storefront's page types. */
-export const PAGE_TYPES = [
-    "home",
-    "catalog",
-    "category",
-    "collection",
-    "product",
-    "page",
-    "landing",
-    "checkout",
-    "thankYou",
-];
-/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
-export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
-/**
- * A `menu` field's value: the handle of one of the store's menus
- * (`main-menu`, `footer`). The server applies the same pattern to menu
- * handles; a menu that does not exist reads as no menu.
- */
-export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-export const COLLECTION_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
-/**
- * A `product` or `category` value: a handle or slug as the store's URLs use
- * it. Merchants may type their own, so the rule only keeps out what cannot be
- * one URL path segment: whitespace, control characters, `/`, `\`, `?`, `#`
- * and `%`, and anything over 255 characters.
- */
-export const RESOURCE_HANDLE_PATTERN = /^[^\s/\\?#%\u0000-\u001f\u007f]{1,255}$/u;
-/**
- * A media object key in the store's bucket: a namespace and a name
- * (`products/3f2a9c.webp`), segments of letters, digits, `.`, `_` and `-`
- * that never start with a dot — so no `..`, no leading slash, no empty
- * segment — and at most 512 characters.
- */
-export const MEDIA_KEY_PATTERN = /^(?=.{3,512}$)[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)+$/;
-/**
- * A BCP 47 language tag in canonical case: a 2–3 letter language, an optional
- * 4-letter script, an optional 2-letter or 3-digit region (`ar`, `zgh`,
- * `ar-DZ`, `zh-Hant-TW`, `es-419`). Canonical case keeps map keys unique:
- * `fr` and `FR` can never both be present.
- */
-const LOCALE_TAG_PATTERN = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/;
-export function isLocaleTag(value) {
-    return LOCALE_TAG_PATTERN.test(value);
-}
-/**
- * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain
- * object with at least one entry, every key a locale tag, every value a string.
- */
-export function isLocaleMap(value) {
-    return isLocaleMapOf(value, (entry) => typeof entry === "string");
-}
-/**
- * Whether `value` is a per-language map whose entries pass `isEntry`: a plain
- * object with at least one entry, every key a locale tag.
- */
-export function isLocaleMapOf(value, isEntry) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    const entries = Object.entries(value);
-    return entries.length > 0 && entries.every(([key, entry]) => isLocaleTag(key) && isEntry(entry));
-}
-/**
- * Whether a `url` field value is safe to render as an `href`: a site path,
- * fragment or query, or an `http(s)`, `mailto` or `tel` URL. Rejects
- * `javascript:`/`data:` and every other scheme, protocol-relative `//host`,
- * backslashes (browsers read `/\host` as `//host`), whitespace and control
- * characters, and anything over 2048 characters.
- */
-export function isSafeLinkTarget(value) {
-    if (value.length === 0 || value.length > 2048)
-        return false;
-    if (/[\s\\\u0000-\u001f\u007f]/.test(value))
-        return false;
-    if (value.startsWith("/"))
-        return !value.startsWith("//");
-    if (value.startsWith("#") || value.startsWith("?"))
-        return true;
-    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
-    if (scheme === "http" || scheme === "https") {
-        return /^https?:\/\/[a-z0-9.-]+(:\d{1,5})?([/?#]|$)/i.test(value);
-    }
-    if (scheme === "mailto" || scheme === "tel")
-        return value.length > scheme.length + 1;
-    return false;
-}
+import { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, MEDIA_KEY_PATTERN, MENU_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, } from "./patterns.js";
+export { COLLECTION_HANDLE_PATTERN, COLOR_PATTERN, isLocaleMap, isLocaleMapOf, isLocaleTag, isSafeLinkTarget, MEDIA_KEY_PATTERN, MENU_HANDLE_PATTERN, PAGE_TYPES, RESOURCE_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, };
 export const JsonValueSchema = z.lazy(() => z.union([
     z.string(),
     z

package/dist/style.d.ts

@@ -29,7 +29,16 @@ export declare function styleClasses(value: StyleValue | undefined): string;
 export declare function themeStyleSheet(style: ThemeStyle | undefined): string;
 /** Why `value` is not a list of color schemes, or `null`. */
 export declare function colorSchemesProblem(value: unknown): string | null;
-/** The class that gives an element a color scheme, or `""` for what is not a scheme id. */
+/**
+ * The class every element wearing a color scheme carries, whichever scheme it
+ * is. A theme derives its own tokens from the roles on `:root, .wc-scheme`,
+ * so they follow the scheme of the nearest element that wears one.
+ */
+export declare const SCHEME_MARKER_CLASS = "wc-scheme";
+/**
+ * The classes that give an element a color scheme — `wc-scheme
+ * wc-scheme-<id>` — or `""` for what is not a scheme id.
+ */
 export declare function schemeClass(id: string | undefined): string;
 /**
  * The store's color schemes as CSS: each scheme's roles as custom properties

package/dist/style.js

@@ -11,7 +11,7 @@
  *   as custom properties on `.wc-scheme-<id>`, dropping anything that is not
  *   a scheme id and a hex color.
  */
-import { COLOR_PATTERN, isLocaleMap } from "./schemas.js";
+import { COLOR_PATTERN, isLocaleMap } from "./patterns.js";
 /** The platform's breakpoints, phone first, with the width each starts at. */
 export const STYLE_BREAKPOINTS = [
     ["base", 0],
@@ -203,9 +203,18 @@ export function colorSchemesProblem(value) {
     }
     return null;
 }
-/** The class that gives an element a color scheme, or `""` for what is not a scheme id. */
+/**
+ * The class every element wearing a color scheme carries, whichever scheme it
+ * is. A theme derives its own tokens from the roles on `:root, .wc-scheme`,
+ * so they follow the scheme of the nearest element that wears one.
+ */
+export const SCHEME_MARKER_CLASS = "wc-scheme";
+/**
+ * The classes that give an element a color scheme — `wc-scheme
+ * wc-scheme-<id>` — or `""` for what is not a scheme id.
+ */
 export function schemeClass(id) {
-    return typeof id === "string" && COLOR_SCHEME_ID_PATTERN.test(id) ? `wc-scheme-${id}` : "";
+    return typeof id === "string" && COLOR_SCHEME_ID_PATTERN.test(id) ? `${SCHEME_MARKER_CLASS} wc-scheme-${id}` : "";
 }
 const roleProperty = (role) => `--wc-color-${role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
 /**

package/dist/types.d.ts

@@ -7,8 +7,8 @@
  */
 import type { StoreClient } from "@wocart/storefront/server";
 import type { StoreConfig } from "@wocart/storefront";
-/** Every value page data may hold. */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
+/** Every value page data may hold. Lists may be read-only, as the rich-text format's are. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     [key: string]: JsonValue;
 };
 /** A JSON object, as stored in `ComponentInstance.props`. */
@@ -352,46 +352,47 @@ export interface ListItem {
 }
 export type RichTextMark = "bold" | "italic" | "underline" | "strike";
 /** A run of text. `link` is a safe link target, as a `url` field's. */
-export interface RichTextText {
+export type RichTextText = {
     type: "text";
     text: string;
     marks?: readonly RichTextMark[];
     link?: string;
-}
+};
 /** A line break inside a block. */
-export interface RichTextBreak {
+export type RichTextBreak = {
     type: "break";
-}
+};
 export type RichTextInline = RichTextText | RichTextBreak;
-export interface RichTextParagraph {
+export type RichTextParagraph = {
     type: "paragraph";
     content?: readonly RichTextInline[];
-}
+};
 /** Levels 2–4: the page owns its level-1 heading. */
-export interface RichTextHeading {
+export type RichTextHeading = {
     type: "heading";
     level: 2 | 3 | 4;
     content?: readonly RichTextInline[];
-}
-export interface RichTextListItem {
+};
+export type RichTextListItem = {
     content?: readonly RichTextInline[];
-}
-export interface RichTextList {
+};
+export type RichTextList = {
     type: "list";
     style: "bullet" | "ordered";
     items: readonly RichTextListItem[];
-}
+};
 export type RichTextBlock = RichTextParagraph | RichTextHeading | RichTextList;
 /**
  * A rich-text value. A closed format: anything not listed here is invalid, so
  * no stored value can carry markup, scripts or styles. `version` lets the
- * format grow; a reader rejects a version it does not know.
+ * format grow; a reader rejects a version it does not know. Like every
+ * rich-text type it is plain JSON, so a preset's props can hold one.
  */
-export interface RichTextDocument {
+export type RichTextDocument = {
     type: "doc";
     version: 1;
     content: readonly RichTextBlock[];
-}
+};
 /** A rich-text field's stored value: one document, or one per language. */
 export type RichTextValue = RichTextDocument | Readonly<Record<LocaleCode, RichTextDocument>>;
 /**
@@ -748,7 +749,7 @@ export interface AreaSpec {
  * The storefront's page types — what a URL means, with the paths the platform
  * owns. The same names as `StorefrontPageType` in `@wocart/storefront`.
  */
-export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou";
+export type SurfacePageType = "home" | "catalog" | "category" | "collection" | "product" | "page" | "landing" | "checkout" | "thankYou" | "trackOrder";
 /**
  * One component as data: a `ComponentDefinition` minus its runtime-only
  * implementation. `component` (the live component reference) and `load` (the

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export declare const THEME_SDK_VERSION = "2.1.0";
+export declare const THEME_SDK_VERSION = "2.3.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export const THEME_SDK_VERSION = "2.1.0";
+export const THEME_SDK_VERSION = "2.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -49,6 +49,14 @@
       "types": "./dist/preview-bridge.d.ts",
       "default": "./dist/preview-bridge.js"
     },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "default": "./dist/lifecycle.js"
+    },
+    "./messages": {
+      "types": "./dist/messages-entry.d.ts",
+      "default": "./dist/messages-entry.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -74,7 +82,7 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@wocart/storefront": "^1.14.0",
+    "@wocart/storefront": "^1.21.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {