@wocart/theme 1.6.0 → 2.1.0

package/dist/page-data.js

@@ -7,6 +7,7 @@
  * failed; a structurally invalid section is dropped with an issue; the
  * document itself is not rewritten by `validatePageData`.
  */
+import { THEME_LIMITS, completeRequired, slotCap, surfaceRules } from "./blocks.js";
 import { resolveInstance } from "./instances.js";
 import { ComponentInstanceSchema, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN } from "./schemas.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -30,14 +31,21 @@ export function parsePageData(input) {
         return envelopeFailure("`sections` must be an array of component instances");
     }
     const issues = [];
-    const seenIds = new Set();
+    const state = { seenIds: new Set(), count: 0, overCap: 0 };
     const sections = [];
     input.sections.forEach((raw, index) => {
-        const instance = sanitizeInstance(raw, `sections[${index}]`, seenIds, issues);
+        if (sections.length >= THEME_LIMITS.sections) {
+            issues.push({ path: `sections[${index}]`, code: "limit-exceeded", message: `a document holds at most ${THEME_LIMITS.sections} sections; dropped` });
+            return;
+        }
+        const instance = sanitizeInstance(raw, `sections[${index}]`, state, issues);
         if (instance !== null) {
             sections.push(instance);
         }
     });
+    if (state.overCap > 0) {
+        issues.push({ path: "sections", code: "limit-exceeded", message: `a document holds at most ${THEME_LIMITS.documentInstances} instances; ${state.overCap} dropped` });
+    }
     // The envelope is forward-compatible: unknown top-level keys are
     // carried through verbatim so a later writer can record metadata without a
     // `version` bump. `PageData` deliberately does not declare them — see its
@@ -112,13 +120,26 @@ export function validatePageData(theme, input, scope = {}) {
                 walk(child, `${path}.slots.${name}[${index}]`);
             });
         }
+        for (const [name, block] of Object.entries(resolved.fixed)) {
+            walk(block, `${path}.fixed.${name}`);
+        }
     };
-    parsed.page.sections.forEach((section, index) => {
+    const spec = surfaceRules(theme, parsed.page.surface);
+    const cap = slotCap(spec, THEME_LIMITS.sections);
+    if (parsed.page.sections.length > cap) {
+        issues.push({ path: "sections", code: "limit-exceeded", message: `surface "${parsed.page.surface}" holds at most ${cap} sections; ${parsed.page.sections.length - cap} are not rendered` });
+    }
+    const sections = completeRequired(parsed.page.sections.slice(0, cap), spec?.required, { id: parsed.page.surface, slot: "sections" }, "sections", issues);
+    sections.forEach((section, index) => {
         walk(section, `sections[${index}]`);
     });
     return { page: parsed.page, issues };
 }
-function sanitizeInstance(raw, path, seenIds, issues) {
+const subtreeSize = (instance) => 1 +
+    (instance.children ?? []).reduce((sum, child) => sum + subtreeSize(child), 0) +
+    Object.values(instance.slots ?? {}).reduce((sum, list) => sum + list.reduce((inner, child) => inner + subtreeSize(child), 0), 0) +
+    Object.values(instance.fixed ?? {}).reduce((sum, block) => sum + subtreeSize(block), 0);
+function sanitizeInstance(raw, path, state, issues) {
     const parsed = ComponentInstanceSchema.safeParse(raw);
     if (!parsed.success) {
         const detail = parsed.error.issues[0]?.message ?? "invalid shape";
@@ -129,15 +150,25 @@ function sanitizeInstance(raw, path, seenIds, issues) {
         });
         return null;
     }
-    return pruneDuplicateIds(parsed.data, path, seenIds, issues);
+    return pruneInstance(parsed.data, path, state, issues, 0);
 }
 /**
- * Deterministic rebuild with duplicate ids pruned (depth-first, first wins).
- * Property presence is preserved — a valid document round-trips unchanged;
- * pruning to empty (all duplicates dropped) keeps the empty container.
+ * Deterministic rebuild with duplicate ids pruned (depth-first, first wins)
+ * and the platform's caps applied: nesting deeper than `THEME_LIMITS.depth`
+ * and instances past `THEME_LIMITS.documentInstances` are dropped and
+ * reported. Property presence is preserved — a valid document round-trips
+ * unchanged; pruning to empty keeps the empty container.
  */
-function pruneDuplicateIds(instance, path, seenIds, issues) {
-    if (seenIds.has(instance.id)) {
+function pruneInstance(instance, path, state, issues, depth) {
+    if (depth > THEME_LIMITS.depth) {
+        issues.push({ path, code: "limit-exceeded", message: `nesting goes at most ${THEME_LIMITS.depth} levels below a section; dropped` });
+        return null;
+    }
+    if (state.count >= THEME_LIMITS.documentInstances) {
+        state.overCap += subtreeSize(instance);
+        return null;
+    }
+    if (state.seenIds.has(instance.id)) {
         issues.push({
             path: `${path}.id`,
             code: "duplicate-id",
@@ -145,7 +176,8 @@ function pruneDuplicateIds(instance, path, seenIds, issues) {
         });
         return null;
     }
-    seenIds.add(instance.id);
+    state.seenIds.add(instance.id);
+    state.count += 1;
     const pruned = { id: instance.id, type: instance.type };
     if (instance.props !== undefined) {
         pruned.props = instance.props;
@@ -153,29 +185,33 @@ function pruneDuplicateIds(instance, path, seenIds, issues) {
     if (instance.hidden !== undefined) {
         pruned.hidden = instance.hidden;
     }
-    if (instance.children !== undefined) {
-        const children = [];
-        instance.children.forEach((child, index) => {
-            const sane = pruneDuplicateIds(child, `${path}.children[${index}]`, seenIds, issues);
-            if (sane !== null) {
-                children.push(sane);
-            }
+    const pruneList = (list, listPath) => {
+        const sane = [];
+        list.forEach((child, index) => {
+            const kept = pruneInstance(child, `${listPath}[${index}]`, state, issues, depth + 1);
+            if (kept !== null)
+                sane.push(kept);
         });
-        pruned.children = children;
+        return sane;
+    };
+    if (instance.children !== undefined) {
+        pruned.children = pruneList(instance.children, `${path}.children`);
     }
     if (instance.slots !== undefined) {
         const slots = {};
         for (const [name, list] of Object.entries(instance.slots)) {
-            const saneList = [];
-            list.forEach((child, index) => {
-                const sane = pruneDuplicateIds(child, `${path}.slots.${name}[${index}]`, seenIds, issues);
-                if (sane !== null) {
-                    saneList.push(sane);
-                }
-            });
-            slots[name] = saneList;
+            slots[name] = pruneList(list, `${path}.slots.${name}`);
         }
         pruned.slots = slots;
     }
+    if (instance.fixed !== undefined) {
+        const fixed = {};
+        for (const [name, block] of Object.entries(instance.fixed)) {
+            const kept = pruneInstance(block, `${path}.fixed.${name}`, state, issues, depth + 1);
+            if (kept !== null)
+                fixed[name] = kept;
+        }
+        pruned.fixed = fixed;
+    }
     return pruned;
 }

package/dist/preview-bridge.js

@@ -260,11 +260,14 @@ export function startPreviewBridge(options) {
     /** What a `remove` or `hide` patch took off the page, to put back on `restore` or show. */
     const removed = new Map();
     const hiddenNodes = new Map();
-    const sectionsOf = () => marked.filter((entry) => entry.parent === null);
     const find = (id) => marked.find((entry) => entry.id === id);
-    /** Puts `nodes` at `index` among the document's sections other than `id`. */
-    const place = (nodes, id, index) => {
-        const others = sectionsOf().filter((entry) => entry.id !== id);
+    /**
+     * Puts `nodes` at `index` among the instances of `owner` (`null`: the
+     * page's sections) other than `id`. An empty slot has no place to find, so
+     * its move waits for the render.
+     */
+    const place = (nodes, id, index, owner) => {
+        const others = marked.filter((entry) => entry.parent === owner && entry.id !== id);
         if (!Number.isInteger(index) || index < 0 || index > others.length)
             return false;
         const before = others[index]?.start ?? others.at(-1)?.end.nextSibling ?? null;
@@ -287,11 +290,11 @@ export function startPreviewBridge(options) {
         const entry = find(patch.id);
         switch (patch.op) {
             case "move": {
-                if (entry === undefined || entry.parent !== null)
+                if (entry === undefined || entry.parent !== (patch.parent ?? null))
                     return [];
                 const nodes = withMarkers(entry);
                 if (nodes !== null)
-                    place(nodes, entry.id, patch.index);
+                    place(nodes, entry.id, patch.index, entry.parent);
                 return [];
             }
             case "duplicate": {
@@ -324,7 +327,7 @@ export function startPreviewBridge(options) {
             }
             case "restore": {
                 const nodes = removed.get(patch.id);
-                if (entry !== undefined || nodes === undefined || !place(nodes, patch.id, patch.index))
+                if (entry !== undefined || nodes === undefined || !place(nodes, patch.id, patch.index, patch.parent ?? null))
                     return [];
                 removed.delete(patch.id);
                 return [patch.id];

package/dist/preview-protocol.d.ts

@@ -64,12 +64,15 @@ export type PreviewMode = "edit" | "interactive";
  * does not know patches (before `@wocart/theme` 1.6.0) still shows every
  * change, a moment later.
  *
- * - `move`: a section of the document to `index` among the sections, counted
- *   once it has left its place (`moveInstance`).
+ * - `move`: an instance to `index` among its siblings, counted once it has
+ *   left its place (`moveInstance`): the document's sections, or with
+ *   `parent` the blocks of that instance. A move to another parent is left to
+ *   the render.
  * - `duplicate`: a copy of an instance right after it; `ids` maps every
  *   instance id inside it, its own included, to its copy's.
  * - `remove`: an instance and everything in it; `restore` puts what a
- *   `remove` took back, as a section of the document at `index`.
+ *   `remove` took back at `index` among the sections, or among `parent`'s
+ *   blocks.
  * - `hide`: an instance switched off (it shows nothing) or back on.
  * - `text`: inside an instance, text that reads `from` now reads `to` — a
  *   field's text as the theme prints it.
@@ -78,6 +81,7 @@ export type PreviewPatch = {
     op: "move";
     id: string;
     index: number;
+    parent?: string;
 } | {
     op: "duplicate";
     id: string;
@@ -89,6 +93,7 @@ export type PreviewPatch = {
     op: "restore";
     id: string;
     index: number;
+    parent?: string;
 } | {
     op: "hide";
     id: string;

package/dist/rich-text.d.ts

@@ -16,6 +16,8 @@ export interface RichTextHtmlOptions {
      * result is escaped; a target that fails the link rule never reaches it.
      */
     href?: (target: string) => string;
+    /** `true`: the first paragraph's text only, without a block element — for a field with `inline: true`. */
+    inline?: boolean;
 }
 /**
  * The document as HTML: `<p>`, `<h2>`–`<h4>`, `<ul>`/`<ol>`, `<strong>`, `<em>`,

package/dist/rich-text.js

@@ -157,6 +157,10 @@ const escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").r
 export function richTextToHtml(document, options = {}) {
     if (!isRecord(document) || !Array.isArray(document.content))
         return "";
+    if (options.inline === true) {
+        const first = document.content.find((block) => isRecord(block) && block.type === "paragraph");
+        return first === undefined ? "" : inlinesHtml(first.content, options);
+    }
     return document.content.map((block) => blockHtml(block, options)).join("");
 }
 function blockHtml(block, options) {

package/dist/schemas.d.ts

@@ -14,7 +14,8 @@ export declare const THEME_KEY_PATTERN: RegExp;
 export declare const TYPE_KEY_PATTERN: RegExp;
 /**
  * The page-document **surface** key — the address of a composed page
- * (`home` today; `page:<slug>` / `lp:<slug>` are reserved conventions).
+ * (`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,

package/dist/schemas.js

@@ -13,7 +13,8 @@ export const THEME_KEY_PATTERN = /^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 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` today; `page:<slug>` / `lp:<slug>` are reserved conventions).
+ * (`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,
@@ -126,6 +127,7 @@ export const ComponentInstanceSchema = z.lazy(() => z.object({
     props: z.exactOptional(z.record(z.string(), JsonValueSchema)),
     children: z.exactOptional(z.array(ComponentInstanceSchema)),
     slots: z.exactOptional(z.record(z.string(), z.array(ComponentInstanceSchema))),
+    fixed: z.exactOptional(z.record(z.string(), ComponentInstanceSchema)),
     hidden: z.exactOptional(z.boolean()),
 }));
 /**

package/dist/settings.js

@@ -11,6 +11,7 @@
  * content pack, for text) → absent.
  */
 import { checkStoredValue, ownValue, resolveField } from "./instances.js";
+import { styleSizeProblem } from "./style.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function declaredSettings(theme) {
     const fields = new Map();
@@ -75,8 +76,26 @@ export function checkThemeSettings(theme, values) {
             continue;
         }
         const checked = checkStoredValue(field, value);
-        if (!checked.ok)
+        if (!checked.ok) {
             issues.push({ path: `settings.${key}`, code: "invalid-setting", message: `"${key}" ${checked.message}` });
+            continue;
+        }
+        if (field.kind === "style") {
+            const problem = styleSizeProblem(theme.style, value);
+            if (problem !== null)
+                issues.push({ path: `settings.${key}`, code: "invalid-setting", message: `"${key}" ${problem}` });
+        }
+    }
+    const schemesField = [...declared.values()].find((field) => field.kind === "colorSchemes");
+    if (schemesField?.kind === "colorSchemes") {
+        const stored = ownValue(values, schemesField.key);
+        const schemes = stored !== undefined && checkStoredValue(schemesField, stored).ok ? stored : schemesField.default;
+        const ids = new Set(schemes.map((scheme) => scheme.id));
+        for (const [key, value] of Object.entries(values)) {
+            if (declared.get(key)?.kind === "colorScheme" && typeof value === "string" && !ids.has(value)) {
+                issues.push({ path: `settings.${key}`, code: "invalid-setting", message: `"${key}" names the color scheme "${value}", which the store does not have` });
+            }
+        }
     }
     return issues;
 }

package/dist/style.d.ts

@@ -0,0 +1,45 @@
+import type { ColorScheme, StylePanel, StyleValue, ThemeStyle } from "./types.js";
+/** The platform's breakpoints, phone first, with the width each starts at. */
+export declare const STYLE_BREAKPOINTS: readonly [readonly ["base", 0], readonly ["md", 768], readonly ["lg", 1024]];
+export declare const STYLE_STEPS: readonly ["s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7", "s8", "s9", "s10", "s11", "s12"];
+export declare const STYLE_WIDTHS: readonly ["wide", "content", "narrow"];
+export declare const STYLE_PANELS: readonly ["spacing", "layout", "size"];
+export declare const COLOR_ROLES: readonly ["background", "text", "heading", "accent", "button", "buttonText", "border"];
+/** A color scheme's id: what a `colorScheme` value names. */
+export declare const COLOR_SCHEME_ID_PATTERN: RegExp;
+/** The most color schemes a store keeps. */
+export declare const COLOR_SCHEMES_MAX = 24;
+/** Where a built theme serves the stylesheet of its style classes (`themeStylesEndpoint`). */
+export declare const THEME_STYLES_PATH = "/wocart-styles.css";
+/** Why `value` is not a style value a field offering `panels` may hold, or `null`. */
+export declare function styleValueProblem(panels: readonly StylePanel[], value: unknown): string | null;
+/**
+ * Why a theme's sizes leave part of a style value without a style: a step or
+ * width the theme does not size. What a writer stores must be sized; a
+ * reader renders an unsized value as no style.
+ */
+export declare function styleSizeProblem(style: ThemeStyle | undefined, value: StyleValue): string | null;
+/** The classes that give an element its style value, from the theme's stylesheet (`themeStyleSheet`). */
+export declare function styleClasses(value: StyleValue | undefined): string;
+/**
+ * Every class a theme's sizes allow, phone first: the base rules, then each
+ * wider breakpoint in its media query. A step or width the theme does not
+ * size has no class.
+ */
+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. */
+export declare function schemeClass(id: string | undefined): string;
+/**
+ * The store's color schemes as CSS: each scheme's roles as custom properties
+ * (`--wc-color-background`, `--wc-color-button-text`, …) with its background
+ * and text applied, on `.wc-scheme-<id>`. A scheme with a malformed id or
+ * color is left out whole.
+ */
+export declare function colorSchemeCss(schemes: readonly ColorScheme[] | undefined): string;
+/**
+ * The WCAG contrast ratio of two hex colors, from 1 to 21. Text needs 4.5 to
+ * meet AA; an editor warns below it. `NaN` for what is not a hex color.
+ */
+export declare function contrastRatio(a: string, b: string): number;

package/dist/style.js

@@ -0,0 +1,248 @@
+/**
+ * Style: how a section or block sits on the page and which colors it wears,
+ * stored as steps and choices — never CSS — and turned into CSS by the SDK.
+ *
+ * - A `style` value holds the platform's step names (`s0`…`s12`) and closed
+ *   choices per breakpoint; `styleClasses` gives its classes, and
+ *   `themeStyleSheet` makes the one stylesheet those classes come from, out of
+ *   the sizes the theme gives the steps. A value can therefore never carry a
+ *   property, a selector or a size the theme did not declare.
+ * - Colors come from the store's color schemes; `colorSchemeCss` writes them
+ *   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";
+/** The platform's breakpoints, phone first, with the width each starts at. */
+export const STYLE_BREAKPOINTS = [
+    ["base", 0],
+    ["md", 768],
+    ["lg", 1024],
+];
+export const STYLE_STEPS = ["s0", "s1", "s2", "s3", "s4", "s5", "s6", "s7", "s8", "s9", "s10", "s11", "s12"];
+export const STYLE_WIDTHS = ["wide", "content", "narrow"];
+export const STYLE_PANELS = ["spacing", "layout", "size"];
+export const COLOR_ROLES = ["background", "text", "heading", "accent", "button", "buttonText", "border"];
+/** A color scheme's id: what a `colorScheme` value names. */
+export const COLOR_SCHEME_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** The most color schemes a store keeps. */
+export const COLOR_SCHEMES_MAX = 24;
+/** Where a built theme serves the stylesheet of its style classes (`themeStylesEndpoint`). */
+export const THEME_STYLES_PATH = "/wocart-styles.css";
+const px = (size) => (size === undefined ? null : `${size}px`);
+const step = (property) => (value, style) => {
+    const size = px(style.spacing?.[value]);
+    return size === null ? null : `${property}:${size}`;
+};
+const choice = (property, map) => (value) => `${property}:${map[String(value)]}`;
+const PROPERTIES = {
+    spacing: {
+        paddingBlockStart: { prefix: "pbs", values: STYLE_STEPS, css: step("padding-block-start") },
+        paddingBlockEnd: { prefix: "pbe", values: STYLE_STEPS, css: step("padding-block-end") },
+        paddingInline: { prefix: "pi", values: STYLE_STEPS, css: step("padding-inline") },
+        marginBlockStart: { prefix: "mbs", values: STYLE_STEPS, css: step("margin-block-start") },
+        marginBlockEnd: { prefix: "mbe", values: STYLE_STEPS, css: step("margin-block-end") },
+        gap: { prefix: "gap", values: STYLE_STEPS, css: step("gap") },
+    },
+    layout: {
+        direction: { prefix: "dir", values: ["row", "column"], css: choice("flex-direction", { row: "row", column: "column" }) },
+        align: {
+            prefix: "items",
+            values: ["start", "center", "end", "stretch"],
+            css: choice("align-items", { start: "flex-start", center: "center", end: "flex-end", stretch: "stretch" }),
+        },
+        justify: {
+            prefix: "justify",
+            values: ["start", "center", "end", "between"],
+            css: choice("justify-content", { start: "flex-start", center: "center", end: "flex-end", between: "space-between" }),
+        },
+        wrap: { prefix: "wrap", values: [true, false], css: choice("flex-wrap", { true: "wrap", false: "nowrap" }) },
+    },
+    size: {
+        width: {
+            prefix: "w",
+            values: ["full", ...STYLE_WIDTHS],
+            css: (value, style) => {
+                if (value === "full")
+                    return "width:100%;max-width:none";
+                const size = px(style.widths?.[value]);
+                return size === null ? null : `width:100%;max-width:${size};margin-inline:auto`;
+            },
+        },
+        minHeight: { prefix: "mh", values: STYLE_STEPS, css: step("min-height") },
+    },
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const token = (value) => (value === true ? "on" : value === false ? "off" : value);
+const className = (breakpoint, prefix, value) => `wc-${breakpoint === "base" ? "" : `${breakpoint}-`}${prefix}-${token(value)}`;
+/** Why `value` is not a style value a field offering `panels` may hold, or `null`. */
+export function styleValueProblem(panels, value) {
+    if (!isRecord(value))
+        return "must be a style value: { spacing?, layout?, size? }";
+    for (const [panel, properties] of Object.entries(value)) {
+        if (!STYLE_PANELS.includes(panel) || !panels.includes(panel)) {
+            return `"${panel}" is not a panel this field offers (${panels.join(", ")})`;
+        }
+        if (!isRecord(properties))
+            return `\`${panel}\` must be an object of properties`;
+        const known = PROPERTIES[panel];
+        for (const [name, responsive] of Object.entries(properties)) {
+            const property = Object.hasOwn(known, name) ? known[name] : undefined;
+            if (property === undefined)
+                return `"${name}" is not a ${panel} property`;
+            if (!isRecord(responsive) || !Object.hasOwn(responsive, "base"))
+                return `\`${panel}.${name}\` must be { base, md?, lg? }`;
+            for (const [breakpoint, choice] of Object.entries(responsive)) {
+                if (!STYLE_BREAKPOINTS.some(([name]) => name === breakpoint))
+                    return `"${breakpoint}" is not a breakpoint (base, md, lg)`;
+                if (!property.values.includes(choice))
+                    return `\`${panel}.${name}.${breakpoint}\` must be one of ${property.values.join(", ")}`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Why a theme's sizes leave part of a style value without a style: a step or
+ * width the theme does not size. What a writer stores must be sized; a
+ * reader renders an unsized value as no style.
+ */
+export function styleSizeProblem(style, value) {
+    for (const [panel, properties] of Object.entries(value)) {
+        for (const [name, responsive] of Object.entries(properties ?? {})) {
+            const property = PROPERTIES[panel]?.[name];
+            if (property === undefined)
+                continue;
+            for (const choice of Object.values(responsive)) {
+                if (property.css(choice, style ?? {}) === null)
+                    return `"${String(choice)}" is not a size this theme gives (${panel}.${name})`;
+            }
+        }
+    }
+    return null;
+}
+/** The classes that give an element its style value, from the theme's stylesheet (`themeStyleSheet`). */
+export function styleClasses(value) {
+    if (!isRecord(value))
+        return "";
+    const classes = [];
+    for (const panel of STYLE_PANELS) {
+        const properties = value[panel];
+        if (!isRecord(properties))
+            continue;
+        let used = false;
+        for (const [name, property] of Object.entries(PROPERTIES[panel])) {
+            const responsive = properties[name];
+            if (!isRecord(responsive) || !Object.hasOwn(responsive, "base"))
+                continue;
+            for (const [breakpoint] of STYLE_BREAKPOINTS) {
+                const choice = responsive[breakpoint];
+                if (choice === undefined || !property.values.includes(choice))
+                    continue;
+                classes.push(className(breakpoint, property.prefix, choice));
+                used = true;
+            }
+        }
+        if (panel === "layout" && used)
+            classes.unshift("wc-flex");
+    }
+    return classes.join(" ");
+}
+/**
+ * Every class a theme's sizes allow, phone first: the base rules, then each
+ * wider breakpoint in its media query. A step or width the theme does not
+ * size has no class.
+ */
+export function themeStyleSheet(style) {
+    const sizes = style ?? {};
+    const rules = (breakpoint) => {
+        const out = breakpoint === "base" ? [".wc-flex{display:flex}"] : [];
+        for (const panel of STYLE_PANELS) {
+            for (const property of Object.values(PROPERTIES[panel])) {
+                for (const value of property.values) {
+                    const css = property.css(value, sizes);
+                    if (css !== null)
+                        out.push(`.${className(breakpoint, property.prefix, value)}{${css}}`);
+                }
+            }
+        }
+        return out.join("");
+    };
+    return STYLE_BREAKPOINTS.map(([breakpoint, from]) => (from === 0 ? rules(breakpoint) : `@media (min-width:${from}px){${rules(breakpoint)}}`)).join("");
+}
+/** Why `value` is not a list of color schemes, or `null`. */
+export function colorSchemesProblem(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return "must be a non-empty list of color schemes";
+    if (value.length > COLOR_SCHEMES_MAX)
+        return `holds at most ${COLOR_SCHEMES_MAX} color schemes`;
+    const ids = new Set();
+    for (const [index, scheme] of value.entries()) {
+        if (!isRecord(scheme))
+            return `scheme ${index} must be { id, name, colors }`;
+        const extra = Object.keys(scheme).find((key) => key !== "id" && key !== "name" && key !== "colors");
+        if (extra !== undefined)
+            return `scheme ${index} has an unknown key "${extra}"`;
+        if (typeof scheme.id !== "string" || !COLOR_SCHEME_ID_PATTERN.test(scheme.id))
+            return `scheme ${index} needs an \`id\` of lowercase letters, digits and dashes`;
+        if (ids.has(scheme.id))
+            return `scheme ${index} repeats the id "${scheme.id}"`;
+        ids.add(scheme.id);
+        const name = scheme.name;
+        if (!((typeof name === "string" && name.length > 0) || isLocaleMap(name)))
+            return `scheme "${scheme.id}" needs a \`name\``;
+        if (!isRecord(scheme.colors))
+            return `scheme "${scheme.id}" needs \`colors\``;
+        for (const role of COLOR_ROLES) {
+            const color = scheme.colors[role];
+            if (typeof color !== "string" || !COLOR_PATTERN.test(color))
+                return `scheme "${scheme.id}" needs a hex color for "${role}"`;
+        }
+        const unknown = Object.keys(scheme.colors).find((role) => !COLOR_ROLES.includes(role));
+        if (unknown !== undefined)
+            return `scheme "${scheme.id}" has an unknown role "${unknown}"`;
+    }
+    return null;
+}
+/** The class that gives an element a color scheme, 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}` : "";
+}
+const roleProperty = (role) => `--wc-color-${role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+/**
+ * The store's color schemes as CSS: each scheme's roles as custom properties
+ * (`--wc-color-background`, `--wc-color-button-text`, …) with its background
+ * and text applied, on `.wc-scheme-<id>`. A scheme with a malformed id or
+ * color is left out whole.
+ */
+export function colorSchemeCss(schemes) {
+    return (schemes ?? [])
+        .filter((scheme) => isRecord(scheme) &&
+        typeof scheme.id === "string" &&
+        COLOR_SCHEME_ID_PATTERN.test(scheme.id) &&
+        isRecord(scheme.colors) &&
+        COLOR_ROLES.every((role) => typeof scheme.colors[role] === "string" && COLOR_PATTERN.test(scheme.colors[role])))
+        .map((scheme) => {
+        const roles = COLOR_ROLES.map((role) => `${roleProperty(role)}:${scheme.colors[role]}`).join(";");
+        return `.wc-scheme-${scheme.id}{${roles};background-color:var(--wc-color-background);color:var(--wc-color-text)}`;
+    })
+        .join("");
+}
+const channel = (value) => {
+    const unit = value / 255;
+    return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+};
+function luminance(hex) {
+    const digits = hex.length === 4 ? [...hex.slice(1)].map((digit) => digit + digit).join("") : hex.slice(1);
+    const [r, g, b] = [0, 2, 4].map((at) => parseInt(digits.slice(at, at + 2), 16));
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/**
+ * The WCAG contrast ratio of two hex colors, from 1 to 21. Text needs 4.5 to
+ * meet AA; an editor warns below it. `NaN` for what is not a hex color.
+ */
+export function contrastRatio(a, b) {
+    if (!COLOR_PATTERN.test(a) || !COLOR_PATTERN.test(b))
+        return Number.NaN;
+    const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (light + 0.05) / (dark + 0.05);
+}