@rangojs/router 0.16.0 → 0.18.0

package/dist/types/router/error-handling.d.ts

@@ -42,10 +42,30 @@ export interface InvokeOnErrorContext<TEnv = any> {
  * @param logPrefix - Prefix for console.error messages (e.g., "Router" or "RSC")
  */
 export declare function invokeOnError<TEnv = any>(onError: OnErrorCallback<TEnv> | undefined, error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>, logPrefix?: string): void;
+/**
+ * First non-undefined `pick(orphan)` over the routeless entries in
+ * `entry.layout` and, recursively, in theirs: depth-first in render order
+ * (resolveOrphanLayout in segment-resolution/fresh.ts). Since #922 a routeless
+ * entry nested in another renders (a layout() after a bare cache() marker, a
+ * layout() in a routeless wrapper); a one-level scan missed the boundaries and
+ * intercepts it declares (#926).
+ *
+ * `skip` is the entry an upward walk came from. Only a bare cache() marker is
+ * both in its layout's layout[] and in the chain, and its subtree was already
+ * scanned at its chain position.
+ */
+export declare function findInOrphans<T>(entry: EntryData, pick: (orphan: EntryData) => T | undefined, skip?: EntryData | null): T | undefined;
+/** `findInOrphans` pick: the orphan when it declares an errorBoundary(). */
+export declare const withErrorBoundary: (entry: EntryData) => EntryData | undefined;
 /**
  * Find the nearest error boundary by walking up the entry chain
  * Also checks sibling layouts (orphan layouts) for error boundaries
  * Returns the first fallback found, or the default error boundary if configured
+ *
+ * An orphan's parent is null, so from an orphan the walk continues at its
+ * orphanOwner (EntryData). Without that step, errors from an intercept declared
+ * in a routeless layout, or from that layout's loaders, stopped at the orphan
+ * and skipped every ancestor boundary (#898).
  */
 export declare function findNearestErrorBoundary(entry: EntryData | null, defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler): ReactNode | ErrorBoundaryHandler | null;
 /**

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

@@ -4,6 +4,12 @@
  * Creates the handler context object passed to route handlers, middleware, and loaders.
  */
 import type { InternalHandlerContext } from "../types";
+/**
+ * `headers` whose mutating methods run `assertWrite(method)` first. Shared by
+ * the handler ctx (createHandlerContext) and the middleware ctx
+ * (createMiddlewareContext).
+ */
+export declare function guardHeaderWrites(headers: Headers, assertWrite: (method: string | symbol) => void): Headers;
 /**
  * Strip internal _rsc* query params from a URL.
  * Returns a new URL with only user-facing params.

package/dist/types/router/instrument.d.ts

@@ -163,6 +163,14 @@ export declare function observePhase<T>(spec: PhaseSpec, fn: (span: TraceSpan) =
  * nothing to record here and short-circuits.
  */
 export declare function observeHandler<C, R>(id: string, handler: (ctx: C) => R, ctx: C): R;
+/**
+ * observeHandler, inside segment `segmentId`'s tag scope, so the tags the
+ * handler records reach the route's cache() record (#957, cache-tag.ts
+ * runInSegmentTagScope). `spanId` is observeHandler's `id`. A request that
+ * cannot write a record takes observeHandler's path as is, with the same one
+ * request-context read: no scope, no closure.
+ */
+export declare function observeSegmentHandler<C, R>(segmentId: string, spanId: string, handler: (ctx: C) => R, ctx: C): R;
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

package/dist/types/router/match-middleware/background-revalidation.d.ts

@@ -82,13 +82,13 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * Background revalidation creates fully isolated context:
- *   - Fresh handleStore (prevents polluting the response stream)
+ * Background revalidation re-renders through rerenderAndCacheRoute (shared
+ * with proactive caching in cache-store.ts):
+ *   - Derived request context with its own handleStore, transition({ when })
+ *     predicates and no perf metrics (the shared fields are never touched;
+ *     the foreground is still producing the page)
  *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
  *     loader results from the foreground pass)
- *   - handleStore is saved/restored in try/finally
- *
- * This matches the proactive caching pattern in cache-store.ts.
  *
  *
  * FRESH RESOLUTION (NO REVALIDATION)
@@ -101,7 +101,48 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { type RouterContext } from "../router-context.js";
+import type { CacheScope } from "../../cache/cache-scope.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
+import { type RequestContext } from "../../server/request-context.js";
+/**
+ * Re-render a cached route in the background and write it with
+ * cacheScope.cacheRoute: the stale-hit refresh below and proactive caching
+ * (cache-store.ts). Returns the number of segments written.
+ *
+ * A render whose status is not 200 (an error or notFound boundary resolved)
+ * is not written and returns 0, as a non-200 MISS is not cached
+ * (cache-store.ts): the entry it would replace keeps serving until a later
+ * refresh succeeds or it expires. Nothing is held in process; a store's own
+ * revalidation marker (CFCacheStore's REVALIDATING) re-arms after
+ * MAX_REVALIDATION_INTERVAL, as after a refresh that throws.
+ *
+ * Runs on a DERIVED request context that owns the per-render state the
+ * foreground reads while it is still producing the page (a stale HIT re-runs
+ * its loaders; a proactive render starts once the Response exists, while its
+ * body streams):
+ *   - _handleStore: read late (loader pushes and aux-lane tracking in
+ *     loader-resolution.ts, nested cache restores and captures in
+ *     cache-scope.ts), so a swap sent live pushes into this render.
+ *     setupLoaderAccess binds the store at setup, so it runs inside the
+ *     derived context too.
+ *   - _transitionWhen: fresh resolution appends transition({ when })
+ *     predicates; the foreground's gateTransitions reads the array after the
+ *     match, and a stale HIT (which replays the stored transition) must not
+ *     evaluate this render's predicates.
+ *   - _metricsStore: undefined, and the DSL store below has `metrics` unset
+ *     (track() reads that one), so nothing lands on the foreground's perf
+ *     timeline. ctx.Store.run closes over ctx.Store, so the derived store
+ *     needs its own run.
+ *   - response writes (headers, cookies, status, onResponse callbacks) go to
+ *     a throwaway context (whose status gates the write, above) and are
+ *     dropped: a layout above the cache() boundary is outside the header
+ *     guard and an error boundary sets a status, so they would otherwise
+ *     reach the live response.
+ * runWithRequestContext also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses; the DSL store is a different ALS (build context).
+ */
+export declare function rerenderAndCacheRoute<TEnv>(ctx: MatchContext<TEnv>, requestCtx: RequestContext<TEnv>, cacheScope: CacheScope, routerCtx: RouterContext<TEnv>): Promise<number>;
 /**
  * Creates background revalidation middleware
  *

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

@@ -1,6 +1,6 @@
 import type { ContextVar } from "../context-var.js";
 import type { DefaultReverseRouteMap, DefaultRouteName, DefaultVars } from "../types/global-namespace.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
@@ -48,10 +48,16 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
     header(name: string, value: string): void;
     routeName?: DefaultRouteName;
     debugPerformance(): void;
-    theme?: Theme;
+    /**
+     * The visitor's theme (cookie or default); undefined without theme config.
+     * Guarded like `cookies()`: a read inside a `"use cache"` function throws
+     * (#971).
+     */
+    readonly theme?: Theme;
     setTheme?: (theme: Theme) => void;
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
-    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+    /** Global route names only; see {@link GlobalReverseFunction}. */
+    reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
 }
 export type MiddlewareFn<TEnv = any, TParams = Record<string, string | undefined>> = (ctx: MiddlewareContext<TEnv, TParams>, next: () => Promise<Response>) => Response | void | Promise<Response | void>;
 export interface MiddlewareEntry<TEnv = any> {

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

@@ -49,7 +49,9 @@ export interface RouterContext<TEnv = any> {
     getMetricsStore: () => MetricsStore | undefined;
     createCacheScope: (cacheConfig: any, parent: CacheScope | null) => CacheScope | null;
     findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext, isAction: boolean) => InterceptResult | null;
-    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: any | undefined, interceptResult: InterceptResult | null, localRouteName: string, pathname: string, stale?: boolean) => Promise<{
+    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, handlerContext: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: any | undefined, interceptResult: InterceptResult | null, localRouteName: string, pathname: string, stale?: boolean, 
+    /** The matched route's full chain when `entries` is part of it (ResolveSegmentOptions.chain). */
+    chain?: readonly EntryData[]) => Promise<{
         segments: ResolvedSegment[];
         matchedIds: string[];
     }>;

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

@@ -137,6 +137,22 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```
      */
     readonly routeMap: TRoutes;
+    /**
+     * Serialize the route manifest for inspection: every route and layout the
+     * router's `.routes()` / `urls` mounts register, with shortCodes, parent
+     * links, and loader/middleware/error-boundary/parallel/intercept flags.
+     *
+     * Server-only development aid. It re-evaluates each mount's `urls()` tree.
+     * Groups mounted with `include()` are lazy and are not expanded: their
+     * routes are absent from the result.
+     *
+     * @example
+     * ```typescript
+     * const manifest = await router.debugManifest();
+     * console.log(manifest.totalRoutes, Object.keys(manifest.routes));
+     * ```
+     */
+    debugManifest(): Promise<SerializedManifest>;
     /**
      * Handle an RSC request.
      *
@@ -147,7 +163,13 @@ export interface Rango<TEnv = any, TRoutes extends Record<string, unknown> = Rec
      * ```tsx
      * import { router } from "./router";
      *
-     * export default { fetch: router.fetch };
+     * // Workers call fetch(request, env, ctx); `{ fetch: router.fetch }` would
+     * // drop env and ctx.
+     * export default {
+     *   fetch(request, env, ctx) {
+     *     return router.fetch(request, { env, ctx });
+     *   },
+     * } satisfies ExportedHandler;
      * ```
      *
      * @example Direct export
@@ -238,7 +260,7 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
     readonly notFound?: RangoOptions<TEnv>["notFound"];
     /**
      * Resolved theme configuration (null if theme not enabled)
-     * Used by NavigationProvider to include ThemeProvider and by MetaTags to render theme script
+     * Used by NavigationProvider to include ThemeProvider and by `Html.Meta` to render theme script
      */
     readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
     /**

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

@@ -146,8 +146,10 @@ export interface RangoOptions<TEnv = any> {
      *
      * Must be a client component ("use client") that accepts { children }.
      *
-     * If not provided, a default document with basic HTML structure is used:
-     * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+     * If not provided, a default document is used: `Html.Meta` and `Html.Scripts`
+     * in `<head>`, `Html.Scripts position="body"` before `{children}` and
+     * `Html.ScrollRestoration` after it. Pass your own to set `getKey` or to
+     * leave back/forward scrolling to the browser.
      *
      * @example
      * ```typescript
@@ -181,7 +183,8 @@ export interface RangoOptions<TEnv = any> {
     defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
     /**
      * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
-     * If not provided, DataNotFoundError will be treated as a regular error
+     * If not provided, notFound() renders the `notFound` option, else a plain
+     * `<h1>Not Found</h1>` (status 404)
      */
     defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
     /**
@@ -190,7 +193,7 @@ export interface RangoOptions<TEnv = any> {
      * This is rendered within your document/app shell with a 404 status code.
      * Use this for a custom 404 page that maintains your app's look and feel.
      *
-     * If not provided, a default "Page not found" component is rendered.
+     * If not provided, a plain `<h1>Not Found</h1>` is rendered.
      *
      * Can be a static ReactNode or a function receiving the pathname.
      *
@@ -337,7 +340,7 @@ export interface RangoOptions<TEnv = any> {
      * When provided, enables:
      * - ctx.theme and ctx.setTheme() in route handlers
      * - useTheme() hook for client components
-     * - FOUC prevention via inline script in MetaTags
+     * - FOUC prevention via inline script in `<Html.Meta />`
      * - Automatic ThemeProvider wrapping in NavigationProvider
      *
      * @example

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

@@ -27,6 +27,16 @@ export interface ResolveSegmentOptions {
      * so error boundaries keep catching at request time.
      */
     throwOnError?: boolean;
+    /**
+     * The matched route's full entry chain. resolveAllSegments defaults it to
+     * its `entries`; withCacheLookup passes it when it resolves only the entries
+     * above a cache() boundary. An orphan list can hold an entry of the chain: a
+     * bare cache() marker sits in its layout's layout[] (it wraps that layout's
+     * routes) and is the parent of the routes after it. For those routes it
+     * resolves once, as a chain entry, below the cache() header latch (issue
+     * #918: resolved twice on a MISS, once and discarded on a HIT).
+     */
+    chain?: readonly EntryData[];
 }
 /**
  * Resolve segments from EntryData.

package/dist/types/router/segment-resolution/loader-cache.d.ts

@@ -16,9 +16,40 @@
  * On hit: returns cached data directly, skips loader execution.
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
+ *
+ * Identity (#972): without a key() or a store keyGenerator the entry is
+ * shared across users, so a fill whose execution recorded a request-identity
+ * read fails and is not stored, whoever started that execution
+ * (server/context.ts recordLoaderIdentityRead).
+ *
+ * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
+ * the HIT must reproduce: the MISS records the pushes of the body and of the
+ * loaders it awaits via ctx.use into the entry's `handles` blob (the
+ * "use cache" capture/encode), and every HIT — stale included — replays
+ * them, each loader's pushes at most once per request (a dependency another
+ * reader already ran keeps its live pushes). See replayLoaderHandles.
+ *
+ * Tags too (#964): the entry stores its cache() tags plus every tag its
+ * execution recorded, those of the loader values it read included
+ * (cache-tag.ts "Recorded-tag sets"), so updateTag() of any of them drops it.
+ * Every HIT records the stored tags through the loader's tag owner
+ * (recordLoaderTags), so a route cache() record, PPR shell or document built
+ * over the HIT carries them, and a loader that reads this one takes them on.
+ * Once the binding started, a loader body's ctx.use of it gets the same
+ * dataPromise as a handler read (createLoaderExecutor's useLoader); a stale
+ * refresh does not (setupLoaderAccess _runLoaderIsolated).
  */
-import type { LoaderEntry } from "../../server/context.js";
+import { type EntryData, type LoaderEntry } from "../../server/context.js";
 import type { HandlerContext } from "../../types.js";
+/**
+ * Whether a request over the matched chain `entries` resolves a loader bound
+ * with its own cache(): on a chain entry, or on its parallel slots, orphan
+ * layouts or intercepts. The match arms the per-execution loader tag sets on
+ * it (cache-tag.ts armLoaderTagSets), before any loader starts, so a
+ * dependency the handler or another binding starts first still records.
+ * Memoized per entry.
+ */
+export declare function bindsLoaderCache(entries: readonly EntryData[]): boolean;
 /**
  * Resolve loader data with optional caching.
  *
@@ -29,5 +60,39 @@ import type { HandlerContext } from "../../types.js";
  * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
  * so it emits no loader phase (the loader did not execute; the hit is only a
  * LoaderCache debug log).
+ *
+ * PPR loader lane rule — the canonical source statement; other sites point
+ * here (consumer docs: skills/ppr/SKILL.md "The loader lane rule";
+ * docs/design/loader-container-bake.md). This is the single funnel every
+ * loader segment path routes through (fresh resolveLoaders, cache-hit
+ * resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation, and
+ * intercept loaders in intercept-resolution.ts, which pass no bake key and
+ * never run under a shell capture), so the lane is decided here, per LOADER,
+ * never by the entry's loading():
+ *
+ * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ *   caller passes a `bakeSegmentKey` for it on document and navigation
+ *   evaluations alike; a capture, a document evaluation, also has
+ *   awaitBeforeFlush). The loader EXECUTES at capture (the
+ *   flag's "data in the HTML before first flush" maps to the frozen prelude)
+ *   and its settled non-promise data bakes into the shell. Promises nested in
+ *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
+ *   live holes at the consumer's own Suspense — per-request material must be
+ *   promise-shaped (the #692 cross-session scar). The masked container
+ *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
+ *   family, and on a HIT the recorded container is overlaid onto the fresh
+ *   run (below) so the payload matches the frozen prelude outside the holes.
+ *   A server-component element holding a promise is a hole as a whole, so its
+ *   other props come from the fresh run (loader-snapshot.ts
+ *   elideLoaderContainer). cookies()/headers() in its body (nested promise
+ *   bodies included) trip the capture guard.
+ * - LIVE lane: every other loader, whatever its entry's loading(). Never
+ *   executes at capture: the slot gets a never-resolving promise
+ *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
+ *   inline Suspense — then streams fresh per request. A masked read with NO
+ *   boundary above it root-postpones and the <body> sanity gate refuses the
+ *   shell (eternal-MISS warning). A route whose loaders are ALL `ssr: false`
+ *   needs no loading(): nothing masks.
  */
 export declare function resolveLoaderData<TEnv>(loaderEntry: LoaderEntry, ctx: HandlerContext<any, TEnv>, pathname: string, bakeSegmentKey?: string | null): Promise<any>;

package/dist/types/router/segment-resolution/loader-mask.d.ts

@@ -2,13 +2,10 @@
  * PPR shell-capture loader masking.
  *
  * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
- * route loaders are the "live lane": they must NOT execute — no side effects, no
- * cost, no cache round-trips. Instead every loader segment's value slot receives
- * a never-resolving promise, so the loader-consuming Suspense subtree stays
- * pending and React's static `prerender` marks it as a postponed hole. The frozen
- * shell (prelude) captures only the fallback; the resumed serve pass runs the
- * loaders fresh through the unchanged execution path and streams their output
- * into the holes.
+ * live-lane loaders (lane rule: see resolveLoaderData, loader-cache.ts) must
+ * NOT execute; their value slot gets a never-resolving promise so the
+ * consuming Suspense subtree postpones as a hole, and the serve pass runs them
+ * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
  * the derived request context of the background capture task (shell-capture.ts) —
@@ -28,17 +25,10 @@ import { type RequestContext } from "../../server/request-context.js";
 export declare function isShellCaptureActive(reqCtx?: RequestContext<any> | undefined): boolean;
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
- * Entry-level lane input for an entry's loaders under PPR (the loading()
- * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: an `ssr: false`
- * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
- * flag's document promise ("data in the HTML before first flush") maps to
- * the frozen prelude — while every other loader is LIVE (masked at capture,
- * fresh on every serve), postponing at loading() or an inline Suspense.
- * This helper still gates which entries pass a bake segment key for the
- * legacy loading()-less shape and the HIT-tail seed overlay.
- *
- * Mirrors segment-system's isRenderableLoading so the mask decision and the
- * tree's boundary placement can never disagree.
+ * True when the entry's loading() is renderable (mirrors segment-system's
+ * isRenderableLoading). Not the lane decision (lane rule: see
+ * resolveLoaderData, loader-cache.ts): callers only use it to decide whether
+ * an unflagged loader's segment key rides as the bake/seed key, which is inert
+ * at capture.
  */
 export declare function entryLoadingMasksLoaders(loading: unknown): boolean;

package/dist/types/router/segment-resolution/loader-snapshot.d.ts

@@ -2,11 +2,13 @@
  * Loader-family capture snapshot: elide + overlay for bake-lane loader
  * containers (docs/design/loader-container-bake.md).
  *
- * A loader on an entry with NO renderable loading() executes during shell
- * capture; its settled container bakes into the prelude while every promise
- * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
- * payload byte-identical to that frozen prelude, the capture pins the container
- * in the shell snapshot:
+ * A bake-lane loader (lane rule: see resolveLoaderData, loader-cache.ts)
+ * executes during shell capture; its settled container bakes into the prelude
+ * while nested promises postpone as holes. To keep a HIT's fresh payload in
+ * agreement with that frozen prelude, the capture pins the container in the
+ * shell snapshot. Everything outside a hole is pinned; the one exception is a
+ * server-component element holding a promise, which is a hole as a whole (see
+ * elideLoaderContainer):
  *
  *   - elide:   deep-walk the settled container; a PENDING nested promise is a
  *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
@@ -27,7 +29,8 @@
  *              storefront PDP regression) — and fresh-only paths pass through
  *              (they cannot contradict prelude bytes that never rendered them).
  */
-export { maskNestedContainerThenables } from "./mask-nested.js";
+import { maskNestedContainerThenables } from "./mask-nested.js";
+export { maskNestedContainerThenables };
 /**
  * Marker object standing in for a pending nested promise in a recorded loader
  * container. Shape-checked (not identity-checked) because the record round-trips
@@ -70,21 +73,29 @@ export type ElideResult = {
  * promises pin their value behind a settled marker (they baked, but consumers
  * hold a promise-shaped key); pending ones become hole markers; a REJECTED
  * nested promise poisons the record (error UI must never bake into a shared
- * shell) — the caller refuses the capture. Only plain objects/arrays are
- * traversed; anything else (Date, Map, class instance) is a pinned leaf.
- * Cycles are cut as pinned references (best effort — Flight rejects true
- * cycles later regardless).
+ * shell) — the caller refuses the capture. Plain data objects, arrays and the
+ * props of host, Suspense/Fragment and client-reference elements are
+ * traversed copy-on-write (an element through cloneElementWithProps); a shared
+ * subtree or a cycle resolves to the same elided result. An element Flight
+ * renders by calling user code (see rendersOnServer) is a leaf, or ONE hole
+ * marker when a thenable sits anywhere in its props: the pin encode calls that
+ * component, so a marker inside its props would reach it. Anything else
+ * (Date, Map, class instance, lazy node) is a pinned leaf.
  *
  * The ROOT container promise-chain unwraps with NO marker: loader-cache
  * overlays against the AWAITED fresh container, so the recorded root must be
  * the unwrapped structure. Everything below it goes through elideNested.
  */
-export declare function elideLoaderContainer(value: unknown, seen?: Set<object>): Promise<ElideResult>;
+export declare function elideLoaderContainer(value: unknown, seen?: Map<object, ElideResult>): Promise<ElideResult>;
 /**
  * Overlay a recorded (elided) container onto the fresh run's container for a
  * shell HIT. Recorded wins per path; hole markers take the fresh value (the
  * live nested promise); fresh-only object keys pass through. Where the shapes
  * disagree structurally, recorded wins wholesale — it is what the prelude
- * froze, and parity beats freshness inside the shell.
+ * froze, and parity beats freshness inside the shell. Copy-on-write: a
+ * recorded subtree without markers comes back by identity. A recorded element
+ * is rebuilt through cloneElementWithProps only at its marker paths, so its
+ * other props stay pinned; props the fresh element adds do not pass through
+ * (the prelude rendered the element without them).
  */
 export declare function overlayLoaderContainer(fresh: unknown, recorded: unknown): unknown;

package/dist/types/router/segment-resolution/mask-nested.d.ts

@@ -1,13 +1,16 @@
 /**
- * Capture-side nested-thenable masking — the mechanism behind "nested-promise
- * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (request-context.ts
- * createUseFunction).
+ * Capture-side nested thenables. Masking is the mechanism behind "nested-
+ * promise shape is the liveness declaration" for the loader lane: bake-lane
+ * loader containers (loader-cache.ts) and DSL loader handle pushes (the
+ * capture handle store's push wrap in rsc/shell-capture.ts). Handler handle
+ * pushes are handler output and bake: the capture waits for their nested
+ * promises instead (settleNestedThenables).
  *
- * Deliberately a LEAF module: request-context needs the mask for handle
- * pushes, and loader-mask (the other natural home) imports request-context —
- * importing from there would cycle. This module imports only is-thenable.
+ * Deliberately a LEAF module: loader-mask (the other natural home) imports
+ * request-context, so any funnel importing the mask from there inherits that
+ * graph. This module imports only is-thenable and react.
  */
+import { type ReactElement } from "react";
 /**
  * A promise that never settles — the masked stand-in for a per-request value
  * during shell capture. The consuming Suspense subtree suspends forever, so
@@ -18,11 +21,55 @@
  */
 export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
 /**
- * Deep-copy a container with every NESTED thenable replaced by a masked
+ * A data object the container walks descend into: prototype Object.prototype
+ * or null, and no symbol `$$typeof`. React elements, lazy nodes and references
+ * are plain objects too, told apart by that symbol (Flight switches on it).
+ * They are React's, not data: an element's dev-only fields (`_debugStack`,
+ * `_debugTask`, `_debugInfo`, `ref`) are non-enumerable, so a key-by-key copy
+ * drops them and dev Flight refuses it ("Attempted to render <x> without
+ * development properties", issue #942).
+ */
+export declare function isPlainDataObject(value: unknown): value is Record<string, unknown>;
+/**
+ * cloneElement with only the given props replaced, keeping React's dev key
+ * validation. React 19 dev cloneElement resets `_store.validated`, so a
+ * keyless child of a static children list (validated at creation) would warn
+ * "Each child in a list should have a unique key" once cloned. Pass only the
+ * props that change: cloneElement re-parents the element (owner) when its
+ * config carries `ref`.
+ */
+export declare function cloneElementWithProps(element: ReactElement, props: Record<string, unknown>): ReactElement;
+/**
+ * Resolves once `value` and every thenable reachable from it through plain
+ * data objects, arrays and React element props has settled, following what
+ * each thenable resolves to. A rejection counts as settled: the consumer that
+ * encodes the value reports it. Other objects are leaves (the same walk as
+ * maskNestedContainerThenables), so a promise inside a Map is not waited for.
+ * An element is walked through its props only (`<X data={promise} />` in a
+ * handle value is handler output too), never its owner or type, and is never
+ * rebuilt: nothing is copied, only awaited.
+ *
+ * The capture waits on this for HANDLER handle pushes (shell-capture.ts):
+ * handler output is baked, so its promises must settle before the doc record
+ * encodes the handles every HIT replays.
+ */
+export declare function settleNestedThenables(value: unknown): Promise<void>;
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The capture push
+ * funnel reads it for a loader push: a container with a masked nested
+ * promise keeps its loader tag, so the handle encode never waits on a mask.
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+    thenable: boolean;
+}
+/**
+ * Copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
- * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (createUseFunction) — the two rango-owned funnels where consumers declare
- * per-request data by promise SHAPE.
+ * loader containers (loader-cache.ts) and (b) DSL loader handle pushes
+ * (shell-capture.ts capture store push wrap) — the rango-owned funnels where
+ * a loader declares per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for
@@ -34,20 +81,14 @@ export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
  * Masking makes the consuming subtree postpone as a hole no matter when the
  * promise settles: liveness by declaration, not by racing the window.
  *
- * Only plain objects/arrays are traversed; other values are leaves. The INPUT
- * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
- * rule, semantic-matrix PPR3) shares the raw container and must keep real
- * values. Cycles are preserved as cycles in the copy.
- */
-/**
- * Optional single-walk report for maskNestedContainerThenables: `thenable`
- * flips true when the walk masked at least one thenable. The shell fast path
- * reads it at handle-push time — a pushed container with a nested thenable
- * declares per-request data, and a shell entry whose HANDLER layer made such
- * a declaration cannot be served handler-free (the hole would never fill).
- * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ * Plain data objects, arrays and React element props are traversed: JSX
+ * carrying a promise (`<Reviews data={fetchReviews()} />`) declares
+ * per-request data the same way a plain container does. Other values, lazy
+ * nodes included, are leaves. Copy-on-write: a subtree without a thenable
+ * comes back by identity, so an element is rebuilt only when its props hold
+ * one, and then through cloneElementWithProps, which keeps its type, key,
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED — handler-side loader consumption (the
+ * consumption-lane rule, semantic-matrix PPR3) shares the raw container and
+ * must keep real values. Cycles are preserved as cycles in the copy.
  */
-export interface MaskReport {
-    thenable: boolean;
-}
 export declare function maskNestedContainerThenables(value: unknown, seen?: Map<object, unknown>, report?: MaskReport): unknown;

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

@@ -66,7 +66,9 @@ export declare function resolveEntryHandlerWithRevalidation<TEnv>(entry: Exclude
  */
 export declare function resolveSegmentWithRevalidation<TEnv>(entry: Exclude<EntryData, {
     type: "parallel";
-}>, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean): Promise<SegmentRevalidationResult>;
+}>, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean, 
+/** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+chain?: readonly EntryData[]): Promise<SegmentRevalidationResult>;
 /**
  * Resolve orphan layout with revalidation.
  */
@@ -79,7 +81,9 @@ parentRouteEntry?: EntryData): Promise<SegmentRevalidationResult>;
 export declare function resolveAllSegmentsWithRevalidation<TEnv>(entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: ActionContext | undefined, interceptResult: {
     intercept: any;
     entry: EntryData;
-} | null, localRouteName: string, pathname: string, deps: SegmentResolutionDeps<TEnv>, stale?: boolean): Promise<{
+} | null, localRouteName: string, pathname: string, deps: SegmentResolutionDeps<TEnv>, stale?: boolean, 
+/** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+chain?: readonly EntryData[]): Promise<{
     segments: ResolvedSegment[];
     matchedIds: string[];
 }>;

package/dist/types/router/segment-wrappers.d.ts

@@ -27,7 +27,7 @@ export interface SegmentWrappers<TEnv = any> {
     } | undefined, interceptResult: {
         intercept: InterceptEntry;
         entry: EntryData;
-    } | null, localRouteName: string, pathname: string) => Promise<{
+    } | null, localRouteName: string, pathname: string, stale?: boolean, chain?: readonly EntryData[]) => Promise<{
         segments: ResolvedSegment[];
         matchedIds: string[];
     }>;