@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/rsc/shell-serve.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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 { type EntryData } from "../server/context.js";
+import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+/** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
+export declare const SHELL_STATUS_HEADER = "x-rango-shell";
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export declare 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 declare const DEV_SHELL_PROBE_TIMEOUT_MS: number;
+/** 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 declare function normalizeCaptureTimeout(value: unknown): number | 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 declare function resolvePprConfig(entry: EntryData | undefined | null): ResolvedPprConfig | null;
+/**
+ * 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 declare function buildShellKey(url: URL): string;
+/**
+ * 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 declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
+/**
+ * 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 declare function hasIntactShellPayload(entry: ShellCacheEntry): boolean;
+/** Decode a base64 prelude back into bytes for stream composition. */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** True when the store implements the shell entry family. */
+export declare function hasShellFamily(store: SegmentCacheStore | undefined): store is SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+    putShell: NonNullable<SegmentCacheStore["putShell"]>;
+};
+/**
+ * Per-stage timing of one shell-HIT tail, all offsets in ms from the response
+ * commit (prelude flush). The HIT commits its 200 + headers BEFORE the live
+ * tail runs, so Server-Timing on the HIT response structurally cannot carry
+ * these numbers — they ride the dev mirror below instead (same doctrine as
+ * the ppr:capture mirror in rsc-rendering.ts, issue #651).
+ */
+export interface ShellTailTiming {
+    key: string;
+    outcome: "complete" | "redirect" | "error";
+    /** Loader-family seed decode (only when the entry carried a snapshot). */
+    seedMs?: number;
+    /** Tail router.match() settled. */
+    matchMs?: number;
+    /** Tail stream (resume output) handed to the response stream. */
+    handoverMs?: number;
+    /** First resumed-HTML byte enqueued on the wire. */
+    firstHtmlMs?: number;
+    /** Tail fully drained (last hole settled and flushed). */
+    completeMs?: number;
+    /** Prelude size flushed at commit (decoded bytes). */
+    preludeBytes?: number;
+    /** Total tail bytes streamed behind the prelude. */
+    tailBytes?: number;
+}
+/**
+ * Compact single-line form for the console log and the dev Server-Timing
+ * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
+ * escaping needed.
+ */
+export declare function describeShellTailTiming(timing: ShellTailTiming): string;
+/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+export declare function publishShellTailTiming(timing: ShellTailTiming): void;
+/**
+ * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
+ * reports into exactly one later response's Server-Timing.
+ */
+export declare function takeShellTailTimingForServerTiming(key: string): ShellTailTiming | undefined;
+/**
+ * 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 declare function warnShellStoreMissingOnce(key: string): void;
+/**
+ * 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 declare function warnPprNonceActiveOnce(key: string): void;

package/dist/types/rsc/ssr-setup.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, SSRRenderOptions } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+import type { MetricsStore } from "../server/context.js";
+import type { RscFlightStage, RscPreparedHtmlRender } from "./render-pipeline.js";
+export type SSRSetup = readonly [SSRModule, SSRStreamMode];
+/**
+ * Key used to stash the early SSR setup promise on request variables.
+ * Read back via `getSSRSetup`.
+ */
+export declare 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 declare function startSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, getMetricsStore?: () => MetricsStore | undefined): Promise<SSRSetup>;
+export interface SsrHtmlStageOptions<TEnv> {
+    ctx: HandlerContext<TEnv>;
+    request: Request;
+    env: TEnv;
+    url: URL;
+    /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
+    metricsStore: MetricsStore | undefined;
+    /**
+     * renderHTML options minus streamMode (the stage resolves streamMode). Carries
+     * the per-site nonce and, for the PE action re-render, formState. Spread
+     * verbatim so each call site's exact key set is preserved.
+     */
+    render: Omit<SSRRenderOptions, "streamMode">;
+    /** ResponseInit merged into the prepared render (e.g. content-type). */
+    init?: ResponseInit;
+}
+/**
+ * Build the `html` stage callback renderRscResponse drives: await the (possibly
+ * early-kicked-off) SSR setup, then renderHTML over the Flight stream. The four
+ * render paths (rsc-rendering full/partial, 404, PE, PE-error) differ only in
+ * metricsStore, render options (nonce/formState), and init — threaded here so
+ * the getSSRSetup + renderHTML wiring lives in one place.
+ */
+export declare function createSsrHtmlStage<TEnv>(options: SsrHtmlStageOptions<TEnv>): (flight: RscFlightStage) => Promise<RscPreparedHtmlRender>;
+/**
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
+ * when available (stashed on request variables), otherwise starts a
+ * fresh setup.
+ */
+export declare function getSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, metricsStore: MetricsStore | undefined): Promise<SSRSetup>;
+/**
+ * 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 declare function mayNeedSSR(request: Request, url: URL): boolean;
+export declare function isRscRequest(request: Request, url: URL, isPartial: boolean): boolean;

package/dist/types/rsc/transition-gate.d.ts

@@ -0,0 +1,27 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.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 declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

package/dist/types/rsc/types.d.ts

@@ -0,0 +1,292 @@
+/**
+ * RSC Handler Types
+ *
+ * Type definitions for the RSC request handler, payload structures,
+ * and SSR integration.
+ */
+import type { ResolvedSegment, SlotState } from "../types.js";
+import type { HandleData } from "../server/handle-store.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+/**
+ * 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 {
+    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;
+        }>;
+        /** Handle data accumulated across route segments (async generator that yields on each push) */
+        handles?: 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;
+        /** 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;
+    };
+}
+/**
+ * React form state type for useActionState progressive enhancement
+ */
+export type ReactFormState = unknown;
+/**
+ * RSC dependencies from @vitejs/plugin-rsc/rsc
+ */
+export interface RSCDependencies {
+    /**
+     * renderToReadableStream from @vitejs/plugin-rsc/rsc
+     */
+    renderToReadableStream: <T>(payload: T, options?: {
+        temporaryReferences?: unknown;
+        onError?: (error: unknown) => string | void;
+    }) => ReadableStream<Uint8Array>;
+    /**
+     * decodeReply from @vitejs/plugin-rsc/rsc
+     */
+    decodeReply: (body: FormData | string, options?: {
+        temporaryReferences?: unknown;
+    }) => Promise<unknown[]>;
+    /**
+     * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+     */
+    createTemporaryReferenceSet: () => unknown;
+    /**
+     * loadServerAction from @vitejs/plugin-rsc/rsc
+     */
+    loadServerAction: (actionId: string) => Promise<Function>;
+    /**
+     * decodeAction from @vitejs/plugin-rsc/rsc
+     * Decodes a FormData into a bound action function (for useActionState forms)
+     */
+    decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
+    /**
+     * decodeFormState from @vitejs/plugin-rsc/rsc
+     * Decodes the action result into a ReactFormState for useActionState progressive enhancement
+     */
+    decodeFormState: (actionResult: unknown, body: FormData) => Promise<ReactFormState | null>;
+}
+/**
+ * Options for SSR HTML rendering
+ */
+export interface SSRRenderOptions {
+    /**
+     * Form state for useActionState progressive enhancement.
+     * This is the result of decodeFormState() and should be passed to
+     * react-dom's renderToReadableStream to enable useActionState to
+     * receive the action result during SSR.
+     */
+    formState?: ReactFormState | null;
+    /**
+     * 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;
+}
+/**
+ * SSR module interface for HTML rendering
+ */
+export interface SSRModule {
+    renderHTML: (rscStream: ReadableStream<Uint8Array>, 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>>;
+}
+/**
+ * Function to load SSR module dynamically
+ */
+export type LoadSSRModule = () => Promise<SSRModule>;
+/**
+ * Cache configuration for handler.
+ * TTL is configured via store.defaults or cache() boundaries.
+ */
+export interface HandlerCacheConfig {
+    /** Cache store implementation */
+    store: import("../cache/types.js").SegmentCacheStore;
+    /** Enable/disable caching (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Nonce provider function type.
+ * Can return a nonce string, or true to auto-generate one.
+ */
+export type NonceProvider<TEnv = unknown> = (request: Request, env: TEnv) => string | true | Promise<string | true>;
+/**
+ * Options for creating an RSC handler
+ */
+export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>> {
+    /**
+     * The RSC router instance
+     */
+    router: RangoInternal<TEnv, TRoutes>;
+    /**
+     * RSC dependencies from @vitejs/plugin-rsc/rsc.
+     * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+     */
+    deps?: RSCDependencies;
+    /**
+     * Function to load the SSR module for HTML rendering.
+     * Defaults to: () => import.meta.viteRsc.loadModule("ssr", "index")
+     */
+    loadSSRModule?: LoadSSRModule;
+    /**
+     * Cache configuration for segment caching.
+     *
+     * Can be a static config object or a function that receives the env
+     * (useful for accessing Cloudflare bindings).
+     *
+     * If not provided, caching is disabled. TTL is configured via store.defaults
+     * or cache() boundaries in the route definition.
+     *
+     * @example Static config
+     * ```typescript
+     * cache: {
+     *   store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+     * }
+     * ```
+     *
+     * @example Dynamic config with env
+     * ```typescript
+     * cache: (env) => ({
+     *   store: new KVSegmentCacheStore(env.Bindings.MY_CACHE, { defaults: { ttl: 60 } }),
+     * })
+     * ```
+     */
+    cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
+    /**
+     * RSC version string included in metadata.
+     * The browser sends this back on partial requests to detect version mismatches.
+     *
+     * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+     * Only set this if you need a custom versioning strategy.
+     *
+     * @default VERSION from rsc-router:version
+     */
+    version?: string;
+    /**
+     * Nonce provider for Content Security Policy (CSP).
+     *
+     * Can be:
+     * - A function that returns a nonce string
+     * - A function that returns `true` to auto-generate a nonce
+     * - 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 the typed `nonce` token:
+     * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
+     *
+     * @example Auto-generate nonce
+     * ```tsx
+     * createRSCHandler({
+     *   router,
+     *   nonce: () => true,
+     * });
+     * ```
+     *
+     * @example Custom nonce from request context
+     * ```tsx
+     * createRSCHandler({
+     *   router,
+     *   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/dist/types/runtime-env.d.ts

@@ -0,0 +1 @@
+export declare function isUnderTestRunner(): boolean;