@wocart/theme 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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.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.
+
+### Changed
+
+- `diffThemeManifests` treats a component that is no longer insertable, or that
+  is limited to a narrower list of surfaces, as a breaking change. Widening a
+  component's surfaces, or making it insertable again, is additive. Before, a
+  theme could narrow where a section sits without the release check noticing.
+
 ## 2.0.0 — 2026-10-20
 
 Blocks: components place other components inside them, some fixed by the

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/manifest-diff.js

@@ -82,6 +82,7 @@ export function diffThemeManifests(previous, next) {
 }
 function compareComponents(previous, next, path, breaking, additive) {
     compareFields(previous.fields, next.fields, `${path}.fields`, breaking, additive);
+    compareCapabilities(previous.capabilities, next.capabilities, `${path}.capabilities`, breaking, additive);
     const nextSlots = new Map(next.slots.map((slot) => [slot.name, slot]));
     for (const slot of previous.slots) {
         const after = nextSlots.get(slot.name);
@@ -108,6 +109,37 @@ function compareComponents(previous, next, path, breaking, additive) {
             additive(`${path}.fixed.${block.name}`, `fixed block "${block.name}" was added`);
     }
 }
+/**
+ * Where an editor may place a component. A narrowed rule is breaking: a section
+ * saved on a surface it no longer covers may stop rendering there, once a theme
+ * renders each surface from the components it covers, and it cannot be placed
+ * again. Widening only adds.
+ */
+function compareCapabilities(previous, next, path, breaking, additive) {
+    const wasInsertable = previous?.insertable !== false;
+    const isInsertable = next?.insertable !== false;
+    if (wasInsertable && !isInsertable)
+        breaking(`${path}.insertable`, "no longer insertable: an editor cannot place it again");
+    else if (!wasInsertable && isInsertable)
+        additive(`${path}.insertable`, "insertable again");
+    const before = previous?.surfaces;
+    const after = next?.surfaces;
+    if (after === undefined) {
+        if (before !== undefined)
+            additive(`${path}.surfaces`, "now on any surface");
+        return;
+    }
+    if (before === undefined) {
+        breaking(`${path}.surfaces`, `now only on ${after.join(", ")}`);
+        return;
+    }
+    const removed = before.filter((surface) => !after.includes(surface));
+    if (removed.length > 0)
+        breaking(`${path}.surfaces`, `no longer on ${removed.join(", ")}`);
+    const added = after.filter((surface) => !before.includes(surface));
+    if (added.length > 0)
+        additive(`${path}.surfaces`, `now also on ${added.join(", ")}`);
+}
 /** A list's cap and required types: a lower cap hides saved instances; a new requirement only adds. */
 function compareCaps(previous, next, path, what, breaking, additive) {
     if (next.max !== undefined && (previous.max === undefined || next.max < previous.max)) {

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"];
+/** 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;