@rangojs/router 0.4.3 → 0.5.1

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-store.d.ts

@@ -30,6 +30,8 @@ import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOpti
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
+    /** True when constructed without KV: the shell family no-ops (see ctor). */
+    readonly shellFamilyInert?: boolean;
     readonly defaults?: CacheDefaults;
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly namespace?;

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

@@ -164,6 +164,15 @@ export interface SegmentCacheStore<TEnv = unknown> {
      *   `stored` when acknowledged, or void for stores without acknowledgements.
      */
     putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /**
+     * Declares the shell family present-but-inert: getShell/putShell exist but
+     * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
+     * captures whose only write target is inert — the background render would be
+     * dead work that still occupies the per-isolate serialized capture queue
+     * (a promise-heavy route bakes for seconds per MISS with nothing stored).
+     * Absent/false means the family, when present, actually stores.
+     */
+    shellFamilyInert?: boolean;
     /**
      * Get a cached function result by key.
      * Returns the serialized value, optional handle data, and staleness flag.
@@ -221,8 +230,8 @@ export interface CacheItemResult {
 /**
  * A cached PPR (Partial Pre-rendering) shell entry.
  *
- * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
- * and React's postponed state — because the pair is version- and
+ * A DOCUMENT entry carries BOTH artifacts a resume needs — the rendered HTML
+ * prelude and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
  * change. The reactVersion and buildVersion fields are the read-time gates that
  * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
@@ -231,15 +240,28 @@ export interface CacheItemResult {
  * positions against one exact tree; resuming it against a different React or a
  * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
  * are committed — an unrecoverable broken serve).
+ *
+ * A `navigationOnly` entry stores NEITHER half: nothing ever serves its HTML
+ * (document serving skips navigationOnly entries at the read gate, and partial
+ * replay consumes only `snapshot`/`docKey`), so the prelude would ride every
+ * store write and read as dead weight at KV-value scale. The capture still runs
+ * the full fizz prerender — it is the completeness arbiter and sanity gate —
+ * but its output is dropped before putShell. hasIntactShellPayload is the
+ * document-half gate; navigationOnly entries never satisfy it.
  */
 export interface ShellCacheEntry {
-    /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
-    prelude: string;
+    /**
+     * Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing).
+     * Absent on `navigationOnly` entries (no document half is stored — see the
+     * interface doc); present on every document-servable entry.
+     */
+    prelude?: string;
     /**
      * JSON.stringify of React's postponed state, or null when the shell settled
-     * with no holes (the DATA variant — served without a fizz resume).
+     * with no holes (the DATA variant — served without a fizz resume). Absent
+     * exactly when `prelude` is (navigationOnly entries).
      */
-    postponed: string | null;
+    postponed?: string | null;
     /** React.version captured at prerender time; the read-time invalidation gate. */
     reactVersion: string;
     /**
@@ -322,6 +344,17 @@ export interface ShellCacheEntry {
     /** Capture-generation start time; tag invalidations at or after it win. */
     createdAt: number;
 }
+/**
+ * A shell entry whose document half is present — what the document HIT path
+ * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
+ * (rsc/shell-serve.ts) is the runtime gate AND the type narrowing to this
+ * shape; navigationOnly entries never pass it (their document half is not
+ * stored).
+ */
+export type DocumentShellCacheEntry = ShellCacheEntry & {
+    prelude: string;
+    postponed: string | null;
+};
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family

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/capture-queue.d.ts

@@ -1,5 +1,20 @@
 /** Bound queued/running capture closures retained by one isolate. */
 export declare const MAX_ADMITTED_CAPTURES: number;
+/** Point-in-time queue occupancy, for capture-scheduling telemetry. */
+export interface CaptureQueueDepths {
+    /** A capture is currently executing (never preempted). */
+    running: boolean;
+    /** Waiting document-priority captures (run before every navigation capture). */
+    document: number;
+    /** Waiting navigation-priority captures. */
+    navigation: number;
+}
+/**
+ * Snapshot the queue's waiting/running state. Wait-timed-out entries still
+ * sitting in the arrays (pruned lazily by takeNextCapture) are excluded — they
+ * will never run, so counting them would overstate the backlog.
+ */
+export declare function captureQueueDepths(): CaptureQueueDepths;
 /** The caller may drop this best-effort capture and retry on a later request. */
 export declare class CaptureQueueFullError extends Error {
     constructor();
@@ -24,10 +39,11 @@ export declare class CaptureQueueWaitTimeoutError extends Error {
     constructor(waitedMs: number);
 }
 /**
- * Run `task` after every previously enqueued capture has settled. Returns a
- * promise for THIS task's completion (rejections propagate to the caller —
- * the queue itself is insulated).
+ * Run `task` after the active capture and every higher/equal-priority capture
+ * ahead of it have settled. Returns a promise for THIS task's completion
+ * (rejections propagate to the caller — the queue itself is insulated).
  */
 export declare function enqueueSerializedCapture(task: () => Promise<void>, opts?: {
     maxQueueWaitMs?: number;
+    priority?: "document" | "navigation";
 }): Promise<void>;

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

@@ -24,7 +24,7 @@
  *   as the reference instant. No tombstones — the manifest is immutable; the
  *   markers say whether it is still current.
  */
-import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+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 {
@@ -49,7 +49,7 @@ declare global {
 /** Reset the memoized manifest (unit tests swap the global loader). */
 export declare function resetBuildShellManifestForTests(): void;
 export interface BuildShellHit {
-    entry: ShellCacheEntry;
+    entry: DocumentShellCacheEntry;
     /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
     stale: boolean;
 }

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

@@ -125,6 +125,10 @@ export interface ShellCaptureDebugEvent {
      * - skip-backoff: the key is inside its refused-capture backoff window and
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
+     * - skip-inert-store: the resolved store's shell family is missing or
+     *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
+     *   without a KV namespace); nothing could store the result, so the
+     *   background render was not scheduled at all
      * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
      *   behind other captures and was dropped unrun (no backoff — the route is
      *   not doomed, the isolate was busy; a later request re-probes). Carries
@@ -132,7 +136,7 @@ export interface ShellCaptureDebugEvent {
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "skip-queue-timeout" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "skip-inert-store" | "skip-queue-timeout" | "backoff";
     /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
     attempt?: number;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -163,6 +167,22 @@ export interface ShellCaptureDebugEvent {
     backoffRemainingMs?: number;
     /** Ms the capture waited in the serialized queue (skip-queue-timeout). */
     queueWaitMs?: number;
+    /** Queue priority class at enqueue: document outranks queued navigation. */
+    queuePriority?: "document" | "navigation";
+    /**
+     * Captures ahead at enqueue: the active one plus every waiting capture of
+     * same-or-higher priority. 0 = this capture starts immediately.
+     */
+    queueAhead?: number;
+    /**
+     * Ms the capture gate was HELD waiting for the slowest bake source — a
+     * top-level pushed handle promise or a bake-lane loader container — to
+     * settle, measured from capture start. Bake time is by-design shell latency
+     * (the hole doctrine: top-level promises bake), but it recurs on EVERY
+     * capture of the route and occupies the serialized queue; this field makes
+     * it attributable. Absent when nothing held the gate.
+     */
+    bakeWaitMs?: number;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -322,7 +342,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *

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

@@ -17,7 +17,7 @@
  */
 import { type EntryData } from "../server/context.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
-import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+import type { DocumentShellCacheEntry, ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
 /** Partial-navigation status header set only after captured PPR segments are consumed. */
@@ -106,18 +106,24 @@ export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): st
  */
 export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
 /**
- * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
- * whose prelude is not decodable base64 or whose postponed blob is not
- * parseable JSON would otherwise throw AFTER the 200 + full static prelude
- * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
- * parses in the tail) — the client gets a visually complete page that never
- * hydrates, re-served on every request until the entry ages out (no eviction
- * path exists; failure schedules no recapture by itself). Checking here turns
- * a corrupt entry (store-layer fault) into a plain MISS the recapture
- * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
- * prelude flush that dominates the path.
+ * DOCUMENT-half integrity gate and type narrowing, run BEFORE the HIT response
+ * commits: a stored entry whose prelude is not decodable base64 or whose
+ * postponed blob is not parseable JSON would otherwise throw AFTER the 200 +
+ * full static prelude flushed (`serveShellHit` decodes at stream construction,
+ * `resumeShellHTML` parses in the tail) — the client gets a visually complete
+ * page that never hydrates, re-served on every request until the entry ages
+ * out (no eviction path exists; failure schedules no recapture by itself).
+ * Checking here turns a corrupt entry (store-layer fault) into a plain MISS
+ * the recapture overwrites. Cost: one duplicate decode/parse per HIT, sub-ms
+ * against a prelude flush that dominates the path.
+ *
+ * navigationOnly entries store no document half (prelude/postponed absent) and
+ * therefore never pass. The partial-replay path skips this gate for them
+ * (replayableShellSnapshot) — snapshot fragment corruption is caught by the
+ * consumer-side Flight decoders instead (SegmentFragmentDecodeError → healing
+ * capture).
  */
-export declare function hasIntactShellPayload(entry: ShellCacheEntry): boolean;
+export declare function hasIntactShellPayload(entry: ShellCacheEntry): entry is DocumentShellCacheEntry;
 /** Decode a base64 prelude back into bytes for stream composition. */
 export declare function base64ToBytes(b64: string): Uint8Array;
 /** True when the store implements the shell entry family. */

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.backup/__internal.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Internal Types - Implementation Details
+ *
+ * @internal
+ * These types are for internal use only and should not be relied upon by consumers.
+ * They may change without notice between versions.
+ *
+ * If you find yourself needing these types, please open an issue to discuss
+ * adding them to the public API.
+ */
+/**
+ * @internal
+ * Internal representation of a resolved route segment.
+ * Used during route matching and rendering pipeline.
+ */
+export type { ResolvedSegment, SegmentMetadata } from "./types.js";
+/**
+ * @internal
+ * Internal match result from route resolution.
+ */
+export type { MatchResult, SlotState } from "./types.js";
+/**
+ * @internal
+ * Context for intercept route selection.
+ */
+export type { InterceptSelectorContext, InterceptSegmentsState, InterceptWhenFn, } from "./server/context.js";
+/**
+ * @internal
+ * RSC protocol payload structure.
+ */
+export type { RscPayload, ReactFormState } from "./rsc/types.js";
+/**
+ * @internal
+ * Internal navigation store interface.
+ */
+export type { NavigationStore, NavigationBridge, RscMetadata, ActionResult, InflightAction, NavigationState, TrackedActionState, ActionStateListener, SegmentCache, SegmentState, NavigationUpdate, } from "./browser/types.js";
+/**
+ * @internal
+ * Internal handle storage mechanism.
+ */
+export type { HandleStore, HandleData } from "./server/handle-store.js";
+/**
+ * @internal
+ * Segment handle data in cache.
+ */
+export type { SegmentHandleData } from "./cache/types.js";
+/**
+ * @internal
+ * Internal cache entry data structure.
+ */
+export type { CachedEntryData, CacheGetResult, SerializedSegmentData, CacheDefaults, } from "./cache/types.js";
+/**
+ * @internal
+ * Router context for AsyncLocalStorage.
+ */
+export type { RouterContext, RevalidationContext, InterceptResult, } from "./router/router-context.js";
+/**
+ * @internal
+ * Route match context during pipeline processing.
+ */
+export type { MatchContext, MatchPipelineState, } from "./router/match-context.js";
+/**
+ * @internal
+ * Pattern matching result.
+ */
+export type { RouteMatchResult } from "./router/pattern-matching.js";
+/**
+ * @internal
+ * Entry data during route traversal.
+ */
+export type { EntryData, InterceptEntry, MetricsStore, PerformanceMetric, EntryCacheConfig, EntryPropCommon, EntryPropDatas, LoaderEntry, EntryPropSegments, } from "./server/context.js";
+/**
+ * @internal
+ * Internal handler context with additional props for router internals.
+ * Includes `_currentSegmentId` and `_responseType`.
+ */
+export type { InternalHandlerContext } from "./types.js";
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type { RequestStartEvent, RequestEndEvent, RequestErrorEvent, RequestTimeoutEvent, LoaderStartEvent, LoaderEndEvent, LoaderErrorEvent, HandlerErrorEvent, CacheDecisionEvent, RevalidationDecisionEvent, } from "./router/telemetry.js";
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export { enableMatchDebug, getMatchDebugStats, } from "./router/pattern-matching.js";
+/**
+ * @internal
+ * Debug utilities for manifest inspection and comparison.
+ */
+export { serializeManifest, compareManifests, formatManifestDiff, type SerializedEntry, type SerializedManifest, } from "./debug.js";

package/dist/types.backup/bin/rango.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.backup/browser/action-coordinator.d.ts

@@ -0,0 +1,57 @@
+import type { ActionEntry } from "./event-controller.js";
+/**
+ * Post-reconciliation action outcome (discriminated union). Error and
+ * full-update-unsupported cases are handled inline in the bridge before
+ * reconciliation; this only covers successfully-reconciled partial responses.
+ */
+type ActionScenario = {
+    type: "navigated-away";
+    historyKeyChanged: boolean;
+    onInterceptRoute: boolean;
+} | {
+    type: "hmr-missing";
+} | {
+    type: "consolidation-needed";
+    segmentIds: string[];
+} | {
+    type: "concurrent-skip";
+    otherFetchingCount: number;
+} | {
+    type: "normal";
+};
+/**
+ * Plain data inputs for classifying a post-reconciliation action outcome.
+ * No browser objects or controller references — all values are snapshots.
+ */
+export interface ActionOutcomeInput {
+    /** This action's unique instance ID */
+    handleId: string;
+    /** All in-flight action entries (snapshot from event controller) */
+    inflightActions: Map<string, ActionEntry>;
+    /** Whether any concurrent actions occurred (controller-level shared flag) */
+    hadAnyConcurrentActions: boolean;
+    /** Segments revalidated by concurrent actions (from tracking set) */
+    revalidatedSegments: Set<string>;
+    /** window.location.pathname captured at action start */
+    actionStartPathname: string;
+    /** window.location.pathname at classification time */
+    currentPathname: string;
+    /** window.history.state?.key captured at action start */
+    actionStartLocationKey: string | undefined;
+    /** window.history.state?.key at classification time */
+    currentLocationKey: string | undefined;
+    /** Number of segments after reconciliation */
+    reconciledSegmentCount: number;
+    /** Number of matched segment IDs from server */
+    matchedCount: number;
+    /** Current intercept source URL (null when not on intercept route) */
+    currentInterceptSource: string | null;
+}
+/**
+ * Classify a post-reconciliation action outcome. Ordered priority chain: each
+ * case assumes the earlier ones are false (e.g. concurrent-skip only applies on
+ * the still-current route, consolidation only once no action is still fetching).
+ * The bridge calls this to decide whether to render, skip, consolidate, or refetch.
+ */
+export declare function classifyActionOutcome(input: ActionOutcomeInput): ActionScenario;
+export {};

package/dist/types.backup/browser/action-fence.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Action fence: a refcounted flag that is raised while a server action is in
+ * flight and lowered when it resolves.
+ *
+ * It replaces the eager cache clear the action bridge used to do at action
+ * start. While the fence is up, the decision of whether the action invalidated
+ * anything is deferred to the response:
+ *
+ * - prefetch consumption is suspended (a queued prefetch result is not served),
+ * - a genuine navigation during the flight fetches with `cache: "no-store"` so
+ *   it cannot be served stale bytes from the browser's Vary-keyed HTTP cache,
+ * - popstate reads are treated as stale-while-revalidate.
+ *
+ * Nothing is wiped, rotated, or broadcast while the fence is up — that is what
+ * keeps a sibling tab from seeing a pre-commit signal. Refcounted so concurrent
+ * actions compose: each action raises and lowers its own reference, and the
+ * fence is down only when the count reaches zero.
+ *
+ * The refcount is a single module-level counter, not keyed by routerId.
+ * Consumers (navigation-client.ts, prefetch/fetch.ts, navigation-bridge.ts)
+ * read it unscoped, so an action in one router would suppress another router's
+ * navigation/prefetch caches. This is correct only because two routers cannot
+ * coexist in one live document: an SPA navigation crossing a host-router
+ * boundary forces a full document reload (src/router/request-classification.ts
+ * app-switch terminal), so there is always exactly one live router per
+ * document. A future multi-router-in-one-document feature must not silently
+ * inherit this global, cross-router cache suppression.
+ */
+export declare function enterActionFence(): void;
+export declare function exitActionFence(): void;
+export declare function isActionFenceActive(): boolean;
+/** Test-only: reset the refcount between cases. */
+export declare function __resetActionFence(): void;

package/dist/types.backup/browser/app-shell.d.ts

@@ -0,0 +1,34 @@
+import type { ComponentType, ReactNode } from "react";
+/**
+ * App-shell metadata: the per-router fields describing the "envelope" around
+ * the current app's segment tree — the rootLayout (Document), basename,
+ * version, and router identity. Set once from the initial RSC payload and read
+ * through the AppShellRef when rendering segments.
+ *
+ * This is a per-document value. A navigation that crosses a host-router app
+ * boundary is a full document load (the server returns X-RSC-Reload for it;
+ * see request-classification.ts, mode "app-switch"), so the target app's shell
+ * — along with everything else document-level (theme, warmup, prefetch-TTL) —
+ * is established fresh by the target app's own load. The shell is never swapped
+ * in place within a session.
+ */
+export interface AppShell {
+    /** Router identity. Used to namespace per-app client state (e.g. the
+     *  rango-state localStorage key) so sibling apps on the same origin
+     *  cannot observe each other's cache invalidations. */
+    routerId?: string;
+    rootLayout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    basename?: string;
+    version?: string;
+}
+/**
+ * Container for the active app shell. Read-through via `get()` so closures
+ * (e.g. the segment renderer) capture the ref and read the shell at call time
+ * rather than closing over a stale snapshot.
+ */
+export interface AppShellRef {
+    get(): AppShell;
+}
+export declare function createAppShellRef(initial: AppShell): AppShellRef;

package/dist/types.backup/browser/app-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+export declare function getAppVersion(): string | undefined;
+export declare function setAppVersion(version: string | undefined): void;