@ankhorage/surface 8.0.0 → 9.0.0

package/src/{theme → features/theme/application/use-cases}/createThemeOverrides.test.ts

@@ -1,12 +1,14 @@
 import type { ThemeConfig } from '@ankhorage/contracts';
 import { describe, expect, it } from 'bun:test';
 
-import { createTheme, DEFAULT_CONFIG, DEFAULT_TOKENS } from './createTheme';
+import { DEFAULT_TOKENS } from '../../constants';
+import { createTheme } from './createTheme';
+
+const defaultConfig = createTheme().config;
 
 describe('createTheme authored global tokens', () => {
   it('preserves defaults when no authored overrides exist', () => {
-    const theme = createTheme(DEFAULT_CONFIG);
-
+    const theme = createTheme(defaultConfig);
     expect(theme.spacing).toEqual(DEFAULT_TOKENS.spacing);
     expect(theme.radii).toEqual(DEFAULT_TOKENS.radii);
     expect(theme.typography.sizes).toEqual(DEFAULT_TOKENS.typography.sizes);
@@ -16,7 +18,7 @@ describe('createTheme authored global tokens', () => {
 
   it('merges authored global tokens without copying omitted defaults into config', () => {
     const config: ThemeConfig = {
-      ...DEFAULT_CONFIG,
+      ...defaultConfig,
       tokens: {
         spacing: { m: 18, hero: 64 },
         radii: { l: 20, pill: 999 },
@@ -28,9 +30,7 @@ describe('createTheme authored global tokens', () => {
         shadows: { soft: 3, floating: 12 },
       },
     };
-
     const theme = createTheme(config);
-
     expect(theme.spacing).toMatchObject({ xs: 4, m: 18, hero: 64 });
     expect(theme.radii).toMatchObject({ m: 8, l: 20, pill: 999 });
     expect(theme.typography.sizes).toMatchObject({ s: 14, m: 17, display: 44 });
@@ -41,9 +41,8 @@ describe('createTheme authored global tokens', () => {
   });
 
   it('keeps module-derived font families isolated per resolved theme', () => {
-    const withFont = createTheme(DEFAULT_CONFIG, 'light', 'source-sans');
-    const withoutFont = createTheme(DEFAULT_CONFIG);
-
+    const withFont = createTheme(defaultConfig, 'light', 'source-sans');
+    const withoutFont = createTheme(defaultConfig);
     expect(withFont.typography.fonts.normal['400']).toBe('SourceSans_400Regular');
     expect(withoutFont.typography.fonts.normal['400']).toBeUndefined();
     expect(DEFAULT_TOKENS.typography.fonts.normal['400']).toBeUndefined();

package/src/{theme → features/theme/application/use-cases}/createThemeValidation.test.ts

@@ -1,7 +1,9 @@
 import type { ThemeConfig, ThemeGlobalTokenOverrides } from '@ankhorage/contracts';
 import { describe, expect, it } from 'bun:test';
 
-import { createTheme, DEFAULT_CONFIG } from './createTheme';
+import { createTheme } from './createTheme';
+
+const defaultConfig = createTheme().config;
 
 describe('createTheme token validation', () => {
   it('rejects negative or non-finite numeric tokens', () => {
@@ -46,5 +48,5 @@ describe('createTheme token validation', () => {
 });
 
 function withTokens(tokens: ThemeGlobalTokenOverrides): ThemeConfig {
-  return { ...DEFAULT_CONFIG, tokens };
+  return { ...defaultConfig, tokens };
 }

package/src/features/theme/constants.ts

@@ -0,0 +1,68 @@
+import type { FontWeight, ThemeTokens } from '../../types/theme';
+
+const EMPTY_FONT_MAP: Record<FontWeight, string | undefined> = {
+  '100': undefined,
+  '200': undefined,
+  '300': undefined,
+  '400': undefined,
+  '500': undefined,
+  '600': undefined,
+  '700': undefined,
+  '800': undefined,
+  '900': undefined,
+  bold: undefined,
+  normal: undefined,
+};
+
+const DEFAULT_TOKENS: Omit<ThemeTokens, 'colors' | 'swatches' | 'semantics' | 'colorDiagnostics'> =
+  {
+    spacing: { none: 0, xs: 4, s: 8, m: 16, l: 24, xl: 32, xxl: 48 },
+    radii: { none: 0, s: 4, m: 8, l: 16, full: 9999 },
+    typography: {
+      headings: {
+        1: { size: 32, lineHeight: 40, weight: 'bold' },
+        2: { size: 24, lineHeight: 32, weight: 'bold' },
+        3: { size: 20, lineHeight: 28, weight: 'bold' },
+        4: { size: 18, lineHeight: 24, weight: 'semiBold' },
+        5: { size: 16, lineHeight: 22, weight: 'semiBold' },
+        6: { size: 14, lineHeight: 20, weight: 'semiBold' },
+      },
+      sizes: {
+        xs: 12,
+        s: 14,
+        m: 16,
+        l: 18,
+        xl: 20,
+        xxl: 24,
+        '3xl': 30,
+        h1: 32,
+        h2: 24,
+        h3: 20,
+        h4: 18,
+        h5: 16,
+        h6: 14,
+      },
+      weights: {
+        thin: '100',
+        extraLight: '200',
+        light: '300',
+        regular: '400',
+        medium: '500',
+        semiBold: '600',
+        bold: '700',
+        extraBold: '800',
+        black: '900',
+      },
+      fonts: { normal: { ...EMPTY_FONT_MAP }, italic: { ...EMPTY_FONT_MAP } },
+    },
+    shadows: { soft: 2, medium: 4, hard: 8 },
+  };
+
+export const SURFACE_COLOR_POLICY = {
+  disabledContrast: 3,
+  surfaceSeparation: 1.05,
+  textContrast: 4.5,
+  uiContrast: 3,
+} as const;
+
+export { DEFAULT_TOKENS };

package/src/{theme → features/theme/domain}/createSurfaceColorDiagnosticCollector.ts

@@ -11,7 +11,10 @@ import {
   selectColorSwatchStep,
 } from '@ankhorage/color-theory';
 
-import type { SurfaceColorSelectionDiagnostic, SurfaceContrastDiagnostic } from './types';
+import type {
+  SurfaceColorSelectionDiagnostic,
+  SurfaceContrastDiagnostic,
+} from '../../../types/theme';
 
 /** Collect deterministic Color Theory evidence while Surface resolves semantic colors. */
 export function createSurfaceColorDiagnosticCollector() {

package/src/{theme → features/theme/domain}/createSurfaceSemanticPolicy.ts

@@ -8,13 +8,13 @@ import type {
 } from '@ankhorage/color-theory';
 import { parseHexColorOrThrow } from '@ankhorage/color-theory';
 
-import { SURFACE_COLOR_POLICY } from './surfaceColorPolicy';
 import type {
   ContentSemantics,
   NeutralSemantics,
   SurfaceContrastDiagnostic,
   SurfaceSemantics,
-} from './types';
+} from '../../../types/theme';
+import { SURFACE_COLOR_POLICY } from '../constants';
 
 type ResolvedSemanticColors = Record<SemanticColorToken, HexColor>;
 

package/src/features/theme/domain/generatePalette.test.ts

@@ -0,0 +1,294 @@
+import type { SemanticColorToken } from '@ankhorage/color-theory';
+import {
+  COLOR_HARMONIES,
+  DARK_SEMANTIC_COLOR_REFERENCES,
+  DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS,
+  LIGHT_SEMANTIC_COLOR_REFERENCES,
+} from '@ankhorage/color-theory';
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { isRecord, readOwnProperty } from '@ankhorage/utility/object';
+import { expect, it } from 'bun:test';
+
+import { generatePalette } from './generatePalette';
+import { resolveSemanticColors } from './resolveSemanticColors';
+
+const mockConfig: ThemeConfig = {
+  id: 'test',
+  name: 'Test Theme',
+  light: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+  },
+  dark: {
+    primaryColor: '#3B82F6',
+    harmony: 'triadic',
+  },
+};
+
+function expectCompleteSemanticValues(value: unknown): void {
+  if (typeof value === 'string') {
+    expect(value.length).toBeGreaterThan(0);
+    return;
+  }
+  if (!isRecord(value)) return;
+  Object.values(value).forEach(expectCompleteSemanticValues);
+}
+
+it('generates a valid palette for light mode', () => {
+  const { colors, swatches, semantics } = generatePalette(mockConfig, 'light');
+
+  expect(colors.primary).toBeDefined();
+  expect(swatches.primary).toBeDefined();
+  expect(swatches.neutral).toBeDefined();
+  expect(Object.keys(swatches.primary)).toHaveLength(11);
+  expect(Object.keys(swatches.neutral)).toHaveLength(11);
+
+  // Surface semantic aliases
+  expect(semantics.surface.default).toBe(semantics.neutral.surface);
+  expect(semantics.content.muted).toBe(semantics.neutral.textMuted);
+  expect(semantics.border.focus).toBe(semantics.brand.outline);
+  expect(semantics.action.primary.base).toBe(semantics.brand.base);
+  expect(semantics.action.danger.base).toBe(semantics.danger.base);
+
+  // Surface runtime semantic aliases derived from ordinal swatches
+  expect(semantics.accent.base).toBeDefined();
+  expect(semantics.highlight.base).toBeDefined();
+  // accent/highlight are Surface semantic aliases (tertiary/quaternary fallback to primary when absent)
+  expect(semantics.accent.base).toBe(colors.accent);
+  expect(semantics.highlight.base).toBe(colors.highlight);
+});
+
+it('generates a valid palette for dark mode', () => {
+  const { colors, swatches, semantics } = generatePalette(mockConfig, 'dark');
+
+  expect(colors.background).toBe(semantics.neutral.bg);
+  expect(semantics.surface.inverse).toBe(swatches.neutral[50]);
+  expect(semantics.content.inverse).toBe(swatches.neutral[900]);
+});
+
+it('uses the Color Theory status owner independently from brand harmony', () => {
+  const statusConfig: ThemeConfig = {
+    ...mockConfig,
+    light: { primaryColor: '#dc2626', harmony: 'monochromatic' },
+    dark: { primaryColor: '#dc2626', harmony: 'monochromatic' },
+  };
+  const light = generatePalette(statusConfig, 'light');
+  const dark = generatePalette(statusConfig, 'dark');
+
+  expect(light.semantics.danger.base).toBe('#ef4444');
+  expect(light.semantics.success.base).toBe('#22c55e');
+  expect(light.semantics.warning.base).toBe('#f59e0b');
+  expect(light.semantics.error.base).toBe(light.semantics.danger.base);
+  expect(light.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
+  expect(light.semantics.info.base).not.toBe(light.semantics.brand.base);
+
+  expect(dark.semantics.danger.base).toBe('#ef4444');
+  expect(dark.semantics.success.base).toBe('#22c55e');
+  expect(dark.semantics.warning.base).toBe('#f59e0b');
+  expect(dark.semantics.error.base).toBe(dark.semantics.danger.base);
+  expect(dark.semantics.info.base).toBe(DEFAULT_SEMANTIC_STATUS_COLOR_SEEDS.info);
+  expect(dark.semantics.info.base).not.toBe(dark.semantics.brand.base);
+  expect(light.semantics.error).toBe(light.semantics.danger);
+  expect(dark.semantics.error).toBe(dark.semantics.danger);
+});
+
+it('uses mode-aware role semantics for dark mode soft states', () => {
+  const light = generatePalette(mockConfig, 'light');
+  const dark = generatePalette(mockConfig, 'dark');
+
+  expect(light.semantics.brand.softBg).toBe(light.swatches.primary[100]);
+  expect(light.semantics.brand.softHover).toBe(light.swatches.primary[200]);
+  expect(light.semantics.brand.softActive).toBe(light.swatches.primary[300]);
+  expect(dark.semantics.brand.softBg).toBe(dark.swatches.primary[900]);
+  expect(dark.semantics.brand.softHover).toBe(dark.swatches.primary[800]);
+  expect(dark.semantics.brand.softActive).toBe(dark.swatches.primary[700]);
+});
+
+it('preserves the primary color at swatch step 500 in light mode', () => {
+  const { swatches } = generatePalette(mockConfig, 'light');
+  expect(String(swatches.primary[500])).toBe(mockConfig.light.primaryColor);
+});
+
+it('preserves the primary color at swatch step 500 in dark mode', () => {
+  const { swatches } = generatePalette(mockConfig, 'dark');
+  expect(String(swatches.primary[500])).toBe(mockConfig.dark.primaryColor);
+});
+
+it('provides a neutral swatch with neutralKeyColor at step 500', () => {
+  const { swatches } = generatePalette(mockConfig, 'light');
+  // neutral swatch must have a step 500 entry
+  expect(swatches.neutral[500]).toBeDefined();
+});
+
+it('throws deterministically on invalid primary color', () => {
+  const config = {
+    ...mockConfig,
+    light: { ...mockConfig.light, primaryColor: 'not-a-hex-color' },
+  };
+  expect(() => generatePalette(config, 'light')).toThrow();
+});
+
+it('throws deterministically on invalid primary color in dark mode', () => {
+  const config = {
+    ...mockConfig,
+    dark: { ...mockConfig.dark, primaryColor: 'rgb(0,0,0)' },
+  };
+  expect(() => generatePalette(config, 'dark')).toThrow();
+});
+
+it('emits required semantic roles for all harmonies', () => {
+  for (const harmony of COLOR_HARMONIES) {
+    const config = {
+      ...mockConfig,
+      light: { ...mockConfig.light, harmony },
+      dark: { ...mockConfig.dark, harmony },
+    };
+    const light = generatePalette(config, 'light');
+    const dark = generatePalette(config, 'dark');
+    expectCompleteSemanticValues(light.semantics);
+    expectCompleteSemanticValues(dark.semantics);
+  }
+});
+
+it('resolves canonical semantic references and returns their selected steps', () => {
+  const light = generatePalette(mockConfig, 'light');
+  const dark = generatePalette(mockConfig, 'dark');
+
+  expect(light.colorDiagnostics.semanticReferences).toBe(LIGHT_SEMANTIC_COLOR_REFERENCES);
+  expect(dark.colorDiagnostics.semanticReferences).toBe(DARK_SEMANTIC_COLOR_REFERENCES);
+  expect(light.colorDiagnostics.generated.swatches).toBe(light.swatches);
+  expect(dark.colorDiagnostics.generated.swatches).toBe(dark.swatches);
+});
+
+it('returns measured selections and contrast diagnostics for both modes', () => {
+  for (const mode of ['light', 'dark'] as const) {
+    const palette = generatePalette(mockConfig, mode);
+
+    expect(palette.colorDiagnostics.selections.length).toBeGreaterThan(0);
+    expect(
+      palette.colorDiagnostics.selections.every(({ result }) => result.selected !== null),
+    ).toBe(true);
+    expect(palette.colorDiagnostics.contrasts.length).toBeGreaterThan(0);
+    expect(palette.colorDiagnostics.contrasts.every(({ passes }) => passes)).toBe(true);
+    expect(palette.colorDiagnostics.surfaceSeparation.length).toBeGreaterThan(0);
+  }
+});
+
+it('reports neutral and surface-separation evidence without hiding failed separation', () => {
+  const palette = generatePalette(mockConfig, 'light');
+  const failedSeparation = palette.colorDiagnostics.surfaceSeparation.find(({ passes }) => !passes);
+
+  expect(palette.colorDiagnostics.generated.neutral.neutralKeyColor).toBe(
+    palette.swatches.neutral[500],
+  );
+  expect(palette.colorDiagnostics.generated.neutral.diagnostics.isUsable).toBeBoolean();
+  expect(failedSeparation).toBeDefined();
+  expect(failedSeparation?.contrast).toBeLessThan(failedSeparation?.minimumContrast ?? 0);
+});
+
+it('preserves owner diagnostics for achromatic and low-chroma inputs', () => {
+  const achromaticConfig: ThemeConfig = {
+    ...mockConfig,
+    light: { primaryColor: '#777777', harmony: 'square' },
+  };
+  const palette = generatePalette(achromaticConfig, 'light');
+
+  expect(palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.isHueReliable).toBe(
+    false,
+  );
+  expect(
+    palette.colorDiagnostics.generated.harmonyRoleColors.diagnostics.warnings.length,
+  ).toBeGreaterThan(0);
+  expect(palette.colorDiagnostics.generated.neutral.diagnostics).toBeDefined();
+});
+
+it('generates ordinal chromatic role swatches (no accent/highlight as swatch keys)', () => {
+  const { swatches } = generatePalette(mockConfig, 'light');
+  const keys = Object.keys(swatches);
+  expect(keys).not.toContain('accent');
+  expect(keys).not.toContain('highlight');
+  expect(keys).not.toContain('surfaceTint');
+  expect(keys).not.toContain('base');
+  // ordinal roles are present
+  expect(keys).toContain('primary');
+  expect(keys).toContain('neutral');
+});
+
+it('semantic resolver maps all SemanticColorToken entries for light mode', () => {
+  const { swatches } = generatePalette(mockConfig, 'light');
+  // Build a minimal GeneratedThemeModeColors for resolver testing
+  const generated = {
+    harmonyRoleColors: {} as never,
+    swatches,
+    neutral: { neutralKeyColor: swatches.neutral[500], diagnostics: {} as never },
+  };
+  const resolved = resolveSemanticColors(generated, LIGHT_SEMANTIC_COLOR_REFERENCES);
+  const tokens: SemanticColorToken[] = [
+    'background',
+    'surface',
+    'surfaceRaised',
+    'border',
+    'divider',
+    'text',
+    'textMuted',
+    'disabledBg',
+    'disabledText',
+    'brand',
+    'brandEmphasis',
+    'action',
+    'actionEmphasis',
+  ];
+  for (const token of tokens) {
+    expect(readOwnProperty(resolved, token)).toBeDefined();
+    expect(typeof readOwnProperty(resolved, token)).toBe('string');
+  }
+});
+
+it('semantic resolver maps all SemanticColorToken entries for dark mode', () => {
+  const { swatches } = generatePalette(mockConfig, 'dark');
+  const generated = {
+    harmonyRoleColors: {} as never,
+    swatches,
+    neutral: { neutralKeyColor: swatches.neutral[500], diagnostics: {} as never },
+  };
+  const resolved = resolveSemanticColors(generated, DARK_SEMANTIC_COLOR_REFERENCES);
+  const tokens: SemanticColorToken[] = [
+    'background',
+    'surface',
+    'surfaceRaised',
+    'border',
+    'divider',
+    'text',
+    'textMuted',
+    'disabledBg',
+    'disabledText',
+    'brand',
+    'brandEmphasis',
+    'action',
+    'actionEmphasis',
+  ];
+  for (const token of tokens) {
+    expect(readOwnProperty(resolved, token)).toBeDefined();
+  }
+});
+
+it('neutral semantics power backgrounds, borders, text in light mode', () => {
+  const { semantics } = generatePalette(mockConfig, 'light');
+  expect(semantics.neutral.bg).toBeDefined();
+  expect(semantics.neutral.bgSubtle).toBeDefined();
+  expect(semantics.neutral.surface).toBeDefined();
+  expect(semantics.neutral.surfaceHover).toBeDefined();
+  expect(semantics.neutral.border).toBeDefined();
+  expect(semantics.neutral.borderStrong).toBeDefined();
+  expect(semantics.neutral.divider).toBeDefined();
+  expect(semantics.neutral.text).toBeDefined();
+  expect(semantics.neutral.textMuted).toBeDefined();
+  expect(semantics.neutral.textSubtle).toBeDefined();
+});
+
+it('readable foregrounds are generated for brand base in both modes', () => {
+  const light = generatePalette(mockConfig, 'light');
+  const dark = generatePalette(mockConfig, 'dark');
+  expect(light.semantics.brand.onSolidText).toMatch(/^#/);
+  expect(dark.semantics.brand.onSolidText).toMatch(/^#/);
+});

package/src/{theme/colorEngine.ts → features/theme/domain/generatePalette.ts}

@@ -1,11 +1,4 @@
-import type {
-  GeneratedThemeModeColors,
-  GeneratedThemeSwatches,
-  HexColor,
-  SemanticColorReferenceMap,
-  SemanticColorToken,
-  ThemeColorMode,
-} from '@ankhorage/color-theory';
+import type { GeneratedThemeSwatches, ThemeColorMode } from '@ankhorage/color-theory';
 import {
   DARK_SEMANTIC_COLOR_REFERENCES,
   generateThemeModeColors,
@@ -14,29 +7,9 @@ import {
 } from '@ankhorage/color-theory';
 import type { ThemeConfig } from '@ankhorage/contracts';
 
+import type { SurfaceColorDiagnostics, ThemeSemantics, ThemeTokens } from '../../../types/theme';
+import { resolveSemanticColors } from './resolveSemanticColors';
 import { resolveSurfaceSemanticModel } from './resolveSurfaceSemanticModel';
-import type { SurfaceColorDiagnostics, ThemeSemantics, ThemeTokens } from './types';
-
-/**
- * Surface semantic resolver: maps color-theory SemanticColorToken references
- * to hex values from the generated swatches.
- */
-export type SurfaceSemanticColors = Record<SemanticColorToken, HexColor>;
-
-export function resolveSemanticColors(
-  generated: GeneratedThemeModeColors,
-  references: SemanticColorReferenceMap,
-): SurfaceSemanticColors {
-  return Object.fromEntries(
-    Object.entries(references).map(([token, ref]) => {
-      const swatch = generated.swatches[ref.role];
-      if (!swatch) {
-        throw new Error(`Missing swatch for role '${ref.role}' (token: '${token}')`);
-      }
-      return [token, swatch[ref.step]];
-    }),
-  ) as SurfaceSemanticColors;
-}
 
 export function generatePalette(
   config: ThemeConfig,

package/src/{theme → features/theme/domain}/inverseSemantics.test.ts

@@ -1,7 +1,7 @@
 import type { ThemeConfig } from '@ankhorage/contracts';
 import { describe, expect, it } from 'bun:test';
 
-import { generatePalette } from './colorEngine';
+import { generatePalette } from './generatePalette';
 
 const config: ThemeConfig = {
   id: 'inverse-semantics-test',

package/src/{theme → features/theme/domain}/resolveRoleSemantics.ts

@@ -1,7 +1,7 @@
 import type { ColorSwatch, HexColor } from '@ankhorage/color-theory';
 
-import { SURFACE_COLOR_POLICY } from './surfaceColorPolicy';
-import type { RoleSemantics } from './types';
+import type { RoleSemantics } from '../../../types/theme';
+import { SURFACE_COLOR_POLICY } from '../constants';
 
 interface ResolveRoleSemanticsInput {
   base?: HexColor;

package/src/features/theme/domain/resolveSemanticColors.ts

@@ -0,0 +1,23 @@
+import type {
+  GeneratedThemeModeColors,
+  HexColor,
+  SemanticColorReferenceMap,
+  SemanticColorToken,
+} from '@ankhorage/color-theory';
+
+export type SurfaceSemanticColors = Record<SemanticColorToken, HexColor>;
+
+export function resolveSemanticColors(
+  generated: GeneratedThemeModeColors,
+  references: SemanticColorReferenceMap,
+): SurfaceSemanticColors {
+  return Object.fromEntries(
+    Object.entries(references).map(([token, ref]) => {
+      const swatch = generated.swatches[ref.role];
+      if (!swatch) {
+        throw new Error(`Missing swatch for role '${ref.role}' (token: '${token}')`);
+      }
+      return [token, swatch[ref.step]];
+    }),
+  ) as SurfaceSemanticColors;
+}

package/src/{theme → features/theme/domain}/resolveSurfaceSemanticModel.ts

@@ -10,16 +10,16 @@ import type {
 } from '@ankhorage/color-theory';
 import { createDefaultSemanticStatusSwatches } from '@ankhorage/color-theory';
 
-import { createSurfaceColorDiagnosticCollector } from './createSurfaceColorDiagnosticCollector';
-import { createSurfaceSemanticPolicy } from './createSurfaceSemanticPolicy';
-import { resolveRoleSemantics } from './resolveRoleSemantics';
 import type {
   BorderSemantics,
   ContentSemantics,
   RoleSemantics,
   SurfaceColorDiagnostics,
   ThemeSemantics,
-} from './types';
+} from '../../../types/theme';
+import { createSurfaceColorDiagnosticCollector } from './createSurfaceColorDiagnosticCollector';
+import { createSurfaceSemanticPolicy } from './createSurfaceSemanticPolicy';
+import { resolveRoleSemantics } from './resolveRoleSemantics';
 
 type ResolvedSemanticColors = Record<SemanticColorToken, HexColor>;
 

package/src/{theme → features/theme}/public.test.ts

@@ -17,7 +17,7 @@ describe('public theme subpath', () => {
 
     expect(source).not.toContain('ThemeContext');
     expect(source).not.toMatch(/from ['"]react(?:-native)?['"]/);
-    expect(source).toContain("export * from './createTheme';");
+    expect(source).toContain("export { createTheme } from './application/use-cases/createTheme';");
   });
 
   test('imports and executes through the package subpath in plain Bun', async () => {

package/src/features/theme/public.ts

@@ -0,0 +1,18 @@
+export type {
+  ActionSemantics,
+  BorderSemantics,
+  ContentSemantics,
+  FontWeight,
+  NeutralSemantics,
+  RoleSemantics,
+  SelectionSemantics,
+  SurfaceColorDiagnostics,
+  SurfaceColorSelectionDiagnostic,
+  SurfaceContrastDiagnostic,
+  SurfaceSemantics,
+  SurfaceTheme,
+  ThemeMode,
+  ThemeSemantics,
+  ThemeTokens,
+} from '../../types/theme';
+export { createTheme } from './application/use-cases/createTheme';

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

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'bun:test';
+
+describe('theme runtime ownership', () => {
+  it('keeps nested scopes on the Surface runtime boundary without exposing raw context', () => {
+    const root = readFileSync(new URL('../../index.ts', import.meta.url), 'utf8');
+    const runtime = readFileSync(new URL('./runtime.ts', import.meta.url), 'utf8');
+    expect(root).toContain('ThemeProvider, ThemeScope, useTheme');
+    expect(root).not.toContain('ThemeContext');
+    expect(runtime).not.toContain('ThemeRuntimeContext');
+  });
+});

package/src/features/theme/runtime.ts

@@ -0,0 +1,4 @@
+export type { ThemeProviderProps, ThemeRuntime, ThemeScopeProps } from '../../types/theme';
+export { ThemeProvider } from './adapters/inbound/ThemeProvider';
+export { ThemeScope } from './adapters/inbound/ThemeScope';
+export { useTheme } from './adapters/inbound/useTheme';

package/src/{theme → features/theme/utils}/resolveGlobalTokens.ts

@@ -1,10 +1,10 @@
 import type { ThemeGlobalTokenOverrides } from '@ankhorage/contracts';
 
-import { DEFAULT_TOKENS } from './defaultTokens';
+import type { ThemeTokens } from '../../../types/theme';
+import { DEFAULT_TOKENS } from '../constants';
 import { resolveHeadingTokenOverrides } from './resolveHeadingTokenOverrides';
 import { resolveNumericTokenOverrides } from './resolveNumericTokenOverrides';
 import { resolveWeightTokenOverrides } from './resolveWeightTokenOverrides';
-import type { ThemeTokens } from './types';
 
 type GlobalThemeTokens = Omit<
   ThemeTokens,

package/src/{theme → features/theme/utils}/resolveHeadingTokenOverrides.ts

@@ -1,6 +1,6 @@
 import type { ThemeTypographyHeadingOverrides } from '@ankhorage/contracts';
 
-import type { ThemeTokens } from './types';
+import type { ThemeTokens } from '../../../types/theme';
 
 type HeadingTokens = ThemeTokens['typography']['headings'];
 type HeadingToken = HeadingTokens[1];

package/src/features/theme/utils/resolveToken.ts

@@ -0,0 +1,16 @@
+/*** Resolve a theme token key through its map while preserving raw values. */
+type ResolvedToken<TMap, TValue> = TValue extends keyof TMap ? TMap[TValue] : TValue;
+
+/*** Resolve a mapped theme token or return the supplied raw value unchanged. */
+export function resolveToken<
+  TMap extends Record<string | number, unknown>,
+  TValue extends string | number | undefined,
+>(map: TMap, value: TValue): ResolvedToken<TMap, TValue> {
+  if (value === undefined) return undefined as ResolvedToken<TMap, TValue>;
+
+  if (Object.prototype.hasOwnProperty.call(map, value)) {
+    return map[value as keyof TMap] as ResolvedToken<TMap, TValue>;
+  }
+
+  return value as ResolvedToken<TMap, TValue>;
+}