@rangojs/router 0.2.0 → 0.4.0

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Router-wide default Link prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop reads the value at render time.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
+/** Current default strategy for Links without an explicit `prefetch` prop. */
+export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;

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

@@ -1,3 +1,2 @@
 export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
 export { abortAllPrefetches, cancelAllPrefetches, setPrefetchConcurrency, } from "./queue.js";
-export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

package/dist/types/browser/react/Link.d.ts

@@ -8,15 +8,8 @@ import { type LocationStateEntry } from "./location-state.js";
  */
 export type StateOrGetter<T = unknown> = T | (() => T);
 export type LinkState = LocationStateEntry[] | StateOrGetter<Record<string, unknown>>;
-/**
- * Prefetch strategy for the Link component
- * - "hover": Prefetch on mouse enter (direct, no queue)
- * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
- * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
- * - "adaptive": Hover on pointer devices, viewport on touch devices
- * - "none": No prefetching (default)
- */
-export type PrefetchStrategy = "hover" | "viewport" | "render" | "adaptive" | "none";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+export type { PrefetchStrategy } from "../../router/prefetch-default.js";
 /**
  * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
  * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
@@ -56,8 +49,12 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      */
     revalidate?: boolean;
     /**
-     * Prefetch strategy for the link destination
-     * @default "none"
+     * Prefetch strategy for the link destination. When omitted, falls back to
+     * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
+     * development, `"viewport"` in production). An explicit value always wins
+     * over the router default, including `"none"` to opt a single Link out.
+     *
+     * @default the router's environment-aware `defaultPrefetch`
      */
     prefetch?: PrefetchStrategy;
     /**

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

@@ -77,6 +77,11 @@ export interface RscMetadata {
      * Sent on initial render so the browser can configure its prefetch queue.
      */
     prefetchConcurrency?: number;
+    /**
+     * Router-wide default prefetch strategy for Links without a `prefetch` prop.
+     * Sent on initial render; applied once at init (default-strategy.ts).
+     */
+    defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
     /**
      * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
      * reads it verbatim and binds the rango state cookie to it; composition

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

@@ -265,6 +265,12 @@ export interface ShellCacheEntry {
      * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
      */
     snapshot?: ShellSnapshotRecord[];
+    /**
+     * The entry was captured from a partial request only to produce an eligible
+     * segment snapshot. Document serving must treat its HTML prelude as a miss;
+     * the partial request's headers and middleware state are not document state.
+     */
+    navigationOnly?: true;
     /**
      * True when the capture's HANDLER layer declared per-request liveness: a
      * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the

package/dist/types/router/prefetch-default.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve the router-wide default Link prefetch strategy once, at router init.
+ * The resolved value ships to the client in payload metadata; the browser
+ * entry applies it via `setDefaultPrefetchStrategy` (browser/prefetch/
+ * default-strategy.ts) and every `<Link>` without an explicit `prefetch` prop
+ * falls back to it.
+ *
+ * The type lives HERE (not in browser/react/Link.tsx) because both seats need
+ * it: this server-side resolver and the client Link/default-strategy modules.
+ * Link.tsx re-exports it so the public `PrefetchStrategy` export path is
+ * unchanged.
+ *
+ * Policy note: automatic prefetch stays quiet in development, matching the
+ * production-only default used by Next.js. Explicit router and per-Link
+ * strategies still work in every mode. Invalid untyped inputs fall back to the
+ * current environment's default.
+ */
+/**
+ * Prefetch strategy for the Link component
+ * - "hover": Prefetch on mouse enter (direct, no queue)
+ * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
+ * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
+ * - "none": No prefetching
+ */
+export type PrefetchStrategy = "hover" | "viewport" | "render" | "adaptive" | "none";
+export declare const DEFAULT_PREFETCH_STRATEGY: PrefetchStrategy;
+export declare function resolveDefaultPrefetch(raw: PrefetchStrategy | undefined, nodeEnv?: string | undefined): PrefetchStrategy;

package/dist/types/router/router-interfaces.d.ts

@@ -249,6 +249,13 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * prefetchConcurrency.
      */
     readonly prefetchConcurrency: number;
+    /**
+     * Router-wide default Link prefetch strategy for Links without an explicit
+     * `prefetch` prop. Shipped to the client in payload metadata. Derived from
+     * the `defaultPrefetch` option (default "none" in development and
+     * "viewport" in production).
+     */
+    readonly defaultPrefetch: import("./prefetch-default.js").PrefetchStrategy;
     /**
      * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
      * router init and shipped to the client in payload metadata. The server-side

package/dist/types/router/router-options.d.ts

@@ -7,6 +7,7 @@ import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { PrefetchStrategy } from "./prefetch-default.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -495,6 +496,35 @@ export interface RangoOptions<TEnv = any> {
      * @default 2
      */
     prefetchConcurrency?: number;
+    /**
+     * Default prefetch strategy for every `<Link>` that does not set its own
+     * `prefetch` prop. A per-Link `prefetch` prop always wins, in both
+     * directions (a Link can opt out of an aggressive default with
+     * `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
+     *
+     * - `"viewport"` (production default): prefetch when the link enters the viewport —
+     *   idle-gated and queued (see `prefetchConcurrency`), so prefetches never
+     *   compete with hydration or an active navigation.
+     * - `"hover"`: prefetch on mouse enter only. Much lighter on the server —
+     *   only links the pointer approaches are fetched — at the cost of the
+     *   ~100-300ms head start viewport prefetch gives.
+     * - `"adaptive"`: `"hover"` on pointer devices, `"viewport"` on touch
+     *   devices (no hover to wait for).
+     * - `"render"`: prefetch on mount regardless of visibility.
+     * - `"none"`: manual mode — nothing prefetches unless a Link opts in.
+     *
+     * Automatic prefetch defaults to `"none"` in development and `"viewport"`
+     * in production. With the production default, every visible Link triggers an
+     * RSC render (loaders included) on the server. Routes served from cache/PPR
+     * absorb this cheaply; per-user dynamic routes pay full price per viewport
+     * entry. Set `"hover"`, `"adaptive"`, or `"none"` when that cost matters.
+     *
+     * To disable the prefetch subsystem entirely (including per-Link opt-ins
+     * and `useRouter().prefetch()`), set `prefetchCacheTTL: false` instead.
+     *
+     * @default "none" in development; "viewport" in production
+     */
+    defaultPrefetch?: PrefetchStrategy;
     /**
      * Prefix for the rango state cookie name. The resolved name is
      * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

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

@@ -1,3 +1,9 @@
+/** Bound queued/running capture closures retained by one isolate. */
+export declare const MAX_ADMITTED_CAPTURES: number;
+/** The caller may drop this best-effort capture and retry on a later request. */
+export declare class CaptureQueueFullError extends Error {
+    constructor();
+}
 /**
  * Run `task` after every previously enqueued capture has settled. Returns a
  * promise for THIS task's completion (rejections propagate to the caller —

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

@@ -124,10 +124,11 @@ export interface ShellCaptureDebugEvent {
      *   the key (stampede guard) and scheduled nothing
      * - 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
      * - 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" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "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). */
@@ -148,6 +149,8 @@ export interface ShellCaptureDebugEvent {
     snapshotBytes?: number;
     /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
     snapshotSkipped?: boolean;
+    /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
+    untaggedBake?: true;
     /** Outcome reported by a store that supports shell-write acknowledgements. */
     storeWrite?: "stored" | "invalidated";
     /** Consecutive failure count in the key's backoff entry, when one exists. */
@@ -280,6 +283,8 @@ export interface ShellCaptureDescriptor {
      * {@link ShellCaptureDebugEvent} per attempt/skip.
      */
     debugSink?: (event: ShellCaptureDebugEvent) => void;
+    /** Store the snapshot for navigation replay, never the captured HTML prelude. */
+    navigationOnly?: true;
 }
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
@@ -288,11 +293,11 @@ export interface ShellCaptureDescriptor {
  * error is routed through reportCacheError — capture is best-effort; a failure just
  * means the next request recaptures.
  *
- * Eligibility (nonce/allReady/partial/status/strategy) is decided by the caller
- * (rsc-rendering.ts maybeScheduleShellCapture); this function only owns the
- * stampede guard and the background dispatch.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller. An SSR
+ * module loader may be passed for cold partial requests; it runs only after the
+ * capture enters the guarded background queue, never on response latency.
  */
-export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor): void;
+export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), descriptor: ShellCaptureDescriptor): void;
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -310,7 +315,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" | "storeWrite">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -351,7 +356,10 @@ export interface CaptureContextDerivation {
  * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
  * as `_cacheStore` so the recording/snapshot machinery arms identically.
  */
-export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">): CaptureContextDerivation;
+export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">, identity?: {
+    request: Request;
+    url: URL;
+}): CaptureContextDerivation;
 /**
  * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
  * captureShellHTML, and store the result. Returns the attempt outcome (the caller

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

@@ -53,9 +53,10 @@ export interface ResolvedPprConfig {
     captureTimeout?: number;
 }
 /**
- * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
- * through; anything else (including 0/negative/NaN/Infinity/non-number)
- * resolves to undefined, which means "use the capture default" downstream.
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
  * Mirrors the prefetch-limit option policy: invalid values silently fall back
  * to the default rather than throwing at request time. Also the boundary
  * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),

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

@@ -49,6 +49,8 @@ export interface RscPayload {
         prefetchCacheSize?: number;
         /** Max concurrent speculative prefetch requests on the client */
         prefetchConcurrency?: number;
+        /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+        defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
         /** Server-resolved rango state cookie name; the client reads it verbatim. */
         stateCookieName?: string;
         /** Theme configuration for FOUC prevention */

package/dist/types/testing/e2e/index.d.ts

@@ -1,11 +1,11 @@
 import type { Expect, TestType } from "@playwright/test";
 import { createUseFixture, type Fixture, type FixtureOptions } from "./fixture.js";
-import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
+import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isPrefetchRequest, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
 export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
-export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
+export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, isPrefetchRequest, blockPrefetch, unblockPrefetch, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {
     useFixture: (options: FixtureOptions) => Fixture;

package/dist/types/testing/e2e/page-helpers.d.ts

@@ -43,6 +43,30 @@ export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
     elapsed: number;
     result: T;
 }>;
+/**
+ * True when the request is a speculative prefetch (Link viewport/hover/render
+ * strategies or `useRouter().prefetch()`). Every prefetch fetch carries the
+ * `X-Rango-Prefetch` header. Links prefetch by default in production unless
+ * the router opts out, so tests that track `_rsc_partial` requests to pin
+ * NAVIGATION behavior must skip these — a request-count or first-request
+ * assertion otherwise races background prefetch traffic.
+ */
+export declare function isPrefetchRequest(req: {
+    headers: () => Record<string, string>;
+}): boolean;
+/**
+ * Abort every speculative prefetch request on this page. Install BEFORE
+ * `page.goto` so no prefetch can complete first. For tests whose semantics
+ * need a virgin prefetch cache: a click on a Link whose target was already
+ * prefetched ADOPTS the warmed entry and issues no navigation fetch at all —
+ * a `page.route` override, a request waiter, or a Set-Cookie assertion aimed
+ * at the navigation request then sees nothing (or sees the prefetch's side
+ * effects instead). Aborted prefetches are benign by design (evicted, never
+ * adopted, no page error), so the click's real fetch is guaranteed live.
+ */
+export declare function blockPrefetch(page: Page): Promise<void>;
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export declare function unblockPrefetch(page: Page): Promise<void>;
 export interface PageHelpers {
     /** Assert that no full page reload occurred between scope entry and exit. */
     expectNoReload: (page: Page) => AsyncDisposable;

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;

package/dist/types.backup/browser/connection-warmup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Connection warmup: keep TLS alive after idle periods.
+ *
+ * After IDLE_TIMEOUT of no user interaction the connection is marked "cold".
+ * On the next pointer/touch interaction or a visibility change, a HEAD request
+ * warms the TLS connection before the user actually clicks a link.
+ *
+ * Extracted from NavigationProvider so the idle/cold/warmup state machine is
+ * unit-testable with an injected environment (document, fetch, timers).
+ *
+ * Ordering bug this guards against: the warmup listeners (mousemove/touchstart)
+ * share events with the idle-reset listeners, and the idle-reset listener is
+ * registered first, so it clears the live "cold" flag before the warmup
+ * listener reads it on the same event. A separate coldLatch — set when the
+ * connection goes cold and cleared only when warmup fires or listeners detach,
+ * never by the idle reset — lets the warmup decision see the pre-reset cold
+ * state regardless of listener ordering.
+ */
+type TimerHandle = ReturnType<typeof setTimeout>;
+export interface WarmupEnv {
+    doc: Pick<Document, "addEventListener" | "removeEventListener" | "visibilityState">;
+    fetch: typeof fetch;
+    setTimeout: (fn: () => void, ms: number) => TimerHandle;
+    clearTimeout: (handle: TimerHandle | undefined) => void;
+}
+/**
+ * Start the connection-warmup state machine. Returns a cleanup function that
+ * cancels timers and removes all listeners.
+ */
+export declare function startConnectionWarmup(env?: WarmupEnv): () => void;
+export {};