@rangojs/router 0.20.0 → 0.22.0

package/dist/types/vite/discovery/build-versions.d.ts

@@ -0,0 +1,393 @@
+/**
+ * Per-router cache versions, computed from the built server output.
+ *
+ * Every cache key and stored PPR shell is tied to a version. A router's
+ * versions are hashes of the code that router can run, so the same code gives
+ * the same versions and a new deployment finds the entries the previous one
+ * wrote. Design and measurements: docs/design/per-app-cache-version.md.
+ *
+ * Two steps, both pure over data the build hooks record:
+ *
+ * 1. Membership ({@link resolveRouterMembers}): which server modules can a
+ *    router run. Walked on the MODULE graph, not the chunk graph, because the
+ *    build has registries that name every app's code (plugin-rsc's
+ *    server-reference map, the loader manifest, the routes manifest). A walk
+ *    that followed them would put every router's code in every router's set.
+ * 2. Hashing ({@link computeRouterVersions}): the bytes on disk of the chunks
+ *    holding those modules, read AFTER postprocessBundle rewrote them, with
+ *    everything taken out that says where or how the build ran instead of what
+ *    it built ({@link digestBundle}).
+ *
+ * One rule covers what the build cannot determine (a file it lists and cannot
+ * read, an import it cannot resolve): the build fails, or the version changes
+ * on every build. A version never silently stays the same.
+ */
+import { type RouterVersionsTable } from "../../router-versions.js";
+/** Import edges of one module, as the bundler resolved them. */
+export interface BuildModuleEdges {
+    readonly imports: readonly string[];
+    readonly dynamicImports: readonly string[];
+    /**
+     * The module encrypts inline-action bound arguments, so what it renders can
+     * only be decrypted with the build's encryption key.
+     */
+    readonly encryptsBoundArgs?: boolean;
+}
+export interface BuildChunk {
+    readonly fileName: string;
+    /** The chunk's name without its content hash. */
+    readonly name: string;
+    readonly moduleIds: readonly string[];
+    /** Specifiers the chunk imports that the bundle does not contain. */
+    readonly externalImports?: readonly string[];
+}
+export interface BuildAsset {
+    readonly fileName: string;
+    /** The asset's name without its content hash. */
+    readonly name: string;
+}
+/** The files one environment's bundle emits. */
+export interface BundleFiles {
+    readonly chunks: readonly BuildChunk[];
+    readonly assets: readonly BuildAsset[];
+}
+/** The RSC environment's bundle, from its real (not scan) build pass. */
+export interface ServerBuildGraph extends BundleFiles {
+    readonly modules: ReadonlyMap<string, BuildModuleEdges>;
+}
+/** The client environment's module graph and emitted file names. */
+export interface ClientBuildGraph {
+    readonly modules: ReadonlyMap<string, BuildModuleEdges>;
+    readonly fileNames: readonly string[];
+}
+/** One discovered router: its runtime id and the module that creates it. */
+export interface RouterSource {
+    readonly id: string;
+    /** Absolute path of the file calling createRouter(), when known. */
+    readonly moduleId: string | undefined;
+}
+/**
+ * One piece of data the build produced that a router's output depends on and
+ * that none of the router's chunks holds. Named by the digest of its bytes.
+ *
+ * The kinds feed different versions, by where the data can end up at run
+ * time:
+ *
+ * - A Static payload is a segment of an ordinary route, so a `cache()` entry
+ *   of that route stores it. It is part of the DATA version.
+ * - A clientUrls() projection is what the server materializes a client-defined
+ *   route group from: its loaders, loading states, transitions and route ids.
+ *   It ships in the routes registry (virtual-module-codegen.ts), which a
+ *   lazily mounted app's chunks do not include. DATA version.
+ * - A server component's stylesheet URLs are read at run time from plugin-rsc's
+ *   assets manifest and rendered as `<link>`s into the router's Flight, so
+ *   they are in cached payloads while no server chunk holds them. DATA version.
+ * - A Prerender payload is served from the build's own store and never
+ *   written to the segment cache (withCacheLookup returns before the cache
+ *   scope, match-middleware/cache-lookup.ts). Only stored HTML holds it: a PPR
+ *   shell or a document-cache response of the route. It is part of the
+ *   DOCUMENT version only.
+ */
+export interface BuildDataRecord {
+    readonly kind: "prerender" | "static" | "client-urls" | "server-css";
+    /**
+     * Prerender manifest key, Static handler id, clientUrls() module, or the
+     * module a `serverResources` entry is keyed by.
+     */
+    readonly key: string;
+    /** sha256 of the payload, the projection, or the entry. */
+    readonly digest: string;
+    /** Router that rendered it (prerender). */
+    readonly routerId?: string;
+    /**
+     * Module the data belongs to (static: the handler's; client-urls: the
+     * clientUrls() module; server-css: the module that renders the links).
+     * Owned by {@link ownersOf}.
+     */
+    readonly moduleId?: string;
+}
+export interface RouterMembers {
+    /** Server modules the router can run. */
+    readonly modules: ReadonlySet<string>;
+    /** Chunk files holding any of them, plus the router's route manifest. */
+    readonly chunkFiles: ReadonlySet<string>;
+}
+/** The slice of a plugin context the graph recorders read. */
+interface ModuleGraphContext {
+    getModuleIds(): Iterable<string>;
+    getModuleInfo(id: string): {
+        importedIds?: readonly string[];
+        dynamicallyImportedIds?: readonly string[];
+        code?: string | null;
+    } | null;
+}
+/** The slice of an output bundle the graph recorders read. */
+type OutputBundleLike = Record<string, {
+    type: string;
+    fileName: string;
+    name?: string;
+    names?: readonly string[];
+    moduleIds?: readonly string[];
+    imports?: readonly string[];
+    dynamicImports?: readonly string[];
+}>;
+/** The chunks and assets of a bundle. Call from generateBundle. */
+export declare function recordBundleFiles(bundle: OutputBundleLike): BundleFiles;
+/** Call from the RSC environment's generateBundle. */
+export declare function recordServerGraph(context: ModuleGraphContext, bundle: OutputBundleLike): ServerBuildGraph;
+/** Call from the client environment's generateBundle. */
+export declare function recordClientGraph(context: ModuleGraphContext, bundle: OutputBundleLike): ClientBuildGraph;
+/** plugin-rsc's build-time map of every server reference in the app. */
+export declare const SERVER_REFERENCES_MODULE_ID = "\0virtual:vite-rsc/server-references";
+/**
+ * plugin-rsc writes the key to this file next to the RSC entry and has chunks
+ * import it at run time (its `rsc:encryption-key` renderChunk), so the key is
+ * in no chunk and in no bundle graph. The file exists only when a rendered
+ * chunk reads the key.
+ */
+export declare const ENCRYPTION_KEY_FILE = "__vite_rsc_encryption_key.js";
+/**
+ * Work out, per router, the server modules it can run and the chunk files
+ * holding them.
+ *
+ * The walk starts at the module calling createRouter() AND at every module
+ * that statically imports it, directly or through other static imports. What
+ * runs with a router is not only what its own module imports: the modules
+ * importing it attach middleware and handlers (`router.use(...)` in an app
+ * module) and wrap its fetch (the mounted handler). The climb stops at a
+ * dynamic import, which is how a host mounts an app it does not run with; so
+ * routers that one module imports statically share that module's code, and
+ * only lazily mounted apps are independent of each other.
+ *
+ * A router whose module the build cannot find is left out of the result; the
+ * runtime then serves it with the whole-build versions
+ * ({@link DEFAULT_ROUTER_VERSIONS_KEY}).
+ *
+ * Membership is per module, the hash is per chunk file. A chunk that holds one
+ * reached module is hashed whole, so a router's version also covers whatever
+ * the bundler placed next to its code: the conservative direction.
+ */
+export declare function resolveRouterMembers(server: ServerBuildGraph, client: ClientBuildGraph | undefined, routers: readonly RouterSource[]): Map<string, RouterMembers>;
+export declare function sha256(value: string | Uint8Array): string;
+/**
+ * A module id without the build machine's checkout directory: root-relative
+ * inside the project, and from the outermost node_modules for an installed
+ * package. The outermost, not the innermost: two installed versions of one
+ * package differ only in the directories between (`.pnpm/foo@1…/node_modules/foo`,
+ * a nested `a/node_modules/foo`), and must not get the same id. A pnpm store
+ * directory is reduced to `name@version` ({@link PNPM_PEER_SUFFIX}).
+ *
+ * A virtual id can carry a file path in its query. plugin-rsc's server CSS
+ * module is `virtual:vite-rsc/css?type=rsc&id=<URI-encoded absolute importer>`,
+ * so those values are made portable too.
+ */
+export declare function portableModuleId(id: string, projectRoot: string): string;
+/** A sourcemap describes a file; it is not code the server runs. */
+export declare function isSourceMap(fileName: string): boolean;
+/**
+ * Drop the body of the server-reference map from a chunk's source.
+ *
+ * The map lists every `"use server"` module of the build with its export
+ * names, and it sits in a chunk every router runs (plugin-rsc's server
+ * runtime imports it). Hashed as is, the map would put every app's action
+ * list into every app's version. Its text is derived: each module it names is
+ * hashed by the routers that reach it (resolveRouterMembers), so nothing the
+ * map says is lost by skipping it.
+ *
+ * Works on the region comments, so a minified server build (which has none)
+ * keeps the map in every router's hash: more clearing, never less.
+ */
+export declare function stripServerReferenceMap(source: string): string;
+/**
+ * Take the module paths out of a chunk's region comments.
+ *
+ * The bundler prints one before each module's code, and the path says where
+ * the build ran, not what it built: it is relative to the directory `vite
+ * build` was started from (`vite build apps/web` from a repository root
+ * prints other paths than `vite build` in the app), it holds the pnpm store
+ * directory with its peer suffix, and a virtual id is printed verbatim,
+ * absolute paths in its query included. The code under the comment is hashed
+ * either way.
+ */
+export declare function stripRegionPaths(source: string): string;
+/** One thing a version is a hash of: its name and the digest of its bytes. */
+export type VersionInput = readonly [name: string, digest: string];
+/** One bundle file, digested once for every router. */
+export interface DigestedFile {
+    readonly fileName: string;
+    /**
+     * What the file is, independent of its content: the un-hashed name plus, for
+     * a chunk, a digest of the module ids inside it. Stands in for the file's
+     * hashed name wherever a router that owns the file refers to it.
+     */
+    readonly identity: string;
+    /**
+     * Digest of the file's bytes with every reference to a bundle file replaced
+     * by one token ({@link FILE_REFERENCE}), so a content hash in a file name
+     * never reaches it.
+     */
+    readonly base: string;
+    /** The files those references named, in order of appearance. */
+    readonly references: readonly string[];
+    /** Specifiers the file imports that the bundle does not contain. */
+    readonly externalImports: readonly string[];
+}
+/**
+ * Digest every file of a bundle, as it is on disk.
+ *
+ * Three things are taken out of a chunk's text first, each because it says
+ * where or how the build ran: the server-reference map's body
+ * ({@link stripServerReferenceMap}), the paths in region comments
+ * ({@link stripRegionPaths}), and the hashed names of bundle files. A name
+ * carries the content hash of its file, and every chunk importing the file
+ * has the name in its bytes, so one router's change would otherwise move the
+ * digest of every chunk naming its chunk. Only names with a content hash are
+ * replaced; a fixed name such as the entry's "index.js" is the same in every
+ * build. An asset is data (a route manifest staged as a text module can be
+ * megabytes): hashed as bytes, never scanned.
+ *
+ * Throws when the bundle lists a file that is not on disk: its bytes would
+ * silently drop out of every version.
+ */
+export declare function digestBundle(bundle: BundleFiles, projectRoot: string, read: (fileName: string) => Uint8Array | undefined, label: string): DigestedFile[];
+/** How the build reads what the bundles leave external. */
+export interface ExternalResolver {
+    /**
+     * What is installed for a package: `name@version` of the package and of
+     * everything it depends on (installed-packages.ts). The chunk only says
+     * `from "pkg"`, whichever version that is. `undefined` when the package
+     * cannot be found.
+     */
+    readonly describePackage: (name: string) => string | undefined;
+    /** The bytes of a file at an absolute path; `undefined` when it is absent. */
+    readonly readFile: (path: string) => Uint8Array | undefined;
+    /** Unique to this build: the digest of an input that cannot be determined. */
+    readonly buildId: string;
+}
+export type ExternalImport = {
+    readonly kind: "provided";
+} | {
+    readonly kind: "package";
+    readonly name: string;
+} | {
+    readonly kind: "file";
+} | {
+    readonly kind: "unknown";
+};
+/**
+ * What an import a bundle leaves external is. THE rule for all of them, and
+ * the only place it is decided:
+ *
+ * - `provided`: the version does not cover it. A runtime builtin (`node:fs`,
+ *   bare `fs`, `cloudflare:workers`, `bun:sqlite`), a `data:` URL (its content
+ *   is the specifier, which is in the chunk), or a marker of another plugin
+ *   whose file is a bundle output the hash already covers.
+ * - `package`: an installed package. The version covers what is installed.
+ * - `file`: a relative or absolute path. The version covers the file's bytes.
+ * - `unknown`: anything else (`https:`, `npm:`, a name npm would reject).
+ *
+ * A package that is not installed, a path that does not resolve and every
+ * `unknown` import get a value unique to the build, and the build names them:
+ * the routers importing them get a new version on every build. Nothing the
+ * build cannot read is left out of a version.
+ */
+export declare function classifyExternal(specifier: string): ExternalImport;
+export interface ComputeRouterVersionsInput {
+    readonly projectRoot: string;
+    readonly server: ServerBuildGraph;
+    readonly client: ClientBuildGraph;
+    /** The SSR environment's bundle, with the files plugin-rsc writes next to it. */
+    readonly ssr: BundleFiles;
+    readonly routers: readonly RouterSource[];
+    readonly buildData: readonly BuildDataRecord[];
+    /** Read a file of the RSC output directory; undefined when it is absent. */
+    readonly readServerFile: (fileName: string) => Uint8Array | undefined;
+    /** Read a file of the SSR output directory; undefined when it is absent. */
+    readonly readSsrFile: (fileName: string) => Uint8Array | undefined;
+    /** Vite's `base`, a prefix of every asset URL in stored HTML. */
+    readonly base: string;
+    /**
+     * plugin-rsc's `serverResources` from the built assets manifest: the
+     * root-relative id of a server module that imports CSS, to the text of its
+     * entry (the stylesheet URLs).
+     */
+    readonly serverResources?: ReadonlyMap<string, string>;
+    readonly externals: ExternalResolver;
+}
+export interface RouterVersionDetail {
+    readonly routerId: string;
+    readonly data: string;
+    readonly document: string;
+    /**
+     * Everything the data version is a hash of, in hashed order: `file
+     * <identity>` for a server file, `static <id>` for a Static payload,
+     * `client-urls <module>` for a clientUrls() projection, `server-css
+     * <module>` for a server component's stylesheets, `external <import>` for
+     * what the bundle left external, `encryption-key` for the key. Two builds'
+     * lists differ exactly where the version's inputs differ.
+     */
+    readonly dataInputs: readonly VersionInput[];
+    /**
+     * What the document version adds to the data version: `ssr-and-client` (the
+     * SSR output and the client asset names) and `prerender <key>` for a
+     * Prerender payload.
+     */
+    readonly documentInputs: readonly VersionInput[];
+    /** The key is part of the router's data version. */
+    readonly usesEncryptionKey: boolean;
+}
+/**
+ * What stored HTML depends on besides a router's server code, one set for the
+ * build (the SSR output is not split by router). Hashed as the
+ * `ssr-and-client` input of every document version.
+ */
+export interface SsrAndClientInputs {
+    /** Vite's `base`, a prefix of every asset URL in stored HTML. */
+    readonly base: string;
+    /**
+     * The SSR output, file by file ({@link digestBundle}). It renders the HTML,
+     * and its own code can change without the client's.
+     */
+    readonly ssr: readonly VersionInput[];
+    /** What the SSR output leaves external ({@link classifyExternal}). */
+    readonly externals: readonly VersionInput[];
+    /**
+     * The client asset names. A prelude and an open tab both hold them, and the
+     * names carry the bundler's content hashes.
+     */
+    readonly client: readonly string[];
+}
+export interface ComputedRouterVersions {
+    readonly table: RouterVersionsTable;
+    /** One entry per attributed router, then the whole-build entry. */
+    readonly details: readonly RouterVersionDetail[];
+    /** What every document version covers besides its router's data version. */
+    readonly ssrAndClient: SsrAndClientInputs;
+    /** Server files no attributed router owns, by identity. */
+    readonly unownedFiles: readonly string[];
+    /** Imports the build could not determine ({@link classifyExternal}). */
+    readonly undetermined: readonly string[];
+}
+/**
+ * Compute every router's data and document version, and the whole-build pair.
+ *
+ * A router's data version covers: its chunk files, the bundle assets those
+ * files name (a route manifest staged as a text module), what those files
+ * leave external, and the inputs it owns that no chunk holds
+ * ({@link ownersOf}). Its document version is the data version plus the SSR
+ * output, the client asset names, `base` and its Prerender payloads.
+ */
+export declare function computeRouterVersions(input: ComputeRouterVersionsInput): ComputedRouterVersions;
+/**
+ * The chunk files of a bundle that hold the `@rangojs/router:version` module,
+ * where the placeholder has to be replaced. Recorded for every environment:
+ * the module is emitted wherever something imports it (a second worker that
+ * uses a cache store), and an unreplaced placeholder throws on load.
+ */
+export declare function recordVersionModuleFiles(bundle: OutputBundleLike): string[];
+/**
+ * Replace the version module's placeholder with the table. Returns undefined
+ * when `source` does not hold the placeholder.
+ */
+export declare function fillRouterVersions(source: string, table: RouterVersionsTable): string | undefined;
+export {};

package/dist/types/vite/discovery/installed-packages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What is installed for a package a server build leaves external.
+ *
+ * The node preset bundles only packages that need the React server condition
+ * (plugin-rsc's `noExternal`); every other dependency stays an import the
+ * deployed process resolves from node_modules. The built chunk then says
+ * `from "pkg"` whichever version is installed, so a lockfile bump changes what
+ * the server renders and nothing the cache versions hash
+ * (discovery/build-versions.ts). This module supplies the missing input: the
+ * `name@version` of the package and of everything it depends on, as installed
+ * next to the project at build time.
+ *
+ * A registry package's code is fixed by its version. A linked package (a
+ * workspace package, resolved to a directory outside node_modules) is not.
+ * Vite bundles those unless the config lists one in `resolve.external`; then
+ * it comes through here and its files are digested instead.
+ */
+/**
+ * Returns a function describing an installed package by name: the sorted
+ * `name@version` lines of the package and its transitive dependencies
+ * (dependencies, optionalDependencies and peerDependencies, each resolved from
+ * the package that declares it), with a digest of its files for a linked
+ * one, or `undefined` when the package is not installed. Results are kept per
+ * name for the life of the returned function.
+ */
+export declare function createInstalledPackageDescriber(projectRoot: string): (name: string) => string | undefined;

package/dist/types/vite/discovery/router-versions-phase.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Post-build cache version phase.
+ *
+ * Runs from the buildApp post hook, after every environment bundle is written
+ * and postprocessBundle has rewritten the RSC chunks, and before the shell
+ * capture phase, which stamps its entries with the document versions computed
+ * here. Reads the bytes that ship, computes each router's versions
+ * (build-versions.ts) and writes the table into the built
+ * `@rangojs/router:version` module in place of its placeholder.
+ */
+import { type RouterVersionsTable } from "../../router-versions.js";
+import type { DiscoveryState } from "./state.js";
+/** Minimal builder surface the post-build phases read. */
+export interface BuilderLike {
+    config?: {
+        base?: string;
+    };
+    environments?: Record<string, {
+        config?: {
+            build?: {
+                outDir?: string;
+            };
+        };
+    } | undefined>;
+}
+/**
+ * An environment's output directory, or Vite's default layout without one.
+ * Resolved against the root: a relative `build.outDir` is relative to it, not
+ * to the directory `vite build <root>` was run from.
+ */
+export declare function environmentOutDir(builder: BuilderLike | undefined, projectRoot: string, environment: string): string;
+/**
+ * Where the build leaves what each version was computed from. Outside the
+ * output directories, so it never ships.
+ */
+export declare const VERSIONS_REPORT_FILE: string;
+/**
+ * The `serverResources` map of plugin-rsc's assets manifest
+ * (`export default { ..., serverResources: { "<module>": { js, css } } }`):
+ * each server module that imports CSS, to the source text of its entry. Text,
+ * not a parsed value: with `renderBuiltUrl` an entry holds runtime expressions.
+ * Throws when the manifest is not that shape, so a plugin-rsc that moves it
+ * fails the build instead of dropping stylesheets from the versions.
+ */
+export declare function readServerResources(manifest: string): Map<string, string>;
+/**
+ * Compute the versions, write them into the built version module and return
+ * the table (`undefined` outside a build). Fails the build when an input was
+ * not recorded or cannot be read: a version computed without it would stay
+ * the same when it changes.
+ */
+export declare function runRouterVersionsPhase(s: DiscoveryState, builder: BuilderLike | undefined): RouterVersionsTable | undefined;

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

@@ -18,23 +18,13 @@
  * or never consulted the prerender store is SKIPPED loudly — the route keeps
  * producer A (runtime capture) semantics, never a wrong-lane bake.
  */
+import { type RouterVersionsTable } from "../../router-versions.js";
+import { type BuilderLike } from "./router-versions-phase.js";
 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.
+ * @param versionsTable The versions the shipped build serves with
+ *   (router-versions-phase.ts), `undefined` outside a build. Never the temp
+ *   server's own version-plugin stamp, which is a dev Date.now() and would
+ *   fail the serve-side isValidShellHit gate forever.
  */
-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 {};
+export declare function runShellPrerenderPhase(s: DiscoveryState, builder: BuilderLike | undefined, versionsTable: RouterVersionsTable | undefined): Promise<void>;

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

@@ -8,6 +8,7 @@
 import type { ScanFilter } from "../../build/generate-route-types.js";
 import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 export declare const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+export declare const VIRTUAL_LOADER_MANIFEST_ID = "virtual:rsc-router/loader-manifest";
 export interface PluginOptions {
     enableBuildPrerender?: boolean;
     staticRouteTypesGeneration?: boolean;
@@ -62,6 +63,7 @@ export interface ChunkInfo {
         name: string;
         handlerId: string;
         passthrough: boolean;
+        onDemand: boolean;
     }>;
 }
 export interface PerRouterManifestEntry {
@@ -143,8 +145,31 @@ export interface DiscoveryState {
      * buildEnd (aborted build).
      */
     shellPhaseTempServer: import("vite").ViteDevServer | null;
+    /**
+     * Inputs of the per-router cache versions (build-versions.ts), recorded by
+     * generateBundle. plugin-rsc builds the RSC and SSR environments twice (a
+     * scan pass, then the real pass); each pass overwrites its slot, so the
+     * buildApp post hook reads the real pass.
+     */
+    serverBuildGraph: import("./build-versions.js").ServerBuildGraph | null;
+    clientBuildGraph: import("./build-versions.js").ClientBuildGraph | null;
+    ssrBundle: import("./build-versions.js").BundleFiles | null;
+    /** Per environment, the chunk files holding the version module. */
+    versionModuleFiles: Map<string, string[]>;
+    /** Prerender and Static payloads the build rendered, by content digest. */
+    buildData: import("./build-versions.js").BuildDataRecord[];
     handlerChunkInfoMap: Map<string, ChunkInfo>;
     staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
+    /**
+     * handlerId ($$id) -> route name for every route the evaluated source marks
+     * onDemand. Written during discovery (buildStart), consumed by the
+     * generateBundle chunk scan (extractHandlerExportsFromChunk) as the
+     * authoritative onDemand set driving producer retention — the same source
+     * that sets the runtime od trie flag, so any truthy onDemand spelling
+     * (literal, spread, imported const) both marks the route and retains its
+     * producer.
+     */
+    onDemandHandlerIds: Map<string, string>;
     rscEntryFileName: string | null;
     resolvedPrerenderModules: Map<string, string[]> | undefined;
     resolvedStaticModules: Map<string, string[]> | undefined;

package/dist/types/vite/encryption-key.d.ts

@@ -1,2 +1,20 @@
+/**
+ * Throws unless `value` is the base64 form of an AES key (16, 24 or 32 bytes).
+ * `source` names where the value came from, for the message.
+ */
+export declare function assertValidEncryptionKey(value: unknown, source: string): void;
+/**
+ * Resolve the build's encryption key from rango({ encryptionKey }) or the
+ * RANGO_ENCRYPTION_KEY fallback, validating whichever is set. Called by
+ * rango() at config time, before any plugin-rsc instance reads the key, so an
+ * invalid key fails the config load instead of the first encrypted action.
+ * A key generated earlier in the process is kept when neither source is set:
+ * the discovery temp server must encrypt with the main build's key.
+ */
+export declare function configureEncryptionKey(option: string | undefined): void;
 export declare function buildEncryptionKey(): string;
+/** False when this build generated its own key (it differs on every build). */
+export declare function isEncryptionKeyStable(): boolean;
 export declare function defineEncryptionKeyExpr(): string;
+/** @internal Test seam: forget the process-wide key. */
+export declare function resetEncryptionKeyForTests(): void;

package/dist/types/vite/inject-client-debug.d.ts

@@ -1,28 +1,9 @@
 import type { Connect } from "vite";
-/**
- * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
- * module so the flag reaches the CLIENT debug logs by just setting the env var.
- *
- * internal-debug.ts normally reads the flag via `typeof __RANGO_DEBUG__`, a Vite
- * define. That delivery is unreliable on the client: in dev Vite ships the define
- * only as an injected global whose presence varies across consumer setups, so the
- * module can fall through to `process.env` (undefined in the browser) and the FE
- * debug flag silently stays false while the server logs work. A Vite `transform`
- * runs on the module regardless of how (or whether) the define is delivered, in
- * both dev and build and for every environment, so the discovery plugin uses this
- * to replace the module with the resolved literal.
- */
-/**
- * Scope to the router's own internal-debug module: the published package
- * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
- * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
- * consumer file that merely sits under a directory named `rangojs-router`.
- * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
- */
+/** A router flag module: internal-debug.ts or internal-suspense-audit.ts. */
 export declare function isRouterInternalDebugId(id: string): boolean;
 /**
- * Transform: replace the module with the resolved literal.
- * Returns null for any module that is not the router's internal-debug module.
+ * Transform: replace a router flag module with the resolved literal.
+ * Returns null for any other module.
  */
 export declare function injectClientDebugFlag(id: string): {
     code: string;
@@ -44,9 +25,9 @@ export declare function injectClientDebugFlag(id: string): {
  * immune -- workspace source is outside node_modules and served no-cache --
  * which is why this bit only npm consumers.
  *
- * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
- * are byte-identical across flag states), so forcing revalidation for this one
- * tiny module is sufficient and costs one conditional request per session. The
+ * The two flag modules are the only flag-varying modules in the graph (their
+ * importers are byte-identical across flag states), so forcing revalidation for
+ * them is sufficient and costs a conditional request each per session. The
  * middleware is unconditional (not gated on the flag) so an already-poisoned
  * cache heals in both directions. Alternatives that do not work: a plugin
  * `resolveId` appending a flag query never fires in Vite 8 dev for

package/dist/types/vite/plugin-types.d.ts

@@ -213,6 +213,33 @@ interface RangoBaseOptions {
     prerender?: {
         onError?: "fail" | "warn";
     };
+    /**
+     * The key inline server actions encrypt their bound arguments with:
+     * base64-encoded 32 bytes (`openssl rand -base64 32`). Pass it from the
+     * environment, never as a literal in the config file:
+     *
+     * ```ts
+     * rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })
+     * ```
+     *
+     * Why set it: the key is part of the cache version of every router whose
+     * server code encrypts with it, because a payload cached under one key
+     * carries arguments another key cannot decrypt. Without a stable key rango
+     * generates one per build, so those routers get a new version, and a cleared
+     * cache, on every deploy. With a stable key their cache survives a deploy
+     * that does not change their server code. It also lets a build decrypt
+     * arguments an earlier build encrypted (a cached or prerendered payload, an
+     * open tab).
+     *
+     * Validated when `rango()` is called: a value that is not base64 or does not
+     * decode to an AES key size (16, 24 or 32 bytes) throws. `undefined` (the
+     * variable is unset) falls back to the `RANGO_ENCRYPTION_KEY` environment
+     * variable, then to a generated key. Rotating the key clears the cache of
+     * the routers that use it.
+     *
+     * @default process.env.RANGO_ENCRYPTION_KEY, else a key generated per build
+     */
+    encryptionKey?: string;
 }
 /**
  * Options for Node.js deployment (default)