@rangojs/router 0.5.2 → 0.7.0

package/src/router/route-trie-builder.ts

@@ -0,0 +1,334 @@
+/**
+ * Runtime Route Trie Construction
+ *
+ * Builds a serializable trie from route manifest data for O(path_length)
+ * route matching at runtime.
+ */
+
+import { parsePattern, type ParsedSegment } from "./parse-pattern.js";
+
+// -- Trie data structures (compact keys for JSON serialization) --
+
+/**
+ * A response-type variant folded into a primary leaf's negotiate list. `pa` is
+ * the variant's own positional param-name array, carried so the runtime can
+ * re-key the matched params under the variant's names when it wins negotiation
+ * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
+ * variant has no params; absent/identical pa means no re-key is needed.
+ */
+export interface NegotiateVariant {
+  routeKey: string;
+  responseType: string;
+  pa?: string[];
+}
+
+export interface TrieLeaf {
+  /** Route name (e.g., "site.l1_500") */
+  n: string;
+  /** Static prefix of the entry (e.g., "/site") */
+  sp: string;
+  /** Constraint validation: paramName -> allowed values */
+  cv?: Record<string, string[]>;
+  /** Ordered param names for this route (positional) */
+  pa?: string[];
+  /** Trailing slash mode */
+  ts?: string;
+  /** Route has pre-rendered data available */
+  pr?: true;
+  /** Passthrough: handler kept in bundle for live fallback on unknown params */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  rt?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  nv?: NegotiateVariant[];
+  /** RSC-first: RSC route was defined before response-type variants */
+  rf?: true;
+}
+
+export interface TrieNode {
+  /** Route terminal at this node */
+  r?: TrieLeaf;
+  /** Static segment children */
+  s?: Record<string, TrieNode>;
+  /** Param child: { n: paramName, c: child node } */
+  p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" -> { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
+  /**
+   * Wildcard terminal: leaf + paramName (`pn`). `pn` is "*" for the bare `/*`
+   * form and the param name for a named catch-all (`:name+`/`:name*`). `w1`
+   * marks a one-or-more catch-all (`:name+`): the runtime walker then rejects
+   * the zero-segment/empty-remainder case. Absent `w1` is zero-or-more.
+   */
+  w?: TrieLeaf & { pn: string; w1?: true };
+}
+
+/**
+ * Build a route trie from route manifest data.
+ *
+ * @param routeManifest - Map of route name to full URL pattern
+ * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
+ * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
+ * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
+ * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
+ */
+export function buildRouteTrie(
+  routeManifest: Record<string, string>,
+  routeToStaticPrefix: Record<string, string>,
+  routeTrailingSlash?: Record<string, string>,
+  prerenderRouteNames?: Set<string>,
+  passthroughRouteNames?: Set<string>,
+  responseTypeRoutes?: Record<string, string>,
+): TrieNode {
+  const root: TrieNode = {};
+
+  for (const [routeName, pattern] of Object.entries(routeManifest)) {
+    const staticPrefix = routeToStaticPrefix[routeName] || "";
+    const trailingSlash = routeTrailingSlash?.[routeName];
+    const responseType = responseTypeRoutes?.[routeName];
+
+    // Detect and strip trailing slash from pattern for parsing
+    const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    const normalizedPattern = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+
+    const segments = parsePattern(normalizedPattern);
+    insertRoute(root, segments, 0, {
+      n: routeName,
+      sp: staticPrefix,
+      ...(trailingSlash ? { ts: trailingSlash } : {}),
+      ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
+      ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
+      ...(responseType ? { rt: responseType } : {}),
+    });
+  }
+
+  sortSuffixParams(root);
+  return root;
+}
+
+/**
+ * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
+ * the matcher tries the most specific suffix first. Overlapping suffixes like
+ * `.min.js` and `.js` must resolve by specificity, not route declaration order:
+ * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
+ *
+ * This started as a bug - `walkTrie` iterates `node.xp` in object order and
+ * returns the first suffix the segment ends with, so the winner depended on
+ * which route was declared first. Sorting at build time fixes it allocation-free
+ * on the match hot path: the serialized production trie preserves this key order
+ * through JSON.parse, so dev (per-request rebuild) and production match
+ * identically. Array.prototype.sort is stable (ES2019+), so equal-length
+ * suffixes keep their declaration order - the router's existing tiebreak.
+ */
+function sortSuffixParams(node: TrieNode): void {
+  if (node.xp) {
+    const sorted: Record<string, { n: string; c: TrieNode }> = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length,
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+}
+
+/**
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` - the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
+ */
+function insertRoute(
+  node: TrieNode,
+  segments: ParsedSegment[],
+  index: number,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
+): void {
+  // cv (full constraint map) is route-level and identical on every terminal,
+  // so compute it once on the shared base.
+  const constraints: Record<string, string[]> = {};
+
+  for (const seg of segments) {
+    if (seg.type === "param") {
+      if (seg.constraint) {
+        constraints[seg.value] = seg.constraint;
+      }
+    }
+  }
+
+  const leafBase: Omit<TrieLeaf, "pa"> = {
+    ...leaf,
+    ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
+  };
+
+  insertSegments(node, segments, index, leafBase, []);
+}
+
+/**
+ * Build a negotiate-variant entry from a leaf being folded into another leaf's
+ * nv list. Carries the variant's positional param names (`pa`) so the runtime
+ * can re-key matched params under the variant's names; omitted when the variant
+ * has none (the common case where primary and variant share the same names is a
+ * no-op re-key regardless).
+ */
+function toVariant(leaf: TrieLeaf, responseType: string): NegotiateVariant {
+  return leaf.pa
+    ? { routeKey: leaf.n, responseType, pa: leaf.pa }
+    : { routeKey: leaf.n, responseType };
+}
+
+/**
+ * Merge a new leaf with an existing leaf, handling content negotiation.
+ * When an RSC route and response-type routes share the same URL pattern,
+ * the RSC route becomes the primary leaf and response-type routes are
+ * appended to the nv (negotiate variants) array.
+ * Multiple response types on the same path are supported (json + text + xml).
+ */
+function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
+  if (!existing) return leaf;
+
+  if (existing.rt && leaf.rt) {
+    // Both are response-type: preserve old as variant
+    const merged = leaf;
+    merged.nv = existing.nv || [];
+    merged.nv.push(toVariant(existing, existing.rt));
+    return merged;
+  }
+  if (leaf.rt && !existing.rt) {
+    // RSC primary exists, new leaf is response-type: append variant
+    // RSC was defined first (it was already the existing leaf)
+    if (!existing.nv) {
+      existing.nv = [];
+      existing.rf = true;
+    }
+    existing.nv.push(toVariant(leaf, leaf.rt));
+    return existing;
+  }
+  if (!leaf.rt && existing.rt) {
+    // Response-type was primary, new leaf is RSC: swap and move old to variants
+    // RSC was defined second (response-type was already the existing leaf)
+    if (!leaf.nv) leaf.nv = [];
+    if (existing.nv) leaf.nv.push(...existing.nv);
+    leaf.nv.push(toVariant(existing, existing.rt));
+    // rf intentionally not set - RSC came after response-type variants
+    return leaf;
+  }
+  // Both RSC (last wins): overwrite
+  return leaf;
+}
+
+function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
+  node.r = mergeLeaves(node.r, leaf);
+}
+
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
+function insertSegments(
+  node: TrieNode,
+  segments: ParsedSegment[],
+  index: number,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): void {
+  // Base case: all segments consumed, add terminal with branch-local pa
+  if (index >= segments.length) {
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
+    return;
+  }
+
+  const segment = segments[index];
+
+  if (segment.type === "static") {
+    if (!node.s) node.s = {};
+    if (!node.s[segment.value]) node.s[segment.value] = {};
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
+  } else if (segment.type === "param") {
+    if (segment.optional) {
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
+    }
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
+    }
+  } else if (segment.type === "wildcard") {
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    // `pn` is "*" for the bare `/*` and the param name for a named catch-all;
+    // `w1` marks the one-or-more variant (`:name+`) so the walker rejects the
+    // empty-remainder case.
+    const wildLeaf: TrieLeaf & { pn: string; w1?: true } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: segment.value,
+      ...(segment.oneOrMore ? { w1: true as const } : {}),
+    };
+    const existing = node.w;
+    // Merge when there's no existing wildcard, when this is a response-type
+    // content-negotiation variant of the same catch-all (one side carries `rt`),
+    // or when it's the SAME catch-all identity (same param name + arity).
+    // Otherwise two DISTINCT catch-all forms (`/x/*` vs `/x/:p+`) would collide on
+    // the single wildcard slot with no non-lossy merge - so keep the first-declared
+    // (matching the regex matcher's declaration-order tiebreak) rather than let
+    // mergeLeaves' last-wins overwrite silently drop its `pn`/`w1` identity (which
+    // stranded the first route and fell through to a corrupt regex-fallback redirect).
+    const canMerge =
+      existing === undefined ||
+      Boolean(existing.rt) ||
+      Boolean(wildLeaf.rt) ||
+      (existing.pn === wildLeaf.pn &&
+        Boolean(existing.w1) === Boolean(wildLeaf.w1));
+    if (canMerge) {
+      const merged = mergeLeaves(
+        existing ? ({ ...existing } as TrieLeaf) : undefined,
+        wildLeaf,
+      );
+      node.w = merged as TrieLeaf & { pn: string; w1?: true };
+    }
+  }
+}

package/src/router/router-interfaces.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { ClientUrlPatterns } from "../client-urls/types.js";
 import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
@@ -29,6 +30,12 @@ export interface RouterRequestInput<TEnv, TVars = DefaultVars> {
   ctx?: ExecutionContext;
 }
 
+/** One materialized UrlPatterns registration and its live router mount index. */
+export interface UrlPatternMount<TEnv = any> {
+  readonly patterns: UrlPatterns<TEnv, any>;
+  readonly mountIndex: number;
+}
+
 /**
  * Merge route patterns with response types into a single route map.
  * Routes with response types get { path, response } objects; others stay as strings.
@@ -100,6 +107,20 @@ export interface Rango<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  /**
+   * Pure-client mounting shorthand: normalizes to a root include in the
+   * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+   * lazy materialization as mounting through include() yourself.
+   */
+  routes<T extends ClientUrlPatterns<any>>(
+    patterns: T,
+  ): Rango<
+    TEnv,
+    TRoutes &
+      (NonNullable<T["_routes"]> extends Record<string, unknown>
+        ? NonNullable<T["_routes"]>
+        : Record<string, string>)
+  >;
   routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
@@ -230,8 +251,25 @@ export interface RangoInternal<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  /**
+   * Pure-client mounting shorthand: normalizes to a root include in the
+   * canonical urls() tree (`include("/", definition, { name: "" })`) — same
+   * lazy materialization as mounting through include() yourself.
+   */
+  routes<T extends ClientUrlPatterns<any>>(
+    patterns: T,
+  ): Rango<
+    TEnv,
+    TRoutes &
+      (NonNullable<T["_routes"]> extends Record<string, unknown>
+        ? NonNullable<T["_routes"]>
+        : Record<string, string>)
+  >;
   routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
+  /** Materialized UrlPatterns registrations in registration order. */
+  readonly __urlpatternMounts: readonly UrlPatternMount<TEnv>[];
+
   /**
    * Add global middleware that runs on all routes
    */

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

@@ -33,6 +33,7 @@ import {
   buildLoaderErrorContext,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import { observeHandler } from "../instrument.js";
@@ -63,6 +64,17 @@ export async function resolveLoaders<TEnv>(
   if (loaderEntries.length === 0) return [];
 
   const shortCode = shortCodeOverride ?? entry.shortCode;
+
+  // Pin `_currentSegmentId` to the OWNING entry BEFORE the loader kickoffs:
+  // createLoaderExecutor captures it synchronously at kickoff for
+  // ctx.use(Handle) push attribution (loader writes land in the same bucket
+  // as the entry's handler pushes — shortCode is in matched/segmentOrder, so
+  // collectHandleData keeps them; an id outside the order is silently
+  // dropped). resolveLoaders runs BEFORE the handler-resolution sites assign
+  // this (fresh.ts handler-first ordering), so without the pin the captured
+  // value is a stale sibling's id (document lane) or undefined (navigation
+  // lane — pushes silently vanished).
+  (ctx as InternalHandlerContext<any, TEnv>)._currentSegmentId = shortCode;
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
 
@@ -92,6 +104,32 @@ export async function resolveLoaders<TEnv>(
   const errorContext = buildLoaderErrorContext(ctx);
 
   if (emitStreaming) {
+    // awaitBeforeFlush (loader(Def, { stream: "navigation" })): document
+    // renders await these loaders before returning, so their data is settled,
+    // their handle pushes beat the barrier snapshot, and a thrown notFound()'s
+    // status write deterministically precedes Response construction. The ids
+    // must register on the request context BEFORE kickoff — rendered() checks
+    // the set to fail fast on the barrier cycle (segment resolution awaits the
+    // loader, the barrier awaits segment resolution, rendered() awaits the
+    // barrier), and the loader body can call rendered() before the await below
+    // is reached. Skipped during shell capture: LIVE-lane loaders are masked
+    // with never-resolving promises there (loader-mask.ts) and would hang.
+    const awaitedIndices: number[] = [];
+    if (!isShellCaptureActive()) {
+      for (let i = 0; i < loaderEntries.length; i++) {
+        if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+      }
+    }
+    if (awaitedIndices.length > 0) {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) {
+        reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+        for (const i of awaitedIndices) {
+          reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+        }
+      }
+    }
+
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
@@ -110,7 +148,13 @@ export async function resolveLoaders<TEnv>(
               loaderEntry,
               ctx,
               ctx.pathname,
-              bakeLane ? segmentId : null,
+              // The bake key rides for flagged loaders too: stream:"navigation"
+              // bakes at capture regardless of the entry's loading() lane
+              // (loader-cache.ts capture branch) and its HIT-tail seed
+              // overlay needs the same key.
+              bakeLane || loaderEntry.awaitBeforeFlush === true
+                ? segmentId
+                : null,
             ),
           ),
           entry,
@@ -122,6 +166,15 @@ export async function resolveLoaders<TEnv>(
       };
     });
 
+    // Await only the flagged loaders; unflagged siblings keep streaming (their
+    // promises were kicked off above and stay pending in the emitted segments).
+    // The wrapped promise is contracted to never reject (wrapLoaderPromise), so
+    // a flagged loader failure resolves with its error envelope and cannot
+    // collapse resolution — same contract the loading-disabled path relies on.
+    if (awaitedIndices.length > 0) {
+      await Promise.all(awaitedIndices.map((i) => segments[i]!.loaderData));
+    }
+
     return segments;
   }
 
@@ -144,7 +197,7 @@ export async function resolveLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          bakeLane ? segmentId : null,
+          bakeLane || loaderEntry.awaitBeforeFlush === true ? segmentId : null,
         ),
       ),
       entry,

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

@@ -8,13 +8,14 @@
  * - Error boundary segment creation
  */
 
-import { createElement, type ReactNode } from "react";
-import { DataNotFoundError } from "../../errors";
+import type { ReactNode } from "react";
+import { isDataNotFoundError } from "../../errors";
 import {
   createErrorInfo,
   createErrorSegment,
   createNotFoundInfo,
   createNotFoundSegment,
+  resolveNotFoundFallback,
 } from "../error-handling.js";
 import { getRequestContext } from "../../server/request-context.js";
 import { DefaultErrorFallback } from "../../default-error-boundary.js";
@@ -252,15 +253,12 @@ export function catchSegmentError<TEnv>(
     }
   };
 
-  if (error instanceof DataNotFoundError) {
-    const notFoundFallback = deps.findNearestNotFoundBoundary(entry);
-    // Fall back to router's notFound component, then a plain default
-    const notFoundOption = deps.notFoundComponent;
-    const defaultFallback =
-      typeof notFoundOption === "function"
-        ? notFoundOption({ pathname: pathname ?? "" })
-        : (notFoundOption ?? createElement("h1", null, "Not Found"));
-    const effectiveNotFoundFallback = notFoundFallback ?? defaultFallback;
+  if (isDataNotFoundError(error)) {
+    const effectiveNotFoundFallback = resolveNotFoundFallback(
+      deps.findNearestNotFoundBoundary(entry),
+      deps.notFoundComponent,
+      pathname,
+    );
 
     const notFoundInfo = createNotFoundInfo(
       error,

package/src/router/segment-resolution/loader-cache.ts

@@ -157,30 +157,41 @@ export function resolveLoaderData<TEnv>(
   //   shell HIT the recorded container is overlaid onto the fresh run so the
   //   payload matches the frozen prelude byte-for-byte.
   if (isShellCaptureActive(reqCtx)) {
-    if (!bakeSegmentKey) {
-      return createMaskedLoaderPromise();
+    // Capture lane, per LOADER (not per entry):
+    //
+    // - `stream: "navigation"` (awaitBeforeFlush) — the BAKE lane. The flag's
+    //   document promise is "this loader's data is in the HTML before first
+    //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
+    //   loader executes at capture and its SETTLED return bakes into the
+    //   shell. Nested-promise SHAPE stays the liveness declaration: nested
+    //   thenables are masked so their subtrees postpone as holes (per-request
+    //   material must be promise-shaped — the #692 cross-session scar). The
+    //   masked container registers on _shellCaptureLoaderRecords: it holds
+    //   the capture gate (bounded by ppr.captureTimeout) and pins into the
+    //   shell snapshot, so a HIT tail replays the baked value and the
+    //   hydration payload matches the frozen prelude byte-for-byte.
+    // - Every other loader — LIVE unconditionally: masked with a
+    //   never-resolving promise, postponed at its boundary (loading() or an
+    //   inline Suspense), streamed fresh per request. A masked reader with NO
+    //   boundary above it root-postpones and the <body> sanity gate refuses
+    //   the shell (eternal-MISS warning) — the degrade for boundary-less ppr
+    //   routes. A route whose loaders are ALL flagged therefore needs no
+    //   loading() at all: nothing masks, the shell captures complete.
+    if (loaderEntry.awaitBeforeFlush && bakeSegmentKey) {
+      const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
+      // Pre-attach a no-op catch: a bake-lane rejection during capture must
+      // surface through the drain's refusal (and the wrapper's error
+      // boundary), never as an unhandled rejection that can kill the worker
+      // before the drain probes this record.
+      containerPromise.catch(() => {});
+      const maskedPromise = containerPromise.then((container: unknown) =>
+        maskNestedContainerThenables(container),
+      );
+      maskedPromise.catch(() => {});
+      reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      return maskedPromise;
     }
-    const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
-    // Pre-attach a no-op catch: a bake-lane rejection during capture must
-    // surface through the drain's refusal (and the wrapper's error boundary),
-    // never as an unhandled rejection that can kill the worker before the
-    // drain probes this record.
-    containerPromise.catch(() => {});
-    // Nested-promise SHAPE is the liveness declaration: mask nested thenables
-    // in the capture's copy of the container so the consuming subtree
-    // postpones as a hole no matter when the promise settles, elide records a
-    // HOLE marker, and every HIT streams the fresh value. Without this, a
-    // nested promise that settled before the quiet window baked its value into
-    // the SHARED shell and the snapshot pinned it for every visitor
-    // (per-request basket data served cross-session, found live). The raw
-    // container is untouched: handler-side ctx.use consumption (the
-    // consumption-lane rule, semantic-matrix PPR3) keeps real values.
-    const maskedPromise = containerPromise.then((container: unknown) =>
-      maskNestedContainerThenables(container),
-    );
-    maskedPromise.catch(() => {});
-    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
-    return maskedPromise;
+    return createMaskedLoaderPromise();
   }
 
   if (bakeSegmentKey) {

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

@@ -42,15 +42,15 @@ export function isShellCaptureActive(
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 
 /**
- * Lane decision for an entry's loaders under PPR (the loading() value decides;
- * docs/design/loader-container-bake.md):
- *
- * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
- *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
- * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
- *   false })` under the SSR manifest) — the BAKE lane: the loader executes
- *   during capture, its settled container bakes, nested pending promises hole
- *   at the consumer's own Suspense. Returns false.
+ * Entry-level lane input for an entry's loaders under PPR (the loading()
+ * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
+ * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
+ * flag's document promise ("data in the HTML before first flush") maps to
+ * the frozen prelude — while every other loader is LIVE (masked at capture,
+ * fresh on every serve), postponing at loading() or an inline Suspense.
+ * This helper still gates which entries pass a bake segment key for the
+ * legacy loading()-less shape and the HIT-tail seed overlay.
  *
  * Mirrors segment-system's isRenderableLoading so the mask decision and the
  * tree's boundary placement can never disagree.