@wocart/theme 1.6.0 → 2.0.0

package/dist/surface-document.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentInstance, PageData, PageDataIssue, ResolutionScope, ThemeDefinition } from "./types.js";
+/**
+ * The document with everything it must hold: the surface's required sections,
+ * each component's fixed blocks (stored, with an id derived from its owner and
+ * name) and each slot's required blocks — a hidden required or fixed block is
+ * shown again. Added ids are unique in the document. What was added or
+ * corrected is reported.
+ */
+export declare function completePage(theme: ThemeDefinition, page: PageData): {
+    page: PageData;
+    issues: PageDataIssue[];
+};
+/**
+ * An instance tree with its fixed and required blocks, as an editor inserts
+ * it: added ids are unique against `taken`, which receives every id of the
+ * tree. Never changes `instance`.
+ */
+export declare function completeInstance(theme: ThemeDefinition, instance: ComponentInstance, taken: Set<string>): ComponentInstance;
+/** Why the theme's default document rendered instead of the saved one. */
+export type SurfaceDocumentReason = 
+/** The store saved none. */
+"absent"
+/** What was saved is not a page document this SDK reads. */
+ | "invalid"
+/** The saved document is for another surface. */
+ | "other-surface"
+/** The saved document was composed for another theme. */
+ | "other-theme"
+/** None of the saved sections is in this theme's catalog. */
+ | "no-overlap";
+export interface SurfaceDocument {
+    /** The document to render, completed. */
+    page: PageData;
+    source: "saved" | "default";
+    /** `null` when the saved document rendered. */
+    reason: SurfaceDocumentReason | null;
+    /** The saved document's issues, then the default's when it rendered instead. */
+    issues: PageDataIssue[];
+}
+/**
+ * The page a surface or area renders: the saved document when this theme can
+ * render it, else the theme's default (`SurfaceSpec.document` or
+ * `AreaSpec.document`, or an empty page). A saved document that names another theme, or whose sections
+ * this catalog knows none of, renders the default — a theme switch must not
+ * leave an empty page. A deliberately emptied document renders empty. The
+ * result is completed (`completePage`), so required and fixed blocks render
+ * whatever was saved.
+ */
+export declare function resolveSurfaceDocument(theme: ThemeDefinition, surface: string, saved: unknown, scope?: ResolutionScope): SurfaceDocument;

package/dist/surface-document.js

@@ -0,0 +1,162 @@
+/**
+ * From what a store saved to the page that renders, for any surface or area
+ * (an area's document is the surface `area:<key>`):
+ * which document wins (the saved one, or the theme's default), and that
+ * document completed with every fixed and required block. A theme
+ * renders `resolveSurfaceDocument(...).page`; an editor edits
+ * `completePage(...).page`. Both are pure and never change their input.
+ */
+import { THEME_LIMITS, completeRequired, fixedBlockId, shippedDocument, slotCap, surfaceRules } from "./blocks.js";
+import { parsePageData, validatePageData } from "./page-data.js";
+/**
+ * The document with everything it must hold: the surface's required sections,
+ * each component's fixed blocks (stored, with an id derived from its owner and
+ * name) and each slot's required blocks — a hidden required or fixed block is
+ * shown again. Added ids are unique in the document. What was added or
+ * corrected is reported.
+ */
+export function completePage(theme, page) {
+    const next = structuredClone(page);
+    const issues = [];
+    const taken = new Set();
+    const collect = (node) => {
+        taken.add(node.id);
+        for (const child of node.children ?? [])
+            collect(child);
+        for (const list of Object.values(node.slots ?? {}))
+            for (const child of list)
+                collect(child);
+        for (const block of Object.values(node.fixed ?? {}))
+            collect(block);
+    };
+    next.sections.forEach(collect);
+    const spec = surfaceRules(theme, next.surface);
+    next.sections = completeRequired(next.sections, spec?.required, { id: next.surface, slot: "sections" }, "sections", issues, taken);
+    next.sections.forEach((section, index) => completeTree(theme, section, `sections[${index}]`, issues, taken, 0));
+    return { page: next, issues };
+}
+/**
+ * An instance tree with its fixed and required blocks, as an editor inserts
+ * it: added ids are unique against `taken`, which receives every id of the
+ * tree. Never changes `instance`.
+ */
+export function completeInstance(theme, instance, taken) {
+    const next = structuredClone(instance);
+    const collect = (node) => {
+        taken.add(node.id);
+        for (const child of node.children ?? [])
+            collect(child);
+        for (const list of Object.values(node.slots ?? {}))
+            for (const child of list)
+                collect(child);
+        for (const block of Object.values(node.fixed ?? {}))
+            collect(block);
+    };
+    collect(next);
+    completeTree(theme, next, "instance", [], taken, 0);
+    return next;
+}
+function uniqueId(base, taken) {
+    let id = base;
+    for (let n = 2; taken.has(id); n += 1)
+        id = `${base}~${n}`;
+    taken.add(id);
+    return id;
+}
+function completeTree(theme, node, path, issues, taken, depth) {
+    const definition = Object.hasOwn(theme.components, node.type) ? theme.components[node.type] : undefined;
+    if (definition === undefined || depth > THEME_LIMITS.depth)
+        return;
+    const declared = definition.fixed ?? [];
+    const stored = node.fixed ?? {};
+    for (const name of Object.keys(stored)) {
+        if (!declared.some((block) => block.name === name)) {
+            issues.push({ path: `${path}.fixed.${name}`, code: "unknown-fixed", message: `"${node.type}" places no fixed block "${name}"; removed` });
+        }
+    }
+    if (declared.length > 0) {
+        const fixed = {};
+        for (const { name, type } of declared) {
+            const entry = Object.hasOwn(stored, name) ? stored[name] : undefined;
+            if (entry !== undefined && entry.type === type) {
+                delete entry.hidden;
+                fixed[name] = entry;
+                continue;
+            }
+            if (entry !== undefined) {
+                issues.push({ path: `${path}.fixed.${name}.type`, code: "fixed-type-mismatch", message: `the fixed block "${name}" is a "${type}", not a "${entry.type}"; replaced by one with its defaults` });
+            }
+            fixed[name] = { id: uniqueId(fixedBlockId(node.id, name), taken), type };
+        }
+        node.fixed = fixed;
+    }
+    else if (node.fixed !== undefined) {
+        delete node.fixed;
+    }
+    for (const slot of definition.slots ?? []) {
+        if ((slot.required ?? []).length === 0)
+            continue;
+        const before = issues.length;
+        if (slot.name === "default") {
+            const list = [...(node.children ?? []), ...(node.slots?.default ?? [])];
+            const done = completeRequired(list, slot.required, { id: node.id, slot: "default" }, `${path}.children`, issues, taken);
+            if (issues.length === before)
+                continue;
+            node.children = done;
+            if (node.slots?.default !== undefined) {
+                delete node.slots.default;
+                if (Object.keys(node.slots).length === 0)
+                    delete node.slots;
+            }
+        }
+        else {
+            const list = node.slots !== undefined && Object.hasOwn(node.slots, slot.name) ? node.slots[slot.name] : [];
+            const done = completeRequired(list, slot.required, { id: node.id, slot: slot.name }, `${path}.slots.${slot.name}`, issues, taken);
+            if (issues.length === before)
+                continue;
+            node.slots = { ...node.slots, [slot.name]: done };
+        }
+    }
+    (node.children ?? []).forEach((child, index) => completeTree(theme, child, `${path}.children[${index}]`, issues, taken, depth + 1));
+    for (const [name, list] of Object.entries(node.slots ?? {})) {
+        list.forEach((child, index) => completeTree(theme, child, `${path}.slots.${name}[${index}]`, issues, taken, depth + 1));
+    }
+    for (const [name, block] of Object.entries(node.fixed ?? {}))
+        completeTree(theme, block, `${path}.fixed.${name}`, issues, taken, depth + 1);
+}
+/**
+ * The page a surface or area renders: the saved document when this theme can
+ * render it, else the theme's default (`SurfaceSpec.document` or
+ * `AreaSpec.document`, or an empty page). A saved document that names another theme, or whose sections
+ * this catalog knows none of, renders the default — a theme switch must not
+ * leave an empty page. A deliberately emptied document renders empty. The
+ * result is completed (`completePage`), so required and fixed blocks render
+ * whatever was saved.
+ */
+export function resolveSurfaceDocument(theme, surface, saved, scope = {}) {
+    const fallback = (reason, savedIssues) => {
+        const shipped = parsePageData(shippedDocument(theme, surface) ?? { version: 1, surface, sections: [] });
+        const page = shipped.page ?? { version: 1, surface, sections: [] };
+        return { page: completePage(theme, page).page, source: "default", reason, issues: [...savedIssues, ...shipped.issues] };
+    };
+    if (saved === null || saved === undefined)
+        return fallback("absent", []);
+    const checked = validatePageData(theme, saved, scope);
+    if (checked.page === null)
+        return fallback("invalid", checked.issues);
+    if (checked.page.surface !== surface) {
+        return fallback("other-surface", [
+            ...checked.issues,
+            { path: "surface", code: "envelope-invalid", message: `the saved document is for "${checked.page.surface}", not "${surface}"` },
+        ]);
+    }
+    if (checked.page.theme !== undefined && checked.page.theme.key !== theme.key)
+        return fallback("other-theme", checked.issues);
+    const sections = checked.page.sections;
+    if (sections.length > 0 && sections.every((section) => !Object.hasOwn(theme.components, section.type))) {
+        return fallback("no-overlap", checked.issues);
+    }
+    const cap = slotCap(surfaceRules(theme, surface), THEME_LIMITS.sections);
+    const renderable = { ...checked.page, sections: sections.slice(0, cap) };
+    return { page: completePage(theme, renderable).page, source: "saved", reason: null, issues: checked.issues };
+}

package/dist/types.d.ts

@@ -41,7 +41,28 @@ export interface ResolutionScope {
  * reader that meets a kind it does not know rejects the manifest rather than
  * render a value it cannot check.
  */
-export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu" | "collection" | "image" | "richtext" | "list" | "product" | "category";
+export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu" | "collection" | "image" | "richtext" | "list" | "product" | "category" | "style" | "colorScheme" | "colorSchemes" | "productList" | "collectionList";
+/** A value a condition compares against: a field's value is one of these when it is set. */
+export type ConditionValue = string | number | boolean | null;
+/**
+ * When a field applies, from the values of the fields beside it (the same
+ * component's, list item's or settings'): equal to a value, one of several,
+ * all or any of other conditions, or not one. A closed format, never an
+ * expression; `isFieldVisible` evaluates it. A hidden field keeps its value.
+ */
+export type FieldCondition = {
+    field: string;
+    equals: ConditionValue;
+} | {
+    field: string;
+    in: readonly ConditionValue[];
+} | {
+    all: readonly FieldCondition[];
+} | {
+    any: readonly FieldCondition[];
+} | {
+    not: FieldCondition;
+};
 interface FieldDefinitionBase {
     /** The exact prop name the component expects. */
     key: string;
@@ -50,6 +71,8 @@ interface FieldDefinitionBase {
     /** Editor-facing help text. */
     description?: LocalizedText;
     required?: boolean;
+    /** When an editor shows the field; absent: always. The renderer ignores it. */
+    visibleIf?: FieldCondition;
 }
 /**
  * `text` / `textarea`: a string that defaults from the content pack
@@ -83,6 +106,8 @@ export interface NumberFieldDefinition extends FieldDefinitionBase {
     min?: number;
     max?: number;
     step?: number;
+    /** How an editor shows it: a box to type in (default) or a slider, which needs `min`, `max` and `step`. */
+    display?: "input" | "slider";
 }
 /** `boolean`. */
 export interface BooleanFieldDefinition extends FieldDefinitionBase {
@@ -99,6 +124,8 @@ export interface SelectFieldDefinition extends FieldDefinitionBase {
     options: readonly string[];
     optionLabels?: Readonly<Record<string, LocalizedText>>;
     default?: string;
+    /** How an editor shows the options: a dropdown (default), radio buttons, or one segmented control. */
+    display?: "dropdown" | "radio" | "segmented";
 }
 /**
  * `url`: a link target an editor may set, safe to render as an `href`. Only a
@@ -178,9 +205,102 @@ export interface RichTextFieldDefinition extends FieldDefinitionBase {
     kind: "richtext";
     formats?: readonly RichTextFormat[];
     default?: RichTextValue;
+    /**
+     * `true`: one line of text — a single paragraph with marks and links, no
+     * headings or lists — rendered without a block element
+     * (`richTextToHtml(doc, { inline: true })`), for a title with one bold word.
+     */
+    inline?: boolean;
+}
+/**
+ * `productList`: hand-picked products, in order — product handles, each read
+ * with the storefront client's `products.get(handle)`. A renamed or deleted
+ * product reads as absent. At most `max` (at most 50).
+ */
+export interface ProductListFieldDefinition extends FieldDefinitionBase {
+    kind: "productList";
+    min?: number;
+    max?: number;
+    default?: readonly string[];
+}
+/** `collectionList`: hand-picked collections, in order — collection handles. At most `max` (at most 50). */
+export interface CollectionListFieldDefinition extends FieldDefinitionBase {
+    kind: "collectionList";
+    min?: number;
+    max?: number;
+    default?: readonly string[];
+}
+/** The platform's breakpoints, phone first: `base` everywhere, `md` from 768 px, `lg` from 1024 px. */
+export type Breakpoint = "base" | "md" | "lg";
+/** A value per breakpoint; a wider one inherits from the narrower. */
+export type Responsive<T> = {
+    base: T;
+} & Partial<Record<Exclude<Breakpoint, "base">, T>>;
+/** The platform's step names; a theme gives the ones it offers a size (`ThemeStyle.spacing`). */
+export type StyleStep = "s0" | "s1" | "s2" | "s3" | "s4" | "s5" | "s6" | "s7" | "s8" | "s9" | "s10" | "s11" | "s12";
+/** The widths a `size` panel offers besides `full`; a theme gives each a maximum (`ThemeStyle.widths`). */
+export type StyleWidth = "wide" | "content" | "narrow";
+/** What a `style` field may offer, each a closed set of CSS logical properties. */
+export type StylePanel = "spacing" | "layout" | "size";
+export interface StyleValue {
+    spacing?: {
+        paddingBlockStart?: Responsive<StyleStep>;
+        paddingBlockEnd?: Responsive<StyleStep>;
+        paddingInline?: Responsive<StyleStep>;
+        marginBlockStart?: Responsive<StyleStep>;
+        marginBlockEnd?: Responsive<StyleStep>;
+        gap?: Responsive<StyleStep>;
+    };
+    layout?: {
+        direction?: Responsive<"row" | "column">;
+        align?: Responsive<"start" | "center" | "end" | "stretch">;
+        justify?: Responsive<"start" | "center" | "end" | "between">;
+        wrap?: Responsive<boolean>;
+    };
+    size?: {
+        width?: Responsive<"full" | StyleWidth>;
+        minHeight?: Responsive<StyleStep>;
+    };
 }
-/** A field a list item may hold: any kind but `list` itself. */
-export type ListItemFieldDefinition = Exclude<FieldDefinition, ListFieldDefinition>;
+/**
+ * `style`: how a section or block sits on the page — spacing, layout, size —
+ * as steps and choices, never CSS. `styleClasses(value)` turns a value into
+ * the classes of the stylesheet the SDK makes from the theme's scales.
+ */
+export interface StyleFieldDefinition extends FieldDefinitionBase {
+    kind: "style";
+    panels: readonly StylePanel[];
+    default?: StyleValue;
+}
+/** The roles every color scheme gives a color, the same in every theme. */
+export type ColorRole = "background" | "text" | "heading" | "accent" | "button" | "buttonText" | "border";
+/** One named set of colors a section or block may wear. */
+export interface ColorScheme {
+    /** Lowercase letters, digits and dashes, at most 32; what a `colorScheme` value names. */
+    id: string;
+    name: LocalizedText;
+    colors: Readonly<Record<ColorRole, string>>;
+}
+/** `colorScheme`: which of the store's color schemes a section or block wears — a scheme's id. */
+export interface ColorSchemeFieldDefinition extends FieldDefinitionBase {
+    kind: "colorScheme";
+    default?: string;
+}
+/**
+ * `colorSchemes`: the store's color schemes, in order — a theme setting, at
+ * most one per theme. Its default is the theme's own schemes.
+ */
+export interface ColorSchemesFieldDefinition extends FieldDefinitionBase {
+    kind: "colorSchemes";
+    default: readonly ColorScheme[];
+}
+/** The sizes a theme gives the platform's style steps, in pixels. */
+export interface ThemeStyle {
+    spacing?: Readonly<Partial<Record<StyleStep, number>>>;
+    widths?: Readonly<Partial<Record<StyleWidth, number>>>;
+}
+/** A field a list item may hold: any kind but `list` itself and the store's color schemes. */
+export type ListItemFieldDefinition = Exclude<FieldDefinition, ListFieldDefinition | ColorSchemesFieldDefinition>;
 /**
  * `list`: repeatable items — trust badges, questions and answers, slides. Each
  * stored item is `{ id, props }`: the id is unique within the list, so
@@ -197,7 +317,7 @@ export interface ListFieldDefinition extends FieldDefinitionBase {
     /** The item field (`text` or `textarea`) an editor shows as each item's title. */
     itemLabel?: string;
 }
-export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition | CollectionFieldDefinition | ProductFieldDefinition | CategoryFieldDefinition | ImageFieldDefinition | RichTextFieldDefinition | ListFieldDefinition;
+export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition | CollectionFieldDefinition | ProductFieldDefinition | CategoryFieldDefinition | ImageFieldDefinition | RichTextFieldDefinition | ListFieldDefinition | StyleFieldDefinition | ColorSchemeFieldDefinition | ColorSchemesFieldDefinition | ProductListFieldDefinition | CollectionListFieldDefinition;
 /**
  * A stored image: the object's key in the store's media bucket
  * (`products/3f2a….webp`), never a URL, plus what the editor knows about it.
@@ -303,7 +423,45 @@ export interface SlotDefinition {
      * a slot.
      */
     allow?: readonly string[];
+    /** At most this many instances (1–50). Absent: the platform's cap (`THEME_LIMITS.slotInstances`). */
+    max?: number;
+    /**
+     * Types that must be present: an editor cannot remove, hide or move out the
+     * last `min` of them, nor insert past `max`, and a document that lacks them
+     * renders them anyway (`completePage`). Each type must be one `allow` takes.
+     */
+    required?: readonly RequiredBlock[];
 }
+/** A type a slot or surface must hold: at least `min` (default 1), at most `max`. */
+export interface RequiredBlock {
+    type: string;
+    min?: number;
+    max?: number;
+}
+/**
+ * Where an editor may place a component: `"section"` at the top level of a
+ * surface or area, `"block"` only inside a slot, `"both"` anywhere. Absent:
+ * anywhere. Enforced by the document operations, never at render.
+ */
+export type ComponentPlacement = "section" | "block" | "both";
+/**
+ * A block the component's own code places with `<Block of={blocks} name>`:
+ * an editor changes its fields and fills its slots, but never removes, moves,
+ * duplicates or hides it. It renders even when the document does not store it.
+ */
+export interface FixedBlockDefinition {
+    /** Lowercase kebab-case, unique among the component's fixed blocks. */
+    name: string;
+    /** The component type rendered there (a catalog key). */
+    type: string;
+    /** Editor-facing name; the type's label when absent. */
+    label?: LocalizedText;
+}
+/**
+ * What a component is to the platform. `"order-form"`: it places orders —
+ * every product surface must guarantee one (`validateThemeDefinition`).
+ */
+export type ComponentRole = "order-form";
 /**
  * What a component permits.
  *
@@ -420,6 +578,9 @@ export interface ComponentDefinition {
     load?: LoadFn;
     capabilities?: ComponentCapabilities;
     presets?: readonly ComponentPreset[];
+    placement?: ComponentPlacement;
+    fixed?: readonly FixedBlockDefinition[];
+    role?: ComponentRole;
 }
 /**
  * The value type one field resolves to. A select narrows to its option
@@ -435,6 +596,12 @@ export type FieldValue<F extends FieldDefinition> = F extends {
 } ? Option : F extends {
     kind: "image";
 } ? ResolvedImage : F extends {
+    kind: "style";
+} ? StyleValue : F extends {
+    kind: "colorSchemes";
+} ? ColorScheme[] : F extends {
+    kind: "productList" | "collectionList";
+} ? string[] : F extends {
     kind: "richtext";
 } ? RichTextDocument : F extends {
     kind: "list";
@@ -494,6 +661,8 @@ export interface ThemeDefinition {
      * offer only valid surfaces.
      */
     surfaces?: readonly SurfaceSpec[];
+    /** The parts every page shares, each a document of sections (`area:<key>`). */
+    areas?: readonly AreaSpec[];
     /**
      * The languages this theme's content packs cover (BCP 47), e.g.
      * `["ar", "fr", "en"]`. Declared, the validator requires every translated
@@ -509,6 +678,12 @@ export interface ThemeDefinition {
      * with `checkThemeSettings`. Setting keys are unique across all groups.
      */
     settings?: readonly SettingsGroup[];
+    /**
+     * The sizes this theme gives the platform's style steps and widths. A
+     * `style` field offers only what is given here; the SDK's stylesheet
+     * (`themeStylesEndpoint`) is made from it.
+     */
+    style?: ThemeStyle;
     /**
      * The theme's own text, one pack per language: what a `contentKey` field
      * shows until the merchant edits it, and the store-wide labels a merchant
@@ -548,6 +723,26 @@ export interface SurfaceSpec {
     pageType?: SurfacePageType;
     /** The theme's shipped document for this surface: what renders before the merchant saves one. */
     document?: PageData;
+    /** Top-level sections the surface must hold, as a slot's `required`. Alternates inherit their base's. */
+    required?: readonly RequiredBlock[];
+    /** At most this many top-level sections (1–50). Absent: `THEME_LIMITS.sections`. */
+    max?: number;
+}
+/**
+ * A part every page shares — a header, a footer — composed of sections like a
+ * page and edited once for the whole store. Its document is stored as the
+ * surface `area:<key>`.
+ */
+export interface AreaSpec {
+    /** Lowercase kebab-case, unique among the theme's areas. */
+    key: string;
+    label: LocalizedText;
+    /** The theme's shipped document for the area (surface `area:<key>`). */
+    document?: PageData;
+    /** Sections the area must hold, as a surface's `required`. */
+    required?: readonly RequiredBlock[];
+    /** At most this many sections (1–50). */
+    max?: number;
 }
 /**
  * The storefront's page types — what a URL means, with the paths the platform
@@ -574,6 +769,9 @@ export interface ComponentSpec {
     slots: readonly SlotDefinition[];
     capabilities?: ComponentCapabilities;
     presets: readonly ComponentPreset[];
+    placement?: ComponentPlacement;
+    fixed?: readonly FixedBlockDefinition[];
+    role?: ComponentRole;
 }
 /**
  * The serializable theme contract.
@@ -599,10 +797,14 @@ export interface ThemeManifest {
      */
     sdkVersion?: string;
     surfaces: readonly SurfaceSpec[];
+    /** The parts every page shares (possibly none). */
+    areas: readonly AreaSpec[];
     /** The languages the theme's packs cover (possibly none declared). */
     locales: readonly LocaleCode[];
     /** The theme's global settings (possibly none). */
     settings: readonly SettingsGroup[];
+    /** The sizes the theme gives the style steps (absent: none). */
+    style?: ThemeStyle;
     /** The theme's content packs, by language (possibly none). */
     content: Readonly<Record<LocaleCode, Readonly<Record<string, string>>>>;
     /** Whether the theme serves a preview route (`THEME_PREVIEW_PATH`). */
@@ -635,9 +837,15 @@ export interface ComponentInstance {
     props?: JsonObject;
     children?: ComponentInstance[];
     slots?: Record<string, ComponentInstance[]>;
+    /**
+     * The values of the component's fixed blocks, by the name its definition
+     * gives each. Absent entries render with their defaults.
+     */
+    fixed?: Record<string, ComponentInstance>;
     /**
      * `true`: kept in the document but not rendered — the merchant switched the
-     * section off. Its children are not rendered either.
+     * section off. Its children are not rendered either. Ignored on a fixed
+     * block and on a required block a slot would otherwise lack.
      */
     hidden?: boolean;
 }
@@ -669,7 +877,7 @@ export interface PageData {
         version: string;
     };
 }
-export type PageDataIssueCode = "envelope-invalid" | "instance-dropped" | "duplicate-id" | "unknown-type" | "unknown-prop" | "invalid-prop" | "missing-required-prop" | "undeclared-children" | "unknown-slot" | "slot-not-multiple" | "disallowed-child" | "invalid-provenance" | "theme-mismatch";
+export type PageDataIssueCode = "envelope-invalid" | "instance-dropped" | "duplicate-id" | "unknown-type" | "unknown-prop" | "invalid-prop" | "missing-required-prop" | "undeclared-children" | "unknown-slot" | "slot-not-multiple" | "disallowed-child" | "invalid-provenance" | "theme-mismatch" | "unknown-fixed" | "fixed-type-mismatch" | "missing-required-block" | "limit-exceeded";
 /** One reported degradation; `path` points into the document (e.g. `sections[0].props.limit`). */
 export interface PageDataIssue {
     path: string;
@@ -686,9 +894,11 @@ export interface ResolvedInstance {
     props: Record<string, unknown>;
     children: ComponentInstance[];
     slots: Record<string, ComponentInstance[]>;
+    /** Every fixed block the definition declares, stored or with its defaults, by name. */
+    fixed: Record<string, ComponentInstance>;
     issues: PageDataIssue[];
 }
-export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-settings" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load" | "invalid-preset" | "invalid-document" | "invalid-content";
+export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-settings" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load" | "invalid-preset" | "invalid-document" | "invalid-content" | "invalid-placement" | "invalid-fixed" | "invalid-role" | "order-form-not-guaranteed";
 export interface ThemeDefinitionIssue {
     path: string;
     code: ThemeDefinitionIssueCode;

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 = "1.6.0";
+export declare const THEME_SDK_VERSION = "2.0.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 = "1.6.0";
+export const THEME_SDK_VERSION = "2.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",
@@ -38,6 +38,9 @@
       "default": "./dist/astro/index.js"
     },
     "./astro/InstanceView.astro": "./dist/astro/InstanceView.astro",
+    "./astro/Blocks.astro": "./dist/astro/Blocks.astro",
+    "./astro/Block.astro": "./dist/astro/Block.astro",
+    "./astro/ThemeStyles.astro": "./dist/astro/ThemeStyles.astro",
     "./image-service": {
       "types": "./dist/image-service.d.ts",
       "default": "./dist/image-service.js"