@rangojs/router 0.24.2 → 0.24.3

package/dist/types/client-urls/layout-loader-copies.d.ts

@@ -0,0 +1,11 @@
+import type { EntryData } from "../server/context.js";
+import type { LoaderDefinition } from "../types.js";
+export declare function setLayoutLoaderCopies(stub: LoaderDefinition<any>, ids: readonly string[]): void;
+/** True for the materialized stub of a clientUrls() layout() loader copy. */
+export declare function isLayoutLoaderCopy(stub: LoaderDefinition<any>): boolean;
+/**
+ * `held` with the id of each of `route`'s layout() loader copies whose
+ * loader the page holds under another route of the layout; `held` itself
+ * when there is none.
+ */
+export declare function withLayoutLoaderCopies(held: ReadonlySet<string>, route: EntryData): ReadonlySet<string>;

package/dist/types/client-urls/server-projection.d.ts

@@ -42,6 +42,11 @@ export interface ClientUrlProjectionRoute {
      *  the registered predicates (revalidate-registry.ts). Absent when no
      *  loader declares one. */
     readonly loaderRevalidate?: readonly (readonly string[])[];
+    /** One per leading loader its layout()s declare
+     *  (ClientUrlRouteRecord.layoutLoaders): the record's ordinal in the
+     *  definition. Two routes whose loader at an index carries the same ordinal
+     *  hold one layout() loader (layout-loader-copies.ts). Absent when none. */
+    readonly layoutLoaders?: readonly number[];
     /** Data-only transition config (never `when`); absent in projections
      *  serialized before transition support. */
     readonly transition?: Readonly<ClientTransitionConfig>;

package/dist/types/handles/pushed-by.d.ts

@@ -27,5 +27,12 @@ export declare function withSegmentHandles(target: HandleData, source: HandleDat
  * the position of the first value they replace (the end when they replace
  * none). New containers throughout: an object a reader was handed (a history
  * entry's data) is never written to.
+ *
+ * A segment with no values of a handle takes, for each loader `matched`
+ * registers on it that did not run, the values that loader pushed under a
+ * segment the page leaves, a slot excepted: a clientUrls() layout() loader the
+ * server held on a navigation between two routes of the layout
+ * (client-urls/layout-loader-copies.ts), whose pushes the page filed under
+ * the route it leaves.
  */
 export declare function mergePartialHandleData(current: HandleData, incoming: HandleData, segmentOrder: readonly string[], matched: readonly string[], resolvedIds: readonly string[] | undefined): HandleData;

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

@@ -353,6 +353,14 @@ interface HelperContext {
     includeScope?: string;
 }
 export declare const RangoContext: AsyncLocalStorage<HelperContext>;
+type ShortCodeType = "layout" | "parallel" | "route" | "loader" | "cache";
+/**
+ * The shortCode the `ahead`-th next `getShortCode(type)` call in this DSL
+ * context returns, without taking it. clientUrls() materialization reads the
+ * code of every group route this way, including the routes an evaluation for
+ * another route skips (client-urls/layout-loader-copies.ts).
+ */
+export declare function peekShortCode(type: ShortCodeType, ahead: number): string;
 export declare const getContext: () => {
     context: AsyncLocalStorage<HelperContext>;
     getStore: () => HelperContext;

package/dist/vite/index.js

@@ -5929,7 +5929,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.24.2",
+  version: "0.24.3",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -11034,7 +11034,11 @@ function serializeTransition(route2) {
 function indicesWhere(items, pred) {
   return items.flatMap((item, index) => pred(item) ? [index] : []);
 }
-function serializeRoute(route2, options) {
+function serializeRoute(route2, options, ordinals) {
+  const layoutLoaders = route2.layoutLoaders.map((record) => {
+    if (!ordinals.has(record)) ordinals.set(record, ordinals.size);
+    return ordinals.get(record);
+  });
   const loaderIds = route2.loaders.map(({ loader: loader2 }, index) => {
     if (typeof loader2.$$id !== "string" || loader2.$$id.length === 0) {
       throw projectionError(
@@ -11078,6 +11082,7 @@ function serializeRoute(route2, options) {
         loaderRevalidate.map((keys) => Object.freeze(keys))
       )
     } : {},
+    ...layoutLoaders.length > 0 ? { layoutLoaders: Object.freeze(layoutLoaders) } : {},
     ...transition2 ? { transition: transition2 } : {},
     ...typeof route2.transition?.when === "function" ? { transitionWhen: true } : {}
   });
@@ -11099,10 +11104,11 @@ function serializeIntercept(record, index) {
   });
 }
 function serializeClientUrlPatterns(patterns, options = {}) {
+  const ordinals = /* @__PURE__ */ new Map();
   return Object.freeze({
     version: 1,
     routes: Object.freeze(
-      patterns.routes.map((route2) => serializeRoute(route2, options))
+      patterns.routes.map((route2) => serializeRoute(route2, options, ordinals))
     ),
     intercepts: Object.freeze(
       (patterns.intercepts ?? []).map(serializeIntercept)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/client-urls/SKILL.md

@@ -278,6 +278,18 @@ yet (a known gap, left for a follow-up). The build still checks those
 predicates like any other, so one that captures a binding of the `"use client"`
 module fails the build although nothing runs it: import it, or drop it.
 
+A group `layout()` loader revalidates as a server layout's loader does. With no
+`revalidate()` a navigation keeps it, whichever route of the layout it goes to
+and whatever params or search change (a same-route param navigation too), and
+an action re-runs it. Its `revalidate()` decides on every navigation and
+action, with that default as `defaultShouldRevalidate`: a shop layout's
+`loader(CartLoader, () => [revalidate(({ isAction }) => isAction(CartActions))])`
+runs on the document request and then only on cart actions, and the page
+commits without waiting for it. A navigation into the layout runs it. A layout
+loader that reads the route's params needs a rule that re-runs it:
+`revalidate(({ currentParams, nextParams, defaultShouldRevalidate }) =>
+currentParams.slug !== nextParams.slug ? true : defaultShouldRevalidate)`.
+
 Two scars worth copying:
 
 - A blunt `() => false` keeps serving the OLD product on product→product
@@ -455,7 +467,11 @@ makes the first flush, and `ssr: false` guarantees the loader's data does. It
 does not cover the client component's module: the first document a build's
 fresh server renders can still be waiting for it. The dev server matches a
 build here: when the shell is ready, it waits for the client components the
-payload has named and that are still loading, and for nothing else.
+payload has named and that are still loading, and for nothing else. On a
+document with an `ssr: false` loader, a part React finishes a moment after the
+shell, such as a `useActionState` form (React suspends it once to encode its
+action), is in the first flush too: the router gives React up to three more
+turns before it, and none when the document is already complete.
 
 ## `prefetch: false` — keep a loader out of prefetches
 
@@ -477,10 +493,16 @@ too, `useOutlet().pending` ends with that commit, and one follow-up request
 own `<Suspense>` to show the page and that fallback at once; with no boundary
 React holds the page being left until the fill answers, as it would with no
 prefetch. Same rules as on a server route (`/loader` → "`prefetch: false`"):
-only a segment new to the page is deferred, so a same-route click
-(`/product/a` to `/product/b`) prefetches the loader as usual.
-
-- On a `layout()` of the group the flag applies to every route below it.
+the flag skips a loader in a prefetch only when the loader is new to the page.
+A loader already on screen is never deferred: if its revalidation (its
+`revalidate()` or the default) re-runs it, it runs in the prefetch with the
+rest of the destination; otherwise it is held. A same-route click
+(`/product/a` to `/product/b`) is the familiar case.
+
+- A group `layout()` loader is on screen on every route of its layout: a
+  prefetch between two of them defers nothing for it (its `revalidate()`
+  decides, and with no rule it is held), and a prefetch that enters the
+  layout defers it.
 - A flagged `loader()` on a server layout above the group is deferred while
   that layout is new to the page (entering the group from outside).
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
@@ -529,8 +551,9 @@ a hard load of the target URL renders the full route.
   `loading()` does not re-flash there. Across different routes, a `layout()`
   keeps its instance while the navigation stays under it, and its own
   `layout()` loaders keep their data on the optimistic frame (a cart count does
-  not suspend); only the destination's loaders and those of layouts it mounts
-  anew wait for the server. `transition()` is not needed for the
+  not suspend), and in the canonical commit when their `revalidate()` holds
+  them; only the destination's loaders and those of layouts it mounts anew
+  wait for the server. `transition()` is not needed for the
   hold; it adds the view-transition animation. Inline `<Suspense>` above each
   `useLoader` read is still the finer-grained tool when different reads on
   one route should wait independently.

package/skills/loader/SKILL.md

@@ -1128,10 +1128,13 @@ What happens:
 - A **prefetch** of the route does not run the loader and does not read its
   `cache()`; the payload marks it deferred. The rest of the page prefetches as
   usual.
-- Only on a route the browser does not show yet. A loader the page already
-  holds, on a same-route navigation such as `/product/a` to `/product/b`, runs
-  in the prefetch when it revalidates, exactly as without the flag, and the
-  click sends no second request. The rule: a click that adopts a prefetch is
+- Only on a loader new to the page. A loader already on screen is never
+  deferred: if its revalidation (its `revalidate()` or the default) re-runs
+  it, it runs in the prefetch with the rest of the destination, exactly as
+  without the flag, and the click sends no second request; otherwise it is
+  held. The familiar case is a same-route navigation such as `/product/a` to
+  `/product/b`; a `clientUrls()` group `layout()` loader is on screen on every
+  route of its layout the same way. The rule: a click that adopts a prefetch is
   never worse than the same click with no prefetch at all (one exception: a
   click before its prefetch has answered, under "The limits"), and content on
   screen is never swapped for a fallback because of the flag. For the same

package/src/browser/segment-reconciler.ts

@@ -87,6 +87,19 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
   const diffSet = new Set(diff);
+  // A clientUrls() layout() loader the server held on a navigation between
+  // two routes of the layout (client-urls/layout-loader-copies.ts): matched
+  // names it under the destination route, the page holds it under the group
+  // route it leaves. Its copy keeps its data under the new id.
+  const origin = input.cachedSegments.find((s) => s.clientGroup);
+  const destination =
+    origin &&
+    input.serverSegments.find((s) => s.clientGroup === origin.clientGroup);
+  const carried = (id: string) => {
+    const copy =
+      destination && cachedSegments.get(id.replace(destination.id, origin.id));
+    return copy && { ...copy, id };
+  };
   if (IS_BROWSER_DEBUG) {
     debugLog(
       `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
@@ -102,7 +115,7 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const segments = matched
     .map((segId: string) => {
       const fromServer = serverSegments.get(segId);
-      const fromCache = cachedSegments.get(segId);
+      let fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
         const inDiff = diffSet.has(segId);
@@ -179,6 +192,7 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
       }
 
       // Fall back to cached segment (server expects client to already have it)
+      fromCache ??= carried(segId);
       if (!fromCache) {
         if (actor === "action") {
           console.error(`[Browser] MISSING SEGMENT: ${segId} not in cache!`);

package/src/client-urls/layout-loader-copies.ts

@@ -0,0 +1,56 @@
+import type { EntryData } from "../server/context.js";
+import type { LoaderDefinition } from "../types.js";
+
+/**
+ * A clientUrls() layout()'s loaders are copied into every route record below
+ * it (client-urls.ts applyConfig), and a loader segment's id names its route
+ * (`${routeShortCode}D${index}.${$$id}`). On a navigation between two of the
+ * layout's routes the destination's copy was a segment the client lacked, so
+ * it ran whatever its revalidate() said.
+ *
+ * Materialization (server-projection.ts) records, for each copy, the ids the
+ * same layout() loader has under the group's other routes of that layout. A
+ * request whose page holds one of them holds the destination's copy: the
+ * loader's revalidate() decides, as on a param navigation, and a held copy is
+ * left out of the response. The browser carries the page's copy to the id
+ * `matched` names (browser/segment-reconciler.ts) with its handle pushes
+ * (handles/pushed-by.ts).
+ *
+ * A copy takes a server layout's revalidation default, not its route's: held
+ * on a navigation, params or search changes included, and re-run on an action
+ * (isLayoutLoaderCopy, segment-resolution/revalidation.ts).
+ *
+ * Keyed by the materialized loader stub, created once per evaluation of the
+ * route: the ids depend on the route's shortCode and its siblings'.
+ */
+const copies = new WeakMap<LoaderDefinition<any>, readonly string[]>();
+
+export function setLayoutLoaderCopies(
+  stub: LoaderDefinition<any>,
+  ids: readonly string[],
+): void {
+  copies.set(stub, ids);
+}
+
+/** True for the materialized stub of a clientUrls() layout() loader copy. */
+export function isLayoutLoaderCopy(stub: LoaderDefinition<any>): boolean {
+  return copies.has(stub);
+}
+
+/**
+ * `held` with the id of each of `route`'s layout() loader copies whose
+ * loader the page holds under another route of the layout; `held` itself
+ * when there is none.
+ */
+export function withLayoutLoaderCopies(
+  held: ReadonlySet<string>,
+  route: EntryData,
+): ReadonlySet<string> {
+  let out: Set<string> | undefined;
+  route.loader?.forEach(({ loader }, index) => {
+    if (copies.get(loader)?.some((id) => held.has(id))) {
+      (out ??= new Set(held)).add(`${route.shortCode}D${index}.${loader.$$id}`);
+    }
+  });
+  return out ?? held;
+}

package/src/client-urls/server-projection.ts

@@ -2,8 +2,10 @@ import * as React from "react";
 import type { SearchSchemaValue } from "../search-params.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
 import {
+  getContext,
   getNamePrefix,
   getUrlPrefix,
+  peekShortCode,
   type InterceptSelectorContext,
 } from "../server/context.js";
 import type {
@@ -21,6 +23,7 @@ import type { AllUseItems } from "../route-types.js";
 import { urls } from "../urls/urls-function.js";
 import { isHoistedRevalidateRef } from "./hoisted-revalidate.js";
 import { getClientUrlRevalidator } from "./revalidate-registry.js";
+import { setLayoutLoaderCopies } from "./layout-loader-copies.js";
 import {
   ClientUrlsGroupLayout,
   ClientUrlsInterceptLoading,
@@ -32,6 +35,7 @@ import { createClientUrlsWhenRef } from "../transition-when-ref.js";
 import type {
   ClientTransitionConfig,
   ClientUrlInterceptRecord,
+  ClientUrlLoaderRecord,
   ClientUrlPatterns,
   ClientUrlRouteRecord,
 } from "./types.js";
@@ -106,6 +110,11 @@ export interface ClientUrlProjectionRoute {
    *  the registered predicates (revalidate-registry.ts). Absent when no
    *  loader declares one. */
   readonly loaderRevalidate?: readonly (readonly string[])[];
+  /** One per leading loader its layout()s declare
+   *  (ClientUrlRouteRecord.layoutLoaders): the record's ordinal in the
+   *  definition. Two routes whose loader at an index carries the same ordinal
+   *  hold one layout() loader (layout-loader-copies.ts). Absent when none. */
+  readonly layoutLoaders?: readonly number[];
   /** Data-only transition config (never `when`); absent in projections
    *  serialized before transition support. */
   readonly transition?: Readonly<ClientTransitionConfig>;
@@ -299,7 +308,13 @@ function indicesWhere<T>(
 function serializeRoute(
   route: ClientUrlRouteRecord,
   options: SerializeClientUrlPatternsOptions,
+  ordinals: Map<ClientUrlLoaderRecord, number>,
 ): ClientUrlProjectionRoute {
+  // flattenLayout creates a layout()'s records once for every route below it.
+  const layoutLoaders = route.layoutLoaders.map((record) => {
+    if (!ordinals.has(record)) ordinals.set(record, ordinals.size);
+    return ordinals.get(record)!;
+  });
   const loaderIds = route.loaders.map(({ loader }, index) => {
     if (typeof loader.$$id !== "string" || loader.$$id.length === 0) {
       throw projectionError(
@@ -355,6 +370,9 @@ function serializeRoute(
           ),
         }
       : {}),
+    ...(layoutLoaders.length > 0
+      ? { layoutLoaders: Object.freeze(layoutLoaders) }
+      : {}),
     ...(transition ? { transition } : {}),
     ...(typeof route.transition?.when === "function"
       ? { transitionWhen: true as const }
@@ -388,10 +406,11 @@ export function serializeClientUrlPatterns(
   patterns: ClientUrlPatterns,
   options: SerializeClientUrlPatternsOptions = {},
 ): ClientUrlProjection {
+  const ordinals = new Map<ClientUrlLoaderRecord, number>();
   return Object.freeze({
     version: 1 as const,
     routes: Object.freeze(
-      patterns.routes.map((route) => serializeRoute(route, options)),
+      patterns.routes.map((route) => serializeRoute(route, options, ordinals)),
     ),
     intercepts: Object.freeze(
       (patterns.intercepts ?? []).map(serializeIntercept),
@@ -613,9 +632,39 @@ function materializeRouteItems(
   // builders must run where the items belong: at the module top level for the
   // flat (no-intercept) shape, or inside the group layout's children callback
   // when intercepts wrap the group.
-  const buildRouteItems = (): AllUseItems[] =>
-    projection.routes.map(
-      (route) =>
+  const buildRouteItems = (): AllUseItems[] => {
+    // Each route's shortCode, read before path() takes them: one per route,
+    // in order, from the same counter. An evaluation for one route skips the
+    // others' entries, not their codes.
+    const codes = projection.routes.map((_, ahead) =>
+      peekShortCode("route", ahead),
+    );
+    // A route's use(), recording each layout() loader copy's ids under the
+    // other routes of its layout() (layout-loader-copies.ts). path() runs it
+    // with the route entry as parent, whose loaders it has created on return.
+    const recordingCopies =
+      <T>(routeIndex: number, use: () => T) =>
+      (): T => {
+        const items = use();
+        const entry = getContext().getParent()!;
+        projection.routes[routeIndex].layoutLoaders?.forEach(
+          (ordinal, loaderIndex) =>
+            setLayoutLoaderCopies(
+              entry.loader[loaderIndex].loader,
+              projection.routes.flatMap((other, otherIndex) =>
+                otherIndex !== routeIndex &&
+                other.layoutLoaders?.[loaderIndex] === ordinal
+                  ? [
+                      `${codes[otherIndex]}D${loaderIndex}.${other.loaderIds[loaderIndex]}`,
+                    ]
+                  : [],
+              ),
+            ),
+        );
+        return items;
+      };
+    return projection.routes.map(
+      (route, routeIndex) =>
         path(
           route.pattern,
           () =>
@@ -625,7 +674,7 @@ function materializeRouteItems(
               namePrefix,
             }),
           materializedPathOptions(route, clientGroup),
-          () => [
+          recordingCopies(routeIndex, () => [
             ...route.loaderIds.map((id, loaderIndex) => {
               const revalidators = loaderRevalidators(
                 reference,
@@ -669,9 +718,10 @@ function materializeRouteItems(
                   }),
                 ]
               : []),
-          ],
+          ]),
         ) as AllUseItems,
     );
+  };
 
   const intercepts = projection.intercepts ?? [];
   if (intercepts.length === 0) return buildRouteItems();

package/src/handles/pushed-by.ts

@@ -89,6 +89,13 @@ export function withSegmentHandles(
  * the position of the first value they replace (the end when they replace
  * none). New containers throughout: an object a reader was handed (a history
  * entry's data) is never written to.
+ *
+ * A segment with no values of a handle takes, for each loader `matched`
+ * registers on it that did not run, the values that loader pushed under a
+ * segment the page leaves, a slot excepted: a clientUrls() layout() loader the
+ * server held on a navigation between two routes of the layout
+ * (client-urls/layout-loader-copies.ts), whose pushes the page filed under
+ * the route it leaves.
  */
 export function mergePartialHandleData(
   current: HandleData,
@@ -109,13 +116,31 @@ export function mergePartialHandleData(
     if (isPushedByKey(name)) continue;
     const byName = pushedByKey(name);
     const buckets: Record<string, unknown[]> = (out[name] = {});
-    for (const segmentId of keysOf(current[name], incoming[name])) {
-      if (!inOrder.has(segmentId)) continue;
+    for (const segmentId of segmentOrder) {
       const run = (by: PushedBy, i: number): string => {
         const key = `${segmentId}\u0000${by?.[i]}`;
         return registered.has(key) ? key : segmentId;
       };
-      const currentBy = current[byName]?.[segmentId] as PushedBy;
+      let currentValues = current[name]?.[segmentId];
+      let currentBy = current[byName]?.[segmentId] as PushedBy;
+      if (!currentValues) {
+        // A loader's values from a segment the page leaves; one that ran for
+        // this response replaces them below, like any of its values. Never
+        // from a slot (".@"): an intercept's or a parallel's own copy of the
+        // loader pushed those.
+        const carried: unknown[] = (currentValues = []);
+        const carriedBy: (string | null)[] = [];
+        for (const from in current[byName]) {
+          if (inOrder.has(from) || from.includes(".@")) continue;
+          current[byName][from].forEach((_, i, runs) => {
+            const key = run(runs as PushedBy, i);
+            if (key === segmentId) return;
+            carried.push(current[name][from][i]);
+            carriedBy.push(runs[i] as string);
+          });
+        }
+        currentBy = carriedBy;
+      }
       const incomingValues = incoming[name]?.[segmentId] ?? [];
       const incomingBy = incoming[byName]?.[segmentId] as PushedBy;
       const delivered = new Set(
@@ -124,7 +149,7 @@ export function mergePartialHandleData(
       const values: unknown[] = [];
       const by: (string | null)[] = [];
       let at = -1;
-      (current[name]?.[segmentId] ?? []).forEach((value, i) => {
+      currentValues.forEach((value, i) => {
         const key = run(currentBy, i);
         if (delivered.has(key) || ran.has(key)) {
           if (at < 0) at = values.length;

package/src/router/match-api.ts

@@ -54,6 +54,7 @@ import {
   type RouteSnapshot,
 } from "./route-snapshot.js";
 import { resolveNavigation } from "./navigation-snapshot.js";
+import { withLayoutLoaderCopies } from "../client-urls/layout-loader-copies.js";
 import {
   partialDeferralMode,
   planPrefetchDeferral,
@@ -419,9 +420,16 @@ export async function createMatchContextForPartial<TEnv>(
             )
           : null);
 
+  // The page's copy of a clientUrls() layout() loader under the route it
+  // leaves holds the destination route's (client-urls/layout-loader-copies.ts).
+  const held = withLayoutLoaderCopies(
+    nav.clientSegmentSet,
+    snapshot.manifestEntry,
+  );
+
   // Make a mutable copy of clientSegmentSet so we can delete entries
   // for same-route navigation forcing
-  const clientSegmentSet = new Set(nav.clientSegmentSet);
+  const clientSegmentSet = new Set(held);
 
   if (
     nav.isSameRouteNavigation &&
@@ -481,9 +489,9 @@ export async function createMatchContextForPartial<TEnv>(
     }),
     matched,
     cacheScope,
-    // As the request listed them, not the copy forced above: see
+    // What the page holds, not the copy forced above: see
     // prefetch-deferral.ts.
-    nav.clientSegmentSet,
+    held,
   );
   (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
     deferral;

package/src/router/segment-resolution/revalidation.ts

@@ -55,6 +55,7 @@ import {
   buildLoaderErrorContext,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
+import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
 import { runInSegmentTagScope } from "../../cache/cache-tag.js";
@@ -254,7 +255,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               component: null,
               params: ctx.params,
               loaderId: loader.$$id,
-              belongsToRoute,
+              // A clientUrls() layout() loader's copy is projected onto the
+              // route but owned by a layout: it takes a layout's default.
+              belongsToRoute: belongsToRoute && !isLayoutLoaderCopy(loader),
             };
 
             return await revalidateHeld({

package/src/server/context.ts

@@ -445,6 +445,53 @@ function bumpCounter(store: HelperContext, key: string): number {
   return store.counters[key]++;
 }
 
+type ShortCodeType = "layout" | "parallel" | "route" | "loader" | "cache";
+
+/**
+ * The next shortCode of `type` under the store's parent, which `take`
+ * consumes; a peek may look `ahead` past it. A root entry is prefixed with the
+ * mount index and counted per mount. A child is counted per parent with
+ * includeScope appended: while a lazy include's direct children evaluate,
+ * includeScope is a per-include token like "I0" / "I1I0" that partitions the
+ * parent's counter namespace so routes inside one include cannot collide with
+ * siblings declared outside it.
+ */
+function nextShortCode(
+  store: HelperContext,
+  type: ShortCodeType,
+  take: boolean,
+  ahead = 0,
+): string {
+  const parent = store.parent;
+  const prefix = SHORT_CODE_PREFIX[type];
+  const mountPrefix =
+    store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
+  const includeScope = store.includeScope ?? "";
+  const counterKey = parent
+    ? `${parent.shortCode}${includeScope}_${type}`
+    : mountPrefix
+      ? `${mountPrefix}_root_${type}`
+      : `root_${type}`;
+  const index = take
+    ? bumpCounter(store, counterKey)
+    : (store.counters[counterKey] ?? 0) + ahead;
+  return parent
+    ? `${parent.shortCode}${includeScope}${prefix}${index}`
+    : `${mountPrefix}${prefix}${index}`;
+}
+
+/**
+ * The shortCode the `ahead`-th next `getShortCode(type)` call in this DSL
+ * context returns, without taking it. clientUrls() materialization reads the
+ * code of every group route this way, including the routes an evaluation for
+ * another route skips (client-urls/layout-loader-copies.ts).
+ */
+export function peekShortCode(type: ShortCodeType, ahead: number): string {
+  const store = RangoContext.getStore();
+  invariant(store, "No context RangoContext available");
+  return nextShortCode(store, type, false, ahead);
+}
+
 export const getContext = (): {
   context: AsyncLocalStorage<HelperContext>;
   getStore: () => HelperContext;
@@ -522,29 +569,7 @@ export const getContext = (): {
     ) => {
       const store = context.getStore();
       invariant(store, "No context RangoContext available");
-
-      const parent = store.parent;
-      const prefix = SHORT_CODE_PREFIX[type];
-      const mountPrefix =
-        store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
-
-      const includeScope = store.includeScope ?? "";
-
-      if (!parent) {
-        // Root entry: prefix with mount index and use mount-scoped counter
-        const counterKey = mountPrefix
-          ? `${mountPrefix}_root_${type}`
-          : `root_${type}`;
-        return `${mountPrefix}${prefix}${bumpCounter(store, counterKey)}`;
-      } else {
-        // Child entry: use parent-scoped counter with includeScope appended.
-        // When we're evaluating a lazy include's direct children, includeScope
-        // is a per-include token like "I0" / "I1I0" that partitions the
-        // parent's counter namespace so routes inside one include cannot
-        // collide with siblings declared outside it.
-        const counterKey = `${parent.shortCode}${includeScope}_${type}`;
-        return `${parent.shortCode}${includeScope}${prefix}${bumpCounter(store, counterKey)}`;
-      }
+      return nextShortCode(store, type, true);
     },
     runWithStore: <T>(
       store: HelperContext,

package/src/ssr/index.tsx

@@ -403,6 +403,62 @@ function trackDocumentClientLoads<T>(decode: () => T): {
   };
 }
 
+/**
+ * Cap on settleSsrFalseFirstFlush's turns. Each turn retries one generation of
+ * tasks parked on thenables that settle in microtasks. A useActionState form
+ * is one generation (the Flight client caches the encoding, so the retry
+ * encodes synchronously); a formAction button inside it renders on that retry
+ * and is a second; the same form behind `lazy()` adds a third. ssr-handler
+ * tests pin all three. A deeper chain flushes its fallback as before.
+ */
+const SSR_FALSE_FIRST_FLUSH_TURNS = 3;
+
+/**
+ * True when the matched chain has a `loader(Def, { ssr: false })` entry: its
+ * payload segments carry `awaitBeforeFlush` (fresh.ts).
+ */
+function hasAwaitBeforeFlush(payload: {
+  metadata?: { segments?: readonly { awaitBeforeFlush?: true }[] };
+}): boolean {
+  return payload.metadata?.segments?.some((s) => s.awaitBeforeFlush) === true;
+}
+
+/**
+ * ssr: false documents only: before the first flush, give Fizz the turns a
+ * task waiting on an already-settling thenable needs, so a boundary that
+ * waits on nothing else completes in place (#1138).
+ *
+ * Fizz's useActionState binds its state onto the action, and the
+ * `<form action>` encode of that bound server reference throws the Flight
+ * client's encodeFormData thenable once (defaultEncodeFormAction). It settles
+ * in microtasks, but once the request has left its opening status, Fizz's
+ * pingTask retries the task on a setTimeout(0) turn. renderToReadableStream
+ * resolves at shell-ready, so the first read would flush the boundary's
+ * fallback before that turn, which a browser without JavaScript keeps (the
+ * form lands in `<div hidden id="S:n">`).
+ *
+ * A document already whole (allReady settled) returns with no macrotask.
+ * Otherwise one setTimeout(0) at a time until allReady, at most
+ * SSR_FALSE_FIRST_FLUSH_TURNS: a timer set after Fizz's ping fires after it.
+ * A boundary waiting on I/O (an unflagged loader, a streamed promise) still
+ * streams its fallback, after at most that many turns.
+ */
+async function settleSsrFalseFirstFlush(
+  allReady: Promise<void>,
+): Promise<void> {
+  let whole = false;
+  const settle = (): void => {
+    whole = true;
+  };
+  // Promise.resolve: a stub renderer's stream may carry no allReady.
+  Promise.resolve(allReady).then(settle, settle);
+  // A settled allReady's reaction was queued before this continuation's.
+  await Promise.resolve();
+  for (let turn = 0; !whole && turn < SSR_FALSE_FIRST_FLUSH_TURNS; turn++) {
+    await macrotask();
+  }
+}
+
 /**
  * Route an SSR error through the deps.onError notification callback with the
  * "rendering" phase. Swallows callback failures so a broken reporter never
@@ -832,13 +888,10 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
       // <html> until this same promise settles. A rejection lands in the
       // catch below — the same reportRenderError path a shell error takes.
-      let progressiveChunkSize = deps.progressiveChunkSize;
-      if (progressiveChunkSize === undefined) {
-        const resolved = await payload;
-        if (resolved.metadata?.segments?.some((s) => s.awaitBeforeFlush)) {
-          progressiveChunkSize = Number.MAX_SAFE_INTEGER;
-        }
-      }
+      const awaitsBeforeFlush = hasAwaitBeforeFlush(await payload);
+      const progressiveChunkSize =
+        deps.progressiveChunkSize ??
+        (awaitsBeforeFlush ? Number.MAX_SAFE_INTEGER : undefined);
 
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
@@ -870,6 +923,9 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // cannot process streamed HTML.
       if (streamMode === "allReady") {
         await htmlStream.allReady;
+      } else if (awaitsBeforeFlush) {
+        // The shell rendered from the payload, so it has settled.
+        await settleSsrFalseFirstFlush(htmlStream.allReady);
       }
 
       // The entry's Fizz hint at default priority, after the head chunk