@rangojs/router 0.1.1 → 0.4.0

package/src/router/match-handlers.ts

@@ -1,12 +1,19 @@
 import type { ReactNode } from "react";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { sanitizeError } from "../errors";
-import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
 import type {
-  EntryData,
-  InterceptEntry,
-  InterceptSelectorContext,
-} from "../server/context";
+  ErrorBoundaryHandler,
+  ErrorInfo,
+  ErrorPhase,
+  MatchResult,
+  NotFoundBoundaryHandler,
+} from "../types";
+import {
+  isPprEntry,
+  type EntryData,
+  type InterceptEntry,
+  type InterceptSelectorContext,
+} from "../server/context.js";
 import type { MatchApiDeps } from "./types.js";
 import type { RouterContext } from "./router-context.js";
 import { runWithRouterContext } from "./router-context.js";
@@ -30,7 +37,6 @@ import {
   startRevalidationTrace,
   flushRevalidationTrace,
 } from "./logging.js";
-import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
@@ -41,6 +47,7 @@ import {
   buildCacheSignalSegments,
 } from "./telemetry.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { evaluatePprTransitionWhen } from "./transition-when.js";
 
 /**
  * Per-call telemetry lifecycle emitter for match()/matchPartial(). Each method
@@ -227,6 +234,35 @@ export function createMatchHandlers<TEnv = any>(
     if (reqCtx) reqCtx._cacheSignal = segments;
   };
 
+  const evaluatePprTransitionWhenForMatch = (
+    ctx: MatchContext<TEnv>,
+    isPartial: boolean,
+  ): void => {
+    const reqCtx = _getRequestContext();
+    if (!reqCtx) return;
+    reqCtx._pprTransitionDecisions = undefined;
+    if (!isPprEntry(ctx.manifestEntry)) return;
+
+    evaluatePprTransitionWhen(
+      ctx.entries,
+      reqCtx,
+      {
+        params: ctx.matched.params,
+        routeName: ctx.interceptSelectorContext.toRouteName,
+      },
+      (error, segmentId) =>
+        callOnError(error, "rendering", {
+          request: ctx.request,
+          url: ctx.url,
+          env: ctx.env,
+          params: ctx.matched.params,
+          segmentId,
+          isPartial,
+          handledByBoundary: false,
+        }),
+    );
+  };
+
   async function createMatchContextForFull(
     request: Request,
     env: TEnv,
@@ -313,6 +349,7 @@ export function createMatchHandlers<TEnv = any>(
           }
 
           const ctx = result as MatchContext<TEnv>;
+          evaluatePprTransitionWhenForMatch(ctx, false);
 
           try {
             const state = createPipelineState();
@@ -424,6 +461,7 @@ export function createMatchHandlers<TEnv = any>(
               emitter.end(0, false);
               return null;
             }
+            evaluatePprTransitionWhenForMatch(ctx, true);
 
             if (isRouterDebugEnabled()) {
               startRevalidationTrace({

package/src/router/match-middleware/cache-lookup.ts

@@ -460,6 +460,8 @@ export function withCacheLookup<TEnv>(
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
+    const pprTransitionDecisions =
+      _getRequestContext()?._pprTransitionDecisions;
 
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
@@ -533,8 +535,13 @@ export function withCacheLookup<TEnv>(
             reason: "cached-no-rules",
           });
         }
-        segment.component = null;
-        segment.loading = undefined;
+        // A PPR transition decision must reach the client even when this cached
+        // segment otherwise needs no update. Keep its replayed component so the
+        // partial result retains the segment for gateTransitions().
+        if (!pprTransitionDecisions?.has(segment.id)) {
+          segment.component = null;
+          segment.loading = undefined;
+        }
         yield segment;
         continue;
       }
@@ -566,7 +573,7 @@ export function withCacheLookup<TEnv>(
         shouldRevalidate,
       });
 
-      if (!shouldRevalidate) {
+      if (!shouldRevalidate && !pprTransitionDecisions?.has(segment.id)) {
         segment.component = null;
         segment.loading = 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/segment-resolution/view-transition-default.ts

@@ -23,10 +23,9 @@ import { getRequestContext } from "../../server/request-context.js";
  * gate, which also avoids needless object allocation and payload growth.
  *
  * `when`: a server-only predicate. It is STRIPPED from the returned config (a
- * function cannot cross Flight or the segment cache) and recorded on the request
- * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
- * outside any cache scope — and drop this segment's transition when it returns
- * false. Used by both the fresh and revalidation resolution paths.
+ * function cannot cross Flight or the segment cache). PPR routes evaluate it
+ * from the manifest before the pipeline; other routes record it here for the
+ * existing post-handler gate. Used by both fresh and revalidation resolution.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
@@ -39,7 +38,12 @@ export function applyViewTransitionDefault(
     if (segmentId !== undefined) {
       try {
         const ctx = getRequestContext();
-        (ctx._transitionWhen ??= []).push({ id: segmentId, when: result.when });
+        if (!ctx._pprTransitionDecisions?.has(segmentId)) {
+          (ctx._transitionWhen ??= []).push({
+            id: segmentId,
+            when: result.when,
+          });
+        }
       } catch {
         // No active request context (e.g. a unit test calling this util
         // directly). Skip collection; the strip below still applies so the

package/src/router/transition-when.ts

@@ -0,0 +1,76 @@
+import { getParallelSlotEntries, type EntryData } from "../server/context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+
+export type TransitionWhenErrorReporter = (
+  error: unknown,
+  segmentId: string,
+) => void;
+
+export function createTransitionWhenContext<TEnv>(
+  ctx: RequestContext<TEnv>,
+  target?: {
+    params: Record<string, string>;
+    routeName?: string;
+  },
+): TransitionWhenContext<Record<string, string>, TEnv> {
+  return {
+    currentUrl: ctx._gateCurrentUrl,
+    currentParams: ctx._gateCurrentParams,
+    fromRouteName: ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+    nextUrl: ctx.url,
+    nextParams: target?.params ?? ctx.params,
+    toRouteName: (target?.routeName ??
+      ctx.routeName) as TransitionWhenContext["toRouteName"],
+    actionId: ctx._gateActionId,
+    actionUrl: ctx._gateActionUrl,
+    actionResult: ctx._gateActionResult,
+    formData: ctx._gateFormData,
+    method: ctx.request.method,
+    get: ctx.get,
+    env: ctx.env,
+  };
+}
+
+/** Evaluate server-only transition gates before handlers on a PPR route. */
+export function evaluatePprTransitionWhen<TEnv>(
+  entries: EntryData[],
+  ctx: RequestContext<TEnv>,
+  target: {
+    params: Record<string, string>;
+    routeName?: string;
+  },
+  reportError: TransitionWhenErrorReporter,
+): void {
+  const decisions = new Map<string, boolean>();
+  const whenContext = createTransitionWhenContext(ctx, target);
+  const visited = new Set<EntryData>();
+
+  const evaluate = (entry: EntryData, segmentId: string): void => {
+    const when = entry.transition?.when;
+    if (!when) return;
+    try {
+      decisions.set(segmentId, when(whenContext) !== false);
+    } catch (error) {
+      decisions.set(segmentId, false);
+      reportError(error, segmentId);
+    }
+  };
+
+  const visitEntryAndOrphanLayouts = (entry: EntryData): void => {
+    if (visited.has(entry)) return;
+    visited.add(entry);
+    evaluate(entry, entry.shortCode);
+
+    for (const orphan of entry.layout) visitEntryAndOrphanLayouts(orphan);
+    // Rendered parallel slots are leaves identified by their owning segment.
+    for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
+      entry.parallel,
+    )) {
+      evaluate(parallelEntry, `${entry.shortCode}.${slot}`);
+    }
+  };
+
+  for (const entry of entries) visitEntryAndOrphanLayouts(entry);
+  ctx._pprTransitionDecisions = decisions.size > 0 ? decisions : undefined;
+}

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,

package/src/rsc/progressive-enhancement.ts

@@ -277,10 +277,15 @@ export async function handleProgressiveEnhancement<TEnv>(
     // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
     // matching — a stale `foregroundOnAction` cache entry must re-execute in the
     // foreground during the re-render, exactly as the JS path's
-    // revalidateAfterAction does. The transition({ when }) gate fields below are
-    // set post-match (the gate reads them after rendering); foregroundOnAction
-    // reads _inActionRevalidation during the match, so it must be set here.
-    getRequestContext()._inActionRevalidation = true;
+    // revalidateAfterAction does. PPR transition({ when }) runs during match,
+    // while foregroundOnAction reads _inActionRevalidation there too, so all
+    // action metadata must be available before matching.
+    const peReqCtx = getRequestContext();
+    peReqCtx._inActionRevalidation = true;
+    peReqCtx._gateActionId = directActionId ?? undefined;
+    peReqCtx._gateActionUrl = new URL(url);
+    peReqCtx._gateActionResult = actionResult;
+    peReqCtx._gateFormData = formData;
 
     const match = await ctx.router.match(renderRequest, { env });
 
@@ -291,16 +296,6 @@ export async function handleProgressiveEnhancement<TEnv>(
       });
     }
 
-    // Expose the no-JS action to the transition({ when }) gate. currentUrl/Params
-    // are absent on this full-render path (no navigation snapshot); useActionState
-    // ids are block-scoped, so only a direct action id is available here.
-    // actionUrl is the page the action was submitted from (this request's url).
-    const peReqCtx = getRequestContext();
-    peReqCtx._gateActionId = directActionId ?? undefined;
-    peReqCtx._gateActionUrl = new URL(url);
-    peReqCtx._gateActionResult = actionResult;
-    peReqCtx._gateFormData = formData;
-
     const payload: RscPayload = {
       metadata: {
         pathname: url.pathname,