@ankhorage/zora 18.0.1 → 19.0.1

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

@@ -1,8 +1,8 @@
 import { View as SurfaceView } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ViewProps } from '../../../../types/layout';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Adapts the token-aware Surface View primitive to ZORA theme scope. */
 export const View = withZoraThemeScope(ViewInner);

package/src/features/layout/appShellMeta.ts

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

package/src/features/layout/constants.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const LAYOUT_PROPS = {
   p: { type: 'spacing', category: 'Spacing' },

package/src/features/layout/dividerMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 import { LAYOUT_PROPS } from './constants';
 
 export const dividerMeta = {

package/src/features/layout/gridMeta.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 './constants';
 
 export const gridMeta = {

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

@@ -23,15 +23,7 @@ const removedPublicNames = [
 
 describe('canonical layout boundary', () => {
   test('exports only the current layout primitives and semantic screen composition', () => {
-    for (const name of [
-      'AppShell',
-      'Divider',
-      'Grid',
-      'Screen',
-      'ScreenSection',
-      'ScrollView',
-      'View',
-    ]) {
+    for (const name of ['AppShell', 'Divider', 'Grid', 'Screen', 'ScrollView', 'View']) {
       expect(publicSource).toMatch(new RegExp(`\\b${name}\\b`, 'u'));
     }
 
@@ -44,12 +36,12 @@ describe('canonical layout boundary', () => {
   test('does not retain the legacy layout or foundation ownership roots', () => {
     expect(existsSync(join(srcDir, 'layout'))).toBe(false);
     expect(existsSync(join(srcDir, 'foundation'))).toBe(false);
-    expect(existsSync(join(srcDir, 'patterns', 'settings-row'))).toBe(false);
-    expect(existsSync(join(srcDir, 'patterns', 'tile-grid'))).toBe(false);
+    expect(existsSync(join(srcDir, 'patterns'))).toBe(false);
   });
 
   test('keeps moved capabilities with their singular feature owners', () => {
     expect(existsSync(join(srcDir, 'features', 'content-rail', 'public.ts'))).toBe(true);
     expect(existsSync(join(srcDir, 'features', 'palette-item', 'public.ts'))).toBe(true);
+    expect(existsSync(join(srcDir, 'features', 'section', 'public.ts'))).toBe(true);
   });
 });

package/src/features/layout/public.ts

@@ -3,7 +3,6 @@ export type {
   DividerProps,
   GridProps,
   ScreenProps,
-  ScreenSectionProps,
   ScrollViewProps,
   ViewProps,
 } from '../../types/layout';
@@ -11,6 +10,5 @@ export { AppShell } from './adapters/inbound/AppShell';
 export { Divider } from './adapters/inbound/Divider';
 export { Grid } from './adapters/inbound/Grid';
 export { Screen } from './adapters/inbound/Screen';
-export { ScreenSection } from './adapters/inbound/ScreenSection';
 export { ScrollView } from './adapters/inbound/ScrollView';
 export { View } from './adapters/inbound/View';

package/src/features/layout/screenMeta.ts

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

package/src/features/layout/scrollViewMeta.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 './constants';
 
 export const scrollViewMeta = {

package/src/features/layout/utils/resolvePageMaxWidth.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolvePageMaxWidth } from './resolvePageMaxWidth';
+
+describe('resolvePageMaxWidth', () => {
+  test('keeps page width presets ordered', () => {
+    expect(resolvePageMaxWidth('wide')).toBeGreaterThan(resolvePageMaxWidth('default'));
+    expect(resolvePageMaxWidth('default')).toBeGreaterThan(resolvePageMaxWidth('narrow'));
+  });
+});

package/src/features/layout/utils/resolvePageMaxWidth.ts

@@ -0,0 +1,13 @@
+import type { ZoraContentWidth } from '../../../types/layout';
+
+export function resolvePageMaxWidth(width: ZoraContentWidth = 'default'): number {
+  switch (width) {
+    case 'narrow':
+      return 760;
+    case 'wide':
+      return 1280;
+    case 'default':
+    default:
+      return 1040;
+  }
+}

package/src/features/layout/viewMeta.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 './constants';
 
 export const viewMeta = {

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

@@ -1,8 +1,8 @@
 import React from 'react';
 import { FlatList as NativeFlatList } from 'react-native';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ManifestListProps } from '../../../../types/manifest-list';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Text } from '../../../typography/public';
 import { HorizontalListSeparator } from './HorizontalListSeparator';
 import { useListVisibility } from './useListVisibility';

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

@@ -1,7 +1,6 @@
 import { List as SurfaceList } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type {
   ListItemProps,
   ListItemsProps,
@@ -9,6 +8,7 @@ import type {
   ListProps,
 } from '../../../../types/list';
 import { Divider, View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { resolveListSeparator } from '../../utils/resolveListSeparator';
 import { ListItem } from './ListItem';
 

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

@@ -1,10 +1,10 @@
 import { ListItem as SurfaceListItem } from '@ankhorage/surface';
 import React from 'react';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ListItemProps, ListItemVariant } from '../../../../types/list';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Text } from '../../../typography/public';
 
 function ListItemInner({

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

@@ -1,9 +1,9 @@
 import React from 'react';
 
-import { SectionHeader } from '../../../../patterns/section-header';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ListSectionProps } from '../../../../types/list';
 import { View } from '../../../layout/public';
+import { SectionHeader } from '../../../section/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { List } from './List';
 
 function ListSectionInner({

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

@@ -1,8 +1,8 @@
 import React from 'react';
 import { SectionList as NativeSectionList } from 'react-native';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { ManifestSectionListProps } from '../../../../types/manifest-list';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Text } from '../../../typography/public';
 import { partitionListSections } from '../../application/use-cases/partitionListSections';
 import { HorizontalListSeparator } from './HorizontalListSeparator';

package/src/features/list/flatListMeta.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 flatListMeta = {
   name: 'FlatList',

package/src/features/list/meta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 const LIST_NOTE =
   'List feature component; collection authoring is represented through List metadata.';

package/src/features/list/sectionListMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 import { flatListMeta } from './flatListMeta';
 
 export const sectionListMeta = {

package/src/features/missing-element/MissingElement.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { ZORA_BINDABLE_COMPONENT_META, ZORA_COMPONENT_META } from '../../metadata';
+import { ZORA_BINDABLE_COMPONENT_META, ZORA_COMPONENT_META } from '../authoring';
 import { missingElementMeta } from './missingElementMeta';
 
 describe('MissingElement draft contract', () => {
@@ -13,7 +13,7 @@ describe('MissingElement draft contract', () => {
       availability: 'draft-only',
       releaseGate: 'blocked',
     });
-    expect(ZORA_COMPONENT_META.Notice.manifestPolicy).toBeUndefined();
+    expect(ZORA_COMPONENT_META.Card.manifestPolicy).toBeUndefined();
     expect(ZORA_COMPONENT_META.EmptyState.manifestPolicy).toBeUndefined();
   });
 
@@ -63,6 +63,6 @@ describe('MissingElement draft contract', () => {
     expect(types).toContain('MissingElementProps extends ZoraBaseProps');
     expect(source).toContain('interactionPolicy: _interactionPolicy');
     expect(source).not.toMatch(/onPress|onLongPress|onChange|onSubmit/);
-    expect(source).not.toMatch(/<Button|<IconButton|<Notice|<EmptyState/);
+    expect(source).not.toMatch(/<Button|<IconButton|<EmptyState/);
   });
 });

package/src/features/missing-element/adapters/inbound/MissingElement.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 { MissingElementProps } from '../../../../types/missing-element';
 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';
 
 /***

package/src/features/missing-element/missingElementMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 const instanceAuthoring = { authority: 'instance' } as const;
 

package/src/features/pagination/adapters/inbound/Pagination.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { PaginationProps } from '../../../../types/pagination';
 import { Button } from '../../../button/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Text } from '../../../typography/public';
 import { resolvePaginationPage } from '../../utils/resolvePaginationPage';
 import { resolvePaginationState } from '../../utils/resolvePaginationState';

package/src/features/pagination/paginationMeta.ts

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

package/src/features/palette-item/adapters/inbound/PaletteItem.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { PaletteItemProps } from '../../../../types/palette-item';
 import { Card } from '../../../card/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Heading } from '../../../typography/public';
 import { Text } from '../../../typography/public';
 

package/src/features/palette-item/paletteItemMeta.ts

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

package/src/features/plugin/ZORA_CORE_PLUGIN.ts

@@ -0,0 +1,9 @@
+import type { ZoraPluginDescriptor } from '../../types/plugin';
+import { ZORA_COMPONENT_REGISTRY } from '../registry/ZORA_COMPONENT_REGISTRY';
+import { ZORA_CORE_PLUGIN_METADATA } from './ZORA_CORE_PLUGIN_METADATA';
+
+/*** Describe the complete ZORA core runtime and authoring surface through the public plugin contract. */
+export const ZORA_CORE_PLUGIN: ZoraPluginDescriptor = {
+  ...ZORA_CORE_PLUGIN_METADATA,
+  componentRegistry: ZORA_COMPONENT_REGISTRY,
+};

package/src/features/plugin/ZORA_CORE_PLUGIN_METADATA.ts

@@ -0,0 +1,49 @@
+import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
+
+import type { ZoraComponentMetaRegistry } from '../../types/authoring';
+import type { ZoraPluginMetadata } from '../../types/plugin';
+import { ZORA_BINDABLE_COMPONENT_META } from '../authoring/bindableComponentMeta';
+import { ZORA_COMPONENT_META } from '../authoring/componentMeta';
+
+const CORE_EXTENSION_HOSTS = [
+  'Card',
+  'Grid',
+  'MessageBubble',
+  'PostCard',
+  'Screen',
+  'ScreenSection',
+  'View',
+] as const;
+
+export const ZORA_CORE_PLUGIN_METADATA: ZoraPluginMetadata = {
+  packageName: '@ankhorage/zora',
+  displayName: 'ZORA',
+  componentMeta: mergeBindableMeta(ZORA_COMPONENT_META, ZORA_BINDABLE_COMPONENT_META),
+  extensionHosts: CORE_EXTENSION_HOSTS,
+};
+
+function mergeBindableMeta(
+  componentMeta: ZoraComponentMetaRegistry,
+  bindableMeta: UiComponentMetaRegistry,
+): ZoraComponentMetaRegistry {
+  const bindingsByComponent = new Map(
+    Object.entries(bindableMeta).map(([componentName, meta]) => [componentName, meta.bindings]),
+  );
+  return Object.fromEntries(
+    Object.entries(componentMeta).map(([componentName, meta]) => [
+      componentName,
+      bindingsByComponent.get(componentName)
+        ? {
+            ...meta,
+            bindings: {
+              props: { ...bindingsByComponent.get(componentName)?.props, ...meta.bindings?.props },
+              events: {
+                ...bindingsByComponent.get(componentName)?.events,
+                ...meta.bindings?.events,
+              },
+            },
+          }
+        : meta,
+    ]),
+  );
+}

package/src/features/plugin/application/use-cases/composeZoraPluginMetadata.ts

@@ -0,0 +1,166 @@
+import type { ZoraComponentMeta } from '../../../../types/authoring';
+import type {
+  ComposedZoraPluginMetadataCatalog,
+  ZoraPluginCompositionErrorCode,
+  ZoraPluginMetadata,
+  ZoraPluginPlacement,
+} from '../../../../types/plugin';
+import { ZoraPluginCompositionError } from '../../domain/ZoraPluginCompositionError';
+
+/*** Compose a selected ZORA metadata set for authoring tools that must not load React Native runtime modules. */
+export function composeZoraPluginMetadata(
+  plugins: readonly ZoraPluginMetadata[],
+): ComposedZoraPluginMetadataCatalog {
+  const descriptors = sortPlugins(plugins);
+  const packages = new Set<string>();
+  const componentOwners = new Map<string, string>();
+  const componentMeta = new Map<string, ZoraComponentMeta>();
+  const extensionHosts = new Set<string>();
+  const interactionPolicySupportedComponents = new Set<string>();
+
+  for (const descriptor of descriptors) {
+    validateUniquePackage(descriptor, packages);
+    validateMetadata(descriptor);
+    for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+      claimComponent(componentName, descriptor.packageName, componentOwners);
+      componentMeta.set(componentName, meta);
+    }
+    for (const componentName of descriptor.extensionHosts ?? []) extensionHosts.add(componentName);
+    for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {
+      interactionPolicySupportedComponents.add(componentName);
+    }
+  }
+
+  for (const descriptor of descriptors) {
+    for (const placement of descriptor.placements ?? []) {
+      applyPlacement({ descriptor, placement, componentMeta, extensionHosts });
+    }
+  }
+
+  return {
+    componentMeta: Object.fromEntries(componentMeta),
+    bindableComponentMeta: Object.fromEntries(componentMeta),
+    packageManifests: descriptors.map(({ packageName, displayName, componentMeta: meta }) => ({
+      packageName,
+      ...(displayName === undefined ? {} : { displayName }),
+      components: meta,
+    })),
+    interactionPolicySupportedComponents: Object.fromEntries(
+      [...interactionPolicySupportedComponents]
+        .sort()
+        .map((componentName) => [componentName, true]),
+    ),
+  };
+}
+
+function validateUniquePackage(descriptor: ZoraPluginMetadata, packages: Set<string>): void {
+  if (packages.has(descriptor.packageName)) {
+    throw compositionError(
+      'duplicate-package',
+      descriptor.packageName,
+      `Duplicate ZORA plugin package '${descriptor.packageName}'.`,
+    );
+  }
+  packages.add(descriptor.packageName);
+}
+
+function validateMetadata(descriptor: ZoraPluginMetadata): void {
+  for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+    if (meta.name !== componentName) {
+      throw compositionError(
+        'invalid-component-meta',
+        descriptor.packageName,
+        `ZORA plugin '${descriptor.packageName}' metadata key '${componentName}' does not match meta.name '${meta.name}'.`,
+        componentName,
+      );
+    }
+  }
+}
+
+function claimComponent(
+  componentName: string,
+  packageName: string,
+  owners: Map<string, string>,
+): void {
+  const existingOwner = owners.get(componentName);
+  if (existingOwner) {
+    throw compositionError(
+      'duplicate-component',
+      packageName,
+      `ZORA component '${componentName}' is owned by both '${existingOwner}' and '${packageName}'.`,
+      componentName,
+    );
+  }
+  owners.set(componentName, packageName);
+}
+
+function applyPlacement(args: {
+  descriptor: ZoraPluginMetadata;
+  placement: ZoraPluginPlacement;
+  componentMeta: Map<string, ZoraComponentMeta>;
+  extensionHosts: ReadonlySet<string>;
+}): void {
+  const { descriptor, placement, componentMeta, extensionHosts } = args;
+  const childMeta = descriptor.componentMeta[placement.child];
+  if (!childMeta?.directManifestNode) {
+    throw compositionError(
+      'invalid-placement-child',
+      descriptor.packageName,
+      `ZORA plugin '${descriptor.packageName}' placement child '${placement.child}' is not an owned direct manifest node.`,
+      placement.child,
+    );
+  }
+  for (const parentName of [...placement.parents].sort()) {
+    const parentMeta = componentMeta.get(parentName);
+    if (!parentMeta || !extensionHosts.has(parentName)) {
+      throw compositionError(
+        'invalid-placement-parent',
+        descriptor.packageName,
+        `ZORA plugin '${descriptor.packageName}' placement parent '${parentName}' is not a declared extension host.`,
+        placement.child,
+      );
+    }
+    componentMeta.set(parentName, addAllowedChild(parentMeta, placement.child));
+  }
+}
+
+function addAllowedChild(meta: ZoraComponentMeta, child: string): ZoraComponentMeta {
+  const allowedChildren = appendUnique(meta.allowedChildren, child);
+  const childrenSlot = meta.slots?.children;
+  return {
+    ...meta,
+    allowedChildren,
+    ...(childrenSlot
+      ? {
+          slots: {
+            ...meta.slots,
+            children: {
+              ...childrenSlot,
+              allowedChildren: appendUnique(childrenSlot.allowedChildren ?? [], child),
+            },
+          },
+        }
+      : {}),
+  };
+}
+
+function appendUnique(values: readonly string[], value: string): readonly string[] {
+  return values.includes(value) ? values : [...values, value];
+}
+
+function sortedEntries<T>(value: Readonly<Record<string, T>>): [string, T][] {
+  return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+}
+
+function sortPlugins<T extends ZoraPluginMetadata>(plugins: readonly T[]): T[] {
+  return [...plugins].sort((left, right) => left.packageName.localeCompare(right.packageName));
+}
+
+function compositionError(
+  code: ZoraPluginCompositionErrorCode,
+  packageName: string,
+  message: string,
+  componentName?: string,
+): ZoraPluginCompositionError {
+  return new ZoraPluginCompositionError({ code, packageName, message, componentName });
+}

package/src/features/plugin/application/use-cases/composeZoraPlugins.ts

@@ -0,0 +1,76 @@
+import type {
+  ComposedZoraPluginCatalog,
+  ZoraPluginCompositionErrorCode,
+  ZoraPluginDescriptor,
+} from '../../../../types/plugin';
+import type { ZoraComponentRegistry } from '../../../../types/registry';
+import { ZoraPluginCompositionError } from '../../domain/ZoraPluginCompositionError';
+import { composeZoraPluginMetadata } from './composeZoraPluginMetadata';
+
+/*** Compose a selected ZORA core/plugin descriptor set into one validated authoring/runtime catalog. */
+export function composeZoraPlugins(
+  plugins: readonly ZoraPluginDescriptor[],
+): ComposedZoraPluginCatalog {
+  const descriptors = [...plugins].sort((left, right) =>
+    left.packageName.localeCompare(right.packageName),
+  );
+  const componentRegistry = new Map<string, ZoraComponentRegistry[string]>();
+
+  for (const descriptor of descriptors) {
+    validateRuntime(descriptor);
+    for (const [componentName, component] of sortedEntries(descriptor.componentRegistry)) {
+      componentRegistry.set(componentName, component);
+    }
+  }
+  const metadataCatalog = composeZoraPluginMetadata(descriptors);
+
+  return { ...metadataCatalog, componentRegistry: Object.fromEntries(componentRegistry) };
+}
+
+function validateRuntime(descriptor: ZoraPluginDescriptor): void {
+  const componentMetaNames = new Set(Object.keys(descriptor.componentMeta));
+  const runtimeComponentNames = new Set(Object.keys(descriptor.componentRegistry));
+  for (const componentName of Object.keys(descriptor.componentRegistry).sort()) {
+    if (!componentMetaNames.has(componentName)) {
+      throw compositionError(
+        'missing-component-meta',
+        descriptor.packageName,
+        `ZORA plugin '${descriptor.packageName}' registers runtime component '${componentName}' without component metadata.`,
+        componentName,
+      );
+    }
+  }
+  for (const [componentName, meta] of sortedEntries(descriptor.componentMeta)) {
+    if (meta.directManifestNode && !runtimeComponentNames.has(componentName)) {
+      throw compositionError(
+        'missing-runtime-component',
+        descriptor.packageName,
+        `ZORA plugin '${descriptor.packageName}' exposes direct manifest node '${componentName}' without a runtime component.`,
+        componentName,
+      );
+    }
+  }
+  for (const componentName of descriptor.interactionPolicySupportedComponents ?? []) {
+    if (!runtimeComponentNames.has(componentName)) {
+      throw compositionError(
+        'invalid-interaction-policy-component',
+        descriptor.packageName,
+        `ZORA plugin '${descriptor.packageName}' declares interaction-policy support for unregistered component '${componentName}'.`,
+        componentName,
+      );
+    }
+  }
+}
+
+function sortedEntries<T>(value: Readonly<Record<string, T>>): [string, T][] {
+  return Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+}
+
+function compositionError(
+  code: ZoraPluginCompositionErrorCode,
+  packageName: string,
+  message: string,
+  componentName?: string,
+): ZoraPluginCompositionError {
+  return new ZoraPluginCompositionError({ code, packageName, message, componentName });
+}

package/src/features/plugin/domain/ZoraPluginCompositionError.ts

@@ -0,0 +1,21 @@
+import type { ZoraPluginCompositionErrorCode } from '../../../types/plugin';
+
+/*** Report one deterministic plugin composition contract violation. */
+export class ZoraPluginCompositionError extends Error {
+  readonly code: ZoraPluginCompositionErrorCode;
+  readonly packageName: string;
+  readonly componentName?: string;
+
+  constructor(args: {
+    readonly code: ZoraPluginCompositionErrorCode;
+    readonly packageName: string;
+    readonly message: string;
+    readonly componentName?: string;
+  }) {
+    super(args.message);
+    this.name = 'ZoraPluginCompositionError';
+    this.code = args.code;
+    this.packageName = args.packageName;
+    this.componentName = args.componentName;
+  }
+}