@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.121

package/src/segment-system.tsx

@@ -1,53 +1,62 @@
+import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
-import { isLoaderDataResult } from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
+import { decodeLoaderResults } from "./decode-loader-results.js";
 import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
   LoaderBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
+import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
 
-/**
- * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
- */
-function resolveLoaderData(
-  resolvedData: any[],
-  loaderIds: string[],
-): { loaderData: Record<string, any>; errorFallback: ReactNode } {
-  const loaderData: Record<string, any> = {};
-  let errorFallback: ReactNode = null;
-
-  for (let i = 0; i < loaderIds.length; i++) {
-    const id = loaderIds[i];
-    const result = resolvedData[i];
-
-    if (!isLoaderDataResult(result)) {
-      // Legacy format - direct data
-      loaderData[id] = result;
+// ViewTransition is only available in React experimental.
+// Access via namespace import to avoid compile-time errors on stable React.
+const ReactViewTransition: any =
+  "ViewTransition" in React ? (React as any).ViewTransition : null;
+
+function restoreParallelLoaderMarkers(
+  segments: ResolvedSegment[],
+): ResolvedSegment[] {
+  const parallelLoadingByNamespace = new Map<string, ReactNode>();
+  let nextSegments: ResolvedSegment[] | null = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+
+    if (segment.type === "parallel") {
+      if (
+        segment.namespace &&
+        segment.loading !== undefined &&
+        segment.loading !== null &&
+        segment.loading !== false
+      ) {
+        parallelLoadingByNamespace.set(segment.namespace, segment.loading);
+      }
       continue;
     }
 
-    if (result.ok) {
-      loaderData[id] = result.data;
+    if (segment.type !== "loader" || segment.parallelLoading !== undefined) {
       continue;
     }
 
-    // Error case
-    if (result.fallback) {
-      errorFallback = result.fallback;
-    } else {
-      throw new Error(result.error.message);
+    const parallelLoading = segment.namespace
+      ? parallelLoadingByNamespace.get(segment.namespace)
+      : undefined;
+    if (parallelLoading === undefined) {
+      continue;
     }
+
+    if (!nextSegments) {
+      nextSegments = segments.slice();
+    }
+    nextSegments[i] = { ...segment, parallelLoading };
   }
 
-  return { loaderData, errorFallback };
+  return nextSegments ?? segments;
 }
 
 /**
@@ -86,6 +95,50 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+function createViewTransitionBoundary(
+  transition: NonNullable<ResolvedSegment["transition"]>,
+  children: ReactNode,
+): ReactNode {
+  // `viewTransition` is a router-specific flag (boundary opt-out), not a React
+  // <ViewTransition> prop — strip it so it never reaches React.
+  const { viewTransition: _viewTransition, ...vtProps } = transition;
+  return createElement(ReactViewTransition, {
+    ...vtProps,
+    children,
+  });
+}
+
+function wrapDefaultOutletContent(
+  content: ReactNode,
+  transition: NonNullable<ResolvedSegment["transition"]>,
+): ReactNode {
+  if (!React.isValidElement(content)) {
+    return createViewTransitionBoundary(transition, content);
+  }
+
+  const props = content.props as any;
+
+  if (content.type === MountContextProvider) {
+    return React.cloneElement(content, {
+      children: wrapDefaultOutletContent(props.children, transition),
+    } as any);
+  }
+
+  if (content.type === OutletProvider && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      content: wrapDefaultOutletContent(props.content, transition),
+    } as any);
+  }
+
+  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      outletContent: wrapDefaultOutletContent(props.outletContent, transition),
+    } as any);
+  }
+
+  return createViewTransitionBoundary(transition, content);
+}
+
 /**
  * Render segments into a React tree with proper layout nesting
  *
@@ -137,6 +190,10 @@ export async function renderSegments(
   } = options || {};
 
   const temporalLazyRefs: Promise<any>[] = [];
+  const normalizedSegments = restoreParallelLoaderMarkers(segments);
+  const normalizedInterceptSegments = interceptSegments
+    ? restoreParallelLoaderMarkers(interceptSegments)
+    : undefined;
 
   /**
    * Registers promises from lazy/async components for awaiting.
@@ -161,7 +218,26 @@ export async function renderSegments(
     );
   }
   // Separate segments by type, passing intercept segments for explicit injection
-  const tree = segmentTreeWalk(segments, interceptSegments);
+  const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+
+  // A route is "in a transition scope" when its own segment OR any layout in
+  // its matched chain declares transition(). Both transition() forms land here:
+  // the per-route item form sets transition on the route entry, and the block
+  // wrapper form sets it on a transparent ancestor layout (dsl-helpers.ts). When
+  // in scope, the route and its route-owned layouts use param-agnostic keys so a
+  // same-route navigation reconciles (holds content) instead of remounting. The
+  // value is a static property of the route's position in the tree, so it is the
+  // same on every render of that route (SSR, navigation, action) — the keys
+  // never drift. Cross-route navigation still remounts: different routes have
+  // different segment ids regardless of transition scope.
+  const inTransitionScope = normalizedSegments.some(
+    (s) =>
+      s.transition != null &&
+      (s.type === "layout" ||
+        s.type === "route" ||
+        s.type === "error" ||
+        s.type === "notFound"),
+  );
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -174,17 +250,31 @@ export async function renderSegments(
     );
     const { component, id, params, loading } = node.segment;
 
-    // Only include params in key for segments that belong to the route
-    // - Routes: always include params (they render param-specific content)
-    // - Error/notFound segments: always include params (they replace failed route content)
-    // - Route's layouts (orphans): include params (children of parameterized route)
-    // - Parent chain layouts: exclude params (shared across routes, param-agnostic)
-    // This prevents unnecessary unmounting when params change
+    // Param-agnostic keys are opt-in via the transition() DSL (see
+    // inTransitionScope above). A route (and its route-owned layouts) inside a
+    // transition scope drops the param from its key, so navigating between two
+    // param values of the SAME route (e.g. /product/1 -> /product/2) reconciles
+    // the route subtree instead of remounting it. Combined with the
+    // startTransition wrap that shouldStartViewTransition already applies to
+    // transition routes (browser/partial-update.ts), the previous content stays
+    // on screen while the new loaders resolve (stale-while-revalidate) instead
+    // of flashing the loading skeleton. This works on stable React; experimental
+    // React adds the animated <ViewTransition> cross-fade on top.
+    //
+    // Outside a transition scope the key stays param-bearing and the route
+    // remounts on param change (the default: a fresh skeleton and fresh
+    // component state).
+    //
+    // error/notFound always keep param-bearing keys: createErrorSegment reuses
+    // the boundary layout's shortCode as the error segment id (router/
+    // error-handling.ts), so a param-agnostic error key could collide with that
+    // layout's key within the same render.
     const includeParams =
-      node.segment.type === "route" ||
       node.segment.type === "error" ||
       node.segment.type === "notFound" ||
-      (node.segment.type === "layout" && node.segment.belongsToRoute);
+      ((node.segment.type === "route" ||
+        (node.segment.type === "layout" && node.segment.belongsToRoute)) &&
+        !inTransitionScope);
 
     const paramStr =
       includeParams && params && Object.keys(params).length > 0
@@ -210,39 +300,65 @@ export async function renderSegments(
     }
 
     let nodeContent: ReactNode =
-      loading !== null && loading
+      loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
         : registerLazyRef(resolvedComponent);
-    // Common props for OutletProvider
-    const outletContent: ReactNode =
+
+    // Wrap with <ViewTransition> if transition config exists (React experimental only).
+    // An empty config ({}) creates a bare <ViewTransition> boundary that participates
+    // in transitions without adding custom animation classes. Named element-level
+    // <ViewTransition> components inside (with name/share props) morph independently
+    // from the parent's default cross-fade.
+    //
+    // For layouts, wrap the outlet content (what `<Outlet />` renders) rather
+    // than the layout component itself. Parallel slots like `<ParallelOutlet
+    // name="@modal" />` read from a separate context channel and end up as
+    // siblings of the VT in the rendered tree, so modal mounts don't trigger a
+    // subtree update on the layout-level VT — which would otherwise make
+    // React's commit walker fire `document.startViewTransition` and apply
+    // view-transition-names to the underlying main subtree (cover/title/etc.).
+    //
+    // `transition.viewTransition === false` opts out of the router-owned
+    // boundary only. Driving (the startTransition wrap in browser/partial-update.ts
+    // and the param-agnostic key/hold below) keys off transition *presence*, not
+    // this flag, so a boundary-less transition still holds content and lets
+    // consumer-placed <ViewTransition> elements animate. The global
+    // createRouter({ viewTransition }) default is resolved into this field
+    // during segment resolution (only `false` is stamped; unset/"auto" is left
+    // as-is and means "wrap"), so this gate needs no router-option threading.
+    let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
+    const transition = node.segment.transition;
+
+    if (
+      ReactViewTransition &&
+      transition &&
+      transition.viewTransition !== false
+    ) {
+      if (node.segment.type === "layout") {
+        outletContent = wrapDefaultOutletContent(outletContent, transition);
+      } else {
+        nodeContent = createViewTransitionBoundary(transition, nodeContent);
+      }
+    }
+
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
-        ? Promise.all(
-            loaderEntries.map((loader) =>
-              loader.loaderData instanceof Promise
-                ? loader.loaderData
-                : Promise.resolve(loader.loaderData),
-            ),
-          )
-        : Promise.resolve([]);
 
     // Use LoaderBoundary when loading is defined to maintain consistent tree structure
     // This ensures cached segments (which may not have loader segments) have the same
     // tree structure as fresh segments, preventing React remounts
     // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
     if (loading !== undefined && loading !== null) {
+      // Aggregate built here only — the loaderless and no-loading branches don't
+      // read it (the latter builds its own per-parallel promises).
+      const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise:
@@ -265,13 +381,68 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton - await loaders and render directly
-      const resolvedData = await loaderDataPromise;
-      const { loaderData, errorFallback } = resolveLoaderData(
+      // Has loaders but no loading skeleton.
+      // Split: parallel-owned loaders stream (their parallel has loading()),
+      // layout-owned loaders are awaited (they gate the layout content).
+      const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
+      const parallelOwnedLoaders = loaderEntries.filter(
+        (l) => !!l.parallelLoading,
+      );
+
+      // Await only layout-owned loaders
+      const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      const layoutLoaderDataPromise =
+        layoutLoaders.length > 0
+          ? Promise.all(
+              layoutLoaders.map((l) =>
+                l.loaderData instanceof Promise
+                  ? l.loaderData
+                  : Promise.resolve(l.loaderData),
+              ),
+            )
+          : Promise.resolve([]);
+      const resolvedData = await layoutLoaderDataPromise;
+      const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
-        loaderIds,
+        layoutLoaderIds,
       );
 
+      // Parallel-owned loaders: attach to their owning parallel segment
+      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
+      if (parallelOwnedLoaders.length > 0) {
+        const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
+
+        for (const loader of parallelOwnedLoaders) {
+          if (!loader.namespace) {
+            continue;
+          }
+          const existing = loadersByParallelNamespace.get(loader.namespace);
+          if (existing) {
+            existing.push(loader);
+          } else {
+            loadersByParallelNamespace.set(loader.namespace, [loader]);
+          }
+        }
+
+        for (const p of node.parallel) {
+          if (!p.loading || !p.namespace) {
+            continue;
+          }
+
+          const ownedLoaders = loadersByParallelNamespace.get(p.namespace);
+          if (!ownedLoaders || ownedLoaders.length === 0) {
+            continue;
+          }
+
+          p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const aggregated = getMemoizedLoaderPromise(ownedLoaders);
+          p.loaderDataPromise =
+            (forceAwait || isAction) && aggregated instanceof Promise
+              ? await aggregated
+              : aggregated;
+        }
+      }
+
       content = createElement(OutletProvider, {
         key,
         content: outletContent,
@@ -407,20 +578,13 @@ function* segmentTreeWalk(
     }
   }
 
-  // Sort segments by ID to ensure consistent root-to-leaf ordering
-  // regardless of the order they arrive in the input array (which can differ
-  // between document requests and actions)
-  // Shorter IDs come first (closer to root), same length sorted lexicographically
-  nonParallels.sort((a, b) => {
-    if (a.id.length !== b.id.length) {
-      return a.id.length - b.id.length;
-    }
-    return a.id.localeCompare(b.id);
-  });
-
-  // Iterate bottom-to-top using reverse() to process leaf segments first
+  // Segments arrive in root-to-leaf order from the server (resolveSegment
+  // and resolveSegmentWithRevalidation push segments in this order).
+  // All consumers (reconcileSegments, cache) preserve this order.
+  // No sorting needed — iterate bottom-to-top to process leaf segments first.
   // This processes route/leaf layouts first, then parent layouts
   // Note: We reverse the array to iterate from end to start (bottom-to-top)
+
   for (let i = nonParallels.length - 1; i >= 0; i--) {
     const segment = nonParallels[i];
 

package/src/serialize.ts

@@ -0,0 +1,243 @@
+/**
+ * Wire-type serialization transforms.
+ *
+ * The type a handler or loader returns on the server is frequently NOT the type
+ * a client receives after serialization. These transforms model that boundary so
+ * consumer-facing types (e.g. `Rango.PathResponse`) describe the wire value, not
+ * the source value.
+ *
+ * Two serializers, two transforms — they are intentionally NOT interchangeable:
+ *
+ * - `JsonSerialize<T>` models plain `JSON.stringify` (`path.json()` /
+ *   `fetch().then(r => r.json())`). Lossy: `Date -> string`, `undefined` /
+ *   functions / symbols dropped, `Map`/`Set` -> `{}`. `bigint` *throws* (no wire
+ *   value), so it collapses the whole result to `never`. Honors `toJSON()`.
+ * - `FlightSerialize<T>` models React RSC Flight (loaders, RSC props, cache).
+ *   High fidelity: `Date`/`Map`/`Set`/`bigint`/typed arrays/`Promise` are
+ *   preserved; ordinary functions and non-global symbols do not cross.
+ *
+ * ## Overriding (full-transform replacement)
+ *
+ * Because `Rango.JsonSerialize` / `Rango.FlightSerialize` are type *aliases*, TS
+ * cannot let you redefine them directly (aliases don't merge). Instead each alias
+ * consults a generic override slot — augment it with a single member that is your
+ * complete transform. Delegate to the built-in for the cases you don't change:
+ *
+ * ```ts
+ * declare global {
+ *   namespace Rango {
+ *     interface FlightSerializeOverride<T> {
+ *       app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+ *     }
+ *   }
+ * }
+ * // now Rango.FlightSerialize<Money> is number; everything else is the built-in.
+ * ```
+ *
+ * Provide exactly one member: the slot is read as `Override<T>[keyof Override<T>]`,
+ * so multiple members union (and conflict). The built-in recurses through the
+ * override-aware alias, so an override applies at every nesting level.
+ */
+
+import type { ReactNode } from "react";
+
+type JsonPrimitive = string | number | boolean | null;
+
+type AnyFunction = (...args: never[]) => unknown;
+
+// --- JSON ---------------------------------------------------------------------
+
+/**
+ * Internal marker for a value that makes `JSON.stringify` throw (`bigint`, or a
+ * `toJSON()` returning one). Distinct from `never`, which means "omitted":
+ * `undefined`/function/symbol-valued keys are dropped, and such array slots
+ * become `null`. A throwing value has no valid JSON wire form, so it propagates
+ * up through every container and is excluded at the public boundary (`bigint`
+ * alone -> `never`; `{ id: bigint }` -> `never`).
+ */
+declare const JSON_THROWS: unique symbol;
+type JsonThrows = typeof JSON_THROWS;
+
+/** True if union `U` contains the throw marker. */
+type HasThrow<U> = [Extract<U, JsonThrows>] extends [never] ? false : true;
+
+/** Map a JSON array/tuple: propagate a throw; else omitted elements become null. */
+type JsonSerializeArray<T extends readonly unknown[]> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[number]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T]: [JsonRawResolve<T[K]>] extends [never]
+          ? null
+          : JsonRawResolve<T[K]>;
+      };
+
+/** Map a JSON object: propagate a throw; else drop omitted keys. */
+type JsonSerializeObject<T> =
+  HasThrow<{ [K in keyof T]: JsonRawResolve<T[K]> }[keyof T]> extends true
+    ? JsonThrows
+    : {
+        [K in keyof T as [JsonRawResolve<T[K]>] extends [never]
+          ? never
+          : K]: JsonRawResolve<T[K]>;
+      };
+
+/**
+ * Built-in JSON rules, *raw* (may yield the throw marker). Honors `toJSON()` (so
+ * `Date -> string` and any class with `toJSON()` serialize correctly), preserves
+ * JSON primitives and literals, omits functions / symbols / `undefined`,
+ * collapses `Map`/`Set` to `{}`, and marks `bigint` as throwing. Recurses through
+ * the override-aware resolver, so registered overrides apply at every level.
+ */
+type JsonSerializeBuiltinRaw<T> = T extends {
+  toJSON(...args: never[]): infer R;
+}
+  ? JsonRawResolve<R>
+  : T extends JsonPrimitive
+    ? T
+    : T extends bigint
+      ? JsonThrows
+      : T extends AnyFunction
+        ? never
+        : T extends symbol
+          ? never
+          : T extends undefined
+            ? never
+            : T extends readonly unknown[]
+              ? JsonSerializeArray<T>
+              : T extends ReadonlyMap<unknown, unknown>
+                ? {}
+                : T extends ReadonlySet<unknown>
+                  ? {}
+                  : T extends object
+                    ? JsonSerializeObject<T>
+                    : never;
+
+/** Override-aware raw JSON resolution (the recursion entry). */
+type JsonRawResolve<T> = [keyof Rango.JsonSerializeOverride<T>] extends [never]
+  ? JsonSerializeBuiltinRaw<T>
+  : Rango.JsonSerializeOverride<T>[keyof Rango.JsonSerializeOverride<T>];
+
+/**
+ * Model the result of round-tripping a value through `JSON.stringify` /
+ * `JSON.parse`. A registered `Rango.JsonSerializeOverride` replaces the transform
+ * wholesale; otherwise the built-in rules apply. Throwing values collapse to
+ * `never`.
+ */
+export type JsonSerialize<T> = Exclude<JsonRawResolve<T>, JsonThrows>;
+
+// --- Flight -------------------------------------------------------------------
+
+/**
+ * Built-in Flight rules. Mirrors React's `ReactClientValue` contract: primitives
+ * including `bigint`, `undefined`, `null`, symbols, `Date`, `ArrayBuffer` and
+ * typed-array views, `Map`, `Set`, `FormData`, `Blob`, `Promise`,
+ * `ReadableStream`, and (async) iterables are preserved; ordinary functions
+ * resolve to `never`. JSX (`ReactNode`, and the async-node union
+ * `ReactNode | Promise<ReactNode>`) is preserved as-is via a non-distributive
+ * leaf, so handle/loader returns that carry JSX round-trip unchanged. Recurses
+ * through the override-aware `FlightSerialize`.
+ *
+ * The source of truth is React's own contract, which is intentionally NOT
+ * semver-stable across RSC framework APIs — this tracks the React version Rango
+ * pins. See:
+ * https://react.dev/reference/rsc/use-client#serializable-types-returned-by-server-components
+ *
+ * Type-level limitations (not detectable structurally, so not modeled): class
+ * instances and null-prototype objects are rejected by React at runtime but pass
+ * here as their structural shape; non-global symbols are rejected at runtime but
+ * `symbol` is preserved here; Server Functions would need an override to be
+ * distinguished from ordinary functions (which resolve to `never`).
+ */
+type FlightSerializeBuiltinRaw<T> = [T] extends [ReactNode | Promise<ReactNode>]
+  ? T
+  : T extends string | number | boolean | bigint | symbol | null | undefined
+    ? T
+    : T extends AnyFunction
+      ? never
+      : T extends Date
+        ? Date
+        : T extends ArrayBuffer
+          ? ArrayBuffer
+          : T extends ArrayBufferView
+            ? T
+            : T extends FormData
+              ? FormData
+              : T extends Blob
+                ? Blob
+                : T extends Map<infer K, infer V>
+                  ? Map<FlightSerialize<K>, FlightSerialize<V>>
+                  : T extends Set<infer V>
+                    ? Set<FlightSerialize<V>>
+                    : T extends Promise<infer V>
+                      ? Promise<FlightSerialize<V>>
+                      : T extends ReadableStream<infer V>
+                        ? ReadableStream<FlightSerialize<V>>
+                        : T extends readonly unknown[]
+                          ? { [K in keyof T]: FlightSerialize<T[K]> }
+                          : T extends AsyncIterable<infer V>
+                            ? AsyncIterable<FlightSerialize<V>>
+                            : T extends Iterable<infer V>
+                              ? Iterable<FlightSerialize<V>>
+                              : T extends object
+                                ? { [K in keyof T]: FlightSerialize<T[K]> }
+                                : never;
+
+/**
+ * Model React RSC Flight serialization. A registered `Rango.FlightSerializeOverride`
+ * replaces the transform wholesale; otherwise the built-in rules apply.
+ */
+export type FlightSerialize<T> = [
+  keyof Rango.FlightSerializeOverride<T>,
+] extends [never]
+  ? FlightSerializeBuiltinRaw<T>
+  : Rango.FlightSerializeOverride<T>[keyof Rango.FlightSerializeOverride<T>];
+
+// Module-scoped aliases so the ambient `Rango.*` members below can reference the
+// module-level transforms without the global namespace shadowing the names.
+type GlobalJsonSerialize<T> = JsonSerialize<T>;
+type GlobalJsonSerializeBuiltin<T> = JsonSerializeBuiltinRaw<T>;
+type GlobalFlightSerialize<T> = FlightSerialize<T>;
+type GlobalFlightSerializeBuiltin<T> = FlightSerializeBuiltinRaw<T>;
+
+/**
+ * Ambient serialization transforms and their override slots on the `Rango`
+ * namespace. Available with no import wherever the router's types are in scope,
+ * alongside `Rango.Path` / `Rango.PathResponse`.
+ *
+ * `Rango.JsonSerialize` is what `Rango.PathResponse` applies; `Rango.FlightSerialize`
+ * is exposed for RSC/loader/cache wire types and must NOT be used for `path.json()`.
+ * `Rango.JsonSerializeBuiltin` / `Rango.FlightSerializeBuiltin` are the defaults,
+ * exported so an override can delegate to them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Full-transform override slot for `Rango.JsonSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.JsonSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface JsonSerializeOverride<T> {}
+
+    /**
+     * Full-transform override slot for `Rango.FlightSerialize`. Empty by default;
+     * augment with one member that is your complete transform (delegate to
+     * `Rango.FlightSerializeBuiltin<T>` for the cases you don't change).
+     */
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface FlightSerializeOverride<T> {}
+
+    /** Wire type after `JSON.stringify` (`path.json()` / `fetch().json()`). */
+    type JsonSerialize<T> = GlobalJsonSerialize<T>;
+    /**
+     * Built-in `JsonSerialize` rules, for an override to delegate to. Raw: a
+     * `bigint`-bearing type yields the internal throw marker here, which
+     * `Rango.JsonSerialize` excludes to `never` at the boundary.
+     */
+    type JsonSerializeBuiltin<T> = GlobalJsonSerializeBuiltin<T>;
+    /** Wire type after RSC Flight serialization (loaders / RSC props / cache). */
+    type FlightSerialize<T> = GlobalFlightSerialize<T>;
+    /** Built-in `FlightSerialize` rules, for an override to delegate to. */
+    type FlightSerializeBuiltin<T> = GlobalFlightSerializeBuiltin<T>;
+  }
+}