@rangojs/router 0.25.0 → 0.26.1

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.25.0",
+      version: "0.26.1",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -21,8 +21,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly namespace?;
     private readonly explicitBaseUrl?;
     private readonly waitUntil?;
-    /** The `version` option: used for every versioned family when set. */
-    private readonly explicitVersion?;
     private readonly edgeLookupTimeoutMs;
     private readonly edgeReadTimeoutMs;
     private readonly kvReadTimeoutMs;

package/dist/types/cache/cf/cf-cache-types.d.ts

@@ -278,22 +278,6 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * (safe to set large) rather than the invalidation-latency ceiling.
      */
     tagCacheTtl?: number;
-    /**
-     * Cache version string override. When set, this exact value prefixes every
-     * versioned key the store writes (`v/{version}/...`), for cached data and
-     * stored HTML alike; changing it makes every earlier entry unreachable.
-     *
-     * Leave it unset for the default: the store keys with the versions of the
-     * router serving the request. Segment entries and `"use cache"` items use
-     * the router's data version; document responses and PPR shells use its
-     * document version (see `createRouter({ version })`). Those are computed
-     * from the router's built code, so a deploy that does not change the router
-     * keeps its entries.
-     *
-     * Tag invalidation markers are never versioned: an invalidation applies to
-     * the entries of every version, including one that comes back in a rollback.
-     */
-    version?: string;
     /**
      * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
      * slower than this is abandoned and treated as a miss, so a degraded colo

package/dist/types/cache/handle-snapshot.d.ts

@@ -73,8 +73,8 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * says the record supplies that loader's value too ("pin", "copies"), and is
  * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
  * owner. Neither claims its loader, so the loader's own cache() HIT still
- * delivers (the thenable pushes a restored copy lets through, or its entry's
- * pushes in a placeholder's place).
+ * delivers (the pushes holding a promise a restored copy lets through, or its
+ * entry's pushes in a placeholder's place).
  */
 export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
 /**

package/dist/types/cache/shell-snapshot.d.ts

@@ -199,11 +199,13 @@ export interface ShellLoaderSeedEntry {
  * by loader. A key that does not parse pins nothing.
  *
  * Deserializations run in parallel; a record that fails to decode is skipped
- * (that loader drifts — the pre-snapshot behavior — instead of failing the
- * HIT). Returns undefined when the snapshot carries no loader records, without
- * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ * and reported to `onUndecodable`: its loader runs instead, which a document
+ * HIT has already committed a prelude against, so serveShellHit retires the
+ * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * records, without touching the Flight codec (kept lazy for cold paths and
+ * non-RSC configs).
  */
-export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
+export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[], onUndecodable?: (key: string) => void): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
 /** The key of a snapshot's one `handles` record (ShellSnapshotHandlesValue). */
 export declare const SHELL_HANDLES_RECORD_KEY = "handles";
 /**

package/dist/types/cache/types.d.ts

@@ -389,7 +389,7 @@ export interface ShellCacheEntry {
     /** React.version captured at prerender time; the read-time invalidation gate. */
     reactVersion: string;
     /**
-     * Build version captured at prerender time: the RSC handler's `version`,
+     * Build version captured at prerender time: the RSC handler's version,
      * which is the router's DOCUMENT version (router-versions.ts) — a hash of
      * its server code and the client asset names by default, a stamp bumped on
      * dev RSC-module edits. The second read-time gate: a persistent shared
@@ -625,11 +625,13 @@ export interface ShellSnapshotLoaderValue {
      */
     holes: 0 | 1;
     /**
-     * 1 when the capture saw a loader push it could not record (a deferred
-     * push, one with masked nested promises, or one made outside any loader
-     * body): a HIT then still runs the loader body in the background
-     * (pin-first) so those pushes reach the page. 0: a hole-free record is
-     * served from the pin alone and its body does not run on a HIT.
+     * 1 when the capture saw a loader push it could not record (one whose
+     * settled value holds masked nested promises, one a live-lane loader made,
+     * or one made outside any loader body): a HIT then still runs the loader
+     * body in the background (pin-first) so those pushes reach the page. A
+     * pushed promise that settles thenable-free is recorded (#1182).
+     * 0: a hole-free record is served from the pin alone and its body does not
+     * run on a HIT.
      *
      * Both bits are always written. A record stored before they existed (v0.17)
      * reads each missing bit as 1 (buildShellLoaderSeed): its snapshot lacks

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -102,7 +102,7 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      *
      * Vercel does not reconcile entries between deployments; the store does it
      * through its keys, which carry the serving router's cache versions (see
-     * `version`). So a deploy that changes a router's code stops reading that
+     * `getCacheVersions`). So a deploy that changes a router's code stops reading that
      * router's old entries, and a deploy that does not keeps them. A namespace
      * that changes per deployment (`getCache({ namespace: VERCEL_DEPLOYMENT_ID })`)
      * still works and clears the cache on every deploy, which is what you want
@@ -128,18 +128,6 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
      * segmentation). Receives the request context and the default key.
      */
     keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
-    /**
-     * Version override, folded into every versioned key as `v/{version}/...`.
-     * When set, this exact value is used for cached data and stored HTML alike;
-     * changing it makes everything this store wrote before unreachable.
-     *
-     * Leave it unset for the default: the store keys with the versions of the
-     * router serving the request, as CFCacheStore does. Segments and `"use
-     * cache"` items use the router's data version; responses and PPR shells use
-     * its document version (see `createRouter({ version })`). Tag markers are
-     * never versioned, so an invalidation applies to every version.
-     */
-    version?: string;
     /**
      * Max serialized entry size in bytes before a write is skipped. Defaults to
      * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
@@ -238,8 +226,6 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly cache;
     private readonly waitUntil?;
-    /** The `version` option: used for every versioned family when set. */
-    private readonly explicitVersion?;
     private readonly maxItemBytes;
     private readonly memo;
     private readonly handleMemos;

package/dist/types/handles/deferred-resolution.d.ts

@@ -48,8 +48,9 @@ export declare function resolveDeferredHandleValues(data: HandleData): Promise<H
  * so a push the record leaves out must not be in the prelude either: it
  * rendered an element no HIT's hydration data matched (issue #1035). Which
  * pushes a record keeps is the capture funnel's decision (shell-capture.ts
- * deriveShellCaptureContext: today it leaves out a deferred loader push and
- * one holding a masked promise), not this function's.
+ * deriveShellCaptureContext: it leaves out a loader push whose settled value
+ * holds a masked promise, and one a live-lane loader made), not this
+ * function's.
  */
 export declare function resolvedHandleStream(handleStore: HandleStore, recordedOnly?: boolean): AsyncGenerator<HandleData, void, unknown>;
 /**

package/dist/types/handles/meta.d.ts

@@ -39,5 +39,10 @@ import type { MetaDescriptor } from "../router/types.js";
  * (resolve-by-default), so they participate in deduplication and `%s`
  * title-templating identically to synchronous descriptors. A descriptor that
  * resolves to `null`/`undefined` (or rejects) is dropped.
+ *
+ * On a ppr route, a descriptor a handler or an `ssr: false` loader pushes,
+ * promise or not, is in the shell's `<head>` on every HIT (#1182). One a
+ * loader without `ssr: false` pushes is live: on a HIT it arrives after
+ * hydration.
  */
 export declare const Meta: Handle<MetaDescriptor, MetaDescriptor[]>;

package/dist/types/prerender/build-shell-capture.d.ts

@@ -68,8 +68,7 @@ export interface BuildShellCaptureOptions {
     /** Build-time env bindings (rango plugin buildEnv), if configured. */
     buildEnv?: unknown;
     /**
-     * The versions the SHIPPED build serves this router with (the build table,
-     * or the router's consumer-set version) — NOT the temp server's own
+     * The versions the SHIPPED build serves this router with (the build table) — NOT the temp server's own
      * version-plugin stamp. The serve-side isValidShellHit gate compares
      * entry.buildVersion against the running worker's ctx.version, which is the
      * document version; stamping the temp server's would make every build entry

package/dist/types/prerender/writable-store.d.ts

@@ -19,9 +19,8 @@ import type { PrerenderEntry } from "./store.js";
 export interface PrerenderKey {
     routerId: string;
     /**
-     * The owning router's cache version (its data version, or
-     * `createRouter({ version })`). Opaque: never set or read by app code; a
-     * store keys off it as given.
+     * The owning router's cache version (its data version). Opaque: never set
+     * or read by app code; a store keys off it as given.
      */
     version: string;
     routeName: string;

package/dist/types/router/dev-reload-handoff.d.ts

@@ -0,0 +1,26 @@
+import type { RangoInternal } from "./router-interfaces.js";
+/** The `import.meta.hot` subset this reads. */
+interface RunnerReloadEvents {
+    on(event: "vite:beforeFullReload", listener: () => void): void;
+}
+/**
+ * Mark this module copy dropped on the runner's next full reload.
+ * @internal
+ */
+export declare function watchRunnerReloads(events: RunnerReloadEvents | undefined): void;
+/**
+ * Whether a runner full reload dropped this module copy.
+ * @internal
+ */
+export declare function droppedByRunnerReload(): boolean;
+/**
+ * The router the reload re-created for `routerId`, or undefined when none
+ * registered within DEV_RECREATED_ROUTER_WAIT_MS. Importing `sourceFile`
+ * evaluates it when nothing else is. While the reload's re-import is still
+ * evaluating it, the runner returns the unfinished module (it is in this
+ * copy's import call stack, `cachedRequest` in vite's module-runner), so this
+ * waits for the fresh registry to receive the router.
+ * @internal
+ */
+export declare function routerAfterRunnerReload(routerId: string, sourceFile: string | undefined): Promise<RangoInternal<any, any> | undefined>;
+export {};

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

@@ -378,11 +378,6 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * Nonce provider for CSP
      */
     readonly nonce?: NonceProvider<TEnv>;
-    /**
-     * The consumer-set version (createRouter({ version })), used for both of the
-     * router's versions. Undefined when the router uses its build versions.
-     */
-    readonly version?: string;
     /**
      * URL patterns reference for build-time manifest generation
      */

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

@@ -489,26 +489,6 @@ export interface RangoOptions<TEnv = any> {
      * ```
      */
     nonce?: NonceProvider<TEnv>;
-    /**
-     * Version override. When set, this exact value is used for both of the
-     * router's versions: it keys the router's cached data (segments, `"use
-     * cache"` values, loader data) and its stored HTML (PPR shells,
-     * document-cache responses), is sent in payload metadata, and is what the
-     * browser's `_rsc_v` is compared with (a mismatch reloads the tab).
-     *
-     * Leave it unset for the default: rango computes two versions per router at
-     * build time, a data version from the router's server code and a document
-     * version that also covers the client assets. The same code builds to the
-     * same versions, so a deploy that does not change this router keeps its
-     * cache. In dev both are a stamp bumped on every RSC module edit.
-     *
-     * Set it to clear this router's cache on demand (change the value), or to
-     * tie the cache to your own release id (a per-deploy value clears the cache
-     * on every deploy).
-     *
-     * @default the router's build versions
-     */
-    version?: string;
     /**
      * TTL (in seconds) for the client-side in-memory prefetch cache.
      *

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

@@ -59,9 +59,11 @@ export declare function settleNestedThenables(value: unknown): Promise<void>;
 /**
  * True when `value` is a thenable or holds one where the capture's loader
  * push funnel masks it (maskNestedContainerThenables): through plain data
- * objects, arrays and React element props. Such a push stays out of a shell's
- * record and reaches a HIT only from a run of its loader there, so a HIT
- * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ * objects, arrays and React element props. A settled push that holds one
+ * stays out of a shell's record and reaches a HIT only from a run of its
+ * loader there, so a HIT keeps it; a push without one is the record's
+ * (HandleStore.pushRestored). A top-level thenable is judged by the value it
+ * settles to, on both sides (#1182).
  */
 export declare function holdsThenable(value: unknown): boolean;
 /**

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

@@ -27,13 +27,15 @@ export interface RouterVersions {
 export type RouterVersionsTable = Readonly<Record<string, readonly [data: string, document: string]>>;
 /** Table key of the whole-build versions. Not a legal `$$id` (8 hex chars). */
 export declare const DEFAULT_ROUTER_VERSIONS_KEY = "*";
-/** One value for both versions: a consumer-set `version`, or the dev stamp. */
+/**
+ * One value for both versions: the dev stamp, the version a build-time shell
+ * capture is asked for, or a test's seed.
+ */
 export declare function uniformVersions(version: string): RouterVersions;
 /**
- * The versions a router serves with under `table`: a consumer-set `version`
- * for both; else the router's own entry; else the whole-build pair, for a
- * router the table does not list. `undefined` when there is no table (dev,
- * tests) or it has neither entry. One function for the request handler and
+ * The versions a router serves with under `table`: the router's own entry,
+ * else the whole-build pair, for a router the table does not list.
+ * `undefined` when there is no table (dev, tests) or it has neither entry. One function for the request handler and
  * the build's shell capture, which must stamp what the handler will check.
  */
-export declare function resolveVersionsFrom(table: RouterVersionsTable | undefined, routerId: string | undefined, override: string | undefined): RouterVersions | undefined;
+export declare function resolveVersionsFrom(table: RouterVersionsTable | undefined, routerId: string | undefined): RouterVersions | undefined;

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

@@ -148,13 +148,17 @@ export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
  * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
  * result): `identity` (a request-scoped read: cookies(), headers(), the
  * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
- * `loader` (a `{ ssr: false }` loader rejected, or settled with
- * redirect()/notFound()), `no-record` (no doc record: the route's cache()
- * refused the write, or the handler output failed), `handles` (a pushed
+ * `loader` (a `{ ssr: false }` loader rejected, settled with
+ * redirect()/notFound(), or a promise it pushed rejected),
+ * `no-record` (no doc record: the route's cache() refused the write, or the
+ * handler output failed), `handles` (a pushed
  * handle value did not finish encoding), `size` (over the store's value
- * limit), `record-expired` (the route cache() record the capture wrote ran
- * out first), `invalidated` (a tag of the shell was invalidated after the
- * capture started), `uncacheable` (the store cannot hold the entry).
+ * limit, or `ssr: false` loader pins over `ppr.maxSnapshotBytes`: a
+ * navigation-only entry was stored in place of the document shell),
+ * `record-expired` (the route cache() record
+ * the capture wrote ran out first), `invalidated` (a tag of the shell was
+ * invalidated after the capture started), `uncacheable` (the store cannot
+ * hold the entry).
  */
 export type ShellCaptureRefusal = "identity" | "dynamic" | "loader" | "no-record" | "handles" | "size" | "record-expired" | "invalidated" | "uncacheable";
 /**

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

@@ -105,9 +105,8 @@ export declare const DEFAULT_SHELL_ENTRY_MAX_BYTES: number;
  * while still fitting any sane pinned-ring payload. Applied ONLY in
  * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
  * the option through undefaulted), so every producer and direct caller gets
- * the same policy. The doc record is exempt; over the cap the other records
- * are dropped (shell still stored and replayed; the pins' loaders read the
- * live store — see PartialPrerenderProps.maxSnapshotBytes).
+ * the same policy. The doc record is exempt; over the cap only the
+ * navigation half is stored (see PartialPrerenderProps.maxSnapshotBytes).
  */
 export declare const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number;
 /**
@@ -165,7 +164,11 @@ export interface ShellCaptureDebugEvent {
     preludeBytes?: number;
     /** Serialized snapshot size in UTF-8 bytes. Absent when nothing was recorded. */
     snapshotBytes?: number;
-    /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
+    /**
+     * True when the loader pins exceeded maxSnapshotBytes: no document shell
+     * was stored, only a navigation-only entry (the doc record, or a tombstone
+     * for a prerender-served capture). The outcome is `refused`, refusal `size`.
+     */
     snapshotSkipped?: boolean;
     /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
     untaggedBake?: true;
@@ -315,8 +318,8 @@ export interface ShellCaptureDescriptor {
     captureTimeout?: number;
     store?: SegmentCacheStore<any>;
     /**
-     * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
-     * the snapshot is skipped and the shell stored without it (reported once per
+     * Cap (serialized UTF-8 bytes) on the entry's loader pins; over it only the
+     * navigation half is stored and the attempt refuses (reported once per
      * key). Absent = DEFAULT_PPR_MAX_SNAPSHOT_BYTES, applied in
      * captureAndStoreShell — the single defaulting site.
      */
@@ -502,8 +505,9 @@ export type CaptureRecordOutcome = {
  * component showed one value in the prelude and another on every HIT.
  *
  * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
- * top-level handle promises, the handler pushes' nested promises, and the
- * bake-lane loader containers settle first (the record encodes the handles
+ * top-level handle promises (a bake-lane loader's pushed promises among
+ * them, #1182), the handler pushes' nested promises, and the bake-lane
+ * loader containers settle first (the record encodes the handles
  * a HIT restores, and its handle encode has its own 5s timeout that must
  * never be the one that fires); then the capture's onResponse callbacks fire
  * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
@@ -529,6 +533,19 @@ export interface CaptureContextDerivation {
      * record encodes its handles, so that encode never races a pending value.
      */
     handlerPushesSettled: () => Promise<void>;
+    /**
+     * Every promise a bake-lane loader body pushed (#1182), in push order.
+     * The record-first step waits for them (they are in the recorded cut) and
+     * names the loader and the handle of one that rejects or misses the
+     * deadline.
+     */
+    loaderPromisePushes: readonly LoaderPromisePush[];
+}
+/** A promise a bake-lane loader pushed at capture, owned by that loader. */
+export interface LoaderPromisePush {
+    loaderId: string;
+    handleName: string;
+    state: "pending" | "fulfilled" | "rejected";
 }
 /**
  * Derive the capture request context from a base context. Producer A passes

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

@@ -333,14 +333,6 @@ export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<
      * ```
      */
     cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
-    /**
-     * Version override for this handler. Same meaning as
-     * `createRouter({ version })`, which it takes precedence over: this exact
-     * value is used for both of the router's versions.
-     *
-     * @default createRouter({ version }), else the router's build versions
-     */
-    version?: string;
     /**
      * Nonce provider for Content Security Policy (CSP).
      *

package/dist/types/server/build-version-table.d.ts

@@ -2,21 +2,18 @@ import { type RouterVersions, type RouterVersionsTable } from "../router-version
 /**
  * The versions a router serves with, in order:
  *
- * 1. `override`, a consumer-set `version` (createRouter or createRSCHandler):
- *    that exact value for both.
- * 2. The router's entry in the build table, else the whole-build entry.
- * 3. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
+ * 1. The router's entry in the build table, else the whole-build entry.
+ * 2. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
  */
-export declare function resolveRouterVersions(routerId: string | undefined, override?: string): RouterVersions;
+export declare function resolveRouterVersions(routerId: string | undefined): RouterVersions;
 /**
  * The version an on-demand prerender overlay key carries: the router's data
  * version, because the overlay stores segment data, as the segment cache does
  * (a client-only deploy keeps both). The write side (`router.prerender`,
- * router.ts) and the read side (rsc/handler.ts) both call this with
- * `createRouter({ version })`, the only override the trigger can see, so they
- * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ * router.ts) and the read side (rsc/handler.ts) both call this, so they
+ * cannot disagree.
  */
-export declare function resolvePrerenderVersion(routerId: string | undefined, routerVersion: string | undefined): string;
+export declare function resolvePrerenderVersion(routerId: string | undefined): string;
 /**
  * The versions of the router serving the current request, for a cache store
  * building a key. A store operation with no request context (a detached task
@@ -40,11 +37,11 @@ export declare function getCacheVersions(): RouterVersions;
 export type KeyVersion = keyof RouterVersions | null;
 /**
  * The `v/{version}/` prefix of a persistent store key, or "" for an
- * unversioned one. A store-level `version` is used for every versioned kind;
- * otherwise the version is the serving router's, read per operation because
- * the cache factory builds the store before the request context exists.
+ * unversioned one. The version is the serving router's, read per operation
+ * because the cache factory builds the store before the request context
+ * exists.
  */
-export declare function versionKeyPrefix(storeVersion: string | undefined, kind: KeyVersion): string;
+export declare function versionKeyPrefix(kind: KeyVersion): string;
 /**
  * @internal Install a table, or restore the build's with `undefined`. A
  * request handler resolves its router's versions once, when it is created, so

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

@@ -97,6 +97,11 @@ export type EntryPropRender = {
      * on both DSL evaluations, whatever `ssr` did to `loading`.
      */
     loadingPrefetch?: false;
+    /**
+     * loading(fallback, { ssr: false }), on both DSL evaluations; a document
+     * then sets `loading` to false (applyDocumentModeLoading).
+     */
+    loadingSsr?: false;
     transition?: TransitionConfig;
 };
 /**
@@ -117,7 +122,8 @@ export type LoaderEntry = {
      * 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.
+     * appears on navigation-lane entries. Set by documentModeLoader, which
+     * getDocumentModeEntry also applies to a lazy include's captured ancestors.
      */
     awaitBeforeFlush?: true;
     /**
@@ -325,7 +331,8 @@ interface HelperContext extends IncludeScopePosition {
      *  different routers don't clobber each other (route-map-builder.ts). */
     routerId?: string;
     metrics?: MetricsStore;
-    /** True when rendering for SSR (document requests) */
+    /** True when rendering for SSR (document requests). DSL decisions on it
+     *  go through the document-mode helpers (documentModeLoader). */
     isSSR?: boolean;
     /** URL patterns map for path() routes (route name -> pattern) */
     patterns?: Map<string, string>;
@@ -479,6 +486,23 @@ export type { HelperContext };
  * parent pointer, handler) stays shared, which is correct and cheap.
  */
 export declare function getIsolatedLazyParent(captured: EntryData | null | undefined): EntryData | null;
+/** loader(Def, { ssr: false }): a document awaits it before the first flush. */
+export declare function documentModeLoader(entry: LoaderEntry): LoaderEntry;
+/** loading(fallback, { ssr: false }): a document renders no fallback. */
+export declare function applyDocumentModeLoading(entry: EntryPropRender): void;
+/**
+ * `entry`, its ancestors, orphan layouts and parallels as a document (isSSR)
+ * DSL evaluation builds them, from an evaluation without isSSR.
+ *
+ * include() captures its parent chain on router.ts routes() or
+ * lazy-includes.ts runExpansion, neither of which has isSSR, and loadManifest
+ * reuses it for every request. Handed to a document as is, every ancestor
+ * outside the include kept its navigation-mode decisions (#1179). Intercepts
+ * stay as they are: a document never resolves one.
+ *
+ * Memoized per entry, so an ancestor several includes share maps to one copy.
+ */
+export declare function getDocumentModeEntry(entry: EntryData): EntryData;
 export declare function getParallelEntries(parallels: ParallelEntries | EntryData[] | undefined): ParallelEntryData[];
 export declare function getParallelSlotEntries(parallels: ParallelEntries | EntryData[] | undefined): Array<{
     slot: `@${string}`;

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

@@ -123,12 +123,14 @@ export interface HandleStore {
      */
     pushPlaceholder(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
-     * push() a record's copy of `loaderId`'s settled push that stands
-     * (restoreHandles): the record supplies the loader's value too. From then
-     * on this request drops every settled, thenable-free push the loader makes
-     * (live, or replayed from a cache entry, anywhere inside its body), and
-     * keeps the ones holding a thenable (holdsThenable: what the record could
-     * not keep), placed among the restored copies in the loader's push order.
+     * push() a record's copy of `loaderId`'s push that stands (restoreHandles):
+     * the record supplies the loader's value too. From then on this request
+     * drops every thenable-free push the loader makes (live, or replayed from
+     * a cache entry, anywhere inside its body), and keeps the ones holding a
+     * thenable (holdsThenable: what the record could not keep), placed among
+     * the restored copies in the loader's push order. A top-level promise is
+     * judged by its settled value, as the capture judged it (#1182): dropped
+     * when it settles thenable-free or rejects, else kept once it settles.
      */
     pushRestored(handleName: string, segmentId: string, data: unknown, loaderId: string): void;
     /**
@@ -140,6 +142,15 @@ export interface HandleStore {
      * takes a push made inside a hole it awaited.
      */
     setRecordAuthority(authority: (loaderId: string) => RecordAuthority): void;
+    /**
+     * Capture only (shell-capture.ts deriveShellCaptureContext): the slot
+     * holding `value` becomes a DSL-loader push without an owner, so the
+     * record and the prelude leave it out (getDataForSegment's
+     * `excludeLoaderPushes`). The capture owns a bake-lane loader's promise
+     * when it is pushed, and calls this once the promise settled to a value
+     * that holds one (#1182).
+     */
+    unrecordPush(handleName: string, segmentId: string, value: unknown): void;
     /**
      * `loaderId`'s run in this request settled (resolved or rejected), its
      * pushes made (loader-resolution.ts createLoaderExecutor). Its placeholders

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

@@ -264,9 +264,10 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
     /**
      * @internal Set on a capture's derived context when a loader pushed a
-     * value the record cannot keep (a deferred push, masked nested promises,
-     * or a push outside a loader body): the loader records then carry
-     * `runs: 1`, so a HIT still runs their bodies for those pushes.
+     * value the record cannot keep (masked nested promises, a pushed promise
+     * that settled to one, a live-lane loader's push, or a push outside a
+     * loader body): the loader records then carry `runs: 1`, so a HIT still
+     * runs their bodies for those pushes.
      */
     _shellCaptureUnrecordedLoaderPush?: true;
     /**

package/dist/types/testing/build-versions.d.ts

@@ -15,9 +15,6 @@ export interface BuildVersions extends RouterVersions {
  * Install the cache versions of a simulated build, or remove them with no
  * argument (routers serve unversioned again, the default in tests).
  *
- * A router that sets `createRouter({ version })` keeps that value for both
- * versions, exactly as in production.
- *
  * @example A deploy that changes the client only keeps cached data
  * ```ts
  * setBuildVersions({ data: "d1", document: "h1" });

package/dist/types/testing/internal/seed-vars.d.ts

@@ -21,10 +21,10 @@ export interface StateCookieSeed {
      */
     routerId?: string;
     /**
-     * The app's version, as `createRouter({ version })` would set it: the
-     * rotated value's prefix (`{version}:{timestamp}`) and the version a cache
-     * store keys with. Defaults to `"0"` for the prefix (resolved inside
-     * createRequestContext) and to the build versions for the store.
+     * The app's version: the rotated value's prefix (`{version}:{timestamp}`)
+     * and the request's cache versions, which a store keys with. Defaults to
+     * `"0"` for the prefix (resolved inside createRequestContext) and to the
+     * build versions for the store.
      */
     version?: string;
 }

package/dist/types/testing/serve-shell-request.d.ts

@@ -2,7 +2,7 @@
  * serveShellRequest — one request through the production PPR serve path.
  *
  * Builds the router's request handler as `router.fetch` does
- * (`createRSCHandler` with the router's `nonce`, `version` and `cache`
+ * (`createRSCHandler` with the router's `nonce` and `cache`
  * config) and serves one GET through it, so middleware, the shell serve path
  * and a MISS's background capture all run production code, on real Flight
  * (the vendored react-server-dom serializer). The call settles every

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

@@ -164,7 +164,12 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
  * deterministically precedes Response construction, where the streamed
  * default only wins that race opportunistically). Under ppr it is also the
  * BAKE lane: the loader executes at shell capture and its settled return is
- * shell material (nested promises stay live holes) — see the ppr docs.
+ * shell material (nested promises stay live holes), and so are its handle
+ * pushes, a pushed promise or `.defer()` included: the capture awaits it and
+ * every HIT serves the value it settled to (#1182). A pushed promise that
+ * rejects, or misses `ppr.captureTimeout`, keeps the route on MISS. A value
+ * that must stay per request belongs to a loader without `ssr: false` — see
+ * the ppr docs.
  *
  * Scoped per LOADER, not per segment: an `ssr: false` loader alongside a
  * deliberately streaming sibling awaits only itself, and the sibling keeps