@ankhorage/zora 19.0.0 → 20.0.0

package/src/features/scanner/adapters/inbound/CameraPermissionView.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { CameraPermissionViewProps } from '../../../../types/scanner';
 import { Button } from '../../../button/public';
 import { Card } from '../../../card/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Text } from '../../../typography/public';
 
 function resolvePermissionCopy(status: CameraPermissionViewProps['status']) {

package/src/features/scanner/adapters/inbound/ScanOverlay.tsx

@@ -1,11 +1,11 @@
 import React from 'react';
 import { StyleSheet } from 'react-native';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ScanOverlayProps } from '../../../../types/scanner';
 import { Badge } from '../../../badge/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Text } from '../../../typography/public';
 
 function ScanOverlayInner({

package/src/features/scanner/meta.ts

@@ -1,5 +1,5 @@
-import type { ZoraComponentMeta } from '../../metadata';
-import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 
 export const scanOverlayMeta = {
   name: 'ScanOverlay',
@@ -44,7 +44,7 @@ export const cameraPermissionViewMeta = {
   directManifestNode: true,
   allowedChildren: [],
   requirements: {
-    permissions: [{ permission: 'camera' }],
+    permissions: { camera: true },
   },
   blueprint: {
     label: 'Camera permission',
@@ -111,8 +111,8 @@ export const barcodeScannerViewMeta = {
   directManifestNode: true,
   allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
   requirements: {
-    permissions: [{ permission: 'camera' }],
-    capabilities: [{ capability: 'barcodeScanner' }],
+    permissions: { camera: true },
+    capabilities: { barcodeScanner: true },
   },
   blueprint: {
     label: 'Barcode scanner',

package/src/features/section/adapters/inbound/ScreenSection.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ScreenSectionProps } from '../../../../types/section';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { SectionHeader } from './SectionHeader';
 
 function ScreenSectionInner({

package/src/features/section/adapters/inbound/SectionHeader.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SectionHeaderProps } from '../../../../types/section';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Heading } from '../../../typography/public';
 import { Text } from '../../../typography/public';
 

package/src/features/section/screenSectionMeta.ts

@@ -1,5 +1,5 @@
-import type { ZoraComponentMeta } from '../../metadata';
-import { SCREEN_SECTION_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../authoring';
+import { SCREEN_SECTION_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 
 export const screenSectionMeta = {
   name: 'ScreenSection',

package/src/features/section/sectionHeaderMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const sectionHeaderMeta = {
   name: 'SectionHeader',

package/src/features/selection/meta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 const SELECTION_NOTE = 'Selection pattern component; not represented as a manifest node in v1.';
 

package/src/features/skeleton/adapters/inbound/Skeleton.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonProps } from '../../../../types/skeleton';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 
 function SkeletonInner({
   themeId: _themeId,

package/src/features/skeleton/adapters/inbound/SkeletonCard.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonCardProps } from '../../../../types/skeleton';
 import { ButtonGroup } from '../../../button/public';
 import { Card } from '../../../card/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 import { SkeletonText } from './SkeletonText';
 

package/src/features/skeleton/adapters/inbound/SkeletonList.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonListProps } from '../../../../types/skeleton';
 import { List, type ListItemProps } from '../../../list/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 import { SkeletonText } from './SkeletonText';
 

package/src/features/skeleton/adapters/inbound/SkeletonText.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonTextProps } from '../../../../types/skeleton';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 
 function clampLines(lines: number): number {

package/src/features/skeleton/public.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from 'bun:test';
 
-import { ZORA_COMPONENT_META } from '../../metadata/componentMeta';
+import { ZORA_COMPONENT_META } from '../authoring/componentMeta';
 
 test('skeletons support direct authoring and automatic feature loading states', async () => {
   const [dataTableSource, publicSource] = await Promise.all([

package/src/features/skeleton/skeletonMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const skeletonMeta = {
   name: 'Skeleton',

package/src/features/surface/adapters/inbound/Surface.tsx

@@ -1,8 +1,8 @@
 import { Surface as SurfaceSurface } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SurfaceProps } from '../../../../types/surface';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Adapts the themed Surface Surface primitive to ZORA scope and interaction props. */
 export const Surface = withZoraThemeScope(SurfaceInner);

package/src/features/surface/surfaceMeta.ts

@@ -1,5 +1,5 @@
-import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 import { LAYOUT_PROPS } from '../layout/constants';
 
 export const surfaceMeta = {

package/src/features/tabs/adapters/inbound/Tab.tsx

@@ -1,8 +1,8 @@
 import { Tab as SurfaceTab } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TabsInteractionPolicyContext } from '../../composition/TabsInteractionPolicyContext';
 
 /*** Renders one labeled selectable tab backed by Surface accessibility semantics. */

package/src/features/tabs/adapters/inbound/TabList.tsx

@@ -1,7 +1,7 @@
 import { TabList as SurfaceTabList } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabListProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders the accessible list of tabs for a Tabs composition. */
 export const TabList = withZoraThemeScope(TabListInner);

package/src/features/tabs/adapters/inbound/TabPanel.tsx

@@ -1,7 +1,7 @@
 import { TabPanel as SurfaceTabPanel } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabPanelProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders content associated with one selected Tab. */
 export const TabPanel = withZoraThemeScope(TabPanelInner);

package/src/features/tabs/adapters/inbound/Tabs.tsx

@@ -1,7 +1,7 @@
 import { Tabs as SurfaceTabs } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabsProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TabsInteractionPolicyContext } from '../../composition/TabsInteractionPolicyContext';
 
 /*** Provides accessible tab state and interaction policy through the Surface Tabs primitive. */

package/src/features/tabs/tabListMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabListMeta = {
   name: 'TabList',

package/src/features/tabs/tabMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabMeta = {
   name: 'Tab',

package/src/features/tabs/tabPanelMeta.ts

@@ -1,5 +1,5 @@
-import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 
 export const tabPanelMeta = {
   name: 'TabPanel',

package/src/features/tabs/tabsMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabsMeta = {
   name: 'Tabs',

package/src/{theme → features/theme}/ThemeModeToggle.meta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const themeModeToggleMeta = {
   name: 'ThemeModeToggle',

package/src/{theme → features/theme/adapters/inbound}/ThemeModeToggle.tsx

@@ -1,7 +1,7 @@
-import { IconButton } from '../features/button/public';
-import { resolveThemeModeToggleState } from './resolveThemeModeToggleState';
-import type { ThemeModeToggleProps } from './ThemeModeToggleProps';
-import { useZoraTheme } from './useZoraTheme';
+import type { ThemeModeToggleProps } from '../../../../types/theme-mode-toggle';
+import { IconButton } from '../../../button/public';
+import { useZoraTheme } from '../../composition/useZoraTheme';
+import { resolveThemeModeToggleState } from '../../utils/resolveThemeModeToggleState';
 
 export function ThemeModeToggle({
   disabled,

package/src/{theme → features/theme/adapters/inbound}/ZoraProvider.tsx

@@ -1,13 +1,13 @@
 import { ThemeProvider } from '@ankhorage/surface';
 import React from 'react';
 
-import type { ZoraProviderProps } from '../types/provider';
-import { createZoraThemeConfig } from './createZoraThemeConfig';
-import { zoraDefaultTheme } from './zoraDefaultTheme';
-import { ZoraRuntimeCapabilities } from './ZoraRuntimeCapabilities';
-import { ZoraThemeRuntimeContext } from './ZoraThemeRuntimeContext';
+import type { ZoraProviderProps } from '../../../../types/provider';
+import { createZoraThemeConfig } from '../../application/use-cases/createZoraThemeConfig';
+import { ZoraRuntimeCapabilities } from '../../composition/ZoraRuntimeCapabilities';
+import { ZoraThemeRuntimeContext } from '../../composition/ZoraThemeRuntimeContext';
+import { zoraDefaultTheme } from '../../zoraDefaultTheme';
 
-export type { ZoraProviderProps, ZoraToastCapability } from '../types/provider';
+export type { ZoraProviderProps, ZoraToastCapability } from '../../../../types/provider';
 
 /*** Installs the core ZORA theme runtime and explicitly enabled optional capabilities. */
 export function ZoraProvider({

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/{theme → features/theme/adapters/inbound}/withZoraThemeScope.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 
-import type { ZoraBaseProps } from './ZoraBaseProps';
+import type { ZoraBaseProps } from '../../../../types/base';
 import { ZoraThemeScope } from './ZoraThemeScope';
 
 export function withZoraThemeScope<P extends ZoraBaseProps>(

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

@@ -6,7 +6,11 @@ import {
 import type { ThemeConfig } from '@ankhorage/contracts';
 import { describe, expect, test } from 'bun:test';
 
-import { compileZoraTheme, type ZoraComputedTheme, type ZoraThemeSelectionTarget } from './public';
+import {
+  compileZoraTheme,
+  type ZoraComputedTheme,
+  type ZoraThemeSelectionTarget,
+} from '../../public';
 
 const baseConfig: ThemeConfig = {
   id: 'compiler-test',

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

@@ -1,6 +1,7 @@
 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,
@@ -11,7 +12,7 @@ import type {
   ZoraThemeProvenanceEntry,
   ZoraThemeSelectionResult,
   ZoraThemeSelectionTarget,
-} from './types';
+} from '../../../../types/theme';
 
 const CONTRACTS_OWNER = '@ankhorage/contracts';
 const COLOR_THEORY_OWNER = '@ankhorage/color-theory';
@@ -173,5 +174,5 @@ function createModeProvenance(
 
 /*** Compare deterministic owner result records for divergence diagnostics. */
 function outputsAgree(left: unknown, right: unknown): boolean {
-  return JSON.stringify(left) === JSON.stringify(right);
+  return isDeepEqual(left, right);
 }

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

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 
+import { zoraDefaultTheme } from '../../zoraDefaultTheme';
 import { createZoraThemeConfig } from './createZoraThemeConfig';
-import { zoraDefaultTheme } from './zoraDefaultTheme';
 
 describe('createZoraThemeConfig', () => {
   test('converts the default theme seed into a surface config', () => {

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

@@ -1,8 +1,8 @@
 import { parseHexColorOrThrow } from '@ankhorage/color-theory';
 import type { ThemeConfig } from '@ankhorage/contracts';
 
-import type { ZoraTheme } from './types';
-import { zoraDefaultTheme } from './zoraDefaultTheme';
+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 {

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/{theme → features/theme/composition}/ZoraRuntimeCapabilities.native.tsx

@@ -1,7 +1,7 @@
 import { ToastProvider as SurfaceToastProvider } from '@ankhorage/surface';
 import { BottomSheetProvider } from '@ankhorage/surface/bottom-sheet';
 
-import type { ZoraRuntimeCapabilitiesProps } from '../types/provider';
+import type { ZoraRuntimeCapabilitiesProps } from '../../../types/provider';
 
 /*** Installs optional native runtime capabilities without forcing unused hosts. */
 export function ZoraRuntimeCapabilities({

package/src/{theme → features/theme/composition}/ZoraRuntimeCapabilities.web.tsx

@@ -1,6 +1,6 @@
 import { ToastProvider as SurfaceToastProvider } from '@ankhorage/surface';
 
-import type { ZoraRuntimeCapabilitiesProps } from '../types/provider';
+import type { ZoraRuntimeCapabilitiesProps } from '../../../types/provider';
 
 /*** Installs only web-relevant optional runtime capabilities. */
 export function ZoraRuntimeCapabilities({ children, toast }: ZoraRuntimeCapabilitiesProps) {

package/src/{theme → features/theme/composition}/ZoraThemeRuntimeContext.tsx

@@ -1,7 +1,7 @@
 import { createContext, use } from 'react';
 
-import type { ZoraThemeId } from './types';
-import { zoraDefaultTheme } from './zoraDefaultTheme';
+import type { ZoraThemeId } from '../../../types/theme';
+import { zoraDefaultTheme } from '../zoraDefaultTheme';
 
 interface ZoraThemeRuntime {
   themeId: ZoraThemeId;

package/src/{theme → features/theme/composition}/useZoraThemeRecipe.ts

@@ -1,4 +1,4 @@
-import { resolveZoraThemeRecipe } from './resolveZoraThemeRecipe';
+import { resolveZoraThemeRecipe } from '../utils/resolveZoraThemeRecipe';
 import { useZoraTheme } from './useZoraTheme';
 
 export function useZoraThemeRecipe(recipeName: string) {

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

@@ -1,5 +1,3 @@
-export { compileZoraTheme } from './compileZoraTheme';
-export { createZoraThemeConfig } from './createZoraThemeConfig';
 export type {
   ZoraComputedTheme,
   ZoraComputedThemeMode,
@@ -14,5 +12,7 @@ export type {
   ZoraThemeSelectionTarget,
   ZoraThemeSwatchRole,
   ZoraThemeValueOrigin,
-} from './types';
+} 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/{theme → features/theme}/themeConfigScope.test.ts

@@ -4,13 +4,19 @@ import { join } from 'node:path';
 import { describe, expect, test } from 'bun:test';
 
 const themeDir = import.meta.dir;
-const srcDir = join(themeDir, '..');
+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, 'ZoraProvider.tsx'), 'utf8');
+    const provider = readFileSync(
+      join(themeDir, 'adapters', 'inbound', 'ZoraProvider.tsx'),
+      'utf8',
+    );
     const providerTypes = readFileSync(join(srcDir, 'types', 'provider.ts'), 'utf8');
-    const context = readFileSync(join(themeDir, 'ZoraThemeRuntimeContext.tsx'), 'utf8');
+    const context = readFileSync(
+      join(themeDir, 'composition', 'ZoraThemeRuntimeContext.tsx'),
+      'utf8',
+    );
 
     expect(providerTypes).toContain('themeConfig?: ThemeConfig');
     expect(provider).toContain('themeConfig ?? createZoraThemeConfig(theme)');
@@ -18,10 +24,13 @@ describe('canonical ThemeConfig scope propagation', () => {
     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');
+  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');
   });

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

@@ -1,5 +1,5 @@
 /**
- * Replace themeScopeStructure.test.ts with real behavior tests once the ZORA component test strategy is decided.
+ * Keep structural guards for the public Surface boundary alongside ZoraThemeScope behavior tests.
  */
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
@@ -7,7 +7,7 @@ import { join } from 'node:path';
 import { describe, expect, it } from 'bun:test';
 
 const themeDir = import.meta.dir;
-const srcDir = join(themeDir, '..');
+const srcDir = join(themeDir, '..', '..');
 
 function readSource(...segments: readonly string[]) {
   return readFileSync(join(themeDir, ...segments), 'utf8');
@@ -39,13 +39,16 @@ function collectSourceFiles(rootDir: string) {
   return files;
 }
 
-const zoraProviderSource = readSource('ZoraProvider.tsx');
-const themeScopeSource = readSource('ZoraThemeScope.tsx');
-const hocSource = readSource('withZoraThemeScope.tsx');
+const zoraProviderSource = readSource('adapters', 'inbound', 'ZoraProvider.tsx');
+const themeScopeSource = readSource('adapters', 'inbound', 'ZoraThemeScope.tsx');
+const hocSource = readSource('adapters', 'inbound', 'withZoraThemeScope.tsx');
 
 const scopeGuardDirs = [join(srcDir, 'features')] as const;
+const themeFeatureDir = join(srcDir, 'features', 'theme');
 
-const scopeGuardFiles = scopeGuardDirs.flatMap(collectSourceFiles);
+const scopeGuardFiles = scopeGuardDirs
+  .flatMap(collectSourceFiles)
+  .filter((filePath) => !filePath.startsWith(`${themeFeatureDir}/`));
 
 const scopedComponentFiles = [
   join(srcDir, 'features', 'layout', 'adapters', 'inbound', 'AppShell.tsx'),
@@ -172,9 +175,13 @@ describe('theme scope structure', () => {
     expect(zoraProviderSource).not.toMatch(/ResponsiveProvider/);
   });
 
-  it('implements nested scopes without nesting Surface ThemeProvider', () => {
-    expect(themeScopeSource).toMatch(/<ThemeContext\s+value=/u);
-    expect(themeScopeSource).toMatch(/createTheme\(/u);
+  it('delegates nested Surface runtime ownership to the public ThemeScope boundary', () => {
+    expect(themeScopeSource).toMatch(/import \{ ThemeScope \} from '@ankhorage\/surface'/u);
+    expect(themeScopeSource).toMatch(/<ThemeScope\s+mode=/u);
+    expect(themeScopeSource).not.toMatch(/ThemeContext/u);
+    expect(themeScopeSource).not.toMatch(/useFontContext/u);
+    expect(themeScopeSource).not.toMatch(/createTheme\(/u);
+    expect(themeScopeSource).not.toMatch(/_hasProvider/u);
     expect(themeScopeSource).not.toMatch(/<ThemeProvider\b/u);
   });
 

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

@@ -1,4 +1,4 @@
-import type { ZoraThemeMode } from './types';
+import type { ZoraThemeMode } from '../../../types/theme';
 
 interface ThemeModeToggleState {
   readonly iconName: 'moon-outline' | 'sunny-outline';

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

@@ -1,4 +1,4 @@
-import type { ZoraThemeId } from './types';
+import type { ZoraThemeId } from '../../../types/theme';
 
 export function resolveZoraScopedThemeId({
   desiredThemeId,

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

@@ -1,7 +1,7 @@
 import type { ThemeConfig, ThemeRecipeOverrideValue } from '@ankhorage/contracts';
 
-import { ZORA_THEME_RECIPE_META } from '../metadata/themeRecipeMeta';
-import type { ZoraThemeRecipeFieldMeta, ZoraThemeTokenFamily } from '../metadata/themeRecipeTypes';
+import type { ZoraThemeRecipeFieldMeta, ZoraThemeTokenFamily } from '../../../types/theme-recipe';
+import { ZORA_THEME_RECIPE_META } from '../../authoring/themeRecipeMeta';
 
 interface ZoraThemeRecipeRuntimeTheme {
   readonly config: ThemeConfig;