@bedrock-core/navigation 0.6.0

package/README.md

@@ -0,0 +1,77 @@
+# @bedrock-core/navigation
+
+Stack-based navigation system for @bedrock-core/ui.
+
+## ⚠️ MVP Status
+
+This is a stack-only navigator. It does **not** support:
+- Tabs or other navigator types
+- Nested navigators
+- Deep linking
+- State persistence
+- Transition animations
+- Keep-alive inactive routes
+
+## Core API
+
+- **`NavigationContainer`** – Context provider that initializes and manages navigation state per player session. Wrap the entire navigator tree in this component as the root passed to `render()`.
+- **`createStackNavigator(config)`** – Factory that returns a `{ Navigator }` object. Register screens by passing a `{ screens: { [name]: component | { screen, initialParams } } }` config.
+- **`useNavigation<TRoutes>()`** – Hook returning a `NavigationHelpers<TRoutes>` object with: `navigate(name, params?)`, `push(name, params?)`, `goBack()`, `canGoBack()`, `reset(state)`, `setParams(name, params)`, `getState()`.
+- **`useRoute<TRoutes, K>()`** – Hook returning the current `RouteObject<TRoutes[K]>` with shape `{ key: string, name: K, params: TRoutes[K] }`. Must be called from within a screen component.
+
+## Usage
+
+```tsx
+import { NavigationContainer, createStackNavigator } from '@bedrock-core/navigation';
+import { useNavigation, useRoute } from '@bedrock-core/navigation';
+
+// Define screens
+function HomeScreen() {
+  const navigation = useNavigation();
+  return (
+    <Button onPress={() => navigation.navigate('Profile', { userId: 42 })}>
+      Go to Profile
+    </Button>
+  );
+}
+
+function ProfileScreen() {
+  const route = useRoute();
+  const { userId } = route.params;
+  const navigation = useNavigation();
+  return (
+    <>
+      <Text>Profile: {userId}</Text>
+      <Button onPress={() => navigation.goBack()}>Back</Button>
+    </>
+  );
+}
+
+// Create navigator
+const Stack = createStackNavigator({
+  screens: {
+    Home: HomeScreen,
+    Profile: {
+      screen: ProfileScreen,
+      initialParams: { userId: 0 }
+    }
+  }
+});
+
+// Render once per player
+render(
+  <NavigationContainer>
+    <Stack.Navigator initialRouteName="Home" />
+  </NavigationContainer>,
+  player
+);
+```
+
+## Key Architecture
+
+1. **Single root render per player** – Navigation state changes do NOT trigger new `render()` calls.
+2. **Action-driven updates** – All screen transitions happen through `navigate`, `push`, `goBack`, etc.
+3. **Reuses present loop** – Button callbacks naturally trigger screen updates via the runtime's present cycle.
+4. **No nested renders** – Screen components must never call `render()` directly.
+
+See [comprehensive documentation](../../docs/) for more details.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@bedrock-core/navigation",
+  "version": "0.6.0",
+  "description": "@bedrock-core/ui navigation system",
+  "keywords": [
+    "ui",
+    "navigation",
+    "minecraft",
+    "bedrock",
+    "typescript",
+    "framework"
+  ],
+  "license": "MIT",
+  "author": "DrAv0011",
+  "contributors": [
+    {
+      "name": "DrAv0011",
+      "email": "contact@drav.dev",
+      "url": "https://drav.dev"
+    }
+  ],
+  "repository": "github:bedrock-core/ui",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint ."
+  },
+  "packageManager": "yarn@4.9.3",
+  "devDependencies": {
+    "@bedrock-core/ui-runtime": "^0.6.0",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@bedrock-core/ui-runtime": "*"
+  }
+}

package/src/context.ts

@@ -0,0 +1,67 @@
+import { createContext, JSX } from '@bedrock-core/ui-runtime';
+import type { NavigationHelpers, NavigationState } from './types';
+import type { StackAction } from './reducer';
+
+export interface NavigationContextValue<
+  TRoutes extends Record<string, unknown> = Record<string, unknown>,
+> {
+  state: NavigationState<TRoutes>;
+  dispatch: (action: StackAction<TRoutes>) => void;
+  helpers: NavigationHelpers<TRoutes>;
+  routeNames: Extract<keyof TRoutes, string>[];
+  initialRouteName?: Extract<keyof TRoutes, string>;
+}
+
+/**
+ * Module-level context — unparameterized so it can be created once at module load.
+ * Types are recovered via casts inside the hooks and the navigators.
+ */
+export const NavigationContext = createContext<NavigationContextValue | undefined>(undefined);
+
+/**
+ * Provides a navigation context boundary. Wrap your app root with this.
+ * The actual state is owned by the Navigator inside; this just establishes
+ * the context slot with a stale placeholder so hooks can detect missing providers.
+ */
+export function NavigationContainer({
+  children,
+  initialState,
+}: {
+  children: JSX.Node;
+  initialState?: NavigationState;
+}): JSX.Element {
+  const placeholder: NavigationContextValue = {
+    state: initialState ?? {
+      type: 'stack',
+      key: 'stack-placeholder',
+      routeNames: [],
+      routes: [],
+      index: 0,
+      stale: true,
+    },
+    dispatch: (): void => {},
+    helpers: buildNoopHelpers(),
+    routeNames: [],
+    initialRouteName: undefined,
+  };
+
+  return {
+    type: 'context-provider',
+    props: { __context: NavigationContext, value: placeholder, children },
+  };
+}
+
+/** No-op helpers for the placeholder context before Navigator mounts. */
+function buildNoopHelpers(): NavigationHelpers<Record<string, unknown>> {
+  return {
+    navigate: (): void => {},
+    push: (): void => {},
+    goBack: (): void => {},
+    canGoBack: (): boolean => false,
+    reset: (): void => {},
+    setParams: (): void => {},
+    getState: (): NavigationState<Record<string, unknown>> => ({
+      type: 'stack', key: '', routeNames: [], routes: [], index: 0, stale: true,
+    }),
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,55 @@
+import { useContext } from '@bedrock-core/ui-runtime';
+import type { NavigationHelpers, RouteObject } from './types';
+import { NavigationContext } from './context';
+
+/**
+ * Hook to access the navigation object within a screen.
+ * Provides methods like navigate, goBack, push, etc.
+ *
+ * Always pass TRoutes to get full type safety: useNavigation<MyRoutes>()
+ */
+export function useNavigation<TRoutes extends Record<string, unknown>>(): NavigationHelpers<TRoutes> {
+  const ctx = useContext(NavigationContext);
+
+  if (!ctx) {
+    throw new Error(
+      'useNavigation must be called within a NavigationContainer. '
+      + 'Make sure your component is rendered inside a NavigationContainer.',
+    );
+  }
+
+  return ctx.helpers;
+}
+
+/**
+ * Hook to access the current route object within a screen.
+ * Provides route name and typed params.
+ *
+ * Usage: useRoute<MyRoutes, 'Profile'>()
+ */
+export function useRoute<
+  TRoutes extends Record<string, unknown>,
+  K extends keyof TRoutes = keyof TRoutes,
+>(): RouteObject<TRoutes[K]> {
+  const ctx = useContext(NavigationContext);
+
+  if (!ctx) {
+    throw new Error(
+      'useRoute must be called within a NavigationContainer. '
+      + 'Make sure your component is rendered inside a NavigationContainer.',
+    );
+  }
+
+  const focusedRoute = ctx.state.routes[ctx.state.index];
+
+  if (!focusedRoute) {
+    throw new Error('No focused route found in navigation state');
+  }
+
+  return {
+    key: focusedRoute.key,
+    name: focusedRoute.name,
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Route.params is unknown internally; caller asserts TRoutes[K] at the hook call site
+    params: focusedRoute.params as RouteObject<TRoutes[K]>['params'],
+  };
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @bedrock-core/navigation - Stack navigation system MVP
+ *
+ * A single-root-render navigation library for Minecraft Bedrock UI.
+ * Inspired by React Navigation but designed for the ui-runtime's presentation loop.
+ *
+ * Key principle: one render() call per player, all screen transitions via navigation actions.
+ */
+
+export { NavigationContainer } from './context';
+export { createStackNavigator } from './navigators/stack-navigator';
+export { useNavigation, useRoute } from './hooks';
+export { stackReducer, type StackAction, type ScreenDefaults } from './reducer';
+
+export type {
+  Route,
+  NavigationState,
+  StackNavigatorOptions,
+  NavigationHelpers,
+  RouteObject,
+  ScreenProps,
+  ScreenComponent,
+  ScreensMap,
+  RouteEntry,
+  ResetRouteEntry,
+} from './types';

package/src/navigators/resolve-screen.ts

@@ -0,0 +1,28 @@
+import type { ScreenComponent, ScreensMap } from '../types';
+
+/**
+ * Resolve a screen component from a screens map entry.
+ * Each entry is either a bare component or an object `{ screen, initialParams? }`.
+ * Returns `undefined` when the route name has no entry.
+ *
+ * Shared by both the stack and tab navigators.
+ */
+export function resolveScreenComponent<
+  TRoutes extends Record<string, unknown>,
+  K extends Extract<keyof TRoutes, string>,
+>(
+  screens: ScreensMap<TRoutes>,
+  name: K,
+): ScreenComponent<TRoutes, K> | undefined {
+  const entry = screens[name];
+
+  if (entry == null) {
+    return undefined;
+  }
+
+  if (typeof entry === 'function') {
+    return entry;
+  }
+
+  return entry.screen;
+}

package/src/navigators/stack-navigator.ts

@@ -0,0 +1,159 @@
+/* eslint-disable @typescript-eslint/no-unsafe-type-assertion --
+    Type assertions are required at the navigation context boundary: Object.keys casts,
+    unparameterized context recovery, discriminated-union action payloads, and JSX element
+    construction. Type safety is enforced at the NavigationHelpers / NavigationContextValue
+    interfaces rather than at each individual assertion site. */
+
+import { useContext, useState, JSX } from '@bedrock-core/ui-runtime';
+import type {
+  NavigationHelpers,
+  NavigationState,
+  StackNavigatorOptions,
+} from '../types';
+import { NavigationContext } from '../context';
+import type { NavigationContextValue } from '../context';
+import { stackReducer, type StackAction, type ScreenDefaults } from '../reducer';
+import { resolveScreenComponent } from './resolve-screen';
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type -- return type is a complex generic object; consumers use the inferred type via `typeof Stack`
+export function createStackNavigator<TRoutes extends Record<string, unknown>>(
+  options: StackNavigatorOptions<TRoutes>,
+) {
+  const routeNames = Object.keys(options.screens) as Extract<keyof TRoutes, string>[];
+  const { initialRouteName } = options;
+
+  // Extract initialParams from each screen entry into a screenDefaults map.
+  const screenDefaults: ScreenDefaults<TRoutes> = {};
+
+  for (const key of routeNames) {
+    const entry = options.screens[key];
+
+    //
+    if (entry != null && typeof entry === 'object' && 'initialParams' in entry) {
+      (screenDefaults as Record<string, unknown>)[key] = (entry as { initialParams?: unknown }).initialParams;
+    }
+  }
+
+  const reducerConfig = { routeNames, initialRouteName, screenDefaults };
+
+  function Navigator({
+    initialRouteName: propInitialRouteName,
+  }: {
+    initialRouteName?: Extract<keyof TRoutes, string>;
+  }): JSX.Element {
+    const effectiveInitialRoute
+      = propInitialRouteName ?? initialRouteName ?? routeNames[0];
+
+    const cfg = { ...reducerConfig, initialRouteName: effectiveInitialRoute };
+
+    const existingCtx = useContext(NavigationContext) as NavigationContextValue<TRoutes> | undefined;
+
+    const [navState, setNavState] = useState<NavigationState<TRoutes>>(() =>
+      existingCtx != null && !existingCtx.state.stale
+        ? existingCtx.state
+        : stackReducer<TRoutes>(undefined, { type: 'GO_BACK' }, cfg),
+    );
+
+    const dispatch = (action: StackAction<TRoutes>): void => {
+      setNavState(prev => stackReducer<TRoutes>(prev, action, cfg));
+    };
+
+    const helpers = buildHelpers<TRoutes>(navState, dispatch);
+
+    // ── Resolve active screen ─────────────────────────────────────────────────
+
+    const focusedRoute = navState.routes[navState.index];
+
+    const activeRouteName = (focusedRoute?.name ?? effectiveInitialRoute) as Extract<keyof TRoutes, string>;
+
+    const ActiveScreen = resolveScreenComponent(options.screens, activeRouteName);
+
+    if (ActiveScreen == null) {
+      return { type: 'fragment', props: { children: [] } };
+    }
+
+    const routeObject = {
+      key: focusedRoute?.key ?? activeRouteName,
+      name: activeRouteName,
+      // Stored params win over defaults; screen always sees at least its initialParams.
+      params: mergeRouteParams(
+        screenDefaults[activeRouteName],
+        focusedRoute?.params,
+      ),
+    };
+
+    const contextValue: NavigationContextValue<TRoutes> = {
+      state: navState,
+      dispatch,
+      helpers,
+      routeNames,
+      initialRouteName: effectiveInitialRoute,
+    };
+
+    return {
+      type: 'context-provider',
+      props: {
+        __context: NavigationContext,
+        value: contextValue,
+        children: {
+          type: ActiveScreen as (props: Record<string, unknown>) => JSX.Element,
+          props: { navigation: helpers, route: routeObject },
+        },
+      },
+    };
+  }
+
+  return {
+    Navigator,
+    routeNames,
+    initialRouteName: initialRouteName ?? routeNames[0],
+  };
+}
+
+function buildHelpers<TRoutes extends Record<string, unknown>>(
+  navState: NavigationState<TRoutes>,
+  dispatch: (action: StackAction<TRoutes>) => void,
+): NavigationHelpers<TRoutes> {
+  return {
+    navigate(...args): void {
+      const [name, params] = args as [Extract<keyof TRoutes, string>, unknown];
+
+      dispatch({ type: 'NAVIGATE', payload: { name, params } } as unknown as StackAction<TRoutes>);
+    },
+    push(...args): void {
+      const [name, params] = args as [Extract<keyof TRoutes, string>, unknown];
+
+      dispatch({ type: 'PUSH', payload: { name, params } } as unknown as StackAction<TRoutes>);
+    },
+    goBack(): void {
+      dispatch({ type: 'GO_BACK' });
+    },
+    canGoBack(): boolean {
+      return navState.index > 0;
+    },
+    reset(resetState): void {
+      dispatch({ type: 'RESET', payload: resetState } as unknown as StackAction<TRoutes>);
+    },
+    setParams(name, params): void {
+      dispatch({ type: 'SET_PARAMS', payload: { name, params } } as unknown as StackAction<TRoutes>);
+    },
+    getState(): NavigationState<TRoutes> {
+      return navState;
+    },
+  };
+}
+
+function mergeRouteParams(
+  defaults: Record<string, unknown> | undefined,
+  stored: unknown,
+): unknown {
+  if (defaults == null) {
+    return stored;
+  }
+
+  if (stored == null) {
+    return defaults;
+  }
+
+  return { ...defaults, ...(stored as Record<string, unknown>) };
+}

package/src/reducer.ts

@@ -0,0 +1,228 @@
+/**
+ * Pure stack navigation state reducer.
+ * Handles all navigation actions without side effects.
+ */
+
+import type { NavigationState, Route, RouteEntry, ResetRouteEntry } from './types';
+
+/**
+ * Per-screen default params applied when a route is first created and no params
+ * are supplied by the action. Action params always win on top of these defaults.
+ */
+export type ScreenDefaults<TRoutes extends Record<string, unknown>> = {
+  [K in Extract<keyof TRoutes, string>]?: Partial<
+    Exclude<TRoutes[K], undefined> & Record<string, unknown>
+  >;
+};
+
+/**
+ * SET_PARAMS payload — only valid for routes that have params (not `undefined` routes).
+ */
+type SetParamsEntry<TRoutes extends Record<string, unknown>> = {
+  [K in Extract<keyof TRoutes, string>]: [TRoutes[K]] extends [undefined]
+    ? never
+    : { name: K; params: Partial<Exclude<TRoutes[K], undefined> & Record<string, unknown>> };
+}[Extract<keyof TRoutes, string>];
+
+/**
+ * Navigation actions, fully typed from the routes map.
+ */
+export type StackAction<TRoutes extends Record<string, unknown> = Record<string, unknown>>
+  = | { type: 'NAVIGATE'; payload: RouteEntry<TRoutes> }
+    | { type: 'PUSH'; payload: RouteEntry<TRoutes> }
+    | { type: 'GO_BACK' }
+    | { type: 'RESET'; payload: { routes: ResetRouteEntry<TRoutes>[]; index: number } }
+    | { type: 'SET_PARAMS'; payload: SetParamsEntry<TRoutes> };
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function generateRouteKey(name: string): string {
+  return `${name}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Merge action params on top of screen defaults. Both may be absent.
+ * `incoming` is typed as unknown because Route.params is loosely typed internally;
+ * type safety is enforced at the NavigationHelpers dispatch boundary.
+ */
+function mergeParams(
+  defaults: Record<string, unknown> | undefined,
+  incoming: unknown,
+): unknown {
+  if (defaults == null && incoming == null) {
+    return undefined;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- params are always plain objects or undefined at runtime; Route.params is typed as unknown for internal flexibility
+  return { ...defaults, ...(incoming as Record<string, unknown> | undefined) };
+}
+
+// ─── Reducer ──────────────────────────────────────────────────────────────────
+
+/**
+ * Reduce the navigation state based on an action.
+ * Pure function with no side effects.
+ */
+export function stackReducer<TRoutes extends Record<string, unknown>>(
+  state: NavigationState<TRoutes> | undefined,
+  action: StackAction<TRoutes>,
+  config: {
+    routeNames: Extract<keyof TRoutes, string>[];
+    initialRouteName?: Extract<keyof TRoutes, string>;
+    screenDefaults?: ScreenDefaults<TRoutes>;
+  },
+): NavigationState<TRoutes> {
+  const { routeNames, initialRouteName, screenDefaults } = config;
+
+  // ── Initialization ──────────────────────────────────────────────────────────
+  if (state == null || state.stale) {
+    const firstName = initialRouteName ?? routeNames[0];
+
+    if (firstName == null) {
+      throw new Error('stackReducer: routeNames is empty — at least one screen is required.');
+    }
+
+    const defaults = screenDefaults?.[firstName] as Record<string, unknown> | undefined;
+
+    return {
+      type: 'stack',
+      key: `stack-${Math.random().toString(36).slice(2, 11)}`,
+      routeNames,
+      routes: [{ key: generateRouteKey(firstName), name: firstName, params: defaults }],
+      index: 0,
+      stale: false,
+    };
+  }
+
+  switch (action.type) {
+    // ── NAVIGATE ──────────────────────────────────────────────────────────────
+    // Navigate to a route. If it already exists in the stack, pop back to it
+    // (discard everything after it). If it is new, push it onto the stack.
+    case 'NAVIGATE': {
+      const { name, params } = action.payload;
+
+      if (!routeNames.includes(name)) {
+        return state;
+      }
+
+      const defaults = screenDefaults?.[name] as Record<string, unknown> | undefined;
+      const mergedParams = mergeParams(defaults, params);
+
+      const existingIndex = state.routes.findIndex(r => r.name === name);
+
+      if (existingIndex !== -1) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Route.params is typed as unknown internally; safe to spread as Record at runtime
+        const existingParams = state.routes[existingIndex].params as Record<string, unknown> | undefined;
+        const updatedRoute: Route = {
+          ...state.routes[existingIndex],
+          params: mergeParams(existingParams, mergedParams),
+        };
+
+        return {
+          ...state,
+          // Slice to existingIndex + 1 to discard all forward history (pop-to behavior).
+          routes: [...state.routes.slice(0, existingIndex), updatedRoute],
+          index: existingIndex,
+        };
+      }
+
+      return {
+        ...state,
+        routes: [...state.routes, { key: generateRouteKey(name), name, params: mergedParams }],
+        index: state.routes.length,
+      };
+    }
+
+    // ── PUSH ─────────────────────────────────────────────────────────────────
+    // Always push a new entry, even if the route is already in the stack.
+    case 'PUSH': {
+      const { name, params } = action.payload;
+
+      if (!routeNames.includes(name)) {
+        return state;
+      }
+
+      const defaults = screenDefaults?.[name] as Record<string, unknown> | undefined;
+
+      return {
+        ...state,
+        routes: [
+          ...state.routes,
+          { key: generateRouteKey(name), name, params: mergeParams(defaults, params) },
+        ],
+        index: state.routes.length,
+      };
+    }
+
+    // ── GO_BACK ───────────────────────────────────────────────────────────────
+    case 'GO_BACK': {
+      if (state.index <= 0) {
+        return state;
+      }
+
+      return {
+        ...state,
+        routes: state.routes.slice(0, state.index),
+        index: state.index - 1,
+      };
+    }
+
+    // ── RESET ─────────────────────────────────────────────────────────────────
+    case 'RESET': {
+      const { routes: incoming, index: requestedIndex } = action.payload;
+
+      const built = incoming
+        .filter(r => routeNames.includes(r.name))
+        .map((r) => {
+          const defaults = screenDefaults?.[r.name] as Record<string, unknown> | undefined;
+
+          return {
+            key: generateRouteKey(r.name),
+            name: r.name,
+            params: mergeParams(defaults, r.params),
+          };
+        });
+
+      if (built.length === 0) {
+        return state;
+      }
+
+      return {
+        ...state,
+        routes: built,
+        index: Math.max(0, Math.min(requestedIndex, built.length - 1)),
+      };
+    }
+
+    // ── SET_PARAMS ────────────────────────────────────────────────────────────
+    case 'SET_PARAMS': {
+      const { name, params: incoming } = action.payload;
+
+      const targetIndex = state.routes.findIndex(r => r.name === name);
+
+      if (targetIndex === -1) {
+        return state;
+      }
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Route.params is typed as unknown internally; safe to spread as Record at runtime
+      const existing = state.routes[targetIndex].params as Record<string, unknown> | undefined;
+      const updatedRoute: Route = {
+        ...state.routes[targetIndex],
+
+        params: { ...existing, ...(incoming as Record<string, unknown>) },
+      };
+
+      return {
+        ...state,
+        routes: [
+          ...state.routes.slice(0, targetIndex),
+          updatedRoute,
+          ...state.routes.slice(targetIndex + 1),
+        ],
+      };
+    }
+
+    default:
+      return state;
+  }
+}

package/src/types.ts

@@ -0,0 +1,456 @@
+import type { JSX } from '@bedrock-core/ui-runtime';
+
+/**
+ * Rest-argument tuple for `navigate` / `push` calls.
+ *
+ * Driven by the **route-level** param type — four cases:
+ * - `undefined`                   → params argument forbidden:  `[name]`
+ * - `T | undefined`               → params argument optional:   `[name]` or `[name, params]`
+ * - `T`                           → params argument required:   `[name, params]`
+ * - `{ req: A; opt?: B }`         → params argument required, but individual properties
+ *                                    inside the object can still be optional as normal
+ *
+ * Uses non-distributive `[T] extends [undefined]` so a union like `T | undefined`
+ * falls through to the optional branch instead of splitting across both branches.
+ * `Exclude<TParams, undefined>` strips only the route-level `undefined` from the union —
+ * it never touches optional properties inside the params object.
+ */
+type NavigateArgs<K extends string, TParams> = [TParams] extends [undefined]
+  ? [name: K]
+  : [undefined] extends [TParams]
+      ? [name: K] | [name: K, params: Exclude<TParams, undefined>]
+      : [name: K, params: TParams];
+
+/**
+ * Navigation API injected into every screen and exposed via `useNavigation`.
+ *
+ * The generic `TRoutes` parameter constrains every call so route names and
+ * their param shapes are validated at compile time.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = {
+ *   Home:     undefined;
+ *   Profile:  { userId: string };
+ *   Settings: { tab?: string };
+ * };
+ *
+ * function MyComponent({ navigation }: ScreenProps<AppRoutes, 'Home'>) {
+ *   // undefined route — name only, params forbidden:
+ *   navigation.navigate('Home');
+ *
+ *   // Required params — TypeScript errors if userId is missing:
+ *   navigation.navigate('Profile', { userId: '42' });
+ *
+ *   // Optional params — both forms are valid:
+ *   navigation.navigate('Feed');
+ *   navigation.navigate('Feed', { sort: 'top' });
+ *
+ *   // Push always adds a new stack entry:
+ *   navigation.push('Feed', { sort: 'latest' });
+ *
+ *   // Go back one screen:
+ *   navigation.goBack();
+ *
+ *   // Guard against going back when there is nothing to go back to:
+ *   if (navigation.canGoBack()) navigation.goBack();
+ *
+ *   // Replace the entire stack (e.g. after logout):
+ *   navigation.reset({ routes: [{ name: 'Home' }], index: 0 });
+ *
+ *   // Merge new values into an already-mounted screen's params:
+ *   navigation.setParams('Settings', { tab: 'account' });
+ *
+ *   // Read the current stack state:
+ *   const state = navigation.getState();
+ * }
+ * ```
+ */
+export interface NavigationHelpers<TRoutes extends Record<string, unknown>> {
+  /**
+   * Navigate to a route by name.
+   * If the route is already in the stack, navigates back to it instead of
+   * pushing a new copy.
+   *
+   * Param rules mirror the route definition:
+   * - `undefined` route  → only the name, no params argument
+   * - `T` route          → name + required params object
+   * - `T | undefined`    → name alone, or name + optional params object
+   *
+   * @example
+   * ```ts
+   * navigation.navigate('Home');                                        // undefined route
+   * navigation.navigate('Profile', { userId: '42' });                  // required params
+   * navigation.navigate('User', { userId: 1 });                        // mixed — req only
+   * navigation.navigate('User', { userId: 1, username: 'Alice' });     // mixed — req + opt
+   * navigation.navigate('Feed');                                        // optional — no params
+   * navigation.navigate('Feed', { sort: 'latest' });                   // optional — with params
+   * ```
+   */
+  navigate<K extends Extract<keyof TRoutes, string>>(
+    ...args: NavigateArgs<K, TRoutes[K]>
+  ): void;
+
+  /**
+   * Always push a new entry onto the stack, even if that route is already present.
+   * Useful when you want multiple instances of the same screen (e.g. nested profiles).
+   *
+   * @example
+   * ```ts
+   * navigation.push('Profile', { userId: '99' });
+   * ```
+   */
+  push<K extends Extract<keyof TRoutes, string>>(
+    ...args: NavigateArgs<K, TRoutes[K]>
+  ): void;
+
+  /**
+   * Pop the current screen and return to the previous one.
+   * Has no effect when the stack only has one entry — check `canGoBack` first.
+   *
+   * @example
+   * ```ts
+   * navigation.goBack();
+   * ```
+   */
+  goBack(): void;
+
+  /**
+   * Returns `true` when there is at least one screen behind the current one.
+   *
+   * @example
+   * ```ts
+   * if (navigation.canGoBack()) {
+   *   navigation.goBack();
+   * }
+   * ```
+   */
+  canGoBack(): boolean;
+
+  /**
+   * Replace the entire navigation stack with a new one.
+   * `index` must point to the focused route in the `routes` array.
+   * Params inside `routes` are partial — omit any you want to keep at defaults.
+   *
+   * @example
+   * ```ts
+   * // After logout, reset to the Home screen:
+   * navigation.reset({ routes: [{ name: 'Home' }], index: 0 });
+   *
+   * // Restore a two-screen stack with Profile focused:
+   * navigation.reset({
+   *   routes: [{ name: 'Home' }, { name: 'Profile', params: { userId: '42' } }],
+   *   index: 1,
+   * });
+   * ```
+   */
+  reset(state: { routes: ResetRouteEntry<TRoutes>[]; index: number }): void;
+
+  /**
+   * Merge partial params into a screen that is already in the stack.
+   * Only valid for routes that have a params type — TypeScript will error for
+   * parameterless routes (`TRoutes[K] extends undefined`).
+   *
+   * @example
+   * ```ts
+   * // Switch the active tab on the Settings screen without re-mounting it:
+   * navigation.setParams('Settings', { tab: 'privacy' });
+   * ```
+   */
+  setParams<K extends Extract<keyof TRoutes, string>>(
+    name: K,
+    params: [TRoutes[K]] extends [undefined] ? never : Partial<Exclude<TRoutes[K], undefined> & Record<string, unknown>>,
+  ): void;
+
+  /**
+   * Returns a snapshot of the current navigation state (stack, index, etc.).
+   *
+   * @example
+   * ```ts
+   * const { routes, index } = navigation.getState();
+   * const currentRoute = routes[index];
+   * ```
+   */
+  getState(): NavigationState<TRoutes>;
+}
+
+/**
+ * Discriminated union of every valid `{ name, params }` pair for `TRoutes`.
+ * Used internally for NAVIGATE and PUSH action payloads to guarantee that the
+ * correct params type is paired with each route name.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = {
+ *   Home:    undefined;
+ *   Profile: { userId: string };
+ *   User:    { userId: number; username?: string };
+ *   Feed:    { sort: 'latest' | 'top' } | undefined;
+ * };
+ *
+ * // Resolves to:
+ * // | { name: 'Home';    params?: undefined }
+ * // | { name: 'Profile'; params: { userId: string } }
+ * // | { name: 'User';    params: { userId: number; username?: string } }
+ * // | { name: 'Feed';    params?: { sort: 'latest' | 'top' } }
+ * type Entry = RouteEntry<AppRoutes>;
+ *
+ * const a: Entry = { name: 'Home' };
+ * const b: Entry = { name: 'Profile', params: { userId: '1' } };
+ * const c: Entry = { name: 'Profile' };                              // TS error — missing params
+ * const d: Entry = { name: 'User', params: { userId: 1 } };         // ok — username optional
+ * const e: Entry = { name: 'User', params: { userId: 1, username: 'Alice' } }; // also ok
+ * const f: Entry = { name: 'Feed' };                                // ok — params optional
+ * const g: Entry = { name: 'Feed', params: { sort: 'top' } };      // also ok
+ * ```
+ */
+export type RouteEntry<TRoutes extends Record<string, unknown>> = {
+  [K in Extract<keyof TRoutes, string>]: [TRoutes[K]] extends [undefined]
+    ? { name: K; params?: undefined }
+    : [undefined] extends [TRoutes[K]]
+        ? { name: K; params?: Exclude<TRoutes[K], undefined> }
+        : { name: K; params: TRoutes[K] };
+}[Extract<keyof TRoutes, string>];
+
+/**
+ * Like `RouteEntry` but params are always optional partial — used for RESET
+ * payloads where you may want to omit params and fall back to screen defaults.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = { Home: undefined; Profile: { userId: string } };
+ *
+ * // Resolves to:
+ * // | { name: 'Home'; params?: undefined }
+ * // | { name: 'Profile'; params?: Partial<{ userId: string }> }
+ * type Entry = ResetRouteEntry<AppRoutes>;
+ *
+ * const routes: Entry[] = [
+ *   { name: 'Home' },
+ *   { name: 'Profile' },          // params omitted — screen uses its initialParams
+ *   { name: 'Profile', params: { userId: '5' } }, // or supply them explicitly
+ * ];
+ * ```
+ */
+export type ResetRouteEntry<TRoutes extends Record<string, unknown>> = {
+  [K in Extract<keyof TRoutes, string>]: TRoutes[K] extends undefined
+    ? { name: K; params?: undefined }
+    : { name: K; params?: Partial<TRoutes[K] & Record<string, unknown>> };
+}[Extract<keyof TRoutes, string>];
+
+/**
+ * Props injected into every screen component: `navigation` and `route`, both
+ * typed to the specific route key `K` within `TRoutes`.
+ *
+ * **Recommended pattern** — create a single app-level alias so you only ever
+ * pass one generic per screen:
+ *
+ * ```ts
+ * // routes.ts — define once
+ * export type AppRoutes = {
+ *   Home:     undefined;
+ *   Profile:  { userId: string };
+ *   Settings: { tab?: string };
+ * };
+ * export type AppScreenProps<K extends keyof AppRoutes> = ScreenProps<AppRoutes, K>;
+ * ```
+ *
+ * ```ts
+ * // ProfileScreen.tsx — required params
+ * import type { AppScreenProps } from './routes';
+ *
+ * function ProfileScreen({ route, navigation }: AppScreenProps<'Profile'>) {
+ *   const { userId } = route.params;              // string — fully typed
+ *   navigation.navigate('Feed');                  // optional route, no params
+ *   navigation.navigate('Feed', { sort: 'top' }); // optional route, with params
+ * }
+ *
+ * // FeedScreen.tsx — optional params (T | undefined)
+ * function FeedScreen({ route, navigation }: AppScreenProps<'Feed'>) {
+ *   const sort = route.params?.sort ?? 'latest';  // params may be undefined
+ *   navigation.goBack();
+ * }
+ * ```
+ *
+ * You can also use `ScreenProps` directly without an alias:
+ *
+ * ```ts
+ * function HomeScreen({ navigation }: ScreenProps<AppRoutes, 'Home'>) {
+ *   navigation.navigate('Profile', { userId: '42' });
+ * }
+ * ```
+ */
+export type ScreenProps<
+  TRoutes extends Record<string, unknown>,
+  K extends keyof TRoutes,
+> = {
+  navigation: NavigationHelpers<TRoutes>;
+  route: RouteObject<TRoutes[K]>;
+};
+
+/**
+ * A screen component typed to a specific route key.
+ * The component receives `navigation` and `route` props whose types are derived
+ * from the `TRoutes` map and the route key `K`.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = { Profile: { userId: string } };
+ *
+ * const ProfileScreen: ScreenComponent<AppRoutes, 'Profile'> = ({ navigation, route }) => {
+ *   return <Text onPress={() => navigation.goBack()}>{route.params.userId}</Text>;
+ * };
+ * ```
+ */
+export type ScreenComponent<
+  TRoutes extends Record<string, unknown>,
+  K extends Extract<keyof TRoutes, string>,
+> = (props: ScreenProps<TRoutes, K>) => JSX.Element;
+
+/**
+ * The screens map passed to `createStackNavigator`.
+ * Every key in `TRoutes` must be present. Each value is either a bare screen
+ * component or an object with `screen` + optional `initialParams`.
+ *
+ * `initialParams` is only valid for routes that have a params type; it is
+ * forbidden (`never`) for parameterless routes.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = {
+ *   Home:     undefined;
+ *   Profile:  { userId: string };
+ *   Settings: { tab?: string };
+ * };
+ *
+ * const screens: ScreensMap<AppRoutes> = {
+ *   // Bare component — no initial params:
+ *   Home: HomeScreen,
+ *
+ *   // Object form — also no initial params here:
+ *   Profile: { screen: ProfileScreen },
+ *
+ *   // With initial params that apply when the screen has none:
+ *   Settings: { screen: SettingsScreen, initialParams: { tab: 'general' } },
+ * };
+ * ```
+ */
+export type ScreensMap<TRoutes extends Record<string, unknown>> = {
+  [K in Extract<keyof TRoutes, string>]:
+    | ScreenComponent<TRoutes, K>
+    | {
+      screen: ScreenComponent<TRoutes, K>;
+      initialParams?: [TRoutes[K]] extends [undefined]
+        ? never
+        : Partial<Exclude<TRoutes[K], undefined> & Record<string, unknown>>;
+    };
+};
+
+/**
+ * A single route entry in the navigation stack.
+ * Loosely typed internally — type safety is enforced at action dispatch boundaries.
+ *
+ * @example
+ * ```ts
+ * const route: Route = {
+ *   key: 'Profile-abc123',
+ *   name: 'Profile',
+ *   params: { userId: '42' },
+ * };
+ * ```
+ */
+export interface Route {
+  /** Unique key for this route instance (generated on push). */
+  key: string;
+  /** Name of the route, matching a key in `TRoutes`. */
+  name: string;
+  /** Route parameters. Typed loosely here; narrowed at screen boundaries. */
+  params?: unknown;
+}
+
+/**
+ * Snapshot of a stack navigator's state.
+ *
+ * @example
+ * ```ts
+ * const state: NavigationState<AppRoutes> = {
+ *   type: 'stack',
+ *   key: 'stack-1',
+ *   routeNames: ['Home', 'Profile', 'Settings'],
+ *   routes: [
+ *     { key: 'Home-abc', name: 'Home' },
+ *     { key: 'Profile-xyz', name: 'Profile', params: { userId: '42' } },
+ *   ],
+ *   index: 1,   // Profile is currently focused
+ *   stale: false,
+ * };
+ * ```
+ */
+export interface NavigationState<TRoutes extends Record<string, unknown> = Record<string, unknown>> {
+  /** Always `'stack'` for stack navigators. */
+  type: 'stack';
+  /** Unique key for this navigator instance. */
+  key: string;
+  /** Ordered list of all possible route names registered in this navigator. */
+  routeNames: Extract<keyof TRoutes, string>[];
+  /** Current route stack — the last entry is the top of the stack. */
+  routes: Route[];
+  /** Zero-based index of the currently focused route in `routes`. */
+  index: number;
+  /** `true` when the state has not yet been sanitized/rehydrated. */
+  stale: boolean;
+}
+
+/**
+ * Options accepted by `createStackNavigator`.
+ *
+ * @example
+ * ```ts
+ * type AppRoutes = {
+ *   Home:    undefined;
+ *   Profile: { userId: string };
+ * };
+ *
+ * const Navigator = createStackNavigator<AppRoutes>({
+ *   initialRouteName: 'Home',   // shown first; defaults to the first key if omitted
+ *   screens: {
+ *     Home:    HomeScreen,
+ *     Profile: { screen: ProfileScreen, initialParams: { userId: 'guest' } },
+ *   },
+ * });
+ * ```
+ */
+export interface StackNavigatorOptions<TRoutes extends Record<string, unknown>> {
+  /** The screens map — every route in `TRoutes` must be represented. */
+  screens: ScreensMap<TRoutes>;
+  /**
+   * Name of the route to show when the navigator first mounts.
+   * Defaults to the first key declared in `screens` if omitted.
+   */
+  initialRouteName?: Extract<keyof TRoutes, string>;
+}
+
+/**
+ * The route object passed to a screen component via `useRoute`.
+ * `TParams` is `undefined` for parameterless routes, in which case `params`
+ * is typed as `undefined` rather than an empty object.
+ *
+ * @example
+ * ```ts
+ * // In a parameterless screen:
+ * const route = useRoute<RouteObject<undefined>>();
+ * route.params; // undefined
+ *
+ * // In a screen with params:
+ * const route = useRoute<RouteObject<{ userId: string }>>();
+ * route.params.userId; // string
+ * ```
+ */
+export interface RouteObject<TParams = undefined> {
+  /** Unique key for this route instance. */
+  key: string;
+  /** Route name matching the key in the screens map. */
+  name: string;
+  /** Typed params — `undefined` for parameterless routes. */
+  params: TParams extends undefined ? undefined : TParams;
+}