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

package/dist/types/server/root-layout.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from "react";
+declare const MapRootLayout: ReactNode;
+export default MapRootLayout;

package/dist/types/server.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @rangojs/router/server — Internal subpath
+ *
+ * This module is NOT user-facing. Import from "@rangojs/router" instead.
+ *
+ * Exports here are consumed by the Vite plugin (discovery, manifest injection,
+ * virtual modules) and the RSC handler internals. They are not part of the
+ * public API and may change without notice.
+ */
+export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
+export { HostRouterRegistry, type HostRouterRegistryEntry, } from "./host/router.js";
+export { registerRouteMap, setCachedManifest, clearCachedManifest, clearAllRouterData, getGlobalRouteMap, getRouterManifest, setManifestReadyPromise, setRouterManifest, setRouterTrie, setRouterPrecomputedEntries, registerRouterManifestLoader, ensureRouterManifest, } from "./route-map-builder.js";
+export { registerLoaderById, setLoaderImports, } from "./server/loader-registry.js";
+export { createRequestContext, type CreateRequestContextOptions, } from "./server/request-context.js";
+export { isClientComponent, assertClientComponent } from "./component-utils.js";
+export { clearClientUrlProjections, setClientUrlProjection, type ClientUrlProjection, } from "./client-urls/server-projection.js";

package/dist/types/ssr/index.d.ts

@@ -0,0 +1,271 @@
+import React from "react";
+import type { ErrorPhase } from "../types.js";
+import type { HeadScriptsOption } from "../vite/plugin-types.js";
+export { installClientReferencePreinit } from "./preinit-client-references.js";
+/**
+ * Options for injectRSCPayload
+ */
+export interface InjectRSCPayloadOptions {
+    /**
+     * Nonce for Content Security Policy (CSP)
+     */
+    nonce?: string;
+}
+/**
+ * Options for renderToReadableStream from react-dom/server
+ */
+interface RenderToReadableStreamOptions {
+    bootstrapScriptContent?: string;
+    bootstrapModules?: string[];
+    nonce?: string;
+    formState?: unknown;
+}
+/**
+ * ReadableStream with the allReady promise added by react-dom/server.edge.
+ */
+interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
+    allReady: Promise<void>;
+}
+/**
+ * Options for prerender from react-dom/static.edge
+ */
+interface PrerenderOptions {
+    signal?: AbortSignal;
+    bootstrapScriptContent?: string;
+    bootstrapModules?: string[];
+    onError?: (error: unknown) => void;
+}
+/**
+ * Result of prerender from react-dom/static.edge. `postponed` is React's
+ * opaque resume state — non-null when the render was aborted with pending
+ * holes, null when the shell completed with nothing left to stream.
+ */
+interface PrerenderResult {
+    prelude: ReadableStream<Uint8Array>;
+    postponed: unknown;
+}
+/**
+ * prerender from react-dom/static.edge
+ */
+type PrerenderFn = (element: React.ReactNode, options?: PrerenderOptions) => Promise<PrerenderResult>;
+/**
+ * Options for resume from react-dom/server.edge
+ */
+interface ResumeOptions {
+    onError?: (error: unknown) => void;
+    nonce?: string;
+}
+/**
+ * resume from react-dom/server.edge — continues a prerendered render, emitting
+ * only the postponed holes.
+ */
+type ResumeFn = (element: React.ReactNode, postponedState: unknown, options?: ResumeOptions) => Promise<ReactDOMReadableStream>;
+/**
+ * Options for the renderHTML function
+ */
+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?: unknown;
+    /**
+     * 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 (`?`-prefixed or empty). Seeds the SSR
+     * navigation store location so `useSearchParams` carries real values
+     * during document renders. Absent on the build-time prerender pass —
+     * build shells capture bare pathnames and serve search-less requests
+     * only (runtime captures own the search variants, seeded per key).
+     */
+    search?: string;
+    /**
+     * The live request's origin, seeding the SSR store location so
+     * origin-dependent markup (Link's data-external) agrees with the
+     * browser's window.location across hydration. Absent on the build-time
+     * prerender pass (host-agnostic bare captures).
+     */
+    origin?: string;
+}
+/**
+ * SSR dependencies from external packages
+ */
+export interface SSRDependencies<TEnv = unknown> {
+    /**
+     * createFromReadableStream from @rangojs/router/internal/deps/ssr
+     */
+    createFromReadableStream: <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+    /**
+     * renderToReadableStream from react-dom/server.edge
+     */
+    renderToReadableStream: (element: React.ReactNode, options?: RenderToReadableStreamOptions) => Promise<ReactDOMReadableStream>;
+    /**
+     * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
+     */
+    injectRSCPayload: (rscStream: ReadableStream<Uint8Array>, options?: InjectRSCPayloadOptions) => TransformStream<Uint8Array, Uint8Array>;
+    /**
+     * Function to load bootstrap script content
+     * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+     */
+    loadBootstrapScriptContent: () => Promise<string>;
+    /**
+     * Document script strategy; the generated virtual SSR entry threads the
+     * `rango({ headScripts })` plugin option here (canonical docs on
+     * `RangoBaseOptions.headScripts` in vite/plugin-types.ts). The
+     * bootstrapModules conversion runs ONLY on an explicit `"preinit"`:
+     * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
+     * never installed the preinit hook cannot drift into the half-converted
+     * state on upgrade (the generated entry always passes an explicit value).
+     */
+    headScripts?: HeadScriptsOption;
+    /**
+     * prerender from react-dom/static.edge. Optional; required only by
+     * {@link createShellCaptureHandler} for PPR shell capture.
+     */
+    prerender?: PrerenderFn;
+    /**
+     * resume from react-dom/server.edge. Optional; required only by
+     * {@link createShellResumeHandler} for resuming a postponed shell.
+     */
+    resume?: ResumeFn;
+    /**
+     * Optional callback invoked when an error occurs during SSR rendering.
+     *
+     * This callback is for notification/logging purposes.
+     *
+     * @example
+     * ```typescript
+     * export const renderHTML = createSSRHandler({
+     *   // ... other deps
+     *   onError: (error, context) => {
+     *     console.error('[SSR] Rendering error:', error);
+     *     Sentry.captureException(error);
+     *   },
+     * });
+     * ```
+     */
+    onError?: (error: Error, context: {
+        phase: ErrorPhase;
+    }) => void;
+}
+/**
+ * True when a debugger is attached outside a production build: a breakpoint
+ * pauses script execution but not wall-clock, so the capture deadline would
+ * expire mid-inspection and push the key into refusal/backoff while debugging.
+ * Next.js precedent (packages/next/src/export/worker.ts): its static-page
+ * timeout race is disabled when NODE_OPTIONS contains --inspect. The gate is
+ * the bare `process.env.NODE_ENV !== "production"` token — the build define
+ * folds exactly that token to a literal (same dev signal as shell-capture.ts's
+ * isDevMode), and it covers dev servers that never set NODE_ENV, the common
+ * debug case. A production worker launched with --inspect in NODE_OPTIONS
+ * keeps the capture's safety bound unconditionally. Every probe is guarded:
+ * `process` reads are optional-chained and the node:inspector import is
+ * try/caught, so non-Node runtimes (workerd) resolve to false instead of
+ * breaking.
+ */
+export declare function isDebuggerAttached(): Promise<boolean>;
+/**
+ * Options for the captureShellHTML function returned by
+ * {@link createShellCaptureHandler}.
+ */
+interface ShellCaptureOptions {
+    /** Caller-provided promise that resolves once the cached content settled. */
+    quiesce: Promise<void>;
+    /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
+    maxWaitMs?: number;
+    /**
+     * The SHELL KEY's search string (`?`-prefixed, sorted, cache.searchParams
+     * filter applied — shellSearchSeed in rsc/shell-serve.ts), seeding the SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key. MUST equal the resume pass's seed for the same key.
+     */
+    search?: string;
+    /**
+     * The capture request's origin. Shell keys are host-scoped, so the resume
+     * pass's request agrees modulo protocol drift; seeding it keeps
+     * origin-dependent static markup (Link's data-external) identical across
+     * capture, resume, and browser hydration.
+     */
+    origin?: string;
+}
+/**
+ * Result of a successful shell capture. `prelude` is the raw prelude bytes;
+ * `postponed` is React's resume state serialized to JSON, or null when the
+ * shell completed with no holes (the DATA variant).
+ */
+interface ShellCaptureResult {
+    prelude: Uint8Array;
+    postponed: string | null;
+}
+/**
+ * Options for the resumeShellHTML function returned by
+ * {@link createShellResumeHandler}.
+ */
+interface ShellResumeOptions {
+    /** JSON from capture; null selects the DATA variant (no fizz). */
+    postponed: string | null;
+    /** Nonce for CSP. */
+    nonce?: string;
+    /**
+     * The SHELL KEY's search string — same derivation as the capture pass
+     * (shellSearchSeed). A HIT shares the capture's key, so seeding the same
+     * string keeps the resume tree identical to the captured tree above the
+     * postponed holes.
+     */
+    search?: string;
+    /** The HIT request's origin — same host as the capture's (key-scoped). */
+    origin?: string;
+}
+/**
+ * Create an SSR handler that converts RSC streams to HTML.
+ *
+ * @example
+ * ```tsx
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+ * import { renderToReadableStream } from "react-dom/server.edge";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+ *
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
+ *   loadBootstrapScriptContent: () =>
+ *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
+ * });
+ * ```
+ */
+export declare function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, options?: SSRRenderOptions) => Promise<ReadableStream<Uint8Array>>;
+/**
+ * Create the PPR shell capture handler.
+ *
+ * captureShellHTML prerenders the shell over the (cached, loader-masked) Flight
+ * stream, aborts once the shell settles, and returns the prelude bytes plus the
+ * postponed resume state for storage. The stored pair is later served by
+ * {@link createShellResumeHandler}. See docs/design/ppr-shell-resume.md.
+ *
+ * Throws at creation if `deps.prerender` is missing — capture cannot run
+ * without react-dom/static.edge's prerender.
+ */
+export declare function createShellCaptureHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, opts: ShellCaptureOptions) => Promise<ShellCaptureResult | null>;
+/**
+ * Create the PPR shell resume handler.
+ *
+ * resumeShellHTML produces the per-request live portion of the document: for a
+ * postponed shell it resumes fizz over a fresh SsrRoot to emit only the holes;
+ * for the DATA variant it emits only the fresh Flight payload scripts. The
+ * caller (shell-cache middleware) prepends the stored prelude bytes to form the
+ * composite response. See docs/design/ppr-shell-resume.md.
+ */
+export declare function createShellResumeHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, opts: ShellResumeOptions) => Promise<ReadableStream<Uint8Array>>;

package/dist/types/ssr/inject-rsc-eager.d.ts

@@ -0,0 +1,3 @@
+export declare function injectRSCPayloadEager(rscStream: ReadableStream<Uint8Array>, options?: {
+    nonce?: string;
+}): TransformStream<Uint8Array, Uint8Array>;

package/dist/types/ssr/preinit-client-references.d.ts

@@ -0,0 +1,71 @@
+/**
+ * JS/CSS asset deps plugin-rsc resolves for a client reference. Structural
+ * mirror of @vitejs/plugin-rsc's ResolvedAssetDeps — deliberately not imported:
+ * @rangojs/router/ssr never imports plugin-rsc directly; every plugin binding
+ * is injected by the virtual SSR entry (see SSRDependencies).
+ */
+export interface ClientReferenceDeps {
+    js: string[];
+    css: string[];
+}
+/**
+ * Callback shape of @vitejs/plugin-rsc/ssr's setOnClientReference. Fired
+ * (synchronously, inside the Fizz render) whenever a client reference module
+ * is accessed during SSR — the same moment plugin-rsc issues its own
+ * ReactDOM.preloadModule calls for the reference's chunks.
+ */
+export type OnClientReference = (reference: {
+    id: string;
+    deps: ClientReferenceDeps;
+}) => void;
+/** setOnClientReference from @vitejs/plugin-rsc/ssr (injected). */
+export type SetOnClientReference = (callback: OnClientReference | undefined) => void;
+/**
+ * Run a Fizz render (renderToReadableStream / prerender / resume) with the
+ * request's nonce visible to the client-reference preinit hook. Nonce-less
+ * requests (the common non-CSP configuration) skip the ALS frame entirely —
+ * getStore() on an unentered storage already returns undefined, so the hook
+ * reads the same value either way.
+ */
+export declare function runWithPreinitNonce<T>(nonce: string | undefined, fn: () => T): T;
+/**
+ * Upgrade plugin-rsc's client-reference modulepreload hints to executing
+ * scripts: for every JS chunk a client reference needs, emit
+ * `<script type="module" src async>` hoisted into the document head instead of
+ * only `<link rel="modulepreload">`.
+ *
+ * Why: modulepreload fetches + compiles but never executes; the chunks then
+ * execute only when the entry's hydration import walks the graph — after the
+ * whole document has streamed. preinitModule starts execution as soon as each
+ * chunk arrives, overlapping it with body streaming (the pattern Next.js uses
+ * via ReactDOM.preinit for all non-bootstrap chunks). Under PPR the preinits
+ * run during shell capture, so the executing tags live in the stored prelude
+ * and chunk execution starts on the first flushed bytes.
+ *
+ * No duplicate tags: plugin-rsc's preloadModule fires first in the same
+ * synchronous block; Fizz's preinitModuleScript then clears the queued preload
+ * chunks for that URL and adopts its credentials (ReactFizzConfigDOM,
+ * renderState.preloads.moduleScripts). Capture→resume double-emission is
+ * prevented the same way: the `moduleScriptResources[src] = null` markers
+ * serialize inside the postponed state, so the resume pass preinits only
+ * references the shell never saw.
+ *
+ * crossOrigin "" matches plugin-rsc's preloadModule creds so the upgrade path
+ * reuses the same resource instead of forking on credential mismatch.
+ *
+ * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
+ * PR #694 has the Lighthouse/hydration numbers):
+ * - Fetch priority: an executing async module script fetches at Chromium's
+ *   async-script priority, below a bare modulepreload hint; preinitModule
+ *   forwards no fetchPriority (react-dom's public API drops it — only
+ *   `preinit` forwards it). Execution-overlap is bought with hint priority,
+ *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
+ *   dev documents have no head chunk scripts — a client module whose module
+ *   scope assumes body-parsed DOM can break in production only. The
+ *   `rango({ headScripts: "preload" })` escape hatch restores hint-only.
+ * - plugin-rsc's setOnClientReference is a single-slot, last-write-wins
+ *   setter: another registrant in the SSR environment silently replaces this
+ *   hook (or is replaced by it). No composition API exists upstream yet.
+ */
+export declare function installClientReferencePreinit(setOnClientReference: SetOnClientReference): void;

package/dist/types/ssr/ssr-root.d.ts

@@ -0,0 +1,84 @@
+import React from "react";
+import type { HandleData } from "../browser/types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+/**
+ * createFromReadableStream from @rangojs/router/internal/deps/ssr.
+ * Deserializes the Flight branch used to build the SSR VDOM.
+ */
+export type CreateFromReadableStream = <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+export interface RscPayload {
+    metadata?: {
+        segments?: ResolvedSegment[];
+        rootLayout?: React.ComponentType<{
+            children: React.ReactNode;
+        }>;
+        handles?: AsyncGenerator<HandleData, void, unknown>;
+        matched?: string[];
+        pathname?: string;
+        params?: Record<string, string>;
+        basename?: string;
+        themeConfig?: ResolvedThemeConfig | null;
+        initialTheme?: Theme;
+        version?: string;
+    };
+}
+/**
+ * Options for {@link createSsrRootComponent}.
+ */
+export interface SsrRootOptions {
+    /** createFromReadableStream for the SSR branch of the Flight stream. */
+    createFromReadableStream: CreateFromReadableStream;
+    /** The Flight stream branch to deserialize into the SSR VDOM. */
+    rscStream: ReadableStream<Uint8Array>;
+    /** Nonce for CSP; propagated to NonceContext. */
+    nonce?: string;
+    /**
+     * Fires once when the Flight payload root settles (resolve OR reject) — the
+     * signal that every client-module load the payload references completed and
+     * fizz can start emitting the tree. The capture pass gates its abort on
+     * this: a fully REPLAYED (prerendered) route's Flight stream goes
+     * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
+     * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
+     * graph), so an abort gated on Flight quiet alone fires first and freezes
+     * a zero-byte prelude. Masked-loader holes do NOT block this signal —
+     * they postpone below the root.
+     */
+    onPayloadSettled?: () => void;
+    /**
+     * The query string seeding the SSR store location (`?`-prefixed or
+     * empty), so `useSearchParams`/`useNavigation` carry real values during
+     * document renders. Live fizz passes the request's raw search. The shell
+     * capture and resume passes pass the SHELL KEY's search (sorted,
+     * cache.searchParams filter applied — search is part of shell identity):
+     * a HIT shares the capture's key, so both passes seed the SAME string and
+     * the resume tree matches the captured tree above the postponed holes.
+     */
+    search?: string;
+    /**
+     * Origin seeding the SSR store location (see createSsrEventController):
+     * live fizz passes the request's origin; capture/resume pass theirs.
+     */
+    origin?: string;
+}
+/**
+ * Build the closure component that deserializes the Flight payload, consumes
+ * handles to completion, builds the segment tree, and wraps it in the
+ * NavigationStore / Nonce / Theme providers.
+ *
+ * The full-fizz path (renderHTML), the shell prerender pass (capture), and the
+ * shell resume pass all render this identical tree. `resume` requires the tree
+ * above the postponed holes to match the prerendered tree; rendering the same
+ * builder over the same replayed segments is what makes that hold. A fresh
+ * component instance per pass is fine — replay matches structure, not function
+ * identity.
+ *
+ * The memo slots (payload/handles/context/root) are closure-scoped to the
+ * returned instance, so each render pass memoizes independently. renderSegments
+ * is async: React.use() on a fresh promise would suspend and replay SsrRoot,
+ * re-running the whole segment-tree build unless the promise is memoized.
+ */
+export declare function createSsrRootComponent(opts: SsrRootOptions): React.FC;

package/dist/types/ssr-suspension-warning.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dev-only diagnostic for the { ssr: false } SSR-completeness opt-in.
+ *
+ * A document render that awaits flagged loaders before first flush is usually
+ * expected to produce an SSR-complete boundary — but the await is scoped per
+ * LOADER (see LoaderOptions in types/loader-types.ts), so one unflagged read
+ * under the same Suspense boundary still suspends it and the boundary streams
+ * as its fallback, invisible without JS. That failure mode looks exactly like
+ * the flag not working; a consumer app burned hours on byte-level archaeology
+ * before the unflagged sibling read was identified. This warning names the
+ * culprit at the suspension site instead.
+ *
+ * Fires at most once per loader id per process, only during the SSR pass
+ * (`window` undefined), only in dev, and only when the render actually awaited
+ * flagged loaders (`awaitedLoaderIds` is stamped by segment resolution on the
+ * document lane and deliberately NOT during shell capture, where live loaders
+ * are masked with never-resolving promises and every read suspends by design).
+ */
+export declare function warnAwaitedSsrSuspension(loaderId: string, awaitedLoaderIds: readonly string[] | undefined, stream: Promise<unknown>, isServer?: boolean): void;

package/dist/types/static-handler.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Static handler definition for build-time rendering of individual segments.
+ *
+ * Static wraps a handler so that in production the segment is
+ * rendered once at build time. The handler is then replaced with a static
+ * asset import -- no runtime store lookup needed.
+ *
+ * In dev mode, Static behaves as a normal handler: the wrapped
+ * function runs on every request, identical to a regular layout/path handler.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * Key difference from Prerender:
+ *   - Prerender: route-scoped, produces URLs via getParams, renders subtree per-params
+ *   - Static: segment-scoped, renders once, no URLs, no params
+ *
+ * Works on: layout(), parallel(), and path().
+ *
+ * @example
+ * ```ts
+ * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
+ * export const DocShell = Static((ctx) => <Shell />);
+ *
+ * urls(({ path, layout }) => [
+ *   layout(DocsNav, () => [
+ *     path("/getting-started", DocShell, { name: "doc.gs" }),
+ *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *   ]),
+ * ]);
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { Handler } from "./types.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
+export interface StaticHandlerOptions {
+    /**
+     * Keep handler in server bundle for live fallback (default: false).
+     * false: handler replaced with stub, source-only APIs excluded from bundle.
+     * true: handler stays in bundle, renders live at request time.
+     */
+    passthrough?: boolean;
+}
+declare const STATIC_HANDLER_REF: unique symbol;
+/**
+ * Opaque identity used by DSL type seams that accept Static() values.
+ *
+ * The brand is required, never optional: an optional brand makes this a weak
+ * type, and weak-type checking lets `{}` through — `parallel({ "@x": {} })`
+ * would typecheck and then die at render as an invalid React child. The
+ * symbol never exists at runtime; Static() casts its return instead.
+ */
+export interface StaticHandlerRef {
+    /** @internal Type-only brand; see interface doc. */
+    readonly [STATIC_HANDLER_REF]: true;
+}
+export interface StaticHandlerDefinition<TParams extends Record<string, any> = any> extends StaticHandlerRef {
+    readonly __brand: "staticHandler";
+    /** Auto-generated unique ID (injected by Vite plugin). */
+    $$id: string;
+    /** In dev mode, the actual handler function that layout/path/parallel can call. */
+    handler: Handler<TParams>;
+    /** Static handler options (passthrough support). */
+    options?: StaticHandlerOptions;
+    /** Composable default DSL items merged when the handler is mounted. */
+    use?: () => UseItems<HandlerUseItem>;
+}
+export declare function Static<TParams extends Record<string, any> = {}>(handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>, options?: StaticHandlerOptions, __injectedId?: string): StaticHandlerDefinition<TParams>;
+export declare function isStaticHandler(value: unknown): value is StaticHandlerDefinition;
+export {};

package/dist/types/testing/cache-status.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+import type { CacheDecisionEvent, CacheSegmentStatus, TelemetryEvent, TelemetrySink } from "../router/telemetry.js";
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | {
+    headers: Headers;
+};
+export declare function parseCacheHeader(headerValue: string | null | undefined): Record<string, string>;
+export declare function assertCacheStatus(target: CacheStatusTarget, segment: string, expected: ExpectedCacheStatus): void;
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+    /** Wire into `createRouter({ telemetry: sink })`. */
+    sink: TelemetrySink;
+    /** All telemetry events captured so far, in emit order. */
+    events: TelemetryEvent[];
+}
+export declare function createCacheSink(): CacheSink;
+export declare function filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[];
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export declare function assertCacheDecision(events: readonly TelemetryEvent[], routeKey: string, expected: ExpectedCacheStatus): void;

package/dist/types/testing/collect-handle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to the default identity collect — with a
+ * warning, since a CUSTOM collect that failed to register silently returns the
+ * wrong shape.
+ */
+import { type Handle } from "../handle.js";
+export declare function collectHandle<TData, TAccumulated>(handle: Handle<TData, TAccumulated>, segments: ReadonlyArray<ReadonlyArray<TData>>): TAccumulated;