@rangojs/router 0.25.0 → 0.26.1

package/skills/testing/server-actions.md

@@ -8,22 +8,22 @@
 
 ### Options — `CreateTestContextOptions<TEnv>`
 
-| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                               |
-| --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                                                                                             |
-| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                                                                                 |
-| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                                                                                            |
-| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                                                                                              |
-| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                                                                                             |
-| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                                                                                              |
-| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                                                                                          |
-| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                                         |
-| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                                                                                            |
-| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                                                                                             |
-| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                                                                                         |
-| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                                                                                            |
-| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                                                                                        |
-| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (the app's version, as `createRouter({ version })` would set it; value is `{version}:{timestamp}`, default `"0"`). |
+| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                                                       |
+| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                                           |
+| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                                                      |
+| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                                                        |
+| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                                                       |
+| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                                                        |
+| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                                                    |
+| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                                                   |
+| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                                                      |
+| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                                                       |
+| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                                                   |
+| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                                                      |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                                                  |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (a seeded app version: the value is `{version}:{timestamp}`, default `"0"`). |
 
 ### Context — `RequestContext<TEnv>` (what your code receives)
 

package/skills/vercel/SKILL.md

@@ -120,7 +120,7 @@ The cache factory receives `(env, ctx)`: on Vercel `env` is `process.env` and `c
 
 `router.prerender()` can warm a route into this store before traffic (`/prerender` → "Warm any route before traffic"). The Runtime Cache is per region, so `VercelCacheStore` declares `scope: "regional"`: a warm fills the region the call runs in. That is all traffic when the project's functions run in one region (the default `iad1` for new projects, and every Hobby project); on a multi-region project it warms one region and the others fill on first use. The router does not detect the region count. The memory store used off-platform above is refused in production and allowed under the dev server.
 
-`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. `version` on the store (or on `createRouter`) replaces both versions. To clear the cache on every deploy, set `version` to a per-deploy value or keep a deployment-scoped `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace or `version`.
+`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. To clear the cache on every deploy, keep a deployment-scoped `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace.
 
 ## Host routers (multi-app)
 

package/src/cache/cf/cf-cache-store.ts

@@ -500,8 +500,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private readonly namespace?: string;
   private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly edgeLookupTimeoutMs: number;
   private readonly edgeReadTimeoutMs: number;
   private readonly kvReadTimeoutMs: number;
@@ -554,7 +552,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // the internal host. Only the explicit override can be captured eagerly.
     this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
-    this.explicitVersion = options.version;
     // Coalesce only finite numbers to the override; a non-finite value (NaN from
     // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
     // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
@@ -1628,8 +1625,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // stamp). Carried on doc L1 entries for the herd guard; never serve them.
     headers.delete(CACHE_EXPIRES_AT_HEADER);
     headers.delete(CACHE_REVALIDATING_AT_HEADER);
-    // Finding #3 (read side): strip per-client signals a pre-fix or
-    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    // Finding #3 (read side): strip per-client signals a pre-fix L1 entry
+    // may carry. See the read-side note in the design doc.
     stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
@@ -2952,7 +2949,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private keyToRequest(key: string, family: KeyVersion): Request {
     const encodedKey = encodeURIComponent(key);
     return new Request(
-      `${this.resolveBaseUrl()}${versionKeyPrefix(this.explicitVersion, family)}${encodedKey}`,
+      `${this.resolveBaseUrl()}${versionKeyPrefix(family)}${encodedKey}`,
       { method: "GET" },
     );
   }
@@ -2976,7 +2973,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * @internal
    */
   private async toKVKey(key: string, family: KeyVersion): Promise<string> {
-    const composed = `${versionKeyPrefix(this.explicitVersion, family)}${key}`;
+    const composed = `${versionKeyPrefix(family)}${key}`;
     if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
     const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
     return `${prefix}~${await kvKeyDigest(composed)}`;

package/src/cache/cf/cf-cache-types.ts

@@ -322,23 +322,6 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   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/src/cache/handle-snapshot.ts

@@ -177,8 +177,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 function restoreHandles(
   handles: Record<string, SegmentHandleData>,

package/src/cache/shell-snapshot.ts

@@ -405,12 +405,15 @@ const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
  * 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 async function buildShellLoaderSeed(
   snapshot: ShellSnapshotRecord[],
+  onUndecodable?: (key: string) => void,
 ): Promise<Map<string, ShellLoaderSeedEntry> | undefined> {
   const loaderRecords: ShellSnapshotRecord[] = [];
   for (const rec of snapshot) {
@@ -441,6 +444,7 @@ export async function buildShellLoaderSeed(
             },
           ];
         } catch {
+          onUndecodable?.(rec.key);
           return null;
         }
       },

package/src/cache/types.ts

@@ -445,7 +445,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
@@ -686,11 +686,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/src/cache/vercel/vercel-cache-store.ts

@@ -330,7 +330,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
@@ -363,19 +363,6 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
     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).
@@ -537,8 +524,6 @@ export class VercelCacheStore<
 
   private readonly cache: VercelRuntimeCache;
   private readonly waitUntil?: (promise: Promise<unknown>) => void;
-  /** The `version` option: used for every versioned family when set. */
-  private readonly explicitVersion?: string;
   private readonly maxItemBytes: number;
   private readonly memo: ResolvedShellMemoOptions;
   private readonly handleMemos: VercelHandleMemos;
@@ -563,7 +548,6 @@ export class VercelCacheStore<
     this.waitUntil = options.waitUntil;
     this.defaults = options.defaults;
     this.keyGenerator = options.keyGenerator;
-    this.explicitVersion = options.version;
     this.maxItemBytes = options.maxItemBytes ?? VERCEL_MAX_ITEM_BYTES;
     this.maxShellEntryBytes = Math.floor((this.maxItemBytes * 3) / 4);
     this.memo = resolveShellMemoOptions(options.memo, {
@@ -1516,7 +1500,7 @@ export class VercelCacheStore<
   // cross-family one reads as corrupt. See the class doc for passing a wider
   // hash (sha256) when many keys are live.
   private toStoreKey(key: string, family: CacheFamily): string {
-    return `${versionKeyPrefix(this.explicitVersion, FAMILY_VERSION[family])}rg:${family}:${key}`;
+    return `${versionKeyPrefix(FAMILY_VERSION[family])}rg:${family}:${key}`;
   }
 
   private async write(

package/src/handles/deferred-resolution.ts

@@ -116,8 +116,9 @@ function keptValues(resolved: ResolvedValue[]): unknown[] {
  * 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 async function* resolvedHandleStream(
   handleStore: HandleStore,

package/src/handles/meta.ts

@@ -231,6 +231,11 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * (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 const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
   MetaDescriptor,

package/src/prerender/build-shell-capture.ts

@@ -106,8 +106,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/src/prerender/writable-store.ts

@@ -22,9 +22,8 @@ import { paramsEqual } from "../router/params-util.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/src/route-definition/dsl-helpers.ts

@@ -9,6 +9,8 @@ import type {
   TransitionConfig,
 } from "../types.js";
 import {
+  applyDocumentModeLoading,
+  documentModeLoader,
   getContext,
   getNamePrefix,
   getReverseScope,
@@ -928,17 +930,14 @@ const loader: RouteHelpers<any, any>["loader"] = (
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
 
-  // Create loader entry with empty revalidate array. awaitBeforeFlush is
-  // resolved here, at DSL-evaluation time, for the same reason
-  // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
-  // flag request-mode-correct with no isSSR threading; see LoaderEntry.
-  // `bake` is the lane, the same on both evaluations.
+  // Create loader entry with empty revalidate array. `bake` is the lane, the
+  // same on both evaluations; a document evaluation adds awaitBeforeFlush at
+  // the push (documentModeLoader) — per-isSSR entry caching makes the flag
+  // request-mode-correct with no isSSR threading; see LoaderEntry.
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
     ...(optionsGiven?.ssr === false && { bake: true as const }),
-    ...(optionsGiven?.ssr === false &&
-      ctx.isSSR && { awaitBeforeFlush: true as const }),
     ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
     // The declaring layout's / parallel's / cache()'s scope. A route's (and
     // an intercept's) loaders have none: they resolve from the route's name,
@@ -978,7 +977,9 @@ const loader: RouteHelpers<any, any>["loader"] = (
     validateUseItems(result, name, "loader", "use");
   }
 
-  ctx.parent.loader.push(loaderEntry);
+  ctx.parent.loader.push(
+    ctx.isSSR ? documentModeLoader(loaderEntry) : loaderEntry,
+  );
   return { name, type: "loader" } as LoaderItem;
 };
 
@@ -1006,12 +1007,11 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
   const resolved =
     typeof component === "function" ? (component as () => any)() : component;
 
-  // If ssr: false and we're in SSR, set loading to false
-  if (options?.ssr === false && ctx.isSSR) {
-    parent.loading = false;
-  } else {
-    parent.loading = resolved;
-  }
+  // `loadingSsr` records ssr: false on both evaluations; a document drops
+  // the fallback (applyDocumentModeLoading).
+  parent.loading = resolved;
+  parent.loadingSsr = options?.ssr === false ? false : undefined;
+  if (ctx.isSSR) applyDocumentModeLoading(parent);
 
   // The flag means "what this fallback covers": without a fallback to show
   // there is nothing to defer behind. Recorded from `resolved`, not

package/src/router/dev-reload-handoff.ts

@@ -0,0 +1,73 @@
+import type { RangoInternal } from "./router-interfaces.js";
+
+/**
+ * Dev only (#1186). A runner full reload clears its evaluated modules while a
+ * request may still be loading them, splitting it across two router copies
+ * whose registries disagree. A router of a dropped copy hands its requests to
+ * the router the reload re-created. docs/manifests.md, "A request the reload
+ * split".
+ */
+let runnerReloaded = false;
+
+/**
+ * Bound on the wait for the re-created router. cloudflare-basic's entry took
+ * about 5 s to re-evaluate after the optimizer's `invalidateAll`.
+ */
+const DEV_RECREATED_ROUTER_WAIT_MS = 10_000;
+const DEV_RECREATED_ROUTER_POLL_MS = 20;
+
+/** 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 function watchRunnerReloads(
+  events: RunnerReloadEvents | undefined,
+): void {
+  events?.on("vite:beforeFullReload", () => {
+    runnerReloaded = true;
+  });
+}
+
+if (process.env.NODE_ENV !== "production") {
+  watchRunnerReloads(import.meta.hot);
+}
+
+/**
+ * Whether a runner full reload dropped this module copy.
+ * @internal
+ */
+export function droppedByRunnerReload(): boolean {
+  return runnerReloaded;
+}
+
+/**
+ * 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 async function routerAfterRunnerReload(
+  routerId: string,
+  sourceFile: string | undefined,
+): Promise<RangoInternal<any, any> | undefined> {
+  if (!sourceFile) return undefined;
+  await import(/* @vite-ignore */ sourceFile);
+  const { RouterRegistry } = await import("./router-registry.js");
+  const deadline = Date.now() + DEV_RECREATED_ROUTER_WAIT_MS;
+  let router = RouterRegistry.get(routerId);
+  while (!router && Date.now() < deadline) {
+    await new Promise((resolve) =>
+      setTimeout(resolve, DEV_RECREATED_ROUTER_POLL_MS),
+    );
+    router = RouterRegistry.get(routerId);
+  }
+  return router;
+}

package/src/router/manifest.ts

@@ -3,6 +3,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getDocumentModeEntry,
   getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
@@ -120,12 +121,18 @@ export async function loadManifest(
       mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
 
     // For lazy entries, use the captured parent from include() context
-    // This ensures routes are registered under the correct layout hierarchy
+    // This ensures routes are registered under the correct layout hierarchy.
+    // The captured chain comes from an evaluation without isSSR: a document
+    // request takes its document-mode copy (getDocumentModeEntry, #1179).
     const lazyContext =
       entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
+    const capturedParent =
+      (lazyContext?.parent as EntryData | null | undefined) ?? Store.parent;
     const parentForContext = lazyContext
       ? getIsolatedLazyParent(
-          (lazyContext.parent as EntryData | null) ?? Store.parent,
+          isSSR && capturedParent
+            ? getDocumentModeEntry(capturedParent)
+            : capturedParent,
         )
       : Store.parent;
 

package/src/router/match-middleware/intercept-resolution.ts

@@ -232,8 +232,8 @@ async function handleCacheHitIntercept<TEnv>(
   const cachedSlot = segments.filter(isInterceptSegment);
   // A record stored before 0.25.0 carries the loaders' aggregate on the slot;
   // the loader segments below replace it. Build versions hash the router's
-  // code, so only a `version` pinned across the upgrade (createRouter's or
-  // the store's) still reads one.
+  // code, so an upgrade does not read one; a custom store that ignores
+  // versions can.
   for (const slot of cachedSlot) {
     delete slot.loaderDataPromise;
     delete slot.loaderIds;

package/src/router/router-interfaces.ts

@@ -479,12 +479,6 @@ export interface RangoInternal<
    */
   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/src/router/router-options.ts

@@ -531,27 +531,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/src/router/segment-resolution/loader-cache.ts

@@ -378,9 +378,10 @@ function getLoaderStore(
  * push funnel reads the pushReplayed owner, shell-capture.ts), so a replay
  * of that shell that serves this loader from its pin restores them owned
  * (HandleStore.pushRestored), on a document HIT and on a navigation alike.
- * This replay still runs there: the store drops its settled values, which
- * the record already restored, and keeps the thenable ones the record could
- * not keep (a deferred push, the reason the loader's pin carries `runs`).
+ * This replay still runs there: the store drops its values that settle
+ * thenable-free, which the record already restored, and keeps the ones
+ * holding a promise the record could not keep (the reason the loader's pin
+ * carries `runs`).
  */
 async function replayLoaderHandles(
   encoded: string | undefined,

package/src/router/segment-resolution/mask-nested.ts

@@ -125,9 +125,11 @@ function someNestedThenable(
 /**
  * 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 function holdsThenable(value: unknown): boolean {
   return someNestedThenable(value, () => true);

package/src/router-versions.ts

@@ -33,24 +33,24 @@ export type RouterVersionsTable = Readonly<
 /** Table key of the whole-build versions. Not a legal `$$id` (8 hex chars). */
 export 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 function uniformVersions(version: string): RouterVersions {
   return { data: version, document: version };
 }
 
 /**
- * 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 function resolveVersionsFrom(
   table: RouterVersionsTable | undefined,
   routerId: string | undefined,
-  override: string | undefined,
 ): RouterVersions | undefined {
-  if (override !== undefined) return uniformVersions(override);
   if (!table) return undefined;
   const pair =
     (routerId !== undefined && Object.hasOwn(table, routerId)