@rangojs/router 0.16.0 → 0.18.0

package/src/client.rsc.tsx

@@ -1,7 +1,7 @@
 /**
  * RSC-environment version of client exports
  *
- * This file is used when importing "rsc-router/client" from RSC (server components).
+ * This file is used when importing "@rangojs/router/client" from RSC (server components).
  * It re-exports the server's createLoader so that loader definitions work in both
  * environments with the same import.
  *
@@ -9,6 +9,10 @@
  * in RSC context, while the regular client.tsx is used in client components.
  */
 
+// From html.ts directly, never via ./client.js: every export of that
+// "use client" module is an opaque client reference here.
+import * as Html from "./html.js";
+
 // Re-export everything from client.tsx (Outlet, useLoader, etc.)
 // These are safe to use in RSC context
 export {
@@ -64,7 +68,10 @@ export {
   useLinkStatus,
   type LinkStatus,
 } from "./browser/react/use-link-status.js";
-export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+export {
+  useScrollRestoration,
+  type ScrollRestorationProps,
+} from "./browser/react/ScrollRestoration.js";
 
 export {
   Link,
@@ -72,11 +79,6 @@ export {
   type PrefetchStrategy,
 } from "./browser/react/Link.js";
 
-export {
-  ScrollRestoration,
-  type ScrollRestorationProps,
-} from "./browser/react/ScrollRestoration.js";
-
 export {
   NavigationProvider,
   type NavigationProviderProps,
@@ -91,14 +93,13 @@ export { MountContext } from "./browser/react/mount-context.js";
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
 export { Meta } from "./handles/meta.js";
-export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export {
   Script,
   type ScriptConfig,
   type ScriptAttributes,
 } from "./handles/script.js";
-export { Scripts } from "./handles/Scripts.js";
+export { Html };
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 export {

package/src/client.tsx

@@ -8,6 +8,9 @@ import {
   Suspense,
   type ReactNode,
 } from "react";
+// Not `export * as Html`: plugin-rsc's "use client" proxy transform only
+// expands bare `export *` and throws on a named one.
+import * as Html from "./html.js";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import {
   type ClientErrorBoundaryFallbackProps,
@@ -300,7 +303,7 @@ interface ErrorBoundaryState {
  * @example
  * ```tsx
  * "use client";
- * import { ErrorBoundary } from "rsc-router/client";
+ * import { ErrorBoundary } from "@rangojs/router/client";
  *
  * function MyComponent() {
  *   return (
@@ -427,7 +430,6 @@ export {
 } from "./browser/react/use-link-status.js";
 
 export {
-  ScrollRestoration,
   useScrollRestoration,
   type ScrollRestorationProps,
 } from "./browser/react/ScrollRestoration.js";
@@ -436,14 +438,13 @@ export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
 
 export { Meta } from "./handles/meta.js";
-export { MetaTags } from "./handles/MetaTags.js";
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 export {
   Script,
   type ScriptConfig,
   type ScriptAttributes,
 } from "./handles/script.js";
-export { Scripts } from "./handles/Scripts.js";
+export { Html };
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
 
 export {

package/src/components/DefaultDocument.tsx

@@ -3,12 +3,16 @@
 import type { ReactNode, ReactElement } from "react";
 import { MetaTags } from "../handles/MetaTags.js";
 import { Scripts } from "../handles/Scripts.js";
+import { ScrollRestoration } from "../browser/react/ScrollRestoration.js";
 
 /**
  * Default document component that provides a basic HTML structure.
  * Used when no custom document is provided to createRouter.
- * Includes MetaTags for automatic charset, viewport, and route meta support,
- * and Scripts (head + body sites) so the Script handle works out of the box.
+ * Renders every Html member: Html.Meta (charset, viewport, route meta), head +
+ * body Html.Scripts sites for the Script handle, and Html.ScrollRestoration.
+ * An app that wants a custom getKey or no scroll restoration passes its own
+ * document; rendering a second Html.ScrollRestoration under this one only
+ * warns ("[Scroll] Already initialized").
  *
  * Uses suppressHydrationWarning on <html> because the theme script
  * may modify class/style attributes before React hydrates.
@@ -27,6 +31,7 @@ export function DefaultDocument({
       <body>
         <Scripts position="body" />
         {children}
+        <ScrollRestoration />
       </body>
     </html>
   );

package/src/context-var.ts

@@ -12,7 +12,7 @@
  * interface PaginationData { current: number; total: number }
  * export const Pagination = createVar<PaginationData>();
  *
- * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * // Non-cacheable var — ctx.get(User) throws inside cache() or "use cache"
  * export const User = createVar<UserData>({ cache: false });
  *
  * // handler
@@ -26,7 +26,7 @@
 export interface ContextVar<T> {
   readonly __brand: "context-var";
   readonly key: symbol;
-  /** When false, ctx.get(var) throws inside a cache() boundary. */
+  /** When false, ctx.get(var) throws inside cache() or "use cache". */
   readonly cache: boolean;
   /** Phantom field to carry the type parameter. Never set at runtime. */
   readonly __type?: T;
@@ -35,9 +35,10 @@ export interface ContextVar<T> {
 export interface ContextVarOptions {
   /**
    * When false, marks this variable as non-cacheable.
-   * Reading this var with ctx.get() inside a cache() boundary throws. Use for
-   * inherently request-specific data (user sessions, auth tokens, etc.) that
-   * must never be baked into cached segments.
+   * Reading this var with ctx.get() inside a cache() boundary or a "use cache"
+   * function throws. Use for inherently request-specific data (user sessions,
+   * auth tokens, etc.) that must never be baked into cached segments or
+   * entries; pass the value into a "use cache" function as an argument.
    *
    * @default true
    */

package/src/escape-script.ts

@@ -45,7 +45,7 @@ export function escapeJsonForScript(json: string): string {
  * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
  * inlining it as code.
  *
- * Used by the Script handle's <Scripts> renderer for inline `children`.
+ * Used by the Script handle's <Html.Scripts> renderer for inline `children`.
  */
 export function escapeScriptBody(js: string): string {
   return js.replace(/<!--/g, "<\\u0021--").replace(/<\/(script)/gi, "<\\/$1");

package/src/handles/MetaTags.tsx

@@ -2,17 +2,18 @@
 
 /**
  * Component to render collected meta descriptors in the document head.
+ * Public as `Html.Meta` (`@rangojs/router/client`).
  *
- * Deferred (Promise) meta descriptors are resolved before MetaTags renders
+ * Deferred (Promise) meta descriptors are resolved before `<Html.Meta />` renders
  * (server-side on the full render, client-side before apply on navigation), so
  * it only ever receives resolved descriptors and never suspends.
  *
- * When theme is enabled in the router config, MetaTags also renders
+ * When theme is enabled in the router config, `<Html.Meta />` also renders
  * the theme initialization script to prevent FOUC (flash of unstyled content).
- * This makes MetaTags the sole FOUC-script injector for apps that render it;
- * the standalone `<ThemeScript />` is only needed when MetaTags is not used.
- * Rendering both is safe (the inline script guards listener registration) but
- * redundant.
+ * This makes `<Html.Meta />` the sole FOUC-script injector for apps that render
+ * it; the standalone `<ThemeScript />` is only needed when `<Html.Meta />` is not
+ * used. Rendering both is safe (the inline script guards listener registration)
+ * but redundant.
  *
  * @example
  * ```tsx
@@ -20,7 +21,7 @@
  *   return (
  *     <html lang="en" suppressHydrationWarning>
  *       <head>
- *         <MetaTags />
+ *         <Html.Meta />
  *       </head>
  *       <body>...</body>
  *     </html>
@@ -179,17 +180,18 @@ export function renderMetaDescriptor(
 }
 
 /**
- * Renders all collected meta descriptors from route handlers.
+ * Renders all collected meta descriptors from route handlers. Public as
+ * `Html.Meta` (`@rangojs/router/client`).
  *
- * Place this component inside the `<head>` element of your document.
+ * Place `<Html.Meta />` inside the `<head>` element of your document.
  * It will automatically update when meta descriptors change during navigation.
  *
  * When theme is enabled in router config, also renders the theme initialization
  * script to prevent FOUC (flash of unstyled content).
  *
- * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * Deferred (Promise) meta descriptors are resolved BEFORE this renders —
  * server-side on the full/SSR render, client-side before apply on navigation
- * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * (resolve-by-default) — so it only ever receives resolved descriptors and
  * never suspends.
  */
 export function MetaTags(): React.ReactNode {

package/src/handles/Scripts.tsx

@@ -1,11 +1,12 @@
 "use client";
 
 /**
- * Renders the scripts collected by the Script handle into the document.
+ * Renders the scripts collected by the Script handle into the document. Public
+ * as `Html.Scripts` (`@rangojs/router/client`).
  *
- * Place `<Scripts />` inside `<head>` (default) and, if you push body scripts,
- * `<Scripts position="body" />` at the top of `<body>`. Each site renders the
- * configs whose `position` matches; the request CSP nonce is applied
+ * Place `<Html.Scripts />` inside `<head>` (default) and, if you push body
+ * scripts, `<Html.Scripts position="body" />` at the top of `<body>`. Each site
+ * renders the configs whose `position` matches; the request CSP nonce is applied
  * automatically to every DOCUMENT-RENDERED <script> (consumers never pass it). An
  * async script first encountered on a soft navigation is injected client-side
  * where the nonce is unavailable, so it carries no nonce and relies on
@@ -24,11 +25,11 @@
  * ```tsx
  * <html>
  *   <head>
- *     <MetaTags />
- *     <Scripts />
+ *     <Html.Meta />
+ *     <Html.Scripts />
  *   </head>
  *   <body>
- *     <Scripts position="body" />
+ *     <Html.Scripts position="body" />
  *     {children}
  *   </body>
  * </html>
@@ -80,10 +81,10 @@ function passthroughAttributes(
       if (dev) {
         console.warn(
           isHandler
-            ? `[Scripts] event handler "${key}" in a script's attributes is ` +
+            ? `[Html.Scripts] event handler "${key}" in a script's attributes is ` +
                 `dropped; callbacks cannot cross the server -> client handle ` +
                 `boundary. Use a "use client" component for load/error handling.`
-            : `[Scripts] managed field "${key}" in a script's attributes is ` +
+            : `[Html.Scripts] managed field "${key}" in a script's attributes is ` +
                 `dropped; set it via the ScriptConfig fields (the request nonce ` +
                 `is applied automatically).`,
         );
@@ -129,7 +130,7 @@ function renderScript(
     async
   ) {
     console.warn(
-      `[Scripts] An async external script (src="${src}") is hoisted into ` +
+      `[Html.Scripts] An async external script (src="${src}") is hoisted into ` +
         `<head> by React; position: "body" is ignored for it.`,
     );
   }

package/src/handles/meta.ts

@@ -19,7 +19,7 @@
  *   return (
  *     <html>
  *       <head>
- *         <MetaTags />
+ *         <Html.Meta />
  *       </head>
  *       ...
  *     </html>
@@ -225,7 +225,7 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  * Built-in handle for managing document metadata.
  *
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
- * Use `<MetaTags />` component to render them in the document head.
+ * Use the `<Html.Meta />` component to render them in the document head.
  *
  * Deferred (Promise) descriptors are resolved before collectMeta runs
  * (resolve-by-default), so they participate in deduplication and `%s`

package/src/handles/script.ts

@@ -3,22 +3,23 @@
  * route/layout handlers.
  *
  * Push from a SERVER handler with `ctx.use(Script)(config)`; render with the
- * `<Scripts />` component (from `@rangojs/router/client`) placed in the Document
- * `<head>` (and optionally a second `<Scripts position="body" />` at the top of
- * `<body>`). This mirrors the Meta / <MetaTags> pair.
+ * `<Html.Scripts />` component (from `@rangojs/router/client`) placed in the
+ * Document `<head>` (and optionally a second `<Html.Scripts position="body" />`
+ * at the top of `<body>`). This mirrors the Meta / <Html.Meta> pair.
  *
- * The request CSP nonce is applied AUTOMATICALLY by <Scripts> to document-rendered
- * scripts; consumers never pass a nonce. (An async script first loaded on a soft
- * navigation is injected client-side without a nonce — it relies on
- * 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT below and the
- * /scripts skill.) A ScriptConfig is fully serializable (it crosses the
- * server -> client handle-collection boundary), so callbacks like onLoad are NOT
- * supported — a consumer needing them renders their own "use client" script.
+ * The request CSP nonce is applied AUTOMATICALLY by <Html.Scripts> to
+ * document-rendered scripts; consumers never pass a nonce. (An async script
+ * first loaded on a soft navigation is injected client-side without a nonce —
+ * it relies on 'strict-dynamic' or a host allowance; see the EXECUTION CONTRACT
+ * below and the /scripts skill.) A ScriptConfig is fully serializable (it
+ * crosses the server -> client handle-collection boundary), so callbacks like
+ * onLoad are NOT supported — a consumer needing them renders their own
+ * "use client" script.
  *
  * EXECUTION CONTRACT (see the /scripts skill for the full story):
  * - Inline (`children`) and ordered external (`src`, optional `defer`) scripts
  *   are DOCUMENT-LOAD scripts: they execute only when present in the initial HTML
- *   response. <Scripts> freezes them after hydration, so a later client (soft)
+ *   response. <Html.Scripts> freezes them after hydration, so a later client (soft)
  *   navigation never inserts an inert copy — React creates client-mounted
  *   <script> elements via innerHTML, which the HTML spec makes non-executing.
  * - Async external scripts (`src` + `async: true`) are React RESOURCES: they load
@@ -78,9 +79,9 @@ export type ScriptAttributes = Omit<
 /** Fields shared by every script shape. */
 interface ScriptConfigBase {
   /**
-   * Where <Scripts> renders this script.
-   * - "head" (default): the `<head>` <Scripts> site.
-   * - "body": the `<Scripts position="body" />` site at the top of <body>.
+   * Where <Html.Scripts> renders this script.
+   * - "head" (default): the `<head>` <Html.Scripts> site.
+   * - "body": the `<Html.Scripts position="body" />` site at the top of <body>.
    * Note: an external `async` script is hoisted into <head> by React regardless.
    */
   position?: "head" | "body";
@@ -96,7 +97,7 @@ interface ScriptConfigBase {
 /**
  * Inline script: a raw JS body rendered in place, escaped against `</script>`
  * breakout. DOCUMENT-LOAD only (executes when present in the initial HTML;
- * <Scripts> freezes it after hydration so navigation never inserts an inert
+ * <Html.Scripts> freezes it after hydration so navigation never inserts an inert
  * copy). `id` is REQUIRED — inline scripts are never deduped by React, so a
  * layout and a child pushing the same bootstrap would inject it twice. It is also
  * rendered as the script's DOM `id`. Forbids `src`/`async`/`defer`. For analytics
@@ -146,7 +147,7 @@ export interface OrderedScriptConfig extends ScriptConfigBase {
  * inline (`id` + `children`), external async (`src` + `async: true`), or external
  * ordered (`src`, optional `defer`). Invalid combinations (both `src`+`children`,
  * `async`+`defer`, inline without `id`) are compile errors. The CSP nonce is
- * applied by <Scripts>, never here.
+ * applied by <Html.Scripts>, never here.
  */
 export type ScriptConfig =
   | InlineScriptConfig

package/src/href-client.ts

@@ -6,7 +6,7 @@
  *
  * @example
  * ```typescript
- * import { href } from "rsc-router/client";
+ * import { href } from "@rangojs/router/client";
  *
  * href("/blog/my-post");           // ✓ matches /blog/:slug
  * href("/shop/product/widget");    // ✓ matches /shop/product/:slug

package/src/html.ts

@@ -0,0 +1,12 @@
+/**
+ * Members of the `Html` namespace; client.tsx and client.rsc.tsx expose this
+ * module as `import * as Html`. A module namespace, not an object literal, so
+ * bundlers drop members an app never renders (a literal kept opt-in
+ * ScrollRestoration in every app: +313 B gzip, over the router-chunk ratchet).
+ * No "use client": each member stays its own module's client reference, so a
+ * server component can dot into `Html`. Pinned by __tests__/html.test.ts and
+ * testing/__tests__/html-namespace.rsc-test.tsx.
+ */
+export { MetaTags as Meta } from "./handles/MetaTags.js";
+export { Scripts } from "./handles/Scripts.js";
+export { ScrollRestoration } from "./browser/react/ScrollRestoration.js";

package/src/index.rsc.ts

@@ -51,6 +51,7 @@ export type {
   LoaderDefinition,
   LoaderFn,
   LoaderContext,
+  LoaderOptions,
   FetchableLoaderOptions,
   LoadOptions,
   // Error boundary types
@@ -188,6 +189,9 @@ export {
   type RouterRequestInput,
 } from "./router.js";
 
+// Route manifest snapshot returned by router.debugManifest()
+export type { SerializedManifest } from "./debug.js";
+
 // RSC handler types (server-side)
 export type { HandlerCacheConfig } from "./rsc/types.js";
 export {
@@ -254,6 +258,7 @@ export type {
 export type {
   ScopedReverseFunction,
   ReverseFunction,
+  GlobalReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
 } from "./reverse.js";

package/src/index.ts

@@ -334,6 +334,7 @@ export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
 export type {
   ScopedReverseFunction,
   ReverseFunction,
+  GlobalReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
 } from "./reverse.js";

package/src/loader-store.ts

@@ -162,10 +162,13 @@ export class LoaderStore {
    * browser/partial-update.ts calls INSIDE every transition commit, so a
    * reader whose content is held on screen by that transition pins
    * `isLoading: true` for the data it is still showing until the transition
-   * lands (use-loader.tsx). The new tree's own read of the loader suspends at
-   * the read site and never observes the flag. A Set, not a flag: overlapping
-   * navigations (second click before the first stream lands) keep the family
-   * pending until the LAST stream settles.
+   * lands (use-loader.tsx). Family-keyed on purpose: a persisting layout
+   * reader of the same createLoader the child is re-running is pinned too
+   * (the loader is in flight; not "this segment's copy is being replaced" —
+   * issue #862, working as designed). The new tree's own read of the loader
+   * suspends at the read site and never observes the flag. A Set, not a
+   * flag: overlapping navigations (second click before the first stream
+   * lands) keep the family pending until the LAST stream settles.
    */
   private readonly pendingStreams = new Map<string, Set<Promise<unknown>>>();
 

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

@@ -4,9 +4,9 @@
  * Runs in the RSC realm of the build's temp server, AFTER all bundles are
  * written (the prelude embeds built client asset URLs — bootstrap module,
  * chunk preloads — that only exist post-client-build). The capture core is
- * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
- * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
- * quiesce, tags union, putShell barrier). Build capture first replays global
+ * producer A's, verbatim: deriveShellCaptureContext (push funnel, snapshot
+ * recording, implicit doc-cache scope) + settleCaptureRecord (the record-first
+ * step) + captureAndStoreShell (gates, quiesce, tags union, putShell barrier). Build capture first replays global
  * and route middleware with a synthetic build request context
  * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
  * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
@@ -21,6 +21,7 @@
  */
 
 import type { ShellCacheEntry } from "../cache/types.js";
+import type { MatchResult } from "../types.js";
 import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
 import {
   createRequestContext,
@@ -31,7 +32,10 @@ import {
 import {
   deriveShellCaptureContext,
   captureAndStoreShell,
+  settleCaptureRecord,
+  withinDeadline,
   delay,
+  SHELL_CAPTURE_MAX_WAIT_MS,
   SHELL_CAPTURE_RETRY_DELAY_MS,
   type ShellCaptureDescriptor,
 } from "../rsc/shell-capture.js";
@@ -44,7 +48,7 @@ import { isRouteNotFoundError } from "../errors.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { executeMiddleware, matchMiddleware } from "../router/middleware.js";
 import type { MiddlewareEntry } from "../router/middleware.js";
-import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
 import {
   resolvePprConfig,
   type ResolvedPprConfig,
@@ -134,18 +138,25 @@ export interface BuildShellCaptureResult {
   tags?: string[];
   /** On route-mismatch: what this router's match actually landed on. */
   matchedRouteName?: string;
+  /**
+   * On no-shell: the attempt ran out of ppr.captureTimeout. It is not
+   * retried: its match may still be running, and the retry would start the
+   * same work beside it (runtime twin: shell-capture.ts runShellCapture).
+   */
+  timedOut?: true;
 }
 
 /**
  * Capture the PPR shell for one prerendered URL at build time. Retries once
  * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
- * transform graph, mirroring producer A's cold-start retry — same delay).
+ * transform graph, mirroring producer A's cold-start retry — same delay),
+ * unless the attempt ran out of ppr.captureTimeout (`timedOut`).
  */
 export async function captureShellForBuild(
   opts: BuildShellCaptureOptions,
 ): Promise<BuildShellCaptureResult> {
   const first = await attemptBuildCapture(opts);
-  if (first.outcome !== "no-shell") return first;
+  if (first.outcome !== "no-shell" || first.timedOut) return first;
   if (opts.debug) {
     console.log(
       `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
@@ -215,6 +226,7 @@ async function attemptBuildCapture(
   };
 
   let mismatchedRouteName: string | undefined;
+  let timedOut = false;
   const result = await runWithRequestContext(baseCtx, async () => {
     const preview =
       typeof router.previewMatch === "function"
@@ -234,14 +246,11 @@ async function attemptBuildCapture(
       setRequestContextParams(preview.params ?? {}, preview.routeKey);
     }
 
-    const routeReverse = createReverseFunction(
-      getGlobalRouteMap(),
-      preview?.routeKey,
-      preview?.params ?? {},
-      preview?.routeKey
-        ? isRouteRootScoped(preview.routeKey, router.id)
-        : undefined,
-    );
+    // Global-only, like the live request's middleware reverse
+    // (rsc/handler.ts: createReverseFunction(getRequiredRouteMap())): no
+    // include() scope, no param auto-fill. A scoped reverse here resolved
+    // `.name` at build while the live request threw `Unknown route`.
+    const middlewareReverse = createReverseFunction(getGlobalRouteMap());
 
     const runCapture = () =>
       runBuildCaptureFinal({
@@ -255,6 +264,9 @@ async function attemptBuildCapture(
         setMismatchedRouteName: (routeName) => {
           mismatchedRouteName = routeName;
         },
+        markTimedOut: () => {
+          timedOut = true;
+        },
       });
 
     const routeMiddleware =
@@ -268,7 +280,7 @@ async function attemptBuildCapture(
         env,
         variables,
         runCapture,
-        routeReverse,
+        middlewareReverse,
         baseCtx,
       );
 
@@ -281,7 +293,7 @@ async function attemptBuildCapture(
       env,
       variables,
       runRouteMiddleware,
-      routeReverse,
+      middlewareReverse,
       baseCtx,
     );
   });
@@ -294,6 +306,7 @@ async function attemptBuildCapture(
   if (outcome === "route-mismatch") {
     return { outcome, matchedRouteName: mismatchedRouteName };
   }
+  if (outcome === "no-shell" && timedOut) return { outcome, timedOut: true };
   return { outcome };
 }
 
@@ -313,6 +326,8 @@ interface BuildCaptureFinalOptions {
   router: any;
   url: URL;
   setMismatchedRouteName(routeName: string | undefined): void;
+  /** The attempt ran out of ppr.captureTimeout (BuildShellCaptureResult.timedOut). */
+  markTimedOut(): void;
 }
 
 async function runBuildMiddlewareEnvelope<TEnv>(
@@ -372,15 +387,28 @@ async function runBuildCaptureFinal(
   // invoking this when baseCtx._dynamic is set. A loader/handler opting out
   // DURING the capture render is caught by the derivedCtx._dynamic check below.
 
-  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+  const derivation = deriveShellCaptureContext(baseCtx, {
     ttl: opts.ttl,
     swr: opts.swr,
   });
+  const { derivedCtx, freshHandleStore } = derivation;
 
   const outcome = await runWithRequestContext(derivedCtx, async () => {
-    let match;
+    // Same one deadline as the runtime capture: the match, the record-first
+    // step, then the prerender with what is left.
+    const deadline =
+      Date.now() + (opts.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS);
+    let match: MatchResult;
     try {
-      match = await router.match(request, { env });
+      const matched = await withinDeadline<MatchResult>(
+        router.match(request, { env }),
+        deadline,
+      );
+      if (!matched.done) {
+        options.markTimedOut();
+        return "no-shell" as const;
+      }
+      match = matched.value;
     } catch (error) {
       if (isPlainPathMiss(error, opts.urlPath)) {
         return "route-mismatch" as const;
@@ -395,8 +423,25 @@ async function runBuildCaptureFinal(
 
     setRequestContextParams(match.params, match.routeName);
 
-    const payload = buildFullPayload(
+    // Same record-first step as the runtime capture. A prerendered URL's
+    // match comes from the prerender store (no handler runs, no doc record),
+    // which settleCaptureRecord reports as `prerender`.
+    const settled = await settleCaptureRecord(
       match,
+      derivation,
+      descriptor,
+      deadline,
+    );
+    if (settled.kind === "refused") {
+      return derivedCtx._dynamic ? ("dynamic" as const) : ("refused" as const);
+    }
+    if (settled.kind === "timeout") {
+      options.markTimedOut();
+      return "no-shell" as const;
+    }
+
+    const payload = buildFullPayload(
+      settled.match,
       // buildFullPayload reads only ctx.router.* and ctx.version.
       { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
       url,
@@ -419,9 +464,15 @@ async function runBuildCaptureFinal(
       rscStream,
       freshHandleStore,
       derivedCtx,
-      descriptor,
+      { ...descriptor, captureTimeout: Math.max(1, deadline - Date.now()) },
     );
-    return derivedCtx._dynamic ? "dynamic" : captureOutcome;
+    if (captureOutcome === "no-shell" && Date.now() >= deadline) {
+      options.markTimedOut();
+    }
+    if (derivedCtx._dynamic) return "dynamic";
+    // A route cache() record that ran out mid-capture: the in-place retry
+    // (captureShellForBuild) reads or renders a newer one.
+    return captureOutcome === "expired" ? "no-shell" : captureOutcome;
   });
 
   return {