@rangojs/router 0.2.0 → 0.4.0

package/package.json

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

package/skills/comparison/references/framework-comparison.md

@@ -539,7 +539,8 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 ### Prefetching: stability and control
 
-`<Link prefetch="hover|viewport|render|adaptive|none">` (default `"none"`), plus
+`<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
+`defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
 `prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
 whose response branches on `currentUrl`). The distinguishing part is the stability
 gating: a queued prefetch (`viewport`/`render`) will not fire until **both** the

package/skills/ppr/SKILL.md

@@ -175,12 +175,14 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
-### Soft navigation reuses the captured segment shell
+### Soft navigation caches and reuses the handler layer
 
-A usable shell snapshot also accelerates ordinary partial RSC navigations to
-the same URL. The capture records the canonical document segment tree alongside
-the HTML prelude. On a partial request the server replays only that segment
-record through the normal `matchPartial()` pipeline, which then:
+Ordinary partial RSC navigations to a `ppr` URL use the same handler-layer cache
+contract even when no document request has captured an HTML shell yet. When a
+shell snapshot exists, the server replays its canonical document segment record.
+On a cold partial request, normal matching renders the response and schedules a
+background navigation-only shell capture; later navigations and prefetches
+replay its eligible snapshot. In both cases `matchPartial()`:
 
 - preserves client-owned shared layouts by segment id;
 - returns only new or revalidating destination segments;
@@ -191,9 +193,8 @@ This is deliberately invisible to the browser: the response is the same
 `RscPayload` shape as any other partial navigation. Captured item/response values
 and loader-container pins are NOT replayed on this path, so loader reads stay
 live. A route's own `cache()` scope still resolves its normal store, key, TTL,
-SWR, tags, and condition; only the implicit document scope sees the replay
-overlay, and fresh segment writes there stay request-local rather than polluting
-the canonical `doc:` namespace. `transition({ when })` is evaluated from the
+SWR, tags, and condition; only the implicit PPR scope sees this behavior.
+`transition({ when })` is evaluated from the
 matched manifest before route handlers on every PPR match, so it can vary by
 URL/params/action or middleware context without disabling replay; handler-set
 context is unavailable by design. Intercepts, handler-live holes, an active
@@ -204,12 +205,21 @@ an explicit cache tier remains frozen by that tier's normal semantics.
 Fresh and stale-within-SWR runtime shells replay. The stale read is passive: it
 uses `getShell(key, { claimRevalidation: false })`, does not claim SWR ownership,
 and cannot recapture HTML. A later document request owns the background
-recapture; hard-expired entries fall open. Production may also use a fresh local
-build manifest; development stays runtime-only because probing `/__rsc_shell`
-would block navigation on an on-demand capture. Custom `SegmentCacheStore`
+recapture; hard-expired entries schedule a navigation-only capture. Production
+may also use a fresh local build manifest. Development does not probe
+`/__rsc_shell`; it schedules the same local background capture instead. Custom `SegmentCacheStore`
 implementations must set `supportsPassiveShellReads: true` and honor the
 non-claiming read option.
 
+The first cold partial request reports `BYPASS; reason=no-entry` because no
+artifact could supply that response; its successful render schedules
+`scheduleShellCapture` with a navigation-only marker. The next request reports
+`HIT` when the capture produced an eligible snapshot. Navigation snapshots use
+a separate shell key, so they cannot overwrite or be served as a document shell.
+The capture runs with the stripped target document URL and loads SSR support in
+the bounded background queue, outside the triggering partial response's latency.
+An `allReady` decision still declines capture.
+
 Partial responses expose the actual decision as `x-rango-ppr-replay`:
 `HIT; freshness=fresh|stale` or `BYPASS; reason=<bounded-token>`. With
 performance metrics enabled, the same decision appears as
@@ -292,7 +302,9 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
-  `ShellCaptureDebugEvent` instead. In dev, with `debugPerformance` on, the
+  `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
+  has 32 queued/running captures; the dropped best-effort capture can retry on a
+  later request. In dev, with `debugPerformance` on, the
   last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 
@@ -750,7 +762,10 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   it: call `cacheTag(...)` from the shell-material render code (the render-time
   lever), or add the tag to `ppr.tags` (operational tags the render cannot know —
   a tenant id, a deploy marker). Ring-1/ring-3 tag invalidation does NOT drop the
-  shell.
+  shell. Tags are optional: if TTL/SWR is the complete freshness policy, leave
+  the shell untagged. Rango does not warn for that choice; with
+  `debugShellCapture` enabled, a stored event reports `untaggedBake: true` when
+  bake-lane loader material uses TTL/SWR-only invalidation.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the

package/skills/router-setup/SKILL.md

@@ -120,6 +120,10 @@ interface RangoOptions<TEnv> {
   // Set to false to disable prefetch caching.
   prefetchCacheTTL?: number | false;
 
+  // Default prefetch strategy for Links without a `prefetch` prop
+  // (dev: "none", production: "viewport"). Per-Link props win in both directions.
+  defaultPrefetch?: "hover" | "viewport" | "render" | "adaptive" | "none";
+
   // CSP nonce provider (for router.fetch)
   nonce?: (
     request: Request,

package/src/browser/prefetch/default-strategy.ts

@@ -0,0 +1,34 @@
+/**
+ * Router-wide default Link prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop reads the value at render time.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+
+// Mirrors DEFAULT_PREFETCH_STRATEGY without pulling router-layer code into the
+// client bundle. NODE_ENV is folded by the app build.
+let defaultStrategy: PrefetchStrategy =
+  process.env.NODE_ENV === "production" ? "viewport" : "none";
+
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
+  defaultStrategy = strategy;
+}
+
+/** Current default strategy for Links without an explicit `prefetch` prop. */
+export function getDefaultPrefetchStrategy(): PrefetchStrategy {
+  return defaultStrategy;
+}

package/src/browser/prefetch/loader.ts

@@ -1,4 +1,8 @@
 import type { RscPayload } from "../types.js";
+import {
+  observeForPrefetch as observeElementForPrefetch,
+  unobserveForPrefetch,
+} from "./observer.js";
 
 type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 
@@ -83,19 +87,9 @@ export function observeForPrefetch(
   callback: () => void,
 ): () => void {
   if (typeof IntersectionObserver === "undefined") return () => {};
-  let active = true;
-  if (runtime) {
-    runtime.observeForPrefetch(element, callback);
-  } else {
-    void loadRuntime()
-      .then((loaded) => {
-        if (active) loaded.observeForPrefetch(element, callback);
-      })
-      .catch(() => {});
-  }
+  observeElementForPrefetch(element, callback);
   return () => {
-    active = false;
-    runtime?.unobserveForPrefetch(element);
+    unobserveForPrefetch(element);
   };
 }
 

package/src/browser/prefetch/runtime.ts

@@ -4,4 +4,3 @@ export {
   cancelAllPrefetches,
   setPrefetchConcurrency,
 } from "./queue.js";
-export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

package/src/browser/react/Link.tsx

@@ -37,7 +37,9 @@ import {
   prefetchDirect,
   prefetchQueued,
 } from "../prefetch/loader.js";
+import { getDefaultPrefetchStrategy } from "../prefetch/default-strategy.js";
 import { getAppVersion } from "../app-version.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 // The (hover: none) MediaQueryList, created lazily on first client read and
 // reused across every Link render. matchMedia allocates and registers a live
@@ -62,20 +64,10 @@ function isTouchDevice(): boolean {
   return hoverNoneQuery.matches;
 }
 
-/**
- * Prefetch strategy for the Link component
- * - "hover": Prefetch on mouse enter (direct, no queue)
- * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
- * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
- * - "adaptive": Hover on pointer devices, viewport on touch devices
- * - "none": No prefetching (default)
- */
-export type PrefetchStrategy =
-  | "hover"
-  | "viewport"
-  | "render"
-  | "adaptive"
-  | "none";
+// The PrefetchStrategy union is defined in router/prefetch-default.ts (both
+// the server-side option resolver and this client seat consume it); re-export
+// so the public `PrefetchStrategy` import path via client.tsx is unchanged.
+export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 /**
  * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
@@ -125,8 +117,12 @@ export interface LinkProps extends Omit<
    */
   revalidate?: boolean;
   /**
-   * Prefetch strategy for the link destination
-   * @default "none"
+   * Prefetch strategy for the link destination. When omitted, falls back to
+   * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
+   * development, `"viewport"` in production). An explicit value always wins
+   * over the router default, including `"none"` to opt a single Link out.
+   *
+   * @default the router's environment-aware `defaultPrefetch`
    */
   prefetch?: PrefetchStrategy;
   /**
@@ -240,7 +236,7 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
-    prefetch = "none",
+    prefetch,
     prefetchKey,
     state,
     children,
@@ -262,10 +258,15 @@ export const Link: ForwardRefExoticComponent<
     return to === "/" ? bn : bn + to;
   }, [to, isExternal, ctx?.basename]);
 
-  // Resolve adaptive: viewport on touch devices, hover on pointer devices.
-  // isTouchDevice() is read here (per render), not from a module-load snapshot,
-  // so a device whose input capability changes resolves to the current value.
-  const resolvedStrategy = resolveAdaptiveStrategy(prefetch);
+  // No explicit `prefetch` prop: fall back to the router-wide default
+  // (server-resolved, applied at browser init — before hydration, so this
+  // render-time read never races the metadata). Then resolve adaptive:
+  // viewport on touch devices, hover on pointer devices. isTouchDevice() is
+  // read here (per render), not from a module-load snapshot, so a device
+  // whose input capability changes resolves to the current value.
+  const resolvedStrategy = resolveAdaptiveStrategy(
+    prefetch ?? getDefaultPrefetchStrategy(),
+  );
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);

package/src/browser/rsc-router.tsx

@@ -30,6 +30,7 @@ import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
+import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -297,6 +298,13 @@ export async function initBrowserApp(
   if (prefetchConcurrency !== undefined) {
     setPrefetchConcurrency(prefetchConcurrency);
   }
+  // Apply the router-wide default Link prefetch strategy. Undefined (older
+  // server payload) keeps the module's environment-aware default, which equals
+  // the server resolver's default by contract — see default-strategy.ts.
+  const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
+  if (defaultPrefetch !== undefined) {
+    setDefaultPrefetchStrategy(defaultPrefetch);
+  }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
   // client chunks (same createFromFetch the navigation client uses).

package/src/browser/types.ts

@@ -82,6 +82,11 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its prefetch queue.
    */
   prefetchConcurrency?: number;
+  /**
+   * Router-wide default prefetch strategy for Links without a `prefetch` prop.
+   * Sent on initial render; applied once at init (default-strategy.ts).
+   */
+  defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
   /**
    * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
    * reads it verbatim and binds the rango state cookie to it; composition

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

@@ -295,6 +295,8 @@ interface KVShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /**
@@ -1819,6 +1821,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           snapshot: envelope.sn,
           handlerLiveHoles: envelope.lh,
           transitionWhen: envelope.tw,
+          navigationOnly: envelope.no,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1907,6 +1910,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             sn: entry.snapshot,
             lh: entry.handlerLiveHoles,
             tw: entry.transitionWhen,
+            no: entry.navigationOnly,
           };
           await this.kv!.put(kvKey, JSON.stringify(envelope), {
             expirationTtl: retentionTtl,

package/src/cache/types.ts

@@ -305,6 +305,12 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
+  /**
+   * The entry was captured from a partial request only to produce an eligible
+   * segment snapshot. Document serving must treat its HTML prelude as a miss;
+   * the partial request's headers and middleware state are not document state.
+   */
+  navigationOnly?: true;
   /**
    * True when the capture's HANDLER layer declared per-request liveness: a
    * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the

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

@@ -211,6 +211,8 @@ interface VercelShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /** Read-path outcome for the debug sink. */
@@ -816,6 +818,7 @@ export class VercelCacheStore<
         snapshot: env.sn,
         handlerLiveHoles: env.lh,
         transitionWhen: env.tw,
+        navigationOnly: env.no,
         createdAt: env.c,
       },
       shouldRevalidate,
@@ -865,6 +868,7 @@ export class VercelCacheStore<
         sn: entry.snapshot,
         lh: entry.handlerLiveHoles,
         tw: entry.transitionWhen,
+        no: entry.navigationOnly,
       };
       // write() enforces the 2 MB per-item ceiling (withinSizeLimit): an
       // oversized shell prelude is reported and skipped (fail-open to a full
@@ -1192,7 +1196,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn, lh, tw, no } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1210,6 +1214,7 @@ export class VercelCacheStore<
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : undefined,
       lh: lh === true ? true : undefined,
       tw: tw === true ? true : undefined,
+      no: no === true ? true : undefined,
     };
   }
 

package/src/router/prefetch-default.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolve the router-wide default Link prefetch strategy once, at router init.
+ * The resolved value ships to the client in payload metadata; the browser
+ * entry applies it via `setDefaultPrefetchStrategy` (browser/prefetch/
+ * default-strategy.ts) and every `<Link>` without an explicit `prefetch` prop
+ * falls back to it.
+ *
+ * The type lives HERE (not in browser/react/Link.tsx) because both seats need
+ * it: this server-side resolver and the client Link/default-strategy modules.
+ * Link.tsx re-exports it so the public `PrefetchStrategy` export path is
+ * unchanged.
+ *
+ * Policy note: automatic prefetch stays quiet in development, matching the
+ * production-only default used by Next.js. Explicit router and per-Link
+ * strategies still work in every mode. Invalid untyped inputs fall back to the
+ * current environment's default.
+ */
+
+/**
+ * Prefetch strategy for the Link component
+ * - "hover": Prefetch on mouse enter (direct, no queue)
+ * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
+ * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
+ * - "none": No prefetching
+ */
+export type PrefetchStrategy =
+  | "hover"
+  | "viewport"
+  | "render"
+  | "adaptive"
+  | "none";
+
+function defaultPrefetchForEnvironment(
+  nodeEnv: string | undefined,
+): PrefetchStrategy {
+  return nodeEnv === "production" ? "viewport" : "none";
+}
+
+export const DEFAULT_PREFETCH_STRATEGY: PrefetchStrategy =
+  defaultPrefetchForEnvironment(process.env.NODE_ENV);
+
+const VALID_STRATEGIES: ReadonlySet<string> = new Set([
+  "hover",
+  "viewport",
+  "render",
+  "adaptive",
+  "none",
+] satisfies PrefetchStrategy[]);
+
+export function resolveDefaultPrefetch(
+  raw: PrefetchStrategy | undefined,
+  nodeEnv: string | undefined = process.env.NODE_ENV,
+): PrefetchStrategy {
+  if (typeof raw === "string" && VALID_STRATEGIES.has(raw)) {
+    return raw;
+  }
+  return defaultPrefetchForEnvironment(nodeEnv);
+}

package/src/router/router-interfaces.ts

@@ -318,6 +318,14 @@ export interface RangoInternal<
    */
   readonly prefetchConcurrency: number;
 
+  /**
+   * Router-wide default Link prefetch strategy for Links without an explicit
+   * `prefetch` prop. Shipped to the client in payload metadata. Derived from
+   * the `defaultPrefetch` option (default "none" in development and
+   * "viewport" in production).
+   */
+  readonly defaultPrefetch: import("./prefetch-default.js").PrefetchStrategy;
+
   /**
    * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
    * router init and shipped to the client in payload metadata. The server-side

package/src/router/router-options.ts

@@ -11,6 +11,7 @@ import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { PrefetchStrategy } from "./prefetch-default.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -532,6 +533,36 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchConcurrency?: number;
 
+  /**
+   * Default prefetch strategy for every `<Link>` that does not set its own
+   * `prefetch` prop. A per-Link `prefetch` prop always wins, in both
+   * directions (a Link can opt out of an aggressive default with
+   * `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
+   *
+   * - `"viewport"` (production default): prefetch when the link enters the viewport —
+   *   idle-gated and queued (see `prefetchConcurrency`), so prefetches never
+   *   compete with hydration or an active navigation.
+   * - `"hover"`: prefetch on mouse enter only. Much lighter on the server —
+   *   only links the pointer approaches are fetched — at the cost of the
+   *   ~100-300ms head start viewport prefetch gives.
+   * - `"adaptive"`: `"hover"` on pointer devices, `"viewport"` on touch
+   *   devices (no hover to wait for).
+   * - `"render"`: prefetch on mount regardless of visibility.
+   * - `"none"`: manual mode — nothing prefetches unless a Link opts in.
+   *
+   * Automatic prefetch defaults to `"none"` in development and `"viewport"`
+   * in production. With the production default, every visible Link triggers an
+   * RSC render (loaders included) on the server. Routes served from cache/PPR
+   * absorb this cheaply; per-user dynamic routes pay full price per viewport
+   * entry. Set `"hover"`, `"adaptive"`, or `"none"` when that cost matters.
+   *
+   * To disable the prefetch subsystem entirely (including per-Link opt-ins
+   * and `useRouter().prefetch()`), set `prefetchCacheTTL: false` instead.
+   *
+   * @default "none" in development; "viewport" in production
+   */
+  defaultPrefetch?: PrefetchStrategy;
+
   /**
    * Prefix for the rango state cookie name. The resolved name is
    * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

package/src/router.ts

@@ -115,6 +115,7 @@ import {
 } from "./router/prerender-match.js";
 import { resolveStateCookieName } from "./router/state-cookie-name.js";
 import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.js";
+import { resolveDefaultPrefetch } from "./router/prefetch-default.js";
 import {
   resolvePrefetchCacheSize,
   resolvePrefetchConcurrency,
@@ -160,6 +161,7 @@ export function createRouter<TEnv = any>(
     prefetchCacheTTL: prefetchCacheTTLOption,
     prefetchCacheSize: prefetchCacheSizeOption,
     prefetchConcurrency: prefetchConcurrencyOption,
+    defaultPrefetch: defaultPrefetchOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     telemetry: telemetrySink,
@@ -268,6 +270,10 @@ export function createRouter<TEnv = any>(
     prefetchConcurrencyOption,
   );
 
+  // Resolve the router-wide default Link prefetch strategy ("none" in dev,
+  // "viewport" in production). Links without an explicit prop fall back to it.
+  const defaultPrefetch = resolveDefaultPrefetch(defaultPrefetchOption);
+
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
@@ -1009,6 +1015,7 @@ export function createRouter<TEnv = any>(
     prefetchCacheTTL,
     prefetchCacheSize,
     prefetchConcurrency,
+    defaultPrefetch,
 
     // Expose the resolved rango state cookie name for the server-side writer
     // (invalidateClientCache) and for shipping to the client in metadata.

package/src/rsc/capture-queue.ts

@@ -23,6 +23,18 @@
  * swallow, so one rejected capture can never wedge every later one.
  */
 let captureQueue: Promise<void> = Promise.resolve();
+let admittedCaptures = 0;
+
+/** Bound queued/running capture closures retained by one isolate. */
+export const MAX_ADMITTED_CAPTURES: number = 32;
+
+/** The caller may drop this best-effort capture and retry on a later request. */
+export class CaptureQueueFullError extends Error {
+  constructor() {
+    super(`shell capture queue is full (${MAX_ADMITTED_CAPTURES})`);
+    this.name = "CaptureQueueFullError";
+  }
+}
 
 /**
  * Upper bound on how long one queue link may hold the queue. A capture task
@@ -43,6 +55,10 @@ const QUEUE_LINK_CAP_MS = 60_000;
 export function enqueueSerializedCapture(
   task: () => Promise<void>,
 ): Promise<void> {
+  if (admittedCaptures >= MAX_ADMITTED_CAPTURES) {
+    return Promise.reject(new CaptureQueueFullError());
+  }
+  admittedCaptures++;
   const prior = captureQueue;
   let releaseQueue!: () => void;
   captureQueue = new Promise<void>((resolve) => {
@@ -51,9 +67,16 @@ export function enqueueSerializedCapture(
   return (async () => {
     await prior.catch(() => {});
     let capTimer: ReturnType<typeof setTimeout> | undefined;
+    const taskPromise = Promise.resolve()
+      .then(task)
+      .finally(() => {
+        // A timed-out link releases serialization, but its detached task still
+        // counts against admission until it actually settles.
+        admittedCaptures--;
+      });
     try {
       await Promise.race([
-        task(),
+        taskPromise,
         new Promise<void>((resolve) => {
           capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
           (capTimer as { unref?: () => void }).unref?.();

package/src/rsc/full-payload.ts

@@ -53,6 +53,7 @@ export function buildFullPayload(
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,
       prefetchConcurrency: ctx.router.prefetchConcurrency,
+      defaultPrefetch: ctx.router.defaultPrefetch,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       // Carry warmupEnabled on the initial full-render payload so the client

package/src/rsc/handler.ts

@@ -1219,6 +1219,7 @@ export function createRSCHandler<
               prefetchCacheTTL: router.prefetchCacheTTL,
               prefetchCacheSize: router.prefetchCacheSize,
               prefetchConcurrency: router.prefetchConcurrency,
+              defaultPrefetch: router.defaultPrefetch,
               stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,