@ankhorage/contracts 11.1.0 → 12.0.1

package/src/navigator/planning.ts

@@ -7,13 +7,14 @@ import type {
   StackScreenOptions,
 } from '../navigator';
 import type { CustomNavigatorRegistry } from './extensions';
+import type { NavigatorDependencyRequirement } from './generation';
 
-export interface ResolvedCustomTabsPresentation {
+export interface ResolvedHeadlessTabsPresentation {
   presentation: ResolvedTabsPresentation;
   customPresentationId?: string;
 }
 
-export type ResolvedTabsImplementation = 'custom' | 'javascript' | 'native';
+export type ResolvedTabsImplementation = 'headless' | 'javascript' | 'native';
 
 export type ResolvedTabsPresentation = 'bottom' | 'top' | 'rail' | 'sidebar' | 'custom';
 
@@ -60,7 +61,7 @@ export type NavigatorAdapterId =
   | 'drawer'
   | 'tabs.native'
   | 'tabs.javascript'
-  | 'tabs.custom'
+  | 'tabs.headless'
   | 'split-view'
   | 'custom';
 
@@ -76,6 +77,8 @@ export interface NavigatorAdapterPlan {
 
 export type NavigatorApiStability = 'stable' | 'alpha';
 
+export type NavigatorCapabilityId = string;
+
 export interface NavigatorDiagnostic {
   code: string;
   severity: 'error' | 'warning';
@@ -115,11 +118,9 @@ export interface NavigatorPlan {
   context: NavigatorValidationContext;
   root: NavigatorNodePlan;
   diagnostics: readonly NavigatorDiagnostic[];
-  supported: boolean;
-  flows: {
-    onboarding: boolean;
-    authentication: boolean;
-  };
+  support: NavigatorSupportStatus;
+  capabilityIds: readonly NavigatorCapabilityId[];
+  dependencies: readonly NavigatorDependencyRequirement[];
 }
 
 export type NavigatorResponsiveSize = 'compact' | 'medium' | 'expanded';
@@ -138,7 +139,7 @@ export interface NavigatorRoutePlan {
 
 export type NavigatorRuntimePlatform = 'android' | 'ios' | 'web';
 
-export type NavigatorSupportStatus = 'supported' | 'unavailable';
+export type NavigatorSupportStatus = 'supported' | 'testing-only' | 'unsupported';
 
 export interface NavigatorValidationContext {
   platform: NavigatorRuntimePlatform;

package/src/navigator-runtime-contracts.test.ts

@@ -2,8 +2,10 @@ import { expect, test } from 'bun:test';
 
 import type {
   CustomNavigatorRegistration,
+  NavigatorCatalog,
   NavigatorGeneratedFile,
   NavigatorGenerationBindings,
+  NavigatorGenerationResult,
   NavigatorPlan,
 } from './navigator';
 
@@ -32,10 +34,59 @@ test('keeps generation bindings and plan output portable across package boundari
       routes: [],
     },
     diagnostics: [],
-    supported: true,
-    flows: { onboarding: false, authentication: false },
+    support: 'supported',
+    capabilityIds: ['slot'],
+    dependencies: [],
   };
-  expect(JSON.parse(JSON.stringify({ bindings, file, plan }))).toEqual({ bindings, file, plan });
+  const result: NavigatorGenerationResult = {
+    support: plan.support,
+    capabilityIds: plan.capabilityIds,
+    dependencies: plan.dependencies,
+    diagnostics: plan.diagnostics,
+    plan,
+    files: [file],
+  };
+  expect(JSON.parse(JSON.stringify({ bindings, result }))).toEqual({ bindings, result });
+});
+
+test('separates capability taxonomy, target support, stability, and verification', () => {
+  const catalog: NavigatorCatalog = {
+    capabilities: [
+      {
+        id: 'tabs.headless.sidebar',
+        topology: 'tabs',
+        implementation: 'headless',
+        presentation: 'sidebar',
+        stability: 'stable',
+        targets: [
+          {
+            platform: 'web',
+            support: 'supported',
+            verification: [{ kind: 'browser', status: 'verified' }],
+          },
+          {
+            platform: 'ios',
+            support: 'testing-only',
+            verification: [{ kind: 'device', status: 'unverified' }],
+          },
+        ],
+        dependencies: [],
+        requirements: [],
+        incompatibilities: [],
+        limitations: [],
+      },
+    ],
+    presets: [
+      {
+        id: 'drawer',
+        description: 'Drawer as the root navigator with direct routes.',
+        topology: ['drawer'],
+      },
+    ],
+  };
+
+  expect(catalog.capabilities[0]?.targets[1]?.support).toBe('testing-only');
+  expect(catalog.presets[0]?.topology).toEqual(['drawer']);
 });
 
 test('describes a custom extension without importing Navigator or a UI runtime', () => {

package/src/navigator-validation.test.ts

@@ -6,7 +6,7 @@ import { describe, expect, it } from 'bun:test';
 import { isAppNavigatorManifest } from './appManifest/screens';
 import type {
   CustomNavigatorNode,
-  CustomTabsConfig,
+  HeadlessTabsConfig,
   NavigatorNode,
   StackImplementationConfig,
 } from './navigator';
@@ -20,9 +20,9 @@ describe('app navigator manifest type discrimination', () => {
       implementation: 'experimental',
       options: { presentation: 'modal' },
     };
-    // @ts-expect-error Fixed custom tabs do not accept a registered custom presentation id.
-    const tabs: CustomTabsConfig = {
-      implementation: 'custom',
+    // @ts-expect-error Fixed headless tabs do not accept a registered custom presentation id.
+    const tabs: HeadlessTabsConfig = {
+      implementation: 'headless',
       presentation: 'sidebar',
       customPresentationId: 'workspace-tabs',
     };
@@ -70,6 +70,33 @@ describe('app navigator manifest stack validation', () => {
   });
 });
 
+describe('app navigator manifest removed fields', () => {
+  it('rejects flow metadata and the superseded custom Tabs implementation', () => {
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        flows: { onboarding: true },
+        routes: [],
+      }),
+    ).toBe(false);
+    expect(
+      isAppNavigatorManifest({
+        type: 'tabs',
+        implementation: 'custom',
+        presentation: 'bottom',
+        routes: [],
+      }),
+    ).toBe(false);
+    expect(
+      isAppNavigatorManifest({
+        type: 'stack',
+        preset: 'root-stack-tabs',
+        routes: [],
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('app navigator manifest sheet validation', () => {
   it('validates native form-sheet detents and their presentation discriminant', () => {
     for (const sheetAllowedDetents of [[], [0.8, 0.4], [0.4, 0.4], [0], [1.1], [Number.NaN]]) {

package/src/navigator.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'bun:test';
 
-import { isAppNavigatorManifest } from './appManifest/screens';
 import {
   type AppNavigatorManifest,
+  isAppNavigatorManifest,
   NAVIGATOR_PRESETS,
   NAVIGATOR_TYPES,
   type NavigatorNode,
@@ -10,6 +10,11 @@ import {
   type TabsNavigatorConfig,
 } from './navigator';
 
+function parseNavigator(value: unknown): AppNavigatorManifest {
+  if (!isAppNavigatorManifest(value)) throw new Error('Expected a navigator manifest.');
+  return value;
+}
+
 function createAdaptiveTabs(): AppNavigatorManifest {
   return {
     type: 'tabs',
@@ -23,7 +28,6 @@ function createAdaptiveTabs(): AppNavigatorManifest {
         expanded: 'sidebar',
       },
     },
-    flows: { onboarding: true },
     routes: [{ name: 'home', path: '/', screenId: 'home' }],
   };
 }
@@ -82,14 +86,33 @@ const VALID_NAVIGATOR_NODES = [
   },
 ] as const satisfies readonly NavigatorNode[];
 
+it('narrows unknown input through the public navigator boundary', () => {
+  const manifest = parseNavigator({ type: 'drawer', routes: [] });
+
+  expect(manifest.type).toBe('drawer');
+});
+
 describe('app navigator manifest topology', () => {
   it('keeps canonical topology presets finite and authorable', () => {
     expect(NAVIGATOR_TYPES).toEqual(['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom']);
-    expect(NAVIGATOR_PRESETS).toContain('slot');
-    expect(NAVIGATOR_PRESETS).toContain('split-view');
-    expect(NAVIGATOR_PRESETS).toContain('custom');
-    expect(NAVIGATOR_PRESETS).toContain('root-stack-tabs-stack');
-    expect(NAVIGATOR_PRESETS).toContain('root-stack-drawer-tabs-stack');
+    expect(NAVIGATOR_PRESETS).toEqual([
+      'slot',
+      'stack',
+      'tabs',
+      'tabs-stack',
+      'stack-tabs',
+      'stack-tabs-stack',
+      'drawer',
+      'drawer-stack',
+      'stack-drawer',
+      'stack-drawer-stack',
+      'drawer-tabs',
+      'drawer-tabs-stack',
+      'stack-drawer-tabs',
+      'stack-drawer-tabs-stack',
+      'split-view',
+      'custom',
+    ]);
   });
 
   it('accepts adaptive native/Web tabs with responsive custom presentation', () => {
@@ -152,12 +175,12 @@ describe('app navigator manifest node variants', () => {
   });
 });
 
-describe('app navigator manifest custom presentation', () => {
+describe('app navigator manifest headless presentation', () => {
   it('accepts fixed and registered custom Web presentations', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'sidebar',
         routes: [],
       }),
@@ -166,7 +189,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'custom',
         customPresentationId: 'workspace-tabs',
         routes: [],
@@ -178,7 +201,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'responsive',
         routes: [],
       }),
@@ -187,7 +210,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'custom',
         routes: [],
       }),
@@ -219,7 +242,7 @@ describe('app navigator manifest tabs branch validation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'sidebar',
         customPresentationId: 'must-not-apply',
         routes: [],
@@ -229,7 +252,7 @@ describe('app navigator manifest tabs branch validation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'custom',
         customPresentationId: 'workspace-tabs',
         responsive: { compact: 'bottom', expanded: 'sidebar' },
@@ -240,14 +263,21 @@ describe('app navigator manifest tabs branch validation', () => {
 });
 
 describe('app navigator manifest composition', () => {
-  it('keeps nested topology separate from app-level flow metadata', () => {
+  it('expresses app-owned sequences as ordinary guarded navigator branches', () => {
     expect(
       isAppNavigatorManifest({
         type: 'stack',
-        flows: { authentication: true },
         routes: [
           {
-            name: 'app',
+            name: 'entry',
+            navigator: {
+              type: 'stack',
+              routes: [{ name: 'step', screenId: 'step' }],
+            },
+          },
+          {
+            name: 'main',
+            guards: ['entry-complete'],
             navigator: {
               type: 'tabs',
               routes: [{ name: 'home', screenId: 'home' }],
@@ -257,7 +287,9 @@ describe('app navigator manifest composition', () => {
       }),
     ).toBe(true);
   });
+});
 
+describe('app navigator manifest route metadata', () => {
   it('preserves authored route names, labels, paths, guards, and visibility without inference', () => {
     const navigator = {
       type: 'stack',

package/src/navigator.ts

@@ -1,5 +1,7 @@
 import type { IconSpec, ManifestValue } from './types';
 
+export { isAppNavigatorManifest } from './appManifest/navigator';
+
 export const NAVIGATOR_TYPES = ['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom'] as const;
 export type NavigatorType = (typeof NAVIGATOR_TYPES)[number];
 
@@ -8,16 +10,16 @@ export const NAVIGATOR_PRESETS = [
   'stack',
   'tabs',
   'tabs-stack',
+  'stack-tabs',
+  'stack-tabs-stack',
   'drawer',
   'drawer-stack',
+  'stack-drawer',
+  'stack-drawer-stack',
   'drawer-tabs',
   'drawer-tabs-stack',
-  'root-stack-tabs',
-  'root-stack-tabs-stack',
-  'root-stack-drawer',
-  'root-stack-drawer-stack',
-  'root-stack-drawer-tabs',
-  'root-stack-drawer-tabs-stack',
+  'stack-drawer-tabs',
+  'stack-drawer-tabs-stack',
   'split-view',
   'custom',
 ] as const;
@@ -94,15 +96,15 @@ export interface DrawerNavigatorOptions {
   headerShown?: boolean;
 }
 
-export const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;
-export type FixedCustomTabsPresentation = (typeof FIXED_CUSTOM_TABS_PRESENTATIONS)[number];
+export const FIXED_HEADLESS_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;
+export type FixedHeadlessTabsPresentation = (typeof FIXED_HEADLESS_TABS_PRESENTATIONS)[number];
 
-export const CUSTOM_TABS_PRESENTATIONS = [
-  ...FIXED_CUSTOM_TABS_PRESENTATIONS,
+export const HEADLESS_TABS_PRESENTATIONS = [
+  ...FIXED_HEADLESS_TABS_PRESENTATIONS,
   'responsive',
   'custom',
 ] as const;
-export type CustomTabsPresentation = (typeof CUSTOM_TABS_PRESENTATIONS)[number];
+export type HeadlessTabsPresentation = (typeof HEADLESS_TABS_PRESENTATIONS)[number];
 
 export const JAVASCRIPT_TABS_PRESENTATIONS = ['bottom', 'top'] as const;
 export type JavaScriptTabsPresentation = (typeof JAVASCRIPT_TABS_PRESENTATIONS)[number];
@@ -116,14 +118,14 @@ export const NATIVE_TABS_MINIMIZE_BEHAVIORS = [
 export type NativeTabsMinimizeBehavior = (typeof NATIVE_TABS_MINIMIZE_BEHAVIORS)[number];
 
 export interface ResponsiveTabsPresentation {
-  compact: FixedCustomTabsPresentation;
-  medium?: FixedCustomTabsPresentation;
-  expanded: FixedCustomTabsPresentation;
+  compact: FixedHeadlessTabsPresentation;
+  medium?: FixedHeadlessTabsPresentation;
+  expanded: FixedHeadlessTabsPresentation;
 }
 
-export type CustomTabsPresentationConfig =
+export type HeadlessTabsPresentationConfig =
   | {
-      presentation: FixedCustomTabsPresentation;
+      presentation: FixedHeadlessTabsPresentation;
       responsive?: never;
       customPresentationId?: never;
     }
@@ -139,11 +141,11 @@ export type CustomTabsPresentationConfig =
       customPresentationId: string;
     };
 
-export type CustomTabsConfig = {
-  implementation: 'custom';
-} & CustomTabsPresentationConfig;
+export type HeadlessTabsConfig = {
+  implementation: 'headless';
+} & HeadlessTabsPresentationConfig;
 
-export type CustomTabsWebConfig = CustomTabsPresentationConfig;
+export type HeadlessTabsWebConfig = HeadlessTabsPresentationConfig;
 
 export interface NavigatorScreenReference {
   screenId: string;
@@ -167,12 +169,12 @@ export interface AdaptiveTabsConfig {
   implementation?: 'adaptive';
   /** Android/iOS branch. Expo Router may expose this implementation as unstable. */
   native?: NativeTabsConfig;
-  /** Web branch rendered through headless custom tabs. */
-  web?: CustomTabsWebConfig;
+  /** Web branch rendered through headless tabs. */
+  web?: HeadlessTabsWebConfig;
 }
 
 export type TabsImplementationConfig =
-  AdaptiveTabsConfig | CustomTabsConfig | JavaScriptTabsConfig | NativeTabsConfig;
+  AdaptiveTabsConfig | HeadlessTabsConfig | JavaScriptTabsConfig | NativeTabsConfig;
 
 interface NavigatorNodeBase {
   initialRouteName?: string;
@@ -237,11 +239,6 @@ export interface RouteDefinition {
   navigator?: NavigatorNode;
 }
 
-export interface NavigatorFlows {
-  onboarding?: boolean;
-  authentication?: boolean;
-}
-
 export interface NavigatorDefaults {
   tabs?: TabsImplementationConfig;
   stack?: StackImplementationConfig;
@@ -266,20 +263,33 @@ export interface NavigatorPlatforms {
  */
 export type AppNavigatorManifest = NavigatorNode & {
   preset?: NavigatorPreset;
-  flows?: NavigatorFlows;
   defaults?: NavigatorDefaults;
   platforms?: NavigatorPlatforms;
 };
 
+export type {
+  NavigatorCapabilityDescriptor,
+  NavigatorCapabilityRequirement,
+  NavigatorCapabilityTarget,
+  NavigatorCapabilityVerification,
+  NavigatorCatalog,
+  NavigatorImplementation,
+  NavigatorPresentation,
+  NavigatorPresetDescriptor,
+  NavigatorVerificationKind,
+  NavigatorVerificationStatus,
+} from './navigator/catalog';
 export type {
   CustomNavigatorConfigIssue,
   CustomNavigatorRegistration,
   CustomNavigatorRegistry,
 } from './navigator/extensions';
 export type {
+  NavigatorDependencyRequirement,
   NavigatorGeneratedFile,
   NavigatorGenerationBindings,
   NavigatorGenerationOptions,
+  NavigatorGenerationResult,
   NavigatorScreenModule,
 } from './navigator/generation';
 export type {
@@ -288,6 +298,7 @@ export type {
   NavigatorAdapterId,
   NavigatorAdapterPlan,
   NavigatorApiStability,
+  NavigatorCapabilityId,
   NavigatorDiagnostic,
   NavigatorNodePlan,
   NavigatorPlan,
@@ -296,7 +307,7 @@ export type {
   NavigatorRuntimePlatform,
   NavigatorSupportStatus,
   NavigatorValidationContext,
-  ResolvedCustomTabsPresentation,
+  ResolvedHeadlessTabsPresentation,
   ResolvedTabsImplementation,
   ResolvedTabsPresentation,
   TabsNavigatorPlan,