@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/rsc/render-pipeline.d.ts

@@ -0,0 +1,148 @@
+import type { TraceSpan } from "../router/tracing.js";
+import type { RenderMode, RenderPhase } from "../router/timeout.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { RscPayload } from "./types.js";
+import type { RoutineTrace } from "./routine-plan.js";
+export type RscRenderMode = RenderMode;
+export type RscRenderPhase = RenderPhase;
+export interface RscRenderStageProgress {
+    completed: number;
+    total: number;
+}
+export interface RscRenderStageContext {
+    mode: RscRenderMode;
+    phase: RscRenderPhase;
+    pathname: string;
+    progress: RscRenderStageProgress;
+    startedAt: number;
+    phaseStartedAt: number;
+    routeKey?: string;
+    actionId?: string;
+}
+export type RscRenderStageEvent = {
+    type: "stage:start";
+    context: RscRenderStageContext;
+} | {
+    type: "stage:complete";
+    context: RscRenderStageContext;
+    durationMs: number;
+} | {
+    type: "stage:error";
+    context: RscRenderStageContext;
+    durationMs: number;
+    error: unknown;
+};
+export interface RscRenderStageTracking {
+    mode?: RscRenderMode;
+    routeKey?: string;
+    actionId?: string;
+    onEvent?: (event: RscRenderStageEvent) => void;
+    /** Whole-render span receiving low-cardinality current/error phase attrs. */
+    span?: TraceSpan;
+}
+type RscRenderContext<TEnv> = Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError" | "devDiscoveryEpoch">;
+export interface RscRenderInput<TEnv> {
+    ctx: RscRenderContext<TEnv>;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    payload: RscPayload;
+    init: ResponseInit;
+    temporaryReferences?: unknown;
+    recordSerializeMetric?: boolean;
+    tracking?: RscRenderStageTracking;
+}
+export interface RscFlightStageInput<TEnv> {
+    ctx: RscRenderContext<TEnv>;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    payload: RscPayload;
+    temporaryReferences?: unknown;
+    recordSerializeMetric?: boolean;
+    tracking?: RscRenderStageTracking;
+}
+export interface RscFlightStage {
+    type: "flight";
+    payload: RscPayload;
+    stream: ReadableStream<Uint8Array>;
+    init: ResponseInit;
+}
+export interface RscPreparedHtmlRender {
+    render: () => BodyInit | null | Promise<BodyInit | null>;
+    init?: ResponseInit;
+}
+export interface RscRenderOptions {
+    html?: (flight: RscFlightStage) => RscPreparedHtmlRender | Promise<RscPreparedHtmlRender>;
+}
+interface RscFlightCommand<TEnv> {
+    type: "flight";
+    execute: () => RscFlightStage;
+    recordSerializeMetric: boolean;
+}
+interface RscHtmlCommand {
+    type: "html";
+    prepare: () => RscPreparedHtmlRender | Promise<RscPreparedHtmlRender>;
+}
+interface RscResponseCommand {
+    type: "response";
+    execute: () => Response;
+}
+export type RscRenderCommand<TEnv> = RscFlightCommand<TEnv> | RscHtmlCommand | RscResponseCommand;
+export type RscRenderCommandResult = {
+    type: "flight";
+    value: RscFlightStage;
+} | {
+    type: "html";
+    value: RscHtmlResult;
+} | {
+    type: "response";
+    value: Response;
+};
+interface RscHtmlResult {
+    body: BodyInit | null;
+    init?: ResponseInit;
+}
+export interface RscRenderDriverOptions {
+    url: URL;
+    tracking?: RscRenderStageTracking;
+    /**
+     * The plan's command sequence. Required (not defaulted): the driver reports
+     * `total` from its length, and a wrong/absent list made progress read
+     * `completed > total`. Callers of createRscRenderPlan pass rscRenderPlanPhases.
+     */
+    phases: readonly RscRenderPhase[];
+}
+type RscRenderPlan<TEnv> = Generator<RscRenderCommand<TEnv>, Response | undefined, RscRenderCommandResult>;
+/**
+ * Describe the foreground response-construction work without executing it.
+ * Each command is yielded before its work starts; the driver owns execution,
+ * attribution, and resumption.
+ */
+export declare function createRscRenderPlan<TEnv>(input: RscRenderInput<TEnv>, options?: RscRenderOptions): RscRenderPlan<TEnv>;
+/**
+ * The exact command sequence createRscRenderPlan yields, derived from the SAME
+ * `options.html` branch that shapes the plan. Callers pass this as the driver's
+ * `phases` so `total` mirrors the number of commands and progress can never
+ * report `completed > total`. Keep in lockstep with createRscRenderPlan.
+ */
+export declare function rscRenderPlanPhases(options?: RscRenderOptions): readonly RscRenderPhase[];
+/** Execute a render plan while preserving the exact result/error identities. */
+export declare function driveRscRenderPlan<TEnv>(plan: RscRenderPlan<TEnv>, options: RscRenderDriverOptions): Promise<Response>;
+/** Build a standard Flight or Flight+HTML response through the shared driver. */
+export declare function renderRscResponse<TEnv>(input: RscRenderInput<TEnv>, options?: RscRenderOptions): Promise<Response>;
+/**
+ * Construct Flight directly for specialized post-commit paths such as PPR.
+ * Standard responses use renderRscResponse so the driver owns every phase.
+ */
+export declare function renderRscFlightStage<TEnv>(input: RscFlightStageInput<TEnv>, init?: ResponseInit): RscFlightStage;
+/**
+ * Feed this driver's stage events (flight/html/response) into a routine flow
+ * trace as child entries of the currently running plan step. Stages are
+ * strictly sequential, so one `current` slot suffices. Depth is captured at
+ * creation: the bridge is built while the caller's render step executes, so
+ * children sit one level under it.
+ */
+export declare function createRenderStageTraceBridge(trace: RoutineTrace): (event: RscRenderStageEvent) => void;
+export declare function createRscStageDebugSink(log?: (message: string, details?: Record<string, unknown>) => void): (event: RscRenderStageEvent) => void;
+export {};

package/dist/types/rsc/response-cache-serve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared response-route cache serve.
+ *
+ * Owns the single response-cache contract — cache-scope resolution from the
+ * matched entry tree, condition eval, key resolution (route key() > store
+ * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
+ * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
+ * primitive (testing/dispatch.ts), so the two can never drift.
+ *
+ * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
+ * which the non-Vite unit-test runner cannot resolve, and this module is on the
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
+ * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
+ * caller (production imports them statically; dispatch lazy-imports them only once
+ * a response route matches). The only runtime imports here are plugin-rsc-free
+ * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
+ * type-only import (erased at build).
+ */
+import type { CacheScope } from "../cache/cache-scope.js";
+import type { PartialCacheOptions } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { EntryCacheConfig, EntryData } from "../server/context.js";
+/** Injected cache-scope builders (kept off this module's runtime import graph). */
+export interface CacheScopeDeps {
+    createCacheScope: (config: EntryCacheConfig | undefined, parent?: CacheScope | null) => CacheScope | null;
+    resolveCacheTags: (config: PartialCacheOptions | false, ctx: RequestContext | undefined) => string[] | undefined;
+}
+export interface ServeResponseRouteWithCacheArgs {
+    reqCtx: RequestContext;
+    manifestEntry: EntryData;
+    responseType: string;
+    url: URL;
+    /** callHandler wrapped by route-level middleware — the unit the cache wraps. */
+    executeHandler: () => Promise<Response>;
+    deps: CacheScopeDeps;
+}
+/**
+ * Serve a response route through its cache, or return `undefined` when no cache
+ * applies (no scope, disabled, condition false, or store lacks get/putResponse)
+ * so the caller falls through to a plain `executeHandler()` run.
+ *
+ * Must run inside runWithRequestContext (reads the ambient request context via
+ * the helpers and reqCtx.waitUntil for background writes).
+ */
+export declare function serveResponseRouteWithCache(args: ServeResponseRouteWithCacheArgs): Promise<Response | undefined>;

package/dist/types/rsc/response-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Problem Details (RFC 9457) Builder
+ *
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
+ */
+import type { ProblemDetails } from "../urls.js";
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
+ * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
+ */
+export declare function createProblemDetails(error: unknown, status: number, isDev: boolean): ProblemDetails;

package/dist/types/rsc/response-route-handler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Response Route Handler
+ *
+ * Handles response routes (JSON, text, HTML, XML, markdown, image, stream)
+ * that bypass the RSC rendering pipeline entirely. Includes content-type
+ * dispatch, route middleware execution, and response caching with SWR.
+ */
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { EntryData } from "../server/context.js";
+import type { HandlerContext } from "./handler-context.js";
+export interface ResponseRouteMatch {
+    responseType: string;
+    handler: Function;
+    params?: Record<string, string>;
+    negotiated?: boolean;
+    manifestEntry?: EntryData;
+    routeMiddleware?: Array<{
+        handler: MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+}
+/**
+ * Handle a response route (non-RSC). Dispatches by content type, wraps
+ * with route middleware and response caching when configured.
+ *
+ * For partial (client-side navigation) requests, returns X-RSC-Reload
+ * so the browser triggers a hard navigation to the response route URL.
+ */
+export declare function handleResponseRoute<TEnv>(handlerCtx: HandlerContext<TEnv>, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;

package/dist/types/rsc/routine-plan.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Routine plans — the request-level extension of the render stage driver
+ * (docs/design/routine-plans.md; protocol lineage in render-stage-driver.md).
+ * A plan is a synchronous generator that EMITS instructions before their work
+ * runs; the runner is the only code that executes them. Two effect shapes:
+ *
+ *   step(name, fn)     — sequential work; the plan suspends until its result.
+ *   handoff(name, fn)  — background registration (waitUntil-shaped); completes
+ *                        at scheduling and returns nothing.
+ *
+ * Plans compose by level: `yield* scope(name, plan)` flattens a nested plan
+ * into the same instruction stream while the trace records the scope. Tracking
+ * is derived, not declared — "what is running" is the instruction in hand.
+ *
+ * Deliberate boundaries (see the design doc's "Not built yet, on purpose"):
+ * the runner opens no observability spans — effects own their own
+ * instrumentation, and the render driver keeps PHASES.ssr — and there is no
+ * plan.return abort/cleanup path; the render driver's cleanup rules are the
+ * template if a caller ever needs one.
+ */
+export type RoutineEffectKind = "step" | "handoff";
+export type RoutineCommand = {
+    kind: "step";
+    name: string;
+    execute: () => unknown;
+} | {
+    kind: "handoff";
+    name: string;
+    execute: () => unknown;
+} | {
+    kind: "enter";
+    name: string;
+} | {
+    kind: "exit";
+    outcome: "done" | "failed";
+    error?: unknown;
+};
+export type RoutineCommandResult = {
+    kind: "step";
+    value: unknown;
+} | {
+    kind: "handoff";
+} | {
+    kind: "enter";
+} | {
+    kind: "exit";
+};
+/** One imperative step: yields a command, returns its typed result. */
+export type RoutineStep<T> = Generator<RoutineCommand, T, RoutineCommandResult>;
+/** A full plan is shaped like a step; the alias marks intent at call sites. */
+export type RoutinePlan<TReturn> = RoutineStep<TReturn>;
+/**
+ * Sequential work. The `as Awaited<T>` narrow is the trust boundary with the
+ * runner, which resumes with the exact value `execute` produced.
+ */
+export declare function step<T>(name: string, execute: () => T | Promise<T>): RoutineStep<Awaited<T>>;
+/**
+ * Background handoff: successful registration completes the foreground step.
+ * A synchronous registration failure is thrown back into the plan, matching a
+ * direct waitUntil/scheduler call. A returned promise settles in the background;
+ * its rejection marks the trace but never fails the foreground response.
+ *
+ * Settlement tracking follows the RETURNED value: a returned promise is
+ * observed until it settles; a scheduler that fires-and-forgets internally
+ * (e.g. scheduleShellCapture via runBackground) returns void, so its trace
+ * entry settles at the scheduling call, not at background completion. That is
+ * deliberate — the plan's contract ends at the handoff.
+ */
+export declare function handoff(name: string, execute: () => unknown): RoutineStep<void>;
+/**
+ * Run a nested plan as a named scope. `yield*` flattens its instructions into
+ * the parent stream; enter/exit only inform the trace. The scope reports its
+ * terminal outcome after internal recovery has either succeeded or escaped.
+ */
+export declare function scope<TReturn>(name: string, plan: RoutinePlan<TReturn>): RoutineStep<TReturn>;
+export interface RoutineTraceEntry {
+    name: string;
+    kind: RoutineEffectKind | "scope";
+    depth: number;
+    /** step/scope: running -> done|failed. handoff: pending -> settled|failed. */
+    state: "running" | "pending" | "done" | "settled" | "failed";
+    startedAt: number;
+    endedAt?: number;
+    settledAt?: number;
+    error?: unknown;
+}
+export interface RoutineTrace {
+    readonly name: string;
+    readonly entries: readonly RoutineTraceEntry[];
+    enterScope(name: string): void;
+    exitScope(outcome: "done" | "failed", error?: unknown): void;
+    /** Scope depth entries currently record at. Bridges (e.g. render stage
+     * events feeding child entries under a running step) capture this once and
+     * pass `depth + 1` explicitly. */
+    currentDepth(): number;
+    begin(name: string, kind: RoutineEffectKind, depth?: number): RoutineTraceEntry;
+    end(entry: RoutineTraceEntry): void;
+    fail(entry: RoutineTraceEntry, error: unknown): void;
+    settle(entry: RoutineTraceEntry, outcome: {
+        status: "fulfilled";
+    } | {
+        status: "rejected";
+        error: unknown;
+    }): void;
+    /** Running scopes plus the foreground instruction currently in hand. */
+    active(): RoutineTraceEntry[];
+    format(): string;
+    formatActive(entries?: readonly RoutineTraceEntry[], activeAt?: number): string;
+}
+export declare function createRoutineTrace(name: string, now?: () => number): RoutineTrace;
+export interface RoutineTraceOwner {
+    _activeRoutine?: RoutineTrace;
+}
+export interface RoutineRunnerOptions {
+    trace?: RoutineTrace;
+    owner?: RoutineTraceOwner;
+}
+/**
+ * Interpret a plan. Invariants shared with driveRscRenderPlan: a command is
+ * observable before its work runs, `execute` runs exactly once, results and
+ * errors resume the plan with exact identity, and a plan-level try/catch
+ * around a step is the recovery mechanism.
+ */
+export declare function runRoutine<TReturn>(plan: RoutinePlan<TReturn>, options?: RoutineRunnerOptions): Promise<TReturn>;

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

@@ -0,0 +1,18 @@
+/**
+ * RSC Rendering Handler (Navigation)
+ *
+ * Handles RSC rendering for both partial (client-side navigation) and full
+ * (initial page load) requests. Includes prerender collection for build-time
+ * static generation.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { HandlerContext } from "./handler-context.js";
+export declare function handleRscRendering<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, isPartial: boolean, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], nonce: string | undefined): Promise<Response>;
+/**
+ * Neutralize the shell-HIT degradation redirect target. The inline
+ * `location.replace` in a committed 200 body bypasses the 3xx chokepoint
+ * (guardOutgoingRedirect only sees 3xx + Location), so this reuses the same
+ * same-origin resolver directly: unsafe targets neutralize to the
+ * redirect-guard.ts landing instead of navigating the user off-host.
+ */
+export declare function resolveShellHitRedirectTarget(rawTarget: string, requestOrigin: string, basename: string | undefined): string;

package/dist/types/rsc/runtime-warnings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export declare function extractRedirectResponse(value: unknown): Response | null;
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export declare function warnNonRedirectPeResponse(): void;
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export declare function warnNonRedirectActionResponse(actionId: string): void;

package/dist/types/rsc/server-action.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Server Action Handler
+ *
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { MatchResult } from "../types.js";
+/**
+ * Data flowing from action execution to the revalidation phase.
+ * When the action completes without redirect, the handler passes this to route
+ * middleware → revalidateAfterAction.
+ *
+ * `errorBoundary` carries the matched error-boundary result when the action
+ * threw and a boundary matched. The error-boundary render is then performed in
+ * the revalidation phase so it runs INSIDE the same route-middleware wrapper as
+ * a successful revalidation — route middleware (context vars, headers, cookies)
+ * must apply to the error render too, matching the module doc's "identical to a
+ * normal render". When `errorBoundary` is set, `actionContext` is unused (the
+ * boundary is already matched; no matchPartial is run).
+ */
+export interface ActionContinuation {
+    returnValue: {
+        ok: boolean;
+        data: unknown;
+    };
+    actionStatus: number;
+    temporaryReferences: ReturnType<HandlerContext["createTemporaryReferenceSet"]>;
+    actionContext: {
+        actionId: string;
+        actionUrl: URL;
+        actionResult: unknown;
+        formData?: FormData;
+    };
+    errorBoundary?: MatchResult;
+}
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export declare function executeServerAction<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, actionId: string, handleStore: ReturnType<typeof getRequestContext>["_handleStore"]): Promise<Response | ActionContinuation>;
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export declare function revalidateAfterAction<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], continuation: ActionContinuation): Promise<Response>;

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Build-time shell entry read-through (producer B, issue #699).
+ *
+ * The build stages one ShellCacheEntry per Prerender+ppr URL as a lazy
+ * manifest module injected into the RSC bundle
+ * (`globalThis.__loadShellManifestModule`, mirroring the prerender payload
+ * manifest — the worker handles every request; nothing is served from
+ * assets). The serve path consults this on a runtime shell-store MISS, so the
+ * FIRST request after a deploy is already a shell HIT with zero runtime
+ * capture. The worker cannot tell where an entry came from: a build hit is
+ * served through the same serveShellHit as a captured one.
+ *
+ * Lifecycle:
+ * - No expiry until the next deploy — the buildVersion gate retires entries
+ *   the moment a new build ships (a new manifest replaces them anyway).
+ * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
+ *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
+ *   from build entry to fresher runtime entry, not the bootstrap path. The
+ *   runtime store is consulted first, so a captured entry supersedes the
+ *   build entry as soon as it lands.
+ * - `updateTag()` evicts build entries like runtime ones: the read-through
+ *   validates the entry's baked tag union against the store's tag
+ *   invalidation markers (isTagsInvalidatedSince) with the entry's createdAt
+ *   as the reference instant. No tombstones — the manifest is immutable; the
+ *   markers say whether it is still current.
+ */
+import type { DocumentShellCacheEntry, SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
+/** One baked manifest record (the __ps asset module's default export). */
+export interface BuildShellEntry {
+    entry: ShellCacheEntry;
+    /** Resolved ppr ttl (seconds) — drives staleness/recapture, never expiry. */
+    ttl: number;
+    swr?: number;
+    /** The putShell-barrier tag union baked at build (static + recorded). */
+    tags?: string[];
+    routeName: string;
+}
+interface ShellManifestModule {
+    /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
+    default: Record<string, string>;
+    loadShellAsset: (spec: string) => Promise<{
+        default: BuildShellEntry;
+    }>;
+}
+declare global {
+    var __loadShellManifestModule: (() => Promise<ShellManifestModule>) | undefined;
+}
+/** Reset the memoized manifest (unit tests swap the global loader). */
+export declare function resetBuildShellManifestForTests(): void;
+export interface BuildShellHit {
+    entry: DocumentShellCacheEntry;
+    /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
+    stale: boolean;
+}
+/**
+ * Dev-mode lookup context: there is no build manifest in dev, so producer B
+ * runs ON DEMAND through the Vite dev server's /__rsc_shell endpoint
+ * (memoized per router HMR generation), mirroring the dev prerender store's
+ * /__rsc_prerender flow. Only armed for PRERENDERED routes (matched.pr) —
+ * exactly production's candidate set; everything else keeps runtime capture.
+ */
+export interface DevShellLookup {
+    /** True when the classified route is trie-flagged pr (Prerender-backed). */
+    isPrerenderRoute: boolean;
+    /** Canonical route key of the classified route (endpoint verification). */
+    routeName: string | undefined;
+    /** Resolved ppr policy from the serve gate (the endpoint is policy-free). */
+    ttl: number;
+    swr?: number;
+    tags?: string[];
+    maxSnapshotBytes?: number;
+    /** Resolved `ppr.captureTimeout` (ms) — the endpoint's capture honors it. */
+    captureTimeout?: number;
+}
+/**
+ * Look up the baked shell entry for a request, applying every serve gate:
+ * search-less requests only (the build captured the bare pathname; a
+ * search-bearing URL has its own shell identity owned by runtime capture),
+ * version validity, payload integrity, and tag-invalidation markers. Returns
+ * null on any gate failure — the caller degrades to the ordinary MISS path
+ * (axis 1 + runtime capture), never a broken serve.
+ *
+ * "Search-less" is evaluated AFTER the request's `cache.searchParams` filter:
+ * a URL whose only params are excluded ones (`?fbclid=…` under a tracking
+ * exclusion) matches the baked shell — ad-click traffic is exactly the
+ * traffic the shell was prerendered for.
+ */
+export declare function lookupBuildShell(url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup, filter?: SearchParamsFilter): Promise<BuildShellHit | null>;
+export {};

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Default upper bound on the capture prerender wait before forcing the abort
+ * that freezes the shell — the ONLY wall-clock on the capture path, and a
+ * pathological guard: it should never fire once the caller's `quiesce` is a
+ * task-quantized, frozen-byte signal (the capture gate in shell-capture.ts).
+ *
+ * Leaf module on purpose (imports nothing): shell-capture.ts re-exports it
+ * (single import site for the rsc graph — shell-build-manifest.ts sizes the
+ * dev fetch envelope from that re-export) and ssr/index.tsx uses it as
+ * captureShellHTML's own fallback; the ssr graph must not pull the capture
+ * orchestration module for one number.
+ *
+ * 15s, raised from 5s: captures are background work (waitUntil), so the budget
+ * costs latency-to-HIT only — never a served response — and 5s spuriously
+ * refused legitimately-slow deferred shell material (a real storefront's meta
+ * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
+ * past response completion, and a guaranteed two-attempt envelope needs
+ * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
+ * 15s default deliberately sits just past that: attempt 1 always gets its
+ * full 15s, but when it consumed the whole budget the in-place RETRY may be
+ * truncated by the platform kill on workerd — degrading to the existing
+ * best-effort contract (the key stays MISS; a later request re-captures).
+ * Node/dev and build-time captures have no waitUntil ceiling. The per-route
+ * `ppr.captureTimeout` knob remains for tightening below the default. See
+ * docs/design/ppr-shell-resume.md (Cost model).
+ */
+export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
+/**
+ * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
+ * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+ * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
+ * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * wedges the task with no deadline in force. The task's settle path releases
+ * the per-key stampede guard and the serialized capture-queue slot, so an
+ * unbounded task strands BOTH for the isolate's lifetime.
+ *
+ * 25s: above one full-budget attempt plus overhead (cutting a second attempt
+ * short is an acceptable loss — every terminal path backs the key off anyway),
+ * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
+ * live context. When workerd kills the context BEFORE the cap fires, the timer
+ * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * check on the stampede guard, keyed off the same constant.
+ */
+export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;