@wocart/theme 1.4.0 → 1.5.0

package/dist/manifest.d.ts

@@ -9,9 +9,15 @@
  * so the manifest and assembly validators cannot disagree.
  */
 import { z } from "zod";
-import type { ThemeDefinition, ThemeManifest, ThemeManifestResult } from "./types.js";
+import type { PageData, PresetInstance, SurfacePageType, RichTextFormat, RichTextValue, ThemeDefinition, ThemeManifest, ThemeManifestResult } from "./types.js";
 /** Version of the manifest schema and its interpretation (not the theme's). */
 export declare const THEME_MANIFEST_CONTRACT_VERSION: 1;
+/**
+ * Where a built theme serves its manifest: a prerendered page at this path
+ * (`src/pages/wocart-theme.json.ts`), so the file is part of every build and
+ * a release can read it without running the theme.
+ */
+export declare const THEME_MANIFEST_PATH = "/wocart-theme.json";
 /** Derive the data-only manifest from a theme. `component` and `load` are dropped. */
 export declare function themeManifest(theme: ThemeDefinition): ThemeManifest;
 /**
@@ -23,9 +29,12 @@ export declare const ThemeManifestSchema: z.ZodObject<{
     contractVersion: z.ZodLiteral<1>;
     key: z.ZodString;
     version: z.ZodString;
+    sdkVersion: z.ZodExactOptional<z.ZodString>;
     surfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        pageType: z.ZodExactOptional<z.ZodCustom<SurfacePageType, SurfacePageType>>;
+        document: z.ZodExactOptional<z.ZodCustom<PageData, PageData>>;
     }, z.core.$strip>>>;
     locales: z.ZodDefault<z.ZodArray<z.ZodString>>;
     settings: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -56,6 +65,7 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             default: z.ZodExactOptional<z.ZodNumber>;
             min: z.ZodExactOptional<z.ZodNumber>;
             max: z.ZodExactOptional<z.ZodNumber>;
+            step: z.ZodExactOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -70,37 +80,110 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             required: z.ZodExactOptional<z.ZodBoolean>;
             kind: z.ZodLiteral<"select">;
             options: z.ZodArray<z.ZodString>;
+            optionLabels: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
             default: z.ZodExactOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
+        }, z.core.$strip>, ...z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"url">;
+            kind: z.ZodLiteral<"category" | "collection" | "color" | "menu" | "product" | "url">;
             default: z.ZodExactOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
+        }, z.core.$strip>[], z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"color">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"image">;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"menu">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"richtext">;
+            formats: z.ZodExactOptional<z.ZodArray<z.ZodCustom<RichTextFormat, RichTextFormat>>>;
+            default: z.ZodExactOptional<z.ZodCustom<RichTextValue, RichTextValue>>;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"collection">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"list">;
+            fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                contentKey: z.ZodExactOptional<z.ZodString>;
+                default: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                kind: z.ZodLiteral<"text">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                contentKey: z.ZodExactOptional<z.ZodString>;
+                default: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                kind: z.ZodLiteral<"textarea">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"number">;
+                default: z.ZodExactOptional<z.ZodNumber>;
+                min: z.ZodExactOptional<z.ZodNumber>;
+                max: z.ZodExactOptional<z.ZodNumber>;
+                step: z.ZodExactOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"boolean">;
+                default: z.ZodExactOptional<z.ZodBoolean>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"select">;
+                options: z.ZodArray<z.ZodString>;
+                optionLabels: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
+                default: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strip>, ...z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"category" | "collection" | "color" | "menu" | "product" | "url">;
+                default: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strip>[], z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"image">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"richtext">;
+                formats: z.ZodExactOptional<z.ZodArray<z.ZodCustom<RichTextFormat, RichTextFormat>>>;
+                default: z.ZodExactOptional<z.ZodCustom<RichTextValue, RichTextValue>>;
+            }, z.core.$strip>], "kind">>;
+            min: z.ZodExactOptional<z.ZodNumber>;
+            max: z.ZodExactOptional<z.ZodNumber>;
+            default: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                props: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./types.js").JsonValue, unknown, z.core.$ZodTypeInternals<import("./types.js").JsonValue, unknown>>>>;
+            }, z.core.$strip>>>;
+            itemLabel: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>;
+    content: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
+    preview: z.ZodDefault<z.ZodBoolean>;
     components: z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodString;
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -130,6 +213,7 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             default: z.ZodExactOptional<z.ZodNumber>;
             min: z.ZodExactOptional<z.ZodNumber>;
             max: z.ZodExactOptional<z.ZodNumber>;
+            step: z.ZodExactOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -144,35 +228,106 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             required: z.ZodExactOptional<z.ZodBoolean>;
             kind: z.ZodLiteral<"select">;
             options: z.ZodArray<z.ZodString>;
+            optionLabels: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
             default: z.ZodExactOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
+        }, z.core.$strip>, ...z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"url">;
+            kind: z.ZodLiteral<"category" | "collection" | "color" | "menu" | "product" | "url">;
             default: z.ZodExactOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
+        }, z.core.$strip>[], z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"color">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"image">;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"menu">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"richtext">;
+            formats: z.ZodExactOptional<z.ZodArray<z.ZodCustom<RichTextFormat, RichTextFormat>>>;
+            default: z.ZodExactOptional<z.ZodCustom<RichTextValue, RichTextValue>>;
         }, z.core.$strip>, z.ZodObject<{
             key: z.ZodString;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
             required: z.ZodExactOptional<z.ZodBoolean>;
-            kind: z.ZodLiteral<"collection">;
-            default: z.ZodExactOptional<z.ZodString>;
+            kind: z.ZodLiteral<"list">;
+            fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                contentKey: z.ZodExactOptional<z.ZodString>;
+                default: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                kind: z.ZodLiteral<"text">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                contentKey: z.ZodExactOptional<z.ZodString>;
+                default: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                kind: z.ZodLiteral<"textarea">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"number">;
+                default: z.ZodExactOptional<z.ZodNumber>;
+                min: z.ZodExactOptional<z.ZodNumber>;
+                max: z.ZodExactOptional<z.ZodNumber>;
+                step: z.ZodExactOptional<z.ZodNumber>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"boolean">;
+                default: z.ZodExactOptional<z.ZodBoolean>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"select">;
+                options: z.ZodArray<z.ZodString>;
+                optionLabels: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
+                default: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strip>, ...z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"category" | "collection" | "color" | "menu" | "product" | "url">;
+                default: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strip>[], z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"image">;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+                description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+                required: z.ZodExactOptional<z.ZodBoolean>;
+                kind: z.ZodLiteral<"richtext">;
+                formats: z.ZodExactOptional<z.ZodArray<z.ZodCustom<RichTextFormat, RichTextFormat>>>;
+                default: z.ZodExactOptional<z.ZodCustom<RichTextValue, RichTextValue>>;
+            }, z.core.$strip>], "kind">>;
+            min: z.ZodExactOptional<z.ZodNumber>;
+            max: z.ZodExactOptional<z.ZodNumber>;
+            default: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                props: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./types.js").JsonValue, unknown, z.core.$ZodTypeInternals<import("./types.js").JsonValue, unknown>>>>;
+            }, z.core.$strip>>>;
+            itemLabel: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strip>], "kind">>>;
         slots: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
@@ -181,7 +336,16 @@ export declare const ThemeManifestSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         capabilities: z.ZodExactOptional<z.ZodObject<{
             insertable: z.ZodExactOptional<z.ZodBoolean>;
+            surfaces: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        presets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+            description: z.ZodExactOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+            props: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./types.js").JsonValue, unknown, z.core.$ZodTypeInternals<import("./types.js").JsonValue, unknown>>>>;
+            children: z.ZodExactOptional<z.ZodArray<z.ZodType<PresetInstance, unknown, z.core.$ZodTypeInternals<PresetInstance, unknown>>>>;
+            slots: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodType<PresetInstance, unknown, z.core.$ZodTypeInternals<PresetInstance, unknown>>>>>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
@@ -190,3 +354,12 @@ export declare const ThemeManifestSchema: z.ZodObject<{
  * returns the manifest with an `invalid-version` issue.
  */
 export declare function validateThemeManifest(input: unknown): ThemeManifestResult;
+/**
+ * A manifest as a catalog every data function takes — `createInstance`,
+ * `instantiatePreset`, the document operations, `checkPageData`,
+ * `validatePageData`, `resolveThemeSettings`, `checkThemeSettings` — so an
+ * editor or a tool works from a theme's manifest alone, never its code.
+ * Components carry no implementation (`component: null`): the catalog
+ * describes and checks; it does not render.
+ */
+export declare function manifestCatalog(manifest: ThemeManifest): ThemeDefinition;

package/dist/manifest.js

@@ -10,8 +10,16 @@
  */
 import { z } from "zod";
 import { validateThemeDefinition } from "./definitions.js";
+import { JsonValueSchema } from "./schemas.js";
+import { THEME_SDK_VERSION } from "./version.js";
 /** Version of the manifest schema and its interpretation (not the theme's). */
 export const THEME_MANIFEST_CONTRACT_VERSION = 1;
+/**
+ * Where a built theme serves its manifest: a prerendered page at this path
+ * (`src/pages/wocart-theme.json.ts`), so the file is part of every build and
+ * a release can read it without running the theme.
+ */
+export const THEME_MANIFEST_PATH = "/wocart-theme.json";
 const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 // ── Derivation ───────────────────────────────────────────────────────────────
@@ -21,12 +29,17 @@ export function themeManifest(theme) {
         contractVersion: THEME_MANIFEST_CONTRACT_VERSION,
         key: theme.key,
         version: theme.version,
+        sdkVersion: THEME_SDK_VERSION,
         surfaces: (theme.surfaces ?? []).map((surface) => ({
             key: surface.key,
             label: copyData(surface.label),
+            ...(surface.pageType === undefined ? {} : { pageType: surface.pageType }),
+            ...(surface.document === undefined ? {} : { document: copyData(surface.document) }),
         })),
         locales: [...(theme.locales ?? [])],
         settings: (theme.settings ?? []).map((group) => copyData(group)),
+        content: copyData(theme.content ?? {}),
+        preview: theme.preview === true,
         components: Object.fromEntries(Object.entries(theme.components).map(([key, definition]) => [
             key,
             componentSpec(definition),
@@ -43,6 +56,7 @@ function componentSpec(definition) {
         ...(definition.capabilities === undefined
             ? {}
             : { capabilities: copyData(definition.capabilities) }),
+        presets: (definition.presets ?? []).map((preset) => copyData(preset)),
     };
 }
 /**
@@ -67,7 +81,7 @@ const TextFieldSchema = z.object({
     contentKey: z.exactOptional(z.string()),
     default: z.exactOptional(LocalizedTextSchema),
 });
-const FieldSchema = z.discriminatedUnion("kind", [
+const ScalarFieldSchemas = [
     TextFieldSchema.extend({ kind: z.literal("text") }),
     TextFieldSchema.extend({ kind: z.literal("textarea") }),
     z.object({
@@ -76,6 +90,7 @@ const FieldSchema = z.discriminatedUnion("kind", [
         default: z.exactOptional(z.number()),
         min: z.exactOptional(z.number()),
         max: z.exactOptional(z.number()),
+        step: z.exactOptional(z.number()),
     }),
     z.object({
         ...FieldCommonSchema,
@@ -86,29 +101,45 @@ const FieldSchema = z.discriminatedUnion("kind", [
         ...FieldCommonSchema,
         kind: z.literal("select"),
         options: z.array(z.string()),
+        optionLabels: z.exactOptional(z.record(z.string(), LocalizedTextSchema)),
         default: z.exactOptional(z.string()),
     }),
-    z.object({
+    ...["url", "color", "menu", "collection", "product", "category"].map((kind) => z.object({
         ...FieldCommonSchema,
-        kind: z.literal("url"),
+        kind: z.literal(kind),
         default: z.exactOptional(z.string()),
-    }),
+    })),
     z.object({
         ...FieldCommonSchema,
-        kind: z.literal("color"),
-        default: z.exactOptional(z.string()),
+        kind: z.literal("image"),
     }),
     z.object({
         ...FieldCommonSchema,
-        kind: z.literal("menu"),
-        default: z.exactOptional(z.string()),
+        kind: z.literal("richtext"),
+        formats: z.exactOptional(z.array(z.custom((value) => typeof value === "string"))),
+        // The document's own rules are relational; `validateThemeDefinition` checks them.
+        default: z.exactOptional(z.custom((value) => typeof value === "object" && value !== null)),
     }),
+];
+const ItemFieldSchema = z.discriminatedUnion("kind", [...ScalarFieldSchemas]);
+const FieldSchema = z.discriminatedUnion("kind", [
+    ...ScalarFieldSchemas,
     z.object({
         ...FieldCommonSchema,
-        kind: z.literal("collection"),
-        default: z.exactOptional(z.string()),
+        kind: z.literal("list"),
+        fields: z.array(ItemFieldSchema),
+        min: z.exactOptional(z.number()),
+        max: z.exactOptional(z.number()),
+        default: z.exactOptional(z.array(z.object({ id: z.string(), props: z.exactOptional(z.record(z.string(), JsonValueSchema)) }))),
+        itemLabel: z.exactOptional(z.string()),
     }),
 ]);
+const PresetInstanceSchema = z.lazy(() => z.object({
+    type: z.string(),
+    props: z.exactOptional(z.record(z.string(), JsonValueSchema)),
+    children: z.exactOptional(z.array(PresetInstanceSchema)),
+    slots: z.exactOptional(z.record(z.string(), z.array(PresetInstanceSchema))),
+}));
 const ComponentSpecSchema = z.object({
     type: z.string(),
     label: LocalizedTextSchema,
@@ -121,7 +152,20 @@ const ComponentSpecSchema = z.object({
         allow: z.exactOptional(z.array(z.string())),
     }))
         .default([]),
-    capabilities: z.exactOptional(z.object({ insertable: z.exactOptional(z.boolean()) })),
+    capabilities: z.exactOptional(z.object({
+        insertable: z.exactOptional(z.boolean()),
+        surfaces: z.exactOptional(z.array(z.string())),
+    })),
+    presets: z
+        .array(z.object({
+        key: z.string(),
+        label: LocalizedTextSchema,
+        description: z.exactOptional(LocalizedTextSchema),
+        props: z.exactOptional(z.record(z.string(), JsonValueSchema)),
+        children: z.exactOptional(z.array(PresetInstanceSchema)),
+        slots: z.exactOptional(z.record(z.string(), z.array(PresetInstanceSchema))),
+    }))
+        .default([]),
 });
 /**
  * The manifest's structural shape. Unknown keys are stripped (the forward-compat
@@ -132,13 +176,22 @@ export const ThemeManifestSchema = z.object({
     contractVersion: z.literal(THEME_MANIFEST_CONTRACT_VERSION),
     key: z.string(),
     version: z.string(),
+    sdkVersion: z.exactOptional(z.string()),
     surfaces: z
-        .array(z.object({ key: z.string(), label: LocalizedTextSchema }))
+        .array(z.object({
+        key: z.string(),
+        label: LocalizedTextSchema,
+        pageType: z.exactOptional(z.custom((value) => typeof value === "string")),
+        // A page document's own rules are checked by `validateThemeDefinition` on the probe.
+        document: z.exactOptional(z.custom((value) => isRecord(value))),
+    }))
         .default([]),
     locales: z.array(z.string()).default([]),
     settings: z
         .array(z.object({ key: z.string(), label: LocalizedTextSchema, fields: z.array(FieldSchema) }))
         .default([]),
+    content: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+    preview: z.boolean().default(false),
     components: z.record(z.string(), ComponentSpecSchema),
 });
 // ── Validation ───────────────────────────────────────────────────────────────
@@ -168,7 +221,7 @@ export function validateThemeManifest(input) {
         return { manifest: null, issues };
     }
     const manifest = parsed.data;
-    const issues = validateThemeDefinition(probeOf(manifest)).map((issue) => ({
+    const issues = validateThemeDefinition(manifestCatalog(manifest)).map((issue) => ({
         path: issue.path,
         code: issue.code === "type-mismatch" ? "type-mismatch" : codeAt(issue.path),
         message: issue.message,
@@ -198,6 +251,8 @@ function codeAt(path) {
         return "invalid-surface";
     if (path === "settings" || path.startsWith("settings["))
         return "invalid-settings";
+    if (path === "content" || path.startsWith("content."))
+        return "invalid-content";
     if (path.startsWith("components."))
         return "invalid-component";
     return "invalid-manifest";
@@ -211,16 +266,22 @@ function toPath(segments) {
     }, "");
 }
 /**
- * The manifest as a `ThemeDefinition` with a placeholder component, so the
- * assembly validator checks the relational rules without a real component.
+ * A manifest as a catalog every data function takes — `createInstance`,
+ * `instantiatePreset`, the document operations, `checkPageData`,
+ * `validatePageData`, `resolveThemeSettings`, `checkThemeSettings` — so an
+ * editor or a tool works from a theme's manifest alone, never its code.
+ * Components carry no implementation (`component: null`): the catalog
+ * describes and checks; it does not render.
  */
-function probeOf(manifest) {
+export function manifestCatalog(manifest) {
     return {
         key: manifest.key,
         version: manifest.version,
         surfaces: manifest.surfaces,
         locales: manifest.locales,
         settings: manifest.settings,
+        content: manifest.content,
+        preview: manifest.preview,
         components: Object.fromEntries(Object.entries(manifest.components).map(([key, spec]) => [
             key,
             { ...spec, component: null },

package/dist/operations.d.ts

@@ -0,0 +1,71 @@
+import type { ComponentInstance, JsonValue, PageData, ThemeDefinition } from "./types.js";
+export type DocumentIssueCode = "invalid-document" | "invalid-instance" | "invalid-index" | "invalid-props" | "unknown-instance" | "unknown-type" | "unknown-slot" | "duplicate-id" | "not-insertable" | "not-available" | "not-allowed" | "slot-full" | "cycle";
+/** Why a document or a change is refused; `path` points into the document. */
+export interface DocumentIssue {
+    path: string;
+    code: DocumentIssueCode;
+    message: string;
+}
+export type DocumentEdit = {
+    ok: true;
+    page: PageData;
+} | {
+    ok: false;
+    issue: DocumentIssue;
+};
+/** Where an instance goes: a parent's slot (absent: the top-level sections) at an index (absent: the end). */
+export interface InstancePlacement {
+    parent?: string;
+    /** Absent or `"default"`: the parent's children. */
+    slot?: string;
+    index?: number;
+}
+/** Where an instance is: its parent (`null` at the top level), its slot and its index there. */
+export interface InstanceLocation {
+    instance: ComponentInstance;
+    parent: string | null;
+    slot: string | null;
+    index: number;
+}
+/**
+ * A new instance id: `cmp_` and 16 random hex digits. Operations refuse an id
+ * the document already holds, so a collision is reported, never written.
+ */
+export declare function newInstanceId(): string;
+/** Where `id` is in the document, or `null`. */
+export declare function findInstance(page: PageData, id: string): InstanceLocation | null;
+/**
+ * Insert a new instance — from `createInstance` or `instantiatePreset` — at a
+ * placement. Refused when the component is not insertable or not available on
+ * the document's surface, when the slot does not take it, or when any id is
+ * already in the document.
+ */
+export declare function insertInstance(theme: ThemeDefinition, page: PageData, instance: ComponentInstance, placement?: InstancePlacement): DocumentEdit;
+/** Remove an instance and everything inside it. */
+export declare function removeInstance(page: PageData, id: string): DocumentEdit;
+/**
+ * Move an instance (with everything inside it) to a placement. `index` counts
+ * positions in the destination after the instance has left its old place.
+ */
+export declare function moveInstance(theme: ThemeDefinition, page: PageData, id: string, placement?: InstancePlacement): DocumentEdit;
+/**
+ * Copy an instance and everything inside it right after the original, every
+ * copied instance with an id from `newId`. List items keep their ids: they
+ * are unique within their list, not the document.
+ */
+export declare function duplicateInstance(theme: ThemeDefinition, page: PageData, id: string, newId: () => string): DocumentEdit;
+/**
+ * Change an instance's props: each value is checked by its field;
+ * `undefined` removes the stored value, so the field falls back to its
+ * content-pack text or default.
+ */
+export declare function setInstanceProps(theme: ThemeDefinition, page: PageData, id: string, changes: Readonly<Record<string, JsonValue | undefined>>): DocumentEdit;
+/** Switch an instance off (kept, not rendered) or back on. */
+export declare function setInstanceHidden(page: PageData, id: string, hidden: boolean): DocumentEdit;
+/**
+ * Everything a writer must fix before saving a document for this theme —
+ * the strict counterpart of `validatePageData`: an envelope for one of the
+ * theme's surfaces when it declares any, and every section a tree the
+ * operations would have built. An empty list means the document may be saved.
+ */
+export declare function checkPageData(theme: ThemeDefinition, input: unknown): DocumentIssue[];