@ankhorage/contracts 11.0.0 → 12.0.0

package/src/navigator/planning.ts

@@ -0,0 +1,147 @@
+import type {
+  CustomNavigatorNode,
+  DrawerNavigatorOptions,
+  NavigatorType,
+  RouteDefinition,
+  StackImplementation,
+  StackScreenOptions,
+} from '../navigator';
+import type { CustomNavigatorRegistry } from './extensions';
+import type { NavigatorDependencyRequirement } from './generation';
+
+export interface ResolvedHeadlessTabsPresentation {
+  presentation: ResolvedTabsPresentation;
+  customPresentationId?: string;
+}
+
+export type ResolvedTabsImplementation = 'headless' | 'javascript' | 'native';
+
+export type ResolvedTabsPresentation = 'bottom' | 'top' | 'rail' | 'sidebar' | 'custom';
+
+/**
+ * Disposable adapter plan for a `tabs` topology.
+ *
+ * The implementation selects the Router runtime. Presentation only selects its visual chrome and
+ * never creates another route topology.
+ */
+export interface TabsNavigatorPlan {
+  implementation: ResolvedTabsImplementation;
+  module: ExpoRouterNavigatorModule;
+  exportName: string;
+  stability: NavigatorApiStability;
+  presentation?: ResolvedTabsPresentation;
+  presentations?: Readonly<Record<NavigatorResponsiveSize, ResolvedTabsPresentation>>;
+  customPresentationId?: string;
+  minimizeBehavior?: 'automatic' | 'never' | 'onScrollDown' | 'onScrollUp';
+  bottomAccessoryScreenId?: string;
+}
+
+export interface CreateNavigatorPlanOptions {
+  platform: NavigatorRuntimePlatform;
+  expoRouterVersion: string;
+  responsiveSize?: NavigatorResponsiveSize;
+  customNavigators?: CustomNavigatorRegistry;
+}
+
+export type ExpoRouterNavigatorModule =
+  | 'expo-router'
+  | 'expo-router/drawer'
+  | 'expo-router/js-stack'
+  | 'expo-router/js-tabs'
+  | 'expo-router/js-top-tabs'
+  | 'expo-router/ui'
+  | 'expo-router/unstable-split-view'
+  | 'expo-router/unstable-native-tabs';
+
+export type NavigatorAdapterId =
+  | 'slot'
+  | 'stack.native'
+  | 'stack.javascript'
+  | 'stack.experimental'
+  | 'drawer'
+  | 'tabs.native'
+  | 'tabs.javascript'
+  | 'tabs.headless'
+  | 'split-view'
+  | 'custom';
+
+export interface NavigatorAdapterPlan {
+  id: NavigatorAdapterId;
+  /** Built-in Expo Router entry point or an explicitly registered custom module. */
+  module?: string;
+  exportName?: string;
+  support: NavigatorSupportStatus;
+  stability: NavigatorApiStability;
+  limitations: readonly string[];
+}
+
+export type NavigatorApiStability = 'stable' | 'alpha';
+
+export type NavigatorCapabilityId = string;
+
+export interface NavigatorDiagnostic {
+  code: string;
+  severity: 'error' | 'warning';
+  path: string;
+  message: string;
+}
+
+export interface NavigatorNodePlan {
+  type: NavigatorType;
+  pointer: string;
+  adapter: NavigatorAdapterPlan;
+  initialRouteName?: string;
+  routes: readonly NavigatorRoutePlan[];
+  stack?: {
+    implementation: StackImplementation;
+    options?: StackScreenOptions;
+  };
+  drawer?: {
+    options?: DrawerNavigatorOptions;
+  };
+  tabs?: TabsNavigatorPlan;
+  splitView?: {
+    columns: {
+      primary: string;
+      supplementary?: string;
+    };
+    inspector?: string;
+    topColumnForCollapsing?: 'primary' | 'secondary' | 'supplementary';
+  };
+  custom?: {
+    navigatorId: string;
+    config?: CustomNavigatorNode['config'];
+  };
+}
+
+export interface NavigatorPlan {
+  context: NavigatorValidationContext;
+  root: NavigatorNodePlan;
+  diagnostics: readonly NavigatorDiagnostic[];
+  support: NavigatorSupportStatus;
+  capabilityIds: readonly NavigatorCapabilityId[];
+  dependencies: readonly NavigatorDependencyRequirement[];
+}
+
+export type NavigatorResponsiveSize = 'compact' | 'medium' | 'expanded';
+
+export interface NavigatorRoutePlan {
+  name: string;
+  path?: string;
+  label?: string;
+  icon?: RouteDefinition['icon'];
+  showInPrimaryNavigation?: boolean;
+  guards: readonly string[];
+  screenId?: string;
+  stackOptions?: StackScreenOptions;
+  navigator?: NavigatorNodePlan;
+}
+
+export type NavigatorRuntimePlatform = 'android' | 'ios' | 'web';
+
+export type NavigatorSupportStatus = 'supported' | 'testing-only' | 'unsupported';
+
+export interface NavigatorValidationContext {
+  platform: NavigatorRuntimePlatform;
+  expoRouterVersion: string;
+}

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

@@ -0,0 +1,104 @@
+import { expect, test } from 'bun:test';
+
+import type {
+  CustomNavigatorRegistration,
+  NavigatorCatalog,
+  NavigatorGeneratedFile,
+  NavigatorGenerationBindings,
+  NavigatorGenerationResult,
+  NavigatorPlan,
+} from './navigator';
+
+test('keeps generation bindings and plan output portable across package boundaries', () => {
+  const bindings: NavigatorGenerationBindings = {
+    screens: { home: { module: '@/screens/Home', exportName: 'Home' } },
+    guards: {},
+  };
+  const file: NavigatorGeneratedFile = {
+    path: 'src/app/index.tsx',
+    contents: 'export default Home;',
+  };
+  const plan: NavigatorPlan = {
+    context: { platform: 'web', expoRouterVersion: '57.0.18' },
+    root: {
+      type: 'slot',
+      pointer: '',
+      adapter: {
+        id: 'slot',
+        module: 'expo-router',
+        exportName: 'Slot',
+        support: 'supported',
+        stability: 'stable',
+        limitations: [],
+      },
+      routes: [],
+    },
+    diagnostics: [],
+    support: 'supported',
+    capabilityIds: ['slot'],
+    dependencies: [],
+  };
+  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', () => {
+  const registration: CustomNavigatorRegistration = {
+    id: 'example',
+    platforms: ['web'],
+    stability: 'stable',
+    integration: 'expo-router-standard',
+    router: 'stack',
+    module: '@example/navigation',
+    exportName: 'ExampleNavigator',
+    validateConfig: () => [],
+  };
+  expect(registration.validateConfig({ mode: 'compact' })).toEqual([]);
+});

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

@@ -23,7 +23,6 @@ function createAdaptiveTabs(): AppNavigatorManifest {
         expanded: 'sidebar',
       },
     },
-    flows: { onboarding: true },
     routes: [{ name: 'home', path: '/', screenId: 'home' }],
   };
 }
@@ -85,11 +84,24 @@ const VALID_NAVIGATOR_NODES = [
 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 +164,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 +178,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'custom',
         customPresentationId: 'workspace-tabs',
         routes: [],
@@ -178,7 +190,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'responsive',
         routes: [],
       }),
@@ -187,7 +199,7 @@ describe('app navigator manifest custom presentation', () => {
     expect(
       isAppNavigatorManifest({
         type: 'tabs',
-        implementation: 'custom',
+        implementation: 'headless',
         presentation: 'custom',
         routes: [],
       }),
@@ -219,7 +231,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 +241,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 +252,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 +276,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

@@ -8,16 +8,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 +94,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 +116,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 +139,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 +167,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 +237,6 @@ export interface RouteDefinition {
   navigator?: NavigatorNode;
 }
 
-export interface NavigatorFlows {
-  onboarding?: boolean;
-  authentication?: boolean;
-}
-
 export interface NavigatorDefaults {
   tabs?: TabsImplementationConfig;
   stack?: StackImplementationConfig;
@@ -266,7 +261,52 @@ 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 {
+  CreateNavigatorPlanOptions,
+  ExpoRouterNavigatorModule,
+  NavigatorAdapterId,
+  NavigatorAdapterPlan,
+  NavigatorApiStability,
+  NavigatorCapabilityId,
+  NavigatorDiagnostic,
+  NavigatorNodePlan,
+  NavigatorPlan,
+  NavigatorResponsiveSize,
+  NavigatorRoutePlan,
+  NavigatorRuntimePlatform,
+  NavigatorSupportStatus,
+  NavigatorValidationContext,
+  ResolvedHeadlessTabsPresentation,
+  ResolvedTabsImplementation,
+  ResolvedTabsPresentation,
+  TabsNavigatorPlan,
+} from './navigator/planning';