@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/rsc/shell-serve.ts

@@ -0,0 +1,226 @@
+/**
+ * Integrated PPR shell serving (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * PPR is opt-in per PAGE ROUTE via the `ppr` path option
+ * (`path(pattern, Handler, { name, ppr: true | PartialPrerenderProps })`) and the
+ * serving logic is INTEGRAL to the render pipeline — there is no middleware to
+ * mount. This module owns the config/key/store plumbing the render layer
+ * (rsc-rendering.ts) uses at its COMMIT POINT, which sits after the WHOLE
+ * middleware chain (global `router.use()` chain AND route DSL `middleware()`,
+ * both of which wrap the render pass): any middleware rejection/redirect wins
+ * before a single shell byte is written.
+ *
+ * The shell store is the app-level `createRouter({ cache })` store
+ * (`requestCtx._cacheStore`). A store without the `getShell`/`putShell` family
+ * degrades a ppr route to axis 1 with a once-per-key warning (the declared
+ * intent cannot be honored — unlike an undeclared route, which is silent).
+ */
+
+import React from "react";
+import { isPprEntry, type EntryData } from "../server/context.js";
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+
+/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
+export const SHELL_STATUS_HEADER = "x-rango-shell";
+
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export const DEFAULT_PPR_TTL_SECONDS = 300;
+
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export const DEV_SHELL_PROBE_TIMEOUT_MS: number = 10_000;
+
+/** The route's ppr option normalized to a concrete policy. */
+export interface ResolvedPprConfig {
+  ttl: number;
+  swr?: number;
+  tags?: string[];
+  /**
+   * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+   * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+   * shell-capture.ts), so direct descriptor callers and resolved configs
+   * cannot drift.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 15_000) — the default's single
+   * owner stays shell-capture.ts so build/runtime producers cannot drift.
+   */
+  captureTimeout?: number;
+}
+
+/**
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
+ * through; anything else (including 0/negative/NaN/Infinity/non-number)
+ * resolves to undefined, which means "use the capture default" downstream.
+ * Mirrors the prefetch-limit option policy: invalid values silently fall back
+ * to the default rather than throwing at request time. Also the boundary
+ * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
+ * whose param crossed an HTTP query string.
+ */
+export function normalizeCaptureTimeout(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? value
+    : undefined;
+}
+
+/**
+ * Normalize the matched page route's `ppr` path option. Returns null when the
+ * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
+ * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
+ *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
+ * PPR is a DOCUMENT-level property of the page route; there is no subtree
+ * inheritance (declaring it on a layout is not supported — a follow-up).
+ */
+export function resolvePprConfig(
+  entry: EntryData | undefined | null,
+): ResolvedPprConfig | null {
+  // isPprEntry (server/context.ts) is the ONE opt-in predicate — shared with
+  // the header-write latch so serve and guard can never drift.
+  if (!entry || !isPprEntry(entry)) return null;
+  const ppr = entry.ppr;
+  if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
+  return {
+    ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
+    swr: ppr.swr,
+    tags: ppr.tags,
+    maxSnapshotBytes: ppr.maxSnapshotBytes,
+    captureTimeout: normalizeCaptureTimeout(ppr.captureTimeout),
+  };
+}
+
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ */
+export function buildShellKey(url: URL): string {
+  const sorted = sortedSearchString(url.searchParams);
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+}
+
+/**
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
+ */
+export function isValidShellHit(
+  entry: ShellCacheEntry,
+  buildVersion: string,
+): boolean {
+  return (
+    entry.reactVersion === React.version && entry.buildVersion === buildVersion
+  );
+}
+
+/**
+ * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
+ * whose prelude is not decodable base64 or whose postponed blob is not
+ * parseable JSON would otherwise throw AFTER the 200 + full static prelude
+ * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
+ * parses in the tail) — the client gets a visually complete page that never
+ * hydrates, re-served on every request until the entry ages out (no eviction
+ * path exists; failure schedules no recapture by itself). Checking here turns
+ * a corrupt entry (store-layer fault) into a plain MISS the recapture
+ * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
+ * prelude flush that dominates the path.
+ */
+export function hasIntactShellPayload(entry: ShellCacheEntry): boolean {
+  try {
+    base64ToBytes(entry.prelude);
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Decode a base64 prelude back into bytes for stream composition. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** True when the store implements the shell entry family. */
+export function hasShellFamily(
+  store: SegmentCacheStore | undefined,
+): store is SegmentCacheStore & {
+  getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  putShell: NonNullable<SegmentCacheStore["putShell"]>;
+} {
+  return !!store?.getShell && !!store?.putShell;
+}
+
+/** Keys already warned about a missing shell store family (once per key). */
+const warnedMissingStore = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but the app-level cache store
+ * does not implement the shell family (getShell/putShell), so the route stays on
+ * axis 1. Unlike an undeclared route (silent), a declared route that cannot be
+ * honored deserves a diagnostic.
+ */
+export function warnShellStoreMissingOnce(key: string): void {
+  if (warnedMissingStore.has(key)) return;
+  warnedMissingStore.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
+      "cache store does not implement the shell family (getShell/putShell), so " +
+      "the route is served on axis 1 without a shell. Use MemorySegmentCacheStore, " +
+      "CFCacheStore, or VercelCacheStore (or add the family to your custom store) " +
+      "via createRouter({ cache }).",
+  );
+}
+
+/** Keys already warned about an active per-request nonce (once per key). */
+const warnedNonceActive = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export function warnPprNonceActiveOnce(key: string): void {
+  if (warnedNonceActive.has(key)) return;
+  warnedNonceActive.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+      "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
+      "ctx.set(nonce, …) token write in middleware), so the route is served on " +
+      "axis 1 without a shell. A shell is shared per host+URL; baking one " +
+      "request's nonce into it would break CSP for every other visitor. Drop the " +
+      "ppr option on this route, or stop setting a per-request nonce for it.",
+  );
+}

package/src/rsc/ssr-setup.ts

@@ -0,0 +1,176 @@
+/**
+ * SSR Setup Utilities
+ *
+ * Manages early kickoff and retrieval of SSR module loading and stream mode
+ * resolution. Both operations are request-scoped but independent of route
+ * matching, so they can run in parallel with segment resolution.
+ */
+
+import type { HandlerContext } from "./handler-context.js";
+import type { SSRModule } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+import type { MetricsStore } from "../server/context.js";
+import { appendMetric } from "../router/metrics.js";
+import {
+  parseAcceptTypes,
+  prefersFlightRepresentation,
+  RSC_WIRE_MIME,
+} from "../router/content-negotiation.js";
+import { _getRequestContext } from "../server/request-context.js";
+
+export type SSRSetup = readonly [SSRModule, SSRStreamMode];
+
+/**
+ * Key used to stash the early SSR setup promise on request variables.
+ * Read back via `getSSRSetup`.
+ */
+export const SSR_SETUP_VAR = "__ssrSetup";
+
+/**
+ * Start loading the SSR module and resolving the stream mode in parallel.
+ * When a `getMetricsStore` getter is provided, records individual
+ * `ssr:module-load` and `ssr:stream-mode` metrics (the getter is called
+ * lazily so stores created after kickoff are still captured). Without a
+ * getter the promises run bare — no `.then()` microtasks, no
+ * `performance.now()` calls — keeping the non-debug hot path lean.
+ */
+export function startSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  getMetricsStore?: () => MetricsStore | undefined,
+): Promise<SSRSetup> {
+  if (!getMetricsStore) {
+    return Promise.all([
+      ctx.loadSSRModule(),
+      ctx.resolveStreamMode(request, env, url),
+    ]);
+  }
+  const start = performance.now();
+  return Promise.all([
+    ctx.loadSSRModule().then((mod) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:module-load",
+        start,
+        performance.now() - start,
+      );
+      return mod;
+    }),
+    ctx.resolveStreamMode(request, env, url).then((mode) => {
+      appendMetric(
+        getMetricsStore(),
+        "ssr:stream-mode",
+        start,
+        performance.now() - start,
+      );
+      return mode;
+    }),
+  ]);
+}
+
+/**
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
+ * when available (stashed on request variables), otherwise starts a
+ * fresh setup.
+ */
+export function getSSRSetup<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  metricsStore: MetricsStore | undefined,
+): Promise<SSRSetup> {
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
+    | Promise<SSRSetup>
+    | undefined;
+  if (early) return early;
+  return startSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    metricsStore ? () => metricsStore : undefined,
+  );
+}
+
+/**
+ * Accept-based flight opt-in: the client explicitly listed the RSC wire
+ * format (text/x-component) in Accept, ranked above the HTML document, and
+ * did not override with __html.
+ *
+ * The flight stream is an internal transport representation — it is served
+ * ONLY on explicit opt-in (this Accept value, or the _rsc_ / __rsc transport
+ * params). Everything else (missing Accept, wildcards, application/json,
+ * browser Accept strings) gets the HTML document, per RFC 9110: a missing
+ * Accept is equivalent to a full wildcard, and a wildcard gets the server's
+ * canonical representation. The old rule ("no text/html substring → flight")
+ * handed the wire format to every generic client — curl, health checks,
+ * link unfurlers.
+ *
+ * The includes() guard is a parse-skipping fast path: the bulk of traffic
+ * (browsers, curl, monitors) never mentions the wire format and pays no
+ * parseAcceptTypes allocation. Ranking lives in prefersFlightRepresentation
+ * (router/content-negotiation.ts), co-located with the candidate MIME set.
+ */
+function acceptsFlightExplicitly(request: Request, url: URL): boolean {
+  if (url.searchParams.has("__html")) return false;
+  const accept = request.headers.get("accept");
+  if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
+  return prefersFlightRepresentation(parseAcceptTypes(accept));
+}
+
+/**
+ * Classify whether a request may require SSR (HTML rendering).
+ *
+ * Returns false for requests that are definitively RSC-only: transport
+ * params (partial/action/loader/__rsc), prerender collection, or an explicit
+ * Accept: text/x-component. Must never return false for a request whose
+ * render-time decision (isRscRequest) will be HTML — the two share
+ * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
+ * keys its HTML/RSC response slots off this function, so any divergence from
+ * the render decision poisons a cache slot with the wrong representation.
+ *
+ * Note: response/mime routes are excluded by the caller — this function
+ * runs after classifyRequest() determines the request mode.
+ */
+export function mayNeedSSR(request: Request, url: URL): boolean {
+  if (
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("_rsc_action") ||
+    request.headers.has("rsc-action") ||
+    url.searchParams.has("_rsc_loader") ||
+    url.searchParams.has("__rsc") ||
+    url.searchParams.has("__prerender_collect")
+  ) {
+    return false;
+  }
+
+  return !acceptsFlightExplicitly(request, url);
+}
+
+// Final render-time decision: is the response an RSC stream (vs HTML)?
+// Flight requires explicit opt-in: the partial transport param, __rsc, or
+// Accept: text/x-component. mayNeedSSR is the coarse pre-filter over the
+// transport params; both delegate the Accept call to acceptsFlightExplicitly.
+//
+// _rsc_partial is read from the URL in addition to the plan-derived isPartial
+// flag: the 404 fallback plan hardcodes mode "full-render" even for partial
+// navigations (handler.ts RouteNotFoundError catch), so a partial 404 reaches
+// this decision with isPartial=false. The old Accept rule masked that by
+// classifying */* as flight; without the URL check a client-side navigation
+// to a missing route received an HTML 404 it cannot apply, and the
+// navigation never committed (multi-router soft-404, popstate not-found).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("__rsc") ||
+    acceptsFlightExplicitly(request, url)
+  );
+}

package/src/rsc/transition-gate.ts

@@ -0,0 +1,89 @@
+import type { MatchResult } from "../types.js";
+import type { TransitionWhenContext } from "../types/segments.js";
+import type { getRequestContext } from "../server/request-context.js";
+import { invokeOnError } from "../router/error-handling.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * The predicates were collected during resolution (keyed by segment id) and
+ * stripped from the serialized config; here — after handlers ran and outside any
+ * cache scope — we evaluate each and drop the segment's transition when the
+ * predicate does not hold, so the navigation streams its loading fallback
+ * instead of holding the previous content. A predicate that throws is reported
+ * to the router's onError (phase "rendering") and then treated as "do not hold"
+ * (conservative), so a buggy predicate degrades to no transition rather than
+ * failing the response.
+ *
+ * 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. The flip side is that a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate) — combining transition({ when })
+ * with cache() on the same segment freezes the gate to its cached state, so
+ * avoid caching a route whose transition decision is request-dependent.
+ *
+ * Returns the same array (mutated) for inline use at the payload's `segments`
+ * field.
+ */
+export function gateTransitions(
+  segments: MatchResult["segments"],
+  ctx: ReturnType<typeof getRequestContext>,
+  onError?: OnErrorCallback,
+): MatchResult["segments"] {
+  const predicates = ctx._transitionWhen;
+  if (predicates && predicates.length) {
+    for (const { id, when } of predicates) {
+      let drop: boolean;
+      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).
+        const whenCtx: TransitionWhenContext = {
+          currentUrl: ctx._gateCurrentUrl,
+          currentParams: ctx._gateCurrentParams,
+          fromRouteName:
+            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
+          nextUrl: ctx.url,
+          nextParams: ctx.params,
+          toRouteName: ctx.routeName,
+          actionId: ctx._gateActionId,
+          actionUrl: ctx._gateActionUrl,
+          actionResult: ctx._gateActionResult,
+          formData: ctx._gateFormData,
+          method: ctx.request.method,
+          get: ctx.get,
+          env: ctx.env,
+        };
+        drop = when(whenCtx) === false;
+      } 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.
+        drop = true;
+        invokeOnError(
+          onError,
+          error,
+          "rendering",
+          {
+            request: ctx.request,
+            url: ctx.url,
+            params: ctx.params,
+            segmentId: id,
+          },
+          "RSC",
+        );
+      }
+      if (drop) {
+        const seg = segments.find((s) => s.id === id);
+        if (seg) seg.transition = undefined;
+      }
+    }
+  }
+  return segments;
+}

package/src/rsc/types.ts

@@ -7,21 +7,33 @@
 
 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>;
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
@@ -29,15 +41,39 @@ export interface RscPayload {
     handles?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** 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;
+    /** 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 +90,10 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown }
+    options?: {
+      temporaryReferences?: unknown;
+      onError?: (error: unknown) => string | void;
+    },
   ) => ReadableStream<Uint8Array>;
 
   /**
@@ -62,7 +101,7 @@ export interface RSCDependencies {
    */
   decodeReply: (
     body: FormData | string,
-    options?: { temporaryReferences?: unknown }
+    options?: { temporaryReferences?: unknown },
   ) => Promise<unknown[]>;
 
   /**
@@ -87,7 +126,7 @@ export interface RSCDependencies {
    */
   decodeFormState: (
     actionResult: unknown,
-    body: FormData
+    body: FormData,
   ) => Promise<ReactFormState | null>;
 }
 
@@ -107,6 +146,14 @@ 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;
 }
 
 /**
@@ -115,7 +162,33 @@ 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 },
+  ) => 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 },
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 
@@ -141,7 +214,7 @@ export interface HandlerCacheConfig {
  */
 export type NonceProvider<TEnv = unknown> = (
   request: Request,
-  env: TEnv
+  env: TEnv,
 ) => string | true | Promise<string | true>;
 
 /**
@@ -154,7 +227,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 +286,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 +304,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>;
-
 }