@wocart/theme 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 1.1.0 — 2026-10-17
+
+### Added
+
+- **Theme settings.** `defineTheme({ settings })` declares a theme's global
+  settings in groups, with the field system sections use; they travel in the
+  manifest (`ThemeManifest.settings`, `[]` when none).
+  `resolveThemeSettings(theme, stored, scope)` reads a store's saved values
+  against the declaration — the merchant's value, else the default, with
+  every fallback reported (`invalid-settings`, `unknown-setting`,
+  `invalid-setting`, `missing-required-setting`). `checkThemeSettings` is the
+  writer's strict check. `InferSettings<typeof theme>` types the values.
+- Field kinds `color` (`#rgb`/`#rrggbb`) and `menu` (a menu handle), in
+  sections and settings alike.
+- Types `SettingsGroup`, `ThemeSettingsIssue`, `ThemeSettingsIssueCode`,
+  `ThemeSettingsResult`, `ColorFieldDefinition`, `MenuFieldDefinition`.
+
 ## 1.0.0 — 2026-10-13
 
 The first public release.

package/README.md

@@ -97,6 +97,8 @@ and, for page-data resolution issues, `path`.
 | `number` | finite number | optional `min`/`max`; a `default` must sit inside them |
 | `boolean` | boolean | |
 | `select` | one of `options` | `default` must be one of the options |
+| `color` | `#rgb` or `#rrggbb` | anything else (a color name, `url(…)`) is rejected at assembly and reported on read |
+| `menu` | a menu handle (`main-menu`) | lowercase letters, digits and hyphens; the store's menu is read with `@wocart/storefront`'s `menus.get(handle)` |
 | `url` | a link target | a site path (`/products`), `#fragment`, `?query`, `http(s)://`, `mailto:` or `tel:`; `javascript:`, `data:`, `//host` and backslash tricks are rejected at assembly and reported on read |
 
 Use `url` for every editor-settable `href`, never `text`: the reader drops an
@@ -300,6 +302,49 @@ policy is:
 The SDK does not ship this policy as a function, because the shipped default
 document is theme content.
 
+## Theme settings
+
+A theme's global choices — its font, which menu the header shows, a header
+color — are **settings**: declared once on the theme, in groups, with the same
+field kinds as a section. The merchant's values are stored per store and per
+theme (a value only means something against the theme that declared it) and
+reach the theme as `StoreConfig.themeSettings` from `@wocart/storefront`.
+
+```ts
+export const theme = defineTheme({
+  key: "my-theme",
+  version: "1.0.0",
+  locales: ["ar", "fr"],
+  settings: [
+    {
+      key: "header",
+      label: { ar: "الرأس", fr: "En-tête" },
+      fields: [
+        { key: "headerMenu", kind: "menu", label: { ar: "القائمة", fr: "Menu" }, default: "main-menu" },
+        { key: "font", kind: "select", label: { ar: "الخط", fr: "Police" }, options: ["Cairo", "Tajawal"], default: "Cairo" },
+      ],
+    },
+  ],
+  components: { … },
+});
+
+const { values, issues } = resolveThemeSettings(theme, config?.themeSettings, { locales: [locale] });
+values.headerMenu; // "main-menu" — typed: InferSettings<typeof theme>
+```
+
+- **Reading never fails.** Each setting takes the merchant's value when the
+  declaration accepts it, else the default (or the content pack, for text),
+  else it is absent. A value the theme no longer accepts — a removed option, a
+  color that is not one, a setting since deleted — is reported in `issues`
+  (`invalid-setting`, `unknown-setting`, `invalid-settings`) and falls back.
+- **Keys are unique across groups**; groups are for the editor, values are flat.
+- **A writer checks strictly** with `checkThemeSettings(theme, values)` before
+  saving: every key declared, every value accepted, in every language.
+- Settings travel in the manifest (`manifest.settings`), so an editor lists
+  them without running the theme.
+- Store identity — the logo, the brand colors — is not a theme setting: it
+  belongs to the store and survives a theme change.
+
 ## Content and copy
 
 The theme owns its content. The SDK does not model a content pack, a taxonomy,

package/dist/definitions.js

@@ -4,7 +4,7 @@
  * data — the validator exists so a theme's test suite fails loudly on catalog
  * bugs when the catalog is assembled.
  */
-import { SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
+import { COLOR_PATTERN, MENU_HANDLE_PATTERN, SURFACE_KEY_PATTERN, THEME_KEY_PATTERN, TYPE_KEY_PATTERN, isLocaleMap, isLocaleTag, isSafeLinkTarget, } from "./schemas.js";
 /** Identity helper: returns the definition unchanged so literal types survive. */
 export function defineComponent(definition) {
     return definition;
@@ -95,6 +95,8 @@ export function validateThemeDefinition(theme, options = {}) {
         catalogKeys: new Set(Object.keys(theme.components)),
         locales,
     };
+    if (theme.settings !== undefined)
+        inspectSettings(theme.settings, issues, rules);
     for (const [key, definition] of Object.entries(theme.components)) {
         const path = `components.${key}`;
         if (!TYPE_KEY_PATTERN.test(key)) {
@@ -109,6 +111,51 @@ export function validateThemeDefinition(theme, options = {}) {
     }
     return issues;
 }
+/**
+ * The theme's settings groups: an array of `{ key, label, fields }`, group keys
+ * unique and kebab-case, fields checked like a component's, and every setting
+ * key unique across all groups — values are stored flat, by setting key.
+ */
+function inspectSettings(settings, issues, rules) {
+    if (!Array.isArray(settings)) {
+        addIssue(issues, "settings", "invalid-settings", "`settings` must be an array of setting groups");
+        return;
+    }
+    const groupKeys = new Set();
+    const settingKeys = new Set();
+    settings.forEach((group, index) => {
+        const path = `settings[${index}]`;
+        if (!isRecord(group)) {
+            addIssue(issues, path, "invalid-settings", "a settings group must be an object");
+            return;
+        }
+        if (typeof group.key !== "string" || !TYPE_KEY_PATTERN.test(group.key)) {
+            addIssue(issues, `${path}.key`, "invalid-settings", "`key` must be lowercase kebab-case");
+        }
+        else if (groupKeys.has(group.key)) {
+            addIssue(issues, `${path}.key`, "invalid-settings", `duplicate settings group "${group.key}"`);
+        }
+        else {
+            groupKeys.add(group.key);
+        }
+        const labelProblem = localizedTextProblem(group.label, rules.locales, { allowEmpty: false });
+        if (labelProblem !== null)
+            addIssue(issues, `${path}.label`, "invalid-settings", `\`label\` ${labelProblem}`);
+        if (!Array.isArray(group.fields)) {
+            addIssue(issues, `${path}.fields`, "invalid-settings", "`fields` must be an array");
+            return;
+        }
+        inspectFields(group.fields, path, issues, rules);
+        for (const [fieldIndex, field] of group.fields.entries()) {
+            if (!isRecord(field) || typeof field.key !== "string")
+                continue;
+            if (settingKeys.has(field.key)) {
+                addIssue(issues, `${path}.fields[${fieldIndex}].key`, "duplicate-field-key", `setting "${field.key}" is declared in another group too`);
+            }
+            settingKeys.add(field.key);
+        }
+    });
+}
 function inspectSurfaces(surfaces, issues, locales) {
     const seenKeys = new Set();
     surfaces.forEach((surface, index) => {
@@ -299,6 +346,18 @@ function inspectFields(fields, path, issues, rules) {
                 }
                 break;
             }
+            case "color": {
+                if (field.default !== undefined && (typeof field.default !== "string" || !COLOR_PATTERN.test(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a hex color, #rgb or #rrggbb");
+                }
+                break;
+            }
+            case "menu": {
+                if (field.default !== undefined && (typeof field.default !== "string" || !MENU_HANDLE_PATTERN.test(field.default))) {
+                    addIssue(issues, `${fieldPath}.default`, "invalid-field", "`default` must be a menu handle: lowercase letters, digits and dashes");
+                }
+                break;
+            }
             case "url": {
                 if (field.default !== undefined &&
                     (typeof field.default !== "string" || !isSafeLinkTarget(field.default))) {

package/dist/index.d.ts

@@ -12,8 +12,9 @@
 export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
 export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance } from "./instances.js";
+export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
 export type { MessageOptions, MessageValues, PluralCategory } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";
-export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";
+export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, SlotDefinition, ComponentCapabilities, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, ColorFieldDefinition, MenuFieldDefinition, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

package/dist/index.js

@@ -12,6 +12,7 @@
 export { defineComponent, defineTheme, validateThemeDefinition } from "./definitions.js";
 export { parsePageData, validatePageData } from "./page-data.js";
 export { resolveInstance, createInstance } from "./instances.js";
+export { resolveThemeSettings, checkThemeSettings } from "./settings.js";
 export { localize } from "./locales.js";
 export { PLURAL_CATEGORIES, formatMessage, messageForms, pluralFormIssues } from "./messages.js";
 export { THEME_MANIFEST_CONTRACT_VERSION, themeManifest, validateThemeManifest, } from "./manifest.js";

package/dist/instances.d.ts

@@ -1,10 +1,31 @@
-import type { ComponentDefinition, ComponentInstance, JsonObject, ResolutionScope, ResolvedInstance } from "./types.js";
+import type { ComponentDefinition, ComponentInstance, FieldDefinition, JsonObject, LocaleCode, PageDataIssue, ResolutionScope, ResolvedInstance } from "./types.js";
 /**
  * Gate one instance for rendering: field values through the chain, children
  * and named slots gated against the declared slots, every degradation
  * reported. The instance (and page data) is never modified.
  */
 export declare function resolveInstance(definition: ComponentDefinition, instance: ComponentInstance, scope?: ResolutionScope): ResolvedInstance;
+export type CheckedValue = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+/** An own property only: `constructor` or `toString` must never read the prototype. */
+export declare function ownValue<T>(record: Record<string, T>, key: string): T | undefined;
+/**
+ * One field through the chain. `undefined` = omit the value. Issues are
+ * reported under `${prefix}.${field.key}` — a component's `props`, or a theme's
+ * `settings`.
+ */
+export declare function resolveField(field: FieldDefinition, raw: unknown, content: Record<string, string>, locales: readonly LocaleCode[], issues: PageDataIssue[], prefix: string): unknown;
+/**
+ * What a writer may store: a value that passes the field's rules, or — for a
+ * translatable field — a per-language map whose every entry passes them, so no
+ * language can hold an unsafe link or a wrong type.
+ */
+export declare function checkStoredValue(field: FieldDefinition, value: unknown): CheckedValue;
 /**
  * Create a new instance with insertion-time defaults:
  * materialises `field.default` values only — content-keyed fields stay unset

package/dist/instances.js

@@ -9,7 +9,7 @@
  * default applies last).
  */
 import { localize } from "./locales.js";
-import { isLocaleMap, isSafeLinkTarget } from "./schemas.js";
+import { COLOR_PATTERN, MENU_HANDLE_PATTERN, isLocaleMap, isSafeLinkTarget } from "./schemas.js";
 /** Field kinds whose values may differ per language. Numbers, toggles and choices are shared. */
 const TRANSLATABLE_KINDS = new Set(["text", "textarea", "url"]);
 const isTranslatable = (field) => TRANSLATABLE_KINDS.has(field.kind);
@@ -36,7 +36,7 @@ export function resolveInstance(definition, instance, scope = {}) {
     }
     const props = {};
     for (const field of fields) {
-        const resolved = resolveField(field, ownValue(rawProps, field.key), content, locales, issues);
+        const resolved = resolveField(field, ownValue(rawProps, field.key), content, locales, issues, "props");
         if (resolved !== undefined) {
             props[field.key] = resolved;
         }
@@ -82,7 +82,7 @@ export function resolveInstance(definition, instance, scope = {}) {
     return { props, children, slots, issues };
 }
 /** An own property only: `constructor` or `toString` must never read the prototype. */
-function ownValue(record, key) {
+export function ownValue(record, key) {
     return Object.hasOwn(record, key) ? record[key] : undefined;
 }
 /**
@@ -103,8 +103,12 @@ function storedValueFor(field, raw, locales) {
     const picked = localize(raw, locales);
     return picked === undefined ? { kind: "untranslated" } : { kind: "value", value: picked };
 }
-/** One field through the chain. `undefined` = omit the prop. */
-function resolveField(field, raw, content, locales, issues) {
+/**
+ * One field through the chain. `undefined` = omit the value. Issues are
+ * reported under `${prefix}.${field.key}` — a component's `props`, or a theme's
+ * `settings`.
+ */
+export function resolveField(field, raw, content, locales, issues, prefix) {
     if (raw !== undefined) {
         const stored = storedValueFor(field, raw, locales);
         const checked = stored.kind === "value"
@@ -117,7 +121,7 @@ function resolveField(field, raw, content, locales, issues) {
         }
         if (checked !== undefined) {
             issues.push({
-                path: `props.${field.key}`,
+                path: `${prefix}.${field.key}`,
                 code: "invalid-prop",
                 message: `"${field.key}" ${checked.message}; treated as absent`,
             });
@@ -142,7 +146,7 @@ function resolveField(field, raw, content, locales, issues) {
     }
     if (field.required === true) {
         issues.push({
-            path: `props.${field.key}`,
+            path: `${prefix}.${field.key}`,
             code: "missing-required-prop",
             message: `required field "${field.key}" has no value`,
         });
@@ -154,7 +158,7 @@ function resolveField(field, raw, content, locales, issues) {
  * translatable field — a per-language map whose every entry passes them, so no
  * language can hold an unsafe link or a wrong type.
  */
-function checkStoredValue(field, value) {
+export function checkStoredValue(field, value) {
     if (!isTranslatable(field) || typeof value !== "object" || value === null || Array.isArray(value)) {
         return checkFieldValue(field, value);
     }
@@ -199,6 +203,14 @@ function checkFieldValue(field, value) {
                     ok: false,
                     message: "must be a site path, #fragment, ?query, or an http(s), mailto or tel URL",
                 };
+        case "color":
+            return typeof value === "string" && COLOR_PATTERN.test(value)
+                ? { ok: true, value }
+                : { ok: false, message: "must be a hex color, #rgb or #rrggbb" };
+        case "menu":
+            return typeof value === "string" && MENU_HANDLE_PATTERN.test(value)
+                ? { ok: true, value }
+                : { ok: false, message: "must be a menu handle" };
         case "select":
             return typeof value === "string" && field.options.includes(value)
                 ? { ok: true, value }

package/dist/manifest.d.ts

@@ -28,6 +28,72 @@ export declare const ThemeManifestSchema: z.ZodObject<{
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
     }, z.core.$strip>>>;
     locales: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    settings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
+        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>;
+        }, 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>;
+            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<"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<"color">;
+            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<"menu">;
+            default: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>>;
     components: z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodString;
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -79,6 +145,20 @@ export declare const ThemeManifestSchema: z.ZodObject<{
             required: z.ZodExactOptional<z.ZodBoolean>;
             kind: z.ZodLiteral<"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<"color">;
+            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<"menu">;
+            default: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strip>], "kind">>>;
         slots: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodString;

package/dist/manifest.js

@@ -26,6 +26,7 @@ export function themeManifest(theme) {
             label: copyData(surface.label),
         })),
         locales: [...(theme.locales ?? [])],
+        settings: (theme.settings ?? []).map((group) => copyData(group)),
         components: Object.fromEntries(Object.entries(theme.components).map(([key, definition]) => [
             key,
             componentSpec(definition),
@@ -92,6 +93,16 @@ const FieldSchema = z.discriminatedUnion("kind", [
         kind: z.literal("url"),
         default: z.exactOptional(z.string()),
     }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("color"),
+        default: z.exactOptional(z.string()),
+    }),
+    z.object({
+        ...FieldCommonSchema,
+        kind: z.literal("menu"),
+        default: z.exactOptional(z.string()),
+    }),
 ]);
 const ComponentSpecSchema = z.object({
     type: z.string(),
@@ -120,6 +131,9 @@ export const ThemeManifestSchema = z.object({
         .array(z.object({ key: z.string(), label: LocalizedTextSchema }))
         .default([]),
     locales: z.array(z.string()).default([]),
+    settings: z
+        .array(z.object({ key: z.string(), label: LocalizedTextSchema, fields: z.array(FieldSchema) }))
+        .default([]),
     components: z.record(z.string(), ComponentSpecSchema),
 });
 // ── Validation ───────────────────────────────────────────────────────────────
@@ -177,6 +191,8 @@ function codeAt(path) {
         return "invalid-version";
     if (path === "surfaces" || path.startsWith("surfaces["))
         return "invalid-surface";
+    if (path === "settings" || path.startsWith("settings["))
+        return "invalid-settings";
     if (path.startsWith("components."))
         return "invalid-component";
     return "invalid-manifest";
@@ -199,6 +215,7 @@ function probeOf(manifest) {
         version: manifest.version,
         surfaces: manifest.surfaces,
         locales: manifest.locales,
+        settings: manifest.settings,
         components: Object.fromEntries(Object.entries(manifest.components).map(([key, spec]) => [
             key,
             { ...spec, component: null },

package/dist/schemas.d.ts

@@ -21,6 +21,14 @@ export declare const TYPE_KEY_PATTERN: RegExp;
  * not of the package's curated public surface (`src/index.ts`).
  */
 export declare const SURFACE_KEY_PATTERN: RegExp;
+/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
+export declare const COLOR_PATTERN: RegExp;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export declare const MENU_HANDLE_PATTERN: RegExp;
 export declare function isLocaleTag(value: string): boolean;
 /**
  * Whether `value` is a per-language map (`{ ar: "…", fr: "…" }`): a plain

package/dist/schemas.js

@@ -20,6 +20,14 @@ export const TYPE_KEY_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
  * not of the package's curated public surface (`src/index.ts`).
  */
 export const SURFACE_KEY_PATTERN = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+/** A `color` field's value: a hex color, `#rgb` or `#rrggbb`. */
+export const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+/**
+ * A `menu` field's value: the handle of one of the store's menus
+ * (`main-menu`, `footer`). The server applies the same pattern to menu
+ * handles; a menu that does not exist reads as no menu.
+ */
+export const MENU_HANDLE_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /**
  * A BCP 47 language tag in canonical case: a 2–3 letter language, an optional
  * 4-letter script, an optional 2-letter or 3-digit region (`ar`, `zgh`,

package/dist/settings.d.ts

@@ -0,0 +1,15 @@
+import type { ResolutionScope, ThemeDefinition, ThemeSettingsIssue, ThemeSettingsResult } from "./types.js";
+/**
+ * The effective settings for rendering: every declared setting, from the
+ * store's value when the declaration accepts it, else from the theme's
+ * default. `stored` is the persisted object as it arrived (anything else —
+ * null, an array — reads as no values and is reported). Translated text uses
+ * `scope.locales`; text settings may default from `scope.content`.
+ */
+export declare function resolveThemeSettings(theme: ThemeDefinition, stored: unknown, scope?: ResolutionScope): ThemeSettingsResult;
+/**
+ * What a writer must check before saving a store's settings for a theme:
+ * every key declared, every value accepted by its setting — in every language
+ * for a translated one. An empty list means the values may be saved.
+ */
+export declare function checkThemeSettings(theme: ThemeDefinition, values: unknown): ThemeSettingsIssue[];

package/dist/settings.js

@@ -0,0 +1,80 @@
+/**
+ * A store's theme settings: the merchant's values for the settings a theme
+ * declares (`ThemeDefinition.settings`), read against that declaration.
+ *
+ * Values are stored flat by setting key, for one theme (a value is only
+ * meaningful against the theme that declared it). Reading never fails: a
+ * value the declaration does not accept — a setting since removed, a color
+ * that is not a color, an option no longer offered — is reported and the
+ * setting falls back to the theme's default, exactly as a page document's
+ * field does. Precedence: the merchant's value → the theme's default (or its
+ * content pack, for text) → absent.
+ */
+import { checkStoredValue, ownValue, resolveField } from "./instances.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function declaredSettings(theme) {
+    const fields = new Map();
+    for (const group of theme.settings ?? [])
+        for (const field of group.fields)
+            if (!fields.has(field.key))
+                fields.set(field.key, field);
+    return fields;
+}
+const PAGE_TO_SETTINGS = {
+    "invalid-prop": "invalid-setting",
+    "missing-required-prop": "missing-required-setting",
+};
+/**
+ * The effective settings for rendering: every declared setting, from the
+ * store's value when the declaration accepts it, else from the theme's
+ * default. `stored` is the persisted object as it arrived (anything else —
+ * null, an array — reads as no values and is reported). Translated text uses
+ * `scope.locales`; text settings may default from `scope.content`.
+ */
+export function resolveThemeSettings(theme, stored, scope = {}) {
+    const issues = [];
+    const declared = declaredSettings(theme);
+    let values = {};
+    if (stored !== undefined && stored !== null && !isRecord(stored)) {
+        issues.push({ path: "settings", code: "invalid-settings", message: "stored settings must be an object; the theme's defaults apply" });
+    }
+    else if (isRecord(stored)) {
+        values = stored;
+    }
+    for (const key of Object.keys(values)) {
+        if (!declared.has(key))
+            issues.push({ path: `settings.${key}`, code: "unknown-setting", message: `"${key}" is not a setting of "${theme.key}"; ignored` });
+    }
+    const resolved = {};
+    const fieldIssues = [];
+    for (const [key, field] of declared) {
+        const value = resolveField(field, ownValue(values, key), scope.content ?? {}, scope.locales ?? [], fieldIssues, "settings");
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    for (const issue of fieldIssues)
+        issues.push({ path: issue.path, code: PAGE_TO_SETTINGS[issue.code] ?? "invalid-setting", message: issue.message });
+    return { values: resolved, issues };
+}
+/**
+ * What a writer must check before saving a store's settings for a theme:
+ * every key declared, every value accepted by its setting — in every language
+ * for a translated one. An empty list means the values may be saved.
+ */
+export function checkThemeSettings(theme, values) {
+    if (!isRecord(values))
+        return [{ path: "settings", code: "invalid-settings", message: "settings must be an object" }];
+    const declared = declaredSettings(theme);
+    const issues = [];
+    for (const [key, value] of Object.entries(values)) {
+        const field = declared.get(key);
+        if (field === undefined) {
+            issues.push({ path: `settings.${key}`, code: "unknown-setting", message: `"${key}" is not a setting of "${theme.key}"` });
+            continue;
+        }
+        const checked = checkStoredValue(field, value);
+        if (!checked.ok)
+            issues.push({ path: `settings.${key}`, code: "invalid-setting", message: `"${key}" ${checked.message}` });
+    }
+    return issues;
+}

package/dist/types.d.ts

@@ -36,8 +36,8 @@ export interface ResolutionScope {
     content?: Record<string, string>;
     locales?: readonly LocaleCode[];
 }
-/** The V1 field kinds. */
-export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url";
+/** The field kinds. `color` and `menu` were added after V1, additively. */
+export type FieldKind = "text" | "textarea" | "number" | "boolean" | "select" | "url" | "color" | "menu";
 interface FieldDefinitionBase {
     /** The exact prop name the component expects. */
     key: string;
@@ -97,7 +97,22 @@ export interface UrlFieldDefinition extends FieldDefinitionBase {
     kind: "url";
     default?: string;
 }
-export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition;
+/** `color`: a hex color, `#rgb` or `#rrggbb`. Not translatable. */
+export interface ColorFieldDefinition extends FieldDefinitionBase {
+    kind: "color";
+    default?: string;
+}
+/**
+ * `menu`: which of the store's menus to show here — Shopify's `link_list`.
+ * The value is a menu handle (`main-menu`); the theme reads the menu with
+ * the storefront client's `menus.get(handle)`. A theme never assumes a menu
+ * exists: an unknown handle reads as no menu.
+ */
+export interface MenuFieldDefinition extends FieldDefinitionBase {
+    kind: "menu";
+    default?: string;
+}
+export type FieldDefinition = TextFieldDefinition | NumberFieldDefinition | BooleanFieldDefinition | SelectFieldDefinition | UrlFieldDefinition | ColorFieldDefinition | MenuFieldDefinition;
 /**
  * One composition point a component declares (`"default"` = children).
  *
@@ -270,8 +285,23 @@ export interface ThemeDefinition {
      * languages the theme can serve. Absent means "not declared".
      */
     locales?: readonly LocaleCode[];
+    /**
+     * The theme's global settings: what a merchant may change about the whole
+     * theme (its font, its colors, which menu the header shows), declared with
+     * the same fields sections use, in named groups. Optional and additive. A
+     * store's values are read with `resolveThemeSettings`; a writer checks them
+     * with `checkThemeSettings`. Setting keys are unique across all groups.
+     */
+    settings?: readonly SettingsGroup[];
     components: Record<string, ComponentDefinition>;
 }
+/** One group of theme settings, as an editor lists them ("Typography", "Header"). */
+export interface SettingsGroup {
+    /** Lowercase kebab-case, unique in the theme. */
+    key: string;
+    label: LocalizedText;
+    fields: readonly FieldDefinition[];
+}
 /**
  * One surface a theme declares it can render.
  *
@@ -322,9 +352,11 @@ export interface ThemeManifest {
     surfaces: readonly SurfaceSpec[];
     /** The languages the theme's packs cover (possibly none declared). */
     locales: readonly LocaleCode[];
+    /** The theme's global settings (possibly none). */
+    settings: readonly SettingsGroup[];
     components: Record<string, ComponentSpec>;
 }
-export type ThemeManifestIssueCode = "invalid-manifest" | "unsupported-contract" | "invalid-identity" | "invalid-version" | "invalid-surface" | "invalid-component" | "type-mismatch" | "non-serializable";
+export type ThemeManifestIssueCode = "invalid-manifest" | "unsupported-contract" | "invalid-identity" | "invalid-version" | "invalid-surface" | "invalid-settings" | "invalid-component" | "type-mismatch" | "non-serializable";
 /** One reported manifest problem; `path` points into the manifest (e.g. `components.hero.fields[0].kind`). */
 export interface ThemeManifestIssue {
     path: string;
@@ -389,7 +421,7 @@ export interface ResolvedInstance {
     slots: Record<string, ComponentInstance[]>;
     issues: PageDataIssue[];
 }
-export type ThemeDefinitionIssueCode = "invalid-theme" | "invalid-definition" | "invalid-type" | "type-mismatch" | "invalid-field" | "duplicate-field-key" | "unknown-content-key" | "invalid-slot" | "duplicate-slot" | "invalid-capability" | "invalid-load";
+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";
 export interface ThemeDefinitionIssue {
     path: string;
     code: ThemeDefinitionIssueCode;
@@ -409,4 +441,39 @@ export interface ThemeDefinitionIssue {
 export interface ThemeValidationOptions {
     contentKeys?: readonly string[];
 }
+export type ThemeSettingsIssueCode = "invalid-settings" | "unknown-setting" | "invalid-setting" | "missing-required-setting";
+/** One reported problem with a store's theme settings; `path` is `settings.<key>`. */
+export interface ThemeSettingsIssue {
+    path: string;
+    code: ThemeSettingsIssueCode;
+    message: string;
+}
+/** The effective settings: every value checked, the rest from the theme's defaults. */
+export interface ThemeSettingsResult {
+    values: Record<string, unknown>;
+    issues: ThemeSettingsIssue[];
+}
+type SettingsFieldsOf<T> = T extends {
+    settings: readonly (infer G)[];
+} ? G extends {
+    fields: readonly (infer F extends FieldDefinition)[];
+} ? F : never : never;
+/**
+ * The effective settings of a theme, typed from its declaration: a setting
+ * with a `default` is always present, any other may be absent.
+ *
+ * ```ts
+ * const { values } = resolveThemeSettings(theme, stored);
+ * const settings = values as InferSettings<typeof theme>;
+ * ```
+ */
+export type InferSettings<T extends ThemeDefinition> = {
+    [F in SettingsFieldsOf<T> as F extends {
+        default: unknown;
+    } ? F["key"] : never]: FieldValue<F>;
+} & {
+    [F in SettingsFieldsOf<T> as F extends {
+        default: unknown;
+    } ? never : F["key"]]?: FieldValue<F>;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",