@rangojs/router 0.4.0 → 0.4.2

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

@@ -6,10 +6,11 @@
  * 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.
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx), browser hydration, and
+ * capability-gated partial navigation/prefetch decoders. 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
@@ -20,6 +21,15 @@
  * it must stay dependency-free: no plugin-rsc, no request-context.
  */
 import type { ResolvedSegment } from "./types.js";
+/** Partial-request capability gate for browser-side fragment expansion. */
+export declare const SEGMENT_FRAGMENT_CAPABILITY_HEADER: string;
+/** One-shot request marker that forces server-side fragment validation. */
+export declare const SEGMENT_FRAGMENT_RECOVERY_HEADER: string;
+/** A stored fragment failed in its consumer-side Flight decoder. */
+export declare class SegmentFragmentDecodeError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
 /**
  * One RSC-encoded fragment traveling inside an RscPayload segment field.
  * `f` is the stored Flight document (segment-codec output) for that field.
@@ -49,6 +59,19 @@ export type FragmentDecoder = (stream: ReadableStream<Uint8Array>) => Promise<un
  * the same posture as a parseable-but-mismatched postponed blob.
  */
 export declare function expandSegmentFragments(segments: ResolvedSegment[] | undefined, decode: FragmentDecoder): Promise<void>;
+/**
+ * Expand every envelope in an RscPayload-shaped object, in place. Decode
+ * failures use a distinct error so partial navigation can retry once through
+ * the server's decode-and-evict path. The
+ * hasSegmentFragments pre-scan keeps envelope-free payloads — every
+ * non-replay response — to one synchronous field walk; this runs on every
+ * navigation and prefetch decode.
+ */
+export declare function expandPayloadFragments(payload: {
+    metadata?: {
+        segments?: ResolvedSegment[];
+    };
+}, 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.

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

@@ -143,8 +143,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     }>;
     /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
     _pprTransitionDecisions?: Map<string, boolean>;
+    /**
+     * @internal Post-match serve-source truth for the PPR replay reporter.
+     * Stamped from the match context as `intercept`, then overwritten as
+     * `prerender-store` if that lookup actually serves. The latter wins because
+     * it identifies the response source. matchPartialWithPprReplay reads this
+     * AFTER matching to reclassify its pre-match guess and suppress pointless
+     * heal captures.
+     */
+    _pprReplayPostMatchReason?: "prerender-store" | "intercept";
     /** @internal Cache store for segment caching (optional, used by CacheScope) */
     _cacheStore?: SegmentCacheStore;
+    /**
+     * @internal Compiled `cache.searchParams` filter for default cache-key
+     * generation (undefined = "all", the byte-stable unfiltered format). Set
+     * once per request by handler.ts; every URL-keyed tier (segment, document,
+     * response, shell, "use cache") reads it so the tiers cannot drift.
+     */
+    _searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
     /**
      * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
      * capture task's derived request context (built by shell-capture.ts). This is
@@ -190,9 +206,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
      * replay, where `store` is a request-local segment overlay. Handler-live holes
      * and conditional transitions decline replay.
-     * Routes with their own cache() config (including cache(false)) are never
-     * overridden: the marker only applies when the route tree derived NO cache
-     * scope.
+     * Routes with their own cache() config are never overridden — their scope's
+     * store/key/ttl/swr/condition semantics stay authoritative. On the
+     * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
+     * such a scope instead of being ignored: the seeded doc record supplies the match
+     * only when the explicit tier misses (withCacheLookup). cache(false) and a
+     * false condition() stay absolute opt-outs — replay bypasses before any
+     * shell read (`cache-disabled`).
      */
     _shellImplicitCache?: {
         ttl?: number;
@@ -206,17 +226,58 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         keyPrefix?: "doc";
         /** @internal Called only after the implicit cache hit decodes successfully. */
         onHit?: () => void;
+        /**
+         * @internal Called when the seeded document record fails server-side
+         * deserialization. Partial replay uses it to replace the enclosing shell
+         * snapshot after serving the fresh fallback.
+         */
+        onCorrupt?: () => void;
+        /**
+         * @internal The resolved key of the canonical document segment record.
+         * Written during a CAPTURE render by CacheScope.cacheRoute when a
+         * doc-namespaced scope records the matched segments; captureAndStoreShell
+         * stamps it onto the ShellCacheEntry (`docKey`) so replay eligibility can
+         * require the exact consumable record instead of "any segment record".
+         */
+        docKey?: string;
+        /**
+         * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
+         * serve path. Its presence arms the explicit-scope composition in
+         * withCacheLookup: a route-derived cache() scope stays authoritative, and
+         * only when its lookup MISSes does the seeded doc record supply the match.
+         * A capture render must never set this (its match must re-run handlers so
+         * SWR recapture stays fresh), which is why the fallback keys off this
+         * field and not off the marker itself. Fired when the route-derived
+         * scope's own lookup supplied the match — the header then reports
+         * `BYPASS; reason=explicit-cache-hit`, never a false replay HIT.
+         */
+        onExplicitHit?: () => void;
+        /**
+         * @internal Companion to onExplicitHit, same lifecycle: fired when the
+         * route-derived scope's lookup REFUSED the read (`bypass` outcome — a
+         * false condition() or no store). The gate only pre-decides the static
+         * cache(false) case; a predicate refusal is known only at lookup time and
+         * reports `BYPASS; reason=cache-disabled` post-match.
+         */
+        onExplicitBypass?: () => void;
     };
     /**
-     * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
-     * render emit stored segment fragments VERBATIM into the payload
+     * @internal Fragment-passthrough marker: cache/prerender-store hits during
+     * THIS render emit stored segment fragments VERBATIM into the payload
      * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
-     * per request; the payload consumers (SSR resume + browser hydration)
-     * expand them (segment-fragments.ts, issue #700). Own property of
-     * serveShellHit's derived tail context ONLY — it must never be visible to a
-     * capture render: the capture SSR-prerenders the payload AND serializes
-     * segments into records (cacheRoute), and an envelope reaching
-     * serializeSegments would store a double-encoded fragment.
+     * per request; the payload consumers (SSR resume, browser hydration, and
+     * the client partial-navigation decode chokepoints) expand them
+     * (segment-fragments.ts, issue #700). Partial requests arm only after the
+     * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+     * retries without it so CacheScope can evict the bad record. Two arming sites,
+     * both scoped to a
+     * render/match window: serveShellHit's derived tail context (document
+     * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+     * match (matchPartialForReplay). It must never be visible to a capture
+     * render: the capture SSR-prerenders the payload AND serializes segments
+     * into records (cacheRoute), and an envelope reaching serializeSegments
+     * would store a double-encoded fragment — deriveShellCaptureContext resets
+     * it as an own property for exactly that reason.
      */
     _shellFragmentPayload?: boolean;
     /**
@@ -518,7 +579,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" | "_cacheStore" | "_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" | "_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" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_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:
@@ -574,6 +635,11 @@ export interface CreateRequestContextOptions<TEnv> {
     initialResponse?: Response;
     /** Optional cache store for segment caching (used by CacheScope) */
     cacheStore?: SegmentCacheStore;
+    /**
+     * Compiled `cache.searchParams` filter from the resolved handler cache
+     * config (handler.ts). Stored as _searchParamsFilter.
+     */
+    searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
     /**
      * Handler-owned registry of explicit per-scope stores for cross-store tag
      * invalidation. Created once per handler, reused across requests.

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

@@ -37,7 +37,7 @@
  * subtree, pass the `mount` option so useMount() returns the mounted prefix
  * (the segment chain is wrapped in a MountContext exactly as in production).
  */
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import type { NavigationStore } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
@@ -45,6 +45,7 @@ import type { LoaderDefinition } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
 /**
  * Seed shape for `options.handle`, matching the handle wire format:
  * `{ [handleName]: { [segmentId]: pushedValues[] } }` (each segment accumulates
@@ -218,6 +219,14 @@ export interface RenderRouteOptions {
      * expect(getByTestId("nonce").textContent).toBe("test-nonce");
      */
     nonce?: string;
+    /**
+     * Router default prefetch strategy scoped to this rendered tree. This mirrors
+     * `createRouter({ defaultPrefetch })` for Links and eligible plain anchors
+     * inside `basename`. `data-prefetch="false"`/`"none"` opts out; `"true"`
+     * allows an application route with a common static-resource suffix but does
+     * not override a `"none"` default.
+     */
+    defaultPrefetch?: PrefetchStrategy;
 }
 /**
  * Imperative handle returned alongside the RTL result.

package/dist/types/testing/shell-status.d.ts

@@ -27,13 +27,14 @@
  * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
  * (Playwright — same pure helpers, no Vite virtuals).
  */
+import { type CacheSearchParams } from "../cache/search-params-filter.js";
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export declare const SHELL_STATUS_HEADER: string;
 /** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
 export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
-declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "stale-build-entry"];
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
 /** Bounded reasons a PPR partial request can fall open to ordinary matching. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /** Parsed `x-rango-ppr-replay` value. */
@@ -55,9 +56,11 @@ export type ShellStatusTarget = Response | {
  * module (it pulls React). A parity test pins the two implementations.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
- * resolve against `http://localhost`).
+ * resolve against `http://localhost`). Pass the router's `cache.searchParams`
+ * config as `searchParams` when the app under test sets one — the production
+ * key applies it, so the expected key must too.
  */
-export declare function shellCacheKey(url: URL | string): string;
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

package/dist/types/vite/plugin-types.d.ts

@@ -236,7 +236,7 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
  * `.vc-config.json` (and `config.json` for `functionName`).
  */
 export interface VercelPresetOptions {
-    /** Node runtime for the function. @default "nodejs22.x" */
+    /** Node runtime for the function. @default "nodejs24.x" */
     runtime?: string;
     /** Max execution time in seconds. @default 30 */
     maxDuration?: number;