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

package/dist/types/browser/validate-redirect-origin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Validate that a client-consumed redirect URL (from headers or Flight payload)
+ * targets the same origin as the current page. Prevents open-redirect attacks
+ * via crafted responses.
+ *
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
+ * the identical same-origin contract. Adds the client-side `console.error` on a
+ * block; the resolver itself stays pure.
+ *
+ * @returns The canonical (normalized) URL string on success, or null if blocked.
+ */
+export declare function validateRedirectOrigin(url: string, currentOrigin: string): string | null;
+/**
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
+ * the client is about to hard-navigate to via `window.location.assign()`.
+ *
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
+ * identical contract: `external` allows an off-origin target but only an
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
+ * navigation. Adds the client-side `console.error` on a block; the resolver
+ * itself stays pure.
+ *
+ * @returns The normalized URL string on success, or null if blocked.
+ */
+export declare function validateExternalRedirect(url: string, currentOrigin: string): string | null;

package/dist/types/build/collect-fallback-refs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export declare function collectFallbackClientRefs(boundary: unknown, report: (refKey: string) => void): void;

package/dist/types/build/generate-manifest.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Build-time manifest generation for @rangojs/router
+ *
+ * Extracts the prefix tree and route manifest from UrlPatterns at build time.
+ * This enables:
+ * - Pre-computed prefix tree for fast short-circuit checks
+ * - Complete route manifest for href() without runtime evaluation
+ * - Support for nested includes
+ */
+import type { UrlPatterns } from "../urls.js";
+/**
+ * Node in the prefix tree
+ */
+export interface PrefixTreeNode {
+    /** The static prefix for this node */
+    staticPrefix: string;
+    /** The full URL prefix (including parent prefixes) */
+    fullPrefix: string;
+    /** Name prefix for routes in this include */
+    namePrefix?: string;
+    /** Child nodes (nested includes) */
+    children: Record<string, PrefixTreeNode>;
+    /** Route names defined directly in this include (not in children) */
+    routes: string[];
+}
+/**
+ * Generated manifest containing prefix tree and route mappings
+ */
+export interface GeneratedManifest {
+    /** Nested prefix tree for short-circuit optimization */
+    prefixTree: Record<string, PrefixTreeNode>;
+    /** Complete route name → pattern mapping for href() */
+    routeManifest: Record<string, string>;
+    /** Route name → trailing slash mode for trie redirect handling */
+    routeTrailingSlash?: Record<string, string>;
+    /** Route names using Prerender (for dev-mode Node.js delegation) */
+    prerenderRoutes?: string[];
+    /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
+    passthroughRoutes?: string[];
+    /** Route name → response type for non-RSC routes */
+    responseTypeRoutes?: Record<string, string>;
+    /** Route name -> search schema descriptor for typed URL helpers */
+    routeSearchSchemas?: Record<string, Record<string, string>>;
+}
+/**
+ * Internal manifest result including build-pipeline-only fields.
+ * Not part of the public API — use generateManifest() for the public surface.
+ */
+export interface FullManifest extends GeneratedManifest {
+    _prerenderDefs?: Record<string, any>;
+}
+/**
+ * Generate manifest from UrlPatterns (public API).
+ *
+ * Returns only the public GeneratedManifest fields. Internal build pipeline
+ * consumers that need _prerenderDefs should use generateManifestFull() instead.
+ *
+ * @example
+ * ```typescript
+ * import { generateManifest } from "@rangojs/router/build";
+ * import { urlpatterns } from "./urls";
+ *
+ * // Async: awaits async include() providers (`() => import("./routes")`).
+ * const manifest = await generateManifest(urlpatterns);
+ * // Write to file for runtime use
+ * fs.writeFileSync(
+ *   "src/generated/route-manifest.json",
+ *   JSON.stringify(manifest, null, 2)
+ * );
+ * ```
+ */
+export declare function generateManifest<TEnv>(urlpatterns: UrlPatterns<TEnv, any>, mountIndex?: number): Promise<GeneratedManifest>;
+/**
+ * Generate manifest with internal build-pipeline fields.
+ *
+ * Used by the Vite plugin (discover-routers via dynamic import through
+ * @rangojs/router/build), manifest-init (direct import), and trie
+ * building. Not intended for external use.
+ */
+export declare function generateManifestFull<TEnv>(urlpatterns: UrlPatterns<TEnv, any>, mountIndex?: number, options?: {
+    urlPrefix?: string;
+    /**
+     * Owning router id. Threaded into the evaluation store so path() scopes
+     * its search-schema/root-scope registrations per router — same-named
+     * routes in different routers must not clobber each other.
+     */
+    routerId?: string;
+    /**
+     * Called once per `"use client"` component registered as an
+     * errorBoundary/notFoundBoundary fallback, with its client-reference key
+     * (`$$id`). Lets the build collect fallback module ids for dedicated
+     * chunking without exposing the otherwise-discarded EntryData tree. The
+     * EntryData map built below is local; this is the only seam that surfaces it.
+     */
+    collectClientFallbackRef?: (refKey: string) => void;
+}): Promise<FullManifest>;
+/**
+ * Generate TypeScript code for the manifest
+ *
+ * @example
+ * ```typescript
+ * const code = await generateManifestCode(urlpatterns);
+ * fs.writeFileSync("src/generated/route-manifest.ts", code);
+ * ```
+ */
+export declare function generateManifestCode<TEnv>(urlpatterns: UrlPatterns<TEnv, any>): Promise<string>;

package/dist/types/build/generate-route-types.d.ts

@@ -0,0 +1,8 @@
+export { extractParamsFromPattern, formatRouteEntry, } from "./route-types/param-extraction.js";
+export { extractRoutesFromSource } from "./route-types/ast-route-extraction.js";
+export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route-types/codegen.js";
+export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, } from "./route-types/scan-filter.js";
+export { writePerModuleRouteTypes, writePerModuleRouteTypesForFile, } from "./route-types/per-module-writer.js";
+export { type UnresolvableReason, type UnresolvableInclude, extractIncludesWithDiagnostics, } from "./route-types/include-resolution.js";
+export { extractUrlsFromRouter, extractBasenameFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
+export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/dist/types/build/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Build-time utilities for @rangojs/router
+ *
+ * Note: Route manifest is automatically generated at runtime on first request.
+ * These build-time utilities are only needed for advanced use cases like
+ * custom tooling or pre-generating manifests.
+ *
+ * @example Generate manifest programmatically (for custom tooling)
+ * ```typescript
+ * import { generateManifest } from "@rangojs/router/build";
+ * import { urlpatterns } from "./urls";
+ *
+ * // Async: generateManifest awaits any async include() providers
+ * // (`() => import("./routes")`) so the split groups appear in the manifest.
+ * const manifest = await generateManifest(urlpatterns);
+ * console.log(manifest.routeManifest); // { home: "/", about: "/about", ... }
+ * ```
+ */
+export { generateManifest, generateManifestFull, generateManifestCode, type GeneratedManifest, } from "./generate-manifest.js";
+export { writePerModuleRouteTypes, extractRoutesFromSource, generatePerModuleTypesSource, createScanFilter, type ScanFilter, } from "./generate-route-types.js";
+export { hashParams } from "../prerender/param-hash.js";

package/dist/types/build/merge-full-manifests.d.ts

@@ -0,0 +1,3 @@
+import type { FullManifest } from "./generate-manifest.js";
+/** Merge ordered per-mount manifests without mutating any input manifest. */
+export declare function mergeFullManifests(manifests: readonly FullManifest[]): FullManifest;

package/dist/types/build/prefix-tree-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure prefix-tree walks shared by the build/discovery layer and the runtime
+ * trie builder. Kept in `build/` (not `vite/utils`) so runtime code
+ * (rsc/manifest-init via build/route-trie) can consume them without importing
+ * from the vite layer. `vite/utils/manifest-utils` re-exports them so existing
+ * vite-side imports stay unchanged.
+ */
+/**
+ * Flatten prefix tree leaf nodes into precomputed route entries.
+ * Leaf nodes have no children (no nested includes), so their routes can be
+ * used directly by evaluateLazyEntry() without running the handler.
+ * Non-leaf nodes are skipped because they have nested lazy includes that
+ * require the handler to run for discovery.
+ *
+ * A leaf is also skipped when its staticPrefix collides with an ancestor
+ * include node's staticPrefix. That happens when a dynamic param collapses the
+ * staticPrefix of nested includes onto the parent's (e.g. `/m/:id/edit` -> sp
+ * `/m`): precomputing such a leaf under the collapsed prefix would let the
+ * ancestor's lazy entry claim a route it cannot register (the route is behind
+ * further nested lazy includes), producing a RouteNotFoundError at request time
+ * (issue #506). Those routes are resolved via the handler chain instead.
+ */
+export declare function flattenLeafEntries(prefixTree: Record<string, any>, routeManifest: Record<string, string>, result: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}>): void;
+/**
+ * Build the staticPrefix -> routes lookup the runtime shortcut consumes from a
+ * flat precomputed-entry array.
+ *
+ * A staticPrefix owned by MORE THAN ONE leaf include cannot be collapsed to a
+ * single routes object: `new Map(entries.map(e => [e.staticPrefix, e.routes]))`
+ * is last-wins, so one include's routes are silently dropped and mis-assigned
+ * to whichever entry evaluates first. Two distinct includes legitimately share a
+ * staticPrefix when a dynamic param collapses their literal prefixes onto the
+ * same value (e.g. `include("/shop/:cat", ...)` and a nested
+ * `include("/shop/:brand", ...)` both extract "/shop/"). Merging them is also
+ * wrong — assigning the merged set to the first matching entry makes findMatch
+ * pick the wrong handler for routes belonging to the other include, which then
+ * fails its `Store.manifest.has(routeKey)` invariant at render (500 on a valid
+ * route, dev/prod identical).
+ *
+ * So any shared staticPrefix is OMITTED from the shortcut entirely. Those
+ * includes fall through to the handler path in evaluateLazyEntry(), which is the
+ * ground truth (identical to pre-precomputed behavior). The shortcut is purely an
+ * optimization, so dropping a prefix can only cost a handler run, never change a
+ * result.
+ */
+export declare function buildPrecomputedByPrefix(entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+}>): Map<string, Record<string, string>>;
+/**
+ * Walk prefix tree to map each route name to its scope's staticPrefix.
+ */
+export declare function buildRouteToStaticPrefix(prefixTree: Record<string, any>, result: Record<string, string>): void;

package/dist/types/build/route-trie.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build-time Route Trie Construction
+ *
+ * Adapts generated manifests to the runtime-owned route trie builder.
+ */
+import { buildRouteTrie, type TrieNode } from "../router/route-trie-builder.js";
+import type { FullManifest } from "./generate-manifest.js";
+export { buildRouteTrie };
+export type { NegotiateVariant, TrieLeaf, TrieNode, } from "../router/route-trie-builder.js";
+/**
+ * Build a per-router trie from a generated manifest. This is the single
+ * construction path shared by build/discovery (discover-routers.ts, serialized
+ * into the production chunk) and the dev/HMR runtime rebuild
+ * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
+ * runtime trie and the production serialized trie are byte-for-byte identical.
+ *
+ * Returns null when the manifest has no routes, matching the prior guard at
+ * both call sites.
+ */
+export declare function buildPerRouterTrie(manifest: FullManifest): TrieNode | null;

package/dist/types/build/route-types/ast-helpers.d.ts

@@ -0,0 +1,3 @@
+import ts from "typescript";
+export declare function getStringValue(node: ts.Node): string | null;
+export declare function extractObjectStringProperties(node: ts.ObjectLiteralExpression): Record<string, string>;

package/dist/types/build/route-types/ast-route-extraction.d.ts

@@ -0,0 +1,13 @@
+import ts from "typescript";
+/**
+ * Extract route definitions from source code by walking the TypeScript AST.
+ * Finds path() and path.json(), path.md(), etc. call expressions and extracts
+ * the pattern, name, params, and optional search schema from each.
+ * Skips unnamed paths (no { name: "..." }).
+ */
+export declare function extractRoutesFromSource(code: string, sourceFileArg?: ts.SourceFile): Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+}>;

package/dist/types/build/route-types/codegen.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate a per-module types file from extracted routes.
+ * Output has zero imports, preventing circular references.
+ */
+export declare function generatePerModuleTypesSource(routes: Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+}>): string;
+/**
+ * Generates a .ts file that augments Rango.GeneratedRouteMap
+ * with route name -> pattern mappings. This enables Handler<"routeName">
+ * without circular references since the file has no imports from the app.
+ */
+export declare function generateRouteTypesSource(routeManifest: Record<string, string>, searchSchemas?: Record<string, Record<string, string>>): string;

package/dist/types/build/route-types/include-resolution.d.ts

@@ -0,0 +1,74 @@
+import ts from "typescript";
+export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found";
+export interface UnresolvableInclude {
+    pathPrefix: string;
+    namePrefix: string | null;
+    reason: UnresolvableReason;
+    sourceFile: string;
+    detail: string;
+}
+/**
+ * Per-scan memo shared across the include-resolution recursion. Keys are
+ * absolute file paths; values cache the readFileSync result and the
+ * ts.SourceFile parsed from the FULL file source. A separate blockSources map
+ * caches parses of extracted sub-blocks (urls() call text), keyed by the exact
+ * block string, so the two extractors (routes + includes) for the same block
+ * share a single parse.
+ *
+ * The memo is purely a performance accelerator: same input -> same parse, so
+ * generated output is identical to the un-memoized path. A fresh memo is
+ * created per top-level scan entry, so stale file edits between scans are never
+ * served.
+ */
+export interface ScanMemo {
+    files: Map<string, string>;
+    blockSourceFiles: Map<string, ts.SourceFile>;
+}
+export declare function createScanMemo(): ScanMemo;
+/**
+ * Extract include() calls with diagnostics for unresolvable ones.
+ * Returns both resolved includes (identifier second args) and unresolvable
+ * includes (factory calls, etc.) with reasons.
+ */
+export declare function extractIncludesWithDiagnostics(code: string, sourceFileArg?: ts.SourceFile): {
+    resolved: Array<{
+        pathPrefix: string;
+        variableName?: string;
+        moduleSpecifier?: string;
+        namePrefix: string | null;
+    }>;
+    unresolvable: Array<{
+        pathPrefix: string;
+        namePrefix: string | null;
+        reason: UnresolvableReason;
+        detail: string;
+    }>;
+};
+/**
+ * Find the import statement for a local variable name.
+ * Returns the import specifier and the exported name from the source module.
+ */
+export declare function resolveImportedVariable(code: string, localName: string): {
+    specifier: string;
+    exportedName: string;
+} | null;
+/**
+ * Resolve an import specifier relative to the importing file.
+ * Strips .js/.mjs/.jsx extensions and tries .ts/.tsx/.js/.jsx candidates.
+ */
+export declare function resolveImportPath(importSpec: string, fromFile: string): string | null;
+/**
+ * Build route map and search schemas together.
+ * Internal helper used by the include resolution path.
+ *
+ * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
+ *   builder function). When provided, variableName is ignored and the block
+ *   is parsed directly for path()/include() calls.
+ * @param memo - Per-scan readFileSync/parse memo. A fresh one is created at the
+ *   top-level entry and threaded through the recursion so each file is read and
+ *   parsed once per scan. Behavior-preserving (same input -> same output).
+ */
+export declare function buildCombinedRouteMapWithSearch(filePath: string, variableName?: string, visited?: Set<string>, diagnosticsOut?: UnresolvableInclude[], inlineBlock?: string, memo?: ScanMemo): {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+};

package/dist/types/build/route-types/param-extraction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extract typed params from a route pattern string.
+ * Matches `:paramName` and `:paramName?` (optional).
+ * Custom regex constraints like `:id(\d+)` are ignored for type purposes.
+ */
+export declare function extractParamsFromPattern(pattern: string): Record<string, string> | undefined;
+/**
+ * Format a single route entry for codegen output.
+ * Routes without search remain plain strings (params are extracted from
+ * the pattern at the type level by ExtractParams).
+ * Routes with search become objects with path and search fields.
+ */
+export declare function formatRouteEntry(key: string, pattern: string, _params?: Record<string, string>, search?: Record<string, string>): string;

package/dist/types/build/route-types/per-module-writer.d.ts

@@ -0,0 +1,20 @@
+import type { ScanFilter } from "./scan-filter.js";
+/**
+ * Generate per-module route type files by statically parsing url module source.
+ * Scans for files containing `urls(` or `clientUrls(` and writes a sibling
+ * `.gen.ts` with the extracted route name/pattern pairs. Only writes when
+ * content has changed.
+ */
+export declare function writePerModuleRouteTypes(root: string, filter?: ScanFilter): void;
+/**
+ * Find all variable names assigned to urls() or clientUrls() calls in source.
+ * e.g. `export const patterns = urls(...)` -> ["patterns"]
+ */
+export declare function findUrlsVariableNames(code: string): string[];
+/**
+ * Generate per-module route types for a single url module file.
+ * Follows include() calls recursively to produce the full route tree.
+ * No-ops if the file doesn't contain `urls(`/`clientUrls(` or has no named
+ * routes.
+ */
+export declare function writePerModuleRouteTypesForFile(filePath: string): void;

package/dist/types/build/route-types/router-processing.d.ts

@@ -0,0 +1,81 @@
+import type { ScanFilter } from "./scan-filter.js";
+import { type UnresolvableInclude } from "./include-resolution.js";
+export declare function findNestedRouterConflict(routerFiles: string[]): {
+    ancestor: string;
+    nested: string;
+} | null;
+export declare function formatNestedRouterConflictError(conflict: {
+    ancestor: string;
+    nested: string;
+}, prefix?: string): string;
+/**
+ * Result of extracting URL patterns from a router file.
+ * - "variable": a named variable reference (e.g., `.routes(patterns)` or `urls: patterns`)
+ * - "inline": an inline builder function (e.g., `.routes(({ path }) => [...])` or `urls: ({ path }) => [...]`)
+ */
+export type UrlsExtractionResult = {
+    kind: "variable";
+    name: string;
+} | {
+    kind: "inline";
+    block: string;
+};
+/**
+ * Extract the url patterns from a router file using AST.
+ * Detects four patterns:
+ *   1. createRouter(...).routes(variableName)
+ *   2. createRouter({ urls: variableName, ... })
+ *   3. createRouter(...).routes(({ path, ... }) => [...])
+ *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ * Returns either a variable name or an inline code block.
+ */
+export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;
+/**
+ * Extract the `basename` string literal from createRouter({ basename: "..." }).
+ * Returns the basename value or undefined if not present.
+ */
+export declare function extractBasenameFromRouter(code: string): string | undefined;
+export declare function genFileTsPath(sourceFile: string): string;
+export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
+/**
+ * Resolve routes and search schemas from every direct mount in a createRouter
+ * chain. Registrations are merged in runtime order, with later mounts winning.
+ */
+export declare function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+};
+/**
+ * Walk the full include tree starting from a router file and detect
+ * all includes that the static parser cannot resolve.
+ * Returns an array of diagnostics; empty means fully resolvable.
+ */
+export declare function detectUnresolvableIncludes(routerFilePath: string): UnresolvableInclude[];
+/**
+ * Walk the include tree for a standalone urls() module file and detect
+ * all unresolvable includes. Mirrors detectUnresolvableIncludes() but
+ * operates on urls() variable declarations instead of going through
+ * createRouter().
+ */
+export declare function detectUnresolvableIncludesForUrlsFile(filePath: string): UnresolvableInclude[];
+/**
+ * Scan for files containing createRouter() and return their paths.
+ * Call once at startup; the result can be reused on subsequent watcher triggers.
+ */
+export declare function findRouterFiles(root: string, filter?: ScanFilter): string[];
+/**
+ * Scan for files containing createHostRouter() and return their paths. Unlike
+ * findRouterFiles, this does NOT stop at the first router-root directory -- a host
+ * entry typically sits above the sub-app router roots, so the whole tree is scanned.
+ */
+export declare function findHostRouterFiles(root: string, filter?: ScanFilter): string[];
+/**
+ * Write named-routes.gen.ts files from static source parsing.
+ * Dev-only: provides initial .gen.ts files for IDE types before runtime
+ * discovery runs. Must NOT be called during production builds -- runtime
+ * discovery in buildStart produces the definitive file.
+ */
+export declare function writeCombinedRouteTypes(root: string, knownRouterFiles?: string[], opts?: {
+    preserveIfLarger?: boolean;
+    onWrite?: (outPath: string, content: string) => void;
+}): void;

package/dist/types/build/route-types/scan-filter.d.ts

@@ -0,0 +1,17 @@
+/** Default exclude patterns for route type scanning. */
+export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
+export type ScanFilter = (absolutePath: string) => boolean;
+/**
+ * Compile include/exclude glob patterns into a single predicate.
+ * Paths are made root-relative before matching.
+ * Returns undefined when no filtering is needed (no include, default exclude).
+ */
+export declare function createScanFilter(root: string, opts: {
+    include?: string[];
+    exclude?: string[];
+}): ScanFilter | undefined;
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping node_modules
+ * and .gen. files.
+ */
+export declare function findTsFiles(dir: string, filter?: ScanFilter): string[];

package/dist/types/build/route-types/source-scan.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export declare function firstCodeMatchIndex(code: string, pattern: RegExp): number;
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export declare function codeMatchIndices(code: string, pattern: RegExp): number[];

package/dist/types/build/runtime-discovery.d.ts

@@ -0,0 +1,24 @@
+export interface RuntimeDiscoveryOptions {
+    /** Project root directory (where package.json / node_modules live). */
+    root: string;
+    /** Path to vite.config.ts. Auto-detected from root if omitted. */
+    configFile?: string;
+    /** Absolute path to the router entry file. */
+    entry: string;
+    /** Override resolve.alias (skips loading from vite config when provided). */
+    resolveAlias?: Record<string, string>;
+}
+/**
+ * Standalone Vite-based route discovery for the CLI.
+ * Creates a temporary Vite server with the RSC plugin, imports the entry via
+ * the module runner, reads the RouterRegistry, generates manifests, and writes
+ * named-routes.gen.ts files.
+ *
+ * This mirrors the logic in the Vite plugin's discoverRouters() + writeRouteTypesFiles()
+ * but without coupling to plugin closure state.
+ */
+export declare function discoverAndWriteRouteTypes(opts: RuntimeDiscoveryOptions): Promise<{
+    routerCount: number;
+    routeCount: number;
+    outputFiles: string[];
+}>;

package/dist/types/cache/background-task.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Background Task Runner
+ *
+ * Unified helper for scheduling async work via waitUntil.
+ * When waitUntil is unavailable, falls back to blocking or skipping.
+ */
+interface WaitUntilHost {
+    waitUntil?: (fn: () => Promise<void>) => void;
+}
+/**
+ * Schedule an async task in the background via waitUntil.
+ *
+ * @param host - Object with optional waitUntil (request context or similar)
+ * @param task - Async function to execute
+ * @param blockWhenNoWaitUntil - If true, awaits the task when waitUntil is
+ *   unavailable (e.g., Node.js dev server). If false (default), the task
+ *   is silently skipped when waitUntil is unavailable.
+ * @returns A promise when blocking fallback is used, void otherwise.
+ */
+export declare function runBackground(host: WaitUntilHost | null | undefined, task: () => Promise<void>, blockWhenNoWaitUntil?: boolean): Promise<void> | void;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+    _reportBackgroundError?: (error: unknown, category: CacheErrorCategory) => void;
+}
+export type CacheErrorCategory = 
+/** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+"cache-read"
+/** A write failed. Degrade to a no-op (entry simply not cached). */
+ | "cache-write"
+/** A delete/eviction failed. Best-effort. */
+ | "cache-delete"
+/**
+ * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+ * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+ * evicted so subsequent reads do not keep failing on it. Distinct from
+ * cache-read so consumers can tell corruption from a transient outage.
+ */
+ | "cache-corrupt"
+/** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+ | "cache-invalidate"
+/**
+ * A background stale-while-revalidate refresh failed (the `"use cache"`
+ * read-through path). The stale value was already served; the refresh that
+ * would have replaced it errored.
+ */
+ | "stale-revalidation";
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export declare function reportCacheError(error: unknown, category: CacheErrorCategory, label: string, ctx?: CacheErrorReporter): void;
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export declare function reportingAsync(task: () => Promise<unknown>, category: CacheErrorCategory, label: string, ctx?: CacheErrorReporter): Promise<void>;