@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/rsc/stream-idle.ts

@@ -0,0 +1,137 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+
+import { RouterTimeoutError } from "../router/timeout.js";
+
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+  /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+  totalMs: number;
+  /** Chunks forwarded before the trip. */
+  chunks: number;
+  /** The error the client-facing stream was terminated with. */
+  error: RouterTimeoutError;
+}
+
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export function applyStreamIdleTimeout(
+  response: Response,
+  idleMs: number,
+  onTrip: (trip: StreamIdleTrip) => void,
+): Response {
+  const source = response.body;
+  if (!source) return response;
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let chunks = 0;
+  let settled = false;
+  let controllerRef!: TransformStreamDefaultController<unknown>;
+
+  const disarm = () => {
+    settled = true;
+    if (timer) clearTimeout(timer);
+  };
+
+  const trip = () => {
+    if (settled) return;
+    const error = new RouterTimeoutError(
+      "stream-idle",
+      performance.now() - start,
+    );
+    try {
+      controllerRef.error(error);
+    } catch {
+      // The stream already terminated (raced a close/cancel) — nothing was
+      // interrupted, so do not report a timeout.
+      return;
+    }
+    // Erroring the transform makes the pipe abort and CANCEL the source
+    // stream (React aborts the wedged render). Mark settled AFTER the error
+    // took, then report.
+    disarm();
+    onTrip({ totalMs: error.durationMs, chunks, error });
+  };
+
+  const arm = () => {
+    if (settled) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(trip, idleMs);
+    (timer as { unref?: () => void }).unref?.();
+  };
+
+  // `cancel` is the spec's newer transformer hook (client-side cancellation);
+  // TS's lib.dom Transformer type lags it, hence the intersection. Runtimes
+  // without it fall back to the settled/try-catch guards in trip().
+  const transformer: Transformer<unknown, unknown> & { cancel?: () => void } = {
+    start(controller) {
+      controllerRef = controller;
+      arm();
+    },
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      chunks++;
+      arm();
+    },
+    flush() {
+      // Natural end of the source stream.
+      disarm();
+    },
+    cancel() {
+      disarm();
+    },
+  };
+  const watchdog = new TransformStream<unknown, unknown>(transformer);
+
+  return new Response(source.pipeThrough(watchdog) as ReadableStream, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/src/rsc/transition-gate.ts

@@ -0,0 +1,86 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+import { createTransitionWhenContext } from "../router/transition-when.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
+ *
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const pprDecisions = ctx._pprTransitionDecisions;
+  let gatedSegments = segments;
+
+  const dropTransition = (id: string): void => {
+    const index = gatedSegments.findIndex((segment) => segment.id === id);
+    if (index === -1) return;
+    if (!pprDecisions) {
+      gatedSegments[index].transition = undefined;
+      return;
+    }
+    if (gatedSegments === segments) gatedSegments = [...segments];
+    gatedSegments[index] = {
+      ...gatedSegments[index],
+      transition: undefined,
+    };
+  };
+
+  if (pprDecisions) {
+    for (const [id, keep] of pprDecisions) {
+      if (!keep) dropTransition(id);
+    }
+  }
+  const predicates = ctx._transitionWhen;
+  if (predicates) {
+    for (const { id, when } of predicates) {
+      try {
+        // Assemble the ShouldRevalidateFn-shaped predicate context from the
+        // request context. Source fields (currentUrl/currentParams/fromRouteName)
+        // were stashed at match time from the navigation snapshot; action fields
+        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
+        // method/get/env come straight off ctx (setRequestContextParams ran
+        // before the gate). Source/action fields are undefined when absent —
+        // never fabricated (see TransitionWhenContext).
+        if (when(createTransitionWhenContext(ctx)) !== false) continue;
+      } catch (error) {
+        // A throwing predicate must not fail the response: report it and treat
+        // the transition as gated off (do not hold). invokeOnError no-ops when
+        // onError is undefined.
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      dropTransition(id);
+    }
+  }
+  return gatedSegments;
+}

package/src/rsc/types.ts

@@ -7,37 +7,94 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouter } from "../router.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
- * RSC payload sent to the client
+ * RSC payload sent to the client.
+ * The tree is always reconstructed from metadata.segments by consumers
+ * (SSR via renderSegments, browser via renderSegments in bridges).
  */
 export interface RscPayload {
-  root: React.ReactNode | Promise<React.ReactNode>;
   metadata?: {
     pathname: string;
     segments: ResolvedSegment[];
+    /** Router instance ID. When this changes between navigations, the client
+     *  discards cached segments and does a full tree replacement (app switch). */
+    routerId?: string;
     isPartial?: boolean;
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /**
+     * All segment ids re-resolved on the server, including null-component
+     * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+     * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+     */
+    resolvedIds?: string[];
+    /** Merged route params from the matched route */
+    params?: Record<string, string>;
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable from this location as a
+     * navigation origin (see MatchResult.interceptTargets). The browser-local
+     * clientUrls matcher declines optimistic presentation for these.
+     */
+    interceptTargets?: string[];
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
     /** Handle data accumulated across route segments (async generator that yields on each push) */
     handles?: AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late handle channel: full-state updates for pushes landing
+     * AFTER the handler barrier (streaming loader bodies writing handles
+     * mid-body). `handles` above is drained to completion in blocking
+     * positions (SSR seed, pre-hydration), so late pushes need this separate
+     * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+     * Empty/instantly-complete when no auxiliary-lane work is pending at the
+     * handler barrier. Full payloads only — partial payloads' `handles`
+     * generator streams to full settle already.
+     */
+    handlesLate?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** Cloudflare dev worker generation used for stale-document convergence. */
+    devDiscoveryEpoch?: number;
+    /** TTL in milliseconds for the client-side in-memory prefetch cache */
+    prefetchCacheTTL?: number;
+    /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */
+    prefetchCacheSize?: number;
+    /** Max concurrent speculative prefetch requests on the client */
+    prefetchConcurrency?: number;
+    /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+    defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
+    /** Server-resolved rango state cookie name; the client reads it verbatim. */
+    stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */
     initialTheme?: Theme;
+    /** URL prefix for all routes (from createRouter({ basename })). */
+    basename?: string;
     /** Whether connection warmup is enabled */
     warmupEnabled?: boolean;
+    /**
+     * Whether the client should hydrate inside React.StrictMode. Carried on
+     * the initial full-render payload only; the browser entry reads it once at
+     * hydration. Absent on partial (navigation) payloads. Defaults to true on
+     * the client when omitted.
+     */
+    strictMode?: boolean;
+    /**
+     * Server-side redirect with optional state (for partial requests).
+     * `external: true` (from redirect(url, { external: true })) tells the client
+     * to hard-navigate to an off-host target instead of validating same-origin.
+     */
+    redirect?: { url: string; external?: boolean };
+    /** Server-set location state to include in history.pushState */
+    locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
-  formState?: unknown;
 }
 
 /**
@@ -54,7 +111,10 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown }
+    options?: {
+      temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**
@@ -62,7 +122,7 @@ export interface RSCDependencies {
    */
   decodeReply: (
     body: FormData | string,
-    options?: { temporaryReferences?: unknown }
+    options?: { temporaryReferences?: unknown },
   ) => Promise<unknown[]>;
 
   /**
@@ -87,7 +147,7 @@ export interface RSCDependencies {
    */
   decodeFormState: (
     actionResult: unknown,
-    body: FormData
+    body: FormData,
   ) => Promise<ReactFormState | null>;
 }
 
@@ -107,6 +167,32 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /**
+   * The live request's query string (`url.search`, `?`-prefixed or empty).
+   * Seeds the SSR navigation store so `useSearchParams` (and
+   * `useNavigation().location`) carry real values during document renders.
+   * Out-of-band by design — never payload metadata, which cached/prerendered
+   * payloads replay; search is not route identity. The build-time prerender
+   * pass passes none — build shells capture bare pathnames and serve
+   * search-less requests only (runtime ppr captures seed the shell key's
+   * search; see ShellCaptureOptions.search in the SSR entry).
+   */
+  search?: string;
+  /**
+   * The live request's origin (`url.origin`), seeding the SSR store
+   * location so origin-dependent markup (Link's data-external) agrees with
+   * the browser across hydration. Absent on host-agnostic build captures.
+   */
+  origin?: string;
 }
 
 /**
@@ -115,7 +201,43 @@ export interface SSRRenderOptions {
 export interface SSRModule {
   renderHTML: (
     rscStream: ReadableStream<Uint8Array>,
-    options?: SSRRenderOptions
+    options?: SSRRenderOptions,
+  ) => Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * PPR shell CAPTURE strategy (Axis 2). Prerenders the loader-masked shell over
+   * the Flight stream, aborts once quiescent, and returns the prelude bytes plus
+   * the postponed resume state — or null when the prelude degraded and must not
+   * be stored. Present only when the SSR virtual entry wires
+   * createShellCaptureHandler; the render layer feature-detects it. See
+   * docs/design/ppr-shell-resume.md.
+   */
+  captureShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: {
+      quiesce: Promise<void>;
+      maxWaitMs?: number;
+      search?: string;
+      origin?: string;
+    },
+  ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
+
+  /**
+   * PPR shell RESUME strategy (Axis 2). Produces the per-request live portion of
+   * the document: resumes fizz over a fresh SsrRoot to emit only the postponed
+   * holes (or, for the DATA variant with postponed === null, just the fresh Flight
+   * payload scripts). The caller prepends the stored prelude bytes to form the
+   * composite response. Present only when the SSR virtual entry wires
+   * createShellResumeHandler; the render layer feature-detects it.
+   */
+  resumeShellHTML?: (
+    rscStream: ReadableStream<Uint8Array>,
+    options: {
+      postponed: string | null;
+      nonce?: string;
+      search?: string;
+      origin?: string;
+    },
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 
@@ -133,16 +255,37 @@ export interface HandlerCacheConfig {
   store: import("../cache/types.js").SegmentCacheStore;
   /** Enable/disable caching (default: true) */
   enabled?: boolean;
+  /**
+   * Which query params key the cache (default: `"all"`). Affects cache keys
+   * ONLY -- handlers and loaders still see the full query string. Global by
+   * design: the per-route case is already reachable through `cache({ key })`.
+   *
+   * Excluding a param is a promise that rendered output does not depend on
+   * it; if it does, the first variant is cached and served to everyone.
+   *
+   * @example
+   * ```typescript
+   * cache: {
+   *   store: cacheStore,
+   *   searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+   * }
+   * ```
+   */
+  searchParams?: import("../cache/search-params-filter.js").CacheSearchParams;
 }
 
 /**
  * Nonce provider function type.
- * Can return a nonce string, or true to auto-generate one.
+ * Return a nonce string to use verbatim, `true` to auto-generate one, or
+ * `false` (or an empty string) to serve THIS request without a nonce — the
+ * per-request opt-out for apps that nonce globally but declare `ppr` on some
+ * routes: a shell is shared per host+URL and can never bake a per-request
+ * nonce, so a ppr route only captures when its requests opt out here.
  */
 export type NonceProvider<TEnv = unknown> = (
   request: Request,
-  env: TEnv
-) => string | true | Promise<string | true>;
+  env: TEnv,
+) => string | boolean | Promise<string | boolean>;
 
 /**
  * Options for creating an RSC handler
@@ -154,7 +297,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouter<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.
@@ -213,7 +356,8 @@ export interface CreateRSCHandlerOptions<
    * - Undefined to disable nonce (default)
    *
    * The nonce will be applied to inline scripts injected by the RSC payload.
-   * It's also available to middleware via `ctx.get('nonce')`.
+   * It's also available to middleware via the typed `nonce` token:
+   * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
    *
    * @example Auto-generate nonce
    * ```tsx
@@ -230,7 +374,16 @@ export interface CreateRSCHandlerOptions<
    *   nonce: (request, env) => env.nonce,
    * });
    * ```
+   *
+   * @example Access nonce in middleware
+   * ```tsx
+   * import { nonce } from "@rangojs/router";
+   *
+   * const cspMiddleware: Middleware = async (ctx, next) => {
+   *   const value = ctx.get(nonce); // string | undefined
+   *   await next();
+   * };
+   * ```
    */
   nonce?: NonceProvider<TEnv>;
-
 }

package/src/runtime-env.ts

@@ -0,0 +1,18 @@
+// Runtime-safe detection of a test runner (Vitest), used to decide whether a
+// create*() call with no plugin-injected $$id may fall back to a synthetic id (a
+// bare test) or must fail loud (dev / a real build).
+//
+// `process` is absent in some target runtimes (the browser, certain edge/worker
+// RSC environments), so probe it through `globalThis` with optional chaining —
+// NEVER a bare `process.env.VITEST`, which would ReferenceError before the
+// intended error is thrown. Unlike `process.env.NODE_ENV` (folded by the app's
+// build `define`), `VITEST` is not folded, so this stays a small runtime check;
+// it lives only on the create*() error path (id missing), which never runs in a
+// correct production build.
+//
+// Vitest sets `VITEST` in every test process — the node project and the
+// react-server forks alike (the RSC project forces NODE_ENV=production, so NODE_ENV
+// cannot distinguish it from a real build; `VITEST` can). A real build never sets it.
+export function isUnderTestRunner(): boolean {
+  return !!globalThis.process?.env?.VITEST;
+}