@ankhorage/zora 18.0.1 → 19.0.1

package/src/features/theme/adapters/inbound/ZoraThemeScope.tsx

@@ -0,0 +1,41 @@
+import { ThemeScope } from '@ankhorage/surface';
+import React, { useMemo } from 'react';
+
+import type { ZoraThemeId, ZoraThemeMode } from '../../../../types/theme';
+import {
+  useZoraThemeRuntime,
+  ZoraThemeRuntimeContext,
+} from '../../composition/ZoraThemeRuntimeContext';
+import { resolveZoraScopedThemeId } from '../../utils/resolveZoraScopedThemeId';
+
+export interface ZoraThemeScopeProps {
+  children: React.ReactNode;
+  themeId?: ZoraThemeId;
+  mode?: ZoraThemeMode;
+}
+
+/*** Applies nested ZORA theme overrides through the public Surface theme scope. */
+export function ZoraThemeScope({ children, themeId, mode }: ZoraThemeScopeProps) {
+  if (mode === undefined && themeId === undefined) return children;
+  return (
+    <ZoraThemeScopeInner mode={mode} themeId={themeId}>
+      {children}
+    </ZoraThemeScopeInner>
+  );
+}
+
+/*** Resolves and provides the scoped Surface and ZORA theme runtime values. */
+function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
+  const parentRuntime = useZoraThemeRuntime();
+  const scopedThemeId = resolveZoraScopedThemeId({
+    desiredThemeId: themeId,
+    inheritedThemeId: parentRuntime.themeId,
+  });
+  const scopedRuntimeValue = useMemo(() => ({ themeId: scopedThemeId }), [scopedThemeId]);
+  const scopedChildren =
+    mode === undefined ? children : <ThemeScope mode={mode}>{children}</ThemeScope>;
+
+  return (
+    <ZoraThemeRuntimeContext value={scopedRuntimeValue}>{scopedChildren}</ZoraThemeRuntimeContext>
+  );
+}

package/src/features/theme/adapters/inbound/withZoraThemeScope.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+import type { ZoraBaseProps } from '../../../../types/base';
+import { ZoraThemeScope } from './ZoraThemeScope';
+
+export function withZoraThemeScope<P extends ZoraBaseProps>(
+  Component: (props: P) => React.ReactElement | null,
+): (props: P) => React.ReactElement | null {
+  const Wrapped = (props: P) => {
+    if (props.mode === undefined && props.themeId === undefined) {
+      return React.createElement(Component, props);
+    }
+
+    return (
+      <ZoraThemeScope mode={props.mode} themeId={props.themeId}>
+        {React.createElement(Component, props)}
+      </ZoraThemeScope>
+    );
+  };
+
+  const name =
+    (Component as { displayName?: string }).displayName ?? (Component.name || 'Component');
+  (Wrapped as { displayName?: string }).displayName = `withZoraThemeScope(${name})`;
+
+  return Wrapped;
+}

package/src/features/theme/application/use-cases/compileZoraTheme.test.ts

@@ -0,0 +1,166 @@
+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/features/theme/application/use-cases/compileZoraTheme.ts

@@ -0,0 +1,178 @@
+import { generateThemeModeColors, selectColorSwatchStep } from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { createTheme } from '@ankhorage/surface/theme';
+import { isDeepEqual } from '@ankhorage/utility/object';
+
+import type {
+  ZoraComputedTheme,
+  ZoraComputedThemeMode,
+  ZoraThemeCompilationDiagnostic,
+  ZoraThemeCompilationOptions,
+  ZoraThemeMode,
+  ZoraThemeProvenanceEntry,
+  ZoraThemeSelectionResult,
+  ZoraThemeSelectionTarget,
+} from '../../../../types/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: 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 isDeepEqual(left, right);
+}

package/src/features/theme/application/use-cases/createZoraThemeConfig.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+
+import { zoraDefaultTheme } from '../../zoraDefaultTheme';
+import { createZoraThemeConfig } from './createZoraThemeConfig';
+
+describe('createZoraThemeConfig', () => {
+  test('converts the default theme seed into a surface config', () => {
+    const themeConfig = createZoraThemeConfig();
+
+    expect(themeConfig.id).toBe('zora');
+    expect(themeConfig.name).toBe('ZORA');
+    expect(themeConfig.light.primaryColor).toBe(zoraDefaultTheme.primaryColor);
+    expect(themeConfig.light.harmony).toBe('analogous');
+    expect(themeConfig.dark.primaryColor).toBe(zoraDefaultTheme.primaryColor);
+    expect(themeConfig.dark.harmony).toBe('analogous');
+  });
+
+  test('uses theme.name directly without fallback to id', () => {
+    const themeConfig = createZoraThemeConfig({
+      id: 'studio',
+      name: 'Studio',
+      appCategory: 'developer_tools',
+      primaryColor: '#0f766e',
+      harmony: 'analogous',
+    });
+
+    expect(themeConfig.id).toBe('studio');
+    expect(themeConfig.name).toBe('Studio');
+  });
+
+  test('preserves the same primaryColor for both light and dark', () => {
+    const primary = '#2563eb';
+    const themeConfig = createZoraThemeConfig({
+      id: 'test',
+      name: 'Test',
+      appCategory: 'utilities_tools',
+      primaryColor: primary,
+      harmony: 'triadic',
+    });
+
+    expect(themeConfig.light.primaryColor).toBe(primary);
+    expect(themeConfig.dark.primaryColor).toBe(primary);
+  });
+
+  test('validates public primaryColor strings during config conversion', () => {
+    expect(() =>
+      createZoraThemeConfig({
+        id: 'bad-theme',
+        name: 'Bad Theme',
+        appCategory: 'utilities_tools',
+        primaryColor: 'blue',
+        harmony: 'triadic',
+      }),
+    ).toThrow();
+  });
+
+  test('output has no colorTone field', () => {
+    const themeConfig = createZoraThemeConfig();
+
+    expect('colorTone' in themeConfig.light).toBe(false);
+    expect('colorTone' in themeConfig.dark).toBe(false);
+  });
+
+  test('surfaceConfig.name equals theme.name', () => {
+    const themeConfig = createZoraThemeConfig({
+      id: 'my-theme',
+      name: 'My Theme',
+      appCategory: 'games',
+      primaryColor: '#7c3aed',
+      harmony: 'complementary',
+    });
+
+    expect(themeConfig.name).toBe('My Theme');
+  });
+});

package/src/features/theme/application/use-cases/createZoraThemeConfig.ts

@@ -0,0 +1,23 @@
+import { parseHexColorOrThrow } from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
+
+import type { ZoraTheme } from '../../../../types/theme';
+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);
+
+  return {
+    id: theme.id,
+    name: theme.name,
+    light: {
+      primaryColor,
+      harmony: theme.harmony,
+    },
+    dark: {
+      primaryColor,
+      harmony: theme.harmony,
+    },
+  };
+}

package/src/features/theme/colorModel.ts

@@ -0,0 +1,13 @@
+import {
+  SURFACE_COLORS,
+  SURFACE_EMPHASES,
+  SURFACE_PALETTE_COLORS,
+  SURFACE_STATUS_COLORS,
+} from '@ankhorage/surface/color';
+
+export type { ZoraColor, ZoraEmphasis, ZoraPaletteColor, ZoraStatusColor } from '../../types/theme';
+
+export const ZORA_PALETTE_COLORS = SURFACE_PALETTE_COLORS;
+export const ZORA_STATUS_COLORS = SURFACE_STATUS_COLORS;
+export const ZORA_COLORS = SURFACE_COLORS;
+export const ZORA_EMPHASES = SURFACE_EMPHASES;

package/src/features/theme/composition/ZoraRuntimeCapabilities.native.tsx

@@ -0,0 +1,19 @@
+import { ToastProvider as SurfaceToastProvider } from '@ankhorage/surface';
+import { BottomSheetProvider } from '@ankhorage/surface/bottom-sheet';
+
+import type { ZoraRuntimeCapabilitiesProps } from '../../../types/provider';
+
+/*** Installs optional native runtime capabilities without forcing unused hosts. */
+export function ZoraRuntimeCapabilities({
+  bottomSheet,
+  children,
+  toast,
+}: ZoraRuntimeCapabilitiesProps) {
+  const toastContent = toast ? (
+    <SurfaceToastProvider {...(toast === true ? {} : toast)}>{children}</SurfaceToastProvider>
+  ) : (
+    children
+  );
+
+  return bottomSheet ? <BottomSheetProvider>{toastContent}</BottomSheetProvider> : toastContent;
+}

package/src/features/theme/composition/ZoraRuntimeCapabilities.web.tsx

@@ -0,0 +1,10 @@
+import { ToastProvider as SurfaceToastProvider } from '@ankhorage/surface';
+
+import type { ZoraRuntimeCapabilitiesProps } from '../../../types/provider';
+
+/*** Installs only web-relevant optional runtime capabilities. */
+export function ZoraRuntimeCapabilities({ children, toast }: ZoraRuntimeCapabilitiesProps) {
+  if (!toast) return children;
+
+  return <SurfaceToastProvider {...(toast === true ? {} : toast)}>{children}</SurfaceToastProvider>;
+}

package/src/features/theme/composition/ZoraThemeRuntimeContext.tsx

@@ -0,0 +1,17 @@
+import { createContext, use } from 'react';
+
+import type { ZoraThemeId } from '../../../types/theme';
+import { zoraDefaultTheme } from '../zoraDefaultTheme';
+
+interface ZoraThemeRuntime {
+  themeId: ZoraThemeId;
+}
+
+export const ZoraThemeRuntimeContext = createContext<ZoraThemeRuntime>({
+  themeId: zoraDefaultTheme.id,
+});
+
+/*** Returns the active ZORA theme runtime. */
+export function useZoraThemeRuntime(): ZoraThemeRuntime {
+  return use(ZoraThemeRuntimeContext);
+}

package/src/features/theme/composition/useZoraThemeRecipe.ts

@@ -0,0 +1,7 @@
+import { resolveZoraThemeRecipe } from '../utils/resolveZoraThemeRecipe';
+import { useZoraTheme } from './useZoraTheme';
+
+export function useZoraThemeRecipe(recipeName: string) {
+  const { theme } = useZoraTheme();
+  return resolveZoraThemeRecipe(theme, recipeName);
+}

package/src/features/theme/public.ts

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

package/src/features/theme/runtime.ts

@@ -0,0 +1,9 @@
+export type { ZoraBaseProps } from '../../types/base';
+export type { ThemeModeToggleProps } from '../../types/theme-mode-toggle';
+export { ThemeModeToggle } from './adapters/inbound/ThemeModeToggle';
+export { withZoraThemeScope } from './adapters/inbound/withZoraThemeScope';
+export type { ZoraProviderProps, ZoraToastCapability } from './adapters/inbound/ZoraProvider';
+export { ZoraProvider } from './adapters/inbound/ZoraProvider';
+export type { ZoraThemeScopeProps } from './adapters/inbound/ZoraThemeScope';
+export { ZoraThemeScope } from './adapters/inbound/ZoraThemeScope';
+export { useZoraTheme } from './composition/useZoraTheme';

package/src/features/theme/themeConfigScope.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+const themeDir = import.meta.dir;
+const srcDir = join(themeDir, '..', '..');
+
+describe('canonical ThemeConfig scope propagation', () => {
+  test('provider accepts the canonical ThemeConfig without duplicating live config state', () => {
+    const provider = readFileSync(
+      join(themeDir, 'adapters', 'inbound', 'ZoraProvider.tsx'),
+      'utf8',
+    );
+    const providerTypes = readFileSync(join(srcDir, 'types', 'provider.ts'), 'utf8');
+    const context = readFileSync(
+      join(themeDir, 'composition', 'ZoraThemeRuntimeContext.tsx'),
+      'utf8',
+    );
+
+    expect(providerTypes).toContain('themeConfig?: ThemeConfig');
+    expect(provider).toContain('themeConfig ?? createZoraThemeConfig(theme)');
+    expect(context).not.toContain('ThemeConfig');
+    expect(context).not.toContain('sourceTheme');
+  });
+
+  test('nested scopes delegate Surface config and mode ownership to ThemeScope', () => {
+    const scope = readFileSync(join(themeDir, 'adapters', 'inbound', 'ZoraThemeScope.tsx'), 'utf8');
+    expect(scope).toContain("import { ThemeScope } from '@ankhorage/surface';");
+    expect(scope).toContain('<ThemeScope mode={mode}>');
+    expect(scope).not.toContain('parentSurface');
+    expect(scope).not.toContain('sourceConfig');
+    expect(scope).not.toContain('createTheme');
+    expect(scope).not.toContain('createZoraThemeConfig');
+    expect(scope).not.toContain('sourceTheme');
+  });
+});