@ankhorage/zora 23.2.5 → 23.4.0

package/src/capabilities/index.ts

@@ -0,0 +1,63 @@
+import type { Capability } from '@ankhorage/contracts/capabilities';
+
+export const CAPABILITIES = [
+  {
+    id: 'zora.create',
+    owner: '@ankhorage/zora',
+    access: ['invoke'],
+    binding: {
+      kind: 'action',
+      bindableAs: ['target'],
+    },
+    label: 'Materialize ZORA web component',
+    description: 'Materialize a declared ZORA component and reconcile its web runtime.',
+    input: {
+      schema: {
+        type: 'object',
+        required: ['component', 'platform'],
+        properties: {
+          component: { type: 'string' },
+          platform: { type: 'string', const: 'web' },
+        },
+        additionalProperties: false,
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        required: ['exitCode'],
+        properties: { exitCode: { type: 'integer' } },
+        additionalProperties: false,
+      },
+    },
+  },
+  {
+    id: 'zora.sync',
+    owner: '@ankhorage/zora',
+    access: ['invoke'],
+    binding: {
+      kind: 'action',
+      bindableAs: ['target'],
+    },
+    label: 'Synchronize ZORA web components',
+    description: 'Reconcile the web runtime from the declared ZORA component set.',
+    input: {
+      schema: {
+        type: 'object',
+        required: ['platform'],
+        properties: {
+          platform: { type: 'string', const: 'web' },
+        },
+        additionalProperties: false,
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        required: ['exitCode'],
+        properties: { exitCode: { type: 'integer' } },
+        additionalProperties: false,
+      },
+    },
+  },
+] as const satisfies readonly Capability[];

package/src/cli/index.test.ts

@@ -1,11 +1,12 @@
 import { expect, test } from 'bun:test';
 
+import { CAPABILITIES } from '../capabilities';
 import provider from './index';
 
 test('publishes ZORA create and sync through the Ankh provider', () => {
   expect(provider.id).toBe('@ankhorage/zora');
   expect(provider.category).toBe('zora');
-  expect(provider.capabilities).toEqual(['zora.create', 'zora.sync']);
+  expect(provider.capabilities).toBe(CAPABILITIES);
   expect(provider.commands).toEqual([
     {
       path: ['create'],
@@ -22,3 +23,11 @@ test('publishes ZORA create and sync through the Ankh provider', () => {
   expect(provider.handlers[0]?.path).toEqual(['create']);
   expect(provider.handlers[1]?.path).toEqual(['sync']);
 });
+
+test('maps every provider command to one canonical capability independent of catalog order', () => {
+  const commandCapabilityIds = provider.commands.map((command) => command.capability);
+  const capabilityIds = CAPABILITIES.map((capability) => capability.id);
+
+  expect(new Set(commandCapabilityIds).size).toBe(commandCapabilityIds.length);
+  expect(new Set(commandCapabilityIds)).toEqual(new Set(capabilityIds));
+});

package/src/cli/index.ts

@@ -2,36 +2,29 @@ import { readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import type { AnkhCapabilityId, AnkhCommandProviderManifest } from '@ankhorage/contracts/cli';
+import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh';
+import type { Capability } from '@ankhorage/contracts/capabilities';
 
+import { CAPABILITIES } from '../capabilities';
 import { create } from './commands/create';
 import { sync } from './commands/sync';
 
-const CREATE_CAPABILITY = 'zora.create' satisfies AnkhCapabilityId;
-const SYNC_CAPABILITY = 'zora.sync' satisfies AnkhCapabilityId;
 const CREATE_COMMAND = {
   path: ['create'],
-  capability: CREATE_CAPABILITY,
+  capability: 'zora.create' satisfies Capability['id'],
   summary: 'Materialize a canonical ZORA component for a target platform.',
 } as const;
 const SYNC_COMMAND = {
   path: ['sync'],
-  capability: SYNC_CAPABILITY,
+  capability: 'zora.sync' satisfies Capability['id'],
   summary: 'Regenerate the declared ZORA web materialization.',
 } as const;
 
-interface ZoraRuntimeProvider extends AnkhCommandProviderManifest {
-  readonly handlers: readonly {
-    readonly path: readonly string[];
-    readonly handler: typeof create | typeof sync;
-  }[];
-}
-
 const provider = {
   id: '@ankhorage/zora',
   category: 'zora',
   version: readPackageVersion(),
-  capabilities: [CREATE_CAPABILITY, SYNC_CAPABILITY],
+  capabilities: CAPABILITIES,
   commands: [CREATE_COMMAND, SYNC_COMMAND],
   handlers: [
     {
@@ -43,7 +36,7 @@ const provider = {
       handler: sync,
     },
   ],
-} satisfies ZoraRuntimeProvider;
+} satisfies AnkhRuntimeCommandProvider;
 
 export default provider;
 

package/src/constants/authoring.ts

@@ -4,6 +4,13 @@ export const COMPONENT_THEME_AUTHORING = {
   allowInstanceOverride: true,
 } as const;
 
+export const INVERTED_POLARITY_PROP = {
+  type: 'boolean',
+  category: 'Theme',
+  label: 'Inverted surface polarity (inherits when omitted; false resets)',
+  authoring: { authority: 'instance' },
+} as const;
+
 export const FEATURE_MANIFEST_ELEMENTS = {
   auth: [
     'AuthScreen',

package/src/features/app-bar/appBarMeta.ts

@@ -1,3 +1,4 @@
+import { INVERTED_POLARITY_PROP } from '../../constants/authoring';
 import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const appBarMeta = {
@@ -6,5 +7,5 @@ export const appBarMeta = {
   directManifestNode: false,
   allowedChildren: [],
   note: 'Application chrome component; not represented as a manifest node in v1.',
-  props: {},
+  props: { inverted: INVERTED_POLARITY_PROP },
 } as const satisfies ZoraComponentMeta;

package/src/features/app-header/adapters/inbound/AppHeader.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+
+import type { AppHeaderProps } from '../../../../types/app-header';
+import { AppBar } from '../../../app-bar/public';
+
+/*** Composes application header chrome through the scoped ZORA AppBar. */
+export function AppHeader(props: AppHeaderProps) {
+  return <AppBar {...props} />;
+}

package/src/features/app-header/appHeaderMeta.ts

@@ -0,0 +1,13 @@
+import { INVERTED_POLARITY_PROP } from '../../constants/authoring';
+import type { ZoraComponentMeta } from '../../types/authoring';
+
+export const appHeaderMeta = {
+  name: 'AppHeader',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Application header built from AppBar. Inverted is inherited surface polarity; false resets the subtree to normal polarity.',
+  props: {
+    inverted: INVERTED_POLARITY_PROP,
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/app-header/public.ts

@@ -0,0 +1,2 @@
+export type { AppHeaderProps } from '../../types/app-header';
+export { AppHeader } from './adapters/inbound/AppHeader';

package/src/features/game/adapters/inbound/Game.tsx

@@ -2,6 +2,7 @@ import { RuntimeRendererConfigProvider } from '@ankhorage/runtime';
 import React from 'react';
 
 import type { GameProps } from '../../../../types/gamePresentation';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { createGameBindingContext } from '../../composition/createGameBindingContext';
 import { createGameMeasurementRegistry } from '../../composition/createGameMeasurementRegistry';
 import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
@@ -9,7 +10,10 @@ import { useGameRuntime } from '../../composition/useGameRuntime';
 import { GameField } from './GameField';
 
 /*** Bind one serializable game definition to a local transient session and presentation field. */
-export function Game(props: GameProps) {
+export const Game = withZoraThemeScope(GameInner);
+
+/*** Render the game session inside the inherited ZORA theme scope. */
+function GameInner(props: GameProps) {
   const runtime = useGameRuntime(props);
   const [measurementRegistry] = React.useState(createGameMeasurementRegistry);
   const runtimeContext = React.useMemo(

package/src/features/game/adapters/inbound/GameEntity.tsx

@@ -2,11 +2,15 @@ import React from 'react';
 import { Animated, StyleSheet, type View, type ViewStyle } from 'react-native';
 
 import type { GameEntityProps } from '../../../../types/gamePresentation';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { useGameEntityAnimatedStyle } from '../../utils/useGameEntityAnimatedStyle';
 import { useGameEntityMeasurement } from '../../utils/useGameEntityMeasurement';
 
 /*** Render one generic positioned game entity without owning gameplay semantics. */
-export function GameEntity(props: GameEntityProps) {
+export const GameEntity = withZoraThemeScope(GameEntityInner);
+
+/*** Render the positioned entity inside the inherited ZORA theme scope. */
+function GameEntityInner(props: GameEntityProps) {
   const elementRef = React.useRef<View | null>(null);
   const animatedStyle = useGameEntityAnimatedStyle(props);
   useGameEntityMeasurement(elementRef, props.measurementId);

package/src/features/game/adapters/inbound/GameField.tsx

@@ -2,9 +2,13 @@ import { StyleSheet } from 'react-native';
 
 import type { GameFieldProps } from '../../../../types/gamePresentation';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Render a bounded relative-positioning surface for game presentation content. */
-export function GameField({
+export const GameField = withZoraThemeScope(GameFieldInner);
+
+/*** Render the field inside the inherited ZORA theme scope. */
+function GameFieldInner({
   children,
   aspectRatio,
   minHeight = 320,

package/src/features/game/adapters/inbound/GameInputZone.tsx

@@ -1,11 +1,15 @@
 import { Platform, StyleSheet, View, type ViewStyle } from 'react-native';
 
 import type { GameInputZoneProps } from '../../../../types/gamePresentation';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { toGamePercentage } from '../../utils/toGamePercentage';
 import { useGameInputZoneResponder } from './useGameInputZoneResponder';
 
 /*** Capture pointer/touch geometry and optional keyboard input as normalized generic Game events. */
-export function GameInputZone({
+export const GameInputZone = withZoraThemeScope(GameInputZoneInner);
+
+/*** Capture game input inside the inherited ZORA theme scope. */
+function GameInputZoneInner({
   x = 0,
   y = 0,
   width = 100,

package/src/features/game/adapters/inbound/GameMeasurementProbe.tsx

@@ -2,11 +2,15 @@ import React from 'react';
 
 import type { GameMeasurementProbeProps } from '../../../../types/gamePresentation';
 import type { GameRuntimeContextValue } from '../../../../types/gameRuntime';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { GameRuntimeContext } from '../../composition/GameRuntimeContext';
 import { createGameMeasurementEvent } from './createGameMeasurementEvent';
 
 /*** Measure two registered game entities and dispatch only their raw rendered geometry. */
-export function GameMeasurementProbe({
+export const GameMeasurementProbe = withZoraThemeScope(GameMeasurementProbeInner);
+
+/*** Measure geometry inside the inherited ZORA theme scope. */
+function GameMeasurementProbeInner({
   sourceId,
   targetId,
   eventType = 'game.measurement',

package/src/features/game/adapters/inbound/GameOverlay.tsx

@@ -2,9 +2,13 @@ import { StyleSheet, type ViewStyle } from 'react-native';
 
 import type { GameOverlayPlacement, GameOverlayProps } from '../../../../types/gamePresentation';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Render an absolute game presentation layer for HUD, feedback, and phase content. */
-export function GameOverlay({
+export const GameOverlay = withZoraThemeScope(GameOverlayInner);
+
+/*** Render the overlay inside the inherited ZORA theme scope. */
+function GameOverlayInner({
   children,
   placement = 'fill',
   blocking = false,

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -5,6 +5,7 @@ import type { ZoraComponentRegistry } from '../../types/registry';
 import { Accordion, AccordionItem } from '../accordion/public';
 import { ActivityIndicator } from '../activity-indicator/public';
 import { AppBar } from '../app-bar/public';
+import { AppHeader } from '../app-header/public';
 import {
   AuthScreen,
   ForgotPasswordForm,
@@ -108,6 +109,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   AccordionItem,
   ActivityIndicator,
   AppBar,
+  AppHeader,
   Avatar,
   AvatarGroup,
   Badge,

package/src/features/registry/authoringMeta.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
+import { INVERTED_POLARITY_PROP } from '../../constants/authoring';
 import { ZORA_COMPONENT_META, type ZoraComponentPropAuthoring } from '.';
 
 const componentMetaByName = new Map(Object.entries(ZORA_COMPONENT_META));
@@ -43,4 +44,14 @@ describe('ZORA component prop authoring authority', () => {
   test('does not introduce a system authority', () => {
     expect(JSON.stringify(ZORA_COMPONENT_META)).not.toContain('"authority":"system"');
   });
+
+  test('describes inherited surface polarity for every direct manifest component', () => {
+    for (const [name, meta] of componentMetaByName) {
+      if (!meta.directManifestNode) continue;
+      expect(meta.props.inverted, name).toEqual(INVERTED_POLARITY_PROP);
+      expect(meta.bindings?.props?.inverted?.value.type, name).toBe('boolean');
+    }
+    expect(ZORA_COMPONENT_META.AppBar.props.inverted).toEqual(INVERTED_POLARITY_PROP);
+    expect(ZORA_COMPONENT_META.AppHeader.props.inverted).toEqual(INVERTED_POLARITY_PROP);
+  });
 });

package/src/features/registry/bindableComponentMeta.ts

@@ -1,5 +1,6 @@
 import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
 
+import { INVERTED_POLARITY_PROP } from '../../constants/authoring';
 import { imageMeta } from '../image/imageMeta';
 import { readerSurfaceMeta } from '../reader/meta';
 
@@ -22,6 +23,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       text: {
         type: 'string',
         category: 'Content',
@@ -47,6 +49,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       text: {
         type: 'string',
         category: 'Content',
@@ -97,6 +100,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       children: {
         type: 'string',
         category: 'Content',
@@ -111,6 +115,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
   },
   Image: {
     ...imageMeta,
+    props: { ...imageMeta.props, inverted: INVERTED_POLARITY_PROP },
     bindings: {
       props: {
         source: {
@@ -174,6 +179,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       value: {
         type: 'string',
         category: 'Content',
@@ -229,6 +235,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       value: {
         type: 'string',
         category: 'Content',
@@ -284,6 +291,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       checked: {
         type: 'boolean',
         category: 'State',
@@ -339,6 +347,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       checked: { type: 'boolean', category: 'State', label: 'Checked' },
       disabled: { type: 'boolean', category: 'State', label: 'Disabled' },
     },
@@ -364,6 +373,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       items: {
         type: 'array',
         category: 'Data',
@@ -392,6 +402,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
     props: {
+      inverted: INVERTED_POLARITY_PROP,
       rows: {
         type: 'array',
         category: 'Data',
@@ -401,6 +412,7 @@ export const ZORA_BINDABLE_COMPONENT_META = {
   },
   ReaderSurface: {
     ...readerSurfaceMeta,
+    props: { ...readerSurfaceMeta.props, inverted: INVERTED_POLARITY_PROP },
     bindings: {
       props: {
         location: {

package/src/features/registry/componentMeta.ts

@@ -3,6 +3,7 @@ import { accordionItemMeta } from '../accordion/accordionItemMeta';
 import { accordionMeta } from '../accordion/accordionMeta';
 import { activityIndicatorMeta } from '../activity-indicator/activityIndicatorMeta';
 import { appBarMeta } from '../app-bar/appBarMeta';
+import { appHeaderMeta } from '../app-header/appHeaderMeta';
 import { authScreenMeta } from '../auth/authScreenMeta';
 import { forgotPasswordFormMeta } from '../auth/forgotPasswordFormMeta';
 import { oauthProviderButtonMeta } from '../auth/oauthProviderButtonMeta';
@@ -115,6 +116,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   Divider: dividerMeta,
   Surface: surfaceMeta,
   AppBar: appBarMeta,
+  AppHeader: appHeaderMeta,
   Avatar: avatarMeta,
   AvatarGroup: avatarGroupMeta,
   Badge: badgeMeta,

package/src/features/registry/finalizeFeatureMetadata.ts

@@ -1,20 +1,21 @@
-import { FEATURE_MANIFEST_ELEMENTS } from '../../constants/authoring';
-import type { ZoraComponentMetaRegistry } from '../../types/authoring';
+import { INVERTED_POLARITY_PROP } from '../../constants/authoring';
+import type { ZoraComponentMeta, ZoraComponentMetaRegistry } from '../../types/authoring';
 import { createManifestBindings } from './createManifestBindings';
 
 /*** Completes feature bindings while preserving each component's explicit value contracts. */
 export function finalizeFeatureMetadata(
   registry: ZoraComponentMetaRegistry,
 ): ZoraComponentMetaRegistry {
-  const names: ReadonlySet<string> = new Set(Object.values(FEATURE_MANIFEST_ELEMENTS).flat());
   return Object.fromEntries(
-    Object.entries(registry).map(([name, meta]) => {
-      if (!names.has(name)) return [name, meta];
-      const bindings = createManifestBindings(meta.props, meta.events);
+    Object.entries(registry).map(([name, meta]): [string, ZoraComponentMeta] => {
+      if (!meta.directManifestNode) return [name, meta];
+      const props = { ...meta.props, inverted: INVERTED_POLARITY_PROP };
+      const bindings = createManifestBindings(props, meta.events);
       return [
         name,
         {
           ...meta,
+          props,
           bindings: {
             props: { ...bindings.props, ...meta.bindings?.props },
             events: { ...bindings.events, ...meta.bindings?.events },

package/src/features/registry/registry.test.ts

@@ -76,6 +76,7 @@ describe('ZORA_COMPONENT_REGISTRY', () => {
     expect(registry).toEqual({});
     expect(registryEntries).toContain('Screen');
     expect(registryEntries).toContain('View');
+    expect(registryEntries).toContain('AppHeader');
     expect(source).toContain("export type { ZoraComponentRegistry } from './types/registry';");
     expect(source).toContain(
       "export { ZORA_COMPONENT_REGISTRY } from './features/registry/public';",

package/src/features/selection/adapters/inbound/SelectableItem.tsx

@@ -8,6 +8,7 @@ import type {
   SelectableItemState,
   SelectionTrigger,
 } from '../../../../types/selection';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { resolveSelectionEventIntent } from '../../application/resolveSelectionEventIntent';
 import { useSelection } from './SelectionProvider';
 
@@ -24,7 +25,10 @@ function isRenderProp(
 }
 
 /*** Adds selection behavior to arbitrary child content via render props. */
-export function SelectableItem({
+export const SelectableItem = withZoraThemeScope(SelectableItemInner);
+
+/*** Render a selectable item inside the inherited ZORA theme scope. */
+function SelectableItemInner({
   id,
   trigger,
   disabled = false,

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

@@ -2,8 +2,13 @@ import type { ThemeModeToggleProps } from '../../../../types/theme-mode-toggle';
 import { IconButton } from '../../../button/public';
 import { useZoraTheme } from '../../composition/useZoraTheme';
 import { resolveThemeModeToggleState } from '../../utils/resolveThemeModeToggleState';
+import { withZoraThemeScope } from './withZoraThemeScope';
 
-export function ThemeModeToggle({
+/*** Provide a theme mode control with inherited surface polarity. */
+export const ThemeModeToggle = withZoraThemeScope(ThemeModeToggleInner);
+
+/*** Render the control from the active theme mode. */
+function ThemeModeToggleInner({
   disabled,
   interactionPolicy,
   size = 'm',

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

@@ -12,20 +12,21 @@ export interface ZoraThemeScopeProps {
   children: React.ReactNode;
   themeId?: ZoraThemeId;
   mode?: ZoraThemeMode;
+  inverted?: boolean;
 }
 
 /*** 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;
+export function ZoraThemeScope({ children, themeId, mode, inverted }: ZoraThemeScopeProps) {
+  if (mode === undefined && themeId === undefined && inverted === undefined) return children;
   return (
-    <ZoraThemeScopeInner mode={mode} themeId={themeId}>
+    <ZoraThemeScopeInner mode={mode} themeId={themeId} inverted={inverted}>
       {children}
     </ZoraThemeScopeInner>
   );
 }
 
 /*** Resolves and provides the scoped Surface and ZORA theme runtime values. */
-function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
+function ZoraThemeScopeInner({ children, themeId, mode, inverted }: ZoraThemeScopeProps) {
   const parentRuntime = useZoraThemeRuntime();
   const scopedThemeId = resolveZoraScopedThemeId({
     desiredThemeId: themeId,
@@ -33,7 +34,13 @@ function ZoraThemeScopeInner({ children, themeId, mode }: ZoraThemeScopeProps) {
   });
   const scopedRuntimeValue = useMemo(() => ({ themeId: scopedThemeId }), [scopedThemeId]);
   const scopedChildren =
-    mode === undefined ? children : <ThemeScope mode={mode}>{children}</ThemeScope>;
+    mode === undefined && inverted === undefined ? (
+      children
+    ) : (
+      <ThemeScope mode={mode} inverted={inverted}>
+        {children}
+      </ThemeScope>
+    );
 
   return (
     <ZoraThemeRuntimeContext value={scopedRuntimeValue}>{scopedChildren}</ZoraThemeRuntimeContext>

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

@@ -3,17 +3,22 @@ import React from 'react';
 import type { ZoraBaseProps } from '../../../../types/base';
 import { ZoraThemeScope } from './ZoraThemeScope';
 
+/*** Applies optional theme and polarity overrides to any ZORA component. */
 export function withZoraThemeScope<P extends ZoraBaseProps>(
   Component: (props: P) => React.ReactElement | null,
 ): (props: P) => React.ReactElement | null {
   const Wrapped = (props: P) => {
-    if (props.mode === undefined && props.themeId === undefined) {
-      return React.createElement(Component, props);
+    const componentProps = { ...props };
+    delete componentProps.themeId;
+    delete componentProps.mode;
+    delete componentProps.inverted;
+    if (props.mode === undefined && props.themeId === undefined && props.inverted === undefined) {
+      return React.createElement(Component, componentProps);
     }
 
     return (
-      <ZoraThemeScope mode={props.mode} themeId={props.themeId}>
-        {React.createElement(Component, props)}
+      <ZoraThemeScope mode={props.mode} themeId={props.themeId} inverted={props.inverted}>
+        {React.createElement(Component, componentProps)}
       </ZoraThemeScope>
     );
   };

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

@@ -27,7 +27,7 @@ describe('canonical ThemeConfig scope propagation', () => {
   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).toContain('<ThemeScope mode={mode} inverted={inverted}>');
     expect(scope).not.toContain('parentSurface');
     expect(scope).not.toContain('sourceConfig');
     expect(scope).not.toContain('createTheme');

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

@@ -178,6 +178,7 @@ describe('theme scope structure', () => {
   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).toMatch(/inverted=\{inverted\}/u);
     expect(themeScopeSource).not.toMatch(/ThemeContext/u);
     expect(themeScopeSource).not.toMatch(/useFontContext/u);
     expect(themeScopeSource).not.toMatch(/createTheme\(/u);
@@ -185,9 +186,13 @@ describe('theme scope structure', () => {
     expect(themeScopeSource).not.toMatch(/<ThemeProvider\b/u);
   });
 
-  it('wraps components only when mode/themeId overrides are present', () => {
+  it('wraps components only when mode/themeId/inverted overrides are present', () => {
     expect(hocSource).toMatch(/props\.mode === undefined/u);
     expect(hocSource).toMatch(/props\.themeId === undefined/u);
+    expect(hocSource).toMatch(/props\.inverted === undefined/u);
+    expect(hocSource).toMatch(/delete componentProps\.themeId/u);
+    expect(hocSource).toMatch(/delete componentProps\.mode/u);
+    expect(hocSource).toMatch(/delete componentProps\.inverted/u);
     expect(hocSource).toMatch(/<ZoraThemeScope/u);
   });
 

package/src/index.ts

@@ -13,6 +13,7 @@ export {
 } from './features/activity-indicator/public';
 export type { AppBarMode, AppBarOverflowMenu, AppBarProps } from './features/app-bar/public';
 export { AppBar } from './features/app-bar/public';
+export { AppHeader, type AppHeaderProps } from './features/app-header/public';
 export type {
   AuthFormBaseProps,
   AuthIdentifierKind,