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

package/dist/types/router/match-result.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Match Result Collection
+ *
+ * Collects segments from the pipeline and builds the final MatchResult.
+ * This is the final stage of the match pipeline.
+ *
+ * COLLECTION FLOW
+ * ===============
+ *
+ *   Pipeline Generator
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | collectSegments()        |  Drain async generator
+ *   | for await...push         |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | buildMatchResult()       |  Transform to MatchResult
+ *   +---------------------------+
+ *         |
+ *         |
+ *   +-----+-----+
+ *   |           |
+ * Full       Partial
+ * Match      Match
+ *   |           |
+ *   v           v
+ * All segs   Filter:
+ * rendered   - null components out
+ *            - keep loaders
+ *            - handle intercepts
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *   MatchResult {
+ *     segments,    // Segments to render
+ *     matched,     // All segment IDs
+ *     diff,        // Changed segment IDs
+ *     params,      // Route params
+ *     slots,       // Intercept slot data
+ *     serverTiming // Performance metrics
+ *   }
+ *
+ *
+ * FULL VS PARTIAL MATCH
+ * =====================
+ *
+ * Full Match (document request):
+ *   - All segments are rendered
+ *   - allIds = all segment IDs
+ *   - No filtering needed
+ *
+ * Partial Match (navigation):
+ *   - Filter out null components (client already has them)
+ *   - BUT keep loader segments (they carry data)
+ *   - Handle intercepts specially (preserve client page + add modal)
+ *
+ *
+ * SEGMENT FILTERING RULES
+ * =======================
+ *
+ * For partial match, segments are filtered:
+ *
+ *   Keep if:
+ *     - component !== null (needs rendering)
+ *     - type === "loader" (carries data even with null component)
+ *     - client doesn't have the segment (structurally required parent node)
+ *
+ *   Skip if:
+ *     - component === null AND type !== "loader" AND client has it cached
+ *     - (Revalidation skip — client already has this segment's UI)
+ *
+ *
+ * INTERCEPT HANDLING
+ * ==================
+ *
+ * When intercepting (modal over current page):
+ *
+ *   allIds = client segments + intercept segments
+ *
+ * This tells the client:
+ *   1. Keep your current segments
+ *   2. Add these intercept segments to the modal slot
+ *
+ * The page stays visible, modal renders on top.
+ *
+ *
+ * MATCHRESULT STRUCTURE
+ * =====================
+ *
+ * {
+ *   segments: ResolvedSegment[]  // Segments to serialize and render
+ *   matched: string[]            // All segment IDs for this route
+ *   diff: string[]               // Which segments changed (for client diffing)
+ *   params: Record<string,string> // Route parameters
+ *   slots?: Record<string, {...}> // Named slot data for intercepts
+ *   serverTiming?: string         // Server-Timing header value
+ *   routeMiddleware?: [...]       // Route middleware results
+ * }
+ *
+ * The client uses this to:
+ *   1. Render segments[] to the UI tree
+ *   2. Update internal state with matched[]
+ *   3. Diff against previous state with diff[]
+ *   4. Render slot content if slots present
+ */
+import type { MatchResult, ResolvedSegment } from "../types.js";
+import type { MatchContext, MatchPipelineState } from "./match-context.js";
+export declare function collectSegments(generator: AsyncGenerator<ResolvedSegment>): Promise<ResolvedSegment[]>;
+export declare function buildMatchResult<TEnv>(allSegments: ResolvedSegment[], ctx: MatchContext<TEnv>, state: MatchPipelineState): MatchResult;
+export declare function collectMatchResult<TEnv>(pipeline: AsyncGenerator<ResolvedSegment>, ctx: MatchContext<TEnv>, state: MatchPipelineState): Promise<MatchResult>;

package/dist/types/router/metrics.d.ts

@@ -0,0 +1,6 @@
+import type { MetricsStore } from "../server/context";
+export declare function createMetricsStore(debugPerformance: boolean, requestStart?: number): MetricsStore | undefined;
+export declare function appendMetric(metricsStore: MetricsStore | undefined, label: string, start: number, duration: number, depth?: number, desc?: string): void;
+export declare function buildMetricsTiming(method: string, pathname: string, metricsStore: MetricsStore | undefined): string | undefined;
+export declare function logMetrics(method: string, pathname: string, metricsStore: MetricsStore): void;
+export declare function generateServerTiming(metricsStore: MetricsStore): string;

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

@@ -0,0 +1,74 @@
+import type { ContextVar } from "../context-var.js";
+import type { DefaultReverseRouteMap, DefaultRouteName, DefaultVars } from "../types/global-namespace.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type { Theme } from "../theme/types.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import type { RequestScope } from "../types/request-scope.js";
+type GetVariableFn = {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+    <K extends keyof DefaultVars>(key: K): DefaultVars[K];
+};
+type SetVariableFn = {
+    <T>(contextVar: ContextVar<T>, value: T, options?: {
+        cache?: boolean;
+    }): void;
+    <K extends keyof DefaultVars>(key: K, value: DefaultVars[K], options?: {
+        cache?: boolean;
+    }): void;
+};
+export interface CookieOptions {
+    domain?: string;
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+}
+export interface MiddlewareContext<TEnv = any, TParams = Record<string, string | undefined>> extends RequestScope<TEnv> {
+    params: TParams;
+    /**
+     * True for build-time render/capture requests. Live requests use false.
+     * Build-time PPR shell capture sets this while replaying middleware.
+     */
+    readonly build: boolean;
+    /**
+     * Opt this request out of PPR shell serving/capture.
+     * During middleware this runs before the shell HIT commit point, so it can
+     * force the request onto the dynamic axis.
+     *
+     * Scope: the PPR SHELL axis only. It does NOT disable prerender B-segment
+     * (Prerender/Static) serving — a Prerender() route still replays its
+     * build-baked segments at runtime.
+     */
+    dynamic(): void;
+    readonly headers: Headers;
+    get: GetVariableFn;
+    set: SetVariableFn;
+    header(name: string, value: string): void;
+    routeName?: DefaultRouteName;
+    debugPerformance(): void;
+    theme?: Theme;
+    setTheme?: (theme: Theme) => void;
+    setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+}
+export type MiddlewareFn<TEnv = any, TParams = Record<string, string | undefined>> = (ctx: MiddlewareContext<TEnv, TParams>, next: () => Promise<Response>) => Response | void | Promise<Response | void>;
+export interface MiddlewareEntry<TEnv = any> {
+    pattern: string | null;
+    regex: RegExp | null;
+    paramNames: string[];
+    handler: MiddlewareFn<TEnv>;
+}
+export interface ResponseHolder {
+    response: Response | null;
+}
+export interface MiddlewareCollectableEntry {
+    middleware?: MiddlewareFn<any, any>[];
+    layout?: MiddlewareCollectableEntry[];
+}
+export interface CollectedMiddleware {
+    handler: MiddlewareFn<any, any>;
+    params: Record<string, string>;
+}
+export {};

package/dist/types/router/middleware.d.ts

@@ -0,0 +1,116 @@
+import type { CollectedMiddleware, MiddlewareCollectableEntry, MiddlewareContext, MiddlewareEntry, MiddlewareFn, ResponseHolder } from "./middleware-types.js";
+export type { CookieOptions, MiddlewareContext, MiddlewareEntry, MiddlewareFn, } from "./middleware-types.js";
+/**
+ * Compile a middleware scope pattern to a regex + param names.
+ *
+ * Middleware scopes reuse the route pattern parser (`parsePattern` from
+ * pattern-matching.ts), so they support the same param forms as routes —
+ * optional (`:x?`), constrained (`:x(en|gb)`), and suffix (`:x.html`) — in
+ * addition to the trailing-`*` wildcard middleware relies on. Before this
+ * unification the middleware-side parser handled only static, bare `:param`,
+ * and trailing `*`, so e.g. `router.use("/:locale(en|gb)/*", mw)` silently
+ * named the param "locale(en|gb)" and never enforced the constraint.
+ *
+ * Middleware matching semantics deliberately differ from route matching, so we
+ * emit the regex here rather than route through `compilePattern`:
+ * - `*` alone matches every path (`/^.*$/`).
+ * - A trailing `*` segment is an OPTIONAL subtree match (`(?:/.*)?`): `/admin/*`
+ *   matches `/admin`, `/admin/`, and `/admin/users`. It contributes no param
+ *   name (unlike route wildcards, which capture `*`).
+ * - A NON-trailing `*` is also OPTIONAL (`(?:/.*)?`), matching zero-or-more
+ *   intermediate segments: `/a/<star>/b` matches both `/a/b` and `/a/x/b`. This
+ *   mirrors the pre-unification parser, which compiled every `*` part as
+ *   optional regardless of position.
+ * - A pattern without a trailing `*` tolerates a trailing slash (`/?$`).
+ * - Constraints are baked into the regex as an alternation so `matchMiddleware`
+ *   (a bare `regex.test`) enforces them without extra validation. Constraint
+ *   values are matched against the raw (still URL-encoded) path segment, which
+ *   matches the pre-unification middleware behavior (it never decoded for
+ *   matching); the constraint string is regex-escaped so values like `en.gb`
+ *   are treated literally.
+ *
+ * The route segment parser only recognizes `/`-prefixed segments, but the
+ * pre-unification middleware parser split on `/` and dropped empty parts, so a
+ * leading slash was irrelevant: `use("admin/*")` and `use("/admin/*")` scoped
+ * identically. Normalize a non-`*` pattern to have a leading slash before
+ * parsing so that behavior is preserved (without it, `parseRoutePattern("admin/*")`
+ * drops the static `admin` and the scope explodes to every path).
+ */
+export declare function compileMiddlewarePattern(pattern: string): {
+    regex: RegExp;
+    paramNames: string[];
+};
+/**
+ * Extract params from a pathname using a pattern's regex and param names.
+ *
+ * Values are URL-decoded so apps see the raw string (e.g. "ivo@example.com")
+ * instead of the percent-encoded form ("ivo%40example.com"). This matches the
+ * contract assumed by ctx.reverse (which re-encodes) and aligns with
+ * Express/React Router/Fastify/Koa.
+ */
+export declare function extractParams(pathname: string, regex: RegExp, paramNames: string[]): Record<string, string>;
+/**
+ * Create middleware context
+ *
+ * Note: The implementation uses runtime values while the interface provides
+ * compile-time type safety. The env/get/set types are resolved at call sites
+ * via conditional types based on TEnv from createRouter<TBindings>().
+ */
+export declare function createMiddlewareContext<TEnv>(request: Request, env: TEnv, params: Record<string, string>, variables: Record<string, unknown>, responseHolder: ResponseHolder, reverse?: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string): MiddlewareContext<TEnv>;
+/**
+ * Match middleware entries against a pathname
+ * Returns entries that match, with extracted params
+ */
+export declare function matchMiddleware<TEnv>(pathname: string, entries: MiddlewareEntry<TEnv>[]): Array<{
+    entry: MiddlewareEntry<TEnv>;
+    params: Record<string, string>;
+}>;
+/**
+ * Execute middleware chain
+ *
+ * Features:
+ * - `await next()` returns actual Response
+ * - `ctx.headers` available before and after `await next()`
+ * - `ctx.header()` shorthand for setting a single header
+ * - Forgiving: if middleware doesn't return, uses the downstream response
+ * - Short-circuit: return OR throw a Response to stop chain
+ * - Error catching: try/catch around `next()` works
+ */
+export declare function executeMiddleware<TEnv>(middlewares: Array<{
+    entry: MiddlewareEntry<TEnv>;
+    params: Record<string, string>;
+}>, request: Request, env: TEnv, variables: Record<string, any>, finalHandler: () => Promise<Response>, reverse?: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string): Promise<Response>;
+/**
+ * Execute middleware for intercepts (simplified execution)
+ *
+ * Intercepts use a shared stubResponse from the request context. This function:
+ * - Runs middleware in sequence with a simple next() chain
+ * - Returns Response if any middleware short-circuits (returns OR throws a Response, or redirects, BEFORE next())
+ * - Returns null if all middleware calls next() - headers set after next() remain on stubResponse
+ *
+ * @param middlewares - Array of middleware functions
+ * @param request - Original request
+ * @param env - Environment bindings
+ * @param params - Route params
+ * @param variables - Shared variables object
+ * @param stubResponse - Response from request context for collecting headers/cookies
+ */
+export declare function executeInterceptMiddleware<TEnv>(middlewares: MiddlewareFn<TEnv>[], request: Request, env: TEnv, params: Record<string, string>, variables: Record<string, any>, stubResponse: Response, reverse?: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string): Promise<Response | null>;
+/**
+ * Execute middleware chain for loaders (simpler signature)
+ *
+ * Takes an array of MiddlewareFn directly (no entry wrapper needed).
+ * Used for fetchable loader middleware execution.
+ */
+export declare function executeLoaderMiddleware<TEnv>(middlewares: MiddlewareFn<TEnv>[], request: Request, env: TEnv, params: Record<string, string>, variables: Record<string, any>, finalHandler: () => Promise<Response>, reverse?: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string): Promise<Response>;
+/**
+ * Collect route-level middleware from an entry tree
+ *
+ * Recursively collects middleware from entries and their orphan layouts.
+ * Used by match(), matchPartial(), and previewMatch() to gather route middleware.
+ *
+ * @param entries - Iterable of entries to collect middleware from (typically from traverseBack)
+ * @param params - Route params to attach to each middleware entry
+ * @returns Array of collected middleware with params
+ */
+export declare function collectRouteMiddleware(entries: Iterable<MiddlewareCollectableEntry>, params: Record<string, string>): CollectedMiddleware[];

package/dist/types/router/navigation-snapshot.d.ts

@@ -0,0 +1,51 @@
+import type { RouteMatchResult } from "./pattern-matching.js";
+export interface NavigationSnapshot {
+    prevUrl: URL;
+    prevParams: Record<string, string>;
+    prevMatch: RouteMatchResult | null;
+    interceptContextUrl: URL;
+    interceptContextMatch: RouteMatchResult | null;
+    clientSegmentIds: string[];
+    clientSegmentSet: Set<string>;
+    filteredSegmentIds: string[];
+    stale: boolean;
+    isSameRouteNavigation: boolean;
+    effectiveFromUrl: URL;
+    effectiveFromMatch: RouteMatchResult | null;
+    hasInterceptSource: boolean;
+    isHmr: boolean;
+}
+export interface ResolveNavigationDeps {
+    findMatch: (pathname: string) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
+}
+/**
+ * The raw navigation-context header for a partial request, or null when the
+ * request carries none. Single source of truth shared by resolveNavigation and
+ * the PPR replay gate (matchPartialWithPprReplay): a context-less partial can
+ * never produce a partial match, so the replay path must decide
+ * `no-navigation-context` BEFORE spending shell-store reads — the two
+ * predicates drifting apart would misattribute the bypass again.
+ */
+export declare function getNavigationContextHeader(request: Request): string | null;
+/**
+ * Whether withCacheLookup's prerender short-circuit will serve this partial
+ * from the build-time prerender store: a Prerender() match (`matched.pr`)
+ * outside dev HMR — the short-circuit is disabled on X-RSC-HMR so HMR
+ * navigations pick up edited modules. Shared by withCacheLookup and the PPR
+ * replay gate (matchPartialWithPprReplay) for the same drift reason as
+ * getNavigationContextHeader: the gate's `prerender-store` bypass must decide
+ * exactly what the middleware will actually do. (Both callers additionally
+ * exclude actions on their own paths — the gate via its GET-only check.)
+ */
+export declare function prerenderStoreShortCircuits(pr: true | undefined, request: Request): boolean;
+/**
+ * The intercept-source header for a partial request, or null when the request
+ * carries none. Shared by resolveNavigation and the PPR replay gate's
+ * prerender probe: intercept navigations consult the intercept-specific
+ * prerender artifact (`paramHash + "/i"`), so the probe must check the same
+ * variant the middleware will — probing the bare hash for an intercept
+ * request would report `prerender-store` for an artifact that cannot serve.
+ */
+export declare function getInterceptSourceHeader(request: Request): string | null;
+export declare function resolveNavigation(request: Request, url: URL, currentRouteKey: string, deps: ResolveNavigationDeps): Promise<NavigationSnapshot | null>;
+export declare function createNavigationSnapshot(overrides?: Partial<NavigationSnapshot>): NavigationSnapshot;

package/dist/types/router/params-util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared route-param comparison helpers.
+ */
+/**
+ * Shallow equality for two route-param records. Same-reference is a fast path;
+ * otherwise compares key count then each value.
+ */
+export declare function paramsEqual(a: Record<string, string>, b: Record<string, string>): boolean;

package/dist/types/router/parse-pattern.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Route pattern parsing (grammar only).
+ *
+ * Deliberately dependency-free so it is safe to bundle into the CLIENT — the
+ * reverse helper (`substitute-pattern-params.ts` -> `use-reverse`) needs it, and
+ * pulling it from `pattern-matching.ts` would drag that module's server-only
+ * transitive imports (`node:async_hooks` via `logging.ts`) into the browser.
+ * `pattern-matching.ts` re-exports these so existing importers are unaffected.
+ */
+/**
+ * Parsed segment info
+ */
+export interface ParsedSegment {
+    type: "static" | "param" | "wildcard";
+    value: string;
+    optional: boolean;
+    constraint?: string[];
+    suffix?: string;
+    /**
+     * Named catch-all repeat modifier. On a `wildcard` segment whose `value` is a
+     * param name (`:name+` / `:name*`), `true` marks one-or-more (`+`, rejects the
+     * zero-segment case); absent/false marks zero-or-more (`*`, and the bare `/*`).
+     */
+    oneOrMore?: boolean;
+}
+/**
+ * Parse a route pattern into segments
+ *
+ * Supports:
+ * - Static: /blog, /about
+ * - Params: /:slug, /:id
+ * - Optional: /:locale?, /:page?
+ * - Constrained: /:locale(en|gb), /:type(post|page)
+ * - Optional + Constrained: /:locale(en|gb)?
+ * - Wildcard: /*
+ * - Named catch-all: /:slug* (zero-or-more), /:path+ (one-or-more)
+ */
+export declare function parsePattern(pattern: string): ParsedSegment[];

package/dist/types/router/pattern-matching.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Router Pattern Matching
+ *
+ * Route pattern compilation and matching utilities.
+ */
+import type { RouteEntry } from "../types";
+import type { EntryData } from "../server/context";
+import { parsePattern, type ParsedSegment } from "./parse-pattern.js";
+export { parsePattern, type ParsedSegment };
+/**
+ * Compiled pattern result containing regex, param metadata, and trailing slash info.
+ */
+export interface CompiledPattern {
+    regex: RegExp;
+    paramNames: string[];
+    hasTrailingSlash: boolean;
+    /**
+     * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
+     * Validated against the **decoded** param value after regex extraction so
+     * a URL like `/en%20GB` still matches `:lang(en GB)` — matching the trie
+     * path's behavior (trie-matching.ts:validateAndBuild).
+     */
+    constraints?: Record<string, string[]>;
+    /**
+     * The pattern's catch-all param, if any (`*` for bare `/*`, the name for a
+     * named `:name+`/`:name*`). A zero-or-more catch-all (`oneOrMore: false`)
+     * whose optional group is absent binds "" rather than being omitted — so
+     * `/docs` matches `/docs/:slug*` with `slug === ""`. `oneOrMore` keeps the
+     * same polarity as `ParsedSegment.oneOrMore` and the trie's `w1`.
+     */
+    catchAll?: {
+        name: string;
+        oneOrMore: boolean;
+    };
+}
+/**
+ * Get a compiled pattern from cache or compile and cache it.
+ * Avoids O(routes) regex compilations per request in the fallback path.
+ */
+export declare function getCompiledPattern(pattern: string): CompiledPattern;
+/**
+ * Return the current size of the compiled pattern cache.
+ * Exposed for testing.
+ */
+export declare function getPatternCacheSize(): number;
+/**
+ * Clear the compiled pattern cache.
+ * Exposed for testing.
+ */
+export declare function clearPatternCache(): void;
+/**
+ * Compile a route pattern to regex
+ *
+ * Supports:
+ * - Static segments: /blog, /about
+ * - Dynamic params: /:slug, /:id
+ * - Optional params: /:locale?, /:page?
+ * - Constrained params: /:locale(en|gb)
+ * - Optional + constrained: /:locale(en|gb)?
+ * - Wildcard: /*
+ *
+ * @example
+ * compilePattern("/blog/:slug")           // matches /blog/hello
+ * compilePattern("/:locale?/blog")        // matches /blog or /en/blog
+ * compilePattern("/:locale(en|gb)/blog")  // matches /en/blog or /gb/blog
+ * compilePattern("/:locale(en|gb)?/blog") // matches /blog, /en/blog, or /gb/blog
+ */
+export declare function compilePattern(pattern: string): CompiledPattern;
+/**
+ * Build the named-params record from a regex match. Optional segments that
+ * didn't capture leave the corresponding group `undefined`; we skip those
+ * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
+ * keeps the runtime aligned with the `ExtractParams` type and matches the
+ * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ *
+ * A zero-or-more catch-all (`compiled.catchAll`, `oneOrMore: false`) whose
+ * optional group didn't capture binds "" instead of being omitted, so `/docs`
+ * matches `/docs/:slug*` with `slug === ""`. Exported so the `renderRoute`
+ * testing harness (`matchLeaf`) shares this exact logic instead of forking it.
+ */
+export declare function buildParamsFromMatch(match: RegExpExecArray, paramNames: string[], catchAll?: {
+    name: string;
+    oneOrMore: boolean;
+}): Record<string, string>;
+/**
+ * Extract the static prefix from a route pattern.
+ * Returns everything before the first param/wildcard.
+ *
+ * Called ONCE at registration time, not at match time.
+ *
+ * Examples:
+ * - "/api" → "/api"
+ * - "/site/:locale" → "/site"
+ * - "/:locale" → ""
+ * - "/admin/users/:id" → "/admin/users"
+ * - "/api/*" → "/api"
+ */
+export declare function extractStaticPrefix(pattern: string): string;
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export declare function joinPrefix(base: string | undefined, prefix: string): string;
+/**
+ * Match a pathname against registered routes
+ *
+ * Note: Optional params that are absent in the path are omitted from the
+ * returned `params` (read as `undefined`), matching the trie matcher and
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition to
+ * determine which keys are optional.
+ *
+ * Trailing slash handling (priority order):
+ * 1. Per-route `trailingSlash` config from route()
+ * 2. Pattern-based detection (pattern ending with `/`)
+ *
+ * Modes:
+ * - "never": Redirect to no trailing slash
+ * - "always": Redirect to with trailing slash
+ * - "ignore": Match both, no redirect
+ */
+/**
+ * Result of a route match
+ */
+export interface RouteMatchResult<TEnv = any> {
+    entry: RouteEntry<TEnv>;
+    routeKey: string;
+    params: Record<string, string>;
+    redirectTo?: string;
+    /** Route has pre-rendered data available (from trie) */
+    pr?: true;
+    /** Passthrough: handler kept for live fallback on unknown params (from trie) */
+    pt?: true;
+    /** Response type for non-RSC routes (json, text, image, any) */
+    responseType?: string;
+    /** Negotiate variants: response-type routes sharing this path */
+    negotiateVariants?: Array<{
+        routeKey: string;
+        responseType: string;
+    }>;
+    /** RSC-first: RSC route was defined before response-type variants */
+    rscFirst?: true;
+}
+/**
+ * Result when a lazy entry needs evaluation before matching
+ */
+export interface LazyEvaluationNeeded<TEnv = any> {
+    lazyEntry: RouteEntry<TEnv>;
+}
+/**
+ * Type guard to check if result is a lazy evaluation needed response
+ */
+export declare function isLazyEvaluationNeeded<TEnv>(result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null): result is LazyEvaluationNeeded<TEnv>;
+interface MatchDebugStats {
+    entriesChecked: number;
+    entriesSkipped: number;
+    routesChecked: number;
+}
+export declare function enableMatchDebug(enabled: boolean): void;
+export declare function getMatchDebugStats(): MatchDebugStats;
+export declare function findMatch<TEnv>(pathname: string, routesEntries: RouteEntry<TEnv>[]): RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null;
+/**
+ * Traverse from entry to bottom to top, yielding each EntryData
+ * e.g. {child -> parent -> grandparent ...}
+ */
+export declare function traverseBack(entry: EntryData): Generator<EntryData>;

package/dist/types/router/prefetch-cache-ttl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve the prefetch cache TTL once, at router init, into the three derived
+ * values the rest of the router consumes: seconds (for the Cache-Control
+ * max-age), milliseconds (for the client-side in-memory cache), and the
+ * Cache-Control header string (or false when caching is disabled).
+ *
+ * `false` disables prefetch caching (seconds 0). A non-finite input
+ * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
+ * treated as the default rather than producing a malformed
+ * `Cache-Control: max-age=NaN` header; CDNs/browsers ignore such a directive,
+ * which would silently disable caching on EVERY prefetch response. Negative
+ * finite values clamp to 0 (disabled).
+ *
+ * Policy note: this is the prefetch-TTL policy specifically. Other finite-number
+ * guards in the codebase deliberately differ — defer.ts treats Infinity as an
+ * intentional disable, and profile-registry.ts THROWS on non-finite/negative ttl
+ * at config time. They are NOT the same guard, so don't unify them.
+ */
+export interface ResolvedPrefetchCacheTTL {
+    /** TTL in seconds for the Cache-Control max-age directive. */
+    seconds: number;
+    /** TTL in milliseconds for the client-side in-memory prefetch cache. */
+    ms: number;
+    /** Cache-Control header value, or false when caching is disabled. */
+    cacheControl: string | false;
+}
+export declare function resolvePrefetchCacheTTL(rawTTL: number | false | undefined): ResolvedPrefetchCacheTTL;

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/prefetch-limits.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolve the client-side prefetch limits — the in-memory prefetch cache size
+ * and the speculative-prefetch queue concurrency — once, at router init. Both
+ * are positive-integer counts shipped to the browser in payload metadata; the
+ * browser entry feeds them to the prefetch cache (`initPrefetchCache`) and the
+ * prefetch queue (`setPrefetchConcurrency`) at startup.
+ *
+ * Policy note: this is a SEPARATE policy from resolvePrefetchCacheTTL
+ * (prefetch-cache-ttl.ts). These are counts, not durations, so the disable
+ * paths differ: a TTL of `false`/0 intentionally turns prefetching off, but a
+ * cache size or concurrency of 0 would silently break prefetching while leaving
+ * it nominally enabled — never the intent of passing a number. So any value
+ * that is not a finite integer >= 1 (0, negative, fractional below 1, NaN,
+ * Infinity, undefined) falls back to the default. Finite values >= 1 are
+ * floored. Do not unify this guard with the TTL guard.
+ */
+export declare const DEFAULT_PREFETCH_CACHE_SIZE = 100;
+export declare const DEFAULT_PREFETCH_CONCURRENCY = 2;
+export declare function resolvePrefetchCacheSize(raw: number | undefined): number;
+export declare function resolvePrefetchConcurrency(raw: number | undefined): number;