@rangojs/router 0.5.1 → 0.6.0

package/dist/types/router/router-interfaces.d.ts

@@ -2,6 +2,7 @@ import type { ComponentType } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
@@ -27,6 +28,11 @@ export interface RouterRequestInput<TEnv, TVars = DefaultVars> {
     vars?: Partial<TVars>;
     ctx?: ExecutionContext;
 }
+/** One materialized UrlPatterns registration and its live router mount index. */
+export interface UrlPatternMount<TEnv = any> {
+    readonly patterns: UrlPatterns<TEnv, any>;
+    readonly mountIndex: number;
+}
 /**
  * Merge route patterns with response types into a single route map.
  * Routes with response types get { path, response } objects; others stay as strings.
@@ -79,6 +85,12 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```
      */
     routes<T extends UrlPatterns<any, any, any>>(patterns: T & EnvCompatible<T, TEnv>): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]> : Record<string, string>)>;
+    /**
+     * Pure-client mounting shorthand: normalizes to a root include in the
+     * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+     * lazy materialization as mounting through include() yourself.
+     */
+    routes<T extends ClientUrlPatterns<any>>(patterns: T): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? NonNullable<T["_routes"]> : Record<string, string>)>;
     routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
     /**
      * Add global middleware that runs on all routes
@@ -184,7 +196,15 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * `urls<{ DB }>()` cannot be mounted on a `createRouter<{}>()`.
      */
     routes<T extends UrlPatterns<any, any, any>>(patterns: T & EnvCompatible<T, TEnv>): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]> : Record<string, string>)>;
+    /**
+     * Pure-client mounting shorthand: normalizes to a root include in the
+     * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+     * lazy materialization as mounting through include() yourself.
+     */
+    routes<T extends ClientUrlPatterns<any>>(patterns: T): Rango<TEnv, TRoutes & (NonNullable<T["_routes"]> extends Record<string, unknown> ? NonNullable<T["_routes"]> : Record<string, string>)>;
     routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
+    /** Materialized UrlPatterns registrations in registration order. */
+    readonly __urlpatternMounts: readonly UrlPatternMount<TEnv>[];
     /**
      * Add global middleware that runs on all routes
      */

package/dist/types/router/segment-resolution/helpers.d.ts

@@ -7,7 +7,7 @@
  * - Layout handler resolution with static fallback
  * - Error boundary segment creation
  */
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { EntryData } from "../../server/context";
 import type { ResolvedSegment, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";

package/dist/types/router/trie-matching.d.ts

@@ -4,7 +4,7 @@
  * Walks the pre-built trie by path segments in O(path_length) time.
  * Falls back to null when no match is found (caller uses regex fallback).
  */
-import type { TrieNode, NegotiateVariant } from "../build/route-trie.js";
+import type { TrieNode, NegotiateVariant } from "./route-trie-builder.js";
 export interface TrieMatchResult {
     /** Route name */
     routeKey: string;

package/dist/types/rsc/helpers.d.ts

@@ -6,6 +6,7 @@
 import type { RequestContext } from "../server/request-context.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
 /**
  * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
  * iteration prevents re-entrant registrations from double-firing and matches
@@ -122,3 +123,5 @@ export declare function mergeStubHeadersAndFinalize(response: Response): Respons
  * but still need ctx.onResponse() callbacks to fire.
  */
 export declare function finalizeResponse(response: Response): Response;
+/** Match and stamp params/routeName on the request context as one operation. */
+export declare function matchAndRecordParams<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>>;

package/dist/types/rsc/manifest-init.d.ts

@@ -1,13 +1,13 @@
 /**
  * Router Manifest Initialization
  *
- * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
- * where the manifest exists but the trie needs rebuilding.
+ * Builds a fresh route trie from every registered URL-pattern mount for
+ * dev/HMR scenarios where the manifest exists but the trie needs rebuilding.
  */
 /**
- * Build a fresh route trie from router.urlpatterns and store it in the
- * per-router cache. Also sets the per-router manifest and merges into
- * the global manifest for reverse()/href().
+ * Build a fresh route trie from the router's URL-pattern mounts and store it in
+ * the per-router cache. Also sets the per-router manifest and merges into the
+ * global manifest for reverse()/href().
  *
  * Called when manifest data may exist but the per-router trie is missing,
  * which happens in dev mode after HMR: the virtual module sets the manifest

package/dist/types/rsc/render-pipeline.d.ts

@@ -2,6 +2,7 @@ import type { TraceSpan } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { RscPayload } from "./types.js";
+import type { RoutineTrace } from "./routine-plan.js";
 export type RscRenderMode = RenderMode;
 export type RscRenderPhase = RenderPhase;
 export interface RscRenderStageProgress {
@@ -135,5 +136,13 @@ export declare function renderRscResponse<TEnv>(input: RscRenderInput<TEnv>, opt
  * Standard responses use renderRscResponse so the driver owns every phase.
  */
 export declare function renderRscFlightStage<TEnv>(input: RscFlightStageInput<TEnv>, init?: ResponseInit): RscFlightStage;
+/**
+ * Feed this driver's stage events (flight/html/response) into a routine flow
+ * trace as child entries of the currently running plan step. Stages are
+ * strictly sequential, so one `current` slot suffices. Depth is captured at
+ * creation: the bridge is built while the caller's render step executes, so
+ * children sit one level under it.
+ */
+export declare function createRenderStageTraceBridge(trace: RoutineTrace): (event: RscRenderStageEvent) => void;
 export declare function createRscStageDebugSink(log?: (message: string, details?: Record<string, unknown>) => void): (event: RscRenderStageEvent) => void;
 export {};

package/dist/types/rsc/routine-plan.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Routine plans — the request-level extension of the render stage driver
+ * (docs/design/routine-plans.md; protocol lineage in render-stage-driver.md).
+ * A plan is a synchronous generator that EMITS instructions before their work
+ * runs; the runner is the only code that executes them. Two effect shapes:
+ *
+ *   step(name, fn)     — sequential work; the plan suspends until its result.
+ *   handoff(name, fn)  — background registration (waitUntil-shaped); completes
+ *                        at scheduling and returns nothing.
+ *
+ * Plans compose by level: `yield* scope(name, plan)` flattens a nested plan
+ * into the same instruction stream while the trace records the scope. Tracking
+ * is derived, not declared — "what is running" is the instruction in hand.
+ *
+ * Deliberate boundaries (see the design doc's "Not built yet, on purpose"):
+ * the runner opens no observability spans — effects own their own
+ * instrumentation, and the render driver keeps PHASES.ssr — and there is no
+ * plan.return abort/cleanup path; the render driver's cleanup rules are the
+ * template if a caller ever needs one.
+ */
+export type RoutineEffectKind = "step" | "handoff";
+export type RoutineCommand = {
+    kind: "step";
+    name: string;
+    execute: () => unknown;
+} | {
+    kind: "handoff";
+    name: string;
+    execute: () => unknown;
+} | {
+    kind: "enter";
+    name: string;
+} | {
+    kind: "exit";
+    outcome: "done" | "failed";
+    error?: unknown;
+};
+export type RoutineCommandResult = {
+    kind: "step";
+    value: unknown;
+} | {
+    kind: "handoff";
+} | {
+    kind: "enter";
+} | {
+    kind: "exit";
+};
+/** One imperative step: yields a command, returns its typed result. */
+export type RoutineStep<T> = Generator<RoutineCommand, T, RoutineCommandResult>;
+/** A full plan is shaped like a step; the alias marks intent at call sites. */
+export type RoutinePlan<TReturn> = RoutineStep<TReturn>;
+/**
+ * Sequential work. The `as Awaited<T>` narrow is the trust boundary with the
+ * runner, which resumes with the exact value `execute` produced.
+ */
+export declare function step<T>(name: string, execute: () => T | Promise<T>): RoutineStep<Awaited<T>>;
+/**
+ * Background handoff: successful registration completes the foreground step.
+ * A synchronous registration failure is thrown back into the plan, matching a
+ * direct waitUntil/scheduler call. A returned promise settles in the background;
+ * its rejection marks the trace but never fails the foreground response.
+ *
+ * Settlement tracking follows the RETURNED value: a returned promise is
+ * observed until it settles; a scheduler that fires-and-forgets internally
+ * (e.g. scheduleShellCapture via runBackground) returns void, so its trace
+ * entry settles at the scheduling call, not at background completion. That is
+ * deliberate — the plan's contract ends at the handoff.
+ */
+export declare function handoff(name: string, execute: () => unknown): RoutineStep<void>;
+/**
+ * Run a nested plan as a named scope. `yield*` flattens its instructions into
+ * the parent stream; enter/exit only inform the trace. The scope reports its
+ * terminal outcome after internal recovery has either succeeded or escaped.
+ */
+export declare function scope<TReturn>(name: string, plan: RoutinePlan<TReturn>): RoutineStep<TReturn>;
+export interface RoutineTraceEntry {
+    name: string;
+    kind: RoutineEffectKind | "scope";
+    depth: number;
+    /** step/scope: running -> done|failed. handoff: pending -> settled|failed. */
+    state: "running" | "pending" | "done" | "settled" | "failed";
+    startedAt: number;
+    endedAt?: number;
+    settledAt?: number;
+    error?: unknown;
+}
+export interface RoutineTrace {
+    readonly name: string;
+    readonly entries: readonly RoutineTraceEntry[];
+    enterScope(name: string): void;
+    exitScope(outcome: "done" | "failed", error?: unknown): void;
+    /** Scope depth entries currently record at. Bridges (e.g. render stage
+     * events feeding child entries under a running step) capture this once and
+     * pass `depth + 1` explicitly. */
+    currentDepth(): number;
+    begin(name: string, kind: RoutineEffectKind, depth?: number): RoutineTraceEntry;
+    end(entry: RoutineTraceEntry): void;
+    fail(entry: RoutineTraceEntry, error: unknown): void;
+    settle(entry: RoutineTraceEntry, outcome: {
+        status: "fulfilled";
+    } | {
+        status: "rejected";
+        error: unknown;
+    }): void;
+    /** Running scopes plus the foreground instruction currently in hand. */
+    active(): RoutineTraceEntry[];
+    format(): string;
+    formatActive(entries?: readonly RoutineTraceEntry[], activeAt?: number): string;
+}
+export declare function createRoutineTrace(name: string, now?: () => number): RoutineTrace;
+export interface RoutineTraceOwner {
+    _activeRoutine?: RoutineTrace;
+}
+export interface RoutineRunnerOptions {
+    trace?: RoutineTrace;
+    owner?: RoutineTraceOwner;
+}
+/**
+ * Interpret a plan. Invariants shared with driveRscRenderPlan: a command is
+ * observable before its work runs, `execute` runs exactly once, results and
+ * errors resume the plan with exact identity, and a plan-level try/catch
+ * around a step is the recovery mechanism.
+ */
+export declare function runRoutine<TReturn>(plan: RoutinePlan<TReturn>, options?: RoutineRunnerOptions): Promise<TReturn>;

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -25,3 +25,20 @@
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
+/**
+ * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
+ * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+ * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
+ * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * wedges the task with no deadline in force. The task's settle path releases
+ * the per-key stampede guard and the serialized capture-queue slot, so an
+ * unbounded task strands BOTH for the isolate's lifetime.
+ *
+ * 25s: above one full-budget attempt plus overhead (cutting a second attempt
+ * short is an acceptable loss — every terminal path backs the key off anyway),
+ * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
+ * live context. When workerd kills the context BEFORE the cap fires, the timer
+ * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * check on the stampede guard, keyed off the same constant.
+ */
+export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;

package/dist/types/rsc/shell-capture.d.ts

@@ -273,6 +273,15 @@ export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>,
  */
 export interface ShellCaptureDescriptor {
     key: string;
+    /**
+     * The key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+     * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key; the resume pass derives the identical string from
+     * the HIT request. Computed next to the key so the two cannot drift.
+     * Omitted (build-time bare-pathname captures) = search-less, same as "".
+     */
+    searchSeed?: string;
     /**
      * The RSC handler's build version (HandlerContext.version), stamped into the
      * stored entry as ShellCacheEntry.buildVersion — the serve-side

package/dist/types/rsc/shell-serve.d.ts

@@ -94,6 +94,17 @@ export declare function resolvePprConfig(entry: EntryData | undefined | null): R
  * and lookup makes every shell request a permanent miss.
  */
 export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
 /**
  * Version gates for a stored shell: reactVersion AND buildVersion must both
  * match the running server. The postponed blob encodes hole positions against

package/dist/types/rsc/types.d.ts

@@ -33,12 +33,29 @@ export interface RscPayload {
         /** Merged route params from the matched route */
         params?: Record<string, string>;
         slots?: Record<string, SlotState>;
+        /**
+         * Intercept TARGET route names reachable from this location as a
+         * navigation origin (see MatchResult.interceptTargets). The browser-local
+         * clientUrls matcher declines optimistic presentation for these.
+         */
+        interceptTargets?: string[];
         /** Root layout component for browser-side re-renders (client component reference) */
         rootLayout?: React.ComponentType<{
             children: React.ReactNode;
         }>;
         /** Handle data accumulated across route segments (async generator that yields on each push) */
         handles?: AsyncGenerator<HandleData, void, unknown>;
+        /**
+         * Document-lane late handle channel: full-state updates for pushes landing
+         * AFTER the handler barrier (streaming loader bodies writing handles
+         * mid-body). `handles` above is drained to completion in blocking
+         * positions (SSR seed, pre-hydration), so late pushes need this separate
+         * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+         * Empty/instantly-complete when no auxiliary-lane work is pending at the
+         * handler barrier. Full payloads only — partial payloads' `handles`
+         * generator streams to full settle already.
+         */
+        handlesLate?: AsyncGenerator<HandleData, void, unknown>;
         /** RSC version string for cache invalidation */
         version?: string;
         /** Cloudflare dev worker generation used for stale-document convergence. */
@@ -147,6 +164,17 @@ export interface SSRRenderOptions {
      * - `"allReady"` — await `stream.allReady` before returning.
      */
     streamMode?: import("../router/router-options.js").SSRStreamMode;
+    /**
+     * The live request's query string (`url.search`, `?`-prefixed or empty).
+     * Seeds the SSR navigation store so `useSearchParams` (and
+     * `useNavigation().location`) carry real values during document renders.
+     * Out-of-band by design — never payload metadata, which cached/prerendered
+     * payloads replay; search is not route identity. The build-time prerender
+     * pass passes none — build shells capture bare pathnames and serve
+     * search-less requests only (runtime ppr captures seed the shell key's
+     * search; see ShellCaptureOptions.search in the SSR entry).
+     */
+    search?: string;
 }
 /**
  * SSR module interface for HTML rendering
@@ -164,6 +192,7 @@ export interface SSRModule {
     captureShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
         quiesce: Promise<void>;
         maxWaitMs?: number;
+        search?: string;
     }) => Promise<{
         prelude: Uint8Array;
         postponed: string | null;
@@ -179,6 +208,7 @@ export interface SSRModule {
     resumeShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
         postponed: string | null;
         nonce?: string;
+        search?: string;
     }) => Promise<ReadableStream<Uint8Array>>;
 }
 /**

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

@@ -17,6 +17,8 @@ export interface RenderSegmentsOptions {
      * from cache without showing loading skeletons.
      */
     forceAwait?: boolean;
+    /** Seeded descendant client-route pending state for testing. */
+    outletPending?: boolean;
     /**
      * Intercept segments to inject into the tree.
      * These are parallel segments from intercept routes that need to be

package/dist/types/server/context.d.ts

@@ -82,6 +82,16 @@ export type LoaderEntry = {
     revalidate: ShouldRevalidateFn<any, any>[];
     /** Cache config for this specific loader (loaders are NOT cached by default) */
     cache?: EntryCacheConfig;
+    /**
+     * Document renders await this loader before segment resolution returns
+     * (loader(Def, { stream: "navigation" })), so its data, handle pushes, and
+     * thrown notFound()/redirect() deterministically precede first flush.
+     * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
+     * per-isSSR (router/manifest.ts cache key), so the flag is already
+     * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+     * appears on navigation-lane entries.
+     */
+    awaitBeforeFlush?: true;
 };
 /**
  * Segments state for intercept context

package/dist/types/server/handle-store.d.ts

@@ -49,6 +49,24 @@ export interface HandleStore {
      * to onError and telemetry.
      */
     onError?: (error: Error) => void;
+    /**
+     * Track a promise on the AUXILIARY (loader) settlement lane. Aux tracking
+     * keeps the store OPEN for pushes (a mid-body `ctx.handle(H)(...)` from a
+     * streaming loader is legal until this lane drains) WITHOUT joining
+     * `settled` — the handler barrier that rendered()-readers, the document
+     * handle snapshot, and prerender/cache collection wait on. Two lanes exist
+     * because loader bodies stream: joining them to `settled` would block SSR
+     * markup and hydration on the slowest loader (ssr-root.tsx and
+     * rsc-router.tsx both drain the document handle stream in blocking
+     * positions), and would self-deadlock any loader awaiting ctx.rendered().
+     */
+    trackAuxiliary<T>(promise: Promise<T>): Promise<T>;
+    /**
+     * Promise that resolves when the store is sealed AND BOTH lanes (handler +
+     * auxiliary) have drained. Late-push legality and default stream completion
+     * key on this, not on `settled`.
+     */
+    readonly fullySettled: Promise<void>;
     /**
      * Push handle data for a specific handle and segment.
      * Multiple pushes to the same handle/segment accumulate in an array.
@@ -57,15 +75,28 @@ export interface HandleStore {
     push(handleName: string, segmentId: string, data: unknown): void;
     /**
      * Get all collected handle data after all handlers have settled.
-     * Waits for `settled`, then returns the finalized data.
+     * Waits for `settled` (handler lane), then returns the data at that point.
      */
     getData(): Promise<HandleData>;
     /**
      * Get an async iterator that yields handle data on each push.
-     * The iterator completes when all handlers have settled.
+     * Completes at the chosen settlement barrier: "fullySettled" (default —
+     * nav/action payloads, whose consumer applies each yield progressively) or
+     * "settled" (the document lane, whose consumers drain to completion in
+     * blocking positions and must not wait on loader bodies).
      * Each yield contains the full accumulated state (not just the delta).
+     * Safe for concurrent consumers (per-consumer version cursor).
+     */
+    stream(until?: "settled" | "fullySettled"): AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late channel: yields full-state updates for pushes that
+     * land AFTER the handler barrier (streaming loader bodies), completing at
+     * fullySettled. Returns without yielding when the auxiliary lane is empty
+     * by the time `settled` resolves. The client consumes this post-hydration
+     * (rsc-router.tsx) and merges via the same application path as nav-lane
+     * progressive handle updates.
      */
-    stream(): AsyncGenerator<HandleData, void, unknown>;
+    streamLate(): AsyncGenerator<HandleData, void, unknown>;
     /**
      * Get handle data for a specific segment (for caching).
      * Returns data in format: { handleName: [values...] }

package/dist/types/server/request-context.d.ts

@@ -26,6 +26,7 @@ import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RoutineTrace } from "../rsc/routine-plan.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
     phase: RenderPhase;
@@ -506,6 +507,16 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * rendered() and a handler already awaits it, we can detect the deadlock.
      */
     _handlerLoaderDeps?: Set<string>;
+    /**
+     * @internal Loader IDs ($$id) whose entries carry `awaitBeforeFlush`
+     * (loader(Def, { stream: "navigation" })): segment resolution awaits these
+     * before returning, so the render barrier cannot resolve until they settle.
+     * rendered() checks this set to fail fast — a flagged loader awaiting the
+     * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders
+     * (fresh.ts) before loader kickoff; only ever populated on document renders
+     * (the flag is stamped per-isSSR at DSL evaluation).
+     */
+    _awaitBeforeFlushLoaderIds?: Set<string>;
     /**
      * @internal Cached HandleData snapshot built at barrier resolution time.
      * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
@@ -542,6 +553,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * loaders and post-commit stream work have separate lifetimes.
      */
     _renderForeground?: RenderForegroundCursor;
+    /** @internal Request routine currently executing, used by timeout diagnostics. */
+    _activeRoutine?: RoutineTrace;
     /** @internal Keep the render cursor active for timeout support. */
     _renderDiagnosticsEnabled?: boolean;
     /**
@@ -585,7 +598,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/server.d.ts

@@ -13,3 +13,4 @@ export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRoute
 export { registerLoaderById, setLoaderImports, } from "./server/loader-registry.js";
 export { createRequestContext, type CreateRequestContextOptions, } from "./server/request-context.js";
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
+export { clearClientUrlProjections, setClientUrlProjection, type ClientUrlProjection, } from "./client-urls/server-projection.js";

package/dist/types/ssr/index.d.ts

@@ -82,6 +82,14 @@ export interface SSRRenderOptions {
      * - `"allReady"` — await `stream.allReady` before returning.
      */
     streamMode?: import("../router/router-options.js").SSRStreamMode;
+    /**
+     * The live request's query string (`?`-prefixed or empty). Seeds the SSR
+     * navigation store location so `useSearchParams` carries real values
+     * during document renders. Absent on the build-time prerender pass —
+     * build shells capture bare pathnames and serve search-less requests
+     * only (runtime captures own the search variants, seeded per key).
+     */
+    search?: string;
 }
 /**
  * SSR dependencies from external packages
@@ -169,6 +177,13 @@ interface ShellCaptureOptions {
     quiesce: Promise<void>;
     /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
     maxWaitMs?: number;
+    /**
+     * The SHELL KEY's search string (`?`-prefixed, sorted, cache.searchParams
+     * filter applied — shellSearchSeed in rsc/shell-serve.ts), seeding the SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key. MUST equal the resume pass's seed for the same key.
+     */
+    search?: string;
 }
 /**
  * Result of a successful shell capture. `prelude` is the raw prelude bytes;
@@ -188,6 +203,13 @@ interface ShellResumeOptions {
     postponed: string | null;
     /** Nonce for CSP. */
     nonce?: string;
+    /**
+     * The SHELL KEY's search string — same derivation as the capture pass
+     * (shellSearchSeed). A HIT shares the capture's key, so seeding the same
+     * string keeps the resume tree identical to the captured tree above the
+     * postponed holes.
+     */
+    search?: string;
 }
 /**
  * Create an SSR handler that converts RSC streams to HTML.

package/dist/types/ssr/ssr-root.d.ts

@@ -48,6 +48,16 @@ export interface SsrRootOptions {
      * they postpone below the root.
      */
     onPayloadSettled?: () => void;
+    /**
+     * The query string seeding the SSR store location (`?`-prefixed or
+     * empty), so `useSearchParams`/`useNavigation` carry real values during
+     * document renders. Live fizz passes the request's raw search. The shell
+     * capture and resume passes pass the SHELL KEY's search (sorted,
+     * cache.searchParams filter applied — search is part of shell identity):
+     * a HIT shares the capture's key, so both passes seed the SAME string and
+     * the resume tree matches the captured tree above the postponed holes.
+     */
+    search?: string;
 }
 /**
  * Build the closure component that deserializes the Flight payload, consumes

package/dist/types/testing/dom.entry.d.ts

@@ -3,7 +3,7 @@
  *
  * Component-render testing: `renderRoute`, the React-Testing-Library-style stub
  * for client components that read router context (useParams / useReverse /
- * Outlet / useNavigation / useLoader).
+ * Outlet / useOutlet / useNavigation / useLoader).
  *
  * Separate from the main `@rangojs/router/testing` barrel so unit suites that
  * only test loaders, middleware, or `dispatch` never reference React, the

package/dist/types/testing/render-route.d.ts

@@ -19,18 +19,19 @@
  *     props crossing the RSC boundary), loader execution on the server,
  *     middleware, or handler ordering. Those are renderServerTree / renderHandler
  *     / e2e territory.
- *   - Loader data, location state, and handle output are SEEDED directly into
- *     client context (see the `loaders` / `locationState` / `handles` options) —
- *     nothing is executed on the server. This exercises the read path
- *     (useLoader / useLocationState / useHandle from context), not the run path.
+ *   - Loader data, location state, handle output, and outlet pending state are
+ *     SEEDED directly into client context (see the `loaders` / `locationState` /
+ *     `handles` / `outletPending` options) — nothing is executed on the server.
+ *     This exercises the context read path, not the run path.
  *   - navigate() commits synchronously, so it does NOT drive the navigation
  *     lifecycle: useNavigation().state, useLinkStatus().pending, and
  *     useAction().state stay "idle". Assert pending/loading/submitting transition
  *     states with renderServerTree / e2e instead (navigate() warns once if used).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
- * useRouter, usePathname, useSearchParams, Outlet nesting, useLoader /
- * useFetchLoader (seeded data), useLocationState (seeded), and useHandle (seeded).
+ * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
+ * descendant pending state, useLoader/useFetchLoader (seeded data),
+ * useLocationState (seeded), and useHandle (seeded).
  * Basename-mounted apps: pass the `basename` option so useRouter().basename,
  * <Link> prefixing, and useMount/useHref resolve against the mount prefix
  * (without it they resolve at the root "/"). For an include("/shop", ...)
@@ -96,6 +97,15 @@ export interface RenderRouteOptions {
      * the read path is exercised without executing any loader.
      */
     loaderData?: Record<string, unknown>;
+    /**
+     * Descendant client-route pending state to seed into each synthetic segment's
+     * production OutletProvider, so `useOutlet().pending` can be tested alongside
+     * `useOutlet().content`. Defaults to false.
+     *
+     * This is a seeded outlet-context value only. It does not model arbitrary
+     * Suspense, navigation, or action pending state.
+     */
+    outletPending?: boolean;
     /**
      * Loaders to seed by REFERENCE — the robust way to test a component that calls
      * `useLoader(loader)`. A real `createLoader()` handle has an empty `$$id` in a