@rangojs/router 0.25.0 → 0.26.0

package/src/server/build-version-table.ts

@@ -25,33 +25,24 @@ let table: RouterVersionsTable | undefined = ROUTER_VERSIONS;
 /**
  * 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 function resolveRouterVersions(
   routerId: string | undefined,
-  override?: string,
 ): RouterVersions {
-  return (
-    resolveVersionsFrom(table, routerId, override) ?? uniformVersions(VERSION)
-  );
+  return resolveVersionsFrom(table, routerId) ?? uniformVersions(VERSION);
 }
 
 /**
  * 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 function resolvePrerenderVersion(
-  routerId: string | undefined,
-  routerVersion: string | undefined,
-): string {
-  return resolveRouterVersions(routerId, routerVersion).data;
+export function resolvePrerenderVersion(routerId: string | undefined): string {
+  return resolveRouterVersions(routerId).data;
 }
 
 /** The table gives some router a pair of its own. */
@@ -104,16 +95,13 @@ 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 function versionKeyPrefix(
-  storeVersion: string | undefined,
-  kind: KeyVersion,
-): string {
+export function versionKeyPrefix(kind: KeyVersion): string {
   if (kind === null) return "";
-  const version = storeVersion ?? getCacheVersions()[kind];
+  const version = getCacheVersions()[kind];
   return version ? `v/${version}/` : "";
 }
 

package/src/server/context.ts

@@ -130,6 +130,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;
 };
 
@@ -151,7 +156,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;
   /**
@@ -388,7 +394,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>;
@@ -893,6 +900,61 @@ export function getIsolatedLazyParent(
   };
 }
 
+/*
+ * The DSL's document-only decisions. A document (isSSR) evaluation applies
+ * them in dsl-helpers.ts; getDocumentModeEntry applies the same ones to a
+ * chain built without isSSR. A new ctx.isSSR decision gets a helper here,
+ * called from both.
+ */
+
+/** loader(Def, { ssr: false }): a document awaits it before the first flush. */
+export function documentModeLoader(entry: LoaderEntry): LoaderEntry {
+  return entry.bake ? { ...entry, awaitBeforeFlush: true } : entry;
+}
+
+/** loading(fallback, { ssr: false }): a document renders no fallback. */
+export function applyDocumentModeLoading(entry: EntryPropRender): void {
+  if (entry.loadingSsr === false) entry.loading = false;
+}
+
+const documentModeEntries = new WeakMap<EntryData, EntryData>();
+
+/**
+ * `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 function getDocumentModeEntry(entry: EntryData): EntryData {
+  const known = documentModeEntries.get(entry);
+  if (known) return known;
+  const copy = { ...entry };
+  documentModeEntries.set(entry, copy);
+  documentModeEntries.set(copy, copy);
+  copy.loader = entry.loader.map(documentModeLoader);
+  applyDocumentModeLoading(copy);
+  copy.layout = entry.layout.map(getDocumentModeEntry);
+  const parallel: ParallelEntries = {};
+  for (const slot of Object.keys(entry.parallel) as `@${string}`[]) {
+    const slotEntry = entry.parallel[slot];
+    if (slotEntry) {
+      parallel[slot] = getDocumentModeEntry(slotEntry) as ParallelEntryData;
+    }
+  }
+  copy.parallel = parallel;
+  if (entry.parent) copy.parent = getDocumentModeEntry(entry.parent);
+  if (entry.orphanOwner) {
+    copy.orphanOwner = getDocumentModeEntry(entry.orphanOwner);
+  }
+  return copy;
+}
+
 export function getParallelEntries(
   parallels: ParallelEntries | EntryData[] | undefined,
 ): ParallelEntryData[] {

package/src/server/handle-store.ts

@@ -4,6 +4,7 @@ import {
   isInsideLoaderScope,
 } from "./context.js";
 import { holdsThenable } from "../router/segment-resolution/mask-nested.js";
+import { isThenable } from "../handles/is-thenable.js";
 import { pushedByKey } from "../handles/pushed-by.js";
 import { defineSlot } from "./slot-accessors.js";
 
@@ -254,12 +255,14 @@ export interface HandleStore {
   ): 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,
@@ -278,6 +281,16 @@ export interface HandleStore {
    */
   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
@@ -666,6 +679,39 @@ export function createHandleStore(): HandleStore {
     return after;
   }
 
+  // A restored loader's top-level promise push, judged by its settled value
+  // as push(await value) would be: thenable-free, the record's copy stands
+  // (the capture recorded that value, #1182); holding a promise, it is kept
+  // where the loader's pushes go, once it settles; rejected, it is dropped.
+  // Tracked on the auxiliary lane, so the late channel stays open for it.
+  function judgeRestoredPromise(
+    store: HandleStore,
+    handleName: string,
+    segmentId: string,
+    value: unknown,
+    loaderId: string,
+    tag: SlotTag,
+  ): void {
+    const judged = Promise.resolve(value).then(
+      (settled) => {
+        if (!holdsThenable(settled)) {
+          const existing = data[handleName]?.[segmentId];
+          if (existing) matchRestoredSlot(existing, loaderId);
+          return;
+        }
+        const values = ((data[handleName] ??= {})[segmentId] ??= []);
+        insertSlot(values, restoredInsertIndex(values, loaderId), value, tag);
+        if (tag.replayOf !== undefined) {
+          addPending(pendingReplays, tag.replayOf, values);
+        }
+        version++;
+        signalEmission();
+      },
+      () => {},
+    );
+    store.trackAuxiliary(judged);
+  }
+
   function replayPush(
     store: HandleStore,
     replay: NonNullable<typeof replaying>,
@@ -860,10 +906,22 @@ export function createHandleStore(): HandleStore {
           restoredBy = restoringLoader(replayOf);
         }
       }
-      if (restoredBy !== undefined && !holdsThenable(value)) {
-        const existing = data[handleName]?.[segmentId];
-        if (existing) matchRestoredSlot(existing, restoredBy);
-        return;
+      if (restoredBy !== undefined) {
+        if (isThenable(value)) {
+          judgeRestoredPromise(this, handleName, segmentId, value, restoredBy, {
+            loader: (loaderPush ?? isInsideLoaderScope()) || undefined,
+            replayOf,
+            liveOf: replayOf === undefined ? restoredBy : undefined,
+            owner,
+            by: getHandlePushOwner() ?? replayOf ?? owner,
+          });
+          return;
+        }
+        if (!holdsThenable(value)) {
+          const existing = data[handleName]?.[segmentId];
+          if (existing) matchRestoredSlot(existing, restoredBy);
+          return;
+        }
       }
 
       if (!data[handleName]) {
@@ -977,6 +1035,15 @@ export function createHandleStore(): HandleStore {
       authority = of;
     },
 
+    unrecordPush(handleName: string, segmentId: string, value: unknown): void {
+      const values = data[handleName]?.[segmentId];
+      if (!values) return;
+      const i = values.indexOf(value);
+      if (i < 0) return;
+      const tags = tagsFor(values);
+      tags[i] = { ...tags[i], loader: true, owner: undefined };
+    },
+
     settleLoaderRun(loaderId: string): void {
       if (completed) return;
       const hole = isHole(loaderId);

package/src/server/request-context.ts

@@ -368,9 +368,10 @@ export interface RequestContext<
 
   /**
    * @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/src/testing/build-versions.ts

@@ -35,9 +35,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/src/testing/dispatch.ts

@@ -167,8 +167,6 @@ import { applyStreamIdleTimeout } from "../rsc/stream-idle.js";
 interface DispatchableRouter<TEnv> {
   id?: string;
   routerId?: string;
-  /** createRouter({ version }), the consumer-set version. */
-  version?: string;
   routeMap: Record<string, unknown>;
   /** The routes() patterns the dev trie is rebuilt from (rsc/manifest-init.ts). */
   urlpatterns?: unknown;
@@ -448,7 +446,7 @@ export async function dispatch<TEnv = any>(
     cacheProfiles: router.cacheProfiles,
     // The store keys with the router's versions, resolved as the production
     // handler resolves them (rsc/handler.ts).
-    versions: resolveRouterVersions(routerId, router.version),
+    versions: resolveRouterVersions(routerId),
   });
   // Wire background error reporting so cache degradation (reportCacheError ->
   // _reportBackgroundError) reaches the router's onError, mirroring the production

package/src/testing/internal/seed-vars.ts

@@ -23,10 +23,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/src/testing/serve-shell-request.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
@@ -537,10 +537,7 @@ async function getHandler(
   const { resolveRouterVersions } =
     await import("../server/build-version-table.js");
   // What createRSCHandler would resolve for this router now.
-  const { document: versions } = resolveRouterVersions(
-    internal.id,
-    internal.version,
-  );
+  const { document: versions } = resolveRouterVersions(internal.id);
   const cached = byStore.get(cacheStore ?? router);
   if (cached?.versions === versions) return cached.handler;
 

package/src/types/loader-types.ts

@@ -189,7 +189,12 @@ export type LoaderFn<
  * 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

package/src/vite/discovery/shell-prerender-phase.ts

@@ -231,11 +231,7 @@ export async function runShellPrerenderPhase(
       for (const [routerId, routerInstance] of registry) {
         if (typeof routerInstance.match !== "function") continue;
         // The build's table always holds the whole-build pair.
-        const versions = resolveVersionsFrom(
-          versionsTable,
-          routerId,
-          routerInstance.version,
-        )!;
+        const versions = resolveVersionsFrom(versionsTable, routerId)!;
         try {
           const res = await captureMod.captureShellForBuild({
             router: routerInstance,