@ankhorage/surface 8.0.0 → 9.0.1

package/src/constants/surfaceColor.public.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  SURFACE_COLORS,
+  SURFACE_EMPHASES,
+  SURFACE_PALETTE_COLORS,
+  SURFACE_STATUS_COLORS,
+} from './surfaceColor';
+
+describe('public color subpath', () => {
+  test('imports canonical catalogs through the package subpath in plain Bun', async () => {
+    const script = [
+      "import { SURFACE_COLORS, SURFACE_EMPHASES } from '@ankhorage/surface/color';",
+      'process.stdout.write(`${SURFACE_COLORS.length}:${SURFACE_EMPHASES.length}`);',
+    ].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(`${SURFACE_COLORS.length}:${SURFACE_EMPHASES.length}`);
+  });
+
+  test('keeps the package subpath aligned with the canonical catalogs', () => {
+    expect(SURFACE_COLORS).toEqual([...SURFACE_PALETTE_COLORS, ...SURFACE_STATUS_COLORS, 'danger']);
+  });
+});

package/src/constants/surfaceColor.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  SURFACE_COLORS,
+  SURFACE_EMPHASES,
+  SURFACE_PALETTE_COLORS,
+  SURFACE_STATUS_COLORS,
+} from './surfaceColor';
+
+describe('surface color constants', () => {
+  it('keeps canonical color and emphasis catalogs unique and aligned', () => {
+    expect(new Set(SURFACE_COLORS).size).toBe(SURFACE_COLORS.length);
+    expect(new Set(SURFACE_EMPHASES).size).toBe(SURFACE_EMPHASES.length);
+    for (const color of [...SURFACE_PALETTE_COLORS, ...SURFACE_STATUS_COLORS]) {
+      expect(SURFACE_COLORS).toContain(color);
+    }
+  });
+});

package/src/{surfaceColor.ts → constants/surfaceColor.ts}

@@ -15,8 +15,3 @@ export const SURFACE_COLORS = [
 ] as const;
 
 export const SURFACE_EMPHASES = ['default', 'muted', 'subtle', 'inverse'] as const;
-
-export type SurfacePaletteColor = (typeof SURFACE_PALETTE_COLORS)[number];
-export type SurfaceStatusColor = (typeof SURFACE_STATUS_COLORS)[number];
-export type SurfaceColor = (typeof SURFACE_COLORS)[number];
-export type SurfaceEmphasis = (typeof SURFACE_EMPHASES)[number];

package/src/features/app-bar/adapters/inbound/AppBar.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 import { StyleSheet, View as ReactNativeView, type ViewStyle } from 'react-native';
 import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
 
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { AppBarProps } from '../../../../types/app-bar';
 import { Divider, View } from '../../../layout/public';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders application chrome with optional safe-area padding and leading/trailing slots. */
 export function AppBar({

package/src/features/badge/adapters/inbound/Badge.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 import type { ViewStyle } from 'react-native';
 
 import { resolveButtonColors, resolveControlSize } from '../../../../internal/resolvers';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { BadgeProps } from '../../../../types/badge';
 import { View } from '../../../layout/public';
+import { useTheme } from '../../../theme/runtime';
 import { Text } from '../../../typography/public';
 
 /*** Renders compact semantic status or metadata content. */

package/src/features/button/adapters/inbound/Button.tsx

@@ -7,12 +7,12 @@ import {
   resolveControlSize,
   resolveIconSize,
 } from '../../../../internal/resolvers';
-import { useTheme } from '../../../../theme/ThemeContext';
-import type { SurfaceTheme } from '../../../../theme/types';
 import type { ButtonProps } from '../../../../types/button';
+import type { SurfaceTheme } from '../../../../types/theme';
 import { Icon } from '../../../icon/public';
 import { View } from '../../../layout/public';
 import { Pressable } from '../../../pressable/public';
+import { useTheme } from '../../../theme/runtime';
 import { Text } from '../../../typography/public';
 
 /*** Renders the primary Surface action control with semantic visual states. */

package/src/features/button/adapters/inbound/IconButton.tsx

@@ -6,11 +6,11 @@ import {
   resolveControlSize,
   resolveIconSize,
 } from '../../../../internal/resolvers';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { IconButtonProps } from '../../../../types/button';
 import { Icon } from '../../../icon/public';
 import { View } from '../../../layout/public';
 import { Pressable } from '../../../pressable/public';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders a compact accessible icon-only action control. */
 export function IconButton({

package/src/features/card/adapters/inbound/Card.tsx

@@ -1,11 +1,11 @@
 import React from 'react';
 import type { ViewStyle } from 'react-native';
 
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { CardProps } from '../../../../types/card';
 import type { SurfaceVariant } from '../../../../types/surface';
 import { Pressable } from '../../../pressable/public';
 import { Surface } from '../../../surface/public';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders a themed content card with optional interactive press states. */
 export function Card({

package/src/features/font/adapters/inbound/FontProvider.tsx

@@ -0,0 +1,27 @@
+import { useMemo, useState } from 'react';
+
+import type { FontProviderProps, FontRuntime } from '../../../../types/font';
+import { FontRuntimeContext } from './FontRuntimeContext';
+
+/*** Provide loaded-font state and the active font id to Surface theme composition. */
+export function FontProvider({
+  fontsLoaded,
+  activeFontId: initialActiveFontId = null,
+  children,
+  onActiveFontChange,
+}: FontProviderProps) {
+  const [activeFontId, setActiveFontIdState] = useState(initialActiveFontId);
+  const value = useMemo<FontRuntime>(
+    () => ({
+      fontsLoaded,
+      activeFontId,
+      setActiveFontId: (id: string) => {
+        setActiveFontIdState(id);
+        onActiveFontChange?.(id);
+      },
+    }),
+    [activeFontId, fontsLoaded, onActiveFontChange],
+  );
+
+  return <FontRuntimeContext value={value}>{children}</FontRuntimeContext>;
+}

package/src/features/font/adapters/inbound/FontRuntimeContext.tsx

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+
+import type { FontRuntime } from '../../../../types/font';
+
+const fallbackRuntime: FontRuntime = {
+  fontsLoaded: true,
+  activeFontId: null,
+  setActiveFontId: () => undefined,
+};
+
+/*** Holds Surface font runtime state for theme resolution. */
+export const FontRuntimeContext = createContext<FontRuntime>(fallbackRuntime);

package/src/features/font/adapters/inbound/useFontRuntime.ts

@@ -0,0 +1,9 @@
+import { use } from 'react';
+
+import type { FontRuntime } from '../../../../types/font';
+import { FontRuntimeContext } from './FontRuntimeContext';
+
+/*** Read the internal font runtime used by Surface theme composition. */
+export function useFontRuntime(): FontRuntime {
+  return use(FontRuntimeContext);
+}

package/src/features/font/public.ts

@@ -0,0 +1,2 @@
+export type { FontProviderProps, FontRuntime } from '../../types/font';
+export { FontProvider } from './adapters/inbound/FontProvider';

package/src/features/form/checkbox/adapters/inbound/Checkbox.tsx

@@ -9,12 +9,12 @@ import {
   resolveSelectionControlNextChecked,
 } from '../../../../../internal/resolvers';
 import { useControllableState } from '../../../../../internal/useControllableState';
-import { useTheme } from '../../../../../theme/ThemeContext';
-import type { SurfaceTheme } from '../../../../../theme/types';
 import type { CheckboxProps } from '../../../../../types/checkbox';
+import type { SurfaceTheme } from '../../../../../types/theme';
 import { View } from '../../../../layout/public';
 import type { PressableProps } from '../../../../pressable/public';
 import { Pressable } from '../../../../pressable/public';
+import { useTheme } from '../../../../theme/runtime';
 import { Text } from '../../../../typography/public';
 
 /*** Renders a controlled or uncontrolled accessible checkbox. */

package/src/features/form/radio/adapters/inbound/Radio.tsx

@@ -9,12 +9,12 @@ import {
   resolveSelectionControlNextChecked,
 } from '../../../../../internal/resolvers';
 import { useControllableState } from '../../../../../internal/useControllableState';
-import { useTheme } from '../../../../../theme/ThemeContext';
-import type { SurfaceTheme } from '../../../../../theme/types';
 import type { RadioProps } from '../../../../../types/radio';
+import type { SurfaceTheme } from '../../../../../types/theme';
 import { View } from '../../../../layout/public';
 import type { PressableProps } from '../../../../pressable/public';
 import { Pressable } from '../../../../pressable/public';
+import { useTheme } from '../../../../theme/runtime';
 import { Text } from '../../../../typography/public';
 import { isRadioTextContent } from '../../utils/isRadioTextContent';
 

package/src/features/form/switch/adapters/inbound/Switch.tsx

@@ -8,10 +8,10 @@ import {
   resolveSelectionControlNextChecked,
 } from '../../../../../internal/resolvers';
 import { useControllableState } from '../../../../../internal/useControllableState';
-import { useTheme } from '../../../../../theme/ThemeContext';
 import type { SwitchProps } from '../../../../../types/switch';
 import { View } from '../../../../layout/public';
 import { Pressable } from '../../../../pressable/public';
+import { useTheme } from '../../../../theme/runtime';
 import { Text } from '../../../../typography/public';
 
 /*** Renders a controlled or uncontrolled accessible switch. */

package/src/features/form/text-input/adapters/inbound/TextInput.tsx

@@ -9,8 +9,8 @@ import {
 } from 'react-native';
 
 import { resolveFocusRingStyles } from '../../../../../internal/resolvers';
-import { useTheme } from '../../../../../theme/ThemeContext';
 import type { TextInputProps } from '../../../../../types/text-input';
+import { useTheme } from '../../../../theme/runtime';
 import { resolveTextInputPresentation } from '../../utils/resolveTextInputPresentation';
 
 /*** Renders a token-aware text input with controlled interaction policy. */

package/src/features/form/text-input/utils/resolveTextInputPresentation.ts

@@ -6,8 +6,8 @@ import {
   resolveInputColors,
   resolveTextStyles,
 } from '../../../../internal/resolvers';
-import type { SurfaceTheme } from '../../../../theme/types';
 import type { TextInputProps } from '../../../../types/text-input';
+import type { SurfaceTheme } from '../../../../types/theme';
 
 /*** Resolves layout, colors, and editability for one TextInput state. */
 export function resolveTextInputPresentation(

package/src/features/icon/adapters/inbound/Icon.tsx

@@ -1,6 +1,6 @@
-import { resolveToken } from '../../../../theme/resolveToken';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { IconProps } from '../../../../types/icon';
+import { useTheme } from '../../../theme/runtime';
+import { resolveToken } from '../../../theme/utils/resolveToken';
 import { PortableIcon } from './PortableIcon';
 
 /*** Renders a theme-aware font or SVG icon through the portable icon adapter. */

package/src/features/image/adapters/inbound/Image.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 import { Image as ReactNativeImage } from 'react-native';
 
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { ImageProps } from '../../../../types/image';
+import { useTheme } from '../../../theme/runtime';
 import { getSourceKey } from '../../utils/getSourceKey';
 import { normalizeSource } from '../../utils/normalizeSource';
 import { resolveAccessibilityLabel } from '../../utils/resolveAccessibilityLabel';

package/src/features/image/utils/resolveImageProps.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 
-import { createTheme } from '../../../theme/createTheme';
+import { createTheme } from '../../theme/application/use-cases/createTheme';
 import { getSourceKey } from './getSourceKey';
 import { normalizeSource } from './normalizeSource';
 import { resolveImageStyle } from './resolveImageStyle';

package/src/features/image/utils/resolveImageStyle.ts

@@ -1,8 +1,8 @@
 import type { ImageStyle } from 'react-native';
 
-import { resolveToken } from '../../../theme/resolveToken';
-import type { SurfaceTheme } from '../../../theme/types';
 import type { ImageProps } from '../../../types/image';
+import type { SurfaceTheme } from '../../../types/theme';
+import { resolveToken } from '../../theme/utils/resolveToken';
 
 /*** Resolves token-aware dimensions and radius for a Surface image. */
 export function resolveImageStyle(

package/src/features/layout/adapters/inbound/Grid.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 import { View as ReactNativeView, type ViewStyle } from 'react-native';
 
 import { resolveResponsive, useResponsiveRuntime } from '../../../../core/responsive';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { GridProps } from '../../../../types/layout';
 import { resolveSpacing } from '../../../../utils/resolveSpacing';
+import { useTheme } from '../../../theme/runtime';
 import { View } from './View';
 
 /*** Lays out children in a responsive wrapping grid. */

package/src/features/layout/adapters/inbound/ScrollView.tsx

@@ -2,9 +2,9 @@ import React from 'react';
 import { ScrollView as ReactNativeScrollView } from 'react-native';
 
 import { useResponsiveRuntime } from '../../../../core/responsive';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { ScrollViewProps } from '../../../../types/layout';
 import { resolveViewStyles } from '../../../../utils/resolveViewStyles';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders the token-aware responsive Surface adapter for React Native ScrollView. */
 export function ScrollView(props: ScrollViewProps) {

package/src/features/layout/adapters/inbound/View.tsx

@@ -3,9 +3,9 @@ import { View as ReactNativeView } from 'react-native';
 
 import { useResponsiveRuntime } from '../../../../core/responsive';
 import { resolvePointerEvents } from '../../../../internal/resolvePointerEvents';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { ViewProps } from '../../../../types/layout';
 import { resolveViewStyles } from '../../../../utils/resolveViewStyles';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders the token-aware responsive Surface adapter for React Native View. */
 export function View({

package/src/features/list/adapters/inbound/ListItem.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { useTheme } from '../../../../theme/ThemeContext';
-import type { SurfaceTheme } from '../../../../theme/types';
 import type { ListItemProps } from '../../../../types/list';
+import type { SurfaceTheme } from '../../../../types/theme';
 import { View } from '../../../layout/public';
 import { Pressable } from '../../../pressable/public';
+import { useTheme } from '../../../theme/runtime';
 import { Text } from '../../../typography/public';
 
 /*** Renders a static or interactive list item with shared row geometry and interaction states. */

package/src/features/modal/adapters/inbound/Modal.tsx

@@ -5,10 +5,10 @@ import { FocusScope } from '../../../../internal/focus/FocusScope';
 import { Portal } from '../../../../internal/overlay/Portal';
 import { resolvePointerEvents } from '../../../../internal/resolvePointerEvents';
 import { resolveOverlayAnimation } from '../../../../internal/resolvers';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { ModalProps } from '../../../../types/modal';
 import { View } from '../../../layout/public';
 import { Surface } from '../../../surface/public';
+import { useTheme } from '../../../theme/runtime';
 
 const boxNonePointerEvents = resolvePointerEvents('box-none');
 

package/src/features/popover-menu/adapters/inbound/PopoverMenu.tsx

@@ -3,11 +3,11 @@ import { Pressable } from 'react-native';
 
 import { FocusScope } from '../../../../internal/focus/FocusScope';
 import { useFocusManager } from '../../../../internal/focus/useFocusManager';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { PopoverMenuAction, PopoverMenuProps } from '../../../../types/popoverMenu';
 import { View } from '../../../layout/public';
 import { Popover } from '../../../popover/public';
 import { Surface } from '../../../surface/public';
+import { useTheme } from '../../../theme/runtime';
 import { Text } from '../../../typography/public';
 import { usePopoverMenuController } from '../../composition/usePopoverMenuController';
 import { resolveNextMenuIndex } from '../../utils/resolveNextMenuIndex';

package/src/features/pressable/adapters/inbound/Pressable.tsx

@@ -11,9 +11,9 @@ import {
   resolveFocusRingStyles,
   resolveInteractiveState,
 } from '../../../../internal/resolvers';
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { PressableProps } from '../../../../types/pressable';
 import { resolveViewStyles } from '../../../../utils/resolveViewStyles';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders the token-aware Surface adapter for React Native Pressable. */
 export function Pressable({

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

@@ -1,9 +1,9 @@
 import React from 'react';
 import type { ViewStyle } from 'react-native';
 
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { SurfaceProps, SurfaceVariant } from '../../../../types/surface';
 import { View } from '../../../layout/public';
+import { useTheme } from '../../../theme/runtime';
 
 /*** Renders a themed content surface with semantic elevation and border variants. */
 export function Surface({ variant = 'default', radius = 'm', style, ...props }: SurfaceProps) {

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

@@ -1,9 +1,9 @@
 import React from 'react';
 import { Pressable, type ViewStyle } from 'react-native';
 
-import { useTheme } from '../../../../theme/ThemeContext';
 import type { TabProps } from '../../../../types/tabs';
 import { View } from '../../../layout/public';
+import { useTheme } from '../../../theme/runtime';
 import { Text } from '../../../typography/public';
 import { useTabRegistration } from '../../composition/useTabRegistration';
 import { useTabsContext } from '../../composition/useTabsContext';

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

@@ -0,0 +1,46 @@
+import type { ThemeConfig } from '@ankhorage/contracts';
+import { deepMerge } from '@ankhorage/utility/object';
+import { useMemo, useState } from 'react';
+
+import { ResponsiveProvider } from '../../../../core/responsive/ResponsiveProvider';
+import { OverlayProvider } from '../../../../internal/overlay/OverlayProvider';
+import type { ThemeProviderProps, ThemeRuntime } from '../../../../types/theme';
+import { useFontRuntime } from '../../../font/adapters/inbound/useFontRuntime';
+import { createTheme } from '../../application/use-cases/createTheme';
+import { ThemeRuntimeContext } from './ThemeRuntimeContext';
+
+/*** Install the app-level Surface theme together with global responsive and overlay runtime. */
+export function ThemeProvider({
+  children,
+  initialConfig,
+  initialMode = 'light',
+}: ThemeProviderProps) {
+  const defaultTheme = useMemo(() => createTheme(), []);
+  const [config, setConfig] = useState<ThemeConfig>(() =>
+    initialConfig ? deepMerge(defaultTheme.config, initialConfig) : defaultTheme.config,
+  );
+  const [mode, setMode] = useState(initialMode);
+  const { activeFontId } = useFontRuntime();
+
+  const theme = useMemo(
+    () => createTheme(config, mode, activeFontId),
+    [activeFontId, config, mode],
+  );
+  const value = useMemo<ThemeRuntime>(
+    () => ({
+      theme,
+      mode,
+      setThemeConfig: (nextConfig) => setConfig((previous) => deepMerge(previous, nextConfig)),
+      setMode,
+    }),
+    [mode, theme],
+  );
+
+  return (
+    <ResponsiveProvider>
+      <ThemeRuntimeContext value={value}>
+        <OverlayProvider>{children}</OverlayProvider>
+      </ThemeRuntimeContext>
+    </ResponsiveProvider>
+  );
+}

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

@@ -0,0 +1,14 @@
+import { createContext } from 'react';
+
+import type { ThemeRuntime } from '../../../../types/theme';
+import { createTheme } from '../../application/use-cases/createTheme';
+
+const defaultTheme = createTheme();
+
+/*** Holds the active Surface theme runtime for component consumption. */
+export const ThemeRuntimeContext = createContext<ThemeRuntime>({
+  theme: defaultTheme,
+  mode: 'light',
+  setThemeConfig: () => undefined,
+  setMode: () => undefined,
+});

package/src/features/theme/adapters/inbound/ThemeScope.test.tsx

@@ -0,0 +1,52 @@
+import { expect, test } from 'bun:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type { ThemeRuntime } from '../../../../types/theme';
+import { createTheme } from '../../application/use-cases/createTheme';
+import { ThemeRuntimeContext } from './ThemeRuntimeContext';
+import { ThemeScope } from './ThemeScope';
+import { useTheme } from './useTheme';
+
+function ThemeProbe() {
+  const { mode, theme } = useTheme();
+  return <span>{`${theme.config.id}:${mode}:${theme.colorDiagnostics.mode}`}</span>;
+}
+
+const parentRuntime: ThemeRuntime = {
+  theme: createTheme(),
+  mode: 'light',
+  setThemeConfig: () => undefined,
+  setMode: () => undefined,
+};
+
+test('overrides mode without mutating the parent theme runtime', () => {
+  const markup = renderToStaticMarkup(
+    <ThemeRuntimeContext value={parentRuntime}>
+      <ThemeProbe />
+      <ThemeScope mode="dark">
+        <ThemeProbe />
+      </ThemeScope>
+      <ThemeProbe />
+    </ThemeRuntimeContext>,
+  );
+
+  expect(markup).toContain('default:light:light');
+  expect(markup).toContain('default:dark:dark');
+  expect(markup.match(/default:light:light/g)).toHaveLength(2);
+});
+
+test('deep-merges a nested config override while preserving the parent config', () => {
+  const markup = renderToStaticMarkup(
+    <ThemeRuntimeContext value={parentRuntime}>
+      <ThemeProbe />
+      <ThemeScope themeConfig={{ id: 'scoped' }}>
+        <ThemeProbe />
+      </ThemeScope>
+      <ThemeProbe />
+    </ThemeRuntimeContext>,
+  );
+
+  expect(markup).toContain('scoped:light:light');
+  expect(markup.match(/default:light:light/g)).toHaveLength(2);
+  expect(parentRuntime.theme.config.id).toBe('default');
+});

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

@@ -0,0 +1,29 @@
+import { deepMerge } from '@ankhorage/utility/object';
+import { useMemo } from 'react';
+
+import type { ThemeRuntime, ThemeScopeProps } from '../../../../types/theme';
+import { useFontRuntime } from '../../../font/adapters/inbound/useFontRuntime';
+import { createTheme } from '../../application/use-cases/createTheme';
+import { ThemeRuntimeContext } from './ThemeRuntimeContext';
+import { useTheme } from './useTheme';
+
+/*** Apply a nested Surface theme or mode override without remounting app-level providers. */
+export function ThemeScope({ children, themeConfig, mode }: ThemeScopeProps) {
+  const parent = useTheme();
+  const { activeFontId } = useFontRuntime();
+  const scopedMode = mode ?? parent.mode;
+  const scopedConfig = useMemo(
+    () => (themeConfig ? deepMerge(parent.theme.config, themeConfig) : parent.theme.config),
+    [parent.theme.config, themeConfig],
+  );
+  const theme = useMemo(
+    () => createTheme(scopedConfig, scopedMode, activeFontId),
+    [activeFontId, scopedConfig, scopedMode],
+  );
+  const value = useMemo<ThemeRuntime>(
+    () => ({ ...parent, theme, mode: scopedMode }),
+    [parent, scopedMode, theme],
+  );
+
+  return <ThemeRuntimeContext value={value}>{children}</ThemeRuntimeContext>;
+}

package/src/features/theme/adapters/inbound/useTheme.ts

@@ -0,0 +1,9 @@
+import { use } from 'react';
+
+import type { ThemeRuntime } from '../../../../types/theme';
+import { ThemeRuntimeContext } from './ThemeRuntimeContext';
+
+/*** Read the active Surface theme runtime. */
+export function useTheme(): ThemeRuntime {
+  return use(ThemeRuntimeContext);
+}