@lssm/lib.contracts-spec 17.3.2

package/dist/tests/spec.js

@@ -0,0 +1 @@
+export class TestRegistry{items=new Map;register(e){const t=r(e.meta);if(this.items.has(t))throw Error(`Duplicate TestSpec registration for ${t}`);this.items.set(t,e);return this}list(){return[...this.items.values()]}get(e,t){if(t!=null)return this.items.get(`${e}.v${t}`);let n;for(const s of this.items.values()){if(s.meta.key!==e)continue;if(!n||o(s.meta.version,n.meta.version)>0)n=s}return n}}import{compareVersions as o}from"compare-versions";const r=(e)=>`${e.key}.v${e.version}`;export function makeTestKey(e){return r(e)}export function defineTestSpec(e){return e}export const tech_contracts_tests_DocBlocks=[{id:"docs.tech.contracts.tests",title:"TestSpec & TestRunner",summary:"Use `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/tests",tags:["tech","contracts","tests"],body:"## TestSpec & TestRunner\n\nUse `TestSpec` to describe end-to-end scenarios for contracts and workflows. Specs live alongside your contracts and exercise the same OperationSpecRegistry handlers the app uses.\n\n- Types & registry: `packages/libs/contracts/src/tests/spec.ts`\n- Runtime runner: `packages/libs/contracts/src/tests/runner.ts`\n- CLI: `contractspec test`\n\n### Structure\n\n```ts\nexport interface TestSpec {\n  meta: TestSpecMeta;\n  target: TestTarget;  // contract or workflow\n  fixtures?: Fixture[]; // optional shared setup before each scenario\n  scenarios: TestScenario[];\n  coverage?: CoverageRequirement;\n}\n```\n\n- `Fixture`: run an operation before the scenario (`operation`, optional `input`)\n- `Action`: operation input that the scenario exercises\n- `Assertion`:\n  - `expectOutput` `{ match }` deep-equals the handler output\n  - `expectError` `{ messageIncludes? }` ensures an error was thrown\n  - `expectEvents` `{ events: [{ name, version, min?, max? }] }` checks emitted events\n\n### Example\n\n```ts\nimport { defineCommand, type TestSpec } from '@lssm/lib.contracts-spec';\n\nexport const AddNumbersSpec = defineCommand({\n  meta: { key: 'math.add', version: '1.0.0', /* \u2026 */ },\n  io: {\n    input: AddNumbersInput,\n    output: AddNumbersOutput,\n  },\n  policy: { auth: 'user' },\n});\n\nexport const MathAddTests: TestSpec = {\n  meta: {\n    name: 'math.add.tests',\n    version: '1.0.0',\n    title: 'Math add scenarios',\n    owners: ['@team.math'],\n    tags: ['math'],\n    stability: StabilityEnum.Experimental,\n  },\n  target: { type: 'contract', operation: { name: 'math.add' } },\n  scenarios: [\n    {\n      name: 'adds positive numbers',\n      when: {\n        operation: { name: 'math.add' },\n        input: { a: 2, b: 3 },\n      },\n      then: [\n        { type: 'expectOutput', match: { sum: 5 } },\n        {\n          type: 'expectEvents',\n          events: [{ name: 'math.sum_calculated', version: '1.0.0', min: 1 }],\n        },\n      ],\n    },\n  ],\n};\n```\n\n### Running tests\n\n1. Register the contract handlers in a `OperationSpecRegistry`:\n\n```ts\nexport function createRegistry() {\n  const registry = new OperationSpecRegistry();\n  registry.register(AddNumbersSpec);\n  registry.bind(AddNumbersSpec, addNumbersHandler);\n  return registry;\n}\n```\n\n2. Run the CLI:\n\n```\ncontractspec test apps/math/tests/math.add.tests.ts \\\n  --registry apps/math/tests/registry.ts\n```\n\n- The CLI loads the TestSpec, instantiates the registry (via the provided module), and executes each scenario via `TestRunner`.\n- `--json` outputs machine-readable results.\n\n### Programmatic usage\n\n```ts\nconst runner = new TestRunner({\n  registry,\n  createContext: () => ({ actor: 'user', organizationId: 'tenant-1' }),\n});\n\nconst result = await runner.run(MathAddTests);\nconsole.log(result.passed, result.failed);\n```\n\n- `createContext` can supply default `HandlerCtx` values.\n- `beforeEach` / `afterEach` hooks let you seed databases or reset state.\n\n### Best practices\n\n- Keep fixtures idempotent so scenarios can run in parallel in the future.\n- Use `expectEvents` to guard analytics/telemetry expectations.\n- Add specs to `TestRegistry` for discovery and documentation.\n- `coverage` captures desired coverage metrics (enforced by future tooling).\n- Pair TestSpec files with CI using `contractspec test --json` and fail builds when `failed > 0`.\n\n### Mocking with Bun's `vi`\n\n- Pass a single function type to `vi.fn<TFunction>()` so calls retain typed arguments:\n\n```ts\nconst handler = vi.fn<typeof fetch>();\nconst fetchImpl: typeof fetch = ((...args) => handler(...args)) as typeof fetch;\nObject.defineProperty(fetchImpl, 'preconnect', {\n  value: vi.fn<typeof fetch.preconnect>(),\n});\n```\n\n- When you need to inspect calls, use the typed mock (`handler.mock.calls`) rather than casting to `any`.\n- Narrow optional request data defensively (e.g., check for headers before reading them) so tests remain type-safe under strict `tsconfig` settings.\n\n"}];

package/dist/themes.d.js

@@ -0,0 +1 @@
+export{assertThemeSpecValid,ThemeValidationError,validateThemeSpec}from"./themes.validation.js";

package/dist/themes.d.ts

@@ -0,0 +1,248 @@
+/** Scope at which a theme can be applied. */
+import type { DocBlock } from './docs/types.js';
+import type { OwnerShipMeta } from './ownership.js';
+import { SpecContractRegistry } from './registry.js';
+import type { VersionedSpecRef } from './versioning/index.js';
+export { assertThemeSpecValid, ThemeValidationError, type ThemeValidationIssue, type ThemeValidationLevel, type ThemeValidationResult, validateThemeSpec, } from './themes.validation.js';
+export type ThemeScope = 'global' | 'tenant' | 'user';
+export type ThemeColorFormat = 'hex' | 'rgb' | 'hsl' | 'oklch' | 'css' | (string & {});
+export type ThemeTokenUsage = 'semantic' | 'palette' | 'component' | (string & {});
+export interface ThemeToken<T> {
+    value: T;
+    description?: string;
+    format?: ThemeColorFormat;
+    usage?: ThemeTokenUsage;
+}
+/** A font choice with explicit values for CSS and React Native. */
+export interface ThemeFontTokenValue {
+    web: string;
+    native: string;
+}
+/** A platform-neutral density scale applied only inside design boundaries. */
+export interface ThemeDensityTokenValue {
+    spacing: number;
+    size: number;
+}
+/** A serializable elevation value that never sends a CSS shadow to native. */
+export interface ThemeElevationTokenValue {
+    web: string;
+    native: {
+        shadowColor: string;
+        shadowOpacity: number;
+        shadowRadius: number;
+        shadowOffset: {
+            width: number;
+            height: number;
+        };
+        elevation: number;
+    };
+}
+export interface ThemeTokens {
+    colors?: Record<string, ThemeToken<string>>;
+    radii?: Record<string, ThemeToken<number>>;
+    space?: Record<string, ThemeToken<number>>;
+    /** Numeric values are portable between CSS and native text styles. */
+    typography?: Record<string, ThemeToken<number>>;
+    shadows?: Record<string, ThemeToken<string>>;
+    /** Durations use serializable values such as `120ms`; executable easing is forbidden. */
+    motion?: Record<string, ThemeToken<string>>;
+    elevation?: Record<string, ThemeToken<ThemeElevationTokenValue>>;
+    density?: Record<string, ThemeToken<ThemeDensityTokenValue>>;
+    fonts?: Record<string, ThemeToken<ThemeFontTokenValue>>;
+}
+export interface ComponentVariantDefinition {
+    props?: Record<string, unknown>;
+    tokens?: ThemeTokens;
+}
+export interface ComponentVariantSpec {
+    component: string;
+    variants: Record<string, ComponentVariantDefinition>;
+}
+export type ThemeModeName = 'light' | 'dark' | (string & {});
+export interface ThemeModeSpec {
+    tokens?: ThemeTokens;
+    components?: ComponentVariantSpec[];
+    description?: string;
+}
+export interface ThemeOverride {
+    scope: ThemeScope;
+    target: string;
+    tokens?: ThemeTokens;
+    components?: ComponentVariantSpec[];
+    modes?: Record<string, ThemeModeSpec>;
+}
+export interface ThemeMeta extends OwnerShipMeta {
+    extends?: ThemeRef;
+    scopes?: ThemeScope[];
+}
+export interface ThemeSpec {
+    meta: ThemeMeta;
+    tokens: ThemeTokens;
+    components?: ComponentVariantSpec[];
+    overrides?: ThemeOverride[];
+    modes?: Record<string, ThemeModeSpec>;
+}
+/**
+ * Reference to a theme spec.
+ * Uses key and version to identify a specific theme.
+ */
+export type ThemeRef = VersionedSpecRef;
+export declare class ThemeRegistry extends SpecContractRegistry<'theme', ThemeSpec> {
+    constructor(items?: ThemeSpec[]);
+}
+export declare function makeThemeRef(spec: ThemeSpec): ThemeRef;
+export declare const defineTheme: (spec: ThemeSpec) => ThemeSpec;
+export declare const ContractSpecEditorialTheme: ThemeSpec;
+export declare const ContractSpecEditorialThemeCssVariables: {
+    readonly '--paper': '#f7f0e6';
+    readonly '--paper-muted': '#efe4d3';
+    readonly '--paper-panel': '#fbf7f0';
+    readonly '--ink': '#1d1b18';
+    readonly '--ink-soft': '#5e564d';
+    readonly '--line': '#d2c3ae';
+    readonly '--rust': '#a24f2a';
+    readonly '--rust-strong': '#854120';
+    readonly '--amber': '#d8a24a';
+    readonly '--blue': '#255678';
+    readonly '--success': '#2d6a4f';
+    readonly '--success-foreground': '#f4faf6';
+    readonly '--warning': '#905a18';
+    readonly '--warning-foreground': '#fff8f0';
+    readonly '--info': '#2b6688';
+    readonly '--info-foreground': '#eef7fb';
+    readonly '--background': 'var(--paper)';
+    readonly '--foreground': 'var(--ink)';
+    readonly '--card': 'var(--paper-panel)';
+    readonly '--card-foreground': 'var(--ink)';
+    readonly '--popover': 'var(--paper-panel)';
+    readonly '--popover-foreground': 'var(--ink)';
+    readonly '--primary': 'var(--rust)';
+    readonly '--primary-foreground': '#fff8f0';
+    readonly '--secondary': 'var(--paper-muted)';
+    readonly '--secondary-foreground': 'var(--ink)';
+    readonly '--muted': 'color-mix(in srgb, var(--paper-muted) 78%, #ffffff 22%)';
+    readonly '--muted-foreground': 'var(--ink-soft)';
+    readonly '--accent': 'var(--blue)';
+    readonly '--accent-foreground': '#eef7fb';
+    readonly '--destructive': '#b9372f';
+    readonly '--destructive-foreground': '#fff5f2';
+    readonly '--border': 'var(--line)';
+    readonly '--input': 'color-mix(in srgb, var(--paper-panel) 70%, #ffffff 30%)';
+    readonly '--ring': 'color-mix(in srgb, var(--rust) 60%, #ffffff 40%)';
+    readonly '--chart-1': 'var(--rust)';
+    readonly '--chart-2': 'var(--blue)';
+    readonly '--chart-3': 'var(--amber)';
+    readonly '--chart-4': '#7b4d2b';
+    readonly '--chart-5': '#446b55';
+    readonly '--radius': '1.25rem';
+    readonly '--radius-xs': '0.25rem';
+    readonly '--radius-sm': '0.5rem';
+    readonly '--radius-md': '0.75rem';
+    readonly '--radius-lg': '1rem';
+    readonly '--radius-xl': '1.5rem';
+    readonly '--radius-full': '9999px';
+    readonly '--radius-control': 'var(--radius-md)';
+    readonly '--radius-card': 'var(--radius-lg)';
+    readonly '--radius-panel': 'var(--radius)';
+    readonly '--radius-overlay': 'var(--radius-xl)';
+    readonly '--radius-pill': 'var(--radius-full)';
+    readonly '--sidebar': 'var(--paper-panel)';
+    readonly '--sidebar-foreground': 'var(--ink)';
+    readonly '--sidebar-primary': 'var(--rust)';
+    readonly '--sidebar-primary-foreground': '#fff8f0';
+    readonly '--sidebar-accent': 'var(--paper-muted)';
+    readonly '--sidebar-accent-foreground': 'var(--ink)';
+    readonly '--sidebar-border': 'var(--line)';
+    readonly '--sidebar-ring': 'color-mix(in srgb, var(--blue) 55%, #ffffff 45%)';
+};
+export declare const ContractSpecEditorialThemeDarkCssVariables: {
+    readonly '--background': '#161412';
+    readonly '--foreground': '#f5ede2';
+    readonly '--card': '#211d19';
+    readonly '--card-foreground': '#f5ede2';
+    readonly '--popover': '#211d19';
+    readonly '--popover-foreground': '#f5ede2';
+    readonly '--primary': '#c46c43';
+    readonly '--primary-foreground': '#161412';
+    readonly '--secondary': '#2c2723';
+    readonly '--secondary-foreground': '#f5ede2';
+    readonly '--muted': '#322c27';
+    readonly '--muted-foreground': '#cfbeb0';
+    readonly '--accent': '#79a8c6';
+    readonly '--accent-foreground': '#101418';
+    readonly '--destructive': '#d75950';
+    readonly '--destructive-foreground': '#161412';
+    readonly '--success': '#6bbf99';
+    readonly '--success-foreground': '#0d1f17';
+    readonly '--warning': '#e0a44a';
+    readonly '--warning-foreground': '#2a1c08';
+    readonly '--info': '#7fb4d6';
+    readonly '--info-foreground': '#0a1820';
+    readonly '--border': '#433a34';
+    readonly '--input': '#2b2622';
+    readonly '--ring': '#c46c43';
+    readonly '--sidebar': '#1c1916';
+    readonly '--sidebar-foreground': '#f5ede2';
+    readonly '--sidebar-primary': '#c46c43';
+    readonly '--sidebar-primary-foreground': '#161412';
+    readonly '--sidebar-accent': '#2b2622';
+    readonly '--sidebar-accent-foreground': '#f5ede2';
+    readonly '--sidebar-border': '#433a34';
+    readonly '--sidebar-ring': '#79a8c6';
+};
+export declare const ContractSpecEditorialThemeHslVariables: {
+    readonly '--background': '35 52% 94%';
+    readonly '--foreground': '36 9% 10%';
+    readonly '--card': '38 58% 96%';
+    readonly '--card-foreground': '36 9% 10%';
+    readonly '--popover': '38 58% 96%';
+    readonly '--popover-foreground': '36 9% 10%';
+    readonly '--primary': '19 59% 40%';
+    readonly '--primary-foreground': '32 100% 97%';
+    readonly '--secondary': '36 47% 88%';
+    readonly '--secondary-foreground': '36 9% 10%';
+    readonly '--muted': '35 48% 91%';
+    readonly '--muted-foreground': '32 10% 34%';
+    readonly '--accent': '205 53% 31%';
+    readonly '--accent-foreground': '198 62% 96%';
+    readonly '--destructive': '3 59% 45%';
+    readonly '--destructive-foreground': '14 100% 97%';
+    readonly '--success': '153 40% 30%';
+    readonly '--success-foreground': '150 33% 97%';
+    readonly '--warning': '33 71% 33%';
+    readonly '--warning-foreground': '33 100% 97%';
+    readonly '--info': '202 52% 35%';
+    readonly '--info-foreground': '200 60% 96%';
+    readonly '--border': '35 29% 75%';
+    readonly '--input': '37 57% 97%';
+    readonly '--ring': '18 39% 64%';
+};
+export declare const ContractSpecEditorialThemeDarkHslVariables: {
+    readonly '--background': '30 10% 8%';
+    readonly '--foreground': '35 49% 92%';
+    readonly '--card': '30 14% 11%';
+    readonly '--card-foreground': '35 49% 92%';
+    readonly '--popover': '30 14% 11%';
+    readonly '--popover-foreground': '35 49% 92%';
+    readonly '--primary': '19 52% 52%';
+    readonly '--primary-foreground': '30 10% 8%';
+    readonly '--secondary': '27 11% 15%';
+    readonly '--secondary-foreground': '35 49% 92%';
+    readonly '--muted': '27 12% 17%';
+    readonly '--muted-foreground': '27 24% 75%';
+    readonly '--accent': '203 40% 63%';
+    readonly '--accent-foreground': '210 20% 8%';
+    readonly '--destructive': '4 63% 58%';
+    readonly '--destructive-foreground': '30 10% 8%';
+    readonly '--success': '153 40% 58%';
+    readonly '--success-foreground': '156 40% 9%';
+    readonly '--warning': '36 71% 58%';
+    readonly '--warning-foreground': '36 68% 10%';
+    readonly '--info': '203 51% 67%';
+    readonly '--info-foreground': '206 53% 8%';
+    readonly '--border': '24 13% 23%';
+    readonly '--input': '27 12% 15%';
+    readonly '--ring': '19 52% 52%';
+};
+export declare const ContractSpecEditorialThemeBodyBackground = "linear-gradient(180deg, #f8f2e8 0%, #f7f0e6 38%, #f9f4ec 100%)";
+export declare const tech_contracts_themes_DocBlocks: DocBlock[];

package/dist/themes.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as a}from"./registry.js";export{assertThemeSpecValid,ThemeValidationError,validateThemeSpec}from"./themes.validation.js";export class ThemeRegistry extends a{constructor(e){super("theme",e)}}export function makeThemeRef(e){return{key:e.meta.key,version:e.meta.version}}export const defineTheme=(e)=>e;export const ContractSpecEditorialTheme=defineTheme({meta:{key:"contractspec.editorial",version:"1.0.0",title:"ContractSpec Editorial",description:"Warm paper, rust, amber, and slate-blue tokens shared by the public landing and CompanyOS light surfaces.",domain:"design-system",owners:["platform.design"],tags:["theme","marketing","companyos"],stability:"stable",scopes:["global","tenant"]},tokens:{colors:{paper:{value:"#f7f0e6",format:"hex",usage:"palette",description:"Warm paper canvas."},paperMuted:{value:"#efe4d3",format:"hex",usage:"palette",description:"Muted paper surface."},paperPanel:{value:"#fbf7f0",format:"hex",usage:"palette",description:"Raised panel surface."},ink:{value:"#1d1b18",format:"hex",usage:"palette",description:"Primary editorial text."},inkSoft:{value:"#5e564d",format:"hex",usage:"palette",description:"Secondary editorial text."},line:{value:"#d2c3ae",format:"hex",usage:"palette",description:"Warm separator line."},rust:{value:"#a24f2a",format:"hex",usage:"palette",description:"Primary brand action."},rustStrong:{value:"#854120",format:"hex",usage:"palette",description:"Primary hover/action emphasis."},amber:{value:"#d8a24a",format:"hex",usage:"palette",description:"Warm proof accent."},blue:{value:"#255678",format:"hex",usage:"palette",description:"Cool editorial accent."},success:{value:"#2d6a4f",format:"hex",usage:"palette",description:"Positive state accent."},background:{value:"#f7f0e6",format:"hex",usage:"semantic"},foreground:{value:"#1d1b18",format:"hex",usage:"semantic"},card:{value:"#fbf7f0",format:"hex",usage:"semantic"},cardForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},popover:{value:"#fbf7f0",format:"hex",usage:"semantic"},popoverForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},primary:{value:"#a24f2a",format:"hex",usage:"semantic"},primaryForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},secondary:{value:"#efe4d3",format:"hex",usage:"semantic"},secondaryForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},muted:{value:"color-mix(in srgb, #efe4d3 78%, #ffffff 22%)",format:"css",usage:"semantic"},mutedForeground:{value:"#5e564d",format:"hex",usage:"semantic"},accent:{value:"#255678",format:"hex",usage:"semantic"},accentForeground:{value:"#eef7fb",format:"hex",usage:"semantic"},destructive:{value:"#b9372f",format:"hex",usage:"semantic"},destructiveForeground:{value:"#fff5f2",format:"hex",usage:"semantic"},successForeground:{value:"#f4faf6",format:"hex",usage:"semantic"},warning:{value:"#905a18",format:"hex",usage:"semantic"},warningForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},info:{value:"#2b6688",format:"hex",usage:"semantic"},infoForeground:{value:"#eef7fb",format:"hex",usage:"semantic"},border:{value:"#d2c3ae",format:"hex",usage:"semantic"},input:{value:"color-mix(in srgb, #fbf7f0 70%, #ffffff 30%)",format:"css",usage:"semantic"},ring:{value:"color-mix(in srgb, #a24f2a 60%, #ffffff 40%)",format:"css",usage:"semantic"},chart1:{value:"#a24f2a",format:"hex",usage:"semantic"},chart2:{value:"#255678",format:"hex",usage:"semantic"},chart3:{value:"#d8a24a",format:"hex",usage:"semantic"},chart4:{value:"#7b4d2b",format:"hex",usage:"semantic"},chart5:{value:"#446b55",format:"hex",usage:"semantic"},sidebar:{value:"#fbf7f0",format:"hex",usage:"semantic"},sidebarForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},sidebarPrimary:{value:"#a24f2a",format:"hex",usage:"semantic"},sidebarPrimaryForeground:{value:"#fff8f0",format:"hex",usage:"semantic"},sidebarAccent:{value:"#efe4d3",format:"hex",usage:"semantic"},sidebarAccentForeground:{value:"#1d1b18",format:"hex",usage:"semantic"},sidebarBorder:{value:"#d2c3ae",format:"hex",usage:"semantic"},sidebarRing:{value:"color-mix(in srgb, #255678 55%, #ffffff 45%)",format:"css",usage:"semantic"}},radii:{xs:{value:4,description:"Dense indicators, inner affordances, and precise low-emphasis geometry."},sm:{value:8,description:"Compact controls, chips, and assertive small surfaces."},md:{value:12,description:"Standard calm controls and interactive elements."},lg:{value:16,description:"Cards with editorial softness and approachable tone."},xl:{value:24,description:"Large panels, overlays, and low-pressure reading contexts."},full:{value:9999,description:"Capsules, avatars, pills, and status dots."},default:{value:20,description:"1.25rem editorial base radius preserved for existing --radius consumers."},control:{value:12,description:"Semantic alias for standard interactive controls."},card:{value:16,description:"Semantic alias for editorial cards and grouped content."},panel:{value:20,description:"Semantic alias for elevated panels and application chrome."},overlay:{value:24,description:"Semantic alias for modals, sheets, and preview overlays."},pill:{value:9999,description:"Semantic alias for explicit capsule forms."}}},modes:{dark:{description:"Landing-aligned dark mode overlay.",tokens:{colors:{background:{value:"#161412",format:"hex",usage:"semantic"},foreground:{value:"#f5ede2",format:"hex",usage:"semantic"},card:{value:"#211d19",format:"hex",usage:"semantic"},cardForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},popover:{value:"#211d19",format:"hex",usage:"semantic"},popoverForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},primary:{value:"#c46c43",format:"hex",usage:"semantic"},primaryForeground:{value:"#161412",format:"hex",usage:"semantic"},secondary:{value:"#2c2723",format:"hex",usage:"semantic"},secondaryForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},muted:{value:"#322c27",format:"hex",usage:"semantic"},mutedForeground:{value:"#cfbeb0",format:"hex",usage:"semantic"},accent:{value:"#79a8c6",format:"hex",usage:"semantic"},accentForeground:{value:"#101418",format:"hex",usage:"semantic"},destructive:{value:"#d75950",format:"hex",usage:"semantic"},destructiveForeground:{value:"#161412",format:"hex",usage:"semantic"},success:{value:"#6bbf99",format:"hex",usage:"semantic"},successForeground:{value:"#0d1f17",format:"hex",usage:"semantic"},warning:{value:"#e0a44a",format:"hex",usage:"semantic"},warningForeground:{value:"#2a1c08",format:"hex",usage:"semantic"},info:{value:"#7fb4d6",format:"hex",usage:"semantic"},infoForeground:{value:"#0a1820",format:"hex",usage:"semantic"},border:{value:"#433a34",format:"hex",usage:"semantic"},input:{value:"#2b2622",format:"hex",usage:"semantic"},ring:{value:"#c46c43",format:"hex",usage:"semantic"},sidebar:{value:"#1c1916",format:"hex",usage:"semantic"},sidebarForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},sidebarPrimary:{value:"#c46c43",format:"hex",usage:"semantic"},sidebarPrimaryForeground:{value:"#161412",format:"hex",usage:"semantic"},sidebarAccent:{value:"#2b2622",format:"hex",usage:"semantic"},sidebarAccentForeground:{value:"#f5ede2",format:"hex",usage:"semantic"},sidebarBorder:{value:"#433a34",format:"hex",usage:"semantic"},sidebarRing:{value:"#79a8c6",format:"hex",usage:"semantic"}}}}}});export const ContractSpecEditorialThemeCssVariables={"--paper":"#f7f0e6","--paper-muted":"#efe4d3","--paper-panel":"#fbf7f0","--ink":"#1d1b18","--ink-soft":"#5e564d","--line":"#d2c3ae","--rust":"#a24f2a","--rust-strong":"#854120","--amber":"#d8a24a","--blue":"#255678","--success":"#2d6a4f","--success-foreground":"#f4faf6","--warning":"#905a18","--warning-foreground":"#fff8f0","--info":"#2b6688","--info-foreground":"#eef7fb","--background":"var(--paper)","--foreground":"var(--ink)","--card":"var(--paper-panel)","--card-foreground":"var(--ink)","--popover":"var(--paper-panel)","--popover-foreground":"var(--ink)","--primary":"var(--rust)","--primary-foreground":"#fff8f0","--secondary":"var(--paper-muted)","--secondary-foreground":"var(--ink)","--muted":"color-mix(in srgb, var(--paper-muted) 78%, #ffffff 22%)","--muted-foreground":"var(--ink-soft)","--accent":"var(--blue)","--accent-foreground":"#eef7fb","--destructive":"#b9372f","--destructive-foreground":"#fff5f2","--border":"var(--line)","--input":"color-mix(in srgb, var(--paper-panel) 70%, #ffffff 30%)","--ring":"color-mix(in srgb, var(--rust) 60%, #ffffff 40%)","--chart-1":"var(--rust)","--chart-2":"var(--blue)","--chart-3":"var(--amber)","--chart-4":"#7b4d2b","--chart-5":"#446b55","--radius":"1.25rem","--radius-xs":"0.25rem","--radius-sm":"0.5rem","--radius-md":"0.75rem","--radius-lg":"1rem","--radius-xl":"1.5rem","--radius-full":"9999px","--radius-control":"var(--radius-md)","--radius-card":"var(--radius-lg)","--radius-panel":"var(--radius)","--radius-overlay":"var(--radius-xl)","--radius-pill":"var(--radius-full)","--sidebar":"var(--paper-panel)","--sidebar-foreground":"var(--ink)","--sidebar-primary":"var(--rust)","--sidebar-primary-foreground":"#fff8f0","--sidebar-accent":"var(--paper-muted)","--sidebar-accent-foreground":"var(--ink)","--sidebar-border":"var(--line)","--sidebar-ring":"color-mix(in srgb, var(--blue) 55%, #ffffff 45%)"};export const ContractSpecEditorialThemeDarkCssVariables={"--background":"#161412","--foreground":"#f5ede2","--card":"#211d19","--card-foreground":"#f5ede2","--popover":"#211d19","--popover-foreground":"#f5ede2","--primary":"#c46c43","--primary-foreground":"#161412","--secondary":"#2c2723","--secondary-foreground":"#f5ede2","--muted":"#322c27","--muted-foreground":"#cfbeb0","--accent":"#79a8c6","--accent-foreground":"#101418","--destructive":"#d75950","--destructive-foreground":"#161412","--success":"#6bbf99","--success-foreground":"#0d1f17","--warning":"#e0a44a","--warning-foreground":"#2a1c08","--info":"#7fb4d6","--info-foreground":"#0a1820","--border":"#433a34","--input":"#2b2622","--ring":"#c46c43","--sidebar":"#1c1916","--sidebar-foreground":"#f5ede2","--sidebar-primary":"#c46c43","--sidebar-primary-foreground":"#161412","--sidebar-accent":"#2b2622","--sidebar-accent-foreground":"#f5ede2","--sidebar-border":"#433a34","--sidebar-ring":"#79a8c6"};export const ContractSpecEditorialThemeHslVariables={"--background":"35 52% 94%","--foreground":"36 9% 10%","--card":"38 58% 96%","--card-foreground":"36 9% 10%","--popover":"38 58% 96%","--popover-foreground":"36 9% 10%","--primary":"19 59% 40%","--primary-foreground":"32 100% 97%","--secondary":"36 47% 88%","--secondary-foreground":"36 9% 10%","--muted":"35 48% 91%","--muted-foreground":"32 10% 34%","--accent":"205 53% 31%","--accent-foreground":"198 62% 96%","--destructive":"3 59% 45%","--destructive-foreground":"14 100% 97%","--success":"153 40% 30%","--success-foreground":"150 33% 97%","--warning":"33 71% 33%","--warning-foreground":"33 100% 97%","--info":"202 52% 35%","--info-foreground":"200 60% 96%","--border":"35 29% 75%","--input":"37 57% 97%","--ring":"18 39% 64%"};export const ContractSpecEditorialThemeDarkHslVariables={"--background":"30 10% 8%","--foreground":"35 49% 92%","--card":"30 14% 11%","--card-foreground":"35 49% 92%","--popover":"30 14% 11%","--popover-foreground":"35 49% 92%","--primary":"19 52% 52%","--primary-foreground":"30 10% 8%","--secondary":"27 11% 15%","--secondary-foreground":"35 49% 92%","--muted":"27 12% 17%","--muted-foreground":"27 24% 75%","--accent":"203 40% 63%","--accent-foreground":"210 20% 8%","--destructive":"4 63% 58%","--destructive-foreground":"30 10% 8%","--success":"153 40% 58%","--success-foreground":"156 40% 9%","--warning":"36 71% 58%","--warning-foreground":"36 68% 10%","--info":"203 51% 67%","--info-foreground":"206 53% 8%","--border":"24 13% 23%","--input":"27 12% 15%","--ring":"19 52% 52%"};export const ContractSpecEditorialThemeBodyBackground="linear-gradient(180deg, #f8f2e8 0%, #f7f0e6 38%, #f9f4ec 100%)";export const tech_contracts_themes_DocBlocks=[{id:"docs.tech.contracts.themes",title:"ThemeSpec Overview",summary:"`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files. Specs live in `@lssm/lib.contracts-spec`, making them accessible to generators, docs, and runtime tooling.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/themes",tags:["tech","contracts","themes"],body:'# ThemeSpec Overview\n\n## Purpose\n\n`ThemeSpec` defines a structured, versioned source of truth for design tokens, component variants, and scoped overrides. Use it to describe how tenants or individual users should experience the design system without hand-maintaining ad-hoc theme files.\n\n## Location\n\n- Types, helper, registry, and validation: `packages/libs/contracts-spec/src/themes.ts` and `packages/libs/contracts-spec/src/themes.validation.ts`\n- Design tokens bridge: `packages/libs/design-system/src/theme/*`\n\n## Schema\n\n```ts\nexport interface ThemeSpec {\n  meta: ThemeMeta;            // ownership metadata + { key, version, extends?, scopes? }\n  tokens: ThemeTokens;\n  components?: ComponentVariantSpec[];\n  overrides?: ThemeOverride[];\n  modes?: Record<string, ThemeModeSpec>; // use keys like "light" and "dark"\n}\n```\n\n- **ThemeMeta**\n  - `key`: fully-qualified identifier (for example `design.pastel`)\n  - `version`: semver string such as `1.0.0`\n  - `extends?`: optional `ThemeRef` to a base theme\n  - `scopes?`: default scopes where the theme applies (`global`, `tenant`, `user`)\n- **ThemeTokens**\n  - `colors`, `radii`, `space`, `typography`, `shadows`, `motion`\n  - each entry is a map of `{ value, description? }`\n  - the ContractSpec editorial radius taxonomy is additive and public: scale keys `xs/sm/md/lg/xl/full/default` plus semantic aliases `control/card/panel/overlay/pill`. Smaller radii communicate precision or higher action gravity; `md/control` is the normal control default; `lg/card`, `default/panel`, and `xl/overlay` provide progressively softer editorial surfaces; `full/pill` is reserved for capsules, avatars, and dots.\n  - persona-aware or RoleMorph-selected radius profiles are a future documentation hook only. This theme does not switch radius at runtime by persona, role, tone, or density.\n- **ComponentVariantSpec**\n  - `component`: design-system component key (for example `Button`, `NavMain`)\n  - `variants`: map of variant names to `{ props?, tokens? }`\n- **ThemeOverride**\n  - `scope`: `\'global\' | \'tenant\' | \'user\'`\n  - `target`: scoped identifier such as `tenant:artisanos` or `user:123`\n  - `tokens?` / `components?`: partial overrides for that target\n\n## Authoring\n\n```ts\nimport { defineTheme } from \'@lssm/lib.contracts-spec/themes\';\n\nexport const PastelTheme = defineTheme({\n  meta: {\n    key: \'design.pastel\',\n    version: \'1.0.0\',\n    title: \'Pastel\',\n    description: \'Soft pastel palette for marketing surfaces.\',\n    domain: \'design-system\',\n    owners: [\'platform.design\'],\n    tags: [\'theme\', \'marketing\'],\n    stability: \'experimental\',\n    scopes: [\'tenant\'],\n  },\n  tokens: {\n    colors: {\n      background: { value: \'#fdf2f8\', format: \'hex\', usage: \'semantic\' },\n      primary: {\n        value: \'oklch(0.72 0.11 221.19)\',\n        format: \'oklch\',\n        usage: \'semantic\',\n      },\n    },\n  },\n  modes: {\n    dark: {\n      tokens: {\n        colors: {\n          background: {\n            value: \'oklch(0.24 0.03 255)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n          primary: {\n            value: \'oklch(0.64 0.15 246)\',\n            format: \'oklch\',\n            usage: \'semantic\',\n          },\n        },\n      },\n    },\n  },\n});\n```\n\n`tokens` stays the default/light-compatible token bag. Use `modes.dark.tokens` to overlay dark-mode values and preserve full CSS color strings such as OKLCH.\n\nUse `validateThemeSpec()` or `assertThemeSpecValid()` in CI and setup flows to catch duplicate overrides, empty targets, self-referential inheritance, invalid mode keys, and missing ownership metadata before publish time.\n\n## Registry Usage\n\n```ts\nimport { ThemeRegistry } from \'@lssm/lib.contracts-spec/themes\';\n\nconst themes = new ThemeRegistry();\nthemes.register(PastelTheme);\n\nconst theme = themes.get(\'design.pastel\', \'1.0.0\');\nconst tenantVariant = theme?.overrides?.find(\n  (override) => override.target === \'tenant:artisanos\'\n);\n```\n\nThe registry guarantees `key + version` uniqueness and exposes `list()` for discovery tooling.\n\n## Rendering\n\nThe design system consumes specs through adapters you provide:\n\n1. Resolve the base theme plus applicable overrides.\n2. Merge default tokens plus the selected light/dark mode token map using `ThemeTokens`.\n3. Feed the result into `mapTokensForPlatform` or the Tailwind bridge in `@lssm/lib.design-system`.\n\n```ts\nfunction resolveTokens(\n  registry: ThemeRegistry,\n  ref: ThemeRef,\n  ctx: { tenant?: string; user?: string }\n) {\n  const spec = registry.get(ref.key, ref.version);\n  if (!spec) throw new Error(\'Theme not found\');\n\n  const tokens = deepMerge(spec.tokens, collectOverrides(spec.overrides, ctx));\n  return mapTokensForPlatform(tokens);\n}\n```\n\n## CLI\n\n```\ncontractspec create theme\n```\n\nUse the theme wizard to scaffold a `.theme.ts` file that already imports and calls `defineTheme(...)`.\n'}];

package/dist/themes.platform-validation.d.ts

@@ -0,0 +1,7 @@
+import type { ThemeTokens } from './themes.js';
+export interface PlatformTokenValidationIssue {
+    level: 'error';
+    message: string;
+    path: string;
+}
+export declare function validatePlatformTokenGroups(tokens: ThemeTokens, path: string): PlatformTokenValidationIssue[];

package/dist/themes.platform-validation.js

@@ -0,0 +1 @@
+const l=/(?:https?:|data:|url\s*\(|@font-face|javascript:|<\/?(?:script|style))/i;const m=/^\d+(?:\.\d+)?m?s$/;export function validatePlatformTokenGroups(e,s){const r=[];for(const[o,t]of Object.entries(e.fonts??{})){const n=t.value;if(!n?.web?.trim()||!n?.native?.trim()||l.test(n.web)||l.test(n.native))r.push(a(`${s}.fonts.${o}.value`,"Font tokens require local, non-executable web and native family names."))}for(const[o,t]of Object.entries(e.motion??{}))if(!m.test(t.value))r.push(a(`${s}.motion.${o}.value`,"Motion durations must be static ms or s values."));for(const[o,t]of Object.entries(e.density??{}))if(!c(t.value?.spacing)||!c(t.value?.size))r.push(a(`${s}.density.${o}.value`,"Density spacing and size must be positive finite numbers."));for(const[o,t]of Object.entries(e.elevation??{})){const n=t.value,i=n?.native;if(!n?.web?.trim()||l.test(n.web)||!i?.shadowColor?.trim()||!f(i.shadowOpacity)||!f(i.shadowRadius)||!f(i.elevation)||!u(i.shadowOffset?.width)||!u(i.shadowOffset?.height))r.push(a(`${s}.elevation.${o}.value`,"Elevation tokens require static web shadow text and a numeric native shadow descriptor."))}return r}function u(e){return typeof e==="number"&&Number.isFinite(e)}function c(e){return u(e)&&e>0}function f(e){return u(e)&&e>=0}function a(e,s){return{level:"error",message:s,path:e}}

package/dist/themes.validation.d.ts

@@ -0,0 +1,18 @@
+import type { ThemeSpec } from './themes.js';
+export type ThemeValidationLevel = 'error' | 'warning' | 'info';
+export interface ThemeValidationIssue {
+    level: ThemeValidationLevel;
+    message: string;
+    path?: string;
+    context?: Record<string, unknown>;
+}
+export interface ThemeValidationResult {
+    valid: boolean;
+    issues: ThemeValidationIssue[];
+}
+export declare class ThemeValidationError extends Error {
+    readonly issues: ThemeValidationIssue[];
+    constructor(message: string, issues: ThemeValidationIssue[]);
+}
+export declare function validateThemeSpec(spec: ThemeSpec): ThemeValidationResult;
+export declare function assertThemeSpecValid(spec: ThemeSpec): void;

package/dist/themes.validation.js

@@ -0,0 +1 @@
+import{validatePlatformTokenGroups as k}from"./themes.platform-validation.js";const y=new Set(["hex","rgb","hsl","oklch","css"]);export class ThemeValidationError extends Error{issues;constructor(t,e){super(t);this.issues=e;this.name="ThemeValidationError"}}export function validateThemeSpec(t){const e=[];b(t,e);S(t,e);d(t.tokens,e,"tokens");p(t.components,e,"components");g(t.modes,e,"modes");w(t.overrides,e);return{valid:e.every((n)=>n.level!=="error"),issues:e}}export function assertThemeSpecValid(t){const e=validateThemeSpec(t);if(!e.valid)throw new ThemeValidationError(`Theme ${t.meta.key}.v${t.meta.version} is invalid`,e.issues)}function b(t,e){const{meta:n}=t;l(n.key,"Theme must have a non-empty key","meta.key",e);l(n.version,"Theme must have a non-empty version","meta.version",e);l(n.title,"Theme must have a non-empty title","meta.title",e);l(n.description,"Theme must have a non-empty description","meta.description",e);l(n.domain,"Theme must have a non-empty domain","meta.domain",e);if(!n.stability)e.push({level:"error",message:"Theme must declare a stability level",path:"meta.stability"});if(!n.owners.length)e.push({level:"error",message:"Theme must declare at least one owner",path:"meta.owners"});if(!n.tags.length)e.push({level:"error",message:"Theme must declare at least one tag",path:"meta.tags"});if(n.extends&&n.extends.key===n.key&&n.extends.version===n.version)e.push({level:"error",message:"Theme cannot extend itself",path:"meta.extends"})}function S(t,e){if(u(t.tokens)||f(t.components)||T(t.modes)||O(t.overrides))return;e.push({level:"error",message:"Theme must declare tokens, components, or overrides with material configuration",path:"tokens"})}function d(t,e,n){if(!t)return;e.push(...k(t,n));for(const[o,r]of Object.entries(t)){if(r&&Object.keys(r).length===0)e.push({level:"warning",message:`Theme token group "${o}" is empty`,path:`${n}.${o}`});V(r,o,e,`${n}.${o}`)}}function V(t,e,n,o){if(!t||typeof t!=="object")return;const r=t;for(const[a,s]of Object.entries(r))if(e==="colors"&&s?.format&&!y.has(s.format))n.push({level:"warning",message:`Theme color token "${a}" declares unknown format "${s.format}"`,path:`${o}.${a}.format`})}function g(t,e,n){if(!t)return;for(const[o,r]of Object.entries(t)){const a=`${n}.${o}`;if(!o.trim()){e.push({level:"error",message:"Theme mode keys must be non-empty",path:n});continue}if(!v(r))e.push({level:"warning",message:`Theme mode "${o}" does not declare tokens or components`,path:a});d(r.tokens,e,`${a}.tokens`);p(r.components,e,`${a}.components`)}}function p(t,e,n){if(!t?.length)return;const o=new Set,r=new Map;t.forEach((a,s)=>{const h=`${n}[${s}]`,i=a.component.trim();if(!i){e.push({level:"error",message:"Theme component entries must declare a non-empty component key",path:`${h}.component`});return}if(o.has(i))e.push({level:"error",message:`Duplicate component "${i}" in theme`,path:`${h}.component`});o.add(i);const c=r.get(i)??new Set;for(const m of Object.keys(a.variants)){if(c.has(m))e.push({level:"error",message:`Duplicate variant "${m}" for component "${i}"`,path:`${h}.variants.${m}`});c.add(m);d(a.variants[m]?.tokens,e,`${h}.variants.${m}.tokens`)}r.set(i,c)})}function w(t,e){if(!t?.length)return;const n=new Set;t.forEach((o,r)=>{const a=`overrides[${r}]`,s=`${o.scope}:${o.target}`;if(!o.target.trim()){e.push({level:"error",message:"Theme override targets must be non-empty",path:`${a}.target`});return}if(n.has(s))e.push({level:"error",message:`Duplicate override for ${o.scope}:${o.target}`,path:a});n.add(s);if(M(o.scope,o.target))e.push({level:"warning",message:`Override target "${o.target}" does not look scoped for ${o.scope} overrides`,path:`${a}.target`});d(o.tokens,e,`${a}.tokens`);p(o.components,e,`${a}.components`);g(o.modes,e,`${a}.modes`)})}function u(t){if(!t)return!1;return Object.values(t).some((e)=>e!==void 0&&Object.keys(e).length>0)}function f(t){return Boolean(t?.length)}function v(t){return u(t?.tokens)||f(t?.components)}function T(t){return Boolean(Object.values(t??{}).some(v))}function O(t){return Boolean(t?.some((e)=>u(e.tokens)||f(e.components)||T(e.modes)))}function M(t,e){if(t==="global")return!1;return!e.startsWith(`${t}:`)}function l(t,e,n,o){if(t?.trim())return;o.push({level:"error",message:e,path:n})}

package/dist/translations/catalog.d.ts

@@ -0,0 +1,25 @@
+export type Locale = string;
+export type MessageKey = string;
+export interface TranslationEntry {
+    key: MessageKey;
+    locale: Locale;
+    value: string;
+    context?: string;
+}
+export interface TranslationCatalogMeta {
+    key: string;
+    version: string;
+    description?: string;
+}
+export interface PlatformTranslationCatalog {
+    meta: TranslationCatalogMeta;
+    defaultLocale: Locale;
+    supportedLocales: Locale[];
+    entries: TranslationEntry[];
+}
+export interface BlueprintTranslationCatalog {
+    meta: TranslationCatalogMeta;
+    defaultLocale: Locale;
+    supportedLocales: Locale[];
+    entries: TranslationEntry[];
+}

package/dist/translations/diagnostics.d.ts

@@ -0,0 +1,92 @@
+import type { Locale, MessageKey } from './spec.js';
+export type TranslationStaticDiagnosticCode = 'invalid_catalog_shape' | 'missing_catalog' | 'missing_key' | 'extra_key' | 'missing_value' | 'invalid_message_shape' | 'invalid_icu' | 'placeholder_non_parity' | 'locale_non_parity' | 'duplicate_bundle_identity'
+/** AC5 class 5: spec declares supportedLocales but no catalog exists for that locale. */
+ | 'unsupported_locale_claim'
+/** Manifest cross-validation: manifest references a specKey absent from the known catalog set. */
+ | 'manifest_spec_key_missing'
+/**
+ * Untranslated English stub: a non-base-locale message value is byte-identical
+ * (after trim) to the base-locale value, indicating the key was copied from
+ * English rather than translated. Report-only (`info`) — does not fail CI.
+ * Suppressed for allowlisted message keys / values (brand names, codes) and
+ * for non-translatable tokens (numbers, punctuation, URLs).
+ */
+ | 'missing_translation';
+export type TranslationDiagnosticLevel = 'error' | 'warning' | 'info';
+export interface TranslationDiagnosticsOptions {
+    baseLocale?: Locale;
+    expectedLocales?: readonly Locale[];
+    allowExtraKeys?: boolean;
+    checkPlaceholders?: boolean;
+    checkIcu?: boolean;
+    strict?: boolean;
+    /**
+     * Emit `missing_translation` diagnostics for non-base-locale values that are
+     * identical to the base-locale value (untranslated English stubs).
+     * Defaults to `true`. Always emitted at `info` level (report-only) so it never
+     * flips `report.ok`, even under `strict`.
+     */
+    checkMissingTranslation?: boolean;
+    /**
+     * Allowlist of message keys and/or exact values that are English-by-design
+     * (brand names, product codes, acronyms). Matches are excluded from the
+     * `missing_translation` diagnostic. An entry suppresses a stub when it equals
+     * the message key OR the trimmed base/target value.
+     */
+    missingTranslationAllowlist?: readonly string[];
+}
+/**
+ * A single route entry for manifest↔catalog cross-validation.
+ *
+ * `route` is an opaque string — no route-type imports are used here.
+ * `specKeys` lists the translation spec keys the route declares as required.
+ */
+export interface ManifestRouteEntry {
+    route: string;
+    specKeys: readonly string[];
+}
+export interface TranslationCatalogGroupInput extends TranslationDiagnosticsOptions {
+    packagePath?: string;
+    catalogDir?: string;
+    catalogs: readonly unknown[];
+}
+export interface TranslationDiagnosticIssue {
+    code: TranslationStaticDiagnosticCode;
+    level: TranslationDiagnosticLevel;
+    specKey?: string;
+    messageKey?: MessageKey;
+    locale?: Locale;
+    targetLocale?: Locale;
+    path?: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+export interface TranslationDiagnosticsReport {
+    ok: boolean;
+    summary: {
+        packages: number;
+        catalogs: number;
+        keys: number;
+        errors: number;
+        warnings: number;
+        infos: number;
+    };
+    issues: TranslationDiagnosticIssue[];
+}
+export declare function analyzeTranslationCatalogGroup(input: TranslationCatalogGroupInput): TranslationDiagnosticsReport;
+export declare function analyzeTranslationCatalogGroups(inputs: readonly TranslationCatalogGroupInput[]): TranslationDiagnosticsReport;
+/**
+ * Cross-validate a route→specKeys manifest against a known catalog set.
+ *
+ * Emits `manifest_spec_key_missing` for every specKey referenced in the
+ * manifest that has no corresponding entry in `knownSpecKeys`.
+ *
+ * This function is intentionally route-agnostic: `route` is an opaque string
+ * and no route types are imported.
+ *
+ * @param entries - Manifest entries, each pairing an opaque route string with
+ *   the specKeys it declares as required.
+ * @param knownSpecKeys - The set of specKeys present in the registered catalog.
+ * @returns Flat list of diagnostic issues; empty when the manifest is clean.
+ */
+export declare function validateManifestCatalogDrift(entries: readonly ManifestRouteEntry[], knownSpecKeys: ReadonlySet<string> | readonly string[]): TranslationDiagnosticIssue[];

package/dist/translations/diagnostics.js

@@ -0,0 +1 @@
+import{findMissingTranslations as k,validateICUFormat as v,validateTranslationSpec as I}from"./validation.js";const _="en";export function analyzeTranslationCatalogGroup(a){return analyzeTranslationCatalogGroups([a])}export function analyzeTranslationCatalogGroups(a){const e=[];let t=0,o=0;for(const n of a){const r=S(n),l=x(n,e);t+=l.length;o+=l.reduce((c,m)=>c+Object.keys(m.messages).length,0);const i=r.expectedLocales??[...new Set(l.map((c)=>c.locale))].sort();L(l,i,n,e);z(l,n,e);P(l,n,e);w(l,n,e,r);C(l,n,e,r);M(l,n,e,r)}e.sort(A);const s=R(a.length,t,o,e);return{ok:s.errors===0&&(!a.some((n)=>n.strict)||s.warnings===0),summary:s,issues:e}}function S(a){return{baseLocale:a.baseLocale??_,expectedLocales:a.expectedLocales,allowExtraKeys:a.allowExtraKeys??!1,checkPlaceholders:a.checkPlaceholders??!0,checkIcu:a.checkIcu??!0,strict:a.strict??!1,checkMissingTranslation:a.checkMissingTranslation??!0,missingTranslationAllowlist:new Set(a.missingTranslationAllowlist??[])}}function x(a,e){return a.catalogs.flatMap((t,o)=>{const s=`${u(a)}catalogs[${o}]`;if(!d(t)){e.push({code:"invalid_catalog_shape",level:"error",path:s,message:"Translation catalog must be an object",context:g(a)});return[]}if(!d(t.meta)||typeof t.locale!=="string"||!d(t.messages)){e.push({code:"invalid_catalog_shape",level:"error",path:s,message:"Translation catalog must include object meta, string locale, and object messages",context:g(a)});return[]}const n={};for(const[r,l]of Object.entries(t.messages)){const i=`${s}.messages.${r}`;if(!d(l)||typeof l.value!=="string"){e.push({code:"invalid_message_shape",level:"error",specKey:typeof t.meta.key==="string"?t.meta.key:void 0,messageKey:r,locale:t.locale,path:i,message:`Message "${r}" must be an object with a string value`,context:g(a)});continue}if(!l.value.trim())e.push({code:"missing_value",level:"error",specKey:typeof t.meta.key==="string"?t.meta.key:void 0,messageKey:r,locale:t.locale,path:`${i}.value`,message:`Message "${r}" has an empty value`,context:g(a)});n[r]=l}return[{...t,messages:n}]})}function L(a,e,t,o){const s=new Set(a.map((n)=>n.locale));for(const n of e){if(s.has(n))continue;o.push({code:"missing_catalog",level:"error",locale:n,path:u(t),message:`Missing ${n} translation catalog`,context:g(t)})}if(e.length>0&&s.size!==e.length)o.push({code:"locale_non_parity",level:"error",path:u(t),message:`Catalog group has locales ${[...s].sort().join(", ")||"(none)"} but expected ${e.join(", ")}`,context:{...g(t),expectedLocales:e,actualLocales:[...s].sort()}})}function w(a,e,t,o){for(const s of a){const n=I(s);for(const r of n.issues){const l=r.message.includes("invalid ICU"),i=D(r.path);if(l&&(!o.checkIcu||j(s,i)))continue;t.push({code:K(r.path,l),level:r.level,specKey:s.meta.key,messageKey:i,locale:s.locale,path:`${u(e)}${s.meta.key}:${s.locale}.${r.path??""}`,message:r.message,context:g(e)})}}}function D(a){if(!a?.startsWith("messages."))return;return a.slice(9).replace(/\.(value|placeholders|variants|description).*$/,"")}function K(a,e){if(e)return"invalid_icu";if(a?.startsWith("messages."))return"invalid_message_shape";return"invalid_catalog_shape"}function C(a,e,t,o){const s=new Map;for(const n of a){const r=s.get(n.meta.key)??[];r.push(n);s.set(n.meta.key,r)}for(const[n,r]of s){const l=T(r,o.baseLocale);if(!l)continue;for(const i of r){if(i.locale===o.baseLocale)continue;for(const c of k(l,i))t.push({code:"missing_key",level:"error",specKey:n,messageKey:c.messageKey,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c.messageKey}`,message:`${i.locale} is missing translation key "${c.messageKey}" from ${l.locale}`,context:g(e)});for(const c of Object.keys(i.messages)){if(l.messages[c])continue;t.push({code:"extra_key",level:o.allowExtraKeys?"warning":"error",specKey:n,messageKey:c,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c}`,message:`${i.locale} has extra translation key "${c}" absent from ${l.locale}`,context:g(e)})}if(o.checkPlaceholders)O(l,i,e,t)}}}function M(a,e,t,o){if(!o.checkMissingTranslation)return;const s=new Map;for(const n of a){const r=s.get(n.meta.key)??[];r.push(n);s.set(n.meta.key,r)}for(const[n,r]of s){const l=T(r,o.baseLocale);if(!l)continue;for(const i of r){if(i.locale===o.baseLocale)continue;for(const[c,m]of Object.entries(l.messages)){const f=i.messages[c];if(!f)continue;const y=m.value.trim(),b=f.value.trim();if(y!==b)continue;if(G(c,y,o))continue;t.push({code:"missing_translation",level:"info",specKey:n,messageKey:c,locale:l.locale,targetLocale:i.locale,path:`${u(e)}${n}:${i.locale}.messages.${c}.value`,message:`${i.locale} value for "${c}" is identical to ${l.locale} \u2014 likely an untranslated English stub`,context:g(e)})}}}}function G(a,e,t){const o=t.missingTranslationAllowlist;if(o.has(a)||o.has(e))return!0;if(e.length===0)return!0;if(/^[\d\s\p{P}\p{S}]+$/u.test(e))return!0;if(/^https?:\/\/\S+$/u.test(e))return!0;return!1}function O(a,e,t,o){for(const[s,n]of Object.entries(a.messages)){const r=e.messages[s];if(!r)continue;const l=h(n),i=h(r);if(E(l,i))continue;o.push({code:"placeholder_non_parity",level:"error",specKey:a.meta.key,messageKey:s,locale:a.locale,targetLocale:e.locale,path:`${u(t)}${a.meta.key}:${e.locale}.messages.${s}.value`,message:`${e.locale} placeholders for "${s}" do not match ${a.locale}`,context:{...g(t),baseVariables:[...l].sort(),targetVariables:[...i].sort()}})}}function P(a,e,t){const o=new Set;for(const s of a){const n=`${s.meta.key}:${s.locale}:${s.meta.version}`;if(!o.has(n)){o.add(n);continue}t.push({code:"duplicate_bundle_identity",level:"error",specKey:s.meta.key,locale:s.locale,path:`${u(e)}${n}`,message:`Duplicate translation catalog identity ${n}`,context:g(e)})}}function z(a,e,t){const o=new Map;for(const s of a){const n=o.get(s.meta.key)??{present:new Set,claimed:new Set};n.present.add(s.locale);for(const r of s.supportedLocales??[])n.claimed.add(r);o.set(s.meta.key,n)}for(const[s,{present:n,claimed:r}]of o)for(const l of r)if(!n.has(l))t.push({code:"unsupported_locale_claim",level:"error",specKey:s,locale:l,path:`${u(e)}${s}:supportedLocales`,message:`Spec "${s}" claims to support locale "${l}" but no catalog exists for it`,context:g(e)})}export function validateManifestCatalogDrift(a,e){const t=e instanceof Set?e:new Set(e),o=[];for(const s of a)for(const n of s.specKeys)if(!t.has(n))o.push({code:"manifest_spec_key_missing",level:"error",specKey:n,path:`manifest:${s.route}:${n}`,message:`Manifest route "${s.route}" references specKey "${n}" which has no registered catalog`,context:{route:s.route}});return o}function h(a){const e=a.placeholders?.map((o)=>o.name)??[];if(e.length>0)return new Set(e);const t=v(a.value);return new Set([...t.placeholders,...t.plurals,...t.selects,...t.selectOrdinals])}function j(a,e){if(!e)return!1;const t=a.messages[e];if(!t)return!1;return/\{[^{}]*(,|:|"|'|\n)[^{}]*\}/.test(t.value)}function T(a,e){return a.find((t)=>t.locale===e)}function R(a,e,t,o){return{packages:a,catalogs:e,keys:t,errors:o.filter((s)=>s.level==="error").length,warnings:o.filter((s)=>s.level==="warning").length,infos:o.filter((s)=>s.level==="info").length}}function A(a,e){return p(a.path,e.path)||p(a.specKey,e.specKey)||p(a.messageKey,e.messageKey)||p(a.locale,e.locale)||p(a.targetLocale,e.targetLocale)||a.code.localeCompare(e.code)}function p(a,e){return(a??"").localeCompare(e??"")}function E(a,e){if(a.size!==e.size)return!1;for(const t of a)if(!e.has(t))return!1;return!0}function u(a){const e=[a.packagePath,a.catalogDir].filter(Boolean);return e.length>0?`${e.join("/")}:`:""}function g(a){return{packagePath:a.packagePath,catalogDir:a.catalogDir}}function d(a){return typeof a==="object"&&a!==null&&!Array.isArray(a)}

package/dist/translations/i18n-factory-snapshot.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Snapshot, serialization, and hydration surface for the i18n factory stack.
+ *
+ * The canonical snapshot/hydration surface on the `createI18nFactory` stack.
+ * The surface is **additive** and behavior-compatible: it never changes the
+ * resolution semantics of an existing factory or instance, it only exposes a
+ * serializable view of the resolved catalogs so SSR can ship a locale-scoped
+ * payload and the client can rehydrate an identical factory.
+ *
+ * @module translations/i18n-factory-snapshot
+ */
+import type { TranslationSpec } from './spec.js';
+/**
+ * Serializable, locale-scoped snapshot of a factory's resolved catalogs.
+ *
+ * Contains only the catalogs required to reproduce identical `t()` results for
+ * `locale` (the locale itself plus its declared fallback chain), keeping the
+ * SSR payload small while remaining lossless for the scoped locale.
+ */
+export interface I18nFactorySnapshot {
+    /** The spec key the snapshot was scoped to. */
+    specKey: string;
+    /** The resolved locale the snapshot was scoped to. */
+    locale: string;
+    /** Catalogs needed to resolve `locale` (locale + fallback chain). */
+    catalogs: TranslationSpec[];
+}
+/** Stable discriminator for an i18n factory hydration payload. */
+export declare const I18N_FACTORY_HYDRATION_KIND: 'contractspec.i18n-factory.hydration';
+/** Hydration payload schema version. */
+export declare const I18N_FACTORY_HYDRATION_VERSION: 1;
+/**
+ * Versioned envelope wrapping an {@link I18nFactorySnapshot} for transport
+ * (SSR -> client) and forward-compatible validation.
+ */
+export interface I18nFactoryHydrationPayload {
+    kind: typeof I18N_FACTORY_HYDRATION_KIND;
+    version: typeof I18N_FACTORY_HYDRATION_VERSION;
+    snapshot: I18nFactorySnapshot;
+}
+/** Input describing how to scope a snapshot from a factory's catalogs. */
+export interface BuildI18nFactorySnapshotInput {
+    /** Spec key the factory resolves against. */
+    specKey: string;
+    /** Full catalog set held by the factory. */
+    catalogs: readonly TranslationSpec[];
+    /** Already-resolved target locale. */
+    locale: string;
+    /** Default/fallback locale to always include (typically `"en"`). */
+    fallbackLocale?: string;
+}
+/**
+ * Collect the minimal catalog set required to reproduce identical `t()`
+ * resolution for `locale`.
+ *
+ * Follows each matching catalog's declared `fallback`, `fallbacks`, and
+ * `defaultLocale` so the resolution path used by `TranslationRegistry` is fully
+ * represented. The optional `fallbackLocale` is always seeded into the chain.
+ */
+export declare function collectLocaleScopedCatalogs(catalogs: readonly TranslationSpec[], specKey: string, locale: string, fallbackLocale?: string): TranslationSpec[];
+/** Build a locale-scoped snapshot from a factory's catalog set. */
+export declare function buildI18nFactorySnapshot(input: BuildI18nFactorySnapshotInput): I18nFactorySnapshot;
+/** Serialize a snapshot to a JSON string. */
+export declare function serializeI18nFactorySnapshot(snapshot: I18nFactorySnapshot): string;
+/** Parse a snapshot from a JSON string. */
+export declare function parseI18nFactorySnapshot(serialized: string): I18nFactorySnapshot;
+/** Wrap a snapshot in a versioned hydration payload (deep-cloned). */
+export declare function createI18nFactoryHydrationPayload(snapshot: I18nFactorySnapshot): I18nFactoryHydrationPayload;
+/** Serialize a hydration payload to a JSON string. */
+export declare function serializeI18nFactoryHydrationPayload(payload: I18nFactoryHydrationPayload): string;
+/** Validate a snapshot shape; returns human-readable error messages. */
+export declare function validateI18nFactorySnapshot(snapshot: Partial<I18nFactorySnapshot> | undefined): string[];
+/** Validate a hydration payload (kind + version + snapshot). */
+export declare function validateI18nFactoryHydrationPayload(payload: Partial<I18nFactoryHydrationPayload> | undefined): string[];
+/** Parse + validate a hydration payload; throws on invalid input. */
+export declare function parseI18nFactoryHydrationPayload(serialized: string): I18nFactoryHydrationPayload;
+export declare const I18nFactorySnapshotDocBlock: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "reference";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};

package/dist/translations/i18n-factory-snapshot.js

@@ -0,0 +1 @@
+export const I18N_FACTORY_HYDRATION_KIND="contractspec.i18n-factory.hydration";export const I18N_FACTORY_HYDRATION_VERSION=1;export function collectLocaleScopedCatalogs(a,t,s,i){const c=a.filter((o)=>o.meta.key===t),e=new Set,n=[s];if(i)n.push(i);while(n.length>0){const o=n.shift();if(!o||e.has(o))continue;e.add(o);for(const r of c){if(r.locale!==o)continue;if(r.fallback)n.push(r.fallback);for(const l of r.fallbacks??[])n.push(l);if(r.defaultLocale)n.push(r.defaultLocale)}}return c.filter((o)=>e.has(o.locale))}export function buildI18nFactorySnapshot(a){return{specKey:a.specKey,locale:a.locale,catalogs:collectLocaleScopedCatalogs(a.catalogs,a.specKey,a.locale,a.fallbackLocale)}}function y(a){return parseI18nFactorySnapshot(serializeI18nFactorySnapshot(a))}export function serializeI18nFactorySnapshot(a){return JSON.stringify(a)}export function parseI18nFactorySnapshot(a){return JSON.parse(a)}export function createI18nFactoryHydrationPayload(a){return{kind:"contractspec.i18n-factory.hydration",version:1,snapshot:y(a)}}export function serializeI18nFactoryHydrationPayload(a){return JSON.stringify(a)}export function validateI18nFactorySnapshot(a){const t=[];if(!a)return["i18n factory snapshot is missing."];if(!a.specKey)t.push("i18n factory snapshot specKey is missing.");if(!a.locale)t.push("i18n factory snapshot locale is missing.");if(!Array.isArray(a.catalogs))t.push("i18n factory snapshot catalogs must be an array.");return t}export function validateI18nFactoryHydrationPayload(a){const t=[];if(!a||a.kind!=="contractspec.i18n-factory.hydration")t.push("i18n factory hydration payload kind is invalid.");if(a?.version!==1)t.push("i18n factory hydration payload version is unsupported.");t.push(...validateI18nFactorySnapshot(a?.snapshot));return t}export function parseI18nFactoryHydrationPayload(a){const t=JSON.parse(a),s=validateI18nFactoryHydrationPayload(t);if(s.length>0)throw Error(s.join("; "));return createI18nFactoryHydrationPayload(t.snapshot)}export const I18nFactorySnapshotDocBlock={id:"docs.tech.translations.i18n-factory.snapshot",title:"i18n factory snapshot & hydration",summary:"Additive snapshot/serialization/hydration surface for the createI18nFactory stack.",kind:"reference",visibility:"public",route:"/docs/tech/translations/i18n-factory/snapshot",tags:["i18n","translations","ssr","hydration"],body:"# i18n factory snapshot & hydration\n\nThe canonical, additive (behavior-compatible) snapshot/hydration surface on the\n`createI18nFactory` stack.\n\n- `buildI18nFactorySnapshot` produces a **locale-scoped** snapshot containing\n  only the catalogs needed to reproduce identical `t()` results for the locale\n  (the locale plus its declared fallback chain).\n- `createI18nFactoryHydrationPayload` wraps a snapshot in a versioned envelope\n  (`kind` = `contractspec.i18n-factory.hydration`, `version` =\n  `1`) for SSR -> client transport.\n- `parseI18nFactoryHydrationPayload` validates and re-clones the payload.\n\nReconstruct a factory from a snapshot or payload with\n`createI18nFactoryFromSnapshot` / `createI18nFactoryFromHydrationPayload`\n(see the `i18n-factory` module).\n\nCompatibility classification: **ADDITIVE**. No existing exported symbol or\nresolution behavior changes.\n"};