@rangojs/router 0.5.0 → 0.5.2

package/README.md

@@ -439,10 +439,14 @@ For response-aware and path-based utilities (`href()`, `Rango.Path`,
 // router.tsx
 const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109), so extend through a named alias.
+type AppRoutes = typeof router.routeMap;
+
 declare global {
   namespace Rango {
     interface Env extends AppEnv {}
-    interface RegisteredRoutes extends typeof router.routeMap {}
+    interface RegisteredRoutes extends AppRoutes {}
   }
 }
 ```

package/dist/types/browser/event-controller.d.ts

@@ -180,6 +180,12 @@ export interface EventController {
     subscribe(listener: StateListener): () => void;
     subscribeToAction(actionId: string, listener: ActionStateListener): () => void;
     subscribeToHandles(listener: HandleListener): () => void;
+    /**
+     * Deliver queued location, params, navigation, and handle notifications now.
+     * NavigationProvider calls this inside the payload update so React assigns
+     * every route-state hook update to the same normal or transition lane.
+     */
+    flushRouteState(): void;
     setHandleData(data: HandleData, matched?: string[], isPartial?: boolean, 
     /**
      * Segment ids that were re-resolved on the server this request (the

package/dist/types/browser/prefetch/cache.d.ts

@@ -67,8 +67,31 @@ export interface DecodedPrefetch {
      * tell a FULLY warmed prefetch (payload commits without suspending → safe to
      * commit in a startTransition, no fallback flash) from a partially-warmed one
      * (still streaming → stream its fallbacks like a cold load). Starts false.
+     *
+     * On a respawned entry (see `respawn`) this starts true: the buffered bytes
+     * are a complete stream by construction.
      */
     complete: boolean;
+    /**
+     * Re-create this entry from its buffered raw Flight bytes. Attached (by
+     * `executePrefetchFetch`) only after the stream ended cleanly AND the eager
+     * decode succeeded — a truncated or failed prefetch must stay one-shot.
+     *
+     * Why bytes and not the decoded payload: the revived payload is a live graph
+     * with one-shot stream edges (the handle stream is an async generator drained
+     * during commit; userland payloads may embed serialized ReadableStreams).
+     * Re-decoding from the wire bytes manufactures fresh instances of every
+     * stream, which no amount of cloning the revived graph can do. Each call tees
+     * the reserve branch, so the replacement entry carries its own `respawn` —
+     * one prefetch serves unlimited adoptions within TTL/state validity.
+     */
+    respawn?: () => DecodedPrefetch;
+    /**
+     * Release the buffered reserve bytes. Called when the entry is evicted
+     * without being consumed (expiry, FIFO, sweep, cache clear) so the tee
+     * buffer is dropped promptly instead of waiting for GC.
+     */
+    dispose?: () => void;
 }
 /**
  * Initialize the prefetch cache with the configured TTL and max size.
@@ -123,8 +146,14 @@ export declare function buildSourceKey(rangoState: string, sourceHref: string, t
 export declare function hasPrefetch(key: string): boolean;
 /**
  * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
- * expired. One-time consumption: the entry is deleted after retrieval.
- * Returns null when caching is disabled (TTL <= 0).
+ * expired. Returns null when caching is disabled (TTL <= 0).
+ *
+ * A decoded payload is single-render (its handle stream is drained during the
+ * commit), so the returned entry is never served twice. When the entry carries
+ * `respawn` (clean-EOF prefetch with buffered bytes), the slot is re-armed in
+ * place with a fresh decode of those bytes — the ORIGINAL timestamp is kept so
+ * TTL bounds the age of the data, not of the latest adoption. Without
+ * `respawn` the entry is deleted (legacy one-shot behavior).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -65,8 +65,15 @@ export declare const MAX_REVALIDATION_INTERVAL = 30;
  *
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
  */
-export declare const EDGE_LOOKUP_TIMEOUT_MS = 10;
+export declare const EDGE_LOOKUP_TIMEOUT_MS = 25;
 /**
  * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
  * (response.json()) before treating the read as a miss.

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -302,6 +302,19 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /**
      * Convert string key to KV key string.
      * Uses same version prefix as Cache API for consistent invalidation.
+     *
+     * Single chokepoint for EVERY KV family (segments, items, shells, documents
+     * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+     * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+     * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+     * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+     * and the entry silently never reaches L2 (observed in production for
+     * "use cache" items whose serialized args — e.g. a CMS query object — blow
+     * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+     * normalization is semantics-preserving as long as distinct logical keys
+     * stay distinct: colliding requires an identical 400-byte prefix AND a
+     * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+     * and delete paths agree on the stored key.
      * @internal
      */
     private toKVKey;
@@ -546,7 +559,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      *
      * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
      * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-     * fails (transient error, or an over-512-byte key), this rejects with the
+     * fails (transient error; over-limit keys are normalized by toKVKey rather
+     * than rejected), this rejects with the
      * failed tags so an awaiting updateTag() surfaces the failure instead of
      * silently reporting success while other requests/colos serve stale data. The
      * eager purge still fires for the whole batch first (it is additive).

package/dist/types/cache/cf/cf-cache-types.d.ts

@@ -288,7 +288,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * cannot stall the request; the read then falls through to its normal miss
      * path (L2/KV or render).
      *
-     * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+     * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (25). Set to 0 (or any value
      * <= 0) to disable the budget and always await `match`.
      */
     edgeLookupTimeoutMs?: number;

package/dist/types/cache/cf/cf-kv-utils.d.ts

@@ -9,6 +9,27 @@ export declare const KV_MAX_KEY_BYTES = 512;
 export declare const KV_MIN_EXPIRATION_TTL = 60;
 /** UTF-8 byte length of a KV key (multibyte tags can exceed the char count). */
 export declare function kvKeyByteLength(key: string): number;
+/**
+ * Bytes of a composed key preserved verbatim when an over-limit key is
+ * normalized (toKVKey). 400 leaves room for the `~` separator and the 32-hex
+ * digest inside KV_MAX_KEY_BYTES while keeping the version prefix and most of
+ * the logical key readable (and prefix-listable) in the KV dashboard.
+ */
+export declare const KV_KEY_PRESERVED_PREFIX_BYTES = 400;
+/**
+ * Truncate to at most `maxBytes` of UTF-8. A multibyte sequence split at the
+ * boundary decodes to U+FFFD, which is stripped — the result is deterministic
+ * for a given input, which is all key normalization needs.
+ */
+export declare function truncateToBytes(value: string, maxBytes: number): string;
+/**
+ * 128-bit hex digest (SHA-256 truncated) of a composed KV key. WebCrypto is
+ * available on workerd and Node alike; SHA-256 (not a fast non-crypto hash)
+ * because cache keys embed user-influenced serialized args — an engineered
+ * collision between two normalized keys would serve one entry's payload for
+ * the other's.
+ */
+export declare function kvKeyDigest(value: string): Promise<string>;
 /**
  * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
  * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the

package/dist/types/handles/is-thenable.d.ts

@@ -1,8 +1,6 @@
 /**
- * Single thenable predicate for the resolve-by-default handle machinery
- * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
- * handle entries are deferred (`Promise`) values to await before any consumer
- * sees them, and which pass through verbatim.
+ * Shared thenable predicate for framework orchestration. It decides which values
+ * participate in promise lifecycles and which pass through synchronously.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
  * `"then" in obj` membership check, so a non-promise carrying a `then` field

package/dist/types/route-definition/helpers-types.d.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { ExtractRouteParams, Handler, PartialCacheOptions, ErrorBoundaryHandler, LoaderDefinition, MiddlewareFn, NotFoundBoundaryHandler, ResolvedRouteMap, RouteDefinition, ShouldRevalidateFn, TransitionConfig } from "../types.js";
 import type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, CacheItem, TransitionItem, UseItems } from "../route-types.js";
+import type { StaticHandlerRef } from "../static-handler.js";
 export type { AllUseItems, LayoutItem, RouteItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ParallelUseItem, InterceptUseItem, CacheItem, } from "../route-types.js";
 export type { InterceptConfig, InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "../server/context";
 /**
@@ -75,8 +76,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *   },
      * })
      * ```
-     * @param slots - Object with slot names (prefixed with @) mapped to handlers
-     *                or `{ handler, use? }` slot descriptors.
+     * @param slots - Object with slot names (prefixed with @) mapped to handlers,
+     *                Static() definitions, or `{ handler, use? }` descriptors.
      * @param use - Optional callback for loaders, loading, revalidate, etc.
      *              Items here apply to every slot in the call (broadcast).
      *              For per-slot single-assignment items, use the slot descriptor's
@@ -84,8 +85,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *              so they take precedence on `loading()` and other last-write-wins
      *              fields.
      */
-    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | {
-        handler: Handler<any, any, TEnv> | ReactNode;
+    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | StaticHandlerRef | {
+        handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
         use?: () => UseItems<ParallelUseItem>;
     }>, use?: () => UseItems<ParallelUseItem>) => ParallelItem;
     /**

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

@@ -6,6 +6,7 @@
 import type { RequestContext } from "../server/request-context.js";
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
 /**
  * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
  * iteration prevents re-entrant registrations from double-firing and matches
@@ -122,3 +123,5 @@ export declare function mergeStubHeadersAndFinalize(response: Response): Respons
  * but still need ctx.onResponse() callbacks to fire.
  */
 export declare function finalizeResponse(response: Response): Response;
+/** Match and stamp params/routeName on the request context as one operation. */
+export declare function matchAndRecordParams<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>>;

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

@@ -2,6 +2,7 @@ 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 {
@@ -135,5 +136,13 @@ export declare function renderRscResponse<TEnv>(input: RscRenderInput<TEnv>, opt
  * 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/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/shell-capture-constants.d.ts

@@ -25,3 +25,20 @@
  * 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;

package/dist/types/server/request-context.d.ts

@@ -26,6 +26,7 @@ import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RoutineTrace } from "../rsc/routine-plan.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
     phase: RenderPhase;
@@ -542,6 +543,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * loaders and post-commit stream work have separate lifetimes.
      */
     _renderForeground?: RenderForegroundCursor;
+    /** @internal Request routine currently executing, used by timeout diagnostics. */
+    _activeRoutine?: RoutineTrace;
     /** @internal Keep the render cursor active for timeout support. */
     _renderDiagnosticsEnabled?: boolean;
     /**
@@ -585,7 +588,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

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

@@ -42,7 +42,20 @@ export interface StaticHandlerOptions {
      */
     passthrough?: boolean;
 }
-export interface StaticHandlerDefinition<TParams extends Record<string, any> = any> {
+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;
@@ -55,3 +68,4 @@ export interface StaticHandlerDefinition<TParams extends Record<string, any> = a
 }
 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/urls/path-helper-types.d.ts

@@ -3,7 +3,7 @@ import type { ErrorBoundaryHandler, ExtractParams, Handler, HandlerContext, Load
 import type { AllUseItems, TypedLayoutItem, ParallelItem, InterceptItem, MiddlewareItem, RevalidateItem, LoaderItem, LoadingItem, ErrorBoundaryItem, NotFoundBoundaryItem, LayoutUseItem, RouteUseItem, ResponseRouteUseItem, ParallelUseItem, InterceptUseItem, LoaderUseItem, TypedCacheItem, TransitionItem, TypedTransitionItem, TypedRouteItem, TypedIncludeItem, UseItems } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import type { PrerenderHandlerDefinition, PassthroughHandlerDefinition } from "../prerender.js";
-import type { StaticHandlerDefinition } from "../static-handler.js";
+import type { StaticHandlerDefinition, StaticHandlerRef } from "../static-handler.js";
 import type { ResponseHandler, ResponseHandlerContext, TextResponseHandler } from "./response-types.js";
 import type { UnnamedRoute, LocalOnlyInclude, PathOptions, UrlPatterns, IncludeOptions } from "./pattern-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
@@ -118,13 +118,12 @@ export type PathHelpers<TEnv> = {
      *
      * Not generic over the slots record: an inferred type parameter makes the
      * object literal an inference site, which suppresses contextual typing of
-     * arrow slot handlers (`(ctx) => ...` was implicit any). Bare handlers infer
-     * now; a descriptor's `handler:` arrow still needs an explicit ctx annotation
-     * because StaticHandlerDefinition's own `.handler` joins the contextual union
-     * (two callables — see parallel-slot-handler-types.test.ts).
+     * arrow slot handlers (`(ctx) => ...` was implicit any). Static() values use
+     * an opaque handler-less reference here so their own `.handler` cannot
+     * contribute a second call signature or expose internal fields in completion.
      */
-    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition | {
-        handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition;
+    parallel: (slots: Record<`@${string}`, Handler<any, any, TEnv> | ReactNode | StaticHandlerRef | {
+        handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
         use?: () => ParallelUseItem[];
     }>, use?: () => ParallelUseItem[]) => ParallelItem;
     /**

package/dist/types/vite/encryption-key.d.ts

@@ -0,0 +1,2 @@
+export declare function buildEncryptionKey(): string;
+export declare function defineEncryptionKeyExpr(): string;

package/dist/types/vite/plugins/expose-internal-ids.d.ts

@@ -1,6 +1,16 @@
 import type { Plugin } from "vite";
 export { exposeRouterId } from "./expose-ids/router-transform.js";
 export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
+/**
+ * Stub export-only loader modules before plugin-rsc reduces scan modules to
+ * imports. The regular post transform remains authoritative outside scan builds.
+ *
+ * Handles and location-state definitions are intentionally excluded: handle
+ * collect functions run in the browser, and location-state definitions are
+ * callable browser objects. Their dependencies must remain visible to non-RSC
+ * validation rather than being hidden behind an opaque scan stub.
+ */
+export declare function createLoaderScanStubPlugin(): Plugin;
 export declare function exposeInternalIds(options?: {
     forceBuild?: boolean;
 }): Plugin;

package/dist/types/vite/plugins/server-ref-hashing.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from "vite";
+/**
+ * Replace dev-style server-reference ids with their production hashes. The temp
+ * server renders Static/Prerender in a dev/serve Vite server, so plugin-rsc mints
+ * a dev-style id (e.g. "/src/urls/prerender.tsx"); rewriting only the id (group 2)
+ * leaves the hoisted function and its trailing encrypted .bind(...) untouched.
+ * Exported for testing; used by hashServerRefs. Returns null if nothing changed.
+ */
+export declare function transformServerRefs(code: string, projectRoot: string): string | null;
+/**
+ * Server-side analog of hashClientRefs. Runs in the build-discovery temp server
+ * (a dev/serve Vite server, where plugin-rsc mints dev-style ids), rewriting
+ * registerServerReference ids to production hashes AFTER plugin-rsc's
+ * rsc:use-server transform (enforce:"post"), so the Flight serializer bakes the
+ * production hash into the stored prerender/static payloads.
+ *
+ * Without this, a server-created action embedded in a prerendered/static Flight
+ * is stored with a dev-style id that the production hash-keyed server-references
+ * manifest cannot resolve -> "server reference not found" on a build-time-cache
+ * hit. Mirrors hashClientRefs, which already does exactly this for the client
+ * half of the same payload (which is why client refs in stored Flight are
+ * already production hashes while server refs were not).
+ */
+export declare function hashServerRefs(projectRoot: string): Plugin;

package/dist/types/vite/plugins/server-reference-pattern.d.ts

@@ -0,0 +1 @@
+export declare function registerServerReferenceRegex(): RegExp;

package/dist/types/vite/utils/shared-utils.d.ts

@@ -52,4 +52,16 @@ export declare function createVirtualEntriesPlugin(entries: {
  * asset collisions from @vitejs/plugin-rsc copying RSC-env assets to the client bundle.
  */
 export declare function onwarn(warning: Vite.Rollup.RollupLog, defaultHandler: (warning: Vite.Rollup.RollupLog) => void): void;
+/**
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
+ */
 export declare function getManualChunks(id: string): string | undefined;