@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/vite/debug.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export declare const NS: {
+    readonly config: "rango:config";
+    readonly discovery: "rango:discovery";
+    readonly routes: "rango:routes";
+    readonly prerender: "rango:prerender";
+    readonly build: "rango:build";
+    readonly dev: "rango:dev";
+    readonly transform: "rango:transform";
+    readonly chunks: "rango:chunks";
+};
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+export declare function createRangoDebugger(namespace: string): Debugger | undefined;
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export declare function timed<T>(debug: Debugger | undefined, label: string, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export declare function timedSync<T>(debug: Debugger | undefined, label: string, fn: () => T): T;
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+    record(file: string, ms: number): void;
+    /**
+     * Convenience: time a sync or async block and record it. Propagates
+     * throws; records regardless of outcome. Returns the function's result.
+     */
+    time<T>(file: string, fn: () => T): T;
+    time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+    flush(): void;
+}
+export declare function createCounter(debug: Debugger | undefined, label: string): Counter | undefined;

package/dist/types/vite/discovery/bundle-postprocess.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bundle Post-Processing
+ *
+ * Handles handler code eviction from prerender/static chunks and
+ * injection of collected prerender/static data into the RSC entry bundle.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Post-process the RSC bundle: evict handler code and inject
+ * prerender/static data as importable asset modules.
+ */
+export declare function postprocessBundle(state: DiscoveryState): void;

package/dist/types/vite/discovery/dev-prerender-cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Dev prerender result cache — memoizes /__rsc_prerender responses between
+ * HMR edits (issue #654).
+ *
+ * Freshness invariant (why identity keying is correct): the endpoint
+ * re-imports the user's entry module through a Vite module runner on every
+ * request. When ANY module in the entry → router → urls → handler chain was
+ * invalidated (file edit propagates up the importer graph), that import
+ * re-executes the entry, `createRouter()` re-runs, and `RouterRegistry.set`
+ * (router.ts) replaces the router instance with a NEW object. When nothing
+ * was invalidated, the import is a module-cache hit and the instance is the
+ * SAME object. Router-instance identity therefore IS the HMR generation:
+ * keying the cache on it gives "serve cached until an edit invalidates the
+ * chain" without any watcher bookkeeping, and the WeakMap lets every stale
+ * generation's bucket be garbage-collected the moment the registry drops
+ * the old instance.
+ *
+ * Staleness envelope: a cached body can only go stale through NON-module
+ * inputs (a getParams() reading a database, fs content outside the module
+ * graph). Production freezes those at build time, so serving them frozen
+ * between edits makes dev MORE faithful to production, not less — the
+ * pre-#654 behavior of re-rendering per request was the anomaly.
+ */
+import type { SerializedSegmentData } from "../../cache/types.js";
+/** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
+export interface DevPrerenderMatchPayloadSource {
+    segments: SerializedSegmentData[];
+    handles: string;
+    interceptSegments?: SerializedSegmentData[];
+    interceptHandles?: string;
+}
+/** Serialized response bodies for the two endpoint variants of one render. */
+export interface DevPrerenderPayloadBodies {
+    /** `intercept != 1` response: the route's own segments + handles. */
+    main: string;
+    /**
+     * `intercept=1` response: main + intercept segments with the MERGED handle
+     * string. Falls back to `main` byte-for-byte when the route has no
+     * intercept segments — mirroring the endpoint's historical behavior.
+     */
+    intercept: string;
+}
+export interface DevPrerenderCache {
+    get(router: object, key: string): string | undefined;
+    set(router: object, key: string, body: string): void;
+}
+/**
+ * Derive both variant bodies from one matchForPrerender result, so a single
+ * render warms the main AND intercept cache keys (matchForPrerender computes
+ * intercept segments unconditionally either way — see prerender-match.ts
+ * step 14).
+ */
+export declare function payloadBodiesFromResult(result: DevPrerenderMatchPayloadSource): DevPrerenderPayloadBodies;
+/**
+ * Cache key for one endpoint request shape. `pathname` and `routeName` come
+ * straight from the query; `passthrough` selects the getParams-checked match
+ * path; `intercept` selects which variant body is served. All four dimensions
+ * change the response, so all four are in the key.
+ */
+export declare function devPrerenderCacheKey(pathname: string, opts: {
+    intercept: boolean;
+    passthrough: boolean;
+    routeName: string | null;
+}): string;
+export declare function createDevPrerenderCache(maxEntriesPerRouter?: number): DevPrerenderCache;

package/dist/types/vite/discovery/discover-routers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Router Discovery
+ *
+ * Core discovery logic: imports the user's entry file via the RSC
+ * environment's module runner, generates manifests for each discovered
+ * router, and builds route tries for O(path_length) matching.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Import the user's entry via RSC runner, generate manifests for each
+ * discovered router, build route tries, and optionally run prerender
+ * expansion and static handler rendering (build mode only).
+ *
+ * Returns the imported `@rangojs/router/server` module so the caller
+ * can access the RouterRegistry and manifest setters.
+ */
+export declare function discoverRouters(state: DiscoveryState, rscEnv: any): Promise<any>;

package/dist/types/vite/discovery/discovery-errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Router discovery error aggregation.
+ *
+ * During host-router discovery the lazy mounts registered by a host router are
+ * invoked to trigger each sub-app's createRouter() registration. Some mount
+ * failures are expected in the temporary discovery server context (a sub-app may
+ * reference runtime-only bindings), so each is invoked defensively and its error
+ * is collected rather than thrown.
+ *
+ * Previously these errors were discarded with an empty `catch {}`. When a real
+ * failure - typically a sub-app whose router module fails to import - left the
+ * registry empty, discovery reported the misleading "No routers found" message
+ * with no trace of the underlying cause. The collected errors are now surfaced
+ * via the `DiscoveryError` thrown at the end of discovery (issue #499).
+ *
+ * Which entries to invoke is taken from the consumer's declared intent, not
+ * inferred from the function's shape. A host route is registered either with
+ * `.map((request) => Response)` (an inline request handler, `kind: "handler"`)
+ * or `.lazy(() => import("./sub-app"))` (a lazy mount, `kind: "lazy"`). Only
+ * `kind === "lazy"` entries are invoked here; inline handlers are never invoked
+ * during discovery (they need a Request and register no routers). Because a lazy
+ * entry is known to be a module loader, ANY failure it produces - a synchronous
+ * throw or a rejected promise - is a genuine discovery failure and is collected.
+ */
+/** An error caught (and previously swallowed) while resolving host routers. */
+export interface CaughtDiscoveryError {
+    /** Human-readable description of where the error was caught. */
+    context: string;
+    /** The caught value (an Error or otherwise). */
+    error: unknown;
+}
+/**
+ * Minimal shape of a host registry entry needed for mount resolution.
+ * Mirrors the runtime HostRouterRegistry value without coupling to its type.
+ */
+interface HostRegistryRoute {
+    handler?: unknown;
+    kind?: string;
+}
+interface HostRegistryEntry {
+    routes: HostRegistryRoute[];
+    fallback?: HostRegistryRoute | null;
+}
+/**
+ * Invoke every lazy mount in the host registry to trigger sub-app
+ * createRouter() registration, collecting (not throwing) any failures.
+ *
+ * Only `.lazy()` entries are invoked; `.map()` inline request handlers are
+ * skipped (they need a Request and register no routers). Failures are returned
+ * rather than thrown because some mounts legitimately fail in the temporary
+ * discovery server context; the caller decides whether the failures matter,
+ * which is only when discovery finds no routers at all.
+ */
+export declare function resolveHostRouterHandlers(hostRegistry: Map<string, HostRegistryEntry>): Promise<CaughtDiscoveryError[]>;
+/**
+ * Build the terminal "No routers found" message, appending any errors caught
+ * during host-router discovery so the real cause is visible.
+ *
+ * The aggregated errors are inlined into the message (in addition to being
+ * attached via `cause` on `DiscoveryError`) so they survive every caller: the
+ * dev/HMR paths log `err.message`, and the build path re-throws using
+ * `err.stack`, which begins with the message. None of those callers traverse
+ * `cause`, so the message must carry the detail. Each error includes its stack
+ * when available.
+ */
+export declare function formatNoRoutersError(entryPath: string | undefined, errors: CaughtDiscoveryError[]): string;
+/**
+ * Thrown when router discovery completes without finding any routers.
+ *
+ * Carries the entry path and the individual failures caught while resolving
+ * host-router lazy handlers. The formatted detail is embedded in `message` (for
+ * callers that log `err.message`/`err.stack`) and the underlying error(s) are
+ * also attached via `cause` (a single failure directly, multiple wrapped in an
+ * `AggregateError`) for cause-aware tooling such as the Vite error overlay.
+ */
+export declare class DiscoveryError extends Error {
+    /** The entry file that was imported before discovery gave up. */
+    readonly entryPath: string | undefined;
+    /** Individual failures caught while resolving host-router handlers. */
+    readonly caught: CaughtDiscoveryError[];
+    constructor(entryPath: string | undefined, caught: CaughtDiscoveryError[]);
+}
+/** How the dev caller should surface a discovery failure. */
+export interface DiscoveryFailureReport {
+    level: "error" | "warn";
+    message: string;
+}
+/**
+ * Decide how to surface a dev-boot discovery failure in the terminal.
+ *
+ * The bare "no routers found" case (a DiscoveryError with no caught host-handler
+ * failures) is ambiguous. It is either:
+ *   - a genuine misconfiguration — the entry never calls createRouter(), or the
+ *     configured entry path is wrong; or
+ *   - a transient artifact of a Vite dependency re-optimization racing with boot
+ *     discovery (a module read before the entry import resolves to the
+ *     pre-optimize copy of the runner graph while createRouter() populated the
+ *     post-optimize copy — see router-discovery.ts).
+ *
+ * We can only tell them apart when the caller observed the dep optimizer's
+ * `browserHash` change across the discovery attempt (`reoptimizeObserved`): a
+ * reload-causing re-optimization landed mid-flight, so the empty read was
+ * transient and the app self-heals per-request (handler.ts builds the trie from
+ * the router's live urlpatterns) with discovery re-running on the next boot.
+ *
+ * A DiscoveryError that DOES carry caught host-handler failures already embeds
+ * the real cause in its message, and any non-DiscoveryError is a hard failure;
+ * both stay loud with full detail.
+ */
+export declare function describeDiscoveryFailure(err: unknown, opts?: {
+    reoptimizeObserved?: boolean;
+}): DiscoveryFailureReport;
+export {};

package/dist/types/vite/discovery/gate-state.d.ts

@@ -0,0 +1,79 @@
+import type { Debugger } from "../debug.js";
+/**
+ * Manifest-readiness gate + rediscovery scheduler.
+ *
+ * Owns the four pieces of state that cooperate to keep
+ * `s.discoveryDone` (the promise the manifest virtual module's `load()`
+ * hook awaits) consistent across HMR fan-out:
+ *
+ *   - **gatePending**: a Promise has been issued and not yet resolved.
+ *     Workerd's manifest virtual module load() is blocked on it.
+ *   - **inProgress**: a refresh's work callback is currently executing.
+ *   - **queued**: a refresh was attempted while one was already in
+ *     flight; the active run consumes this in its `finally` and
+ *     recurses.
+ *   - **pendingEvents**: a route-file event has been received (gate
+ *     already reset) but the corresponding refresh's work hasn't started
+ *     yet — i.e. the debounce hasn't fired. Set in `noteRouteEvent`,
+ *     cleared at the start of each refresh cycle. Refresh's finally MUST
+ *     hold the gate if this is true even when `queued` is false,
+ *     otherwise an event whose debounce fires AFTER the active refresh
+ *     completes (the "tail-race" window) would observe a resolved gate.
+ *
+ * The HMR-event flow (cloudflare-stress repro):
+ *
+ *   t=0    Touch 1  → noteRouteEvent  → pendingEvents=true, beginGate
+ *                                      (gate1 pending)
+ *          → debounce 100ms
+ *   t=100  runRefreshCycle(work)      → clear pendingEvents, work starts
+ *   t=750  Touch 2  → noteRouteEvent  → pendingEvents=true (no-op gate)
+ *                                      → debounce fires at t=850
+ *   t=800  refresh A's finally        → queued=false, pendingEvents=true
+ *                                      → HOLD gate (don't resolve)
+ *   t=850  runRefreshCycle (debounce) → clear pendingEvents, work starts
+ *   t=1500 refresh B's finally        → queued=false, pendingEvents=false
+ *                                      → resolveGate (gate1 resolves)
+ *
+ * @internal Exported only for unit tests.
+ */
+export interface DiscoveryGate {
+    /**
+     * Reset the gate to a fresh pending Promise via `s.discoveryDone`.
+     * No-op when a gate is already pending — file watchers can fire
+     * multiple events for one save, and replacing the resolver would
+     * orphan the original promise (workerd's manifest load() would hang).
+     */
+    beginGate(): void;
+    /**
+     * Resolve the current pending gate. No-op when no gate is pending.
+     * Called at the tail of the last refresh cycle in a burst.
+     */
+    resolveGate(): void;
+    /**
+     * Record that a route-file event has arrived. Sets `pendingEvents`
+     * and begins the gate. Idempotent for both flags.
+     */
+    noteRouteEvent(): void;
+    /**
+     * Run one refresh cycle, managing queue + pending state around it.
+     * If a cycle is already in flight, sets `queued=true` and returns.
+     * Otherwise clears `pendingEvents`, runs `work`, and in `finally`:
+     *
+     *   - queued        → recurse, gate stays pending
+     *   - pendingEvents → hold gate (next debounced cycle resolves)
+     *   - neither       → resolveGate
+     */
+    runRefreshCycle(work: () => Promise<void>): Promise<void>;
+    /** Snapshot of internal state. Test-only. */
+    readonly state: () => Readonly<{
+        gatePending: boolean;
+        inProgress: boolean;
+        queued: boolean;
+        pendingEvents: boolean;
+    }>;
+}
+/** State container the gate writes `discoveryDone` into. */
+export interface GateOwner {
+    discoveryDone: Promise<void> | null | undefined;
+}
+export declare function createDiscoveryGate(s: GateOwner, debug?: Debugger): DiscoveryGate;

package/dist/types/vite/discovery/prerender-collection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prerender Collection
+ *
+ * Expands prerender routes into concrete URLs and renders them at build
+ * time. Also handles Static handler rendering for segment-level static
+ * generation.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Expand prerender routes into concrete URLs and render them via the
+ * RSC runner. Stages asset modules and stores key-to-file entries in
+ * state.prerenderManifestEntries.
+ */
+export declare function expandPrerenderRoutes(state: DiscoveryState, rscEnv: any, registry: Map<string, any>, allManifests: Array<{
+    id: string;
+    manifest: any;
+}>): Promise<void>;
+/**
+ * Render Static handlers at build time. Each Static handler is called
+ * with a synthetic BuildContext and its output is RSC-serialized.
+ * Stages asset modules and stores handlerId-to-file entries in
+ * state.staticManifestEntries.
+ */
+export declare function renderStaticHandlers(state: DiscoveryState, rscEnv: any, registry: Map<string, any>): Promise<void>;

package/dist/types/vite/discovery/route-types-writer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Route Types Writer
+ *
+ * Generates and writes TypeScript route type files (named-routes.gen.ts)
+ * from discovered router manifests and static source parsing.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Write combined route types for all router files.
+ * Only writes when content has changed to avoid triggering HMR loops.
+ */
+export declare function writeCombinedRouteTypesWithTracking(state: DiscoveryState, opts?: {
+    preserveIfLarger?: boolean;
+}): void;
+/**
+ * Write per-router route types files from runtime discovery data.
+ */
+export declare function writeRouteTypesFiles(state: DiscoveryState): void;
+/**
+ * Supplement gen files with route groups from runtime manifests that the
+ * static parser cannot resolve (factory calls like createDocsPatterns()).
+ * Only adds groups whose dot-prefix (e.g. "docs.") is entirely absent
+ * from the static output. Groups partially visible to the static parser
+ * are left alone so renames/removals propagate immediately without
+ * requiring a server restart.
+ *
+ * The runtime manifest (cachedManifest / perRouterManifestMap) is updated
+ * automatically: the virtual:rsc-router/routes-manifest module imports the
+ * gen file, so when we write new content here, Vite's HMR invalidates the
+ * virtual module and re-evaluates it on the next request.
+ */
+export declare function supplementGenFilesWithRuntimeRoutes(state: DiscoveryState): void;

package/dist/types/vite/discovery/self-gen-tracking.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Self-Generated File Tracking
+ *
+ * Tracks gen files recently written by the discovery plugin so the
+ * file watcher can distinguish self-triggered change events from
+ * manual edits.
+ */
+import type { DiscoveryState } from "./state.js";
+export declare function markSelfGenWrite(state: DiscoveryState, filePath: string, content: string): void;
+export declare function consumeSelfGenWrite(state: DiscoveryState, filePath: string): boolean;
+/**
+ * Non-consuming variant. Used by the `handleHotUpdate` plugin hook to
+ * suppress vite's HMR cascade for our own gen-file writes WITHOUT
+ * consuming the entry — `consumeSelfGenWrite` (called later from the
+ * chokidar `change` handler in `handleRouteFileChange`) still needs to
+ * see and consume the same entry to short-circuit our regen path.
+ *
+ * Both hooks fire for the same file change event:
+ *   - `handleHotUpdate` runs first (vite's HMR pipeline).
+ *   - chokidar `change` callback runs after (filesystem watcher).
+ */
+export declare function peekSelfGenWrite(state: DiscoveryState, filePath: string): boolean;

package/dist/types/vite/discovery/shell-prerender-phase.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Post-build PPR shell capture phase (producer B, issue #699).
+ *
+ * Runs from the buildApp post hook, AFTER every environment bundle is written
+ * — the shell prelude embeds built client asset URLs (the bootstrap entry),
+ * which do not exist during buildStart discovery. Reuses the buildStart temp
+ * server kept alive on DiscoveryState (its realm already has tries installed
+ * and routers registered), seeds an in-realm prerender store from the
+ * retained phase-A Flight payloads, and drives the shared capture core
+ * (prerender/build-shell-capture.ts) once per Prerender+ppr candidate. The
+ * SSR half is composed from the temp server's SSR environment runner with
+ * the BUILT client entry as bootstrap.
+ *
+ * Stored entries are staged as __ps-*.js asset modules under the RSC out
+ * dir with a lazy __shell-manifest.js (mirroring the prerender manifest);
+ * the runtime read-through (rsc/shell-build-manifest.ts) serves them on a
+ * shell-store MISS. A candidate whose capture is refused, produces no shell,
+ * or never consulted the prerender store is SKIPPED loudly — the route keeps
+ * producer A (runtime capture) semantics, never a wrong-lane bake.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Minimal builder surface the phase reads: resolved plugins (for the main
+ * build's version plugin) and per-environment outDirs.
+ */
+interface BuilderLike {
+    config?: {
+        base?: string;
+        plugins?: readonly unknown[];
+    };
+    environments?: Record<string, {
+        config?: {
+            build?: {
+                outDir?: string;
+            };
+        };
+    } | undefined>;
+}
+export declare function runShellPrerenderPhase(s: DiscoveryState, builder: BuilderLike | undefined): Promise<void>;
+export {};

package/dist/types/vite/discovery/state.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Discovery State
+ *
+ * Shared mutable state for the router discovery plugin.
+ * Created once by createRouterDiscoveryPlugin() and passed
+ * to all extracted helper functions.
+ */
+import type { ScanFilter } from "../../build/generate-route-types.js";
+export declare const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+export interface PluginOptions {
+    enableBuildPrerender?: boolean;
+    staticRouteTypesGeneration?: boolean;
+    routerPathRef?: {
+        path?: string;
+    };
+    /** Build-time env option from rango() config. */
+    buildEnv?: import("../plugin-types.js").BuildEnvOption;
+    /** Deployment preset (needed for buildEnv "auto" resolution). */
+    preset?: "node" | "cloudflare" | "vercel";
+    /**
+     * Route-discovery scan filter (glob include/exclude) from rango() config.
+     * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
+     */
+    discovery?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    /**
+     * What to do when a Prerender/Static render throws at build time, from
+     * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+     * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+     */
+    prerenderOnError?: "fail" | "warn";
+    /**
+     * Shared context the built-in clientChunks strategy reads. Discovery populates
+     * it (registered fallback hashes + single-router name) before the client build
+     * invokes the strategy. Present only when the built-in strategy is active
+     * (`clientChunks: true`/default); undefined for `false` or a custom function.
+     */
+    clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
+    /**
+     * rango({ headScripts }) — threaded so the dev temp server can serve the
+     * REAL virtual SSR entry (getVirtualEntrySSR) for the on-demand shell
+     * capture endpoint with the app's configured head-script strategy.
+     */
+    headScripts?: import("../plugin-types.js").HeadScriptsOption;
+}
+export interface PrecomputedEntry {
+    staticPrefix: string;
+    routes: Record<string, string>;
+}
+export interface ChunkInfo {
+    fileName: string;
+    exports: Array<{
+        name: string;
+        handlerId: string;
+        passthrough: boolean;
+    }>;
+}
+export interface PerRouterManifestEntry {
+    id: string;
+    routeManifest: Record<string, string>;
+    routeTrailingSlash?: Record<string, string>;
+    routeSearchSchemas?: Record<string, Record<string, string>>;
+    sourceFile?: string;
+    factoryOnlyPrefixes?: Set<string>;
+}
+/**
+ * One Prerender+ppr URL the build must additionally produce a PPR shell entry
+ * for (issue #699 producer B). `ppr` is the route's raw path option, already
+ * filtered to truthy by the collector.
+ */
+export interface ShellPrerenderCandidate {
+    urlPath: string;
+    routeName: string;
+    paramHash: string;
+    ppr: true | {
+        ttl?: number;
+        swr?: number;
+        tags?: string[];
+        captureTimeout?: number;
+    };
+}
+export interface DiscoveryState {
+    resolvedEntryPath: string | undefined;
+    projectRoot: string;
+    isBuildMode: boolean;
+    userResolveAlias: any;
+    /**
+     * Data-only slice of the user's resolved config (resolve.* incl. native
+     * tsconfigPaths, define, oxc) mirrored into the discovery temp server so it
+     * resolves and transforms modules the same way the real environment does.
+     * See `utils/forward-user-plugins.ts`.
+     */
+    userRunnerConfig: import("../utils/forward-user-plugins.js").ForwardedRunnerConfig | undefined;
+    /**
+     * User resolution plugins (resolveId/load), stripped to their resolution
+     * surface, forwarded into the discovery temp server. Lets third-party
+     * resolvers such as vite-tsconfig-paths participate in discovery.
+     */
+    userResolvePlugins: import("vite").Plugin[];
+    scanFilter: ScanFilter | undefined;
+    cachedRouterFiles: string[] | undefined;
+    opts: PluginOptions | undefined;
+    mergedRouteManifest: Record<string, string> | null;
+    perRouterManifests: PerRouterManifestEntry[];
+    perRouterTrieMap: Map<string, any>;
+    perRouterPrecomputedMap: Map<string, PrecomputedEntry[]>;
+    perRouterManifestDataMap: Map<string, Record<string, string>>;
+    prerenderManifestEntries: Record<string, string> | null;
+    staticManifestEntries: Record<string, string> | null;
+    /**
+     * Build-time PPR shell candidates: prerender routes that ALSO declare the
+     * `ppr` path option (issue #699 producer B). Collected by
+     * expandPrerenderRoutes; consumed by the post-build shell capture phase.
+     */
+    shellCandidates: ShellPrerenderCandidate[] | null;
+    /**
+     * Raw prerender payload JSON strings keyed by manifest key, retained in
+     * memory so the shell capture phase can seed an in-realm prerender store
+     * without re-reading staged asset files.
+     */
+    prerenderPayloadValues: Map<string, string> | null;
+    /**
+     * The buildStart temp RSC server, kept alive past discovery when shell
+     * candidates exist: the shell capture phase (buildApp post) reuses its
+     * realm — tries installed, registry populated — after the client build has
+     * produced the asset URLs the prelude must embed. Deferred as a PAIR with
+     * the buildEnv; closed by the buildApp post hook's finally (success) or
+     * buildEnd (aborted build).
+     */
+    shellPhaseTempServer: import("vite").ViteDevServer | null;
+    handlerChunkInfoMap: Map<string, ChunkInfo>;
+    staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
+    rscEntryFileName: string | null;
+    resolvedPrerenderModules: Map<string, string[]> | undefined;
+    resolvedStaticModules: Map<string, string[]> | undefined;
+    discoveryDone: Promise<void> | null;
+    /** Monotonic Cloudflare-dev generation installed by the routes manifest. */
+    devDiscoveryEpoch?: number;
+    devServerOrigin: string | null;
+    devServer: any;
+    selfWrittenGenFiles: Map<string, {
+        at: number;
+        hash: string;
+    }>;
+    SELF_WRITE_WINDOW_MS: number;
+    /** Resolved build-time env bindings (set during buildStart/configureServer). */
+    resolvedBuildEnv?: Record<string, unknown>;
+    /** Cleanup function for build-time env resources (e.g., miniflare). */
+    buildEnvDispose?: (() => Promise<void> | void) | null;
+    /**
+     * Set when the most recent HMR re-discovery threw. Cleared on the next
+     * successful discovery. Surfaced via debug logs so we can detect "manifest
+     * frozen at last-good after error → user fix in non-route file → no
+     * rediscovery trigger" scenarios.
+     */
+    lastDiscoveryError?: {
+        message: string;
+        at: number;
+    } | null;
+}
+export declare function createDiscoveryState(entryPath: string | undefined, opts: PluginOptions | undefined): DiscoveryState;

package/dist/types/vite/discovery/virtual-module-codegen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Virtual Module Code Generation
+ *
+ * Generates the code for virtual:rsc-router/routes-manifest and
+ * per-router virtual modules used by the load() hook.
+ */
+import type { DiscoveryState } from "./state.js";
+/**
+ * Generate the code for the main virtual:rsc-router/routes-manifest module.
+ */
+export declare function generateRoutesManifestModule(state: DiscoveryState): string;
+/**
+ * Generate the code for a per-router virtual module.
+ */
+export declare function generatePerRouterModule(state: DiscoveryState, routerId: string): string;