@wocart/theme 2.0.0 → 2.2.0

package/dist/patterns.js

@@ -0,0 +1,104 @@
+/**
+ * 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;
+}

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>>;
 /**

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.0.0";
+export declare const THEME_SDK_VERSION = "2.2.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.0.0";
+export const THEME_SDK_VERSION = "2.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "2.0.0",
+  "version": "2.2.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.20.0",
     "astro": "^7.0.0"
   },
   "peerDependenciesMeta": {