@ankhorage/contracts 10.1.0 → 11.1.0

package/dist/navigator.js

@@ -1,5 +1,6 @@
-export const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'];
+export const NAVIGATOR_TYPES = ['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom'];
 export const NAVIGATOR_PRESETS = [
+    'slot',
     'stack',
     'tabs',
     'tabs-stack',
@@ -13,7 +14,22 @@ export const NAVIGATOR_PRESETS = [
     'root-stack-drawer-stack',
     'root-stack-drawer-tabs',
     'root-stack-drawer-tabs-stack',
+    'split-view',
+    'custom',
+];
+export const STACK_IMPLEMENTATIONS = ['native', 'javascript', 'experimental'];
+export const STACK_PRESENTATIONS = [
+    'card',
+    'modal',
+    'transparentModal',
+    'containedModal',
+    'containedTransparentModal',
+    'fullScreenModal',
+    'formSheet',
 ];
+export const JAVASCRIPT_STACK_PRESENTATIONS = ['card', 'modal', 'transparentModal'];
+export const DRAWER_POSITIONS = ['left', 'right'];
+export const DRAWER_TYPES = ['front', 'back', 'slide', 'permanent'];
 export const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'];
 export const CUSTOM_TABS_PRESENTATIONS = [
     ...FIXED_CUSTOM_TABS_PRESENTATIONS,
@@ -21,4 +37,10 @@ export const CUSTOM_TABS_PRESENTATIONS = [
     'custom',
 ];
 export const JAVASCRIPT_TABS_PRESENTATIONS = ['bottom', 'top'];
+export const NATIVE_TABS_MINIMIZE_BEHAVIORS = [
+    'automatic',
+    'never',
+    'onScrollDown',
+    'onScrollUp',
+];
 //# sourceMappingURL=navigator.js.map

package/dist/navigator.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigator.js","sourceRoot":"","sources":["../src/navigator.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAGpE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,OAAO;IACP,MAAM;IACN,YAAY;IACZ,QAAQ;IACR,cAAc;IACd,aAAa;IACb,mBAAmB;IACnB,iBAAiB;IACjB,uBAAuB;IACvB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,8BAA8B;CACtB,CAAC;AAGX,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAG7F,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,GAAG,+BAA+B;IAClC,YAAY;IACZ,QAAQ;CACA,CAAC;AAGX,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAU,CAAC","sourcesContent":["import type { IconSpec } from './types';\n\nexport const NAVIGATOR_TYPES = ['stack', 'tabs', 'drawer'] as const;\nexport type NavigatorType = (typeof NAVIGATOR_TYPES)[number];\n\nexport const NAVIGATOR_PRESETS = [\n  'stack',\n  'tabs',\n  'tabs-stack',\n  'drawer',\n  'drawer-stack',\n  'drawer-tabs',\n  'drawer-tabs-stack',\n  'root-stack-tabs',\n  'root-stack-tabs-stack',\n  'root-stack-drawer',\n  'root-stack-drawer-stack',\n  'root-stack-drawer-tabs',\n  'root-stack-drawer-tabs-stack',\n] as const;\nexport type NavigatorPreset = (typeof NAVIGATOR_PRESETS)[number];\n\nexport const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;\nexport type FixedCustomTabsPresentation = (typeof FIXED_CUSTOM_TABS_PRESENTATIONS)[number];\n\nexport const CUSTOM_TABS_PRESENTATIONS = [\n  ...FIXED_CUSTOM_TABS_PRESENTATIONS,\n  'responsive',\n  'custom',\n] as const;\nexport type CustomTabsPresentation = (typeof CUSTOM_TABS_PRESENTATIONS)[number];\n\nexport const JAVASCRIPT_TABS_PRESENTATIONS = ['bottom', 'top'] as const;\nexport type JavaScriptTabsPresentation = (typeof JAVASCRIPT_TABS_PRESENTATIONS)[number];\n\nexport interface ResponsiveTabsPresentation {\n  compact: FixedCustomTabsPresentation;\n  medium?: FixedCustomTabsPresentation;\n  expanded: FixedCustomTabsPresentation;\n}\n\nexport interface CustomTabsConfig {\n  implementation: 'custom';\n  presentation: CustomTabsPresentation;\n  responsive?: ResponsiveTabsPresentation;\n  /** Serializable registered presentation id used when `presentation` is `custom`. */\n  customPresentationId?: string;\n}\n\nexport interface NativeTabsConfig {\n  implementation: 'native';\n}\n\nexport interface JavaScriptTabsConfig {\n  implementation: 'javascript';\n  presentation?: JavaScriptTabsPresentation;\n}\n\nexport interface AdaptiveTabsConfig {\n  /** Omission selects the canonical adaptive default. */\n  implementation?: 'adaptive';\n  /** Android/iOS branch. Expo Router may expose this implementation as unstable. */\n  native?: NativeTabsConfig;\n  /** Web branch rendered through headless custom tabs. */\n  web?: Omit<CustomTabsConfig, 'implementation'>;\n}\n\nexport type TabsImplementationConfig =\n  AdaptiveTabsConfig | CustomTabsConfig | JavaScriptTabsConfig | NativeTabsConfig;\n\ninterface NavigatorNodeBase {\n  initialRouteName?: string;\n  routes: RouteDefinition[];\n  /** Typed upstream options can be layered by the owning Navigator package. */\n  options?: Record<string, unknown>;\n}\n\nexport interface StackNavigatorNode extends NavigatorNodeBase {\n  type: 'stack';\n}\n\nexport interface DrawerNavigatorNode extends NavigatorNodeBase {\n  type: 'drawer';\n}\n\nexport type TabsNavigatorConfig = {\n  type: 'tabs';\n} & TabsImplementationConfig;\n\nexport type TabsNavigatorNode = NavigatorNodeBase & TabsNavigatorConfig;\n\nexport type NavigatorNode = DrawerNavigatorNode | StackNavigatorNode | TabsNavigatorNode;\n\nexport interface RouteDefinition {\n  name: string;\n  path?: string;\n  label?: string;\n  icon?: IconSpec;\n  /** Hide this route from primary Tabs/Drawer presentation without making it unnavigable. */\n  showInPrimaryNavigation?: boolean;\n  guards?: string[];\n  screenId?: string;\n  navigator?: NavigatorNode;\n}\n\nexport interface NavigatorFlows {\n  onboarding?: boolean;\n  authentication?: boolean;\n}\n\nexport interface NavigatorDefaults {\n  tabs?: TabsImplementationConfig;\n}\n\nexport interface NavigatorPlatformConfig {\n  tabs?: TabsImplementationConfig;\n}\n\nexport interface NavigatorPlatforms {\n  android?: NavigatorPlatformConfig;\n  ios?: NavigatorPlatformConfig;\n  web?: NavigatorPlatformConfig;\n}\n\n/**\n * Serializable desired state for `AppManifest.navigator`.\n *\n * The manifest slice is the root navigator tree itself; optional authoring metadata does not add\n * a redundant `root` wrapper. The standalone Navigator capability consumes this slice directly.\n */\nexport type AppNavigatorManifest = NavigatorNode & {\n  preset?: NavigatorPreset;\n  flows?: NavigatorFlows;\n  defaults?: NavigatorDefaults;\n  platforms?: NavigatorPlatforms;\n};\n"]}
+{"version":3,"file":"navigator.js","sourceRoot":"","sources":["../src/navigator.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAC;AAGpG,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM;IACN,OAAO;IACP,MAAM;IACN,YAAY;IACZ,QAAQ;IACR,cAAc;IACd,aAAa;IACb,mBAAmB;IACnB,iBAAiB;IACjB,uBAAuB;IACvB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;IACxB,8BAA8B;IAC9B,YAAY;IACZ,QAAQ;CACA,CAAC;AAGX,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,cAAc,CAAU,CAAC;AAGvF,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,MAAM;IACN,OAAO;IACP,kBAAkB;IAClB,gBAAgB;IAChB,2BAA2B;IAC3B,iBAAiB;IACjB,WAAW;CACH,CAAC;AAGX,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,kBAAkB,CAAU,CAAC;AA4C7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAU,CAAC;AAG3D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC;AAU7E,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAG7F,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,GAAG,+BAA+B;IAClC,YAAY;IACZ,QAAQ;CACA,CAAC;AAGX,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAU,CAAC;AAGxE,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,WAAW;IACX,OAAO;IACP,cAAc;IACd,YAAY;CACJ,CAAC","sourcesContent":["import type { IconSpec, ManifestValue } from './types';\n\nexport const NAVIGATOR_TYPES = ['slot', 'stack', 'tabs', 'drawer', 'split-view', 'custom'] as const;\nexport type NavigatorType = (typeof NAVIGATOR_TYPES)[number];\n\nexport const NAVIGATOR_PRESETS = [\n  'slot',\n  'stack',\n  'tabs',\n  'tabs-stack',\n  'drawer',\n  'drawer-stack',\n  'drawer-tabs',\n  'drawer-tabs-stack',\n  'root-stack-tabs',\n  'root-stack-tabs-stack',\n  'root-stack-drawer',\n  'root-stack-drawer-stack',\n  'root-stack-drawer-tabs',\n  'root-stack-drawer-tabs-stack',\n  'split-view',\n  'custom',\n] as const;\nexport type NavigatorPreset = (typeof NAVIGATOR_PRESETS)[number];\n\nexport const STACK_IMPLEMENTATIONS = ['native', 'javascript', 'experimental'] as const;\nexport type StackImplementation = (typeof STACK_IMPLEMENTATIONS)[number];\n\nexport const STACK_PRESENTATIONS = [\n  'card',\n  'modal',\n  'transparentModal',\n  'containedModal',\n  'containedTransparentModal',\n  'fullScreenModal',\n  'formSheet',\n] as const;\nexport type StackPresentation = (typeof STACK_PRESENTATIONS)[number];\n\nexport const JAVASCRIPT_STACK_PRESENTATIONS = ['card', 'modal', 'transparentModal'] as const;\nexport type JavaScriptStackPresentation = (typeof JAVASCRIPT_STACK_PRESENTATIONS)[number];\n\nexport interface StackHeaderOptions {\n  title?: string;\n  headerShown?: boolean;\n  headerTransparent?: boolean;\n  headerBackVisible?: boolean;\n}\n\nexport type StackScreenOptions = StackHeaderOptions &\n  (\n    | {\n        presentation?: Exclude<StackPresentation, 'formSheet'>;\n        sheetAllowedDetents?: never;\n        sheetGrabberVisible?: never;\n      }\n    | {\n        presentation: 'formSheet';\n        sheetAllowedDetents?: 'fitToContents' | number[];\n        sheetGrabberVisible?: boolean;\n      }\n  );\n\nexport type JavaScriptStackScreenOptions = StackHeaderOptions & {\n  presentation?: JavaScriptStackPresentation;\n};\n\nexport type StackImplementationConfig =\n  | {\n      /** Omission selects the stable native stack implementation. */\n      implementation?: 'native';\n      options?: StackScreenOptions;\n    }\n  | {\n      implementation: 'javascript';\n      options?: JavaScriptStackScreenOptions;\n    }\n  | {\n      /** Expo Router Experimental Stack is alpha, native-only, and available from SDK 56. */\n      implementation: 'experimental';\n      options?: StackHeaderOptions;\n    };\n\nexport const DRAWER_POSITIONS = ['left', 'right'] as const;\nexport type DrawerPosition = (typeof DRAWER_POSITIONS)[number];\n\nexport const DRAWER_TYPES = ['front', 'back', 'slide', 'permanent'] as const;\nexport type DrawerType = (typeof DRAWER_TYPES)[number];\n\nexport interface DrawerNavigatorOptions {\n  drawerPosition?: DrawerPosition;\n  drawerType?: DrawerType;\n  swipeEnabled?: boolean;\n  headerShown?: boolean;\n}\n\nexport const FIXED_CUSTOM_TABS_PRESENTATIONS = ['bottom', 'top', 'rail', 'sidebar'] as const;\nexport type FixedCustomTabsPresentation = (typeof FIXED_CUSTOM_TABS_PRESENTATIONS)[number];\n\nexport const CUSTOM_TABS_PRESENTATIONS = [\n  ...FIXED_CUSTOM_TABS_PRESENTATIONS,\n  'responsive',\n  'custom',\n] as const;\nexport type CustomTabsPresentation = (typeof CUSTOM_TABS_PRESENTATIONS)[number];\n\nexport const JAVASCRIPT_TABS_PRESENTATIONS = ['bottom', 'top'] as const;\nexport type JavaScriptTabsPresentation = (typeof JAVASCRIPT_TABS_PRESENTATIONS)[number];\n\nexport const NATIVE_TABS_MINIMIZE_BEHAVIORS = [\n  'automatic',\n  'never',\n  'onScrollDown',\n  'onScrollUp',\n] as const;\nexport type NativeTabsMinimizeBehavior = (typeof NATIVE_TABS_MINIMIZE_BEHAVIORS)[number];\n\nexport interface ResponsiveTabsPresentation {\n  compact: FixedCustomTabsPresentation;\n  medium?: FixedCustomTabsPresentation;\n  expanded: FixedCustomTabsPresentation;\n}\n\nexport type CustomTabsPresentationConfig =\n  | {\n      presentation: FixedCustomTabsPresentation;\n      responsive?: never;\n      customPresentationId?: never;\n    }\n  | {\n      presentation: 'responsive';\n      responsive: ResponsiveTabsPresentation;\n      customPresentationId?: never;\n    }\n  | {\n      presentation: 'custom';\n      responsive?: never;\n      /** Serializable registered presentation id. */\n      customPresentationId: string;\n    };\n\nexport type CustomTabsConfig = {\n  implementation: 'custom';\n} & CustomTabsPresentationConfig;\n\nexport type CustomTabsWebConfig = CustomTabsPresentationConfig;\n\nexport interface NavigatorScreenReference {\n  screenId: string;\n}\n\nexport interface NativeTabsConfig {\n  implementation: 'native';\n  /** Expo Router Native Tabs is alpha; minimizing is available on iOS 26+ from SDK 55. */\n  minimizeBehavior?: NativeTabsMinimizeBehavior;\n  /** Registered screen rendered through NativeTabs.BottomAccessory, available from SDK 55. */\n  bottomAccessory?: NavigatorScreenReference;\n}\n\nexport interface JavaScriptTabsConfig {\n  implementation: 'javascript';\n  presentation?: JavaScriptTabsPresentation;\n}\n\nexport interface AdaptiveTabsConfig {\n  /** Omission selects the canonical adaptive default. */\n  implementation?: 'adaptive';\n  /** Android/iOS branch. Expo Router may expose this implementation as unstable. */\n  native?: NativeTabsConfig;\n  /** Web branch rendered through headless custom tabs. */\n  web?: CustomTabsWebConfig;\n}\n\nexport type TabsImplementationConfig =\n  AdaptiveTabsConfig | CustomTabsConfig | JavaScriptTabsConfig | NativeTabsConfig;\n\ninterface NavigatorNodeBase {\n  initialRouteName?: string;\n  routes: RouteDefinition[];\n}\n\nexport interface SlotNavigatorNode extends NavigatorNodeBase {\n  type: 'slot';\n}\n\nexport type StackNavigatorNode = NavigatorNodeBase & {\n  type: 'stack';\n} & StackImplementationConfig;\n\nexport interface DrawerNavigatorNode extends NavigatorNodeBase {\n  type: 'drawer';\n  options?: DrawerNavigatorOptions;\n}\n\nexport type TabsNavigatorConfig = {\n  type: 'tabs';\n} & TabsImplementationConfig;\n\nexport type TabsNavigatorNode = NavigatorNodeBase & TabsNavigatorConfig;\n\nexport interface SplitViewNavigatorNode extends NavigatorNodeBase {\n  type: 'split-view';\n  columns: {\n    primary: NavigatorScreenReference;\n    supplementary?: NavigatorScreenReference;\n  };\n  inspector?: NavigatorScreenReference;\n  /** Split View is alpha and iOS-only; other platforms fall back to Slot. */\n  topColumnForCollapsing?: 'primary' | 'supplementary' | 'secondary';\n}\n\nexport interface CustomNavigatorNode extends NavigatorNodeBase {\n  type: 'custom';\n  navigatorId: string;\n  config?: Readonly<Record<string, ManifestValue>>;\n}\n\nexport type NavigatorNode =\n  | CustomNavigatorNode\n  | DrawerNavigatorNode\n  | SlotNavigatorNode\n  | SplitViewNavigatorNode\n  | StackNavigatorNode\n  | TabsNavigatorNode;\n\nexport interface RouteDefinition {\n  name: string;\n  path?: string;\n  label?: string;\n  icon?: IconSpec;\n  /** Hide this route from primary Tabs/Drawer presentation without making it unnavigable. */\n  showInPrimaryNavigation?: boolean;\n  guards?: string[];\n  screenId?: string;\n  /** Presentation applied by the resolved parent stack implementation. */\n  stackOptions?: StackScreenOptions;\n  navigator?: NavigatorNode;\n}\n\nexport interface NavigatorFlows {\n  onboarding?: boolean;\n  authentication?: boolean;\n}\n\nexport interface NavigatorDefaults {\n  tabs?: TabsImplementationConfig;\n  stack?: StackImplementationConfig;\n}\n\nexport interface NavigatorPlatformConfig {\n  tabs?: TabsImplementationConfig;\n  stack?: StackImplementationConfig;\n}\n\nexport interface NavigatorPlatforms {\n  android?: NavigatorPlatformConfig;\n  ios?: NavigatorPlatformConfig;\n  web?: NavigatorPlatformConfig;\n}\n\n/**\n * Serializable desired state for `AppManifest.navigator`.\n *\n * The manifest slice is the root navigator tree itself; optional authoring metadata does not add\n * a redundant `root` wrapper. The standalone Navigator capability consumes this slice directly.\n */\nexport type AppNavigatorManifest = NavigatorNode & {\n  preset?: NavigatorPreset;\n  flows?: NavigatorFlows;\n  defaults?: NavigatorDefaults;\n  platforms?: NavigatorPlatforms;\n};\n\nexport type {\n  CustomNavigatorConfigIssue,\n  CustomNavigatorRegistration,\n  CustomNavigatorRegistry,\n} from './navigator/extensions';\nexport type {\n  NavigatorGeneratedFile,\n  NavigatorGenerationBindings,\n  NavigatorGenerationOptions,\n  NavigatorScreenModule,\n} from './navigator/generation';\nexport type {\n  CreateNavigatorPlanOptions,\n  ExpoRouterNavigatorModule,\n  NavigatorAdapterId,\n  NavigatorAdapterPlan,\n  NavigatorApiStability,\n  NavigatorDiagnostic,\n  NavigatorNodePlan,\n  NavigatorPlan,\n  NavigatorResponsiveSize,\n  NavigatorRoutePlan,\n  NavigatorRuntimePlatform,\n  NavigatorSupportStatus,\n  NavigatorValidationContext,\n  ResolvedCustomTabsPresentation,\n  ResolvedTabsImplementation,\n  ResolvedTabsPresentation,\n  TabsNavigatorPlan,\n} from './navigator/planning';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "10.1.0",
+  "version": "11.1.0",
   "main": "./dist/index.js",
   "ankh": {
     "category": "contracts",
@@ -13,9 +13,9 @@
     "@ankhorage/color-theory": "^0.3.0"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.10.9",
+    "@ankhorage/devtools": "^1.11.11",
     "@ankhorage/paradox": "^0.1.24",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.1",
     "@types/node": "^25.2.3",
     "typescript": "^5.9.3"
   },
@@ -104,7 +104,7 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "packageManager": "bun@1.4.0",
+  "packageManager": "bun@1.4.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ankhorage/contracts.git"

package/src/appManifest/navigator.ts

@@ -0,0 +1,179 @@
+import { NAVIGATOR_PRESETS, NAVIGATOR_TYPES } from '../navigator';
+import { isIconSpec } from './icon';
+import {
+  hasOnlyKeys,
+  isDrawerNavigatorOptions,
+  isNavigatorScreenReference,
+  isStackImplementationConfig,
+  isStackScreenOptions,
+  isTabsImplementationConfig,
+} from './navigatorOptions';
+import { isOptionalBoolean, isOptionalString, isRecord, isStringArray } from './shared';
+
+const NAVIGATOR_PRESET_SET = new Set<string>(NAVIGATOR_PRESETS);
+const NAVIGATOR_TYPE_SET = new Set<string>(NAVIGATOR_TYPES);
+
+/*** Validate the complete serialized `AppManifest.navigator` slice. */
+export function isAppNavigatorManifest(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isNavigatorNode(value) &&
+    (value.preset === undefined ||
+      (typeof value.preset === 'string' && NAVIGATOR_PRESET_SET.has(value.preset))) &&
+    (value.flows === undefined || isNavigatorFlows(value.flows)) &&
+    (value.defaults === undefined || isNavigatorDefaults(value.defaults)) &&
+    (value.platforms === undefined || isNavigatorPlatforms(value.platforms))
+  );
+}
+
+/*** Validate one nested navigator node independently from app-level authoring metadata. */
+function isNavigatorNode(value: unknown): boolean {
+  if (
+    !isRecord(value) ||
+    typeof value.type !== 'string' ||
+    !NAVIGATOR_TYPE_SET.has(value.type) ||
+    !isOptionalString(value.initialRouteName) ||
+    !Array.isArray(value.routes) ||
+    !value.routes.every(isRouteDefinition)
+  ) {
+    return false;
+  }
+
+  switch (value.type) {
+    case 'slot':
+      return value.options === undefined && value.implementation === undefined;
+    case 'stack':
+      return isStackImplementationConfig(value);
+    case 'tabs':
+      return isTabsImplementationConfig(value);
+    case 'drawer':
+      return (
+        value.implementation === undefined &&
+        (value.options === undefined || isDrawerNavigatorOptions(value.options))
+      );
+    case 'split-view':
+      return isSplitViewNavigatorNode(value);
+    case 'custom':
+      return isCustomNavigatorNode(value);
+    default:
+      return false;
+  }
+}
+
+/*** Validate one route and preserve its portable metadata and nested navigator. */
+function isRouteDefinition(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.path) &&
+    isOptionalString(value.label) &&
+    (value.icon === undefined || isIconSpec(value.icon)) &&
+    isOptionalBoolean(value.showInPrimaryNavigation) &&
+    (value.guards === undefined || isStringArray(value.guards)) &&
+    isOptionalString(value.screenId) &&
+    (value.stackOptions === undefined || isStackScreenOptions(value.stackOptions)) &&
+    (value.navigator === undefined || isNavigatorNode(value.navigator))
+  );
+}
+
+/*** Validate Split View screen references without duplicating the routed secondary tree. */
+function isSplitViewNavigatorNode(value: Record<string, unknown>): boolean {
+  return (
+    value.implementation === undefined &&
+    value.options === undefined &&
+    isRecord(value.columns) &&
+    hasOnlyKeys(value.columns, ['primary', 'supplementary']) &&
+    isNavigatorScreenReference(value.columns.primary) &&
+    (value.columns.supplementary === undefined ||
+      isNavigatorScreenReference(value.columns.supplementary)) &&
+    (value.inspector === undefined || isNavigatorScreenReference(value.inspector)) &&
+    (value.topColumnForCollapsing === undefined ||
+      value.topColumnForCollapsing === 'primary' ||
+      value.topColumnForCollapsing === 'supplementary' ||
+      value.topColumnForCollapsing === 'secondary')
+  );
+}
+
+/*** Validate a registered custom navigator with JSON-safe configuration only. */
+function isCustomNavigatorNode(value: Record<string, unknown>): boolean {
+  return (
+    value.implementation === undefined &&
+    value.options === undefined &&
+    typeof value.navigatorId === 'string' &&
+    (value.config === undefined || isNavigatorJsonRecord(value.config))
+  );
+}
+
+/*** Validate an acyclic, finite JSON object used by a custom navigator adapter. */
+function isNavigatorJsonRecord(value: unknown): boolean {
+  return isRecord(value) && isNavigatorJsonValue(value, new Set<object>());
+}
+
+/*** Recursively validate the portable manifest value domain and reject cycles. */
+function isNavigatorJsonValue(value: unknown, ancestors: Set<object>): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if (typeof value !== 'object' || ancestors.has(value)) return false;
+
+  if (Array.isArray(value)) {
+    if (
+      Object.keys(value).length !== value.length ||
+      Object.getOwnPropertySymbols(value).length > 0
+    ) {
+      return false;
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    if (Reflect.ownKeys(value).some((key) => typeof key !== 'string')) return false;
+  }
+
+  ancestors.add(value);
+  const isValid = Object.values(value).every((entry) => isNavigatorJsonValue(entry, ancestors));
+  ancestors.delete(value);
+  return isValid;
+}
+
+/*** Validate optional app-level navigator flow intent. */
+function isNavigatorFlows(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isOptionalBoolean(value.onboarding) &&
+    isOptionalBoolean(value.authentication)
+  );
+}
+
+/*** Validate package-owned navigator defaults without requiring a navigator node type. */
+function isNavigatorDefaults(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['tabs', 'stack']) &&
+    (value.tabs === undefined ||
+      (isRecord(value.tabs) && isTabsImplementationConfig(value.tabs))) &&
+    (value.stack === undefined ||
+      (isRecord(value.stack) && isStackImplementationConfig(value.stack)))
+  );
+}
+
+/*** Validate per-platform navigator implementation overrides. */
+function isNavigatorPlatforms(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['android', 'ios', 'web']) &&
+    (value.android === undefined || isNavigatorPlatformConfig(value.android)) &&
+    (value.ios === undefined || isNavigatorPlatformConfig(value.ios)) &&
+    (value.web === undefined || isNavigatorPlatformConfig(value.web))
+  );
+}
+
+/*** Validate one platform-specific navigator override slice. */
+function isNavigatorPlatformConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['tabs', 'stack']) &&
+    (value.tabs === undefined ||
+      (isRecord(value.tabs) && isTabsImplementationConfig(value.tabs))) &&
+    (value.stack === undefined ||
+      (isRecord(value.stack) && isStackImplementationConfig(value.stack)))
+  );
+}

package/src/appManifest/navigatorOptions.ts

@@ -0,0 +1,292 @@
+import {
+  CUSTOM_TABS_PRESENTATIONS,
+  DRAWER_POSITIONS,
+  DRAWER_TYPES,
+  FIXED_CUSTOM_TABS_PRESENTATIONS,
+  JAVASCRIPT_STACK_PRESENTATIONS,
+  JAVASCRIPT_TABS_PRESENTATIONS,
+  NATIVE_TABS_MINIMIZE_BEHAVIORS,
+  STACK_PRESENTATIONS,
+} from '../navigator';
+import { isOptionalBoolean, isOptionalString, isRecord } from './shared';
+
+const CUSTOM_TABS_PRESENTATION_SET = new Set<string>(CUSTOM_TABS_PRESENTATIONS);
+const DRAWER_POSITION_SET = new Set<string>(DRAWER_POSITIONS);
+const DRAWER_TYPE_SET = new Set<string>(DRAWER_TYPES);
+const FIXED_CUSTOM_TABS_PRESENTATION_SET = new Set<string>(FIXED_CUSTOM_TABS_PRESENTATIONS);
+const JAVASCRIPT_STACK_PRESENTATION_SET = new Set<string>(JAVASCRIPT_STACK_PRESENTATIONS);
+const JAVASCRIPT_TABS_PRESENTATION_SET = new Set<string>(JAVASCRIPT_TABS_PRESENTATIONS);
+const NATIVE_TABS_MINIMIZE_BEHAVIOR_SET = new Set<string>(NATIVE_TABS_MINIMIZE_BEHAVIORS);
+const STACK_PRESENTATION_SET = new Set<string>(STACK_PRESENTATIONS);
+
+/*** Validate stable native, JavaScript, or alpha Experimental Stack desired state. */
+export function isStackImplementationConfig(value: Record<string, unknown>): boolean {
+  if (
+    !hasNoDefinedKeys(value, [
+      'native',
+      'web',
+      'presentation',
+      'responsive',
+      'customPresentationId',
+      'minimizeBehavior',
+      'bottomAccessory',
+    ])
+  ) {
+    return false;
+  }
+  if (value.implementation === undefined || value.implementation === 'native') {
+    return value.options === undefined || isStackScreenOptions(value.options);
+  }
+  if (value.implementation === 'javascript') {
+    return value.options === undefined || isJavaScriptStackScreenOptions(value.options);
+  }
+  return (
+    value.implementation === 'experimental' &&
+    (value.options === undefined || isStackHeaderOptions(value.options))
+  );
+}
+
+/*** Validate the serializable native-stack screen option subset. */
+export function isStackScreenOptions(value: unknown): boolean {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'title',
+      'headerShown',
+      'headerTransparent',
+      'headerBackVisible',
+      'presentation',
+      'sheetAllowedDetents',
+      'sheetGrabberVisible',
+    ]) ||
+    !isStackHeaderOptionsShape(value) ||
+    (value.presentation !== undefined &&
+      (typeof value.presentation !== 'string' || !STACK_PRESENTATION_SET.has(value.presentation)))
+  ) {
+    return false;
+  }
+
+  if (value.presentation !== 'formSheet') {
+    return value.sheetAllowedDetents === undefined && value.sheetGrabberVisible === undefined;
+  }
+  return (
+    (value.sheetAllowedDetents === undefined || isSheetAllowedDetents(value.sheetAllowedDetents)) &&
+    isOptionalBoolean(value.sheetGrabberVisible)
+  );
+}
+
+/*** Validate the finite serializable Drawer option subset. */
+export function isDrawerNavigatorOptions(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['drawerPosition', 'drawerType', 'swipeEnabled', 'headerShown']) &&
+    (value.drawerPosition === undefined ||
+      (typeof value.drawerPosition === 'string' &&
+        DRAWER_POSITION_SET.has(value.drawerPosition))) &&
+    (value.drawerType === undefined ||
+      (typeof value.drawerType === 'string' && DRAWER_TYPE_SET.has(value.drawerType))) &&
+    isOptionalBoolean(value.swipeEnabled) &&
+    isOptionalBoolean(value.headerShown)
+  );
+}
+
+/*** Validate tabs implementation desired state, with omitted implementation meaning adaptive. */
+export function isTabsImplementationConfig(value: Record<string, unknown>): boolean {
+  if (value.implementation === undefined || value.implementation === 'adaptive') {
+    return isAdaptiveTabsConfig(value);
+  }
+  if (value.implementation === 'native') return isFullNativeTabsConfig(value);
+  if (value.implementation === 'javascript') return isJavaScriptTabsConfig(value);
+  return (
+    value.implementation === 'custom' &&
+    hasNoDefinedKeys(value, ['options', 'native', 'web', 'minimizeBehavior', 'bottomAccessory']) &&
+    isCustomTabsPresentationConfig(value)
+  );
+}
+
+/*** Validate a reference into the app-owned screen registry. */
+export function isNavigatorScreenReference(value: unknown): boolean {
+  return isRecord(value) && hasOnlyKeys(value, ['screenId']) && typeof value.screenId === 'string';
+}
+
+/*** Check that a finite configuration object contains no unsupported keys. */
+export function hasOnlyKeys(
+  value: Record<string, unknown>,
+  allowedKeys: readonly string[],
+): boolean {
+  const allowed = new Set(allowedKeys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+/*** Validate JavaScript Stack options without accepting native-only presentations. */
+function isJavaScriptStackScreenOptions(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, [
+      'title',
+      'headerShown',
+      'headerTransparent',
+      'headerBackVisible',
+      'presentation',
+    ]) &&
+    isStackHeaderOptionsShape(value) &&
+    (value.presentation === undefined ||
+      (typeof value.presentation === 'string' &&
+        JAVASCRIPT_STACK_PRESENTATION_SET.has(value.presentation)))
+  );
+}
+
+/*** Validate the portable header subset supported by Experimental Stack. */
+function isStackHeaderOptions(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['title', 'headerShown', 'headerTransparent', 'headerBackVisible']) &&
+    isStackHeaderOptionsShape(value)
+  );
+}
+
+/*** Validate shared stack header field values after branch-specific key filtering. */
+function isStackHeaderOptionsShape(value: Record<string, unknown>): boolean {
+  return (
+    isOptionalString(value.title) &&
+    isOptionalBoolean(value.headerShown) &&
+    isOptionalBoolean(value.headerTransparent) &&
+    isOptionalBoolean(value.headerBackVisible)
+  );
+}
+
+/*** Validate sorted, finite native sheet detents or the fit-to-content sentinel. */
+function isSheetAllowedDetents(value: unknown): boolean {
+  if (value === 'fitToContents') return true;
+  if (!Array.isArray(value) || value.length === 0) return false;
+  return value.every(
+    (detent, index) =>
+      typeof detent === 'number' &&
+      Number.isFinite(detent) &&
+      detent > 0 &&
+      detent <= 1 &&
+      (index === 0 || detent > value[index - 1]),
+  );
+}
+
+/*** Validate an adaptive tabs branch and reject implementation-specific conflicts. */
+function isAdaptiveTabsConfig(value: Record<string, unknown>): boolean {
+  return (
+    hasNoDefinedKeys(value, [
+      'options',
+      'presentation',
+      'responsive',
+      'customPresentationId',
+      'minimizeBehavior',
+      'bottomAccessory',
+    ]) &&
+    (value.native === undefined || isNativeTabsConfig(value.native)) &&
+    (value.web === undefined || isCustomTabsWebConfig(value.web))
+  );
+}
+
+/*** Validate the top-level native tabs implementation. */
+function isFullNativeTabsConfig(value: Record<string, unknown>): boolean {
+  return (
+    hasNoDefinedKeys(value, [
+      'options',
+      'native',
+      'web',
+      'presentation',
+      'responsive',
+      'customPresentationId',
+    ]) && isNativeTabsFields(value)
+  );
+}
+
+/*** Validate the top-level JavaScript tabs implementation. */
+function isJavaScriptTabsConfig(value: Record<string, unknown>): boolean {
+  return (
+    hasNoDefinedKeys(value, [
+      'options',
+      'native',
+      'web',
+      'responsive',
+      'customPresentationId',
+      'minimizeBehavior',
+      'bottomAccessory',
+    ]) &&
+    (value.presentation === undefined ||
+      (typeof value.presentation === 'string' &&
+        JAVASCRIPT_TABS_PRESENTATION_SET.has(value.presentation)))
+  );
+}
+
+/*** Validate the native branch used by adaptive tabs. */
+function isNativeTabsConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['implementation', 'minimizeBehavior', 'bottomAccessory']) &&
+    value.implementation === 'native' &&
+    isNativeTabsFields(value)
+  );
+}
+
+/*** Validate fields supported by the native tabs branch. */
+function isNativeTabsFields(value: Record<string, unknown>): boolean {
+  return (
+    (value.minimizeBehavior === undefined ||
+      (typeof value.minimizeBehavior === 'string' &&
+        NATIVE_TABS_MINIMIZE_BEHAVIOR_SET.has(value.minimizeBehavior))) &&
+    (value.bottomAccessory === undefined || isNavigatorScreenReference(value.bottomAccessory))
+  );
+}
+
+/*** Validate the implementation-free custom-tabs Web branch inside adaptive tabs. */
+function isCustomTabsWebConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['presentation', 'responsive', 'customPresentationId']) &&
+    isCustomTabsPresentationConfig(value)
+  );
+}
+
+/*** Validate custom-tab presentation and its conditional serializable configuration. */
+function isCustomTabsPresentationConfig(value: Record<string, unknown>): boolean {
+  if (
+    typeof value.presentation !== 'string' ||
+    !CUSTOM_TABS_PRESENTATION_SET.has(value.presentation)
+  ) {
+    return false;
+  }
+  if (value.responsive !== undefined && !isResponsiveTabsPresentation(value.responsive)) {
+    return false;
+  }
+  if (!isOptionalString(value.customPresentationId)) return false;
+  if (FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.presentation)) {
+    return value.responsive === undefined && value.customPresentationId === undefined;
+  }
+  if (value.presentation === 'responsive') {
+    return value.responsive !== undefined && value.customPresentationId === undefined;
+  }
+  return (
+    value.responsive === undefined &&
+    typeof value.customPresentationId === 'string' &&
+    value.customPresentationId.length > 0
+  );
+}
+
+/*** Validate semantic compact/medium/expanded custom-tab presentation mapping. */
+function isResponsiveTabsPresentation(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['compact', 'medium', 'expanded']) &&
+    typeof value.compact === 'string' &&
+    FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.compact) &&
+    (value.medium === undefined ||
+      (typeof value.medium === 'string' && FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.medium))) &&
+    typeof value.expanded === 'string' &&
+    FIXED_CUSTOM_TABS_PRESENTATION_SET.has(value.expanded)
+  );
+}
+
+/*** Check that mutually exclusive branch fields are absent. */
+function hasNoDefinedKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const prohibited = new Set(keys);
+  return !Object.entries(value).some(([key, entry]) => prohibited.has(key) && entry !== undefined);
+}