@rangojs/router 0.20.0 → 0.22.0

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

@@ -22,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.
@@ -36,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/bundle-analysis.d.ts

@@ -6,12 +6,15 @@
 export declare function findMatchingParenInBundle(code: string, openParenPos: number): number;
 /**
  * Scan a bundled chunk for handler exports and extract their names + $$id values.
- * Optionally detects passthrough flag. @internal Exported for testing only.
+ * Optionally detects the passthrough flag by parsing the call body, and marks
+ * onDemand from the authoritative discovery-derived handlerId set.
+ * @internal Exported for testing only.
  */
-export declare function extractHandlerExportsFromChunk(chunkCode: string, handlerModules: Map<string, string[]>, fnName: string, detectPassthrough: boolean): Array<{
+export declare function extractHandlerExportsFromChunk(chunkCode: string, handlerModules: Map<string, string[]>, fnName: string, detectPassthrough: boolean, onDemandHandlerIds?: ReadonlyMap<string, string>): Array<{
     name: string;
     handlerId: string;
     passthrough: boolean;
+    onDemand: boolean;
 }>;
 /**
  * Evict handler code from a bundled chunk, replacing full call expressions with stubs.
@@ -22,6 +25,7 @@ export declare function evictHandlerCode(code: string, exports: Array<{
     name: string;
     handlerId: string;
     passthrough?: boolean;
+    onDemand?: boolean;
 }>, fnName: string, brand: string): {
     code: string;
     savedBytes: number;

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

@@ -58,6 +58,8 @@ 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

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`