@rangojs/router 0.0.0-experimental.tapabs2 → 0.1.0

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,22 @@
+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>;
+}
+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-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;

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

@@ -0,0 +1,50 @@
+import type { RouterContext } from "./router-context.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
+import type { EntryData } from "../server/context";
+import type { PartialPrerenderProps } from "../urls/pattern-types.js";
+import type { HandlerContext, ResolvedSegment } from "../types";
+import type { SerializedSegmentData } from "../cache/types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+export interface PrerenderMatchDeps<TEnv = any> {
+    findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
+    buildRouterContext: () => RouterContext<TEnv>;
+    mergedRouteMap: Record<string, string>;
+    resolveAllSegments: (entries: EntryData[], routeKey: string, params: Record<string, string>, context: HandlerContext<any, TEnv>, loaderPromises: Map<string, Promise<any>>, options?: ResolveSegmentOptions) => Promise<ResolvedSegment[]>;
+}
+/**
+ * Build-time pre-render match. Resolves segments with a BuildContext
+ * (no request/env/headers/cookies), skipping middleware and loaders.
+ */
+export declare function matchForPrerender<TEnv = any>(pathname: string, params: Record<string, string>, deps: PrerenderMatchDeps<TEnv>, buildVars?: Record<string, any>, isPassthroughRoute?: boolean, buildEnv?: TEnv, 
+/** Dev-only: check getParams() for passthrough routes to skip unknown params. */
+devMode?: boolean): Promise<{
+    segments: SerializedSegmentData[];
+    /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. Encoded in
+     *  the producer (where the Flight codec resolves) so the node-side build/dev
+     *  sinks can persist it without touching the codec. */
+    handles: string;
+    routeName: string;
+    params: Record<string, string>;
+    interceptSegments?: SerializedSegmentData[];
+    /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact;
+     *  the sinks store it as-is (no longer merge raw records). */
+    interceptHandles?: string;
+    passthrough?: true;
+    /**
+     * The matched route entry's `ppr` path option, surfaced so the build
+     * collection can flag Prerender+ppr routes as build-time shell candidates
+     * (issue #699 producer B). Runtime-only today; the build otherwise never
+     * sees the option (it lives on EntryData, not the trie).
+     */
+    ppr?: boolean | PartialPrerenderProps;
+} | null>;
+/**
+ * Render a single Static handler at build time.
+ * Creates a minimal BuildContext, calls the handler, and RSC-serializes
+ * the component. Returns the encoded Flight string (or null on failure).
+ * Used by the Vite plugin to collect static segment data at build time.
+ */
+export declare function renderStaticSegment<TEnv = any>(handler: Function, handlerId: string, mergedRouteMap: Record<string, string>, routeName?: string, buildEnv?: TEnv, devMode?: boolean): Promise<{
+    encoded: string;
+    handles: string;
+} | null>;

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

@@ -0,0 +1,22 @@
+import type { EntryData } from "../server/context";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { MiddlewareFn } from "./middleware.js";
+export interface PreviewMatchDeps<TEnv = any> {
+    findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
+}
+/**
+ * Preview match - returns route middleware without segment resolution.
+ * Also returns responseType and handler for response routes (non-RSC short-circuit).
+ */
+export declare function previewMatch<TEnv = any>(request: Request, _context: TEnv, deps: PreviewMatchDeps<TEnv>): Promise<{
+    routeMiddleware?: Array<{
+        handler: MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+    responseType?: string;
+    handler?: Function;
+    params?: Record<string, string>;
+    negotiated?: boolean;
+    manifestEntry?: EntryData;
+    routeKey?: string;
+} | null>;

package/dist/types/router/request-classification.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Request Classification
+ *
+ * Replaces the implicit "preview then match again" model with a clean
+ * two-stage architecture:
+ *
+ * 1. Classification — classifyRequest() produces a RequestPlan that answers
+ *    all routing questions once: target route, request mode, route middleware,
+ *    response-route info, negotiation state.
+ *
+ * 2. Execution — executeRequest() dispatches on the plan to the appropriate
+ *    handler (response route, loader fetch, full render, partial render,
+ *    action revalidation, PE render).
+ *
+ * Builds on RouteSnapshot from route-snapshot.ts.
+ */
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import { type RouteSnapshot } from "./route-snapshot.js";
+interface RedirectPlan<TEnv = any> {
+    mode: "redirect";
+    route: RouteSnapshot<TEnv>;
+    redirectUrl: string;
+}
+interface VersionMismatchPlan<TEnv = any> {
+    mode: "version-mismatch";
+    /** May be undefined when version mismatch is detected before route resolution */
+    route?: RouteSnapshot<TEnv>;
+    reloadUrl: string;
+}
+interface AppSwitchReloadPlan {
+    mode: "app-switch";
+    /** Clean target URL (internal _rsc_* params stripped) to navigate to. */
+    reloadUrl: string;
+}
+interface ResponseRoutePlan<TEnv = any> {
+    mode: "response";
+    route: RouteSnapshot<TEnv>;
+    handler: Function;
+    responseType: string;
+    negotiated: boolean;
+    manifestEntry: EntryData;
+    routeMiddleware: CollectedMiddleware[];
+}
+interface LoaderFetchPlan<TEnv = any> {
+    mode: "loader";
+    route: RouteSnapshot<TEnv>;
+}
+interface PeRenderPlan<TEnv = any> {
+    mode: "pe-render";
+    route: RouteSnapshot<TEnv>;
+}
+interface ActionPlan<TEnv = any> {
+    mode: "action";
+    route: RouteSnapshot<TEnv>;
+    actionId: string;
+    negotiated: boolean;
+}
+interface FullRenderPlan<TEnv = any> {
+    mode: "full-render";
+    route: RouteSnapshot<TEnv>;
+    negotiated: boolean;
+}
+interface PartialRenderPlan<TEnv = any> {
+    mode: "partial-render";
+    route: RouteSnapshot<TEnv>;
+    negotiated: boolean;
+}
+/**
+ * The output of request classification. A discriminated union where each
+ * variant carries exactly the fields needed for its execution path.
+ */
+export type RequestPlan<TEnv = any> = RedirectPlan<TEnv> | VersionMismatchPlan<TEnv> | AppSwitchReloadPlan | ResponseRoutePlan<TEnv> | LoaderFetchPlan<TEnv> | PeRenderPlan<TEnv> | ActionPlan<TEnv> | FullRenderPlan<TEnv> | PartialRenderPlan<TEnv>;
+/**
+ * Plans that have passed the terminal-check gate (version-mismatch and
+ * app-switch reloads handled) and are ready for execution. Always have a
+ * `route` field.
+ */
+export type ExecutableRequestPlan<TEnv = any> = Exclude<RequestPlan<TEnv>, VersionMismatchPlan<TEnv> | AppSwitchReloadPlan>;
+/**
+ * Re-export individual plan types for consumers that need to narrow.
+ */
+export type { RedirectPlan, VersionMismatchPlan, ResponseRoutePlan, LoaderFetchPlan, PeRenderPlan, ActionPlan, FullRenderPlan, PartialRenderPlan, };
+export interface ClassifyRequestDeps<TEnv = any> {
+    findMatch: (pathname: string) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
+    routerVersion: string;
+    routerId: string;
+}
+/**
+ * Classify an incoming request into a RequestPlan.
+ *
+ * This is the single source of truth for request mode detection. It replaces
+ * the scattered previewMatch + isAction/isLoaderFetch/isPartial checks in
+ * handler.ts.
+ *
+ * Classification order:
+ * 1. Route resolution (findMatch + loadManifest via resolveRoute lite)
+ * 2. Redirect detection
+ * 3. Version mismatch
+ * 4. Response route + content negotiation
+ * 5. Mode detection from headers/params
+ */
+export declare function classifyRequest<TEnv = any>(request: Request, url: URL, deps: ClassifyRequestDeps<TEnv>): Promise<RequestPlan<TEnv>>;