@rangojs/router 0.5.0 → 0.5.1

package/dist/types.backup/router/router-registry.d.ts

@@ -0,0 +1,15 @@
+import type { RangoInternal } from "./router-interfaces.js";
+/**
+ * Brand marker for identifying router instances at build time.
+ * Used by the Vite plugin to auto-discover routers from module exports.
+ */
+export declare const RSC_ROUTER_BRAND: "__rsc_router__";
+/**
+ * Global registry of all router instances created via createRouter().
+ * Each router is keyed by its id (auto-generated or user-provided).
+ * Used by the Vite plugin at build time to discover routers and extract
+ * manifests, prefix trees, and pre-render candidates.
+ */
+export declare const RouterRegistry: Map<string, RangoInternal<any, any>>;
+export declare let routerAutoId: number;
+export declare function nextRouterAutoId(): number;

package/dist/types.backup/router/segment-resolution/fresh.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Fresh Path Segment Resolution
+ *
+ * Functions for resolving segments during a full (non-revalidation) request.
+ * Handles loaders, layouts, routes, parallels, orphan layouts, and error boundaries.
+ */
+import { type EntryData } from "../../server/context";
+import type { HandlerContext, ResolvedSegment } from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+/**
+ * Resolve loaders for an entry and emit segments.
+ * Loaders are run lazily via ctx.use() and memoized for parallel execution.
+ */
+export declare function resolveLoaders<TEnv>(entry: EntryData, ctx: HandlerContext<any, TEnv>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, shortCodeOverride?: string): Promise<ResolvedSegment[]>;
+/**
+ * Options for segment resolution.
+ */
+export interface ResolveSegmentOptions {
+    /** When true, skip resolveLoaders() calls (used for pre-rendering) */
+    skipLoaders?: boolean;
+    /**
+     * When true, a thrown render error is re-thrown instead of being converted
+     * into an error-boundary segment. Set only by the pre-render path so a
+     * build-time render failure (and a `throw new Skip()` inside a render fn)
+     * surfaces to the build instead of being silently baked into a frozen error
+     * page served as a 200 (issue #587). The live request path leaves this unset,
+     * so error boundaries keep catching at request time.
+     */
+    throwOnError?: boolean;
+}
+/**
+ * Resolve segments from EntryData.
+ * Executes middlewares, loaders, parallels, and handlers in correct order.
+ * Returns array: [main segment, ...orphan layout segments]
+ */
+export declare function resolveSegment<TEnv>(entry: EntryData, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, deps: SegmentResolutionDeps<TEnv>, isRouteEntry?: boolean, options?: ResolveSegmentOptions): Promise<ResolvedSegment[]>;
+/**
+ * Resolve orphan layout with its middlewares, loaders, and parallels.
+ */
+export declare function resolveOrphanLayout<TEnv>(orphan: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, options?: ResolveSegmentOptions, routeKey?: string, 
+/** Parent route entry — its loaders are inherited by the layout so
+ *  parallel slots inside this layout can access them via useLoader(). */
+parentRouteEntry?: EntryData): Promise<ResolvedSegment[]>;
+/**
+ * Resolve parallel EntryData with its loaders and slot handlers.
+ */
+export declare function resolveParallelEntry<TEnv>(parallelEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, parentShortCode: string, deps: SegmentResolutionDeps<TEnv>, options?: ResolveSegmentOptions, routeKey?: string, slotNames?: `@${string}`[], includeLoaders?: boolean): Promise<ResolvedSegment[]>;
+/**
+ * Resolve all segments for a route (used for single-cache-per-request pattern).
+ */
+export declare function resolveAllSegments<TEnv>(entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, deps: SegmentResolutionDeps<TEnv>, options?: ResolveSegmentOptions): Promise<ResolvedSegment[]>;
+/**
+ * Resolve only loader segments for all entries (used when serving cached non-loader segments).
+ */
+export declare function resolveLoadersOnly<TEnv>(entries: EntryData[], context: HandlerContext<any, TEnv>, deps: SegmentResolutionDeps<TEnv>): Promise<ResolvedSegment[]>;

package/dist/types.backup/router/segment-resolution/helpers.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared Helpers for Segment Resolution
+ *
+ * Common utilities used by both fresh and revalidation resolution paths:
+ * - Handler result processing (Response vs ReactNode)
+ * - Static handler interception (build-time pre-rendered components)
+ * - Layout handler resolution with static fallback
+ * - Error boundary segment creation
+ */
+import { type ReactNode } from "react";
+import type { EntryData } from "../../server/context";
+import type { ResolvedSegment, HandlerContext } from "../../types";
+import type { SegmentResolutionDeps } from "../types.js";
+import type { TelemetrySink } from "../telemetry.js";
+/** The errorContext shape wrapLoaderPromise expects as its 5th argument. */
+type LoaderErrorContext<TEnv> = NonNullable<Parameters<SegmentResolutionDeps<TEnv>["wrapLoaderPromise"]>[4]>;
+/**
+ * Build the errorContext passed to wrapLoaderPromise so a throwing DSL loader
+ * fires createRouter({ onError }) (phase "loader") and emits the loader.error
+ * telemetry event. wrapLoaderPromise only wires the onError/telemetry path when
+ * this 5th argument is present; every real call site previously omitted it, so
+ * loaders were the one phase whose failures were silently dropped (handlers,
+ * actions, routing, rendering, and fetchable loaders all reported correctly).
+ *
+ * The fields come off the handler context, which already carries the request,
+ * url, params, env, and (on the internal shape) the matched route name.
+ */
+export declare function buildLoaderErrorContext<TEnv>(ctx: HandlerContext<any, TEnv>): LoaderErrorContext<TEnv>;
+/**
+ * Handle Response returns from handlers.
+ * When a handler returns a Response (e.g., redirect), throw it to trigger
+ * the short-circuit mechanism. Otherwise return the ReactNode.
+ */
+export declare function handleHandlerResult(result: ReactNode | Response | Promise<ReactNode | Response>): ReactNode;
+/**
+ * Dev-only: warn when a handler on a route that declares loading() resolves or
+ * rejects with a Response (e.g. redirect()).
+ *
+ * On a non-loading route a returned/thrown Response short-circuits to an HTTP
+ * redirect. But when the route declares loading(), the handler result is
+ * streamed (not awaited at the resolution boundary), so the Response surfaces
+ * only during RSC serialization and is rendered into the stream instead of
+ * becoming a 302/308 — a silent failure mode. Issue redirects from middleware,
+ * a loader, or a synchronous handler return instead. Compiled out in production.
+ */
+export declare function warnOnStreamedResponse(result: Promise<unknown>, entryId: string): void;
+/**
+ * Try to resolve a component from the build-time static store.
+ * Returns undefined synchronously when the entry is not a static prerender,
+ * avoiding unnecessary promise wrapping on the hot path.
+ */
+export declare function tryStaticHandler(entry: EntryData, segmentId: string): Promise<ReactNode | undefined> | undefined;
+/**
+ * Try to resolve a parallel slot component from the build-time static store.
+ * Returns undefined synchronously when no static handler ID exists for the slot.
+ */
+export declare function tryStaticSlot(parallelEntry: EntryData, slot: string, segmentId: string): Promise<ReactNode | undefined> | undefined;
+/**
+ * Resolve a layout or cache entry's handler component.
+ * Checks build-time static store first, then invokes the handler.
+ */
+export declare function resolveLayoutComponent<TEnv>(entry: EntryData, context: HandlerContext<any, TEnv>): Promise<ReactNode>;
+/**
+ * Context for error reporting in segment resolution.
+ * When provided, callOnError is invoked with this context.
+ */
+export interface ErrorReportContext {
+    request?: Request;
+    url?: URL;
+    routeKey?: string;
+    env?: any;
+    isPartial?: boolean;
+    requestStartTime?: number;
+    telemetry?: TelemetrySink;
+}
+/**
+ * Handle a caught error during segment resolution by creating an
+ * error or not-found segment with the nearest boundary.
+ *
+ * Called by resolveWithErrorBoundary to produce error/notFound segments.
+ */
+export declare function catchSegmentError<TEnv>(error: unknown, entry: EntryData, params: Record<string, string>, deps: SegmentResolutionDeps<TEnv>, report?: ErrorReportContext, pathname?: string): ResolvedSegment;
+/**
+ * Generic error boundary wrapper for segment resolution.
+ * Catches non-Response errors and produces an error/notFound segment
+ * via catchSegmentError. Response throws (e.g. redirects) are re-thrown.
+ *
+ * The caller provides a `wrapError` callback to shape the error segment
+ * into the expected return type (e.g. ResolvedSegment[] for the fresh
+ * path, or SegmentRevalidationResult for the revalidation path).
+ */
+export declare function resolveWithErrorBoundary<TEnv, TResult>(entry: EntryData, params: Record<string, string>, resolveFn: () => Promise<TResult>, wrapError: (segment: ResolvedSegment) => TResult, deps: SegmentResolutionDeps<TEnv>, report?: ErrorReportContext, pathname?: string, throwOnError?: boolean): Promise<TResult>;
+export {};

package/dist/types.backup/router/segment-resolution/loader-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Loader-Level Caching
+ *
+ * When a LoaderEntry has a cache config (set via loader(Fn, () => [cache({...})])),
+ * this module wraps the loader execution with cache lookup/store using the
+ * getItem()/setItem() methods on SegmentCacheStore.
+ *
+ * Cache key resolution (3-tier, matching CacheScope.resolveKey):
+ *   1. options.key(requestCtx) — full override
+ *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
+ *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
+ *
+ * Values are serialized via RSC Flight (serializeResult/deserializeResult),
+ * supporting ReactNode, Promises, null, and all RSC-serializable types.
+ *
+ * On hit: returns cached data directly, skips loader execution.
+ * On stale hit (SWR): returns stale data, schedules background revalidation.
+ * On miss: executes loader, schedules non-blocking cache write.
+ */
+import type { LoaderEntry } from "../../server/context.js";
+import type { HandlerContext } from "../../types.js";
+/**
+ * Resolve loader data with optional caching.
+ *
+ * When the LoaderEntry has no cache config, delegates directly to ctx.use(loader).
+ * When cached, checks store first and stores on miss via waitUntil.
+ *
+ * Loader metering is NOT done here — it lives at the ctx.use execution funnel
+ * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
+ * so it emits no loader phase (the loader did not execute; the hit is only a
+ * LoaderCache debug log).
+ */
+export declare function resolveLoaderData<TEnv>(loaderEntry: LoaderEntry, ctx: HandlerContext<any, TEnv>, pathname: string, bakeSegmentKey?: string | null): Promise<any>;

package/dist/types.backup/router/segment-resolution/loader-mask.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PPR shell-capture loader masking.
+ *
+ * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
+ * route loaders are the "live lane": they must NOT execute — no side effects, no
+ * cost, no cache round-trips. Instead every loader segment's value slot receives
+ * a never-resolving promise, so the loader-consuming Suspense subtree stays
+ * pending and React's static `prerender` marks it as a postponed hole. The frozen
+ * shell (prelude) captures only the fallback; the resumed serve pass runs the
+ * loaders fresh through the unchanged execution path and streams their output
+ * into the holes.
+ *
+ * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * the derived request context of the background capture task (shell-capture.ts) —
+ * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
+ * capture is wanted" and must not change behavior. This module is the single home
+ * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ */
+import { type RequestContext } from "../../server/request-context.js";
+/**
+ * True when the current render is the active PPR shell capture and route loaders
+ * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * request context (the capture task re-establishes its derived context via
+ * runWithRequestContext), so it is accurate at the loader resolution sites, which
+ * run synchronously inside the pipeline's context frame.
+ */
+export declare function isShellCaptureActive(reqCtx?: RequestContext<any> | undefined): boolean;
+export { createMaskedLoaderPromise } from "./mask-nested.js";
+/**
+ * Lane decision for an entry's loaders under PPR (the loading() value decides;
+ * docs/design/loader-container-bake.md):
+ *
+ * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
+ *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
+ * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
+ *   false })` under the SSR manifest) — the BAKE lane: the loader executes
+ *   during capture, its settled container bakes, nested pending promises hole
+ *   at the consumer's own Suspense. Returns false.
+ *
+ * Mirrors segment-system's isRenderableLoading so the mask decision and the
+ * tree's boundary placement can never disagree.
+ */
+export declare function entryLoadingMasksLoaders(loading: unknown): boolean;

package/dist/types.backup/router/segment-resolution/loader-snapshot.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Loader-family capture snapshot: elide + overlay for bake-lane loader
+ * containers (docs/design/loader-container-bake.md).
+ *
+ * A loader on an entry with NO renderable loading() executes during shell
+ * capture; its settled container bakes into the prelude while every promise
+ * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * payload byte-identical to that frozen prelude, the capture pins the container
+ * in the shell snapshot:
+ *
+ *   - elide:   deep-walk the settled container; a PENDING nested promise is a
+ *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
+ *              loader-cache masks every nested thenable at capture
+ *              ({@link maskNestedContainerThenables}), nested promises are
+ *              ALWAYS pending here for new captures. The SETTLED-marker branch
+ *              below is legacy: it fires only if a settled thenable reaches
+ *              elide anyway, and the overlay keeps decoding SETTLED markers
+ *              from pre-mask snapshots. The result is promise-free and
+ *              Flight-serializable.
+ *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
+ *              the live nested promises), then the recorded container is laid
+ *              over it: recorded paths win (they are what the prelude froze),
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — and fresh-only paths pass through
+ *              (they cannot contradict prelude bytes that never rendered them).
+ */
+export { maskNestedContainerThenables } from "./mask-nested.js";
+/**
+ * Marker object standing in for a pending nested promise in a recorded loader
+ * container. Shape-checked (not identity-checked) because the record round-trips
+ * through Flight serialization and a JSON-embedding store envelope.
+ */
+export declare const LOADER_HOLE_KEY: "$rangoLoaderHole";
+export interface LoaderHoleMarker {
+    [LOADER_HOLE_KEY]: 1;
+}
+export declare function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker;
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export declare const LOADER_SETTLED_KEY: "$rangoLoaderSettled";
+export interface LoaderSettledMarker {
+    [LOADER_SETTLED_KEY]: 1;
+    value: unknown;
+    /**
+     * Present when the pinned subtree contains hole markers. Computed once at
+     * capture (elide already visits every node) so the per-HIT overlay never
+     * rescans the pinned structure to pick its rehydration path.
+     */
+    holes?: 1;
+}
+export declare function isLoaderSettledMarker(value: unknown): value is LoaderSettledMarker;
+export type ElideResult = {
+    state: "ok";
+    value: unknown;
+    hasHole: boolean;
+} | {
+    state: "rejected";
+};
+/**
+ * Deep-elide a settled bake-lane container for recording. Settled nested
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); pending ones become hole markers; a REJECTED
+ * nested promise poisons the record (error UI must never bake into a shared
+ * shell) — the caller refuses the capture. Only plain objects/arrays are
+ * traversed; anything else (Date, Map, class instance) is a pinned leaf.
+ * Cycles are cut as pinned references (best effort — Flight rejects true
+ * cycles later regardless).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
+ */
+export declare function elideLoaderContainer(value: unknown, seen?: Set<object>): Promise<ElideResult>;
+/**
+ * Overlay a recorded (elided) container onto the fresh run's container for a
+ * shell HIT. Recorded wins per path; hole markers take the fresh value (the
+ * live nested promise); fresh-only object keys pass through. Where the shapes
+ * disagree structurally, recorded wins wholesale — it is what the prelude
+ * froze, and parity beats freshness inside the shell.
+ */
+export declare function overlayLoaderContainer(fresh: unknown, recorded: unknown): unknown;

package/dist/types.backup/router/segment-resolution/mask-nested.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Capture-side nested-thenable masking — the mechanism behind "nested-promise
+ * shape is the liveness declaration" for BOTH bake-lane loader containers
+ * (loader-cache.ts) and pushed handle containers (request-context.ts
+ * createUseFunction).
+ *
+ * Deliberately a LEAF module: request-context needs the mask for handle
+ * pushes, and loader-mask (the other natural home) imports request-context —
+ * importing from there would cycle. This module imports only is-thenable.
+ */
+/**
+ * A promise that never settles — the masked stand-in for a per-request value
+ * during shell capture. The consuming Suspense subtree suspends forever, so
+ * the static prerender postpones it as a hole instead of baking a per-request
+ * value into the shared shell. The capture abort (`maxWaitMs` in
+ * captureShellHTML) bounds how long the prerender waits before it freezes the
+ * prelude, so this never hangs the request.
+ */
+export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
+/**
+ * Deep-copy a container with every NESTED thenable replaced by a masked
+ * (never-resolving) promise. Applied during shell capture to (a) bake-lane
+ * loader containers (loader-cache.ts) and (b) pushed handle containers
+ * (createUseFunction) — the two rango-owned funnels where consumers declare
+ * per-request data by promise SHAPE.
+ *
+ * Why: a nested promise that happened to SETTLE before the capture's quiet
+ * window closed used to bake its value into the SHARED shell (and, for
+ * loaders, the snapshot pinned it for every HIT) — per-request data frozen
+ * and served cross-session (found live: a storefront basket, carrying the
+ * capturing session's basketId/customer identifiers, served to anonymous
+ * visitors). The window waits for the slowest shared material on the page, so
+ * any real data source (a 5ms SQL read, a 200ms basket API) lost the race.
+ * Masking makes the consuming subtree postpone as a hole no matter when the
+ * promise settles: liveness by declaration, not by racing the window.
+ *
+ * Only plain objects/arrays are traversed; other values are leaves. The INPUT
+ * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
+ * rule, semantic-matrix PPR3) shares the raw container and must keep real
+ * values. Cycles are preserved as cycles in the copy.
+ */
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The shell fast path
+ * reads it at handle-push time — a pushed container with a nested thenable
+ * declares per-request data, and a shell entry whose HANDLER layer made such
+ * a declaration cannot be served handler-free (the hole would never fill).
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+    thenable: boolean;
+}
+export declare function maskNestedContainerThenables(value: unknown, seen?: Map<object, unknown>, report?: MaskReport): unknown;

package/dist/types.backup/router/segment-resolution/revalidation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Revalidation Path Segment Resolution
+ *
+ * Functions for resolving segments during partial (revalidation) requests.
+ * Mirrors the fresh path but adds revalidation awareness: only re-resolves
+ * segments whose revalidate() predicate returns true.
+ */
+import { type EntryData } from "../../server/context";
+import type { HandlerContext, ResolvedSegment, ShouldRevalidateFn } from "../../types";
+import type { SegmentResolutionDeps, SegmentRevalidationResult, ActionContext } from "../types.js";
+/**
+ * Resolve loaders with revalidation awareness (for partial rendering).
+ * Returns both segments to render AND all matched segment IDs.
+ */
+export declare function resolveLoadersWithRevalidation<TEnv>(entry: EntryData, ctx: HandlerContext<any, TEnv>, belongsToRoute: boolean, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, shortCodeOverride?: string, stale?: boolean): Promise<{
+    segments: ResolvedSegment[];
+    matchedIds: string[];
+}>;
+/**
+ * Resolve only loader segments for all entries with revalidation logic.
+ */
+export declare function resolveLoadersOnlyWithRevalidation<TEnv>(entries: EntryData[], context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean): Promise<{
+    segments: ResolvedSegment[];
+    matchedIds: string[];
+}>;
+/**
+ * Build a map of segment shortCode -> entry with revalidate functions.
+ */
+export declare function buildEntryRevalidateMap(entries: EntryData[]): Map<string, {
+    entry: EntryData;
+    revalidate: ShouldRevalidateFn<any, any>[];
+}>;
+/**
+ * Resolve parallel segments with revalidation.
+ */
+export declare function resolveParallelSegmentsWithRevalidation<TEnv>(entry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean, options?: {
+    /**
+     * Seed for an unknown parent-chain slot (slot not in clientSegmentIds) when
+     * there are no deciding revalidate fns. "type-derived" (default, main path):
+     * `belongsToRoute || isNewParent`. "force-render" (orphan path): always
+     * `true` — orphan parallels always belong to the route and must render
+     * unless the user opts out via revalidate(); the #482 blank-parent-chain-
+     * slot guard.
+     */
+    parentChainDefault?: "type-derived" | "force-render";
+    /**
+     * When a slot's loaders are resolved relative to the slot segment push.
+     * "after" (default, main path) pushes the slot segment first; "before"
+     * (orphan path) resolves loaders first. This only changes the
+     * segments/matchedIds emission ORDER (the client reconciler is insensitive
+     * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
+     */
+    loaderOrder?: "after" | "before";
+}): Promise<SegmentRevalidationResult>;
+/**
+ * Resolve entry handler (layout, cache, or route) with revalidation.
+ */
+export declare function resolveEntryHandlerWithRevalidation<TEnv>(entry: Exclude<EntryData, {
+    type: "parallel";
+}>, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute: boolean, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean): Promise<{
+    segment: ResolvedSegment;
+    matchedId: string;
+}>;
+/**
+ * Resolve segments with revalidation awareness (for partial rendering).
+ */
+export declare function resolveSegmentWithRevalidation<TEnv>(entry: Exclude<EntryData, {
+    type: "parallel";
+}>, routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean): Promise<SegmentRevalidationResult>;
+/**
+ * Resolve orphan layout with revalidation.
+ */
+export declare function resolveOrphanLayoutWithRevalidation<TEnv>(orphan: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, belongsToRoute: boolean, deps: SegmentResolutionDeps<TEnv>, actionContext?: ActionContext, stale?: boolean, 
+/** Parent route entry — its loaders are inherited so parallel slots can access them. */
+parentRouteEntry?: EntryData): Promise<SegmentRevalidationResult>;
+/**
+ * Resolve all segments for a route with revalidation logic (for matchPartial).
+ */
+export declare function resolveAllSegmentsWithRevalidation<TEnv>(entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: ActionContext | undefined, interceptResult: {
+    intercept: any;
+    entry: EntryData;
+} | null, localRouteName: string, pathname: string, deps: SegmentResolutionDeps<TEnv>, stale?: boolean): Promise<{
+    segments: ResolvedSegment[];
+    matchedIds: string[];
+}>;

package/dist/types.backup/router/segment-resolution/static-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Static Store
+ *
+ * Lazy-initialized static store for production Static handler interception.
+ * Manages the build-time static manifest lookup for pre-rendered components.
+ */
+import type { ReactNode } from "react";
+/**
+ * Try to load a pre-rendered Static component from the build-time store.
+ * Returns the deserialized React element, or undefined if not available.
+ * Also replays any handle data captured at build time into the request's HandleStore.
+ *
+ * @param handlerId - The handler's $$id used to look up the static store entry.
+ * @param segmentId - The runtime segment shortCode. Handle data is replayed under
+ *   this key so that useHandle's segmentOrder matching works correctly.
+ */
+export declare function tryStaticLookup(handlerId: string, segmentId: string): Promise<ReactNode | undefined>;

package/dist/types.backup/router/segment-resolution/streamed-handler-telemetry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Streamed Handler Telemetry
+ *
+ * Shared fire-and-forget rejection observer for streamed handler promises,
+ * used by both the fresh and revalidation segment-resolution paths. Lives in
+ * its own module (never mocked) so the resolution unit tests that mock
+ * helpers.js / telemetry.js with explicit export lists do not resolve it to
+ * undefined.
+ */
+import type { ReactNode } from "react";
+/**
+ * Attach a fire-and-forget rejection observer to a streamed handler promise.
+ * React catches the actual error via its error boundary; this only emits
+ * the handler.error telemetry event.
+ */
+export declare function observeStreamedHandler(promise: Promise<ReactNode>, segmentId: string, segmentType: string, pathname?: string, routeKey?: string, params?: Record<string, string>): void;

package/dist/types.backup/router/segment-resolution/view-transition-default.d.ts

@@ -0,0 +1,28 @@
+/**
+ * View-transition boundary default resolution.
+ *
+ * Kept in its own module (rather than helpers.ts) because several resolution
+ * tests mock helpers.ts with an explicit export list; a shared util here is
+ * never mocked, so the fresh and revalidation paths always get the real
+ * implementation.
+ */
+import type { EntryData } from "../../server/context";
+/**
+ * Resolve a segment's transition config: stamp the `viewTransition` default and
+ * peel off a transition({ when }) predicate.
+ *
+ * `viewTransition`: the per-segment value (set via the transition() DSL) always
+ * wins. When it is unset, the router-level createRouter({ viewTransition })
+ * default is stamped in so the render gate reads the boundary decision off the
+ * segment — server and client, via the serialized segment — without the router
+ * option being threaded to the client. Only `false` is ever stamped; an unset
+ * (or "auto") value is left untouched because it already means "wrap" at the
+ * gate, which also avoids needless object allocation and payload growth.
+ *
+ * `when`: a server-only predicate. It is STRIPPED from the returned config (a
+ * function cannot cross Flight or the segment cache) and recorded on the request
+ * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
+ * outside any cache scope — and drop this segment's transition when it returns
+ * false. Used by both the fresh and revalidation resolution paths.
+ */
+export declare function applyViewTransitionDefault(transition: EntryData["transition"], viewTransitionDefault: "auto" | false | undefined, segmentId?: string): EntryData["transition"];

package/dist/types.backup/router/segment-resolution.d.ts

@@ -0,0 +1,3 @@
+export { handleHandlerResult, warnOnStreamedResponse, buildLoaderErrorContext, } from "./segment-resolution/helpers.js";
+export { resolveLoaders, type ResolveSegmentOptions, resolveSegment, resolveOrphanLayout, resolveParallelEntry, resolveAllSegments, resolveLoadersOnly, } from "./segment-resolution/fresh.js";
+export { resolveLoadersWithRevalidation, resolveLoadersOnlyWithRevalidation, buildEntryRevalidateMap, resolveParallelSegmentsWithRevalidation, resolveEntryHandlerWithRevalidation, resolveSegmentWithRevalidation, resolveOrphanLayoutWithRevalidation, resolveAllSegmentsWithRevalidation, } from "./segment-resolution/revalidation.js";

package/dist/types.backup/router/segment-wrappers.d.ts

@@ -0,0 +1,53 @@
+import type { EntryData, InterceptEntry } from "../server/context";
+import type { HandlerContext, ResolvedSegment, ShouldRevalidateFn } from "../types";
+import type { SegmentResolutionDeps } from "./types.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
+import type { InterceptSelectorContext } from "../server/context";
+export interface SegmentWrappers<TEnv = any> {
+    resolveAllSegments: (entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, options?: ResolveSegmentOptions) => Promise<ResolvedSegment[]>;
+    resolveLoadersOnly: (entries: EntryData[], context: HandlerContext<any, TEnv>) => Promise<ResolvedSegment[]>;
+    resolveLoadersOnlyWithRevalidation: (entries: EntryData[], context: HandlerContext<any, TEnv>, clientSegmentIds: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, routeKey: string, actionContext?: {
+        actionId?: string;
+        actionUrl?: URL;
+        actionResult?: any;
+        formData?: FormData;
+    }, stale?: boolean) => Promise<{
+        segments: ResolvedSegment[];
+        matchedIds: string[];
+    }>;
+    buildEntryRevalidateMap: (entries: EntryData[]) => Map<string, {
+        entry: EntryData;
+        revalidate: ShouldRevalidateFn<any, any>[];
+    }>;
+    resolveAllSegmentsWithRevalidation: (entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, clientSegmentSet: Set<string>, prevParams: Record<string, string>, request: Request, prevUrl: URL, nextUrl: URL, actionContext: {
+        actionId?: string;
+        actionUrl?: URL;
+        actionResult?: any;
+        formData?: FormData;
+    } | undefined, interceptResult: {
+        intercept: InterceptEntry;
+        entry: EntryData;
+    } | null, localRouteName: string, pathname: string) => Promise<{
+        segments: ResolvedSegment[];
+        matchedIds: string[];
+    }>;
+    findInterceptForRoute: (targetRouteKey: string, fromEntry: EntryData | null, selectorContext?: InterceptSelectorContext | null, isAction?: boolean) => {
+        intercept: InterceptEntry;
+        entry: EntryData;
+    } | null;
+    resolveInterceptEntry: (interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute?: boolean, revalidationContext?: any, options?: {
+        skipMiddleware?: boolean;
+    }) => Promise<ResolvedSegment[]>;
+    resolveInterceptLoadersOnly: (interceptEntry: InterceptEntry, parentEntry: EntryData, params: Record<string, string>, context: HandlerContext<any, TEnv>, belongsToRoute?: boolean, revalidationContext?: any) => Promise<{
+        loaderDataPromise: Promise<any[]> | any[];
+        loaderIds: string[];
+    } | null>;
+}
+/**
+ * Create thin wrapper functions that bind segmentDeps to extracted
+ * segment resolution and intercept resolution functions.
+ *
+ * These maintain the same signatures as the original inline functions
+ * so that RouterContext and call sites don't need to change.
+ */
+export declare function createSegmentWrappers<TEnv = any>(segmentDeps: SegmentResolutionDeps<TEnv>): SegmentWrappers<TEnv>;

package/dist/types.backup/router/state-cookie-name.d.ts

@@ -0,0 +1 @@
+export declare function resolveStateCookieName(prefix: string | undefined, routerId: string): string;

package/dist/types.backup/router/substitute-pattern-params.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`, producing a URL. Built by walking the SAME parsed segments the
+ * matcher uses (`parsePattern`) and emitting one piece per segment — so a
+ * substituted value is never re-scanned as if it were another placeholder (a
+ * catch-all value like `sha:abc/x` used to make the "required" pass read `:abc`
+ * and throw). Constraint syntax (`:name(en|gb)`) is stripped; trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was omitted.
+ *
+ * Semantics per segment:
+ * - static             -> emitted verbatim.
+ * - `:name`            -> required; `undefined` throws, `""` yields an empty segment.
+ * - `:name?`           -> optional; `undefined`/`""` omitted.
+ * - `:name*` / `:name+`-> catch-all; the value is multi-segment, so each segment
+ *                         is encoded and the `/` separators are preserved. `+`
+ *                         (one-or-more) throws when absent; `*` (and bare `*`)
+ *                         omit when absent.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export declare function substitutePatternParams(pattern: string, params: Record<string, string | undefined>, routeName: string): string;