@rangojs/router 0.19.1 → 0.21.0

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

@@ -68,6 +68,12 @@ export interface ClientChunkMeta {
  *   strategy**. It splits app `"use client"` modules by **route id** — the segment
  *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
  *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   The first marker in the path wins, except that an `app/` directly followed
+ *   by another marker with a directory after it is treated as a source root:
+ *   `app/routes/product/**` becomes `app-product`, while `app/dashboard/**`
+ *   (Next-style), `app/components/**` and files directly in `app/routes/` stay
+ *   `app-dashboard` / `app-components` / `app-routes`. The same route id under
+ *   different markers is one group.
  *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
  *   already split by a dynamic `import()`), it inherits the default grouping
  *   unchanged — so the shared `src/components` chunk stays shared and host apps do
@@ -79,10 +85,14 @@ export interface ClientChunkMeta {
  *   back to the default grouping for that one module. Forwarded directly to
  *   `@vitejs/plugin-rsc`'s `clientChunks`.
  *
- * Every module maps to exactly one group, so there is no byte duplication: a
- * component used by two routes lives in one group and is fetched whenever it
- * renders. Put genuinely shared client components OUTSIDE route directories so
- * they land in the shared group rather than one route's chunk.
+ * Every module maps to exactly one group, so there is no byte duplication. A
+ * group is also the loading unit: rendering any one member downloads the whole
+ * group's chunk, every other member included. A component used by two routes
+ * lives in one group, and rendering it on either route fetches that entire
+ * group. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk, and keep an
+ * always-rendered component (a layout header) out of a large group.
+ * `DEBUG=rango:chunks vite build` logs each group's module count and size.
  *
  * @default true
  */
@@ -114,14 +124,18 @@ interface RangoBaseOptions {
      * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
      *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
      *   plugin-rsc's modulepreload hints in place), and the browser entry ships
-     *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
-     *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+     *   as Fizz `bootstrapModules` — a `modulepreload` hint after the head
+     *   chunk scripts (default priority; Fizz's `fetchpriority=low` is dropped,
+     *   #1025)
+     *   plus the executing end-of-shell `id="_R_"` module script. Chunk
      *   execution overlaps body streaming instead of waiting for the hydration
      *   import walk; under PPR everything lands in the stored shell prelude.
      * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
      *   only, entry as an inline `import()` script at end of shell. Chunks
      *   fetch+compile early but execute only when hydration imports them.
      *
+     * Any other value throws when the generated SSR entry is built.
+     *
      * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
      * reference in dev, so dev documents carry no head chunk scripts in either
      * mode (the bootstrap conversion does apply in dev). Trades and upstream
@@ -199,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)

package/dist/types/vite/plugins/{version-injector.d.ts → entry-bootstrap-injector.d.ts}

@@ -1,10 +1,8 @@
 import type { Plugin } from "vite";
 /**
- * Plugin that auto-injects VERSION, routes-manifest, and loader-manifest into
- * custom entry.rsc files. If a custom entry.rsc file uses createRSCHandler but
- * doesn't pass version, this transform adds the import and property
- * automatically. It also ensures the routes-manifest and loader-manifest
- * virtual modules are always imported.
+ * Plugin that auto-injects the routes-manifest and loader-manifest imports
+ * into a custom entry.rsc file (the Cloudflare preset, where the consumer owns
+ * the worker entry).
  *
  * The loader-manifest import is what makes fetchable loaders resolvable on a
  * custom worker entry. The virtual RSC entry (getVirtualEntryRSC) imports the
@@ -18,4 +16,4 @@ import type { Plugin } from "vite";
  * manifest, hence the production-only failure this fixes.
  * @internal
  */
-export declare function createVersionInjectorPlugin(rscEntryPath: string | undefined): Plugin;
+export declare function createEntryBootstrapInjectorPlugin(rscEntryPath: string | undefined): Plugin;

package/dist/types/vite/plugins/expose-ids/export-analysis.d.ts

@@ -1,5 +1,6 @@
 import type { CreateExportBinding } from "./types.js";
 export declare function isExportOnlyFile(code: string, bindings: CreateExportBinding[]): boolean;
+export declare function createCallPattern(fnNames: string[]): RegExp;
 export declare function countCreateCallsForNames(code: string, fnNames: string[]): number;
 export declare function offsetToLineColumn(code: string, index: number): {
     line: number;

package/dist/types/vite/plugins/expose-ids/router-transform.d.ts

@@ -1,5 +1,19 @@
 import type { Plugin } from "vite";
 import MagicString from "magic-string";
+/**
+ * A router's `$$id`: a hash of its root-relative file and of its position
+ * among the file's createRouter() calls.
+ *
+ * Not of the call's line. `code` is TS-transformed, and a dev server keeps
+ * comments there that a build drops, so a line of `code` gave build-time
+ * discovery and the bundle different ids for any router with a comment above
+ * it (e2e/test-app, tests/cloudflare-basic): the build registered the lazy
+ * route manifest under an id no running router had. And a line of the file as
+ * written changes with every blank line or comment added above the call,
+ * which renamed the state cookie, the route manifest chunk and the router's
+ * cache versions for an edit that changed nothing.
+ */
+export declare function routerId(filePath: string, callIndex: number): string;
 export declare function transformRouter(code: string, filePath: string, routerFnNames: string[], absolutePath?: string, warn?: (message: string) => void): {
     code: string;
     map: ReturnType<MagicString["generateMap"]>;

package/dist/types/vite/plugins/stable-rsc-output.d.ts

@@ -0,0 +1,51 @@
+import { type Plugin } from "vite";
+/** One property of an object literal, by its position in the source. */
+export interface LiteralProperty {
+    readonly key: string;
+    /** Range of the whole property, key included. */
+    readonly start: number;
+    readonly end: number;
+    /** The value's AST node. */
+    readonly value: any;
+}
+/**
+ * The properties of an object-literal AST node, or undefined when it is not an
+ * object literal of plain keys (a spread, a computed key).
+ */
+export declare function literalProperties(object: any): LiteralProperty[] | undefined;
+/**
+ * The properties of a module's `export default { ... }`, or undefined when
+ * the module does not parse or is not that shape. plugin-rsc generates its
+ * registries (the server-reference map, the assets manifest) in this form.
+ */
+export declare function defaultExportProperties(code: string): LiteralProperty[] | undefined;
+/**
+ * Return `code` with the properties of its default-exported object literal
+ * sorted by key, or undefined when there is nothing to reorder (or the module
+ * is not that shape).
+ */
+export declare function sortDefaultExportProperties(code: string): string | undefined;
+/**
+ * Return `code` with its default import of plugin-rsc's assets manifest
+ * renamed to {@link ASSETS_MANIFEST_BINDING}, or undefined when there is
+ * nothing to rename (no such import under a generated name, or the module
+ * uses the canonical name for something else).
+ */
+export declare function canonicalAssetsManifestBinding(code: string): string | undefined;
+/**
+ * Removes two run-to-run differences from plugin-rsc 0.5.35's build output.
+ * The cache versions hash these bytes (discovery/build-versions.ts).
+ *
+ * 1. Property order of the server-reference map. plugin-rsc writes it in the
+ *    order its transforms first saw each `"use server"` module
+ *    (`ServerReferencesManager.claimMap`), which varies with the concurrent
+ *    scan builds (e2e/test-app: 2 of 2 consecutive builds differed). Sorted
+ *    here so a minified server build, where stripServerReferenceMap finds no
+ *    region comments, still hashes the same bytes.
+ * 2. Local name of the assets-manifest import. plugin-rsc imports the manifest
+ *    under three names; the bundler merges them into one import per chunk and
+ *    keeps a different one from build to build (the cache-versions fixture:
+ *    1 of 10 concurrent builds). One name in, one name out.
+ * @internal
+ */
+export declare function stableRscOutput(): Plugin;

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

@@ -1,18 +1,16 @@
 import { type Plugin } from "vite";
 /**
- * Plugin providing rsc-router:version virtual module.
- * Exports VERSION that changes when RSC modules change (dev) or at build time (production).
+ * Plugin providing the `@rangojs/router:version` virtual module.
  *
- * The version is used for:
- * 1. Cache invalidation - CFCacheStore uses VERSION to invalidate stale cache
- * 2. Version mismatch detection - client sends version, server reloads on mismatch
+ * Dev: exports a VERSION stamp used for both versions of every router. It
+ * updates when the server starts and when an RSC module changes via HMR (the
+ * version module is invalidated). Client-only HMR changes do not update it:
+ * they do not affect server-rendered content or cached RSC payloads.
  *
- * In dev mode, the version updates when:
- * - Server starts (initial version)
- * - RSC modules change via HMR (triggers version module invalidation)
- *
- * Client-only HMR changes don't update the version since they don't affect
- * server-rendered content or cached RSC payloads.
+ * Build: exports a placeholder for the per-router versions table. The module
+ * holds nothing that varies between builds; the table is written into the
+ * built chunk after the server output is hashed (the buildApp post hook in
+ * router-discovery.ts). See docs/design/per-app-cache-version.md.
  * @internal
  */
 export declare function createVersionPlugin(): Plugin;

package/dist/types/vite/plugins/virtual-entries.d.ts

@@ -5,7 +5,9 @@ export declare const VIRTUAL_ENTRY_BROWSER: string;
  * option: "preinit" (default) installs the client-reference preinit hook and
  * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
  * "preload" omits the hook and uses the deprecated inline
- * `loadBootstrapScriptContent` bootstrap.
+ * `loadBootstrapScriptContent` bootstrap. Any other value throws: an unknown
+ * string such as "prenit" used to run as "preinit" silently
+ * (`headScripts !== "preload"` since #694).
  */
 export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption, progressiveChunkSize?: number): string;
 /**
@@ -20,7 +22,7 @@ export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption, prog
  *   registered for the _rsc_loader endpoint and fail in production.
  *
  * Single source of truth: both the generated virtual RSC entry below and the
- * custom-entry injector (version-injector) consume this list, so a new
+ * custom-entry injector (entry-bootstrap-injector) consume this list, so a new
  * bootstrap manifest cannot be added to one path and forgotten on the other.
  * That exact drift (loader-manifest present here but missing from the injector)
  * is what left fetchable loaders unresolved on custom worker entries.
@@ -34,4 +36,21 @@ export declare const VIRTUAL_IDS: {
     readonly rsc: "virtual:rsc-router/entry.rsc.js";
     readonly version: "@rangojs/router:version";
 };
+/** Dev: one stamp for both versions of every router, bumped on RSC edits. */
 export declare function getVirtualVersionContent(version: string): string;
+/**
+ * Free identifier the production version module ships in place of the table.
+ * The versions are hashes of the built server code, so they cannot be part of
+ * it: the buildApp post hook (router-discovery.ts) replaces this token in the
+ * written chunk once the hashes are final (runRouterVersionsPhase,
+ * discovery/router-versions-phase.ts). An unreplaced token throws a ReferenceError
+ * when the module evaluates, so a build that skipped the step cannot serve
+ * with a constant version.
+ */
+export declare const ROUTER_VERSIONS_PLACEHOLDER = "__RANGO_ROUTER_VERSIONS__";
+/**
+ * Production: byte-identical in every build, so it never moves the hashes it
+ * is later filled with. VERSION is the whole-build document version (the
+ * table's "*" entry).
+ */
+export declare function getVirtualBuildVersionContent(): string;

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

@@ -35,6 +35,12 @@ export declare function createTempRscServer(state: DiscoveryState, options?: {
      */
     realSsrEntry?: boolean;
 }): Promise<ViteDevServer>;
+import type { BuildEnvOption, BuildEnvFactoryContext, BuildEnvResult } from "./plugin-types.js";
+/**
+ * Resolve the buildEnv option into a concrete { env, dispose? } result.
+ * Handles all four input shapes: false, "auto", factory, plain object.
+ */
+export declare function resolveBuildEnv(option: BuildEnvOption | undefined, factoryCtx: BuildEnvFactoryContext): Promise<BuildEnvResult | null>;
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *

package/dist/types/vite/utils/client-chunks.d.ts

@@ -1,4 +1,6 @@
+import type { Plugin } from "vite";
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
+import { type Debugger } from "../debug.js";
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
 export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
 /**
@@ -36,8 +38,11 @@ export interface ClientChunkContext {
  * 1. Shared runtime (React / router / node_modules) -> `undefined` (never split).
  * 2. A registered error/notFound fallback (`ctx.fallbackRefs`) -> `app-fallback`,
  *    regardless of location, so the error UI is decoupled from the happy path.
- * 3. A {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on that
- *    next segment (the route id), robust to any nesting depth.
+ * 3. The first {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on
+ *    that next segment (the route id), robust to any nesting depth. A
+ *    {@link SOURCE_ROOT_DIRS} marker (`app`) directly followed by another marker
+ *    with a directory after it defers to that inner marker:
+ *    `app/routes/<id>/…` -> `app-<id>`, while `app/<segment>/…` -> `app-<segment>`.
  * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export declare function directoryClientChunks(meta: ClientChunkMeta, ctx?: ClientChunkContext): string | undefined;
@@ -53,3 +58,20 @@ export declare function directoryClientChunks(meta: ClientChunkMeta, ctx?: Clien
  *   fallback refinement does not apply — the consumer owns the grouping).
  */
 export declare function resolveClientChunks(option: ClientChunks | undefined, ctx?: ClientChunkContext): RscClientChunksFn | undefined;
+/** @vitejs/plugin-rsc's client-reference map; its group modules sit under it. */
+export declare const CLIENT_REFERENCES_MODULE_ID = "\0virtual:vite-rsc/client-references";
+/**
+ * Build-end group report under `DEBUG=rango:chunks`: one line per client
+ * reference group with its client-reference count and the size of the group's
+ * own chunk (code split into shared chunks such as `react`/`router` is not
+ * counted). A group is the loading unit (plugin-rsc imports the group's virtual
+ * module to resolve any one member), so a large group that an always-rendered
+ * component belongs to is downloaded on every route; this line makes that
+ * visible. Covers every group, including ones named by a custom `clientChunks`
+ * function or by plugin-rsc's default `serverChunk` grouping. `undefined` when
+ * the namespace is off, so a normal build does not register it. Group names are
+ * printed with NUL escaped: plugin-rsc's default group is named
+ * `facade:\0virtual:…`, and a raw NUL makes `grep` treat the output as binary
+ * and drop that line, usually the largest group. `log` is injectable for tests.
+ */
+export declare function clientChunksReport(log?: Debugger | undefined): Plugin | undefined;

package/dist/types/vite/utils/compare-strings.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Code-unit order, the same on every machine. Generated modules and the cache
+ * version inputs are sorted with it: `localeCompare` depends on the build
+ * machine's ICU data, and build output has to be byte-identical across machines
+ * (discovery/build-versions.ts hashes it).
+ */
+export declare function compareStrings(a: string, b: string): number;

package/dist/types/vite/utils/package-resolution.d.ts

@@ -3,4 +3,12 @@ export declare function isInstalledFromNpm(): boolean;
 export declare function isWorkspaceDevelopment(): boolean;
 export declare function getExcludeDeps(): string[];
 export declare function getPackageAliases(): Record<string, string>;
+/**
+ * @vitejs/plugin-rsc puts these vendor specifiers in `optimizeDeps.include`,
+ * and Vite resolves them from the app root, where pnpm's strict layout does
+ * not link the plugin unless the app lists it (#1050). Aliased to the copy
+ * the router resolves, which therefore also wins over an app's own
+ * @vitejs/plugin-rsc. Must hold every vendor entry the plugin includes:
+ * optimize-deps-vendor-resolution.test.ts checks the resolved config.
+ */
 export declare function getVendorAliases(): Record<string, string>;

package/dist/types/vite/utils/prerender-utils.d.ts

@@ -18,6 +18,8 @@ export declare function notifyOnError(registry: Map<string, any>, error: unknown
  * URL / handler name for the log line; `elapsed` is the per-entry duration string.
  */
 export declare function resolvePrerenderError(registry: Map<string, any>, error: any, onError: "fail" | "warn", label: string, elapsed: string, phase: "prerender" | "static", routeKey?: string, pathname?: string): void;
+/** Build scratch space, relative to the project root. Never shipped. */
+export declare const RANGO_BUILD_DIR = "node_modules/.rangojs-router-build";
 export declare function resetStagedBuildAssets(projectRoot: string): void;
 /**
  * Write one content-hashed `export default <value>;` asset module into `dir`