@rangojs/router 0.1.0 → 0.2.0

package/dist/types/router/segment-resolution/view-transition-default.d.ts

@@ -20,9 +20,8 @@ import type { EntryData } from "../../server/context";
  * gate, which also avoids needless object allocation and payload growth.
  *
  * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache) and recorded on the request
- * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
- * outside any cache scope — and drop this segment's transition when it returns
- * false. Used by both the fresh and revalidation resolution paths.
+ * function cannot cross Flight or the segment cache). PPR routes evaluate it
+ * from the manifest before the pipeline; other routes record it here for the
+ * existing post-handler gate. Used by both fresh and revalidation resolution.
  */
 export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];

package/dist/types/router/transition-when.d.ts

@@ -0,0 +1,13 @@
+import { type EntryData } from "../server/context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+export type TransitionWhenErrorReporter = (error: unknown, segmentId: string) => void;
+export declare function createTransitionWhenContext<TEnv>(ctx: RequestContext<TEnv>, target?: {
+    params: Record<string, string>;
+    routeName?: string;
+}): TransitionWhenContext<Record<string, string>, TEnv>;
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export declare function evaluatePprTransitionWhen<TEnv>(entries: EntryData[], ctx: RequestContext<TEnv>, target: {
+    params: Record<string, string>;
+    routeName?: string;
+}, reportError: TransitionWhenErrorReporter): void;

package/dist/types/rsc/handler-context.d.ts

@@ -13,6 +13,7 @@ import type { SSRStreamMode } from "../router/router-options.js";
 export interface HandlerContext<TEnv = unknown> {
     router: RangoInternal<TEnv, any>;
     version: string;
+    devDiscoveryEpoch?: number;
     renderToReadableStream: RSCDependencies["renderToReadableStream"];
     decodeReply: RSCDependencies["decodeReply"];
     createTemporaryReferenceSet: RSCDependencies["createTemporaryReferenceSet"];

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

@@ -39,8 +39,9 @@ export interface RscRenderStageTracking {
     /** Whole-render span receiving low-cardinality current/error phase attrs. */
     span?: TraceSpan;
 }
+type RscRenderContext<TEnv> = Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError" | "devDiscoveryEpoch">;
 export interface RscRenderInput<TEnv> {
-    ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+    ctx: RscRenderContext<TEnv>;
     request: Request;
     url: URL;
     env: TEnv;
@@ -51,7 +52,7 @@ export interface RscRenderInput<TEnv> {
     tracking?: RscRenderStageTracking;
 }
 export interface RscFlightStageInput<TEnv> {
-    ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+    ctx: RscRenderContext<TEnv>;
     request: Request;
     url: URL;
     env: TEnv;

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

@@ -9,15 +9,10 @@ import { getRequestContext } from "../server/request-context.js";
 import type { HandlerContext } from "./handler-context.js";
 export declare function handleRscRendering<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, isPartial: boolean, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], nonce: string | undefined): Promise<Response>;
 /**
- * Neutralize the shell-HIT degradation redirect target.
- *
- * The inline `location.replace` emitted by serveShellHit when a shell HIT lands
- * on a URL whose route became redirecting mid-TTL is a document-native redirect
- * exit that BYPASSES the 3xx chokepoint (guardOutgoingRedirect acts only on 3xx
- * + Location responses, never a committed 200 body). So it reuses the ONE
- * same-origin resolver directly: a cross-origin/unparseable/unsafe target
- * neutralizes to the same safe same-origin landing as redirect-guard.ts
- * (basename root, or "/" when unset) rather than navigating the user off-host.
- * A safe same-origin/relative target passes through as its normalized href.
+ * Neutralize the shell-HIT degradation redirect target. The inline
+ * `location.replace` in a committed 200 body bypasses the 3xx chokepoint
+ * (guardOutgoingRedirect only sees 3xx + Location), so this reuses the same
+ * same-origin resolver directly: unsafe targets neutralize to the
+ * redirect-guard.ts landing instead of navigating the user off-host.
  */
 export declare function resolveShellHitRedirectTarget(rawTarget: string, requestOrigin: string, basename: string | undefined): string;

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

@@ -148,6 +148,8 @@ export interface ShellCaptureDebugEvent {
     snapshotBytes?: number;
     /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
     snapshotSkipped?: boolean;
+    /** Outcome reported by a store that supports shell-write acknowledgements. */
+    storeWrite?: "stored" | "invalidated";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */
@@ -308,13 +310,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-interface CaptureAttemptStats {
-    barrierWaitMs?: number;
-    writeSettleMs?: number;
-    preludeBytes?: number;
-    snapshotBytes?: number;
-    snapshotSkipped?: boolean;
-}
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "storeWrite">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -369,6 +365,6 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
  * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
  * reaches reportCacheError and is NOT retried.
  */
-declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
+declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats, captureStartedAt?: number): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
 export { runShellCapture, captureAndStoreShell, delay, SHELL_CAPTURE_RETRY_DELAY_MS, };
 export { isCaptureBackedOff, markCaptureBackoff, clearCaptureBackoff, REFUSED_CAPTURE_BASE_MS, REFUSED_CAPTURE_MAX_MS, REFUSED_CAPTURE_DEV_MAX_MS, };

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

@@ -19,6 +19,8 @@ import { type EntryData } from "../server/context.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export declare const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.

package/dist/types/rsc/transition-gate.d.ts

@@ -4,24 +4,20 @@ import type { OnErrorCallback } from "../types/error-types.js";
 /**
  * Apply transition({ when }) gates to a payload's segments.
  *
- * The predicates were collected during resolution (keyed by segment id) and
- * stripped from the serialized config; here — after handlers ran and outside any
- * cache scope — we evaluate each and drop the segment's transition when the
- * predicate does not hold, so the navigation streams its loading fallback
- * instead of holding the previous content. A predicate that throws is reported
- * to the router's onError (phase "rendering") and then treated as "do not hold"
- * (conservative), so a buggy predicate degrades to no transition rather than
- * failing the response.
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
  *
  * Mutating the segments here is safe: the segment cache stores a serialized copy
  * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. The flip side is that a cache hit
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
  * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate) — combining transition({ when })
- * with cache() on the same segment freezes the gate to its cached state, so
- * avoid caching a route whose transition decision is request-dependent.
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
  *
- * Returns the same array (mutated) for inline use at the payload's `segments`
- * field.
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
  */
 export declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

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

@@ -41,6 +41,8 @@ export interface RscPayload {
         handles?: AsyncGenerator<HandleData, void, unknown>;
         /** RSC version string for cache invalidation */
         version?: string;
+        /** Cloudflare dev worker generation used for stale-document convergence. */
+        devDiscoveryEpoch?: number;
         /** TTL in milliseconds for the client-side in-memory prefetch cache */
         prefetchCacheTTL?: number;
         /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */

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

@@ -248,6 +248,10 @@ interface HelperContext {
     counters: Record<string, number>;
     forRoute?: string;
     mountIndex?: number;
+    /** Owning router id, when known (threaded by generateManifestFull). Scopes
+     *  the search-schema/root-scope registries so same-named routes in
+     *  different routers don't clobber each other (route-map-builder.ts). */
+    routerId?: string;
     metrics?: MetricsStore;
     /** True when rendering for SSR (document requests) */
     isSSR?: boolean;
@@ -337,6 +341,18 @@ export declare function getNamePrefix(): string | undefined;
  * Returns true at root or inside { name: "" } includes, false inside named includes.
  */
 export declare function getRootScoped(): boolean;
+/**
+ * Stamp build-time scope identity onto a Static() definition at mount time.
+ * The bake collector (prerender-collection.ts) renders defs OUTSIDE any
+ * evaluation scope and used to iterate the registry first-non-null, so these
+ * are the ONLY reliable carriers of the def's owning router, root-scope, and
+ * full route name — a name-keyed registry lookup at bake time reproduces the
+ * cross-router collision #757/#762 fixed (and the collector's historical
+ * `$$routePrefix` argument is a name PREFIX, which the root-scope registry
+ * never contains, silently degrading to the dot-heuristic).
+ * A definition mounted more than once is stamped each time; the last mount wins.
+ */
+export declare function stampStaticDefScope(handler: unknown, routeName?: string): void;
 export type { HelperContext };
 /**
  * Return an isolated copy of a lazy include's captured parent entry.

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

@@ -141,6 +141,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         id: string;
         when: TransitionWhenFn;
     }>;
+    /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+    _pprTransitionDecisions?: Map<string, boolean>;
     /** @internal Cache store for segment caching (optional, used by CacheScope) */
     _cacheStore?: SegmentCacheStore;
     /**
@@ -180,21 +182,30 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _shellLoaderSeed?: Map<string, import("../cache/shell-snapshot.js").ShellLoaderSeedEntry>;
     /**
-     * @internal Shell fast-path marker: makes the NEXT full match treat the whole
-     * matched route as an implicit doc-level cache() boundary (see
+     * @internal Shell fast-path marker: makes the next eligible match treat the
+     * whole matched route as an implicit doc-level cache() boundary (see
      * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
      * (a) the capture's derived context — with a record-only store so the
      * capture's cacheRoute write lands in the snapshot, never the real store —
-     * and (b) a HIT tail's seeded context when the entry is eligible
-     * (!handlerLiveHoles), where the SeededShellStore serves the recorded doc
-     * entry and the match skips handler execution entirely. Routes with their
-     * own cache() config (including cache(false)) are never overridden: the
-     * marker only applies when the route tree derived NO cache scope.
+     * (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.
      */
     _shellImplicitCache?: {
         ttl?: number;
         swr?: number;
         store?: SegmentCacheStore;
+        /**
+         * @internal Override the implicit scope's default cache namespace. Shell
+         * captures and navigation replay both consume the canonical document
+         * segment record even when the triggering request is partial.
+         */
+        keyPrefix?: "doc";
+        /** @internal Called only after the implicit cache hit decodes successfully. */
+        onHit?: () => void;
     };
     /**
      * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
@@ -484,6 +495,9 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _tracing?: ResolvedTracing;
     /** @internal Router basename for this request (used by redirect()) */
     _basename?: string;
+    /** @internal Owning router id; scopes the search-schema/root-scope registry
+     *  lookups per router (route-map-builder.ts) */
+    _routerId?: string;
     /**
      * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
      * to avoid a second resolveRoute call. Cleared on HMR invalidation.
@@ -504,7 +518,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" | "_cacheStore" | "_shellCaptureRun" | "_shellFragmentPayload" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_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" | "_basename" | "_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" | "_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">;
 /**
  * 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

@@ -9,7 +9,7 @@
  */
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 export { HostRouterRegistry, type HostRouterRegistryEntry, } from "./host/router.js";
-export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRouterData, getGlobalRouteMap, getRouterManifest, setPrecomputedEntries, setRouteTrie, setManifestReadyPromise, setRouterManifest, setRouterTrie, setRouterPrecomputedEntries, registerRouterManifestLoader, ensureRouterManifest, } from "./route-map-builder.js";
+export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRouterData, getGlobalRouteMap, getRouterManifest, setManifestReadyPromise, setRouterManifest, setRouterTrie, setRouterPrecomputedEntries, registerRouterManifestLoader, ensureRouterManifest, } from "./route-map-builder.js";
 export { registerLoaderById, setLoaderImports, } from "./server/loader-registry.js";
 export { createRequestContext, type CreateRequestContextOptions, } from "./server/request-context.js";
 export { isClientComponent, assertClientComponent } from "./component-utils.js";

package/dist/types/testing/e2e/index.d.ts

@@ -4,7 +4,7 @@ import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent,
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
 export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {

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

@@ -44,8 +44,8 @@ export type { DispatchOptions } from "./dispatch.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
 export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
 export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
-export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
+export type { PprReplayBypassReason, PprReplayStatus, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
 export { collectHandle } from "./collect-handle.js";
 export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
 export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";

package/dist/types/testing/run-transition-when.d.ts

@@ -1,10 +1,9 @@
 /**
  * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
  *
- * Runs the SAME two server functions the router uses — applyViewTransitionDefault
- * (strips the `when` function from the serialized config and records the
- * predicate on the request context) and gateTransitions (assembles the
- * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * Runs the SAME server functions the router uses — the PPR pre-handler evaluator
+ * when `ppr: true`, applyViewTransitionDefault (which strips the server-only
+ * function), and gateTransitions. So the
  * predicate sees exactly the navigation/action metadata it would at runtime
  * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
  * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
@@ -39,7 +38,7 @@ export interface RunTransitionWhenOptions<TEnv = any> {
     toRouteName?: string;
     /** Environment bindings surfaced as `env` (and `ctx.env`). */
     env?: TEnv;
-    /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+    /** Variables readable via the predicate's `get()`. With `ppr`, these model pre-handler middleware/input state. */
     vars?: VarsInit;
     /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
     currentUrl?: string | URL;
@@ -57,6 +56,8 @@ export interface RunTransitionWhenOptions<TEnv = any> {
     formData?: FormData;
     /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
     onError?: OnErrorCallback;
+    /** Model a route with `ppr`, where the predicate runs before route handlers and cache lookup. */
+    ppr?: boolean;
 }
 /**
  * Result of runTransitionWhen.

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

@@ -2,7 +2,8 @@
  * PPR shell-status testing primitives for @rangojs/router consumers.
  *
  * Companion to `cache-status.ts` (segment/document cache): this module covers
- * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`).
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`) and
+ * partial-navigation segment replay (`x-rango-ppr-replay: HIT`).
  *
  * ## Spike conclusions (plan 009)
  *
@@ -11,8 +12,9 @@
  *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
  *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
  *
- * 2. **Smallest HIT signal:** response header `x-rango-shell` (`HIT` | `MISS`),
- *    always on document GETs to a ppr route that the serve path considered.
+ * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
+ *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
+ *    HIT is reported only when matching consumes the captured segment record.
  *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
  *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
  *
@@ -27,8 +29,21 @@
  */
 /** 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"];
+/** 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. */
+export type PprReplayStatus = {
+    outcome: "HIT";
+    freshness: "fresh" | "stale";
+} | {
+    outcome: "BYPASS";
+    reason: PprReplayBypassReason;
+};
 /** A target carrying response headers (a Response or a `{ headers }` object). */
 export type ShellStatusTarget = Response | {
     headers: Headers;
@@ -56,3 +71,8 @@ export declare function parseShellStatus(target: ShellStatusTarget): ShellStatus
  * invent a HIT Response in unit tests — that fakes the serve path.
  */
 export declare function assertShellStatus(target: ShellStatusTarget, expected: ShellStatus): void;
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export declare function parsePprReplayStatus(target: ShellStatusTarget): PprReplayStatus | null;
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export declare function assertPprReplayStatus(target: ShellStatusTarget, expected: PprReplayStatus): void;
+export {};

package/dist/types/types/route-entry.d.ts

@@ -9,6 +9,9 @@ export interface LazyIncludeContext {
     cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
     /** Root scope flag for dot-local reverse resolution */
     rootScoped?: boolean;
+    /** Owning router id; scopes search-schema/root-scope registration during
+     *  lazy include evaluation (route-map-builder.ts registries) */
+    routerId?: string;
     /**
      * Positional include scope token composed from the parent scope plus this
      * include's sibling index (`${parentScope}I${idx}`). Applied to direct-

package/dist/types/types/segments.d.ts

@@ -12,11 +12,12 @@ export type ViewTransitionClass = Record<string, string> | string;
  *
  * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
  * gets — the same navigation/action metadata — so the two read the same shape,
- * plus `get`/`env` for post-handler reads. There is no full `HandlerContext`
+ * plus `get`/`env` for request-context reads. There is no full `HandlerContext`
  * here: the gate runs at the RSC-payload layer with the request context, not a
  * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
- * absent by design. `get` is the way to read what the handler/middleware set
- * via `ctx.set(...)` this request.
+ * absent by design. On ordinary routes, `get` can read what handlers or
+ * middleware set via `ctx.set(...)`. On `ppr` routes the gate runs before route
+ * handlers, so only middleware-established values are available.
  *
  * Field availability (all source fields are optional — never fabricated):
  * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
@@ -41,27 +42,30 @@ export type ViewTransitionClass = Record<string, string> | string;
  * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
  * prefetch fired from, NOT necessarily the page the user actually navigates from
  * — the decision is baked into the stored Flight payload and replayed verbatim.
- * A `cache()`/prerender hit replays the stored transition with the predicate NOT
- * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
- * or store-time state. This is accepted (~99% of navigations match), but if your
- * gate must reflect the exact click-time source, source-scope the prefetch
- * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ * A non-PPR `cache()`/prerender hit replays the stored transition with the
+ * predicate NOT re-run. A `ppr` route instead evaluates the predicate before
+ * handlers on every match, including cache, prerender, and PPR replay. Prefetch
+ * still freezes the server decision into its Flight payload. If the gate must
+ * reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`).
  */
 export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unknown> = Partial<Pick<RevalidateParams<TParams, TEnv>, "currentUrl" | "currentParams" | "fromRouteName">> & Pick<RevalidateParams<TParams, TEnv>, "nextUrl" | "nextParams" | "toRouteName" | "actionId" | "actionUrl" | "actionResult" | "formData" | "method"> & Pick<HandlerContext<any, TEnv>, "get" | "env">;
 /**
  * Predicate that gates whether a transition() applies for the current request.
  *
- * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
- * handler/middleware-set state) and outside any cache scope. Return false to
- * drop this segment's transition for the request; return true to apply it. The
+ * Evaluated server-side outside any cache scope. On ordinary routes it runs
+ * AFTER the route's handler, so `get(...)` can read handler/middleware state. A
+ * route with `ppr` automatically hoists it before route handlers and reevaluates
+ * it on every cache/prerender/PPR replay; there `get(...)` can read middleware
+ * state, but not values set by route handlers. Return false to drop this
+ * segment's transition for the request; return true to apply it. The
  * context ({@link TransitionWhenContext}) carries the same navigation/action
  * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
  * error is reported to the router's onError (phase "rendering") and the
  * transition is dropped (the navigation does not hold).
  *
  * Distinct from intercept()'s `when` config selector, which runs at MATCH time
- * over `{ from, to, params, segments, … }`; a transition `when` runs
- * post-handler over the resolved payload.
+ * over `{ from, to, params, segments, … }`.
  *
  * Scope: dropping a transition removes only THIS segment's contribution to the
  * navigation's hold. The startTransition hold is navigation-wide — it engages if
@@ -69,10 +73,10 @@ export type TransitionWhenContext<TParams = Record<string, string>, TEnv = unkno
  * navigation stream its loading fallback only when no other matched segment
  * keeps a transition (the common case: a single transition on the route).
  *
- * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
- * segment is replayed from the runtime cache or a build-time prerender, and a
- * prefetched navigation freezes it to prefetch-time state — see the caveat on
- * {@link TransitionWhenContext}.
+ * On non-PPR routes it runs only during fresh resolution. On PPR routes it runs
+ * before handlers for every match, including runtime cache, build-time
+ * prerender, and PPR segment replay. A prefetched navigation still freezes the
+ * result to prefetch time; see {@link TransitionWhenContext}.
  */
 export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
 /**
@@ -105,11 +109,12 @@ export interface TransitionConfig {
     viewTransition?: "auto" | false;
     /**
      * Optional server-side predicate that gates this transition per request. When
-     * present and it returns false (evaluated post-handler), the router drops this
-     * segment's transition for the request, so the navigation streams its loading
-     * fallback instead of holding. The predicate is server-only and never
-     * serialized to the client; only its resolved effect (transition kept or
-     * dropped) crosses. See {@link TransitionWhenFn}.
+     * present and it returns false, the router drops this segment's transition for
+     * the request, so the navigation streams its loading fallback instead of
+     * holding. PPR routes evaluate it before route handlers and on every replay;
+     * other routes evaluate it after handlers on fresh resolution. The predicate
+     * is server-only and never serialized to the client; only its resolved effect
+     * crosses. See {@link TransitionWhenFn}.
      */
     when?: TransitionWhenFn;
 }

package/dist/types/urls/path-helper-types.d.ts

@@ -183,9 +183,10 @@ export type PathHelpers<TEnv> = {
      * transition cannot fire without a startTransition. See
      * skills/view-transitions for the startTransition x ViewTransition matrix.
      *
-     * Pass `when: (ctx) => boolean` to gate the transition per request: it runs
-     * server-side after the route handler (can read `ctx.get(...)`), and returning
-     * false drops the transition so the navigation streams its loading() skeleton.
+     * Pass `when: (ctx) => boolean` to gate the transition per request. It normally
+     * runs after the route handler; `ppr` routes automatically run it before route
+     * handlers and on every replay, where `ctx.get(...)` sees middleware state but
+     * not handler-set values.
      */
     transition: {
         (): TransitionItem;

package/dist/types/vite/discovery/state.d.ts

@@ -60,6 +60,7 @@ export interface ChunkInfo {
 export interface PerRouterManifestEntry {
     id: string;
     routeManifest: Record<string, string>;
+    routeTrailingSlash?: Record<string, string>;
     routeSearchSchemas?: Record<string, Record<string, string>>;
     sourceFile?: string;
     factoryOnlyPrefixes?: Set<string>;
@@ -103,8 +104,6 @@ export interface DiscoveryState {
     opts: PluginOptions | undefined;
     mergedRouteManifest: Record<string, string> | null;
     perRouterManifests: PerRouterManifestEntry[];
-    mergedPrecomputedEntries: PrecomputedEntry[] | null;
-    mergedRouteTrie: any;
     perRouterTrieMap: Map<string, any>;
     perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
     perRouterManifestDataMap: Map<string, Record<string, string>>;
@@ -137,6 +136,8 @@ export interface DiscoveryState {
     resolvedPrerenderModules: Map<string, string[]> | undefined;
     resolvedStaticModules: Map<string, string[]> | undefined;
     discoveryDone: Promise<void> | null;
+    /** Monotonic Cloudflare-dev generation installed by the routes manifest. */
+    devDiscoveryEpoch?: number;
     devServerOrigin: string | null;
     devServer: any;
     selfWrittenGenFiles: Map<string, {

package/dist/types/vite/utils/manifest-utils.d.ts

@@ -1,4 +1,4 @@
-export { flattenLeafEntries, buildRouteToStaticPrefix, } from "../../build/prefix-tree-utils.js";
+export { flattenLeafEntries } from "../../build/prefix-tree-utils.js";
 /**
  * Wrap a value as `JSON.parse('...')` instead of a JS object literal.
  * V8's JSON parser is significantly faster than its full JS parser for large