@sovecom/theme-sdk 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SovEcom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @sovecom/theme-sdk
+
+The public, author-facing SDK for building [SovEcom](../../README.md) themes.
+
+> **Status:** stub. This package is `private` and consumed in-repo via the pnpm workspace; it is
+> not yet published to npm. This README is a placeholder — the full author guide is forthcoming.
+
+## What it is
+
+This package is the **single source of truth** for the SovEcom theme **manifest** contract: the
+`sovecom.theme.json` schema, its validator, the byte cap + semver gate, and the author ergonomics.
+The core runtime (`apps/api`) imports these same definitions, so the published contract can never
+drift from what the core enforces at install time.
+
+A theme is a **declarative asset**: there is **no `activate`, no worker, no runtime entrypoint, no
+capabilities, no namespaced tables**. So this package exports the manifest contract, author-time
+validation/typing helpers, and the two store-contract types a storefront reads — nothing executable.
+The shared core-API primitives (`CORE_API_VERSION`, `assertCoreCompatible`, `MANIFEST_MAX_BYTES`)
+are reused from `@sovecom/module-sdk` so both SDKs gate against one core version.
+
+## Authoring a theme
+
+```ts
+import { defineTheme, defineThemeSlots, defineThemeSettings } from '@sovecom/theme-sdk';
+
+// defineTheme validates the config and returns the typed, validated manifest OBJECT
+// (NOT an `{ activate }` entry — a theme has no runtime body):
+export default defineTheme({
+  name: 'aurora',
+  displayName: 'Aurora',
+  version: '1.0.0',
+  compatibleCore: '^1.0.0',
+  slots: defineThemeSlots(['product-page', 'cart-drawer']),
+  settingsSchema: './settings.schema.json', // path stays opaque; never read here
+});
+
+// Optional: type your theme's default settings shape (pure compile-time helper):
+export const defaults = defineThemeSettings({ accentColor: '#6c5ce7', showBadges: true });
+```
+
+## Exports
+
+- `defineTheme(config)` — validates the config and returns the typed, validated `ThemeManifest`
+  object. A theme has no runtime entrypoint, so it returns a manifest, not an `{ activate }`.
+- `defineThemeSlots(slots)` — typed, validated builder for the manifest's declarative slot-slug
+  array (lowercase slugs, no duplicates).
+- `defineThemeSettings(defaults)` — pure compile-time helper to type the author's settings object.
+- Manifest types + validators: `ThemeManifest`, `themeManifestSchema`, `parseAndVerifyThemeManifest`,
+  `THEME_NAME_RE`, `SLOT_SLUG_RE`.
+- Shared core-API primitives (re-exported from `@sovecom/module-sdk`): `CORE_API_VERSION`,
+  `assertCoreCompatible`, `MANIFEST_MAX_BYTES`.
+- Store-contract types (consumed by the storefront): `ActiveTheme` (`{ name, version, settings }`),
+  `SlotMap` (`Record<slot, { module, component }>`), `SlotBinding`.
+
+## License
+
+MIT. A theme is derivative of the MIT reference storefront across the HTTP API boundary, so this
+SDK — distinct from the AGPL-3.0 core and the AGPL `@sovecom/module-sdk` — is MIT. See the
+`LICENSE` file in this package.

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@sovecom/theme-sdk` — the public, semver-pinned author-facing contract for the SovEcom theme
+ * ecosystem. This package is the SINGLE SOURCE OF TRUTH for the theme manifest: the validator, the
+ * types, and the author ergonomics. The core runtime imports these definitions FROM here, so the
+ * published SDK can never drift from what the core actually enforces at install time.
+ *
+ * A theme is a declarative ASSET: there is NO `activate`, NO worker, NO runtime entrypoint, NO
+ * capabilities, NO namespaced tables. So this package exports the manifest contract, author-time
+ * validation/typing helpers, and the two store-contract types a storefront reads — nothing
+ * executable. It is MIT-licensed, distinct from the AGPL core, so it can be vendored by commercial
+ * theme authors across the HTTP API boundary.
+ *
+ * The shared core-API primitives (`CORE_API_VERSION`, `assertCoreCompatible`, `MANIFEST_MAX_BYTES`)
+ * are REUSED from `@sovecom/module-sdk` — they have ONE home so both SDKs gate against the same
+ * core version.
+ */
+/** SDK package version (independent of the core API contract version below). */
+export declare const THEME_SDK_VERSION = "1.0.0-rc.1";
+export { defineTheme } from './theme.js';
+export type { DefineThemeConfig } from './theme.js';
+export { defineThemeSlots } from './slots.js';
+export { defineThemeSettings } from './settings.js';
+export type { ThemeSettings, DocumentedThemeSettings, KnownThemeSettings } from './settings.js';
+export { THEME_NAME_RE, SLOT_SLUG_RE, TEMPLATE_PATH_RE, themeManifestSchema, themeTemplateDeclSchema, parseAndVerifyThemeManifest, } from './manifest.js';
+export type { ThemeManifest, ThemeTemplateDecl } from './manifest.js';
+export { PAGE_TYPES, SECTION_TYPE_RE, REGION_NAME_RE, MAX_REGION_DEPTH, pageTypeSchema, regionNameSchema, templateSectionSchema, templateSchema, parseTemplate, defineTemplate, defineSection, } from './template.js';
+export type { PageType, TemplateSection, ThemeTemplate, SectionDef } from './template.js';
+export { WIDGET_TYPES, WIDGET_MAX_BYTES, actionPathSchema, actionSchema, starRatingSummaryPropsSchema, reviewListPropsSchema, productCarouselPropsSchema, toggleButtonPropsSchema, submitFormPropsSchema, widgetDescriptorSchema, parseWidget, } from './widget.js';
+export type { WidgetType, WidgetDescriptor, StarRatingSummaryProps, ReviewListProps, ProductCarouselProps, ToggleButtonProps, SubmitFormProps, } from './widget.js';
+export { MANIFEST_MAX_BYTES, assertCoreCompatible } from './manifest.js';
+export { CORE_API_VERSION } from '@sovecom/module-sdk';
+export type { ActiveTheme, SlotBinding, SlotMap } from './store-contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAG9C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGhG,OAAO,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMtE,OAAO,EACL,UAAU,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAM1F,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,4BAA4B,EAC5B,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * `@sovecom/theme-sdk` — the public, semver-pinned author-facing contract for the SovEcom theme
+ * ecosystem. This package is the SINGLE SOURCE OF TRUTH for the theme manifest: the validator, the
+ * types, and the author ergonomics. The core runtime imports these definitions FROM here, so the
+ * published SDK can never drift from what the core actually enforces at install time.
+ *
+ * A theme is a declarative ASSET: there is NO `activate`, NO worker, NO runtime entrypoint, NO
+ * capabilities, NO namespaced tables. So this package exports the manifest contract, author-time
+ * validation/typing helpers, and the two store-contract types a storefront reads — nothing
+ * executable. It is MIT-licensed, distinct from the AGPL core, so it can be vendored by commercial
+ * theme authors across the HTTP API boundary.
+ *
+ * The shared core-API primitives (`CORE_API_VERSION`, `assertCoreCompatible`, `MANIFEST_MAX_BYTES`)
+ * are REUSED from `@sovecom/module-sdk` — they have ONE home so both SDKs gate against the same
+ * core version.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_API_VERSION = exports.assertCoreCompatible = exports.MANIFEST_MAX_BYTES = exports.parseWidget = exports.widgetDescriptorSchema = exports.submitFormPropsSchema = exports.toggleButtonPropsSchema = exports.productCarouselPropsSchema = exports.reviewListPropsSchema = exports.starRatingSummaryPropsSchema = exports.actionSchema = exports.actionPathSchema = exports.WIDGET_MAX_BYTES = exports.WIDGET_TYPES = exports.defineSection = exports.defineTemplate = exports.parseTemplate = exports.templateSchema = exports.templateSectionSchema = exports.regionNameSchema = exports.pageTypeSchema = exports.MAX_REGION_DEPTH = exports.REGION_NAME_RE = exports.SECTION_TYPE_RE = exports.PAGE_TYPES = exports.parseAndVerifyThemeManifest = exports.themeTemplateDeclSchema = exports.themeManifestSchema = exports.TEMPLATE_PATH_RE = exports.SLOT_SLUG_RE = exports.THEME_NAME_RE = exports.defineThemeSettings = exports.defineThemeSlots = exports.defineTheme = exports.THEME_SDK_VERSION = void 0;
+/** SDK package version (independent of the core API contract version below). */
+exports.THEME_SDK_VERSION = '1.0.0-rc.1';
+// ── author ergonomics ───────────────────────────────────────────────────────────
+var theme_js_1 = require("./theme.js");
+Object.defineProperty(exports, "defineTheme", { enumerable: true, get: function () { return theme_js_1.defineTheme; } });
+var slots_js_1 = require("./slots.js");
+Object.defineProperty(exports, "defineThemeSlots", { enumerable: true, get: function () { return slots_js_1.defineThemeSlots; } });
+var settings_js_1 = require("./settings.js");
+Object.defineProperty(exports, "defineThemeSettings", { enumerable: true, get: function () { return settings_js_1.defineThemeSettings; } });
+// ── manifest types + validators (single source of truth) ─────────────────────────
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "THEME_NAME_RE", { enumerable: true, get: function () { return manifest_js_1.THEME_NAME_RE; } });
+Object.defineProperty(exports, "SLOT_SLUG_RE", { enumerable: true, get: function () { return manifest_js_1.SLOT_SLUG_RE; } });
+Object.defineProperty(exports, "TEMPLATE_PATH_RE", { enumerable: true, get: function () { return manifest_js_1.TEMPLATE_PATH_RE; } });
+Object.defineProperty(exports, "themeManifestSchema", { enumerable: true, get: function () { return manifest_js_1.themeManifestSchema; } });
+Object.defineProperty(exports, "themeTemplateDeclSchema", { enumerable: true, get: function () { return manifest_js_1.themeTemplateDeclSchema; } });
+Object.defineProperty(exports, "parseAndVerifyThemeManifest", { enumerable: true, get: function () { return manifest_js_1.parseAndVerifyThemeManifest; } });
+// ── template contract — section/JSON-template composition ──
+// Declarative page templates (`{ page, sections[] }`) + author helpers. PURE validators, no code
+// execution; the manifest is UNTOUCHED (the manifest `templates[]` declaration is deferred). Only
+// `home` is consumed at this stage; the rest of `PAGE_TYPES` is declared for later stages.
+var template_js_1 = require("./template.js");
+Object.defineProperty(exports, "PAGE_TYPES", { enumerable: true, get: function () { return template_js_1.PAGE_TYPES; } });
+Object.defineProperty(exports, "SECTION_TYPE_RE", { enumerable: true, get: function () { return template_js_1.SECTION_TYPE_RE; } });
+Object.defineProperty(exports, "REGION_NAME_RE", { enumerable: true, get: function () { return template_js_1.REGION_NAME_RE; } });
+Object.defineProperty(exports, "MAX_REGION_DEPTH", { enumerable: true, get: function () { return template_js_1.MAX_REGION_DEPTH; } });
+Object.defineProperty(exports, "pageTypeSchema", { enumerable: true, get: function () { return template_js_1.pageTypeSchema; } });
+Object.defineProperty(exports, "regionNameSchema", { enumerable: true, get: function () { return template_js_1.regionNameSchema; } });
+Object.defineProperty(exports, "templateSectionSchema", { enumerable: true, get: function () { return template_js_1.templateSectionSchema; } });
+Object.defineProperty(exports, "templateSchema", { enumerable: true, get: function () { return template_js_1.templateSchema; } });
+Object.defineProperty(exports, "parseTemplate", { enumerable: true, get: function () { return template_js_1.parseTemplate; } });
+Object.defineProperty(exports, "defineTemplate", { enumerable: true, get: function () { return template_js_1.defineTemplate; } });
+Object.defineProperty(exports, "defineSection", { enumerable: true, get: function () { return template_js_1.defineSection; } });
+// ── module slot-widget contract (data-descriptor widgets) ────────────────────
+// A module contributes storefront UI by returning a typed `{ type, props }` widget descriptor from a
+// CLOSED, core-owned MIT vocabulary. PURE validators only — no code/HTML/SVG crosses; the storefront
+// renders its own known MIT components. `parseWidget` returns `null` on ANY failure (never throws).
+var widget_js_1 = require("./widget.js");
+Object.defineProperty(exports, "WIDGET_TYPES", { enumerable: true, get: function () { return widget_js_1.WIDGET_TYPES; } });
+Object.defineProperty(exports, "WIDGET_MAX_BYTES", { enumerable: true, get: function () { return widget_js_1.WIDGET_MAX_BYTES; } });
+Object.defineProperty(exports, "actionPathSchema", { enumerable: true, get: function () { return widget_js_1.actionPathSchema; } });
+Object.defineProperty(exports, "actionSchema", { enumerable: true, get: function () { return widget_js_1.actionSchema; } });
+Object.defineProperty(exports, "starRatingSummaryPropsSchema", { enumerable: true, get: function () { return widget_js_1.starRatingSummaryPropsSchema; } });
+Object.defineProperty(exports, "reviewListPropsSchema", { enumerable: true, get: function () { return widget_js_1.reviewListPropsSchema; } });
+Object.defineProperty(exports, "productCarouselPropsSchema", { enumerable: true, get: function () { return widget_js_1.productCarouselPropsSchema; } });
+Object.defineProperty(exports, "toggleButtonPropsSchema", { enumerable: true, get: function () { return widget_js_1.toggleButtonPropsSchema; } });
+Object.defineProperty(exports, "submitFormPropsSchema", { enumerable: true, get: function () { return widget_js_1.submitFormPropsSchema; } });
+Object.defineProperty(exports, "widgetDescriptorSchema", { enumerable: true, get: function () { return widget_js_1.widgetDescriptorSchema; } });
+Object.defineProperty(exports, "parseWidget", { enumerable: true, get: function () { return widget_js_1.parseWidget; } });
+// ── shared core-API primitives (re-exported from @sovecom/module-sdk; ONE home) ───
+var manifest_js_2 = require("./manifest.js");
+Object.defineProperty(exports, "MANIFEST_MAX_BYTES", { enumerable: true, get: function () { return manifest_js_2.MANIFEST_MAX_BYTES; } });
+Object.defineProperty(exports, "assertCoreCompatible", { enumerable: true, get: function () { return manifest_js_2.assertCoreCompatible; } });
+var module_sdk_1 = require("@sovecom/module-sdk");
+Object.defineProperty(exports, "CORE_API_VERSION", { enumerable: true, get: function () { return module_sdk_1.CORE_API_VERSION; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,gFAAgF;AACnE,QAAA,iBAAiB,GAAG,YAAY,CAAC;AAE9C,mFAAmF;AACnF,uCAAyC;AAAhC,uGAAA,WAAW,OAAA;AAEpB,uCAA8C;AAArC,4GAAA,gBAAgB,OAAA;AACzB,6CAAoD;AAA3C,kHAAA,mBAAmB,OAAA;AAG5B,oFAAoF;AACpF,6CAOuB;AANrB,4GAAA,aAAa,OAAA;AACb,2GAAA,YAAY,OAAA;AACZ,+GAAA,gBAAgB,OAAA;AAChB,kHAAA,mBAAmB,OAAA;AACnB,sHAAA,uBAAuB,OAAA;AACvB,0HAAA,2BAA2B,OAAA;AAI7B,8DAA8D;AAC9D,iGAAiG;AACjG,kGAAkG;AAClG,2FAA2F;AAC3F,6CAYuB;AAXrB,yGAAA,UAAU,OAAA;AACV,8GAAA,eAAe,OAAA;AACf,6GAAA,cAAc,OAAA;AACd,+GAAA,gBAAgB,OAAA;AAChB,6GAAA,cAAc,OAAA;AACd,+GAAA,gBAAgB,OAAA;AAChB,oHAAA,qBAAqB,OAAA;AACrB,6GAAA,cAAc,OAAA;AACd,4GAAA,aAAa,OAAA;AACb,6GAAA,cAAc,OAAA;AACd,4GAAA,aAAa,OAAA;AAIf,gFAAgF;AAChF,qGAAqG;AACrG,qGAAqG;AACrG,oGAAoG;AACpG,yCAYqB;AAXnB,yGAAA,YAAY,OAAA;AACZ,6GAAA,gBAAgB,OAAA;AAChB,6GAAA,gBAAgB,OAAA;AAChB,yGAAA,YAAY,OAAA;AACZ,yHAAA,4BAA4B,OAAA;AAC5B,kHAAA,qBAAqB,OAAA;AACrB,uHAAA,0BAA0B,OAAA;AAC1B,oHAAA,uBAAuB,OAAA;AACvB,kHAAA,qBAAqB,OAAA;AACrB,mHAAA,sBAAsB,OAAA;AACtB,wGAAA,WAAW,OAAA;AAYb,qFAAqF;AACrF,6CAAyE;AAAhE,iHAAA,kBAAkB,OAAA;AAAE,mHAAA,oBAAoB,OAAA;AACjD,kDAAuD;AAA9C,8GAAA,gBAAgB,OAAA"}

package/dist/manifest.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { MANIFEST_MAX_BYTES, assertCoreCompatible } from '@sovecom/module-sdk';
+/** Theme name: a slug that forms the install identity and a URL segment. */
+export declare const THEME_NAME_RE: RegExp;
+/** A slot slug the theme exposes/renders (same lowercase-slug shape as the module side). */
+export declare const SLOT_SLUG_RE: RegExp;
+/**
+ * A template file path: a SAFE RELATIVE slug path ending in `.json`. Each segment is a lowercase
+ * slug (a-z0-9, `_`, `-`), segments are `/`-joined, and the whole thing ends in `.json`. By
+ * construction this admits NO leading `/` (absolute), NO `..` segment (traversal), NO `\` (Windows
+ * separator), and NO `.`-only / hidden segments — the manifest is the ALLOWLIST of files the ingest
+ * is permitted to read out of the extracted tree. The ingest re-asserts containment
+ * against the extraction root as defence in depth; this regex is the first gate.
+ */
+export declare const TEMPLATE_PATH_RE: RegExp;
+/**
+ * A single template declaration: which `page` the theme ships a template for and the RELATIVE `path`
+ * to its JSON file inside the theme package. `.strict()` rejects unknown keys. The `path` is gated
+ * by {@link TEMPLATE_PATH_RE} (no `..`, no leading `/`, slug segments, `.json` suffix) so the
+ * declaration itself can never name a file outside the theme tree.
+ */
+export declare const themeTemplateDeclSchema: z.ZodObject<{
+    page: z.ZodEnum<{
+        home: "home";
+        product: "product";
+        category: "category";
+        products: "products";
+        search: "search";
+        cart: "cart";
+    }>;
+    path: z.ZodString;
+}, z.core.$strict>;
+/** A validated single template declaration (`{ page, path }`). */
+export type ThemeTemplateDecl = z.infer<typeof themeTemplateDeclSchema>;
+/**
+ * The manifest Zod schema. `.strict()` rejects unknown top-level keys. Mirrors the shape of
+ * the module manifest where it overlaps (name/displayName/version/compatibleCore) so the two
+ * verifiers stay recognisably similar.
+ */
+export declare const themeManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodString;
+    version: z.ZodString;
+    compatibleCore: z.ZodString;
+    slots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    settingsSchema: z.ZodOptional<z.ZodString>;
+    templates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        page: z.ZodEnum<{
+            home: "home";
+            product: "product";
+            category: "category";
+            products: "products";
+            search: "search";
+            cart: "cart";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ThemeManifest = z.infer<typeof themeManifestSchema>;
+/**
+ * Parse + verify a raw `sovecom.theme.json` string. Enforces the byte cap, parses JSON
+ * (mapping a parse failure to a clear error), then runs the Zod schema. Returns the typed
+ * manifest or throws a descriptive `Error`. PURE — no I/O, no code execution.
+ */
+export declare function parseAndVerifyThemeManifest(raw: string): ThemeManifest;
+export { MANIFEST_MAX_BYTES, assertCoreCompatible };
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAuC/E,4EAA4E;AAC5E,eAAO,MAAM,aAAa,QAAsB,CAAC;AACjD,4FAA4F;AAC5F,eAAO,MAAM,YAAY,QAAsB,CAAC;AAChD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAAwD,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;kBASzB,CAAC;AAEZ,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAuCrB,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAuBtE;AAKD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertCoreCompatible = exports.MANIFEST_MAX_BYTES = exports.themeManifestSchema = exports.themeTemplateDeclSchema = exports.TEMPLATE_PATH_RE = exports.SLOT_SLUG_RE = exports.THEME_NAME_RE = void 0;
+exports.parseAndVerifyThemeManifest = parseAndVerifyThemeManifest;
+const semver = __importStar(require("semver"));
+const zod_1 = require("zod");
+// Reuse the SHARED core-API primitives from @sovecom/module-sdk so BOTH SDKs gate against ONE
+// `CORE_API_VERSION` and ONE byte cap (single source of truth; no duplication).
+const module_sdk_1 = require("@sovecom/module-sdk");
+Object.defineProperty(exports, "MANIFEST_MAX_BYTES", { enumerable: true, get: function () { return module_sdk_1.MANIFEST_MAX_BYTES; } });
+Object.defineProperty(exports, "assertCoreCompatible", { enumerable: true, get: function () { return module_sdk_1.assertCoreCompatible; } });
+// The `templates[]` declaration on the manifest references the page-type enum that the template
+// contract owns. Reuse it so the manifest and the template validator agree on
+// exactly which page types exist — no second enum to drift.
+const template_js_1 = require("./template.js");
+/**
+ * Theme manifest verification — the single source of truth. Exported from `@sovecom/theme-sdk`, so
+ * the published author SDK, the core runtime, and the contract-test suite all share ONE validator —
+ * it is structurally impossible for them to drift.
+ *
+ * PURE functions — no Nest, no DB, no filesystem, NO code execution. These parse and validate a
+ * `sovecom.theme.json` already read off disk. Themes are declarative ASSETS: there is no permission
+ * allowlist and no namespaced-tables rule (a theme owns NO DB tables). The security properties
+ * enforced here are data validation:
+ *   - `.strict()` so unknown top-level keys are rejected (supply-chain hygiene);
+ *   - the SAME byte cap as the module manifest on the raw bytes (reused from @sovecom/module-sdk);
+ *   - a slug `name`, a valid-semver `version`, a valid-range `compatibleCore`;
+ *   - a semver MAJOR gate against `CORE_API_VERSION` (reuses {@link assertCoreCompatible}).
+ * The `settingsSchema` path is stored OPAQUE — the referenced JSON-schema file is never read here
+ * (validation of theme settings against it is deferred).
+ */
+/** Bounds — generous but finite, to reject pathological manifests up front. */
+const MAX_NAME_LEN = 64;
+const MAX_DISPLAY_NAME_LEN = 128;
+const MAX_SLOTS = 64;
+const MAX_SLOT_LEN = 128;
+const MAX_SETTINGS_SCHEMA_LEN = 256;
+/**
+ * Bounds on the OPTIONAL `templates[]` declaration. A theme may ship at most one template per page
+ * type, so the array is capped at the number of page types (there is no point declaring more — the
+ * per-page-uniqueness refine would reject the duplicate anyway). The path is a bounded relative slug
+ * path ending in `.json`.
+ */
+const MAX_TEMPLATE_DECLS = template_js_1.PAGE_TYPES.length;
+const MAX_TEMPLATE_PATH_LEN = 256;
+/** Theme name: a slug that forms the install identity and a URL segment. */
+exports.THEME_NAME_RE = /^[a-z][a-z0-9-]*$/;
+/** A slot slug the theme exposes/renders (same lowercase-slug shape as the module side). */
+exports.SLOT_SLUG_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * A template file path: a SAFE RELATIVE slug path ending in `.json`. Each segment is a lowercase
+ * slug (a-z0-9, `_`, `-`), segments are `/`-joined, and the whole thing ends in `.json`. By
+ * construction this admits NO leading `/` (absolute), NO `..` segment (traversal), NO `\` (Windows
+ * separator), and NO `.`-only / hidden segments — the manifest is the ALLOWLIST of files the ingest
+ * is permitted to read out of the extracted tree. The ingest re-asserts containment
+ * against the extraction root as defence in depth; this regex is the first gate.
+ */
+exports.TEMPLATE_PATH_RE = /^[a-z0-9][a-z0-9_-]*(\/[a-z0-9][a-z0-9_-]*)*\.json$/;
+/**
+ * A single template declaration: which `page` the theme ships a template for and the RELATIVE `path`
+ * to its JSON file inside the theme package. `.strict()` rejects unknown keys. The `path` is gated
+ * by {@link TEMPLATE_PATH_RE} (no `..`, no leading `/`, slug segments, `.json` suffix) so the
+ * declaration itself can never name a file outside the theme tree.
+ */
+exports.themeTemplateDeclSchema = zod_1.z
+    .object({
+    page: template_js_1.pageTypeSchema,
+    path: zod_1.z
+        .string()
+        .min(1)
+        .max(MAX_TEMPLATE_PATH_LEN)
+        .regex(exports.TEMPLATE_PATH_RE, 'path must be a relative .json slug path (no "..", no leading "/")'),
+})
+    .strict();
+/**
+ * The manifest Zod schema. `.strict()` rejects unknown top-level keys. Mirrors the shape of
+ * the module manifest where it overlaps (name/displayName/version/compatibleCore) so the two
+ * verifiers stay recognisably similar.
+ */
+exports.themeManifestSchema = zod_1.z
+    .object({
+    name: zod_1.z
+        .string()
+        .min(1)
+        .max(MAX_NAME_LEN)
+        .regex(exports.THEME_NAME_RE, 'name must be a lowercase slug like "aurora"'),
+    displayName: zod_1.z.string().min(1).max(MAX_DISPLAY_NAME_LEN),
+    version: zod_1.z
+        .string()
+        .max(64)
+        .refine((v) => semver.valid(v) !== null, 'version must be a valid semver'),
+    compatibleCore: zod_1.z
+        .string()
+        .max(256)
+        .refine((v) => semver.validRange(v) !== null, 'compatibleCore must be a valid semver range'),
+    slots: zod_1.z
+        .array(zod_1.z.string().min(1).max(MAX_SLOT_LEN).regex(exports.SLOT_SLUG_RE, 'slot must be a lowercase slug'))
+        .max(MAX_SLOTS)
+        // A theme declares any given slot at most once — mirrors the module side's duplicate-slot
+        // check so the two SDKs and `defineThemeSlots` agree.
+        .refine((arr) => new Set(arr).size === arr.length, 'each slot must be declared at most once')
+        .optional(),
+    settingsSchema: zod_1.z.string().min(1).max(MAX_SETTINGS_SCHEMA_LEN).optional(),
+    // OPTIONAL wire-delivered page templates. A bounded array of `{ page, path }` declarations:
+    // which page types the theme ships a template for, and the relative file to read at install.
+    // AT MOST ONE entry per page type (the `.refine`), array capped at the page-type count.
+    // Absent ⇒ a tokens/settings-only theme.
+    templates: zod_1.z
+        .array(exports.themeTemplateDeclSchema)
+        .max(MAX_TEMPLATE_DECLS)
+        .refine((arr) => new Set(arr.map((t) => t.page)).size === arr.length, 'each page type may be declared at most once in templates')
+        .optional(),
+})
+    .strict();
+/**
+ * Parse + verify a raw `sovecom.theme.json` string. Enforces the byte cap, parses JSON
+ * (mapping a parse failure to a clear error), then runs the Zod schema. Returns the typed
+ * manifest or throws a descriptive `Error`. PURE — no I/O, no code execution.
+ */
+function parseAndVerifyThemeManifest(raw) {
+    const byteLen = Buffer.byteLength(raw, 'utf8');
+    if (byteLen > module_sdk_1.MANIFEST_MAX_BYTES) {
+        throw new Error(`theme manifest too large: ${byteLen} bytes exceeds the ${module_sdk_1.MANIFEST_MAX_BYTES}-byte cap`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('theme manifest is not valid JSON');
+    }
+    const result = exports.themeManifestSchema.safeParse(parsed);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`invalid theme manifest: ${detail}`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkIA,kEAuBC;AAzJD,+CAAiC;AACjC,6BAAwB;AACxB,8FAA8F;AAC9F,gFAAgF;AAChF,oDAA+E;AA0JtE,mGA1JA,+BAAkB,OA0JA;AAAE,qGA1JA,iCAAoB,OA0JA;AAzJjD,gGAAgG;AAChG,8EAA8E;AAC9E,4DAA4D;AAC5D,+CAA2D;AAE3D;;;;;;;;;;;;;;;GAeG;AAEH,+EAA+E;AAC/E,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,wBAAU,CAAC,MAAM,CAAC;AAC7C,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,4EAA4E;AAC/D,QAAA,aAAa,GAAG,mBAAmB,CAAC;AACjD,4FAA4F;AAC/E,QAAA,YAAY,GAAG,mBAAmB,CAAC;AAChD;;;;;;;GAOG;AACU,QAAA,gBAAgB,GAAG,qDAAqD,CAAC;AAEtF;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,OAAC;KACrC,MAAM,CAAC;IACN,IAAI,EAAE,4BAAc;IACpB,IAAI,EAAE,OAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,qBAAqB,CAAC;SAC1B,KAAK,CAAC,wBAAgB,EAAE,mEAAmE,CAAC;CAChG,CAAC;KACD,MAAM,EAAE,CAAC;AAKZ;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,OAAC;KACjC,MAAM,CAAC;IACN,IAAI,EAAE,OAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,YAAY,CAAC;SACjB,KAAK,CAAC,qBAAa,EAAE,6CAA6C,CAAC;IACtE,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACxD,OAAO,EAAE,OAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,EAAE,CAAC;SACP,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,gCAAgC,CAAC;IAC5E,cAAc,EAAE,OAAC;SACd,MAAM,EAAE;SACR,GAAG,CAAC,GAAG,CAAC;SACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,6CAA6C,CAAC;IAC9F,KAAK,EAAE,OAAC;SACL,KAAK,CACJ,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,oBAAY,EAAE,+BAA+B,CAAC,CACzF;SACA,GAAG,CAAC,SAAS,CAAC;QACf,0FAA0F;QAC1F,sDAAsD;SACrD,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,EAAE,yCAAyC,CAAC;SAC5F,QAAQ,EAAE;IACb,cAAc,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,QAAQ,EAAE;IACzE,4FAA4F;IAC5F,6FAA6F;IAC7F,wFAAwF;IACxF,yCAAyC;IACzC,SAAS,EAAE,OAAC;SACT,KAAK,CAAC,+BAAuB,CAAC;SAC9B,GAAG,CAAC,kBAAkB,CAAC;SACvB,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,EAC5D,0DAA0D,CAC3D;SACA,QAAQ,EAAE;CACd,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ;;;;GAIG;AACH,SAAgB,2BAA2B,CAAC,GAAW;IACrD,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,+BAAkB,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,6BAA6B,OAAO,sBAAsB,+BAAkB,WAAW,CACxF,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,MAAM,GAAG,2BAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;aACvE,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/settings.d.ts

@@ -0,0 +1,84 @@
+/**
+ * OPTIONAL settings-schema typing helper(s).
+ *
+ * A theme MAY ship a `settingsSchema` path pointing at a JSON-schema file describing the shape of
+ * its tunable settings. That path stays OPAQUE: the core never reads or executes
+ * the referenced file at validation time. These helpers are therefore purely COMPILE-TIME
+ * ergonomics — they let an author type the settings object their theme expects, with NO runtime
+ * behaviour, NO file read, NO code execution. The author's settings shape is their own; the SDK
+ * only gives it a name.
+ */
+/**
+ * The settings shape a theme's `settingsSchema` describes — an arbitrary author-defined record.
+ * This is the same loose shape the store contract surfaces as {@link ActiveTheme.settings}.
+ * Authors may narrow it with their own interface (see {@link defineThemeSettings}).
+ */
+export type ThemeSettings = Record<string, unknown>;
+/**
+ * The design-token settings keys the MIT storefront RECOGNISES and maps onto CSS custom properties.
+ * Documenting them here gives theme authors editor autocomplete for the supported knobs
+ * WITHOUT closing the contract — {@link KnownThemeSettings} intersects this with the open-ended
+ * record so arbitrary author keys still type-check. No runtime behaviour: these are pure
+ * compile-time ergonomics (the SDK keeps `settings` opaque to the core).
+ *
+ * Typography values are CSS `font-family` STACKS (e.g. `Georgia, 'Times New Roman', serif`).
+ * Per the project's RGPD rule the storefront ships SYSTEM stacks only — no webfont files / Google
+ * Fonts / CDN — so these need no asset and are safe by construction.
+ */
+export interface DocumentedThemeSettings {
+    /** CSS color string for the page background (→ `--background`). */
+    readonly background?: string;
+    /** CSS color string for the body text (→ `--foreground`). */
+    readonly foreground?: string;
+    /** Brand/primary color (→ `--primary`). */
+    readonly primary?: string;
+    /** Primary hover color (→ `--primary-hover`). */
+    readonly primaryHover?: string;
+    /** Primary active/pressed color (→ `--primary-active`). */
+    readonly primaryActive?: string;
+    /** Text/icon color on a primary surface (→ `--primary-foreground`). */
+    readonly primaryForeground?: string;
+    /** Accent color (→ `--accent`). */
+    readonly accent?: string;
+    /** Text/icon color on an accent surface (→ `--accent-foreground`). */
+    readonly accentForeground?: string;
+    /** Focus ring color (→ `--ring`). */
+    readonly ring?: string;
+    /** CSS length for the corner radius scale (→ `--radius`). */
+    readonly radius?: string;
+    /** Base sans font-family stack (→ `--font-sans`). System stack — no webfont (RGPD). */
+    readonly fontSans?: string;
+    /**
+     * Heading font-family stack (→ `--font-heading`); override to a serif stack.
+     * System stack — no webfont (RGPD).
+     */
+    readonly fontHeading?: string;
+    /** Absolute http(s) or root-relative logo URL (consumed by the layout, not a CSS var). */
+    readonly logoUrl?: string;
+    /**
+     * Bounded HEADER LAYOUT chrome variant. NOT a CSS var — the storefront reads it to choose
+     * between the simple flat nav (`simple`, default) and a multi-column mega-menu (`mega`). An unknown
+     * value falls back to `simple`, so the default theme is unchanged.
+     */
+    readonly 'header.layout'?: 'simple' | 'mega';
+    /**
+     * Bounded CART AFFORDANCE chrome variant. NOT a CSS var — the storefront reads it to choose
+     * between opening the in-page drawer (`drawer`, default) and a plain link to `/cart` (`page-link`). An
+     * unknown value falls back to `drawer`, so the default theme is unchanged.
+     */
+    readonly 'cart.affordance'?: 'drawer' | 'page-link';
+}
+/**
+ * The settings shape with the {@link DocumentedThemeSettings} keys typed for autocomplete while
+ * staying open-ended for arbitrary author knobs. Use as the type argument to
+ * {@link defineThemeSettings} (e.g. `defineThemeSettings<KnownThemeSettings>({ … })`).
+ */
+export type KnownThemeSettings = DocumentedThemeSettings & ThemeSettings;
+/**
+ * Identity helper that simply types-and-returns an author's default settings object. Gives the
+ * author editor autocomplete + a single inferred `T` to reuse, while remaining a pure no-op at
+ * runtime (it returns its argument unchanged). It does NOT read or validate against the
+ * `settingsSchema` file — that path stays opaque.
+ */
+export declare function defineThemeSettings<T extends ThemeSettings>(defaults: T): T;
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,mCAAmC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,aAAa,CAAC;AAEzE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAE3E"}

package/dist/settings.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * OPTIONAL settings-schema typing helper(s).
+ *
+ * A theme MAY ship a `settingsSchema` path pointing at a JSON-schema file describing the shape of
+ * its tunable settings. That path stays OPAQUE: the core never reads or executes
+ * the referenced file at validation time. These helpers are therefore purely COMPILE-TIME
+ * ergonomics — they let an author type the settings object their theme expects, with NO runtime
+ * behaviour, NO file read, NO code execution. The author's settings shape is their own; the SDK
+ * only gives it a name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineThemeSettings = defineThemeSettings;
+/**
+ * Identity helper that simply types-and-returns an author's default settings object. Gives the
+ * author editor autocomplete + a single inferred `T` to reuse, while remaining a pure no-op at
+ * runtime (it returns its argument unchanged). It does NOT read or validate against the
+ * `settingsSchema` file — that path stays opaque.
+ */
+function defineThemeSettings(defaults) {
+    return defaults;
+}
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA6EH,kDAEC;AARD;;;;;GAKG;AACH,SAAgB,mBAAmB,CAA0B,QAAW;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/slots.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validate + return a theme slot-slug array for the manifest. Enforces the SAME rules as
+ * `themeManifestSchema`:
+ *   - each slot is a non-empty lowercase slug (`^[a-z][a-z0-9-]*$`);
+ *   - no slot slug appears more than once.
+ * Throws a clear `Error` on the first violation. Returns a fresh, frozen array.
+ */
+export declare function defineThemeSlots(slots: ReadonlyArray<string>): readonly string[];
+//# sourceMappingURL=slots.d.ts.map

package/dist/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../src/slots.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAmBhF"}

package/dist/slots.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineThemeSlots = defineThemeSlots;
+/**
+ * a typed AUTHORING helper for the theme
+ * manifest's declarative `slots: string[]` array (the slot slugs a theme exposes/renders).
+ *
+ * Slots are DECLARATIVE metadata; the slot registry is DERIVED at runtime from enabled MODULES'
+ * manifests. This helper is NOT an RPC and there is NO runtime `registerSlot`. It
+ * exists purely so a theme author can build a typed, validated list of the slot slugs the theme
+ * declares, mirroring the same rules the manifest schema enforces (lowercase slug shape; no
+ * duplicate slug). Its output is dropped verbatim into the manifest's `slots`.
+ */
+const manifest_js_1 = require("./manifest.js");
+/**
+ * Validate + return a theme slot-slug array for the manifest. Enforces the SAME rules as
+ * `themeManifestSchema`:
+ *   - each slot is a non-empty lowercase slug (`^[a-z][a-z0-9-]*$`);
+ *   - no slot slug appears more than once.
+ * Throws a clear `Error` on the first violation. Returns a fresh, frozen array.
+ */
+function defineThemeSlots(slots) {
+    if (!Array.isArray(slots)) {
+        throw new TypeError('defineThemeSlots(slots): slots must be an array');
+    }
+    const seen = new Set();
+    const out = [];
+    for (const slot of slots) {
+        if (typeof slot !== 'string' || !manifest_js_1.SLOT_SLUG_RE.test(slot)) {
+            throw new Error(`defineThemeSlots: slot "${String(slot)}" must be a lowercase slug`);
+        }
+        if (seen.has(slot)) {
+            throw new Error(`defineThemeSlots: slot "${slot}" is declared more than once; declare each slot at most once`);
+        }
+        seen.add(slot);
+        out.push(slot);
+    }
+    return Object.freeze(out);
+}
+//# sourceMappingURL=slots.js.map

package/dist/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../src/slots.ts"],"names":[],"mappings":";;AAmBA,4CAmBC;AAtCD;;;;;;;;;GASG;AACH,+CAA6C;AAE7C;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAAC,KAA4B;IAC3D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,0BAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QACvF,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,8DAA8D,CAC9F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC"}