@ankhorage/zora 3.3.4 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.0.0
+
+### Major Changes
+
+- 92c375f: Add a pure `@ankhorage/zora/theme` compiler that returns canonical Color Theory evidence, resolved Surface semantics, measurable selection results, diagnostics, and provenance for both theme modes. Replace the previously unconstructed computed-theme type shape with the compiler's real result.
+
 ## 3.3.4
 
 ### Patch Changes

package/dist/components/heading/resolveHeadingThemeRecipe.d.ts

@@ -2,7 +2,7 @@ import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
 import type { HeadingAlign, HeadingSize, HeadingWeight } from './types';
 export declare function resolveHeadingThemeRecipe(fields: Readonly<Record<string, ThemeRecipeOverrideValue>>): {
     size: HeadingSize | undefined;
-    color: "primary" | "secondary" | "tertiary" | "quaternary" | "neutral" | "success" | "warning" | "error" | "info" | "danger" | undefined;
+    color: "primary" | "secondary" | "tertiary" | "quaternary" | "neutral" | "error" | "success" | "warning" | "info" | "danger" | undefined;
     emphasis: "default" | "muted" | "subtle" | "inverse" | undefined;
     align: HeadingAlign | undefined;
     weight: HeadingWeight | undefined;

package/dist/components/text/resolveTextThemeRecipe.d.ts

@@ -2,7 +2,7 @@ import type { ThemeRecipeOverrideValue } from '@ankhorage/contracts';
 import type { TextAlign, TextVariant, TextWeight } from './types';
 export declare function resolveTextThemeRecipe(fields: Readonly<Record<string, ThemeRecipeOverrideValue>>): {
     variant: TextVariant | undefined;
-    color: "primary" | "secondary" | "tertiary" | "quaternary" | "neutral" | "success" | "warning" | "error" | "info" | "danger" | undefined;
+    color: "primary" | "secondary" | "tertiary" | "quaternary" | "neutral" | "error" | "success" | "warning" | "info" | "danger" | undefined;
     emphasis: "default" | "muted" | "subtle" | "inverse" | undefined;
     align: TextAlign | undefined;
     weight: TextWeight | undefined;

package/dist/theme/compileZoraTheme.d.ts

@@ -0,0 +1,8 @@
+import type { ThemeConfig } from '@ankhorage/contracts';
+import type { ZoraComputedTheme, ZoraThemeCompilationOptions } from './types';
+/***
+ * Compile canonical theme source into Color Theory evidence and resolved Surface themes.
+ * This function is pure and does not mount React or reproduce owner algorithms.
+ */
+export declare function compileZoraTheme(themeConfig: ThemeConfig, options?: ZoraThemeCompilationOptions): ZoraComputedTheme;
+//# sourceMappingURL=compileZoraTheme.d.ts.map

package/dist/theme/compileZoraTheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileZoraTheme.d.ts","sourceRoot":"","sources":["../../src/theme/compileZoraTheme.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EACV,iBAAiB,EAGjB,2BAA2B,EAK5B,MAAM,SAAS,CAAC;AAOjB;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,2BAAgC,GACxC,iBAAiB,CAYnB"}

package/dist/theme/compileZoraTheme.js

@@ -0,0 +1,128 @@
+import { generateThemeModeColors, selectColorSwatchStep } from '@ankhorage/color-theory';
+import { createTheme } from '@ankhorage/surface/theme';
+const CONTRACTS_OWNER = '@ankhorage/contracts';
+const COLOR_THEORY_OWNER = '@ankhorage/color-theory';
+const SURFACE_OWNER = '@ankhorage/surface';
+const ZORA_OWNER = '@ankhorage/zora';
+/***
+ * Compile canonical theme source into Color Theory evidence and resolved Surface themes.
+ * This function is pure and does not mount React or reproduce owner algorithms.
+ */
+export function compileZoraTheme(themeConfig, options = {}) {
+    const light = compileMode(themeConfig, 'light', options.selectionTargets?.light ?? []);
+    const dark = compileMode(themeConfig, 'dark', options.selectionTargets?.dark ?? []);
+    const diagnostics = [...light.diagnostics, ...dark.diagnostics];
+    return {
+        themeConfig,
+        light,
+        dark,
+        diagnostics,
+        provenance: createRootProvenance(themeConfig),
+    };
+}
+/*** Compile one canonical mode and compare the independent owner results. */
+function compileMode(themeConfig, mode, targets) {
+    const modeConfig = mode === 'light' ? themeConfig.light : themeConfig.dark;
+    const generated = generateThemeModeColors(modeConfig);
+    const surfaceTheme = createTheme(themeConfig, mode);
+    const { diagnostics, selections } = resolveSelections(generated, mode, targets);
+    if (!outputsAgree(generated, surfaceTheme.colorDiagnostics.generated)) {
+        diagnostics.push({
+            code: 'generated-output-divergence',
+            message: 'Surface and Color Theory returned different generated color evidence.',
+            mode,
+            path: `${mode}.generated`,
+            severity: 'error',
+        });
+    }
+    return {
+        mode,
+        generated,
+        surfaceTheme,
+        selections,
+        diagnostics,
+        provenance: createModeProvenance(mode, targets),
+    };
+}
+/*** Resolve measurable swatch targets without substituting unavailable roles. */
+function resolveSelections(generated, mode, targets) {
+    const diagnostics = [];
+    const selections = targets.map((request) => {
+        const swatch = generated.swatches[request.swatch];
+        const result = swatch
+            ? selectColorSwatchStep(swatch, request.target, request.contexts, request.tiePolicy)
+            : null;
+        if (!swatch)
+            diagnostics.push(createMissingSwatchDiagnostic(mode, request));
+        else if (!result?.selected)
+            diagnostics.push(createUnresolvedTargetDiagnostic(mode, request));
+        return { request, result };
+    });
+    return { diagnostics, selections };
+}
+/*** Describe a requested swatch that the selected harmony does not generate. */
+function createMissingSwatchDiagnostic(mode, request) {
+    return {
+        code: 'missing-target-swatch',
+        message: `The selected harmony does not generate the '${request.swatch}' swatch.`,
+        mode,
+        path: `${mode}.selectionTargets.${request.id}`,
+        severity: 'error',
+    };
+}
+/*** Describe a measurable target that has no passing swatch candidate. */
+function createUnresolvedTargetDiagnostic(mode, request) {
+    return {
+        code: 'unresolved-selection-target',
+        message: `No '${request.swatch}' step satisfies selection target '${request.id}'.`,
+        mode,
+        path: `${mode}.selectionTargets.${request.id}`,
+        severity: 'error',
+    };
+}
+/*** Record direct source and Surface-owned default provenance. */
+function createRootProvenance(themeConfig) {
+    return [
+        { path: 'themeConfig', origin: 'direct', owner: CONTRACTS_OWNER },
+        {
+            path: 'themeConfig.tokens',
+            origin: themeConfig.tokens ? 'direct' : 'defaulted',
+            owner: themeConfig.tokens ? CONTRACTS_OWNER : SURFACE_OWNER,
+        },
+    ];
+}
+/*** Record the owner transformation chain for one compiled mode. */
+function createModeProvenance(mode, targets) {
+    const inputPath = `themeConfig.${mode}`;
+    const entries = [
+        { path: inputPath, origin: 'direct', owner: CONTRACTS_OWNER },
+        {
+            path: `${mode}.generated`,
+            origin: 'derived',
+            owner: COLOR_THEORY_OWNER,
+            inputs: [inputPath],
+        },
+        {
+            path: `${mode}.surfaceTheme`,
+            origin: 'derived',
+            owner: SURFACE_OWNER,
+            inputs: ['themeConfig', inputPath],
+        },
+    ];
+    for (const target of targets) {
+        const targetPath = `${mode}.selectionTargets.${target.id}`;
+        entries.push({ path: targetPath, origin: 'direct', owner: ZORA_OWNER });
+        entries.push({
+            path: `${mode}.selections.${target.id}`,
+            origin: 'derived',
+            owner: COLOR_THEORY_OWNER,
+            inputs: [`${mode}.generated.swatches.${target.swatch}`, targetPath],
+        });
+    }
+    return entries;
+}
+/*** Compare deterministic owner result records for divergence diagnostics. */
+function outputsAgree(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+//# sourceMappingURL=compileZoraTheme.js.map

package/dist/theme/compileZoraTheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileZoraTheme.js","sourceRoot":"","sources":["../../src/theme/compileZoraTheme.ts"],"names":[],"mappings":"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","sourcesContent":["import { generateThemeModeColors, selectColorSwatchStep } from '@ankhorage/color-theory';\nimport type { ThemeConfig } from '@ankhorage/contracts';\nimport { createTheme } from '@ankhorage/surface/theme';\n\nimport type {\n  ZoraComputedTheme,\n  ZoraComputedThemeMode,\n  ZoraThemeCompilationDiagnostic,\n  ZoraThemeCompilationOptions,\n  ZoraThemeMode,\n  ZoraThemeProvenanceEntry,\n  ZoraThemeSelectionResult,\n  ZoraThemeSelectionTarget,\n} from './types';\n\nconst CONTRACTS_OWNER = '@ankhorage/contracts';\nconst COLOR_THEORY_OWNER = '@ankhorage/color-theory';\nconst SURFACE_OWNER = '@ankhorage/surface';\nconst ZORA_OWNER = '@ankhorage/zora';\n\n/***\n * Compile canonical theme source into Color Theory evidence and resolved Surface themes.\n * This function is pure and does not mount React or reproduce owner algorithms.\n */\nexport function compileZoraTheme(\n  themeConfig: ThemeConfig,\n  options: ZoraThemeCompilationOptions = {},\n): ZoraComputedTheme {\n  const light = compileMode(themeConfig, 'light', options.selectionTargets?.light ?? []);\n  const dark = compileMode(themeConfig, 'dark', options.selectionTargets?.dark ?? []);\n  const diagnostics = [...light.diagnostics, ...dark.diagnostics];\n\n  return {\n    themeConfig,\n    light,\n    dark,\n    diagnostics,\n    provenance: createRootProvenance(themeConfig),\n  };\n}\n\n/*** Compile one canonical mode and compare the independent owner results. */\nfunction compileMode(\n  themeConfig: ThemeConfig,\n  mode: ZoraThemeMode,\n  targets: readonly ZoraThemeSelectionTarget[],\n): ZoraComputedThemeMode {\n  const modeConfig = mode === 'light' ? themeConfig.light : themeConfig.dark;\n  const generated = generateThemeModeColors(modeConfig);\n  const surfaceTheme = createTheme(themeConfig, mode);\n  const { diagnostics, selections } = resolveSelections(generated, mode, targets);\n\n  if (!outputsAgree(generated, surfaceTheme.colorDiagnostics.generated)) {\n    diagnostics.push({\n      code: 'generated-output-divergence',\n      message: 'Surface and Color Theory returned different generated color evidence.',\n      mode,\n      path: `${mode}.generated`,\n      severity: 'error',\n    });\n  }\n\n  return {\n    mode,\n    generated,\n    surfaceTheme,\n    selections,\n    diagnostics,\n    provenance: createModeProvenance(mode, targets),\n  };\n}\n\n/*** Resolve measurable swatch targets without substituting unavailable roles. */\nfunction resolveSelections(\n  generated: ZoraComputedThemeMode['generated'],\n  mode: ZoraThemeMode,\n  targets: readonly ZoraThemeSelectionTarget[],\n): {\n  diagnostics: ZoraThemeCompilationDiagnostic[];\n  selections: ZoraThemeSelectionResult[];\n} {\n  const diagnostics: ZoraThemeCompilationDiagnostic[] = [];\n  const selections = targets.map((request) => {\n    const swatch = generated.swatches[request.swatch];\n    const result = swatch\n      ? selectColorSwatchStep(swatch, request.target, request.contexts, request.tiePolicy)\n      : null;\n\n    if (!swatch) diagnostics.push(createMissingSwatchDiagnostic(mode, request));\n    else if (!result?.selected) diagnostics.push(createUnresolvedTargetDiagnostic(mode, request));\n\n    return { request, result };\n  });\n\n  return { diagnostics, selections };\n}\n\n/*** Describe a requested swatch that the selected harmony does not generate. */\nfunction createMissingSwatchDiagnostic(\n  mode: ZoraThemeMode,\n  request: ZoraThemeSelectionTarget,\n): ZoraThemeCompilationDiagnostic {\n  return {\n    code: 'missing-target-swatch',\n    message: `The selected harmony does not generate the '${request.swatch}' swatch.`,\n    mode,\n    path: `${mode}.selectionTargets.${request.id}`,\n    severity: 'error',\n  };\n}\n\n/*** Describe a measurable target that has no passing swatch candidate. */\nfunction createUnresolvedTargetDiagnostic(\n  mode: ZoraThemeMode,\n  request: ZoraThemeSelectionTarget,\n): ZoraThemeCompilationDiagnostic {\n  return {\n    code: 'unresolved-selection-target',\n    message: `No '${request.swatch}' step satisfies selection target '${request.id}'.`,\n    mode,\n    path: `${mode}.selectionTargets.${request.id}`,\n    severity: 'error',\n  };\n}\n\n/*** Record direct source and Surface-owned default provenance. */\nfunction createRootProvenance(themeConfig: ThemeConfig): ZoraThemeProvenanceEntry[] {\n  return [\n    { path: 'themeConfig', origin: 'direct', owner: CONTRACTS_OWNER },\n    {\n      path: 'themeConfig.tokens',\n      origin: themeConfig.tokens ? 'direct' : 'defaulted',\n      owner: themeConfig.tokens ? CONTRACTS_OWNER : SURFACE_OWNER,\n    },\n  ];\n}\n\n/*** Record the owner transformation chain for one compiled mode. */\nfunction createModeProvenance(\n  mode: ZoraThemeMode,\n  targets: readonly ZoraThemeSelectionTarget[],\n): ZoraThemeProvenanceEntry[] {\n  const inputPath = `themeConfig.${mode}`;\n  const entries: ZoraThemeProvenanceEntry[] = [\n    { path: inputPath, origin: 'direct', owner: CONTRACTS_OWNER },\n    {\n      path: `${mode}.generated`,\n      origin: 'derived',\n      owner: COLOR_THEORY_OWNER,\n      inputs: [inputPath],\n    },\n    {\n      path: `${mode}.surfaceTheme`,\n      origin: 'derived',\n      owner: SURFACE_OWNER,\n      inputs: ['themeConfig', inputPath],\n    },\n  ];\n\n  for (const target of targets) {\n    const targetPath = `${mode}.selectionTargets.${target.id}`;\n    entries.push({ path: targetPath, origin: 'direct', owner: ZORA_OWNER });\n    entries.push({\n      path: `${mode}.selections.${target.id}`,\n      origin: 'derived',\n      owner: COLOR_THEORY_OWNER,\n      inputs: [`${mode}.generated.swatches.${target.swatch}`, targetPath],\n    });\n  }\n\n  return entries;\n}\n\n/*** Compare deterministic owner result records for divergence diagnostics. */\nfunction outputsAgree(left: unknown, right: unknown): boolean {\n  return JSON.stringify(left) === JSON.stringify(right);\n}\n"]}

package/dist/theme/createZoraThemeConfig.d.ts

@@ -1,4 +1,5 @@
 import type { ThemeConfig } from '@ankhorage/contracts';
 import type { ZoraTheme } from './types';
+/*** Convert the concise ZORA design seed into canonical persisted theme source. */
 export declare function createZoraThemeConfig(theme?: ZoraTheme): ThemeConfig;
 //# sourceMappingURL=createZoraThemeConfig.d.ts.map

package/dist/theme/createZoraThemeConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createZoraThemeConfig.d.ts","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,SAA4B,GAAG,WAAW,CAetF"}
+{"version":3,"file":"createZoraThemeConfig.d.ts","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,SAA4B,GAAG,WAAW,CAetF"}

package/dist/theme/createZoraThemeConfig.js

@@ -1,5 +1,6 @@
 import { parseHexColorOrThrow } from '@ankhorage/color-theory';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
+/*** Convert the concise ZORA design seed into canonical persisted theme source. */
 export function createZoraThemeConfig(theme = zoraDefaultTheme) {
     const primaryColor = parseHexColorOrThrow(theme.primaryColor);
     return {

package/dist/theme/createZoraThemeConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"createZoraThemeConfig.js","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAI/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,UAAU,qBAAqB,CAAC,QAAmB,gBAAgB;IACvE,MAAM,YAAY,GAAG,oBAAoB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAE9D,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE;YACL,YAAY;YACZ,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB;QACD,IAAI,EAAE;YACJ,YAAY;YACZ,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { parseHexColorOrThrow } from '@ankhorage/color-theory';\nimport type { ThemeConfig } from '@ankhorage/contracts';\n\nimport type { ZoraTheme } from './types';\nimport { zoraDefaultTheme } from './zoraDefaultTheme';\n\nexport function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {\n  const primaryColor = parseHexColorOrThrow(theme.primaryColor);\n\n  return {\n    id: theme.id,\n    name: theme.name,\n    light: {\n      primaryColor,\n      harmony: theme.harmony,\n    },\n    dark: {\n      primaryColor,\n      harmony: theme.harmony,\n    },\n  };\n}\n"]}
+{"version":3,"file":"createZoraThemeConfig.js","sourceRoot":"","sources":["../../src/theme/createZoraThemeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAI/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CAAC,QAAmB,gBAAgB;IACvE,MAAM,YAAY,GAAG,oBAAoB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAE9D,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE;YACL,YAAY;YACZ,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB;QACD,IAAI,EAAE;YACJ,YAAY;YACZ,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { parseHexColorOrThrow } from '@ankhorage/color-theory';\nimport type { ThemeConfig } from '@ankhorage/contracts';\n\nimport type { ZoraTheme } from './types';\nimport { zoraDefaultTheme } from './zoraDefaultTheme';\n\n/*** Convert the concise ZORA design seed into canonical persisted theme source. */\nexport function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {\n  const primaryColor = parseHexColorOrThrow(theme.primaryColor);\n\n  return {\n    id: theme.id,\n    name: theme.name,\n    light: {\n      primaryColor,\n      harmony: theme.harmony,\n    },\n    dark: {\n      primaryColor,\n      harmony: theme.harmony,\n    },\n  };\n}\n"]}

package/dist/theme/index.d.ts

@@ -1,11 +1,9 @@
-export { createZoraThemeConfig } from './createZoraThemeConfig';
+export * from './public';
 export { ThemeModeToggle } from './ThemeModeToggle';
 export type { ThemeModeToggleProps } from './ThemeModeToggleProps';
-export type { ZoraComputedTheme, ZoraComputedThemeMode, ZoraTheme, ZoraThemeId, ZoraThemeMode, } from './types';
 export { useZoraTheme } from './useZoraTheme';
 export { withZoraThemeScope } from './withZoraThemeScope';
 export type { ZoraBaseProps } from './ZoraBaseProps';
-export { zoraDefaultTheme } from './zoraDefaultTheme';
 export type { ZoraProviderProps } from './ZoraProvider';
 export { ZoraProvider } from './ZoraProvider';
 export type { ZoraThemeScopeProps } from './ZoraThemeScope';

package/dist/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/theme/index.js

@@ -1,8 +1,7 @@
-export { createZoraThemeConfig } from './createZoraThemeConfig';
+export * from './public';
 export { ThemeModeToggle } from './ThemeModeToggle';
 export { useZoraTheme } from './useZoraTheme';
 export { withZoraThemeScope } from './withZoraThemeScope';
-export { zoraDefaultTheme } from './zoraDefaultTheme';
 export { ZoraProvider } from './ZoraProvider';
 export { ZoraThemeScope } from './ZoraThemeScope';
 //# sourceMappingURL=index.js.map

package/dist/theme/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["export { createZoraThemeConfig } from './createZoraThemeConfig';\nexport { ThemeModeToggle } from './ThemeModeToggle';\nexport type { ThemeModeToggleProps } from './ThemeModeToggleProps';\nexport type {\n  ZoraComputedTheme,\n  ZoraComputedThemeMode,\n  ZoraTheme,\n  ZoraThemeId,\n  ZoraThemeMode,\n} from './types';\nexport { useZoraTheme } from './useZoraTheme';\nexport { withZoraThemeScope } from './withZoraThemeScope';\nexport type { ZoraBaseProps } from './ZoraBaseProps';\nexport { zoraDefaultTheme } from './zoraDefaultTheme';\nexport type { ZoraProviderProps } from './ZoraProvider';\nexport { ZoraProvider } from './ZoraProvider';\nexport type { ZoraThemeScopeProps } from './ZoraThemeScope';\nexport { ZoraThemeScope } from './ZoraThemeScope';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["export * from './public';\nexport { ThemeModeToggle } from './ThemeModeToggle';\nexport type { ThemeModeToggleProps } from './ThemeModeToggleProps';\nexport { useZoraTheme } from './useZoraTheme';\nexport { withZoraThemeScope } from './withZoraThemeScope';\nexport type { ZoraBaseProps } from './ZoraBaseProps';\nexport type { ZoraProviderProps } from './ZoraProvider';\nexport { ZoraProvider } from './ZoraProvider';\nexport type { ZoraThemeScopeProps } from './ZoraThemeScope';\nexport { ZoraThemeScope } from './ZoraThemeScope';\n"]}

package/dist/theme/public.d.ts

@@ -0,0 +1,5 @@
+export { compileZoraTheme } from './compileZoraTheme';
+export { createZoraThemeConfig } from './createZoraThemeConfig';
+export type { ZoraComputedTheme, ZoraComputedThemeMode, ZoraTheme, ZoraThemeCompilationDiagnostic, ZoraThemeCompilationDiagnosticCode, ZoraThemeCompilationOptions, ZoraThemeId, ZoraThemeMode, ZoraThemeProvenanceEntry, ZoraThemeSelectionResult, ZoraThemeSelectionTarget, ZoraThemeSwatchRole, ZoraThemeValueOrigin, } from './types';
+export { zoraDefaultTheme } from './zoraDefaultTheme';
+//# sourceMappingURL=public.d.ts.map

package/dist/theme/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/theme/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,EACT,8BAA8B,EAC9B,kCAAkC,EAClC,2BAA2B,EAC3B,WAAW,EACX,aAAa,EACb,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/theme/public.js

@@ -0,0 +1,4 @@
+export { compileZoraTheme } from './compileZoraTheme';
+export { createZoraThemeConfig } from './createZoraThemeConfig';
+export { zoraDefaultTheme } from './zoraDefaultTheme';
+//# sourceMappingURL=public.js.map

package/dist/theme/public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../src/theme/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAgBhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export { compileZoraTheme } from './compileZoraTheme';\nexport { createZoraThemeConfig } from './createZoraThemeConfig';\nexport type {\n  ZoraComputedTheme,\n  ZoraComputedThemeMode,\n  ZoraTheme,\n  ZoraThemeCompilationDiagnostic,\n  ZoraThemeCompilationDiagnosticCode,\n  ZoraThemeCompilationOptions,\n  ZoraThemeId,\n  ZoraThemeMode,\n  ZoraThemeProvenanceEntry,\n  ZoraThemeSelectionResult,\n  ZoraThemeSelectionTarget,\n  ZoraThemeSwatchRole,\n  ZoraThemeValueOrigin,\n} from './types';\nexport { zoraDefaultTheme } from './zoraDefaultTheme';\n"]}

package/dist/theme/types.d.ts

@@ -1,6 +1,6 @@
-import type { ColorHarmony, GeneratedThemeModeColors, GeneratedThemeSwatches, SemanticColorToken } from '@ankhorage/color-theory';
+import type { ColorContrastContext, ColorHarmony, ColorSelectionTarget, ColorSwatchSelectionResult, ColorSwatchTiePolicy, GeneratedThemeModeColors, GeneratedThemeSwatches } from '@ankhorage/color-theory';
 import type { AppCategory, ThemeConfig } from '@ankhorage/contracts';
-import type { SurfaceTheme } from '@ankhorage/surface';
+import type { SurfaceTheme } from '@ankhorage/surface/theme';
 export type ZoraThemeId = string;
 export type ZoraThemeMode = 'light' | 'dark';
 export interface ZoraTheme {
@@ -10,19 +10,50 @@ export interface ZoraTheme {
     primaryColor: string;
     harmony: ColorHarmony;
 }
+export type ZoraThemeSwatchRole = keyof GeneratedThemeSwatches;
+/** A measurable request delegated to Color Theory's canonical swatch selector. */
+export interface ZoraThemeSelectionTarget {
+    readonly id: string;
+    readonly swatch: ZoraThemeSwatchRole;
+    readonly target: ColorSelectionTarget;
+    readonly contexts: readonly ColorContrastContext[];
+    readonly tiePolicy: ColorSwatchTiePolicy;
+}
+export interface ZoraThemeCompilationOptions {
+    readonly selectionTargets?: Partial<Record<ZoraThemeMode, readonly ZoraThemeSelectionTarget[]>>;
+}
+export interface ZoraThemeSelectionResult {
+    readonly request: ZoraThemeSelectionTarget;
+    readonly result: ColorSwatchSelectionResult | null;
+}
+export type ZoraThemeCompilationDiagnosticCode = 'generated-output-divergence' | 'missing-target-swatch' | 'unresolved-selection-target';
+export interface ZoraThemeCompilationDiagnostic {
+    readonly code: ZoraThemeCompilationDiagnosticCode;
+    readonly message: string;
+    readonly mode: ZoraThemeMode;
+    readonly path: string;
+    readonly severity: 'error';
+}
+export type ZoraThemeValueOrigin = 'defaulted' | 'derived' | 'direct';
+export interface ZoraThemeProvenanceEntry {
+    readonly path: string;
+    readonly origin: ZoraThemeValueOrigin;
+    readonly owner: string;
+    readonly inputs?: readonly string[];
+}
 export interface ZoraComputedThemeMode {
-    mode: ZoraThemeMode;
-    surfaceTheme: SurfaceTheme;
-    generated: GeneratedThemeModeColors;
-    swatches: GeneratedThemeSwatches;
-    semanticColors?: Record<SemanticColorToken, string>;
+    readonly mode: ZoraThemeMode;
+    readonly generated: GeneratedThemeModeColors;
+    readonly surfaceTheme: SurfaceTheme;
+    readonly selections: readonly ZoraThemeSelectionResult[];
+    readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];
+    readonly provenance: readonly ZoraThemeProvenanceEntry[];
 }
 export interface ZoraComputedTheme {
-    id: ZoraThemeId;
-    name: string;
-    source: ZoraTheme;
-    surfaceConfig: ThemeConfig;
-    light: ZoraComputedThemeMode;
-    dark: ZoraComputedThemeMode;
+    readonly themeConfig: ThemeConfig;
+    readonly light: ZoraComputedThemeMode;
+    readonly dark: ZoraComputedThemeMode;
+    readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];
+    readonly provenance: readonly ZoraThemeProvenanceEntry[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/theme/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,wBAAwB,CAAC;IACpC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,WAAW,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC;IAClB,aAAa,EAAE,WAAW,CAAC;IAC3B,KAAK,EAAE,qBAAqB,CAAC;IAC7B,IAAI,EAAE,qBAAqB,CAAC;CAC7B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"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"}

package/dist/theme/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ColorHarmony,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n  SemanticColorToken,\n} from '@ankhorage/color-theory';\nimport type { AppCategory, ThemeConfig } from '@ankhorage/contracts';\nimport type { SurfaceTheme } from '@ankhorage/surface';\n\nexport type ZoraThemeId = string;\n\nexport type ZoraThemeMode = 'light' | 'dark';\n\nexport interface ZoraTheme {\n  id: ZoraThemeId;\n  name: string;\n  appCategory: AppCategory;\n  primaryColor: string;\n  harmony: ColorHarmony;\n}\n\nexport interface ZoraComputedThemeMode {\n  mode: ZoraThemeMode;\n  surfaceTheme: SurfaceTheme;\n  generated: GeneratedThemeModeColors;\n  swatches: GeneratedThemeSwatches;\n  semanticColors?: Record<SemanticColorToken, string>;\n}\n\nexport interface ZoraComputedTheme {\n  id: ZoraThemeId;\n  name: string;\n  source: ZoraTheme;\n  surfaceConfig: ThemeConfig;\n  light: ZoraComputedThemeMode;\n  dark: ZoraComputedThemeMode;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  ColorContrastContext,\n  ColorHarmony,\n  ColorSelectionTarget,\n  ColorSwatchSelectionResult,\n  ColorSwatchTiePolicy,\n  GeneratedThemeModeColors,\n  GeneratedThemeSwatches,\n} from '@ankhorage/color-theory';\nimport type { AppCategory, ThemeConfig } from '@ankhorage/contracts';\nimport type { SurfaceTheme } from '@ankhorage/surface/theme';\n\nexport type ZoraThemeId = string;\n\nexport type ZoraThemeMode = 'light' | 'dark';\n\nexport interface ZoraTheme {\n  id: ZoraThemeId;\n  name: string;\n  appCategory: AppCategory;\n  primaryColor: string;\n  harmony: ColorHarmony;\n}\n\nexport type ZoraThemeSwatchRole = keyof GeneratedThemeSwatches;\n\n/** A measurable request delegated to Color Theory's canonical swatch selector. */\nexport interface ZoraThemeSelectionTarget {\n  readonly id: string;\n  readonly swatch: ZoraThemeSwatchRole;\n  readonly target: ColorSelectionTarget;\n  readonly contexts: readonly ColorContrastContext[];\n  readonly tiePolicy: ColorSwatchTiePolicy;\n}\n\nexport interface ZoraThemeCompilationOptions {\n  readonly selectionTargets?: Partial<Record<ZoraThemeMode, readonly ZoraThemeSelectionTarget[]>>;\n}\n\nexport interface ZoraThemeSelectionResult {\n  readonly request: ZoraThemeSelectionTarget;\n  readonly result: ColorSwatchSelectionResult | null;\n}\n\nexport type ZoraThemeCompilationDiagnosticCode =\n  'generated-output-divergence' | 'missing-target-swatch' | 'unresolved-selection-target';\n\nexport interface ZoraThemeCompilationDiagnostic {\n  readonly code: ZoraThemeCompilationDiagnosticCode;\n  readonly message: string;\n  readonly mode: ZoraThemeMode;\n  readonly path: string;\n  readonly severity: 'error';\n}\n\nexport type ZoraThemeValueOrigin = 'defaulted' | 'derived' | 'direct';\n\nexport interface ZoraThemeProvenanceEntry {\n  readonly path: string;\n  readonly origin: ZoraThemeValueOrigin;\n  readonly owner: string;\n  readonly inputs?: readonly string[];\n}\n\nexport interface ZoraComputedThemeMode {\n  readonly mode: ZoraThemeMode;\n  readonly generated: GeneratedThemeModeColors;\n  readonly surfaceTheme: SurfaceTheme;\n  readonly selections: readonly ZoraThemeSelectionResult[];\n  readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];\n  readonly provenance: readonly ZoraThemeProvenanceEntry[];\n}\n\nexport interface ZoraComputedTheme {\n  readonly themeConfig: ThemeConfig;\n  readonly light: ZoraComputedThemeMode;\n  readonly dark: ZoraComputedThemeMode;\n  readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];\n  readonly provenance: readonly ZoraThemeProvenanceEntry[];\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "3.3.4",
+  "version": "4.0.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -38,7 +38,7 @@
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.0",
     "@ankhorage/contracts": "^8.0.2",
-    "@ankhorage/surface": "^3.1.3"
+    "@ankhorage/surface": "^3.3.0"
   },
   "files": [
     "dist",
@@ -63,6 +63,14 @@
       "import": "./dist/metadata/index.js",
       "default": "./dist/metadata/index.js"
     },
+    "./theme": {
+      "bun": "./src/theme/public.ts",
+      "react-native": "./src/theme/public.ts",
+      "browser": "./src/theme/public.ts",
+      "types": "./dist/theme/public.d.ts",
+      "import": "./dist/theme/public.js",
+      "default": "./dist/theme/public.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/theme/compileZoraTheme.test.ts

@@ -0,0 +1,162 @@
+import {
+  COLOR_HARMONIES,
+  generateThemeModeColors,
+  parseHexColorOrThrow,
+} from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { describe, expect, test } from 'bun:test';
+
+import { compileZoraTheme, type ZoraComputedTheme, type ZoraThemeSelectionTarget } from './public';
+
+const baseConfig: ThemeConfig = {
+  id: 'compiler-test',
+  name: 'Compiler test',
+  light: { primaryColor: '#2563eb', harmony: 'analogous' },
+  dark: { primaryColor: '#f97316', harmony: 'square' },
+};
+
+function selectionTarget(
+  overrides: Partial<ZoraThemeSelectionTarget> = {},
+): ZoraThemeSelectionTarget {
+  return {
+    id: 'primary-action',
+    swatch: 'primary',
+    target: { lightness: 0.55, chroma: 0.15 },
+    contexts: [
+      {
+        id: 'canvas',
+        against: parseHexColorOrThrow('#ffffff'),
+        minimumContrast: 1,
+      },
+    ],
+    tiePolicy: 'lower-step',
+    ...overrides,
+  };
+}
+
+describe('compileZoraTheme', () => {
+  test('compiles different light and dark inputs through their canonical owners', () => {
+    const result: ZoraComputedTheme = compileZoraTheme(baseConfig);
+
+    expect(result.themeConfig).toBe(baseConfig);
+    expect(result.light.mode).toBe('light');
+    expect(result.dark.mode).toBe('dark');
+    expect(result.light.generated).toEqual(generateThemeModeColors(baseConfig.light));
+    expect(result.dark.generated).toEqual(generateThemeModeColors(baseConfig.dark));
+    expect(result.light.surfaceTheme.config).toBe(baseConfig);
+    expect(result.dark.surfaceTheme.config).toBe(baseConfig);
+    expect(result.light.surfaceTheme.colorDiagnostics.generated).toEqual(result.light.generated);
+    expect(result.dark.surfaceTheme.colorDiagnostics.generated).toEqual(result.dark.generated);
+    expect(result.diagnostics).toEqual([]);
+  });
+
+  test('accepts every harmony from the canonical Color Theory catalog', () => {
+    for (const harmony of COLOR_HARMONIES) {
+      const result = compileZoraTheme({
+        ...baseConfig,
+        light: { ...baseConfig.light, harmony },
+        dark: { ...baseConfig.dark, harmony },
+      });
+
+      expect(result.light.generated.harmonyRoleColors.harmony).toBe(harmony);
+      expect(result.dark.generated.harmonyRoleColors.harmony).toBe(harmony);
+    }
+  });
+
+  test('delegates measurable swatch targets to Color Theory', () => {
+    const target = selectionTarget();
+    const result = compileZoraTheme(baseConfig, { selectionTargets: { light: [target] } });
+
+    expect(result.light.selections).toHaveLength(1);
+    expect(result.light.selections[0]?.request).toBe(target);
+    expect(result.light.selections[0]?.result?.selected).not.toBeNull();
+    expect(result.light.diagnostics).toEqual([]);
+  });
+
+  test('reports a missing role instead of substituting another swatch', () => {
+    const config: ThemeConfig = {
+      ...baseConfig,
+      light: { ...baseConfig.light, harmony: 'monochromatic' },
+    };
+    const target = selectionTarget({ id: 'quaternary-action', swatch: 'quaternary' });
+    const result = compileZoraTheme(config, { selectionTargets: { light: [target] } });
+
+    expect(result.light.selections[0]?.result).toBeNull();
+    expect(result.light.diagnostics).toEqual([
+      expect.objectContaining({
+        code: 'missing-target-swatch',
+        path: 'light.selectionTargets.quaternary-action',
+      }),
+    ]);
+  });
+
+  test('reports targets that cannot satisfy their measured contrast contexts', () => {
+    const target = selectionTarget({
+      contexts: [
+        {
+          id: 'impossible',
+          against: parseHexColorOrThrow('#ffffff'),
+          minimumContrast: 21,
+        },
+      ],
+    });
+    const result = compileZoraTheme(baseConfig, { selectionTargets: { light: [target] } });
+
+    expect(result.light.selections[0]?.result?.selected).toBeNull();
+    expect(result.light.diagnostics[0]?.code).toBe('unresolved-selection-target');
+  });
+
+  test('records direct, defaulted, and derived provenance without persisting computed output', () => {
+    const result = compileZoraTheme(baseConfig, {
+      selectionTargets: { light: [selectionTarget()] },
+    });
+
+    expect(result.provenance).toContainEqual({
+      path: 'themeConfig',
+      origin: 'direct',
+      owner: '@ankhorage/contracts',
+    });
+    expect(result.provenance).toContainEqual({
+      path: 'themeConfig.tokens',
+      origin: 'defaulted',
+      owner: '@ankhorage/surface',
+    });
+    expect(
+      result.light.provenance.some(
+        ({ origin, owner, path }) =>
+          path === 'light.generated' && origin === 'derived' && owner === '@ankhorage/color-theory',
+      ),
+    ).toBe(true);
+    expect('generated' in result.themeConfig).toBe(false);
+  });
+
+  test('rejects invalid canonical source colors', () => {
+    expect(() =>
+      compileZoraTheme({
+        ...baseConfig,
+        light: { ...baseConfig.light, primaryColor: 'blue' },
+      }),
+    ).toThrow();
+  });
+
+  test('imports and executes through the public theme subpath in plain Bun', async () => {
+    const script = [
+      "import { compileZoraTheme } from '@ankhorage/zora/theme';",
+      `const result = compileZoraTheme(${JSON.stringify(baseConfig)});`,
+      'process.stdout.write(`${result.light.mode}:${result.dark.mode}`);',
+    ].join('\n');
+    const subprocess = Bun.spawn({
+      cmd: [process.execPath, '-e', script],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(subprocess.stdout).text(),
+      new Response(subprocess.stderr).text(),
+      subprocess.exited,
+    ]);
+
+    expect(exitCode, stderr).toBe(0);
+    expect(stdout).toBe('light:dark');
+  });
+});

package/src/theme/compileZoraTheme.ts

@@ -0,0 +1,177 @@
+import { generateThemeModeColors, selectColorSwatchStep } from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { createTheme } from '@ankhorage/surface/theme';
+
+import type {
+  ZoraComputedTheme,
+  ZoraComputedThemeMode,
+  ZoraThemeCompilationDiagnostic,
+  ZoraThemeCompilationOptions,
+  ZoraThemeMode,
+  ZoraThemeProvenanceEntry,
+  ZoraThemeSelectionResult,
+  ZoraThemeSelectionTarget,
+} from './types';
+
+const CONTRACTS_OWNER = '@ankhorage/contracts';
+const COLOR_THEORY_OWNER = '@ankhorage/color-theory';
+const SURFACE_OWNER = '@ankhorage/surface';
+const ZORA_OWNER = '@ankhorage/zora';
+
+/***
+ * Compile canonical theme source into Color Theory evidence and resolved Surface themes.
+ * This function is pure and does not mount React or reproduce owner algorithms.
+ */
+export function compileZoraTheme(
+  themeConfig: ThemeConfig,
+  options: ZoraThemeCompilationOptions = {},
+): ZoraComputedTheme {
+  const light = compileMode(themeConfig, 'light', options.selectionTargets?.light ?? []);
+  const dark = compileMode(themeConfig, 'dark', options.selectionTargets?.dark ?? []);
+  const diagnostics = [...light.diagnostics, ...dark.diagnostics];
+
+  return {
+    themeConfig,
+    light,
+    dark,
+    diagnostics,
+    provenance: createRootProvenance(themeConfig),
+  };
+}
+
+/*** Compile one canonical mode and compare the independent owner results. */
+function compileMode(
+  themeConfig: ThemeConfig,
+  mode: ZoraThemeMode,
+  targets: readonly ZoraThemeSelectionTarget[],
+): ZoraComputedThemeMode {
+  const modeConfig = mode === 'light' ? themeConfig.light : themeConfig.dark;
+  const generated = generateThemeModeColors(modeConfig);
+  const surfaceTheme = createTheme(themeConfig, mode);
+  const { diagnostics, selections } = resolveSelections(generated, mode, targets);
+
+  if (!outputsAgree(generated, surfaceTheme.colorDiagnostics.generated)) {
+    diagnostics.push({
+      code: 'generated-output-divergence',
+      message: 'Surface and Color Theory returned different generated color evidence.',
+      mode,
+      path: `${mode}.generated`,
+      severity: 'error',
+    });
+  }
+
+  return {
+    mode,
+    generated,
+    surfaceTheme,
+    selections,
+    diagnostics,
+    provenance: createModeProvenance(mode, targets),
+  };
+}
+
+/*** Resolve measurable swatch targets without substituting unavailable roles. */
+function resolveSelections(
+  generated: ZoraComputedThemeMode['generated'],
+  mode: ZoraThemeMode,
+  targets: readonly ZoraThemeSelectionTarget[],
+): {
+  diagnostics: ZoraThemeCompilationDiagnostic[];
+  selections: ZoraThemeSelectionResult[];
+} {
+  const diagnostics: ZoraThemeCompilationDiagnostic[] = [];
+  const selections = targets.map((request) => {
+    const swatch = generated.swatches[request.swatch];
+    const result = swatch
+      ? selectColorSwatchStep(swatch, request.target, request.contexts, request.tiePolicy)
+      : null;
+
+    if (!swatch) diagnostics.push(createMissingSwatchDiagnostic(mode, request));
+    else if (!result?.selected) diagnostics.push(createUnresolvedTargetDiagnostic(mode, request));
+
+    return { request, result };
+  });
+
+  return { diagnostics, selections };
+}
+
+/*** Describe a requested swatch that the selected harmony does not generate. */
+function createMissingSwatchDiagnostic(
+  mode: ZoraThemeMode,
+  request: ZoraThemeSelectionTarget,
+): ZoraThemeCompilationDiagnostic {
+  return {
+    code: 'missing-target-swatch',
+    message: `The selected harmony does not generate the '${request.swatch}' swatch.`,
+    mode,
+    path: `${mode}.selectionTargets.${request.id}`,
+    severity: 'error',
+  };
+}
+
+/*** Describe a measurable target that has no passing swatch candidate. */
+function createUnresolvedTargetDiagnostic(
+  mode: ZoraThemeMode,
+  request: ZoraThemeSelectionTarget,
+): ZoraThemeCompilationDiagnostic {
+  return {
+    code: 'unresolved-selection-target',
+    message: `No '${request.swatch}' step satisfies selection target '${request.id}'.`,
+    mode,
+    path: `${mode}.selectionTargets.${request.id}`,
+    severity: 'error',
+  };
+}
+
+/*** Record direct source and Surface-owned default provenance. */
+function createRootProvenance(themeConfig: ThemeConfig): ZoraThemeProvenanceEntry[] {
+  return [
+    { path: 'themeConfig', origin: 'direct', owner: CONTRACTS_OWNER },
+    {
+      path: 'themeConfig.tokens',
+      origin: themeConfig.tokens ? 'direct' : 'defaulted',
+      owner: themeConfig.tokens ? CONTRACTS_OWNER : SURFACE_OWNER,
+    },
+  ];
+}
+
+/*** Record the owner transformation chain for one compiled mode. */
+function createModeProvenance(
+  mode: ZoraThemeMode,
+  targets: readonly ZoraThemeSelectionTarget[],
+): ZoraThemeProvenanceEntry[] {
+  const inputPath = `themeConfig.${mode}`;
+  const entries: ZoraThemeProvenanceEntry[] = [
+    { path: inputPath, origin: 'direct', owner: CONTRACTS_OWNER },
+    {
+      path: `${mode}.generated`,
+      origin: 'derived',
+      owner: COLOR_THEORY_OWNER,
+      inputs: [inputPath],
+    },
+    {
+      path: `${mode}.surfaceTheme`,
+      origin: 'derived',
+      owner: SURFACE_OWNER,
+      inputs: ['themeConfig', inputPath],
+    },
+  ];
+
+  for (const target of targets) {
+    const targetPath = `${mode}.selectionTargets.${target.id}`;
+    entries.push({ path: targetPath, origin: 'direct', owner: ZORA_OWNER });
+    entries.push({
+      path: `${mode}.selections.${target.id}`,
+      origin: 'derived',
+      owner: COLOR_THEORY_OWNER,
+      inputs: [`${mode}.generated.swatches.${target.swatch}`, targetPath],
+    });
+  }
+
+  return entries;
+}
+
+/*** Compare deterministic owner result records for divergence diagnostics. */
+function outputsAgree(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}

package/src/theme/createZoraThemeConfig.ts

@@ -4,6 +4,7 @@ import type { ThemeConfig } from '@ankhorage/contracts';
 import type { ZoraTheme } from './types';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
 
+/*** Convert the concise ZORA design seed into canonical persisted theme source. */
 export function createZoraThemeConfig(theme: ZoraTheme = zoraDefaultTheme): ThemeConfig {
   const primaryColor = parseHexColorOrThrow(theme.primaryColor);
 

package/src/theme/index.ts

@@ -1,17 +1,9 @@
-export { createZoraThemeConfig } from './createZoraThemeConfig';
+export * from './public';
 export { ThemeModeToggle } from './ThemeModeToggle';
 export type { ThemeModeToggleProps } from './ThemeModeToggleProps';
-export type {
-  ZoraComputedTheme,
-  ZoraComputedThemeMode,
-  ZoraTheme,
-  ZoraThemeId,
-  ZoraThemeMode,
-} from './types';
 export { useZoraTheme } from './useZoraTheme';
 export { withZoraThemeScope } from './withZoraThemeScope';
 export type { ZoraBaseProps } from './ZoraBaseProps';
-export { zoraDefaultTheme } from './zoraDefaultTheme';
 export type { ZoraProviderProps } from './ZoraProvider';
 export { ZoraProvider } from './ZoraProvider';
 export type { ZoraThemeScopeProps } from './ZoraThemeScope';

package/src/theme/public.ts

@@ -0,0 +1,18 @@
+export { compileZoraTheme } from './compileZoraTheme';
+export { createZoraThemeConfig } from './createZoraThemeConfig';
+export type {
+  ZoraComputedTheme,
+  ZoraComputedThemeMode,
+  ZoraTheme,
+  ZoraThemeCompilationDiagnostic,
+  ZoraThemeCompilationDiagnosticCode,
+  ZoraThemeCompilationOptions,
+  ZoraThemeId,
+  ZoraThemeMode,
+  ZoraThemeProvenanceEntry,
+  ZoraThemeSelectionResult,
+  ZoraThemeSelectionTarget,
+  ZoraThemeSwatchRole,
+  ZoraThemeValueOrigin,
+} from './types';
+export { zoraDefaultTheme } from './zoraDefaultTheme';

package/src/theme/types.ts

@@ -1,11 +1,14 @@
 import type {
+  ColorContrastContext,
   ColorHarmony,
+  ColorSelectionTarget,
+  ColorSwatchSelectionResult,
+  ColorSwatchTiePolicy,
   GeneratedThemeModeColors,
   GeneratedThemeSwatches,
-  SemanticColorToken,
 } from '@ankhorage/color-theory';
 import type { AppCategory, ThemeConfig } from '@ankhorage/contracts';
-import type { SurfaceTheme } from '@ankhorage/surface';
+import type { SurfaceTheme } from '@ankhorage/surface/theme';
 
 export type ZoraThemeId = string;
 
@@ -19,19 +22,59 @@ export interface ZoraTheme {
   harmony: ColorHarmony;
 }
 
+export type ZoraThemeSwatchRole = keyof GeneratedThemeSwatches;
+
+/** A measurable request delegated to Color Theory's canonical swatch selector. */
+export interface ZoraThemeSelectionTarget {
+  readonly id: string;
+  readonly swatch: ZoraThemeSwatchRole;
+  readonly target: ColorSelectionTarget;
+  readonly contexts: readonly ColorContrastContext[];
+  readonly tiePolicy: ColorSwatchTiePolicy;
+}
+
+export interface ZoraThemeCompilationOptions {
+  readonly selectionTargets?: Partial<Record<ZoraThemeMode, readonly ZoraThemeSelectionTarget[]>>;
+}
+
+export interface ZoraThemeSelectionResult {
+  readonly request: ZoraThemeSelectionTarget;
+  readonly result: ColorSwatchSelectionResult | null;
+}
+
+export type ZoraThemeCompilationDiagnosticCode =
+  'generated-output-divergence' | 'missing-target-swatch' | 'unresolved-selection-target';
+
+export interface ZoraThemeCompilationDiagnostic {
+  readonly code: ZoraThemeCompilationDiagnosticCode;
+  readonly message: string;
+  readonly mode: ZoraThemeMode;
+  readonly path: string;
+  readonly severity: 'error';
+}
+
+export type ZoraThemeValueOrigin = 'defaulted' | 'derived' | 'direct';
+
+export interface ZoraThemeProvenanceEntry {
+  readonly path: string;
+  readonly origin: ZoraThemeValueOrigin;
+  readonly owner: string;
+  readonly inputs?: readonly string[];
+}
+
 export interface ZoraComputedThemeMode {
-  mode: ZoraThemeMode;
-  surfaceTheme: SurfaceTheme;
-  generated: GeneratedThemeModeColors;
-  swatches: GeneratedThemeSwatches;
-  semanticColors?: Record<SemanticColorToken, string>;
+  readonly mode: ZoraThemeMode;
+  readonly generated: GeneratedThemeModeColors;
+  readonly surfaceTheme: SurfaceTheme;
+  readonly selections: readonly ZoraThemeSelectionResult[];
+  readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];
+  readonly provenance: readonly ZoraThemeProvenanceEntry[];
 }
 
 export interface ZoraComputedTheme {
-  id: ZoraThemeId;
-  name: string;
-  source: ZoraTheme;
-  surfaceConfig: ThemeConfig;
-  light: ZoraComputedThemeMode;
-  dark: ZoraComputedThemeMode;
+  readonly themeConfig: ThemeConfig;
+  readonly light: ZoraComputedThemeMode;
+  readonly dark: ZoraComputedThemeMode;
+  readonly diagnostics: readonly ZoraThemeCompilationDiagnostic[];
+  readonly provenance: readonly ZoraThemeProvenanceEntry[];
 }