@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/dist/types/search-params.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Search parameter schema types and runtime utilities.
+ *
+ * Provides a lightweight schema system for typed query parameters.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
+ */
+/** Supported scalar types for search params (append ? for optional). */
+export type SearchSchemaValue = "string" | "number" | "boolean" | "string?" | "number?" | "boolean?";
+/** A search schema maps param names to their type descriptors. */
+export type SearchSchema = Record<string, SearchSchemaValue>;
+/** Strip trailing `?` from a schema value to get the base type. */
+type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
+/** Map a base type string to its TypeScript type. */
+type ResolveBaseType<T extends string> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+/** Keys whose schema value does NOT end with `?`. */
+type RequiredKeys<T extends SearchSchema> = {
+    [K in keyof T]: T[K] extends `${string}?` ? never : K;
+}[keyof T];
+/** Keys whose schema value ends with `?`. */
+type OptionalKeys<T extends SearchSchema> = {
+    [K in keyof T]: T[K] extends `${string}?` ? K : never;
+}[keyof T];
+/** Flatten an intersection type into a single object type. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Resolve a SearchSchema to its typed object.
+ *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string | undefined; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<{
+    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>> | undefined;
+} & {
+    [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
+}>;
+/** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never ? keyof Rango.GeneratedRouteMap extends never ? Record<string, string> : Rango.GeneratedRouteMap : Rango.RegisteredRoutes;
+/**
+ * Extract the resolved search params type for a named route.
+ * Looks up the search schema from the route map and resolves it.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/search", handler, { name: "search", search: { q: "string", page: "number?" } })
+ * type Params = RouteSearchParams<"search">;
+ * // { q: string; page?: number }
+ * ```
+ */
+export type RouteSearchParams<TName extends string, TRouteMap = never> = [
+    TRouteMap
+] extends [never] ? ExtractAndResolveSearch<GlobalRouteMap, TName> : ExtractAndResolveSearch<TRouteMap, TName>;
+type ExtractAndResolveSearch<TRouteMap, TName> = TName extends keyof TRouteMap ? TRouteMap[TName] extends {
+    readonly search: infer S extends SearchSchema;
+} ? ResolveSearchSchema<S> : {} : {};
+/**
+ * Extract the route params type for a named route.
+ * Looks up the path pattern from the route map and extracts params.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/blog/:slug", handler, { name: "blogPost" })
+ * type Params = RouteParams<"blogPost">;
+ * // { slug: string }
+ * ```
+ */
+export type RouteParams<TName extends string, TRouteMap = never> = [
+    TRouteMap
+] extends [never] ? ExtractRouteParamsFromMap<GlobalRouteMap, TName> : ExtractRouteParamsFromMap<TRouteMap, TName>;
+type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap ? TRouteMap[TName] extends string ? ExtractParamsFromPattern<TRouteMap[TName]> : TRouteMap[TName] extends {
+    readonly path: infer P extends string;
+} ? ExtractParamsFromPattern<P> : {} : {};
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> = T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+/** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
+type ExtractParamsFromPattern<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? Param extends `${infer Name}(${infer C})?` ? {
+    [K in Name]?: ParseConstraint<C>;
+} & ExtractParamsFromPattern<`/${Rest}`> : Param extends `${infer Name}(${infer C})` ? {
+    [K in Name]: ParseConstraint<C>;
+} & ExtractParamsFromPattern<`/${Rest}`> : Param extends `${infer Name}?` ? {
+    [K in Name]?: string;
+} & ExtractParamsFromPattern<`/${Rest}`> : {
+    [K in Param]: string;
+} & ExtractParamsFromPattern<`/${Rest}`> : T extends `${string}:${infer Param}` ? Param extends `${infer Name}(${infer C})?` ? {
+    [K in Name]?: ParseConstraint<C>;
+} : Param extends `${infer Name}(${infer C})` ? {
+    [K in Name]: ParseConstraint<C>;
+} : Param extends `${infer Name}?` ? {
+    [K in Name]?: string;
+} : {
+    [K in Param]: string;
+} : {};
+/**
+ * Parse URLSearchParams into a typed object using the given schema.
+ *
+ * - `"string"` / `"string?"` - kept as-is
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
+ * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
+ *
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
+ */
+export declare function parseSearchParams<T extends SearchSchema>(searchParams: URLSearchParams, schema: T): ResolveSearchSchema<T>;
+/**
+ * Serialize a typed search params object to a query string (without leading `?`).
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
+ */
+export declare function serializeSearchParams(params: Record<string, unknown>): string;
+export {};

package/dist/types/segment-content-promise.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation.
+ *
+ * @internal
+ */
+export declare function getMemoizedContentPromise(component: ReactNode): Promise<ReactNode>;

package/dist/types/segment-fragments.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Segment Flight-fragment envelopes (PPR fast-path payload splice, issue #700).
+ *
+ * On a shell-HIT tail, replayed (baked) segments do NOT round-trip through the
+ * server codec (deserialize -> re-serialize) per request. The stored RSC
+ * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
+ * — the outer Flight render copies a string instead of re-serializing a whole
+ * element tree — and the CONSUMER expands each envelope through its own Flight
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
+ * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
+ * independently, exactly like the segment codec's per-record decode — so
+ * there is no Flight row-id collision or shared-row dedupe hazard.
+ *
+ * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
+ * loading). A plain object is never a valid ReactNode, so the marker cannot
+ * collide with legitimate segment content; loader data fields (consumer data,
+ * any shape) are never enveloped.
+ *
+ * This module is shared client/server code (browser + SSR + RSC import it) —
+ * it must stay dependency-free: no plugin-rsc, no request-context.
+ */
+import type { ResolvedSegment } from "./types.js";
+/**
+ * One RSC-encoded fragment traveling inside an RscPayload segment field.
+ * `f` is the stored Flight document (segment-codec output) for that field.
+ */
+export interface SegmentFlightFragment {
+    __rangoFragment: 1;
+    f: string;
+}
+/** Wrap a stored fragment string for the wire. */
+export declare function segmentFragment(encoded: string): SegmentFlightFragment;
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export declare function isSegmentFragment(value: unknown): value is SegmentFlightFragment;
+/**
+ * A consumer-side Flight deserializer: the browser's or the SSR runtime's
+ * createFromReadableStream (each resolves client references through its own
+ * module map, exactly as it does for the outer payload stream). Non-generic
+ * so both environments' generic createFromReadableStream signatures assign
+ * directly.
+ */
+export type FragmentDecoder = (stream: ReadableStream<Uint8Array>) => Promise<unknown>;
+/**
+ * Expand every fragment envelope in `segments` IN PLACE via `decode`,
+ * in parallel. A payload with no envelopes (every non-shell-HIT payload) costs
+ * one synchronous field scan. A failing fragment decode rejects the whole
+ * expansion: the caller's payload promise rejects, which on the SSR side
+ * errors the HIT tail (serveShellHit then schedules the healing recapture) —
+ * the same posture as a parseable-but-mismatched postponed blob.
+ */
+export declare function expandSegmentFragments(segments: ResolvedSegment[] | undefined, decode: FragmentDecoder): Promise<void>;
+/**
+ * True when any segment carries an unexpanded envelope. Cheap scan used by
+ * consumers that only need to know whether an expansion pass is required.
+ */
+export declare function hasSegmentFragments(segments: ResolvedSegment[] | undefined): boolean;

package/dist/types/segment-loader-promise.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Build a fresh aggregate Promise.all over the loaders' resolved data refs.
+ * Unlike getMemoizedLoaderPromise this never caches, so each call yields a new
+ * Promise — correct for sites that await the result immediately (a shared,
+ * already-resolved promise would leak React's `.status` across server requests
+ * and skip the Suspense fallback).
+ *
+ * @internal
+ */
+export declare function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]>;
+/**
+ * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
+ * same aggregate across renders — invalidated only when any underlying
+ * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
+ * state and prevents a fresh Promise.all from suspending (and briefly
+ * committing the Suspense fallback) on every partial update that doesn't
+ * actually change loader data.
+ *
+ * @internal
+ */
+export declare function getMemoizedLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> | any[];

package/dist/types/segment-system.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode, type ComponentType } from "react";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
+export declare function restoreParallelLoaderMarkers(segments: ResolvedSegment[]): ResolvedSegment[];
+/**
+ * Options for renderSegments
+ */
+export interface RenderSegmentsOptions {
+    /**
+     * If true, this render is for a server action response.
+     * In browser during actions, we await component promises to prevent
+     * UI flickering/suspense during optimistic updates.
+     */
+    isAction?: boolean;
+    /**
+     * If true, force awaiting all loaders instead of streaming with Suspense.
+     * Used for popstate (back/forward) navigation where we want instant rendering
+     * from cache without showing loading skeletons.
+     */
+    forceAwait?: boolean;
+    /**
+     * Intercept segments to inject into the tree.
+     * These are parallel segments from intercept routes that need to be
+     * associated with their parent layout's named outlet.
+     *
+     * Passed separately for explicit handling - makes the flow clearer
+     * and easier to debug than relying on ID pattern matching.
+     */
+    interceptSegments?: ResolvedSegment[];
+    /**
+     * Root layout component that wraps the entire application.
+     * When provided, wraps both route content and the error boundary,
+     * preventing the app shell from unmounting during errors (avoids FOUC).
+     */
+    rootLayout?: ComponentType<RootLayoutProps>;
+}
+/**
+ * Render segments into a React tree with proper layout nesting
+ *
+ * Layouts nest using OutletProvider; a layout receives the inner content via
+ * its `<Outlet />`. Parallel segments do NOT render as inline Fragment siblings
+ * — they flow through OutletContext.parallel and are resolved where a layout
+ * places `<ParallelOutlet name="@sidebar" />` (or `<Outlet name="@sidebar" />`).
+ *
+ * The result is always wrapped in RootErrorBoundary so unhandled errors never
+ * blank the screen. When `options.rootLayout` is provided it wraps the error
+ * boundary at the OUTERMOST level (so the app shell survives errors).
+ *
+ * Error segments are treated like route segments - they render their fallback
+ * component in place of the failed segment. When an error occurs in a handler,
+ * loader, or middleware, the router creates an error segment with the nearest
+ * error boundary's fallback component.
+ *
+ * NotFound segments are similar to error segments but are triggered by
+ * DataNotFoundError (thrown via notFound()). They render the nearest
+ * notFoundBoundary's fallback component.
+ *
+ * @param segments - Array of resolved segments to render
+ * @returns Promise resolving to the ReactNode tree (the function is async)
+ *
+ * @example
+ * ```typescript
+ * const segments = [
+ *   { id: 'L0.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'L0R1', type: 'route', component: <BlogPost /> },
+ *   { id: 'L0R1.@sidebar', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ * ];
+ *
+ * // BlogLayout renders <Outlet /> for the route and
+ * // <ParallelOutlet name="@sidebar" /> for the parallel slot.
+ * const tree = await renderSegments(segments, { rootLayout: RootLayout });
+ * // Results in (outermost first):
+ * // <RootLayout>
+ * //   <RootErrorBoundary>
+ * //     <OutletProvider segment={BlogLayout} parallel={[Sidebar]}>
+ * //       <BlogPost />
+ * //     </OutletProvider>
+ * //   </RootErrorBoundary>
+ * // </RootLayout>
+ *
+ * // For server actions, pass isAction to await components:
+ * const tree = await renderSegments(segments, { isAction: true });
+ * ```
+ */
+export declare function renderSegments(segments: ResolvedSegment[], options?: RenderSegmentsOptions): Promise<ReactNode>;

package/dist/types/serialize.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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;
+/**
+ * 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>;
+/**
+ * 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>];
+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).
+         */
+        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).
+         */
+        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>;
+    }
+}
+export {};