@react-navigation/core 8.0.0-alpha.3 → 8.0.0-alpha.31

package/src/types.tsx

@@ -14,6 +14,7 @@ import type {
   FlatType,
   KeyOf,
   NotUndefined,
+  StandardSchemaV1,
   UnionToIntersection,
 } from './utilities';
 
@@ -54,13 +55,8 @@ export interface RootNavigator {}
 export interface Theme {}
 
 export type RootParamList =
-  RootNavigator extends TypedNavigatorInternal<
-    infer ParamList,
-    any,
-    any,
-    any,
-    any,
-    any
+  RootNavigator extends PrivateValueStore<
+    [infer ParamList extends {}, any, any, any]
   >
     ? ParamList
     : {};
@@ -82,58 +78,68 @@ export type DefaultNavigatorOptions<
    * Layout for the navigator.
    * Useful for wrapping with a component with access to navigator's state and options.
    */
-  layout?: (props: {
-    state: State;
-    navigation: NavigationHelpers<ParamList>;
-    descriptors: Record<
-      string,
-      Descriptor<
-        ScreenOptions,
-        NavigationProp<
-          ParamList,
-          keyof ParamList,
-          State,
-          ScreenOptions,
-          EventMap
-        >,
-        RouteProp<ParamList>
-      >
-    >;
-    children: React.ReactNode;
-  }) => React.ReactElement;
+  layout?:
+    | ((props: {
+        state: State;
+        navigation: NavigationHelpers<ParamList>;
+        descriptors: Record<
+          string,
+          Descriptor<
+            ScreenOptions,
+            NavigationProp<
+              ParamList,
+              keyof ParamList,
+              State,
+              ScreenOptions,
+              EventMap
+            >,
+            ScreenRouteProp<ParamList>
+          >
+        >;
+        children: React.ReactNode;
+      }) => React.ReactElement)
+    | undefined;
 
   /**
    * Event listeners for all the screens in the navigator.
    */
   screenListeners?:
-    | ScreenListeners<State, EventMap>
-    | ((props: {
-        route: RouteProp<ParamList>;
-        navigation: Navigation;
-      }) => ScreenListeners<State, EventMap>);
+    | (
+        | ScreenListeners<State, EventMap>
+        | ((props: {
+            route: ScreenRouteProp<ParamList>;
+            navigation: Navigation;
+          }) => ScreenListeners<State, EventMap>)
+      )
+    | undefined;
 
   /**
    * Default options for all screens under this navigator.
    */
   screenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: ScreenRouteProp<ParamList>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Layout for all screens under this navigator.
    */
-  screenLayout?: (
-    props: ScreenLayoutArgs<
-      ParamList,
-      keyof ParamList,
-      ScreenOptions,
-      Navigation
-    >
-  ) => React.ReactElement;
+  screenLayout?:
+    | ((
+        props: ScreenLayoutArgs<
+          ParamList,
+          keyof ParamList,
+          ScreenOptions,
+          Navigation
+        >
+      ) => React.ReactElement)
+    | undefined;
 
   /**
    * A function returning overrides for the underlying router used by the navigator.
@@ -142,9 +148,11 @@ export type DefaultNavigatorOptions<
    *
    * This must be a pure function and cannot reference outside dynamic variables.
    */
-  router?: <Action extends NavigationAction>(
-    original: Router<State, Action>
-  ) => Partial<Router<State, Action>>;
+  router?:
+    | (<Action extends NavigationAction>(
+        original: Router<State, Action>
+      ) => Partial<Router<State, Action>>)
+    | undefined;
 
   /**
    * What should happen when the available route names change.
@@ -165,15 +173,15 @@ export type DefaultNavigatorOptions<
    * - Direct navigation is only handled for `NAVIGATE` actions.
    * - Unhandled state is restored only if the current state becomes invalid, i.e. it doesn't contain any currently defined screens.
    */
-  routeNamesChangeBehavior?: 'firstMatch' | 'lastUnhandled';
+  routeNamesChangeBehavior?: ('firstMatch' | 'lastUnhandled') | undefined;
 };
 
 export type EventMapBase = Record<
   string,
-  { data?: any; canPreventDefault?: boolean }
+  { data?: any; canPreventDefault?: boolean | undefined }
 >;
 
-export type EventMapCore<State extends NavigationState> = {
+export type EventMapCore<in out State extends NavigationState> = {
   focus: { data: undefined };
   blur: { data: undefined };
   state: { data: { state: State } };
@@ -192,7 +200,7 @@ export type EventArg<
   /**
    * Key of the route which received the event.
    */
-  readonly target?: string;
+  readonly target?: string | undefined;
 } & (CanPreventDefault extends true
   ? {
       /**
@@ -206,15 +214,14 @@ export type EventArg<
     }
   : {}) &
   (undefined extends Data
-    ? { readonly data?: Readonly<Data> }
+    ? { readonly data?: Readonly<Data> | undefined }
     : { readonly data: Readonly<Data> });
 
 export type EventListenerCallback<
-  EventMap extends EventMapBase,
-  EventName extends keyof EventMap,
-  EventCanPreventDefault extends
-    | boolean
-    | undefined = EventMap[EventName]['canPreventDefault'],
+  in out EventMap extends EventMapBase,
+  in out EventName extends keyof EventMap,
+  in out EventCanPreventDefault extends boolean | undefined =
+    EventMap[EventName]['canPreventDefault'],
 > = (
   e: EventArg<
     EventName,
@@ -223,7 +230,7 @@ export type EventListenerCallback<
   >
 ) => void;
 
-export type EventConsumer<EventMap extends EventMapBase> = {
+export type EventConsumer<in out EventMap extends EventMapBase> = {
   /**
    * Subscribe to events from the parent navigator.
    *
@@ -240,7 +247,7 @@ export type EventConsumer<EventMap extends EventMapBase> = {
   ): void;
 };
 
-export type EventEmitter<EventMap extends EventMapBase> = {
+export type EventEmitter<in out EventMap extends EventMapBase> = {
   /**
    * Emit an event to child screens.
    *
@@ -266,7 +273,7 @@ export type EventEmitter<EventMap extends EventMapBase> = {
   >;
 };
 
-export class PrivateValueStore<T extends [any, any, any]> {
+export class PrivateValueStore<T extends [any, any, any, any]> {
   /**
    * UGLY HACK! DO NOT USE THE TYPE!!!
    *
@@ -280,6 +287,50 @@ export class PrivateValueStore<T extends [any, any, any]> {
   protected ''?: T;
 }
 
+type NavigatorLike =
+  | {
+      Navigator: React.ComponentType<any>;
+      Screen: unknown;
+      Group: unknown;
+    }
+  | {
+      config: unknown;
+      getComponent: () => React.ComponentType<any>;
+    };
+
+export type ParamListForNavigator<T extends {}> = T extends NavigatorLike
+  ? T extends PrivateValueStore<[infer ParamList extends {}, any, any, any]>
+    ? ParamList
+    : T
+  : T;
+
+// Remove `undefined` before checking for nested navigator params.
+// If nothing remains, avoid matching `never` against `NavigatorScreenParams`
+type NestedNavigatorForScreenParams<T, Params = NotUndefined<T>> = [
+  Params,
+] extends [never]
+  ? never
+  : Params extends NavigatorScreenParams<infer Navigator>
+    ? Navigator extends PrivateValueStore<[any, any, any, any]>
+      ? Navigator extends NavigatorLike
+        ? Navigator
+        : never
+      : never
+    : never;
+
+export type NestedNavigatorsForParamList<ParamList extends {}> = {
+  [RouteName in keyof ParamList as NestedNavigatorForScreenParams<
+    ParamList[RouteName]
+  > extends never
+    ? never
+    : RouteName]: NestedNavigatorForScreenParams<ParamList[RouteName]>;
+};
+
+type NavigateOptions = {
+  merge?: boolean | undefined;
+  pop?: boolean | undefined;
+};
+
 type NavigationHelpersCommon<
   ParamList extends ParamListBase,
   State extends NavigationState = NavigationState,
@@ -314,37 +365,16 @@ type NavigationHelpersCommon<
         ? [
             screen: RouteName,
             params?: ParamList[RouteName],
-            options?: { merge?: boolean; pop?: boolean },
+            options?: NavigateOptions,
           ]
         : [
             screen: RouteName,
             params: ParamList[RouteName],
-            options?: { merge?: boolean; pop?: boolean },
+            options?: NavigateOptions,
           ]
       : never
   ): void;
 
-  /**
-   * Navigate to a route in current navigation tree.
-   *
-   * @param options.name Name of the route to navigate to.
-   * @param [options.params] Params object for the route.
-   * @param [options.path] Path to associate the route with (e.g. for deep links).
-   * @param [options.merge] Whether to merge the params onto the route. Defaults to `false`.
-   * @param [options.pop] Whether to pop routes in a stack to go back to the matching route. Defaults to `false`.
-   */
-  navigate<RouteName extends keyof ParamList>(
-    options: RouteName extends unknown
-      ? {
-          name: RouteName;
-          params: ParamList[RouteName];
-          path?: string;
-          merge?: boolean;
-          pop?: boolean;
-        }
-      : never
-  ): void;
-
   /**
    * Preloads the route in current navigation tree.
    *
@@ -395,11 +425,11 @@ type NavigationHelpersCommon<
    * So don't use it in `render`.
    */
   getState(): State;
-} & PrivateValueStore<[ParamList, unknown, unknown]>;
+};
 
 type ParamType<
   ParamList extends {},
-  RouteName extends keyof ParamList | unknown,
+  RouteName,
   IsPartial extends boolean = false,
 > = RouteName extends keyof ParamList
   ? ParamList[RouteName] extends undefined
@@ -410,8 +440,8 @@ type ParamType<
   : unknown;
 
 type NavigationHelpersRoute<
-  ParamList extends {},
-  RouteName extends keyof ParamList = KeyOf<ParamList>,
+  in out ParamList extends {},
+  in out RouteName extends keyof ParamList = KeyOf<ParamList>,
 > = {
   /**
    * Update the param object for the route.
@@ -443,43 +473,51 @@ export type NavigationHelpers<
   EventMap extends EventMapBase = {},
 > = NavigationHelpersCommon<ParamList> &
   EventEmitter<EventMap> &
-  NavigationHelpersRoute<ParamList, keyof ParamList>;
+  NavigationHelpersRoute<ParamList, keyof ParamList> &
+  PrivateValueStore<[ParamList, unknown, unknown, unknown]>;
 
 export type NavigationContainerProps = {
   /**
    * Initial state object for the navigation tree.
    */
-  initialState?: InitialState;
+  initialState?: InitialState | undefined;
   /**
    * Callback which is called with the latest navigation state when it changes.
    */
-  onStateChange?: (state: Readonly<NavigationState> | undefined) => void;
+  onStateChange?:
+    | ((state: Readonly<NavigationState> | undefined) => void)
+    | undefined;
   /**
    * Callback which is called after the navigation tree mounts.
    */
-  onReady?: () => void;
+  onReady?: (() => void) | undefined;
   /**
    * Callback which is called when an action is not handled.
    */
-  onUnhandledAction?: (action: Readonly<NavigationAction>) => void;
+  onUnhandledAction?:
+    | ((action: Readonly<NavigationAction>) => void)
+    | undefined;
   /**
    * Theme object for the UI elements.
    */
-  theme?: Theme;
+  theme?: Theme | undefined;
   /**
    * Children elements to render.
    */
   children: React.ReactNode;
 };
 
-export type NavigationProp<
+// Everything in `NavigationProp` except `getParent` and the private brand.
+// The composite navigation prop intersects this directly, so it doesn't have
+// to walk `NavigationProp`'s members with `Omit` to drop `getParent`/the brand.
+type NavigationPropBase<
   ParamList extends {},
   RouteName extends keyof ParamList = KeyOf<ParamList>,
   State extends NavigationState = NavigationState<ParamList>,
   ScreenOptions extends {} = {},
   EventMap extends EventMapBase = {},
   ActionHelpers extends Record<string, (...args: any) => void> = {},
-> = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
+> = NavigationHelpersCommon<ParamList, State> & {
   /**
    * Update the options for the route.
    * The options object will be shallow merged with default options object.
@@ -487,6 +525,25 @@ export type NavigationProp<
    * @param options Partial options object for the current screen.
    */
   setOptions(options: Partial<ScreenOptions>): void;
+} & NavigationHelpersRoute<ParamList, RouteName> &
+  ActionHelpers &
+  EventConsumer<EventMap & EventMapCore<State>>;
+
+export type NavigationProp<
+  ParamList extends {},
+  RouteName extends keyof ParamList = KeyOf<ParamList>,
+  State extends NavigationState = NavigationState<ParamList>,
+  ScreenOptions extends {} = {},
+  EventMap extends EventMapBase = {},
+  ActionHelpers extends Record<string, (...args: any) => void> = {},
+> = NavigationPropBase<
+  ParamList,
+  RouteName,
+  State,
+  ScreenOptions,
+  EventMap,
+  ActionHelpers
+> & {
   /**
    * Returns the navigation prop of the parent screen.
    * If a route name is provided, the navigation prop from the parent screen with matching route name (including current) will be returned.
@@ -505,58 +562,100 @@ export type NavigationProp<
     ActionHelpers
   >;
   getParent(): NavigationProp<ParamListBase> | undefined;
-} & NavigationHelpersRoute<ParamList, RouteName> &
-  ActionHelpers &
-  EventConsumer<EventMap & EventMapCore<State>> &
-  PrivateValueStore<[ParamList, RouteName, EventMap]>;
+} & PrivateValueStore<[ParamList, RouteName, EventMap, ActionHelpers]>;
 
 export type RouteProp<
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList = KeyOf<ParamList>,
+> = Route<Extract<RouteName, string>, ParamList[RouteName]>;
+
+type ScreenRouteProp<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList = KeyOf<ParamList>,
-> = Route<Extract<RouteName, string>, ParamList[RouteName]>;
+> = {
+  [Name in Extract<RouteName, string>]: RouteProp<ParamList, Name>;
+}[Extract<RouteName, string>];
 
 export type CompositeNavigationProp<
   A extends NavigationProp<ParamListBase, any, any, any, any>,
   B extends NavigationProp<ParamListBase, any, any, any, any>,
-> = Omit<A & B, keyof NavigationProp<any, any, any, any, any>> &
-  Omit<
-    NavigationProp<
-      /**
-       * Param list from both navigation objects needs to be combined
-       * For example, we should be able to navigate to screens in both A and B
-       */
-      (A extends NavigationHelpersCommon<infer T> ? T : never) &
-        (B extends NavigationHelpersCommon<infer U> ? U : never),
-      /**
-       * The route name should refer to the route name specified in the first type
-       * Ideally it should work for any of them, but it's not possible to infer that way
-       */
-      A extends NavigationProp<any, infer R> ? R : string,
-      /**
-       * The type of state should refer to the state specified in the first type
-       */
-      A extends NavigationProp<any, any, infer S> ? S : NavigationState,
-      /**
-       * Screen options should refer to the options specified in the first type
-       */
-      A extends NavigationProp<any, any, any, infer O> ? O : {},
-      /**
-       * Event consumer config should refer to the config specified in the first type
-       * This allows typechecking `addListener`/`removeListener`
-       */
-      A extends NavigationProp<any, any, any, any, infer E> ? E : {}
-    >,
-    'getParent'
-  > & {
-    getParent: A['getParent'] & B['getParent'];
-  };
+> = CompositeNavigationPropInternal<
+  A,
+  B,
+  /**
+   * Param list from both navigation objects needs to be combined
+   * For example, we should be able to navigate to screens in both A and B
+   */
+  ParamListOfNavigationProp<A> & ParamListOfNavigationProp<B>,
+  /**
+   * The route name should refer to the route name specified in the first type
+   */
+  RouteNameOfNavigationProp<A>,
+  /**
+   * Event map should refer to the config specified in the first type
+   */
+  EventMapOfNavigationProp<A>
+>;
+
+type CompositeNavigationPropInternal<
+  A extends NavigationProp<ParamListBase, any, any, any, any>,
+  B extends NavigationProp<ParamListBase, any, any, any, any>,
+  ParamList extends {},
+  RouteName extends keyof ParamList,
+  EventMap extends EventMapBase,
+> = // Action helpers are read from the private brand (4th slot) instead of
+  // `Omit<A & B, keyof NavigationProp>`, which had to walk the whole (possibly
+  // deeply composed) member set of `A & B` to drop the standard members.
+  ActionHelpersOfNavigationProp<A> &
+    ActionHelpersOfNavigationProp<B> &
+    // Intersect the brand-free base directly instead of `Omit`-ing `getParent`
+    // off a full `NavigationProp`, so we skip a mapped-type pass per composite.
+    NavigationPropBase<
+      ParamList,
+      RouteName,
+      StateOfNavigationProp<A>,
+      ScreenOptionsOfNavigationProp<A>,
+      EventMap
+    > & {
+      getParent: A['getParent'] & B['getParent'];
+    } & PrivateValueStore<
+      [
+        ParamList,
+        RouteName,
+        EventMap,
+        ActionHelpersOfNavigationProp<A> & ActionHelpersOfNavigationProp<B>,
+      ]
+    >;
+
+type PrivateValueOfNavigationProp<T> =
+  T extends PrivateValueStore<infer Value> ? Value : [never, unknown, {}, {}];
+
+type ParamListOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[0];
+
+type RouteNameOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[1];
+
+type ActionHelpersOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[3];
+
+type StateOfNavigationProp<T> = T extends {
+  getState: () => infer State extends NavigationState;
+}
+  ? State
+  : NavigationState;
+
+type ScreenOptionsOfNavigationProp<T> = T extends {
+  setOptions: (options: Partial<infer ScreenOptions>) => void;
+}
+  ? ScreenOptions
+  : {};
+
+type EventMapOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[2];
 
 export type CompositeScreenProps<
-  A extends {
+  in out A extends {
     navigation: NavigationProp<ParamListBase, string, any, any, any>;
     route: RouteProp<ParamListBase>;
   },
-  B extends {
+  in out B extends {
     navigation: NavigationProp<ParamListBase, string, any, any, any>;
   },
 > = {
@@ -565,12 +664,12 @@ export type CompositeScreenProps<
 };
 
 export type ScreenLayoutArgs<
-  ParamList extends ParamListBase,
-  RouteName extends keyof ParamList,
-  ScreenOptions extends {},
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList,
+  in out ScreenOptions extends {},
+  in out Navigation,
 > = {
-  route: RouteProp<ParamList, RouteName>;
+  route: ScreenRouteProp<ParamList, RouteName>;
   options: ScreenOptions;
   navigation: Navigation;
   theme: Theme;
@@ -578,9 +677,9 @@ export type ScreenLayoutArgs<
 };
 
 export type Descriptor<
-  ScreenOptions extends {},
-  Navigation extends NavigationProp<any, any, any, any, any>,
-  Route extends RouteProp<any, any>,
+  out ScreenOptions extends {},
+  out Navigation extends NavigationProp<ParamListBase, any, any, any, any>,
+  out Route extends RouteProp<any, any>,
 > = {
   /**
    * Render the component associated with this route.
@@ -604,8 +703,8 @@ export type Descriptor<
 };
 
 export type ScreenListeners<
-  State extends NavigationState,
-  EventMap extends EventMapBase,
+  in out State extends NavigationState,
+  in out EventMap extends EventMapBase,
 > = Partial<{
   [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
     EventMap & EventMapCore<State>,
@@ -656,19 +755,19 @@ export type RouteConfigComponent<
     };
 
 export type RouteConfigProps<
-  ParamList extends ParamListBase,
-  RouteName extends keyof ParamList,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList,
+  in out State extends NavigationState,
+  in out ScreenOptions extends {},
+  in out EventMap extends EventMapBase,
+  in out Navigation,
 > = {
   /**
    * Optional key for this screen. This doesn't need to be unique.
    * If the key changes, existing screens with this name will be removed or reset.
    * Useful when we have some common screens and have conditional rendering.
    */
-  navigationKey?: string;
+  navigationKey?: string | undefined;
 
   /**
    * Route name of this screen.
@@ -679,31 +778,39 @@ export type RouteConfigProps<
    * Navigator options for this screen.
    */
   options?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList, RouteName>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: RouteProp<ParamList, RouteName>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Event listeners for this screen.
    */
   listeners?:
-    | ScreenListeners<State, EventMap>
-    | ((props: {
-        route: RouteProp<ParamList, RouteName>;
-        navigation: Navigation;
-      }) => ScreenListeners<State, EventMap>);
+    | (
+        | ScreenListeners<State, EventMap>
+        | ((props: {
+            route: RouteProp<ParamList, RouteName>;
+            navigation: Navigation;
+          }) => ScreenListeners<State, EventMap>)
+      )
+    | undefined;
 
   /**
    * Layout for this screen.
    * Useful for wrapping the screen with custom containers.
    * e.g. for styling, error boundaries, suspense, etc.
    */
-  layout?: (
-    props: ScreenLayoutArgs<ParamList, RouteName, ScreenOptions, Navigation>
-  ) => React.ReactElement;
+  layout?:
+    | ((
+        props: ScreenLayoutArgs<ParamList, RouteName, ScreenOptions, Navigation>
+      ) => React.ReactElement)
+    | undefined;
 
   /**
    * Function to return an unique ID for this screen.
@@ -711,16 +818,18 @@ export type RouteConfigProps<
    * For a given screen name, there will always be only one screen corresponding to an ID.
    * If `undefined` is returned, it acts same as no `getId` being specified.
    */
-  getId?: ({
-    params,
-  }: {
-    params: Readonly<ParamList[RouteName]>;
-  }) => string | undefined;
+  getId?:
+    | (({
+        params,
+      }: {
+        params: Readonly<ParamList[RouteName]>;
+      }) => string | undefined)
+    | undefined;
 
   /**
    * Initial params object for the route.
    */
-  initialParams?: Partial<ParamList[RouteName]>;
+  initialParams?: Partial<ParamList[RouteName]> | undefined;
 };
 
 export type RouteConfig<
@@ -741,43 +850,49 @@ export type RouteConfig<
   RouteConfigComponent<ParamList, RouteName>;
 
 export type RouteGroupConfig<
-  ParamList extends ParamListBase,
-  ScreenOptions extends {},
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out ScreenOptions extends {},
+  in out Navigation,
 > = {
   /**
    * Optional key for the screens in this group.
    * If the key changes, all existing screens in this group will be removed or reset.
    */
-  navigationKey?: string;
+  navigationKey?: string | undefined;
 
   /**
    * Navigator options for this screen.
    */
   screenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList, keyof ParamList>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: ScreenRouteProp<ParamList>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Layout for the screens inside the group.
    * This will override the `screenLayout` of parent group or navigator.
    */
   screenLayout?:
-    | ((
-        props: ScreenLayoutArgs<
-          ParamList,
-          keyof ParamList,
-          ScreenOptions,
-          Navigation
-        >
-      ) => React.ReactElement)
-    | {
-        // FIXME: TypeScript doesn't seem to infer `navigation` correctly without this
-      };
+    | (
+        | ((
+            props: ScreenLayoutArgs<
+              ParamList,
+              keyof ParamList,
+              ScreenOptions,
+              Navigation
+            >
+          ) => React.ReactElement)
+        | {
+            // FIXME: TypeScript doesn't seem to infer `navigation` correctly without this
+          }
+      )
+    | undefined;
 
   /**
    * Children React Elements to extract the route configuration from.
@@ -843,15 +958,19 @@ export type NavigationContainerEventMap = {
       /**
        * The data object passed when emitting the event.
        */
-      data: unknown;
+      data?: unknown;
       /**
        * The key of the target route which received the event.
        */
-      target: string | undefined;
+      target?: string | undefined;
       /**
        * Whether `event.preventDefault()` was called on this event.
        */
-      defaultPrevented: boolean | undefined;
+      defaultPrevented?: boolean | undefined;
+      /**
+       * Prevent the default action which happens on this event.
+       */
+      preventDefault?: (() => void) | undefined;
     };
   };
 };
@@ -922,12 +1041,44 @@ export type GenericNavigation<ParamList extends {}> = Omit<
 export type RouteForName<
   ParamList extends {},
   RouteName extends string,
-> = Extract<ParamListRoute<ParamList>, { name: RouteName }>;
+> = string extends RouteName
+  ? // RouteName is a not a literal but `string`
+    // Return union of all possible routes in the tree
+    ParamListRoute<ParamList>
+  : RouteForNameInternal<ParamList, RouteName>;
+
+// Look up route object by checking each level and recursing into the nested param lists
+// This avoids building a union of all routes, which doesn't scale on large trees
+type RouteForNameInternal<ParamList extends {}, RouteName extends string> =
+  | (RouteName extends KeyOf<ParamList>
+      ? RouteProp<ParamList, RouteName>
+      : never)
+  | RouteForNameNested<NestedParamLists<ParamList>, RouteName>;
+
+type RouteForNameNested<ParamLists, RouteName extends string> =
+  // Distributes over the union of nested param lists
+  // e.g. if ParamLists is A | B
+  // TypeScript evaluates the branch once per member (A, then B)
+  // and unions the outcomes
+  ParamLists extends {} ? RouteForNameInternal<ParamLists, RouteName> : never;
+
+/**
+ * Union of param lists of the nested navigators in a param list.
+ */
+export type NestedParamLists<ParamList extends {}> = {
+  [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
+    ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<infer T>
+      ? ParamListForNavigator<T>
+      : never
+    : never;
+}[keyof ParamList];
 
 type ParamListRoute<ParamList extends {}> = {
   [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
     ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<infer T>
-      ? ParamListRoute<T> | RouteProp<ParamList, RouteName>
+      ?
+          | ParamListRoute<ParamListForNavigator<T>>
+          | RouteProp<ParamList, RouteName>
       : RouteProp<ParamList, RouteName>
     : RouteProp<ParamList, RouteName>;
 }[keyof ParamList];
@@ -938,11 +1089,10 @@ type MaybeParamListRoute<ParamList extends {}> = ParamList extends ParamListBase
 
 type BasicNavigationComposite<
   Navigation extends NavigationProp<any, any, any, any, any>,
-  Parent,
-> =
-  Parent extends NavigationProp<any, any, any, any, any>
-    ? CompositeNavigationProp<Navigation, Parent>
-    : Navigation;
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = Parent extends undefined
+  ? Navigation
+  : CompositeNavigationProp<Navigation, NonNullable<Parent>>;
 
 type BasicNavigationList<
   ParamList extends {},
@@ -954,11 +1104,15 @@ type BasicNavigationList<
       ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<
           infer T
         >
-        ? BasicNavigationList<
-            T,
-            ExcludedRouteNames,
-            NavigationProp<ParamList, RouteName>
-          >
+        ? ParamListForNavigator<T> extends infer NestedParamList extends {}
+          ? keyof NestedParamList extends ExcludedRouteNames
+            ? {}
+            : BasicNavigationList<
+                NestedParamList,
+                ExcludedRouteNames,
+                NavigationProp<ParamList, RouteName>
+              >
+          : {}
         : {}
       : {}) &
       (RouteName extends ExcludedRouteNames
@@ -972,178 +1126,407 @@ type BasicNavigationList<
   }[keyof ParamList]
 >;
 
-export type NavigationListForNavigator<Navigator> =
-  Navigator extends TypedNavigator<infer Bag, any>
-    ? Bag['NavigationList']
-    : Navigator extends PrivateValueStore<[any, infer NavigationList, any]>
-      ? NavigationList
-      : {};
-
-export type NavigationListForNested<Navigator> = FlatType<
-  NavigationListForNestedInternal<Navigator> &
-    (Navigator extends TypedNavigator<infer Bag, any>
-      ? BasicNavigationList<
-          Bag['ParamList'],
-          keyof NavigationListForNestedInternal<Navigator>,
-          undefined
-        >
-      : Navigator extends PrivateValueStore<[infer ParamList, any, any]>
-        ? ParamList extends {}
-          ? BasicNavigationList<
-              ParamList,
-              keyof NavigationListForNestedInternal<Navigator>,
-              undefined
-            >
-          : {}
-        : {})
->;
+type InheritedParentParams<ParentParamList, ParamList> = {
+  [K in keyof ParentParamList as K extends keyof ParamList
+    ? never
+    : string extends K
+      ? never
+      : K]: ParentParamList[K];
+};
 
-type NavigationListForNestedInternal<Navigator> =
-  NavigationListForNavigator<Navigator> &
-    NavigationListForStaticConfig<
-      NavigationListForNavigator<Navigator>,
-      Navigator
+type GenericNavigationComposite<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  Parent,
+> =
+  Parent extends NavigationProp<any, any, any, any, any>
+    ? ParamListOfNavigationProp<Parent> extends infer ParentParamList
+      ? NavigationProp<
+          ParamList & InheritedParentParams<ParentParamList, ParamList>,
+          RouteName
+        > & { getParent: Parent['getParent'] }
+      : never
+    : NavigationProp<ParamList, RouteName>;
+
+type NavigationListForScreenParams<
+  T extends {},
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = T extends PrivateValueStore<[any, any, any, any]> & NavigatorLike
+  ? NavigationListForNestedInternal<
+      T,
+      GenericNavigationComposite<ParamList, RouteName, Parent>
+    >
+  : NavigationListForParamListScreenParams<
+      T,
+      ParamList,
+      RouteName,
+      ExcludedRouteNames,
+      Parent
     >;
 
-type NavigationListWithComposite<
-  Parent extends NavigationProp<any, any, any, any, any>,
-  NavigatorList extends Record<string, any>,
-> = {
-  [K in keyof NavigatorList]: CompositeNavigationProp<NavigatorList[K], Parent>;
-};
+type NavigationListForParamListScreenParams<
+  T extends {},
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> =
+  // `T` is only ever a plain param list here, since navigators are routed to
+  // `NavigationListForNestedInternal` by `NavigationListForScreenParams`.
+  // So there's no navigator to unwrap with `ParamListForNavigator`.
+  T extends ParamListBase
+    ? BasicNavigationListForParamList<
+        T,
+        ExcludedRouteNames,
+        GenericNavigationComposite<ParamList, RouteName, Parent>
+      >
+    : {};
+
+type BasicNavigationListForParamList<
+  ParamList extends ParamListBase,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = UnionToIntersection<
+  {
+    [RouteName in keyof ParamList]: (NavigatorScreenParams<{}> extends ParamList[RouteName]
+      ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<
+          infer T
+        >
+        ? NavigationListForScreenParams<
+            T,
+            ParamList,
+            RouteName,
+            ExcludedRouteNames,
+            Parent
+          >
+        : {}
+      : {}) &
+      (RouteName extends ExcludedRouteNames
+        ? {}
+        : {
+            [Key in RouteName]: GenericNavigationComposite<
+              ParamList,
+              RouteName,
+              Parent
+            >;
+          });
+  }[keyof ParamList]
+>;
 
-type NavigationListForStaticConfig<ParentList, Navigator> = Navigator extends {
+export type NavigationListForNavigator<Navigator> =
+  Navigator extends PrivateValueStore<infer Value> ? Value[1] : {};
+
+export type NavigationListForNested<Navigator> =
+  NavigationListForNestedInternal<Navigator> extends infer NavigationList
+    ? Navigator extends PrivateValueStore<[infer ParamList, any, any, any]>
+      ? ParamList extends {}
+        ? NavigationList &
+            BasicNavigationList<ParamList, keyof NavigationList, undefined>
+        : NavigationList
+      : NavigationList
+    : never;
+
+type NavigationListForNestedInternal<
+  Navigator,
+  Parent = undefined,
+  NavigatorList extends Record<string, any> =
+    NavigationListForNavigator<Navigator>,
+  Navigators = NestedNavigatorsOf<Navigator>,
+  // This navigator's own routes, each composed with the accumulated parent.
+  // It's threaded into the recursion as the parent for nested navigators so
+  // each route is composed with its ancestors exactly once, instead of
+  // re-wrapping the whole descendant list at every level (which is quadratic
+  // in the nesting depth).
+  ComposedList = ComposeNavigationList<NavigatorList, Parent>,
+> = (Navigator extends {
   readonly config: {
-    screens?: any;
-    groups?: any;
+    readonly screens?: infer Screens;
+    readonly groups?: infer Groups;
   };
 }
-  ? NavigationListForScreens<ParentList, Navigator['config']['screens']> &
-      NavigationListForGroups<ParentList, Navigator['config']['groups']>
-  : {};
+  ? ComposedList &
+      NavigationListForScreens<ComposedList, Screens> &
+      NavigationListForGroups<ComposedList, Groups>
+  : ComposedList) &
+  NavigationListForNestedNavigators<ComposedList, Navigators> &
+  NavigationListForDynamicNestedParamLists<Navigator, ComposedList, Navigators>;
+
+type NavigationListForDynamicNestedParamLists<
+  Navigator,
+  ParentList,
+  Navigators,
+> = Navigator extends { readonly config: unknown }
+  ? {}
+  : Navigator extends PrivateValueStore<[infer ParamList, any, any, any]>
+    ? NavigationListForNestedParamLists<ParentList, ParamList, Navigators>
+    : {};
 
-type NavigationListForScreens<ParentList, Screens> = UnionToIntersection<
-  {
-    // Only check screens with static config to avoid overly-complex types
-    // Otherwise TypeScript fails to load the types due to complexity
-    [K in keyof Screens]: ParentList extends Record<K, any>
-      ? Screens[K] extends { config: any }
-        ? NavigationListWithComposite<
-            ParentList[K],
-            NavigationListForNested<Screens[K]>
-          >
-        : Screens[K] extends { screen: { config: any } }
-          ? NavigationListWithComposite<
-              ParentList[K],
-              NavigationListForNested<Screens[K]['screen']>
-            >
-          : {}
-      : {};
-  }[keyof Screens]
->;
+// Map of route name to nested navigator type
+// inferred from `NavigatorScreenParams<typeof Navigator>`
+type NestedNavigatorsOf<Navigator> =
+  Navigator extends PrivateValueStore<[any, any, any, infer Nesting]>
+    ? Nesting extends Record<string, any>
+      ? Nesting
+      : {}
+    : {};
 
-type NavigationListForGroups<ParentList, Groups> =
-  Groups extends Record<string, { screens: any }>
-    ? UnionToIntersection<
-        {
-          [K in keyof Groups]: NavigationListForScreens<
-            ParentList,
-            Groups[K]['screens']
-          >;
-        }[keyof Groups]
-      >
+// Like `NavigationListForScreens`, but reads nested navigators from the brand
+// map instead of a static config.
+type NavigationListForNestedNavigators<ParentList, Navigators> =
+  UnionToIntersection<
+    {
+      [K in keyof Navigators]: K extends keyof ParentList
+        ? NavigationListForNestedInternal<Navigators[K], ParentList[K]>
+        : {};
+    }[keyof Navigators]
+  >;
+
+// Fallback for dynamic nested routes declared through NavigatorScreenParams<ParamList>.
+// Param-list branches expose generic navigation props, while nested navigator
+// entries still recover their concrete navigator props.
+type NavigationListForNestedParamLists<ParentList, ParamList, Navigators> =
+  ParentList extends Record<string, any>
+    ? ParamList extends ParamListBase
+      ? UnionToIntersection<
+          {
+            [K in keyof ParamList]: K extends keyof Navigators
+              ? {}
+              : K extends keyof ParentList
+                ? NavigatorScreenParams<{}> extends ParamList[K]
+                  ? NotUndefined<ParamList[K]> extends NavigatorScreenParams<
+                      infer T
+                    >
+                    ? NavigationListForScreenParams<
+                        T,
+                        ParamList,
+                        K,
+                        keyof ParentList,
+                        ParentList[K]
+                      >
+                    : {}
+                  : {}
+                : {};
+          }[keyof ParamList]
+        >
+      : {}
     : {};
 
-export type NavigationContainerRef<ParamList extends {}> =
-  NavigationHelpers<ParamList> &
-    EventConsumer<NavigationContainerEventMap> & {
-      /**
-       * Reset the navigation state of the root navigator to the provided state.
-       *
-       * @param state Navigation state object.
-       */
-      resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
-      /**
-       * Get the rehydrated navigation state of the navigation tree.
-       */
-      getRootState(): NavigationState;
-      /**
-       * Get the currently focused navigation route.
-       */
-      getCurrentRoute(): MaybeParamListRoute<ParamList> | undefined;
-      /**
-       * Get the currently focused route's options.
-       */
-      getCurrentOptions(): object | undefined;
-      /**
-       * Whether the navigation container is ready to handle actions.
-       */
-      isReady(): boolean;
-      /**
-       * Stub function for setOptions on navigation object for use with useNavigation.
-       */
-      setOptions(): never;
-      /**
-       * Stub function for getParent on navigation object for use with useNavigation.
-       */
-      getParent(): undefined;
-    };
+// Compose every entry in a navigator's list with the accumulated parent.
+// When there's no parent (root navigator), the list is returned as-is so the
+// common shallow case doesn't pay for a redundant mapped type.
+type ComposeNavigationList<NavigatorList extends Record<string, any>, Parent> =
+  Parent extends NavigationProp<any, any, any, any, any>
+    ? {
+        [K in keyof NavigatorList]: CompositeNavigationProp<
+          NavigatorList[K],
+          Parent
+        >;
+      }
+    : NavigatorList;
+
+type NavigationListForScreens<ParentList, Screens> = Screens extends {}
+  ? UnionToIntersection<
+      {
+        // Only check screens with static config to avoid overly-complex types
+        // Otherwise TypeScript fails to load the types due to complexity
+        [K in keyof Screens]: Screens[K] extends { config: any }
+          ? K extends keyof ParentList
+            ? NavigationListForNestedInternal<Screens[K], ParentList[K]>
+            : never
+          : Screens[K] extends { screen: { config: any } }
+            ? K extends keyof ParentList
+              ? NavigationListForNestedInternal<
+                  Screens[K]['screen'],
+                  ParentList[K]
+                >
+              : never
+            : never;
+      }[keyof Screens]
+    >
+  : {};
+
+type NavigationListForGroups<ParentList, Groups> = Groups extends {}
+  ? UnionToIntersection<
+      {
+        [K in keyof Groups]: Groups[K] extends { screens: any }
+          ? NavigationListForScreens<ParentList, Groups[K]['screens']>
+          : never;
+      }[keyof Groups]
+    >
+  : {};
+
+export type NavigationContainerRef<ParamList extends {}> = Omit<
+  NavigationHelpers<ParamList>,
+  keyof NavigationHelpersRoute<{}>
+> &
+  NavigationHelpersRoute<{}> &
+  EventConsumer<NavigationContainerEventMap> & {
+    /**
+     * Reset the navigation state of the root navigator to the provided state.
+     *
+     * @param state Navigation state object.
+     */
+    resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
+    /**
+     * Get the rehydrated navigation state of the navigation tree.
+     */
+    getRootState(): NavigationState;
+    /**
+     * Get the currently focused navigation route.
+     */
+    getCurrentRoute(): MaybeParamListRoute<ParamList> | undefined;
+    /**
+     * Get the currently focused route's options.
+     */
+    getCurrentOptions(): object | undefined;
+    /**
+     * Whether the navigation container is ready to handle actions.
+     */
+    isReady(): boolean;
+    /**
+     * Stub function for setOptions on navigation object for use with useNavigation.
+     */
+    setOptions(): never;
+  };
 
 export type NavigationContainerRefWithCurrent<ParamList extends {}> =
   NavigationContainerRef<ParamList> & {
     current: NavigationContainerRef<ParamList> | null;
   };
 
-export type NavigationListBase<ParamList extends ParamListBase> = {
+export type NavigationListBase<in out ParamList extends ParamListBase> = {
   [RouteName in keyof ParamList]: unknown;
 };
 
-export type NavigatorTypeBagBase = {
+// Only use action helpers if all values are functions
+type ActionHelpersOf<T> =
+  T extends Record<string, (...args: any) => void> ? T : {};
+
+export interface NavigatorTypeBagBase {
   ParamList: {};
   State: NavigationState;
   ScreenOptions: {};
   EventMap: {};
-  NavigationList: NavigationListBase<ParamListBase>;
+  ActionHelpers: {};
+  NavigationList: {
+    [RouteName in keyof this['ParamList']]: NavigationProp<
+      this['ParamList'],
+      RouteName,
+      this['State'],
+      this['ScreenOptions'],
+      this['EventMap'],
+      ActionHelpersOf<this['ActionHelpers']>
+    >;
+  };
   Navigator: React.ComponentType<any>;
-};
+}
 
-export type TypedNavigator<
-  Bag extends NavigatorTypeBagBase,
-  Config = unknown,
-> = TypedNavigatorInternal<
-  Bag['ParamList'],
-  Bag['State'],
-  Bag['ScreenOptions'],
-  Bag['EventMap'],
-  Bag['NavigationList'],
-  Bag['Navigator']
-> &
-  (undefined extends Config ? {} : { config: Config }) &
-  PrivateValueStore<[Bag['ParamList'], Bag['NavigationList'], unknown]>;
+/**
+ * Adds a proper `ParamList` to a type bag interface
+ * So it can be used as `this['ParamList']`
+ */
+export type NavigatorTypeBagFor<
+  TypeBag extends NavigatorTypeBagBase,
+  ParamList extends {},
+> = TypeBag & { ParamList: ParamList };
 
-type TypedNavigatorInternal<
+export type NavigatorProps<
   ParamList extends ParamListBase,
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
-  NavigationList extends NavigationListBase<ParamList>,
+  Navigation,
   Navigator extends React.ComponentType<any>,
+> = Omit<
+  React.ComponentProps<Navigator>,
+  keyof DefaultNavigatorOptions<any, any, any, any, any>
+> &
+  DefaultNavigatorOptions<
+    ParamList,
+    State,
+    ScreenOptions,
+    EventMap,
+    Navigation
+  >;
+
+type TypedNavigatorStaticComponent<Bag extends NavigatorTypeBagBase> =
+  React.ComponentType<
+    Partial<
+      Omit<
+        NavigatorProps<
+          Bag['ParamList'],
+          Bag['State'],
+          Bag['ScreenOptions'],
+          Bag['EventMap'],
+          Bag['NavigationList'][keyof Bag['ParamList']],
+          Bag['Navigator']
+        >,
+        'children'
+      >
+    >
+  >;
+
+type TypedNavigatorStaticDecorated<Bag extends NavigatorTypeBagBase, Config> = {
+  getComponent: () => React.ComponentType<{}>;
+  config: Config;
+} & PrivateValueStore<
+  [Bag['ParamList'], Bag['NavigationList'], unknown, unknown]
+>;
+
+type TypedNavigatorStatic<
+  in out Bag extends NavigatorTypeBagBase,
+  in out Config,
+> = {
+  config: Config;
+  with: (
+    Component: React.ComponentType<{
+      Navigator: TypedNavigatorStaticComponent<Bag>;
+    }>
+  ) => TypedNavigatorStaticDecorated<Bag, Config>;
+  getComponent: () => TypedNavigatorStaticComponent<Bag>;
+};
+
+export type TypedNavigator<
+  Bag extends NavigatorTypeBagBase,
+  Config = unknown,
+  Nesting = unknown,
+> = (undefined extends Config
+  ? TypedNavigatorInternal<
+      Bag['ParamList'],
+      Bag['State'],
+      Bag['ScreenOptions'],
+      Bag['EventMap'],
+      Bag['NavigationList'],
+      Bag['Navigator']
+    >
+  : TypedNavigatorStatic<Bag, Config>) &
+  PrivateValueStore<
+    [Bag['ParamList'], Bag['NavigationList'], unknown, Nesting]
+  >;
+
+type TypedNavigatorInternal<
+  in out ParamList extends ParamListBase,
+  in out State extends NavigationState,
+  in out ScreenOptions extends {},
+  in out EventMap extends EventMapBase,
+  in out NavigationList extends NavigationListBase<ParamList>,
+  in out Navigator extends React.ComponentType<any>,
 > = {
   /**
    * Navigator component which manages the child screens.
    */
   Navigator: React.ComponentType<
-    Omit<
-      React.ComponentProps<Navigator>,
-      keyof DefaultNavigatorOptions<any, any, any, any, any>
-    > &
-      DefaultNavigatorOptions<
-        ParamList,
-        State,
-        ScreenOptions,
-        EventMap,
-        NavigationList[keyof ParamList]
-      >
+    NavigatorProps<
+      ParamList,
+      State,
+      ScreenOptions,
+      EventMap,
+      NavigationList[keyof ParamList],
+      Navigator
+    >
   >;
   /**
    * Component used for grouping multiple route configuration.
@@ -1166,40 +1549,59 @@ type TypedNavigatorInternal<
   ) => null;
 };
 
-export type NavigatorScreenParams<ParamList extends {}> =
+declare const NavigatorScreenParamsSymbol: unique symbol;
+
+type NavigatorScreenParamsBrand<T extends {}> = {
+  // Preserve the original generic for inference without affecting assignability.
+  // - The symbol key hides the property from normal object usage
+  // - The actual type is intersected for inference
+  // - The `any` makes the property effectively `any` for assignability
+  readonly [NavigatorScreenParamsSymbol]?: any & { readonly type: T };
+};
+
+type NavigatorScreenParamsForParamList<ParamList extends {}> =
   | {
       screen?: never;
       params?: never;
       merge?: never;
       initial?: never;
       pop?: never;
-      path?: string;
+      preload?: never;
+      path?: string | undefined;
       state: PartialState<NavigationState> | NavigationState | undefined;
     }
   | {
       [RouteName in keyof ParamList]: undefined extends ParamList[RouteName]
         ? {
             screen: RouteName;
-            params?: ParamList[RouteName];
-            merge?: boolean;
-            initial?: boolean;
-            path?: string;
-            pop?: boolean;
+            params?: ParamList[RouteName] | undefined;
+            merge?: boolean | undefined;
+            initial?: boolean | undefined;
+            path?: string | undefined;
+            pop?: boolean | undefined;
+            preload?: boolean | undefined;
             state?: never;
           }
         : {
             screen: RouteName;
             params: ParamList[RouteName];
-            merge?: boolean;
-            initial?: boolean;
-            path?: string;
-            pop?: boolean;
+            merge?: boolean | undefined;
+            initial?: boolean | undefined;
+            path?: string | undefined;
+            pop?: boolean | undefined;
+            preload?: boolean | undefined;
             state?: never;
           };
     }[keyof ParamList];
 
+export type NavigatorScreenParams<ParamList extends {}> =
+  NavigatorScreenParamsForParamList<ParamListForNavigator<ParamList>> &
+    NavigatorScreenParamsBrand<ParamList>;
+
 type ParseConfig<Params> = {
-  [K in keyof Params]?: (value: string) => Params[K];
+  [K in keyof Params]?:
+    | ((value: string) => Params[K])
+    | StandardSchemaV1<string | string[] | null | undefined, Params[K]>;
 };
 
 type StringifyConfig<Params> = {
@@ -1217,9 +1619,9 @@ type PathConfigAlias<Params> = {
    * By default, paths are relating to the path config on the parent screen.
    * If `exact` is set to `true`, the parent path configuration is not used.
    */
-  exact?: boolean;
+  exact?: boolean | undefined;
   /**
-   * An object mapping the param name to a function which parses the param value.
+   * An object mapping the param name to a parser function or a Standard Schema.
    *
    * @example
    * ```js
@@ -1229,14 +1631,30 @@ type PathConfigAlias<Params> = {
    * }
    * ```
    */
-  parse?: ParseConfig<Params>;
+  parse?: ParseConfig<Params> | undefined;
+  /**
+   * Whether this path can resolve to multiple routes.
+   * Both routes should specify `shared: true` for this to work.
+   * By default, a path can only resolve to one route.
+   *
+   * This is useful when same screen used in multiple navigators,
+   * e.g. tabs with stacks containing profile screen in each stack.
+   *
+   * The path defined first will be the canonical path.
+   */
+  shared?: boolean | undefined;
 };
 
 export type PathConfig<Params> = FlatType<
-  Partial<PathConfigAlias<Params>> & {
+  Partial<Omit<PathConfigAlias<Params>, 'path'>> & {
+    /**
+     * Path string to match against.
+     * e.g. `/users/:id` will match `/users/1` and extract `id` param as `1`.
+     */
+    path?: string | undefined;
     /**
      * An object mapping the param name to a function which converts the param value to a string.
-     * By default, all params are converted to strings using `String(value)`.
+     * By default, arrays and null are preserved for query params, and other values are converted using `String(value)`.
      * Keys are constrained to valid param names when Params type is provided.
      *
      * @example
@@ -1246,25 +1664,32 @@ export type PathConfig<Params> = FlatType<
      * }
      * ```
      */
-    stringify?: StringifyConfig<Params>;
+    stringify?: StringifyConfig<Params> | undefined;
     /**
      * Additional path alias that will be matched to the same screen.
      */
-    alias?: (string | PathConfigAlias<Params>)[];
+    alias?: (string | PathConfigAlias<Params>)[] | undefined;
   } & (NonNullable<Params> extends NavigatorScreenParams<infer ParamList>
-      ? {
-          /**
-           * Path configuration for child screens.
-           */
-          screens?: PathConfigMap<ParamList>;
-          /**
-           * Name of the initial route to use for the navigator when the path matches.
-           */
-          initialRouteName?: keyof ParamList;
-        }
+      ? ParamListForNavigator<ParamList> extends infer ChildParamList extends {}
+        ? {
+            /**
+             * Path configuration for child screens.
+             */
+            screens?: PathConfigMap<ChildParamList> | undefined;
+            /**
+             * Name of the initial route to use for the navigator when the path matches.
+             */
+            initialRouteName?:
+              | Extract<keyof ChildParamList, string>
+              | undefined;
+          }
+        : {}
       : {})
 >;
 
 export type PathConfigMap<ParamList extends {}> = {
-  [RouteName in keyof ParamList]?: string | PathConfig<ParamList[RouteName]>;
+  [RouteName in keyof ParamList]?:
+    | string
+    | PathConfig<ParamList[RouteName]>
+    | undefined;
 };