@ankhorage/zora 2.11.0 → 2.13.0

package/src/metadata/themeRecipeMeta.test.ts

@@ -3,65 +3,67 @@ import { describe, expect, test } from 'bun:test';
 import { ZORA_COMPONENT_META, ZORA_THEME_RECIPE_META, ZORA_THEME_TOKEN_FAMILIES } from './index';
 
 const tokenFamilies = new Set<string>(ZORA_THEME_TOKEN_FAMILIES);
-const expectedKinds = new Map<string, 'component' | 'pattern'>([
-  ['Button', 'component'],
-  ['Card', 'component'],
-  ['Text', 'component'],
-  ['Panel', 'pattern'],
-]);
+const recipeMetaByName = new Map(Object.entries(ZORA_THEME_RECIPE_META));
 
 describe('ZORA_THEME_RECIPE_META', () => {
-  test('exports representative component and pattern recipes', () => {
-    expect(Object.keys(ZORA_THEME_RECIPE_META)).toEqual(['Button', 'Card', 'Text', 'Panel']);
-    expect(ZORA_THEME_RECIPE_META.Button?.kind).toBe('component');
-    expect(ZORA_THEME_RECIPE_META.Panel?.kind).toBe('pattern');
-  });
+  test('exports every current component/pattern theme-authority recipe', () => {
+    expect(Object.keys(ZORA_THEME_RECIPE_META)).toEqual([
+      'Button',
+      'Card',
+      'Heading',
+      'Text',
+      'Panel',
+    ]);
 
-  test('keeps registry names unique and aligned with component metadata', () => {
-    const names = Object.values(ZORA_THEME_RECIPE_META).map((meta) => meta.name);
-    expect(new Set(names).size).toBe(names.length);
+    for (const [name, componentMeta] of Object.entries(ZORA_COMPONENT_META)) {
+      const themeProps = Object.entries(componentMeta.props).filter(
+        ([, prop]) => prop.authoring?.authority === 'theme' && prop.authoring.scope !== 'global',
+      );
+      if (themeProps.length === 0) continue;
 
-    for (const [key, meta] of Object.entries(ZORA_THEME_RECIPE_META)) {
-      expect(meta.name).toBe(key);
-      expect(meta.kind).toBe(expectedKinds.get(key));
+      const recipe = recipeMetaByName.get(name);
+      expect(recipe, `${name} has theme props but no theme recipe`).toBeDefined();
+      expect(recipe?.kind).toBe(componentMeta.category === 'pattern' ? 'pattern' : 'component');
+      const fields = new Map(Object.entries(recipe?.fields ?? {}));
+      for (const [propName] of themeProps) {
+        expect(
+          fields.get(propName),
+          `${name}.${propName} is missing from its recipe`,
+        ).toBeDefined();
+      }
     }
-
-    expect(ZORA_COMPONENT_META.Button.category).toBe('component');
-    expect(ZORA_COMPONENT_META.Card.category).toBe('component');
-    expect(ZORA_COMPONENT_META.Text.category).toBe('component');
-    expect(ZORA_COMPONENT_META.Panel.category).toBe('pattern');
   });
 
-  test('references only canonical token families and valid choice defaults', () => {
+  test('references only canonical token families and valid declared defaults', () => {
     for (const meta of Object.values(ZORA_THEME_RECIPE_META)) {
       for (const field of Object.values(meta.fields)) {
         if (field.type === 'token') {
           expect(tokenFamilies.has(field.tokenFamily), `${meta.name}.${field.label}`).toBe(true);
         }
-        if (field.type === 'choice') {
+        if (field.type === 'choice' && field.default !== undefined) {
           expect(field.options).toContain(field.default);
         }
       }
     }
   });
 
-  test('describes component-specific semantic scales instead of universal geometry', () => {
-    expect(ZORA_THEME_RECIPE_META.Button?.fields.size).toMatchObject({
-      type: 'choice',
-      options: ['s', 'm', 'l'],
-      default: 'm',
-    });
-    expect(ZORA_THEME_RECIPE_META.Card?.fields.padding).toMatchObject({
-      type: 'token',
-      tokenFamily: 'spacing',
-      default: 'l',
-    });
+  test('keeps recipe defaults aligned with existing runtime behavior', () => {
+    expect(ZORA_THEME_RECIPE_META.Button?.fields.size?.default).toBe('l');
+    expect(ZORA_THEME_RECIPE_META.Card?.fields.padding?.default).toBeUndefined();
+    expect(ZORA_THEME_RECIPE_META.Text?.fields.weight?.default).toBeUndefined();
+    expect(ZORA_THEME_RECIPE_META.Heading?.fields.size?.default).toBeUndefined();
   });
 
-  test('stays distinct from component metadata', () => {
-    expect(ZORA_THEME_RECIPE_META).not.toBe(ZORA_COMPONENT_META);
-    expect(ZORA_COMPONENT_META.Button.props.size?.type).toBe('enum');
-    expect(ZORA_THEME_RECIPE_META.Button?.fields.size?.type).toBe('choice');
+  test('does not persist theme-owned defaults into new instance blueprints', () => {
+    for (const [name, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      const props = new Map(Object.entries(meta.props));
+      for (const propName of Object.keys(meta.blueprint?.defaultProps ?? {})) {
+        expect(
+          props.get(propName)?.authoring?.authority,
+          `${name}.${propName} blueprint must not pin a theme-owned value`,
+        ).not.toBe('theme');
+      }
+    }
   });
 
   test('is serializable for downstream authoring consumers', () => {

package/src/metadata/themeRecipeMeta.ts

@@ -1,5 +1,6 @@
 import { buttonThemeRecipeMeta } from '../components/button/themeRecipeMeta';
 import { cardThemeRecipeMeta } from '../components/card/themeRecipeMeta';
+import { headingThemeRecipeMeta } from '../components/heading/themeRecipeMeta';
 import { textThemeRecipeMeta } from '../components/text/themeRecipeMeta';
 import { panelThemeRecipeMeta } from '../patterns/panel/themeRecipeMeta';
 import type { ZoraThemeRecipeMetaRegistry } from './themeRecipeTypes';
@@ -7,6 +8,7 @@ import type { ZoraThemeRecipeMetaRegistry } from './themeRecipeTypes';
 export const ZORA_THEME_RECIPE_META: ZoraThemeRecipeMetaRegistry = {
   Button: buttonThemeRecipeMeta,
   Card: cardThemeRecipeMeta,
+  Heading: headingThemeRecipeMeta,
   Text: textThemeRecipeMeta,
   Panel: panelThemeRecipeMeta,
 };

package/src/metadata/themeRecipeTypes.ts

@@ -18,18 +18,18 @@ interface ZoraThemeRecipeFieldBase {
 export interface ZoraThemeRecipeTokenFieldMeta extends ZoraThemeRecipeFieldBase {
   readonly type: 'token';
   readonly tokenFamily: ZoraThemeTokenFamily;
-  readonly default: string;
+  readonly default?: string;
 }
 
 export interface ZoraThemeRecipeChoiceFieldMeta extends ZoraThemeRecipeFieldBase {
   readonly type: 'choice';
   readonly options: readonly string[];
-  readonly default: string;
+  readonly default?: string;
 }
 
 export interface ZoraThemeRecipeBooleanFieldMeta extends ZoraThemeRecipeFieldBase {
   readonly type: 'boolean';
-  readonly default: boolean;
+  readonly default?: boolean;
 }
 
 export type ZoraThemeRecipeFieldMeta =

package/src/metadata/types.ts

@@ -1,21 +1,13 @@
-import type { ComponentEventDtoKind, ComponentRequirements } from '@ankhorage/contracts';
+import type {
+  ComponentEventDtoKind,
+  ComponentRequirements,
+  MediaAssetKind,
+  UiComponentPropType,
+} from '@ankhorage/contracts';
 
 export type ZoraComponentCategory = 'foundation' | 'component' | 'pattern' | 'layout';
 
-export type ZoraComponentPropType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'enum'
-  | 'color'
-  | 'spacing'
-  | 'radius'
-  | 'shadow'
-  | 'typographySize'
-  | 'typographyWeight'
-  | 'action'
-  | 'imageAsset'
-  | 'array';
+export type ZoraComponentPropType = UiComponentPropType;
 
 export type ZoraComponentPropValue =
   | string
@@ -30,6 +22,7 @@ export type ZoraComponentPropAuthoring =
   | {
       readonly authority: 'theme';
       readonly scope: 'global' | 'component' | 'pattern';
+      readonly allowInstanceOverride?: boolean;
     };
 
 export interface ZoraComponentPropArrayItemSchema {
@@ -44,27 +37,21 @@ export interface ZoraComponentPropSchema {
   enum?: readonly (string | number)[];
   default?: ZoraComponentPropValue;
   itemSchema?: readonly ZoraComponentPropArrayItemSchema[];
+  mediaKinds?: readonly MediaAssetKind[];
   authoring?: ZoraComponentPropAuthoring;
 }
 
 export interface ZoraComponentBlueprint {
   label: string;
-  icon?: {
-    name: string;
-    provider?: string;
-  };
+  icon?: { name: string; provider?: string };
   defaultProps?: Readonly<Record<string, ZoraComponentPropValue>>;
 }
 
 export interface ZoraComponentI18nMeta {
-  fields: readonly {
-    keyProp: string;
-    defaultTextProp: string;
-  }[];
+  fields: readonly { keyProp: string; defaultTextProp: string }[];
 }
 
 export type ZoraComponentEventPayloadKind = ComponentEventDtoKind | (string & {});
-
 export type ZoraComponentEventPayloadFieldType =
   | 'boolean'
   | 'number'

package/src/patterns/panel/Panel.tsx

@@ -1,16 +1,26 @@
 import React from 'react';
 
 import { Card } from '../../components/card';
+import { resolveCardThemeRecipe } from '../../components/card/resolveCardThemeRecipe';
+import { useZoraThemeRecipe } from '../../theme/useZoraThemeRecipe';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
 import type { PanelProps } from './types';
 
-function PanelInner({ themeId: _themeId, mode: _mode, ...props }: PanelProps) {
-  return <Card {...props} />;
+function PanelInner({
+  themeId: _themeId,
+  mode: _mode,
+  tone,
+  compact,
+  padding,
+  radius,
+  ...props
+}: PanelProps) {
+  const themeFields = useZoraThemeRecipe('Panel');
+  const recipe = resolveCardThemeRecipe({ tone, compact, padding, radius, themeFields });
+  return <Card {...props} {...recipe} />;
 }
 
 /***
  * Semantic wrapper around `Card` for panel-style page sections.
- *
- 
  */
 export const Panel = withZoraThemeScope(PanelInner);

package/src/patterns/panel/meta.ts

@@ -1,18 +1,18 @@
 import type { ZoraComponentMeta } from '../../metadata';
 import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
 
+const themeAuthoring = {
+  authority: 'theme',
+  scope: 'pattern',
+  allowInstanceOverride: true,
+} as const;
+
 export const panelMeta = {
   name: 'Panel',
   category: 'pattern',
   directManifestNode: true,
   allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
-  blueprint: {
-    label: 'Panel',
-    defaultProps: {
-      title: 'Panel',
-      tone: 'default',
-    },
-  },
+  blueprint: { label: 'Panel', defaultProps: { title: 'Panel' } },
   props: {
     title: {
       type: 'string',
@@ -37,15 +37,15 @@ export const panelMeta = {
       category: 'Style',
       label: 'Tone',
       enum: ['default', 'subtle', 'outline'],
-      default: 'default',
-      authoring: { authority: 'theme', scope: 'pattern' },
+      authoring: themeAuthoring,
     },
-    compact: {
-      type: 'boolean',
-      category: 'Layout',
-      label: 'Compact',
-      default: false,
-      authoring: { authority: 'theme', scope: 'pattern' },
+    compact: { type: 'boolean', category: 'Layout', label: 'Compact', authoring: themeAuthoring },
+    padding: { type: 'spacing', category: 'Layout', label: 'Padding', authoring: themeAuthoring },
+    radius: {
+      type: 'radius',
+      category: 'Style',
+      label: 'Corner radius',
+      authoring: themeAuthoring,
     },
   },
 } as const satisfies ZoraComponentMeta;

package/src/patterns/panel/themeRecipeMeta.ts

@@ -15,7 +15,7 @@ export const panelThemeRecipeMeta = {
       type: 'token',
       tokenFamily: 'spacing',
       label: 'Padding',
-      default: 'l',
+      description: 'When unset, Panel keeps Card compact-aware spacing.',
     },
     radius: {
       type: 'token',

package/src/patterns/panel/types.ts

@@ -12,4 +12,6 @@ export interface PanelProps extends ZoraBaseProps {
   children?: React.ReactNode;
   tone?: ZoraCardTone;
   compact?: boolean;
+  padding?: string;
+  radius?: string;
 }

package/src/theme/ZoraProvider.tsx

@@ -1,3 +1,4 @@
+import type { ThemeConfig } from '@ankhorage/contracts';
 import { ThemeProvider } from '@ankhorage/surface';
 import React from 'react';
 
@@ -9,30 +10,26 @@ import { ZoraThemeRuntimeContext } from './ZoraThemeRuntimeContext';
 export interface ZoraProviderProps {
   children: React.ReactNode;
   theme?: ZoraTheme;
+  themeConfig?: ThemeConfig;
   initialMode?: ZoraThemeMode;
 }
 
-/***
- * Installs the ZORA theme runtime and underlying Surface theme provider.
- *
- * Wrap an app with `ZoraProvider` once near the root so components, patterns,
- * layouts, and theme hooks resolve the same design tokens and color mode.
- *
- * @example App provider
- * ```tsx
- * <ZoraProvider initialMode="light"><App /></ZoraProvider>
- * ```
- */
+/** Installs the ZORA theme runtime and underlying Surface theme provider. */
 export function ZoraProvider({
   children,
   theme = zoraDefaultTheme,
+  themeConfig,
   initialMode = 'light',
 }: ZoraProviderProps) {
-  const runtimeValue = React.useMemo(() => ({ sourceTheme: theme, themeId: theme.id }), [theme]);
+  const resolvedConfig = React.useMemo(
+    () => themeConfig ?? createZoraThemeConfig(theme),
+    [theme, themeConfig],
+  );
+  const runtimeValue = React.useMemo(() => ({ themeId: resolvedConfig.id }), [resolvedConfig.id]);
 
   return (
     <ZoraThemeRuntimeContext.Provider value={runtimeValue}>
-      <ThemeProvider initialConfig={createZoraThemeConfig(theme)} initialMode={initialMode}>
+      <ThemeProvider initialConfig={resolvedConfig} initialMode={initialMode}>
         {children}
       </ThemeProvider>
     </ZoraThemeRuntimeContext.Provider>

package/src/theme/ZoraThemeRuntimeContext.tsx

@@ -1,15 +1,13 @@
 import { createContext, useContext } from 'react';
 
-import type { ZoraTheme, ZoraThemeId } from './types';
+import type { ZoraThemeId } from './types';
 import { zoraDefaultTheme } from './zoraDefaultTheme';
 
 interface ZoraThemeRuntime {
-  sourceTheme: ZoraTheme;
   themeId: ZoraThemeId;
 }
 
 export const ZoraThemeRuntimeContext = createContext<ZoraThemeRuntime>({
-  sourceTheme: zoraDefaultTheme,
   themeId: zoraDefaultTheme.id,
 });
 

package/src/theme/ZoraThemeScope.tsx

@@ -1,7 +1,6 @@
 import { createTheme, ThemeContext, useFontContext, useTheme } from '@ankhorage/surface';
 import React, { useMemo } from 'react';
 
-import { createZoraThemeConfig } from './createZoraThemeConfig';
 import { resolveZoraScopedThemeId } from './resolveZoraScopedThemeId';
 import type { ZoraThemeId, ZoraThemeMode } from './types';
 import { useZoraThemeRuntime, ZoraThemeRuntimeContext } from './ZoraThemeRuntimeContext';
@@ -16,25 +15,16 @@ function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
   const parentSurface = useTheme();
   const parentRuntime = useZoraThemeRuntime();
   const { activeFontId } = useFontContext();
-
   const scopedThemeId = resolveZoraScopedThemeId({
     desiredThemeId: themeId,
     inheritedThemeId: parentRuntime.themeId,
   });
-
   const scopedMode = mode ?? parentSurface.mode;
-
-  // Plan 2: there is no multi-theme registry yet. Keep the active theme seed inherited.
-  const surfaceConfig = useMemo(
-    () => createZoraThemeConfig(parentRuntime.sourceTheme),
-    [parentRuntime.sourceTheme],
-  );
-
+  const sourceConfig = parentSurface.theme.config;
   const scopedTheme = useMemo(
-    () => createTheme(surfaceConfig, scopedMode, activeFontId),
-    [surfaceConfig, scopedMode, activeFontId],
+    () => createTheme(sourceConfig, scopedMode, activeFontId),
+    [sourceConfig, scopedMode, activeFontId],
   );
-
   const scopedSurfaceValue = useMemo(
     () => ({
       theme: scopedTheme,
@@ -45,14 +35,7 @@ function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
     }),
     [parentSurface.setMode, parentSurface.setThemeConfig, scopedMode, scopedTheme],
   );
-
-  const scopedRuntimeValue = useMemo(
-    () => ({
-      sourceTheme: parentRuntime.sourceTheme,
-      themeId: scopedThemeId,
-    }),
-    [parentRuntime.sourceTheme, scopedThemeId],
-  );
+  const scopedRuntimeValue = useMemo(() => ({ themeId: scopedThemeId }), [scopedThemeId]);
 
   return (
     <ZoraThemeRuntimeContext.Provider value={scopedRuntimeValue}>
@@ -62,10 +45,7 @@ function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
 }
 
 export function ZoraThemeScope({ children, themeId, mode }: ZoraThemeScopeProps) {
-  if (mode === undefined && themeId === undefined) {
-    return children;
-  }
-
+  if (mode === undefined && themeId === undefined) return children;
   return (
     <ZoraThemeScopeInner mode={mode} themeId={themeId}>
       {children}

package/src/theme/resolveZoraThemeRecipe.test.ts

@@ -0,0 +1,72 @@
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { describe, expect, test } from 'bun:test';
+
+import { resolveZoraThemeRecipe } from './resolveZoraThemeRecipe';
+
+const baseConfig: ThemeConfig = {
+  id: 'test',
+  name: 'Test',
+  light: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
+  dark: { primaryColor: '#3B82F6', harmony: 'monochromatic' },
+  tokens: { spacing: { hero: 64 } },
+};
+
+function runtimeTheme(config: ThemeConfig) {
+  return {
+    config,
+    colors: { primary: '#3B82F6' },
+    spacing: { m: 16, l: 24, hero: 64 },
+    radii: { m: 8, l: 16 },
+    shadows: { soft: 2 },
+    typography: {
+      sizes: { m: 16 },
+      weights: { regular: '400' },
+      headings: { 1: { size: 32 } },
+    },
+  };
+}
+
+function withRecipes(recipes: ThemeConfig['recipes']): ThemeConfig {
+  return { ...baseConfig, recipes };
+}
+
+describe('resolveZoraThemeRecipe', () => {
+  test('merges metadata defaults with persisted known fields', () => {
+    const theme = runtimeTheme(
+      withRecipes({ components: { Card: { tone: 'outline', padding: 'hero' } } }),
+    );
+    expect(resolveZoraThemeRecipe(theme, 'Card')).toEqual({
+      tone: 'outline',
+      padding: 'hero',
+      radius: 'l',
+      compact: false,
+    });
+  });
+
+  test('ignores stale unknown persisted fields without guessing metadata', () => {
+    const theme = runtimeTheme(
+      withRecipes({ components: { Button: { variant: 'soft', retiredField: 'legacy' } } }),
+    );
+    expect(resolveZoraThemeRecipe(theme, 'Button')).toEqual({
+      color: 'primary',
+      variant: 'soft',
+      size: 'l',
+    });
+  });
+
+  test('rejects invalid known choices and token references', () => {
+    const choiceTheme = runtimeTheme(withRecipes({ components: { Button: { variant: 'neon' } } }));
+    expect(() => resolveZoraThemeRecipe(choiceTheme, 'Button')).toThrow(
+      'Invalid theme recipe choice',
+    );
+
+    const tokenTheme = runtimeTheme(withRecipes({ components: { Card: { padding: 'missing' } } }));
+    expect(() => resolveZoraThemeRecipe(tokenTheme, 'Card')).toThrow('Unknown spacing token');
+  });
+
+  test('rejects code requests for unknown recipe names', () => {
+    expect(() => resolveZoraThemeRecipe(runtimeTheme(baseConfig), 'Missing')).toThrow(
+      'Unknown ZORA theme recipe',
+    );
+  });
+});

package/src/theme/resolveZoraThemeRecipe.ts

@@ -0,0 +1,91 @@
+import type { ThemeConfig, ThemeRecipeOverrideValue } from '@ankhorage/contracts';
+
+import { ZORA_THEME_RECIPE_META } from '../metadata/themeRecipeMeta';
+import type { ZoraThemeRecipeFieldMeta, ZoraThemeTokenFamily } from '../metadata/themeRecipeTypes';
+
+interface ZoraThemeRecipeRuntimeTheme {
+  readonly config: ThemeConfig;
+  readonly colors: object;
+  readonly spacing: object;
+  readonly radii: object;
+  readonly shadows: object;
+  readonly typography: {
+    readonly sizes: object;
+    readonly weights: object;
+    readonly headings: object;
+  };
+}
+
+const recipeMetaByName = new Map(Object.entries(ZORA_THEME_RECIPE_META));
+
+export function resolveZoraThemeRecipe(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  recipeName: string,
+): Readonly<Record<string, ThemeRecipeOverrideValue>> {
+  const meta = recipeMetaByName.get(recipeName);
+  if (!meta) throw new RangeError(`Unknown ZORA theme recipe: ${recipeName}.`);
+
+  const recipes =
+    meta.kind === 'component' ? theme.config.recipes?.components : theme.config.recipes?.patterns;
+  const overrides = new Map(Object.entries(recipes ?? {})).get(recipeName);
+  const overrideByField = new Map(Object.entries(overrides ?? {}));
+  const resolved: [string, ThemeRecipeOverrideValue][] = [];
+
+  for (const [fieldName, fieldMeta] of Object.entries(meta.fields)) {
+    const override = overrideByField.get(fieldName);
+    if (override !== undefined) {
+      validateFieldValue(theme, recipeName, fieldName, fieldMeta, override);
+      resolved.push([fieldName, override]);
+    } else if (fieldMeta.default !== undefined) {
+      resolved.push([fieldName, fieldMeta.default]);
+    }
+  }
+
+  return Object.fromEntries(resolved);
+}
+
+function validateFieldValue(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  recipeName: string,
+  fieldName: string,
+  meta: ZoraThemeRecipeFieldMeta,
+  value: ThemeRecipeOverrideValue,
+): void {
+  if (meta.type === 'boolean') {
+    if (typeof value !== 'boolean') {
+      throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be boolean.`);
+    }
+    return;
+  }
+  if (typeof value !== 'string') {
+    throw new TypeError(`Theme recipe ${recipeName}.${fieldName} must be a string.`);
+  }
+  if (meta.type === 'choice' && !meta.options.includes(value)) {
+    throw new RangeError(`Invalid theme recipe choice for ${recipeName}.${fieldName}: ${value}.`);
+  }
+  if (meta.type === 'token' && !hasThemeToken(theme, meta.tokenFamily, value)) {
+    throw new RangeError(
+      `Unknown ${meta.tokenFamily} token for ${recipeName}.${fieldName}: ${value}.`,
+    );
+  }
+}
+
+function hasThemeToken(
+  theme: ZoraThemeRecipeRuntimeTheme,
+  family: ZoraThemeTokenFamily,
+  token: string,
+): boolean {
+  if (family === 'colors') return hasOwn(theme.colors, token);
+  if (family === 'spacing') return hasOwn(theme.spacing, token);
+  if (family === 'radii') return hasOwn(theme.radii, token);
+  if (family === 'shadows') return hasOwn(theme.shadows, token);
+  return (
+    hasOwn(theme.typography.sizes, token) ||
+    hasOwn(theme.typography.weights, token) ||
+    hasOwn(theme.typography.headings, token)
+  );
+}
+
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}

package/src/theme/themeConfigScope.test.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+const themeDir = import.meta.dir;
+
+describe('canonical ThemeConfig scope propagation', () => {
+  test('provider accepts the canonical ThemeConfig without duplicating live config state', () => {
+    const provider = readFileSync(join(themeDir, 'ZoraProvider.tsx'), 'utf8');
+    const context = readFileSync(join(themeDir, 'ZoraThemeRuntimeContext.tsx'), 'utf8');
+    expect(provider).toContain('themeConfig?: ThemeConfig');
+    expect(provider).toContain('themeConfig ?? createZoraThemeConfig(theme)');
+    expect(context).not.toContain('ThemeConfig');
+    expect(context).not.toContain('sourceTheme');
+  });
+
+  test('nested scopes derive from the current Surface config authority', () => {
+    const scope = readFileSync(join(themeDir, 'ZoraThemeScope.tsx'), 'utf8');
+    expect(scope).toContain('const sourceConfig = parentSurface.theme.config;');
+    expect(scope).toContain('createTheme(sourceConfig');
+    expect(scope).not.toContain('createZoraThemeConfig');
+    expect(scope).not.toContain('sourceTheme');
+  });
+});

package/src/theme/useZoraThemeRecipe.ts

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