@sovecom/theme-sdk 1.0.0-rc.1

package/dist/store-contract.d.ts

@@ -0,0 +1,35 @@
+/**
+ * the STORE-facing contract types the storefront will
+ * consume. These describe the two tiny, already-shipped store endpoints a theme touches — there is
+ * no other runtime contract:
+ *   - `GET /store/v1/theme` → `ActiveTheme` (`{ name, version, settings }`);
+ *   - `GET /store/v1/slots` → `SlotMap` (`Record<slot, { module, component }>`, conflicts omitted).
+ *
+ * A CI type-conformance guard in apps/api asserts the in-tree view types (`ActiveThemeView` in
+ * `themes.service.ts`, the store slot map in `slots.controller.store.ts`) stay assignable to these
+ * exported types — so the seam is guarded at compile time, not by hope.
+ */
+import type { ThemeSettings } from './settings.js';
+/**
+ * The public store view of the active theme — exactly what `GET /store/v1/theme` returns and what
+ * the storefront reads to render. Name + version + the (opaque) settings record only.
+ */
+export interface ActiveTheme {
+    readonly name: string;
+    readonly version: string;
+    readonly settings: ThemeSettings;
+}
+/**
+ * A single cleanly-resolved slot binding: the module that fills the slot and the component id the
+ * storefront maps to that module's UI.
+ */
+export interface SlotBinding {
+    readonly module: string;
+    readonly component: string;
+}
+/**
+ * The public slot map — exactly what `GET /store/v1/slots` returns: `slot → { module, component }`
+ * for cleanly-resolved slots only (conflicts/unresolved slots are OMITTED, never silently picked).
+ */
+export type SlotMap = Record<string, SlotBinding>;
+//# sourceMappingURL=store-contract.d.ts.map

package/dist/store-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-contract.d.ts","sourceRoot":"","sources":["../src/store-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC"}

package/dist/store-contract.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=store-contract.js.map

package/dist/store-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-contract.js","sourceRoot":"","sources":["../src/store-contract.ts"],"names":[],"mappings":""}

package/dist/template.d.ts

@@ -0,0 +1,119 @@
+/**
+ * the section/JSON-template contract for theme COMPOSITION.
+ *
+ * A page template is a declarative JSON document: a `page` type plus an ordered list of `sections`,
+ * each a `{ type, settings? }` pair. The storefront runtime resolves each `type` against a section
+ * registry and renders the sections in order. Like the manifest (see `manifest.ts`), this is a
+ * declarative ASSET — there is NO code execution here: these are PURE validators + author-time typing
+ * helpers, exactly mirroring `parseAndVerifyThemeManifest` / `defineTheme` / `defineThemeSettings`.
+ *
+ * The manifest is NOT touched: the `templates[]` declaration on the manifest itself is deferred to a
+ * later stage. This file only ADDS the template contract; `apps/api` is unaffected.
+ *
+ * The byte cap is REUSED from `@sovecom/module-sdk` (via `manifest.ts`) so a template is gated by the
+ * same finite size bound as a manifest — one home for the cap, no duplication.
+ */
+import { z } from 'zod';
+/**
+ * Max nesting depth of `regions`. Depth 0 = a top-level section; a layout section with
+ * `regions` is depth 1; a section INSIDE a region is depth 2. Two levels of layout nesting is the
+ * cap — enough for the `columns` sidebar/results split without unbounded recursion. Enforced in
+ * {@link parseTemplate} (the schema validates shape/bounds; this walk rejects over-depth).
+ */
+export declare const MAX_REGION_DEPTH = 2;
+/** A region name is a non-empty lowercase slug (e.g. `left`/`right`) — same shape as a section type. */
+export declare const REGION_NAME_RE: RegExp;
+/**
+ * The page types a theme can supply a template for. Only `home` is consumed at this stage; the rest
+ * are DECLARED so later stages slot in (product/category/products/search/cart) without a contract
+ * change. The literal-tuple `as const` lets {@link pageTypeSchema} mirror it exactly.
+ */
+export declare const PAGE_TYPES: readonly ["home", "product", "category", "products", "search", "cart"];
+/** A section `type`: the same lowercase-slug shape as a theme name / slot slug (`manifest.ts`). */
+export declare const SECTION_TYPE_RE: RegExp;
+/** Zod enum over {@link PAGE_TYPES}. Rejects any page type outside the declared set. */
+export declare const pageTypeSchema: z.ZodEnum<{
+    home: "home";
+    product: "product";
+    category: "category";
+    products: "products";
+    search: "search";
+    cart: "cart";
+}>;
+/**
+ * A region-name key schema: a non-empty, bounded lowercase slug (e.g. `left`/`right`). Used as the
+ * KEY schema of the `regions` record so a bad region name is rejected at parse time.
+ */
+export declare const regionNameSchema: z.ZodString;
+/**
+ * A single template section: a slug `type`, an optional opaque `settings` bag, and an
+ * OPTIONAL `regions` map for LAYOUT nesting — named region → an ordered list of nested sections,
+ * recursively the same shape. `.strict()` rejects unknown keys (supply-chain hygiene, mirrors the
+ * manifest). `settings` is `Record<string, unknown>` — opaque on the wire, validated against the
+ * section's own shape at render time (not here).
+ *
+ * The schema is SELF-REFERENTIAL: `regions` values are arrays of `templateSectionSchema`. The
+ * recursion uses the canonical Zod 4 pattern — a FIELD-LEVEL `z.lazy()` that defers the self-reference
+ * to validation time, so `templateSectionSchema` is fully initialised before the thunk dereferences
+ * it (no eager-`.strict()` ordering hazard). Structural bounds (region count, per-region section cap,
+ * region-name shape) are enforced HERE; the max NESTING DEPTH is enforced separately in
+ * {@link parseTemplate} (a post-parse walk), so an over-deep template is rejected with a clear error.
+ */
+export declare const templateSectionSchema: z.ZodType<TemplateSection>;
+/**
+ * A page template: a known `page` type plus an ordered, bounded list of sections. `.strict()` rejects
+ * unknown top-level keys. The section count is capped at {@link MAX_SECTIONS} to reject runaway docs.
+ */
+export declare const templateSchema: z.ZodObject<{
+    page: z.ZodEnum<{
+        home: "home";
+        product: "product";
+        category: "category";
+        products: "products";
+        search: "search";
+        cart: "cart";
+    }>;
+    sections: z.ZodArray<z.ZodType<TemplateSection, unknown, z.core.$ZodTypeInternals<TemplateSection, unknown>>>;
+}, z.core.$strict>;
+/** A validated page type (one of {@link PAGE_TYPES}). */
+export type PageType = z.infer<typeof pageTypeSchema>;
+/**
+ * A validated template section (`{ type, settings?, regions? }`). SELF-REFERENTIAL:
+ * `regions` maps a region name → a list of nested `TemplateSection`s. Hand-written rather than
+ * `z.infer`'d so the recursion is explicit + stable across the getter-based schema.
+ */
+export interface TemplateSection {
+    type: string;
+    settings?: Record<string, unknown>;
+    regions?: Record<string, TemplateSection[]>;
+}
+/** A validated page template (`{ page, sections }`). */
+export type ThemeTemplate = z.infer<typeof templateSchema>;
+/**
+ * Parse + verify a raw template JSON string. Enforces the byte cap (reused from the manifest), parses
+ * JSON (mapping a parse failure to a clear error), then runs the Zod schema, aggregating issues into a
+ * descriptive message. Returns the typed template or throws a descriptive `Error`. PURE — no I/O, no
+ * code execution. Mirrors {@link parseAndVerifyThemeManifest}.
+ */
+export declare function parseTemplate(raw: string): ThemeTemplate;
+/**
+ * Validate an author's template config and return the validated, typed {@link ThemeTemplate}. Runs the
+ * SAME `parseTemplate` pipeline (round-trips through JSON), so what passes here is exactly what the
+ * runtime accepts. Throws a clear `Error` on invalid input. NO code execution. Mirrors {@link defineTheme}.
+ */
+export declare function defineTemplate(config: ThemeTemplate): ThemeTemplate;
+/**
+ * An author-time section DEFINITION: the section `type` plus an OPTIONAL phantom `settings` default
+ * carrying the settings type `T`. Purely a typing vehicle — see {@link defineSection}.
+ */
+export interface SectionDef<T> {
+    readonly type: string;
+    readonly settings?: T;
+}
+/**
+ * Identity helper that types-and-returns a section definition, pinning the settings type `T` for
+ * author editor autocomplete. A pure no-op at runtime (returns its argument unchanged) — it does NOT
+ * validate or read anything. Mirrors {@link defineThemeSettings}'s pure-typing style.
+ */
+export declare function defineSection<T>(def: SectionDef<T>): SectionDef<T>;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,wGAAwG;AACxG,eAAO,MAAM,cAAc,QAAsB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,UAAU,wEAAyE,CAAC;AAEjG,mGAAmG;AACnG,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD,wFAAwF;AACxF,eAAO,MAAM,cAAc;;;;;;;EAAqB,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,aAI+C,CAAC;AAE7E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAqBpB,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;kBAKhB,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;CAC7C;AACD,wDAAwD;AACxD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA6BxD;AAkBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAKnE;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}

package/dist/template.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templateSchema = exports.templateSectionSchema = exports.regionNameSchema = exports.pageTypeSchema = exports.SECTION_TYPE_RE = exports.PAGE_TYPES = exports.REGION_NAME_RE = exports.MAX_REGION_DEPTH = void 0;
+exports.parseTemplate = parseTemplate;
+exports.defineTemplate = defineTemplate;
+exports.defineSection = defineSection;
+/**
+ * the section/JSON-template contract for theme COMPOSITION.
+ *
+ * A page template is a declarative JSON document: a `page` type plus an ordered list of `sections`,
+ * each a `{ type, settings? }` pair. The storefront runtime resolves each `type` against a section
+ * registry and renders the sections in order. Like the manifest (see `manifest.ts`), this is a
+ * declarative ASSET — there is NO code execution here: these are PURE validators + author-time typing
+ * helpers, exactly mirroring `parseAndVerifyThemeManifest` / `defineTheme` / `defineThemeSettings`.
+ *
+ * The manifest is NOT touched: the `templates[]` declaration on the manifest itself is deferred to a
+ * later stage. This file only ADDS the template contract; `apps/api` is unaffected.
+ *
+ * The byte cap is REUSED from `@sovecom/module-sdk` (via `manifest.ts`) so a template is gated by the
+ * same finite size bound as a manifest — one home for the cap, no duplication.
+ */
+const zod_1 = require("zod");
+const manifest_js_1 = require("./manifest.js");
+/** Generous-but-finite bound — reject pathological templates up front. */
+const MAX_SECTIONS = 64;
+/** A section type is a non-empty lowercase slug — same length bound the manifest uses for slots. */
+const MAX_SECTION_TYPE_LEN = 128;
+/** A layout section nests sub-sections in named `regions` — bound the region-name count. */
+const MAX_REGIONS = 8;
+/**
+ * Max nesting depth of `regions`. Depth 0 = a top-level section; a layout section with
+ * `regions` is depth 1; a section INSIDE a region is depth 2. Two levels of layout nesting is the
+ * cap — enough for the `columns` sidebar/results split without unbounded recursion. Enforced in
+ * {@link parseTemplate} (the schema validates shape/bounds; this walk rejects over-depth).
+ */
+exports.MAX_REGION_DEPTH = 2;
+/** A region name is a non-empty lowercase slug (e.g. `left`/`right`) — same shape as a section type. */
+exports.REGION_NAME_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * The page types a theme can supply a template for. Only `home` is consumed at this stage; the rest
+ * are DECLARED so later stages slot in (product/category/products/search/cart) without a contract
+ * change. The literal-tuple `as const` lets {@link pageTypeSchema} mirror it exactly.
+ */
+exports.PAGE_TYPES = ['home', 'product', 'category', 'products', 'search', 'cart'];
+/** A section `type`: the same lowercase-slug shape as a theme name / slot slug (`manifest.ts`). */
+exports.SECTION_TYPE_RE = /^[a-z][a-z0-9-]*$/;
+/** Zod enum over {@link PAGE_TYPES}. Rejects any page type outside the declared set. */
+exports.pageTypeSchema = zod_1.z.enum(exports.PAGE_TYPES);
+/**
+ * A region-name key schema: a non-empty, bounded lowercase slug (e.g. `left`/`right`). Used as the
+ * KEY schema of the `regions` record so a bad region name is rejected at parse time.
+ */
+exports.regionNameSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(MAX_SECTION_TYPE_LEN)
+    .regex(exports.REGION_NAME_RE, 'region name must be a lowercase slug like "left"');
+/**
+ * A single template section: a slug `type`, an optional opaque `settings` bag, and an
+ * OPTIONAL `regions` map for LAYOUT nesting — named region → an ordered list of nested sections,
+ * recursively the same shape. `.strict()` rejects unknown keys (supply-chain hygiene, mirrors the
+ * manifest). `settings` is `Record<string, unknown>` — opaque on the wire, validated against the
+ * section's own shape at render time (not here).
+ *
+ * The schema is SELF-REFERENTIAL: `regions` values are arrays of `templateSectionSchema`. The
+ * recursion uses the canonical Zod 4 pattern — a FIELD-LEVEL `z.lazy()` that defers the self-reference
+ * to validation time, so `templateSectionSchema` is fully initialised before the thunk dereferences
+ * it (no eager-`.strict()` ordering hazard). Structural bounds (region count, per-region section cap,
+ * region-name shape) are enforced HERE; the max NESTING DEPTH is enforced separately in
+ * {@link parseTemplate} (a post-parse walk), so an over-deep template is rejected with a clear error.
+ */
+exports.templateSectionSchema = zod_1.z
+    .object({
+    type: zod_1.z
+        .string()
+        .min(1)
+        .max(MAX_SECTION_TYPE_LEN)
+        .regex(exports.SECTION_TYPE_RE, 'section type must be a lowercase slug like "featured-products"'),
+    settings: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    // Canonical Zod 4 recursion: a field-level `z.lazy()` thunk yields a `regions` record of
+    // region-name → bounded array of nested sections; the region-COUNT cap is a `.refine` on the
+    // record. Nesting DEPTH (≤ MAX_REGION_DEPTH) is enforced separately in `parseTemplate`.
+    regions: zod_1.z
+        .lazy(() => zod_1.z
+        .record(exports.regionNameSchema, zod_1.z.array(exports.templateSectionSchema).max(MAX_SECTIONS))
+        .refine((r) => Object.keys(r).length <= MAX_REGIONS, {
+        message: `a section may declare at most ${MAX_REGIONS} regions`,
+    }))
+        .optional(),
+})
+    .strict();
+/**
+ * A page template: a known `page` type plus an ordered, bounded list of sections. `.strict()` rejects
+ * unknown top-level keys. The section count is capped at {@link MAX_SECTIONS} to reject runaway docs.
+ */
+exports.templateSchema = zod_1.z
+    .object({
+    page: exports.pageTypeSchema,
+    sections: zod_1.z.array(exports.templateSectionSchema).max(MAX_SECTIONS),
+})
+    .strict();
+/**
+ * Parse + verify a raw template JSON string. Enforces the byte cap (reused from the manifest), parses
+ * JSON (mapping a parse failure to a clear error), then runs the Zod schema, aggregating issues into a
+ * descriptive message. Returns the typed template or throws a descriptive `Error`. PURE — no I/O, no
+ * code execution. Mirrors {@link parseAndVerifyThemeManifest}.
+ */
+function parseTemplate(raw) {
+    const byteLen = Buffer.byteLength(raw, 'utf8');
+    if (byteLen > manifest_js_1.MANIFEST_MAX_BYTES) {
+        throw new Error(`theme template too large: ${byteLen} bytes exceeds the ${manifest_js_1.MANIFEST_MAX_BYTES}-byte cap`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('theme template is not valid JSON');
+    }
+    const result = exports.templateSchema.safeParse(parsed);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`invalid theme template: ${detail}`);
+    }
+    // Enforce the max nesting depth. The Zod schema validates the shape + structural
+    // bounds at every level (region count, per-region cap, region-name slug, .strict), but a getter-
+    // based recursive schema can't bound DEPTH — so reject an over-deep `regions` tree here. Depth 0 =
+    // a top-level section; a section inside a region is depth 1; nested again is depth 2; deeper throws.
+    for (const section of result.data.sections)
+        assertRegionDepth(section, 0);
+    return result.data;
+}
+/**
+ * Recursively assert no `regions` nesting exceeds {@link MAX_REGION_DEPTH}. `depth` is the current
+ * section's depth (0 at the top level). Throws a descriptive `Error` on the first over-deep section.
+ */
+function assertRegionDepth(section, depth) {
+    if (!section.regions)
+        return;
+    if (depth >= exports.MAX_REGION_DEPTH) {
+        throw new Error(`invalid theme template: region nesting exceeds the max depth of ${exports.MAX_REGION_DEPTH}`);
+    }
+    for (const nested of Object.values(section.regions)) {
+        for (const child of nested)
+            assertRegionDepth(child, depth + 1);
+    }
+}
+/**
+ * Validate an author's template config and return the validated, typed {@link ThemeTemplate}. Runs the
+ * SAME `parseTemplate` pipeline (round-trips through JSON), so what passes here is exactly what the
+ * runtime accepts. Throws a clear `Error` on invalid input. NO code execution. Mirrors {@link defineTheme}.
+ */
+function defineTemplate(config) {
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+        throw new TypeError('defineTemplate(config): config must be an object');
+    }
+    return parseTemplate(JSON.stringify(config));
+}
+/**
+ * Identity helper that types-and-returns a section definition, pinning the settings type `T` for
+ * author editor autocomplete. A pure no-op at runtime (returns its argument unchanged) — it does NOT
+ * validate or read anything. Mirrors {@link defineThemeSettings}'s pure-typing style.
+ */
+function defineSection(def) {
+    return def;
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"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"}

package/dist/theme.d.ts

@@ -0,0 +1,35 @@
+/**
+ * the author-facing `defineTheme` helper.
+ *
+ * `defineTheme(config)` is the theme twin of `@sovecom/module-sdk`'s `defineModule`, with one
+ * LOAD-BEARING difference: a theme is a declarative ASSET — there is NO
+ * `activate`, NO worker, NO runtime entrypoint. So `defineTheme` does not wrap an executable
+ * body; it VALIDATES the author's config against the canonical manifest schema and returns the
+ * typed, validated `ThemeManifest` OBJECT. It is a build-/author-time helper, never a runtime
+ * entry. A misconfigured theme therefore fails fast with a clear message at author build time,
+ * not as an opaque install rejection.
+ */
+import { type ThemeManifest } from './manifest.js';
+/**
+ * Author-supplied config for {@link defineTheme}. Structurally the manifest shape itself — the
+ * author writes their `sovecom.theme.json` content as a typed object and `defineTheme` validates
+ * it. Kept as a distinct alias so the authoring intent (input) reads differently from the
+ * validated output ({@link ThemeManifest}).
+ *
+ * The `slots` INPUT is widened to `readonly string[]` so the documented compose pattern
+ * `defineTheme({ slots: defineThemeSlots([...]) })` typechecks — `defineThemeSlots` returns a
+ * FROZEN (`readonly`) array and that must be assignable here. The runtime validation is unchanged:
+ * `defineTheme` round-trips the config through `parseAndVerifyThemeManifest`, so the returned
+ * {@link ThemeManifest} still carries the schema-validated mutable `string[]`.
+ */
+export type DefineThemeConfig = Omit<ThemeManifest, 'slots'> & {
+    readonly slots?: readonly string[];
+};
+/**
+ * Validate an author's theme config and return the validated, typed {@link ThemeManifest}.
+ * Runs the SAME `parseAndVerifyThemeManifest` the core runs at install time (single source of
+ * truth), so what passes here is exactly what the core will accept. Throws a clear `Error` on
+ * invalid input (bad slug, invalid semver, unknown key, oversized, …). NO code execution.
+ */
+export declare function defineTheme(config: DefineThemeConfig): ThemeManifest;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,GAAG;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAQpE"}

package/dist/theme.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTheme = defineTheme;
+/**
+ * the author-facing `defineTheme` helper.
+ *
+ * `defineTheme(config)` is the theme twin of `@sovecom/module-sdk`'s `defineModule`, with one
+ * LOAD-BEARING difference: a theme is a declarative ASSET — there is NO
+ * `activate`, NO worker, NO runtime entrypoint. So `defineTheme` does not wrap an executable
+ * body; it VALIDATES the author's config against the canonical manifest schema and returns the
+ * typed, validated `ThemeManifest` OBJECT. It is a build-/author-time helper, never a runtime
+ * entry. A misconfigured theme therefore fails fast with a clear message at author build time,
+ * not as an opaque install rejection.
+ */
+const manifest_js_1 = require("./manifest.js");
+/**
+ * Validate an author's theme config and return the validated, typed {@link ThemeManifest}.
+ * Runs the SAME `parseAndVerifyThemeManifest` the core runs at install time (single source of
+ * truth), so what passes here is exactly what the core will accept. Throws a clear `Error` on
+ * invalid input (bad slug, invalid semver, unknown key, oversized, …). NO code execution.
+ */
+function defineTheme(config) {
+    if (config === null || typeof config !== 'object') {
+        throw new TypeError('defineTheme(config): config must be an object');
+    }
+    // Round-trip through the canonical validator: serialise, then parse+verify. This reuses the
+    // one byte-cap + `.strict()` + slug + semver pipeline the core enforces, so `defineTheme`
+    // cannot drift from install-time validation.
+    return (0, manifest_js_1.parseAndVerifyThemeManifest)(JSON.stringify(config));
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":";;AAmCA,kCAQC;AA3CD;;;;;;;;;;GAUG;AACH,+CAAgF;AAkBhF;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,MAAyB;IACnD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,4FAA4F;IAC5F,0FAA0F;IAC1F,6CAA6C;IAC7C,OAAO,IAAA,yCAA2B,EAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/widget.d.ts

@@ -0,0 +1,200 @@
+/**
+ * the module slot-widget CONTRACT + vocabulary.
+ *
+ * A sandboxed module contributes storefront UI by returning a typed **widget descriptor**
+ * `{ type, props }` — a widget `type` from a CLOSED, core-owned MIT vocabulary plus validated props.
+ * The storefront renders its OWN known MIT components with that data; NO code, NO HTML, NO SVG
+ * crosses the boundary — only DATA.
+ *
+ * Like `manifest.ts` / `template.ts`, this file is a declarative ASSET contract: PURE validators +
+ * types only. There is NO React, NO fetch, NO Node runtime API, NO render here. `parseWidget` mirrors
+ * `parseTemplate`'s byte-cap + JSON.parse + Zod pipeline, with ONE deliberate difference: it returns
+ * `null` on ANY failure (never throws) — the defensive fail-closed contract the storefront RSC relies
+ * on to "render nothing, never 500 the page".
+ *
+ * The byte cap is its own constant ({@link WIDGET_MAX_BYTES}) but reuses the manifest cap value so a
+ * widget descriptor is gated by the same finite bound — one numeric home, no divergence.
+ */
+import { z } from 'zod';
+/**
+ * The CLOSED, core-owned widget vocabulary. A module author CANNOT register a new type;
+ * adding one is an MIT storefront contribution reviewed like adding a section. The
+ * `component` slug in a module manifest's `slots[]` IS one of these `type`s. The literal-tuple
+ * `as const` lets the discriminated union below mirror it exactly.
+ */
+export declare const WIDGET_TYPES: readonly ["star-rating-summary", "review-list", "product-carousel", "toggle-button", "submit-form"];
+/** A validated widget type (one of {@link WIDGET_TYPES}). */
+export type WidgetType = (typeof WIDGET_TYPES)[number];
+/**
+ * Byte cap for a raw widget descriptor. Reuses the manifest cap VALUE (one source of truth) — a
+ * descriptor is small data, so this generous bound only rejects pathological payloads up front, before
+ * any JSON.parse or schema work.
+ */
+export declare const WIDGET_MAX_BYTES: number;
+export declare const actionPathSchema: z.ZodString;
+/** An interactive widget's action target: just a validated relative `path` (C1 shape-only). */
+export declare const actionSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>;
+/** `star-rating-summary` props: an average in [0,5] and a non-negative integer count. */
+export declare const starRatingSummaryPropsSchema: z.ZodObject<{
+    average: z.ZodNumber;
+    count: z.ZodNumber;
+}, z.core.$strict>;
+/** `review-list` props: a bounded list of bounded review items (id/rating/body/author/createdAt). */
+export declare const reviewListPropsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        rating: z.ZodNumber;
+        body: z.ZodString;
+        author: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** `product-carousel` props: an optional heading + a bounded list of bounded product cards. */
+export declare const productCarouselPropsSchema: z.ZodObject<{
+    heading: z.ZodOptional<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        slug: z.ZodString;
+        title: z.ZodString;
+        imageUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** `toggle-button` props: on/off actions (relative paths), bounded labels, enum-only icon. */
+export declare const toggleButtonPropsSchema: z.ZodObject<{
+    initialOn: z.ZodBoolean;
+    onAction: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>;
+    offAction: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>;
+    labels: z.ZodObject<{
+        on: z.ZodString;
+        off: z.ZodString;
+    }, z.core.$strict>;
+    icon: z.ZodEnum<{
+        heart: "heart";
+        bell: "bell";
+        star: "star";
+    }>;
+}, z.core.$strict>;
+/** `submit-form` props: a relative action path, a bounded field list with enum-only kinds. */
+export declare const submitFormPropsSchema: z.ZodObject<{
+    action: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>;
+    submitLabel: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        kind: z.ZodEnum<{
+            rating: "rating";
+            text: "text";
+            textarea: "textarea";
+            email: "email";
+            select: "select";
+        }>;
+        required: z.ZodBoolean;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    successMessage: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The widget descriptor: `{ type, props }` discriminated on `type`, so each widget's props are
+ * validated against ITS OWN schema (wrong props for a type ⇒ fail). `.strict()` on each member rejects
+ * unknown keys at the descriptor level; the per-widget props schemas are `.strict()` too, so unknown
+ * keys are rejected at BOTH levels.
+ */
+export declare const widgetDescriptorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"star-rating-summary">;
+    props: z.ZodObject<{
+        average: z.ZodNumber;
+        count: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"review-list">;
+    props: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            rating: z.ZodNumber;
+            body: z.ZodString;
+            author: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"product-carousel">;
+    props: z.ZodObject<{
+        heading: z.ZodOptional<z.ZodString>;
+        items: z.ZodArray<z.ZodObject<{
+            productId: z.ZodString;
+            slug: z.ZodString;
+            title: z.ZodString;
+            imageUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"toggle-button">;
+    props: z.ZodObject<{
+        initialOn: z.ZodBoolean;
+        onAction: z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>;
+        offAction: z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>;
+        labels: z.ZodObject<{
+            on: z.ZodString;
+            off: z.ZodString;
+        }, z.core.$strict>;
+        icon: z.ZodEnum<{
+            heart: "heart";
+            bell: "bell";
+            star: "star";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"submit-form">;
+    props: z.ZodObject<{
+        action: z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>;
+        submitLabel: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            kind: z.ZodEnum<{
+                rating: "rating";
+                text: "text";
+                textarea: "textarea";
+                email: "email";
+                select: "select";
+            }>;
+            required: z.ZodBoolean;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        successMessage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+export type StarRatingSummaryProps = z.infer<typeof starRatingSummaryPropsSchema>;
+export type ReviewListProps = z.infer<typeof reviewListPropsSchema>;
+export type ProductCarouselProps = z.infer<typeof productCarouselPropsSchema>;
+export type ToggleButtonProps = z.infer<typeof toggleButtonPropsSchema>;
+export type SubmitFormProps = z.infer<typeof submitFormPropsSchema>;
+/** A validated widget descriptor (the discriminated `{ type, props }`). */
+export type WidgetDescriptor = z.infer<typeof widgetDescriptorSchema>;
+/**
+ * Parse + verify a raw widget descriptor. PURE — no I/O, no code execution, no render.
+ *
+ * Accepts either a JSON string (the wire form — byte-capped, then `JSON.parse`d, mirroring
+ * {@link parseTemplate}) or an already-parsed value (so the storefront can hand it the parsed JSON
+ * directly). Enforces the byte cap on the string form, validates against {@link widgetDescriptorSchema}
+ * (the discriminated union + per-widget `.strict()` props), and returns the typed descriptor — or
+ * `null` on ANY failure: oversized, non-JSON, non-object, unknown type, discriminator mismatch, an
+ * out-of-bounds / bad-enum / bad-path prop, or an unknown key at either level. It NEVER throws: the
+ * fail-closed contract the storefront RSC relies on to "render nothing, never block or 500 the page".
+ */
+export declare function parseWidget(raw: unknown): WidgetDescriptor | null;
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,qGAMf,CAAC;AAEX,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAmDnD,eAAO,MAAM,gBAAgB,aAOzB,CAAC;AAEL,+FAA+F;AAC/F,eAAO,MAAM,YAAY;;kBAAgD,CAAC;AAI1E,yFAAyF;AACzF,eAAO,MAAM,4BAA4B;;;kBAK9B,CAAC;AAEZ,qGAAqG;AACrG,eAAO,MAAM,qBAAqB;;;;;;;;kBAkBvB,CAAC;AAmBZ,+FAA+F;AAC/F,eAAO,MAAM,0BAA0B;;;;;;;;kBAgB5B,CAAC;AAEZ,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;kBAazB,CAAC;AAEZ,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;kBAmBvB,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAQjC,CAAC;AAGH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAcjE"}