@rangojs/router 0.1.1 → 0.4.0

package/dist/types.backup/vite/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API for @rangojs/router/vite
+ *
+ * Exports: rango() plugin factory, poke() dev utility plugin,
+ * and related option types. All other utilities are internal implementation
+ * details consumed via direct imports within the package.
+ */
+export { rango } from "./rango.js";
+export { poke } from "./plugins/refresh-cmd.js";
+export { directoryClientChunks } from "./utils/client-chunks.js";
+export type { RangoNodeOptions, RangoCloudflareOptions, RangoVercelOptions, VercelPresetOptions, RangoOptions, ClientChunks, ClientChunkMeta, HeadScriptsOption, BuildEnvOption, BuildEnvFactory, BuildEnvFactoryContext, BuildEnvResult, } from "./plugin-types.js";

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

@@ -0,0 +1,56 @@
+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`).
+ */
+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.
+ */
+export declare function injectClientDebugFlag(id: string): {
+    code: string;
+    map: null;
+} | null;
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * 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
+ * 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
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export declare function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction;

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

@@ -0,0 +1,298 @@
+/**
+ * Context passed to a buildEnv factory function.
+ * Provides Vite config details for conditional env setup.
+ */
+export interface BuildEnvFactoryContext {
+    /** Vite project root directory. */
+    root: string;
+    /** Vite mode (e.g. "development", "production"). */
+    mode: string;
+    /** Vite command ("serve" for dev, "build" for production). */
+    command: "serve" | "build";
+    /** Router deployment preset. */
+    preset: "node" | "cloudflare" | "vercel";
+}
+/**
+ * Factory function that creates build-time environment bindings.
+ * Called once at plugin startup. Return `dispose` to clean up resources.
+ */
+export type BuildEnvFactory = (ctx: BuildEnvFactoryContext) => Promise<BuildEnvResult> | BuildEnvResult;
+/**
+ * Result of resolving build-time environment bindings.
+ */
+export interface BuildEnvResult {
+    /** Environment bindings available to Prerender/Static handlers via ctx.env. */
+    env: Record<string, unknown>;
+    /** Called after build completes to clean up resources (e.g., miniflare). */
+    dispose?: () => Promise<void> | void;
+}
+/**
+ * Build-time environment configuration for Prerender and Static handlers.
+ *
+ * - `false` (default): no build-time env, `ctx.env` throws.
+ * - `"auto"`: calls `wrangler.getPlatformProxy()` (cloudflare preset only).
+ * - Object: used directly as `ctx.env` during build.
+ * - Factory: called once at startup, must return `{ env, dispose? }`.
+ */
+export type BuildEnvOption = false | "auto" | Record<string, unknown> | BuildEnvFactory;
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+    /** Absolute module id of the "use client" file. */
+    id: string;
+    /** Normalized (posix) module id — convenient for path-based matching. */
+    normalizedId: string;
+    /**
+     * The RSC/server chunk that statically imports this client reference. This is
+     * the key used for the default grouping when no override is supplied: a single
+     * router that statically imports every route yields ONE `serverChunk`, hence
+     * one client chunk for all routes.
+     */
+    serverChunk: string;
+}
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   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.
+ *   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
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   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.
+ *
+ * @default true
+ */
+export type ClientChunks = boolean | ((meta: ClientChunkMeta) => string | undefined);
+/**
+ * Document script strategy. See {@link RangoBaseOptions.headScripts}.
+ */
+export type HeadScriptsOption = "preinit" | "preload";
+/**
+ * Base options shared by all presets
+ */
+interface RangoBaseOptions {
+    /**
+     * Show startup banner. Set to false to disable.
+     * @default true
+     */
+    banner?: boolean;
+    /**
+     * Group client ("use client") components into browser chunks for per-route /
+     * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+     * See {@link ClientChunks}.
+     *
+     * @default true
+     */
+    clientChunks?: ClientChunks;
+    /**
+     * How the document ships its JavaScript.
+     *
+     * - `"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
+     *   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.
+     *
+     * 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
+     * limits are documented in src/ssr/preinit-client-references.ts.
+     *
+     * Wired in the generated virtual SSR entry
+     * (`src/ssr/preinit-client-references.ts` has the mechanism); apps with a
+     * custom SSR entry choose per-handler via `SSRDependencies.headScripts` and
+     * `installClientReferencePreinit`.
+     *
+     * @default "preinit"
+     */
+    headScripts?: HeadScriptsOption;
+    /**
+     * Filter which files route discovery scans, by glob. Paths are matched
+     * root-relative (e.g. `src/routes/**`). `include` restricts discovery to
+     * matching files; `exclude` removes matches (the defaults cover tests, dist,
+     * coverage, etc.). Mirrors the CLI's `--include`/`--exclude`.
+     *
+     * @example
+     * rango({ discovery: { include: ["src/routes/**"] } })
+     */
+    discovery?: {
+        include?: string[];
+        exclude?: string[];
+    };
+    /**
+     * What to do when a `Prerender` route's or `Static` handler's render throws at
+     * build time. Otherwise the route error boundary catches it and the rendered
+     * error page is baked as the artifact, then served as an HTTP 200 — a silent,
+     * user-visible breakage (issue #587). Independent of this setting, a render may
+     * `throw new Skip()` (from `@rangojs/router`) to skip a single URL/handler.
+     *
+     * - `"fail"` (**default**): fail the build, naming the URL/handler and the
+     *   original render error.
+     * - `"warn"`: log a warning and skip baking the artifact — it is never served as a
+     *   baked 200 error page. `"warn"` is a build-unblock, NOT a runtime contract for
+     *   the skipped entry: the route falls through to normal resolution, which may
+     *   render live (its handler is still bundled — e.g. when nothing else baked) or
+     *   404 (once prerender handler eviction has run for other baked entries), so the
+     *   outcome depends on the rest of the build, and a skipped `Static()` handler's
+     *   evicted code can surface as an error. For DEFINED runtime behavior use
+     *   `Passthrough()` (a live fallback) or `throw new Skip()` (an intentional skip);
+     *   otherwise prefer the default `"fail"`.
+     *
+     * @default "fail"
+     */
+    prerender?: {
+        onError?: "fail" | "warn";
+    };
+}
+/**
+ * Options for Node.js deployment (default)
+ */
+export interface RangoNodeOptions extends RangoBaseOptions {
+    /**
+     * Deployment preset. Defaults to 'node' when not specified.
+     */
+    preset?: "node";
+    /**
+     * Path to a host-router entry (a module that calls `createHostRouter()` and
+     * exports the instance) to serve instead of a single `createRouter()` app.
+     * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+     *
+     * Set this when the app is a multi-app host router: auto-discovery otherwise
+     * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+     * When omitted, rango auto-detects a single `createHostRouter()` file if the
+     * app has several `createRouter()` files. The host module must export the
+     * `HostRouter` instance (default export or a named `hostRouter`/`router`
+     * export), not a Cloudflare-style `{ fetch }` object.
+     */
+    hostRouter?: string;
+    /**
+     * Environment bindings available to Prerender and Static handlers at build
+     * time via `ctx.env`. Shared across all prerender invocations for the build.
+     *
+     * `"auto"` is Cloudflare-only (it resolves the wrangler platform proxy), so it
+     * is not accepted on the Node preset — pass an object or a factory instead.
+     *
+     * @default false
+     */
+    buildEnv?: Exclude<BuildEnvOption, "auto">;
+}
+/**
+ * Options for Cloudflare Workers deployment
+ */
+export interface RangoCloudflareOptions extends RangoBaseOptions {
+    /**
+     * Deployment preset for Cloudflare Workers.
+     * When using cloudflare preset:
+     * - @vitejs/plugin-rsc IS still added by rango(), but with `serverHandler: false`
+     *   (the cloudflare plugin owns the RSC worker/server entry); only `client` and
+     *   `ssr` virtual entries are configured, no rsc entry
+     * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
+     * - Browser and SSR use virtual entries
+     * - Build-time manifest generation is auto-detected from the resolved RSC environment config
+     */
+    preset: "cloudflare";
+    /**
+     * Environment bindings available to Prerender and Static handlers at build
+     * time via `ctx.env`. Shared across all prerender invocations for the build.
+     *
+     * `"auto"` resolves the Cloudflare platform proxy via wrangler
+     * `getPlatformProxy()`.
+     *
+     * @default false
+     */
+    buildEnv?: BuildEnvOption;
+}
+/**
+ * Per-function knobs for the Vercel deployment, written into the generated
+ * `.vc-config.json` (and `config.json` for `functionName`).
+ */
+export interface VercelPresetOptions {
+    /** Node runtime for the function. @default "nodejs22.x" */
+    runtime?: string;
+    /** Max execution time in seconds. @default 30 */
+    maxDuration?: number;
+    /** Function memory in MB (platform default when omitted). */
+    memory?: number;
+    /** Regions to pin the function to (platform default when omitted). */
+    regions?: string[];
+    /**
+     * Function name — the `<name>.func` directory and the `config.json` route
+     * destination. @default "index"
+     */
+    functionName?: string;
+}
+/**
+ * Options for Vercel Functions deployment.
+ *
+ * Builds like the node preset (Vercel runs Node Functions, not Workers): rango
+ * owns the RSC entry, `process.env.NODE_ENV` is folded for the build, and after
+ * the build a `.vercel/output` directory (Build Output API v3) is assembled from
+ * `dist/` — a single streaming Node Function plus the static client assets. The
+ * app must install `@vercel/functions` (used by `VercelCacheStore` and the
+ * generated function launcher).
+ */
+export interface RangoVercelOptions extends RangoBaseOptions {
+    /**
+     * Deployment preset for Vercel Functions.
+     */
+    preset: "vercel";
+    /**
+     * Path to a host-router entry (a module that calls `createHostRouter()` and
+     * exports the instance) to serve instead of a single `createRouter()` app.
+     * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+     *
+     * Set this when the app is a multi-app host router: auto-discovery otherwise
+     * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+     * When omitted, rango auto-detects a single `createHostRouter()` file if the
+     * app has several `createRouter()` files. The host module must export the
+     * `HostRouter` instance (default export or a named `hostRouter`/`router`
+     * export), not a Cloudflare-style `{ fetch }` object. The Vercel function then
+     * runs `hostRouter.match()` for every request (single-function deploy).
+     */
+    hostRouter?: string;
+    /**
+     * Environment bindings available to Prerender and Static handlers at build
+     * time via `ctx.env`. `"auto"` is Cloudflare-only; pass an object or a factory.
+     *
+     * @default false
+     */
+    buildEnv?: Exclude<BuildEnvOption, "auto">;
+    /**
+     * Vercel function configuration written into the Build Output.
+     */
+    vercel?: VercelPresetOptions;
+}
+/**
+ * Options for rango() Vite plugin
+ */
+export type RangoOptions = RangoNodeOptions | RangoCloudflareOptions | RangoVercelOptions;
+export {};

package/dist/types.backup/vite/plugins/cjs-to-esm.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+/**
+ * Transform CJS vendor files from @vitejs/plugin-rsc to ESM for browser compatibility.
+ * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
+ */
+export declare function createCjsToEsmPlugin(): Plugin;

package/dist/types.backup/vite/plugins/client-ref-dedup.d.ts

@@ -0,0 +1,40 @@
+import type { Plugin } from "vite";
+/**
+ * Extract the bare package name from an absolute node_modules path.
+ * Handles scoped packages (@org/name) and nested node_modules.
+ * Returns null if the path doesn't contain a valid package reference.
+ *
+ * NOTE: This is a lossy transformation. It maps a specific submodule path
+ * (e.g., pkg/internal/context.js) to the package root (pkg). The load()
+ * hook then re-exports via the bare specifier, which resolves to the
+ * package entry point. This works for packages that barrel-export their
+ * "use client" symbols from the root, which covers the common case
+ * (component libraries like @mantine/core, @chakra-ui/react, etc.).
+ * Packages whose client symbols are only available from deep subpaths
+ * (not re-exported from the root) would lose those symbols after the
+ * rewrite. A more precise approach would resolve through the package's
+ * exports map to find the correct entry point, but that adds significant
+ * complexity for a rare edge case.
+ * See: https://github.com/cloudflare/vinext/pull/413
+ */
+export declare function extractPackageName(absolutePath: string): string | null;
+/**
+ * Vite plugin that deduplicates client references from third-party packages
+ * in dev mode.
+ *
+ * When @vitejs/plugin-rsc encounters a "use client" submodule inside a
+ * package imported from a server component, it creates a
+ * client-in-server-package-proxy virtual module that re-exports from the
+ * absolute file path. In the client environment, this absolute path bypasses
+ * Vite's pre-bundling, while direct client imports of the same package go
+ * through .vite/deps/. Two separate module instances are created, breaking
+ * React contexts (createContext runs twice, provider/consumer mismatch).
+ *
+ * This plugin intercepts absolute node_modules imports from proxy modules
+ * in the client environment and rewrites them to bare specifier imports
+ * that go through pre-bundling, ensuring a single module instance.
+ *
+ * Dev-only: production builds use the SSR manifest which handles module
+ * identity correctly.
+ */
+export declare function clientRefDedup(): Plugin;

package/dist/types.backup/vite/plugins/client-ref-hashing.d.ts

@@ -0,0 +1,35 @@
+import type { Plugin } from "vite";
+/**
+ * Compute the production SHA-256 hash for a dev-mode client reference key.
+ * Mirrors the hashing logic in @vitejs/plugin-rsc's build mode:
+ *   - Local files: hashString(toRelativeId(id)) where toRelativeId = relative(root, id)
+ *   - Package proxies: hashString(packageSource)
+ *   - client-in-server-package proxies: hashString(relative(root, decodedAbsPath))
+ *
+ * Returns the input unchanged if it doesn't match a known dev-mode pattern
+ * (e.g., already a production hash).
+ */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export declare function hashRefKey(relativeId: string): string;
+export declare function computeProductionHash(projectRoot: string, refKey: string): string;
+/**
+ * Transform source code by replacing dev-mode client reference keys with
+ * production hashes. Exported for testing; used internally by hashClientRefs.
+ * Returns null if no replacements were made.
+ */
+export declare function transformClientRefs(code: string, projectRoot: string): string | null;
+/**
+ * Vite plugin that rewrites registerClientReference() calls in the RSC
+ * environment, replacing dev-mode reference keys with production hashes.
+ *
+ * This runs AFTER the RSC plugin's transform so the Flight serializer
+ * naturally emits production IDs, eliminating the need for post-build
+ * regex replacement of Flight payloads.
+ */
+export declare function hashClientRefs(projectRoot: string): Plugin;

package/dist/types.backup/vite/plugins/cloudflare-protocol-stub.d.ts

@@ -0,0 +1,64 @@
+import type { Plugin } from "vite";
+/**
+ * `globalThis` key the `cloudflare:workers` stub reads to populate its
+ * `env` export. Router discovery sets this to the resolved `buildEnv`
+ * proxy (from `wrangler.getPlatformProxy()` when `buildEnv: "auto"` is
+ * configured, or a user-supplied object otherwise) before importing the
+ * worker entry, and clears it after discovery disposes the proxy. When
+ * unset, the stub's `env` falls back to `{}`.
+ *
+ * Using `globalThis` is the only cross-module bridge that works here:
+ * the stub's `load` hook returns source text, not a live closure, but
+ * the stub module is evaluated in the same Node process as the
+ * discovery plugin — so reading a global at module-evaluation time
+ * reaches whatever the plugin assigned there. A symbol key would be
+ * cleaner in-process but awkward to name from the stub source.
+ *
+ * @internal
+ */
+export declare const BUILD_ENV_GLOBAL_KEY = "__rango_build_env__";
+/**
+ * Stubs `cloudflare:*` imports for the discovery-time Node Vite server.
+ *
+ * Discovery only evaluates user module top-level code — it never invokes
+ * DurableObject / WorkerEntrypoint / Workflow handlers — so empty base
+ * classes are enough for `class X extends DurableObject {}` declarations
+ * to load in Node, where `cloudflare:*` is otherwise unresolvable.
+ *
+ * Interception point: a transform hook parses source with Rollup's
+ * plugin-context parser (`this.parse`) and rewrites only real import
+ * specifier spans (`import ... from "cloudflare:xxx"`,
+ * `import("cloudflare:xxx")`, `export ... from "cloudflare:xxx"`) to a
+ * plain virtual module name (`virtual:rango-cloudflare-stub-xxx`).
+ * This must be done in transform because Vite's module runner routes
+ * URL-scheme specifiers straight to Node's native ESM loader without
+ * consulting plugin `resolveId` hooks. Using the AST (instead of a
+ * text regex or a permissive lexer) guarantees that strings,
+ * comments, and template literals that merely contain import-like
+ * text are never mutated — the walker only looks at the four import
+ * node types.
+ *
+ * The transform runs on user source AND on compiled node_modules
+ * output: real-world CF packages (e.g. the Cloudflare Agents SDK)
+ * ship compiled JS that contains `import ... from "cloudflare:email"`
+ * and similar, so excluding node_modules would leave those imports
+ * unrewritten. Cost is small because the early exit (`code.includes`)
+ * skips files with no cloudflare: mention.
+ *
+ * The plugin intentionally runs at Vite's default ordering (no
+ * `enforce: "pre"`) so TS/JSX has already been compiled to plain JS
+ * by the time `this.parse` runs — acorn doesn't understand
+ * non-standard syntax.
+ *
+ * `cloudflare:workers`, `cloudflare:email`, `cloudflare:sockets`, and
+ * `cloudflare:workflows` each get curated stubs with the well-known
+ * symbols that appear in top-level `extends` positions. Any other
+ * `cloudflare:*` specifier falls back to an empty default export —
+ * discovery never executes the handlers, so an empty module is safe
+ * for anything the graph pulls in transitively.
+ *
+ * Only registered in the discovery temp server, not the user's runtime
+ * config.
+ * @internal
+ */
+export declare function createCloudflareProtocolStubPlugin(): Plugin;

package/dist/types.backup/vite/plugins/expose-action-id.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that exposes action IDs on server reference functions.
+ *
+ * When React Server Components creates server references via createServerReference(),
+ * the action ID (format: "hash#actionName") is passed as the first argument but not
+ * exposed on the returned function. This plugin transforms the output to attach
+ * the $id property to each server reference function, enabling the router to
+ * identify which action was called during revalidation.
+ *
+ * Server bundles (RSC/SSR) get file paths in $id for filtering (e.g., "src/actions.ts#add").
+ * Client bundles keep hashed IDs for security (e.g., "ec387bc704d4#add").
+ *
+ * Works in:
+ * - Build mode: uses renderChunk to transform bundled chunks
+ * - Dev mode: uses transform with enforce:"post" to transform after RSC plugin
+ */
+export declare function exposeActionId(): Plugin;

package/dist/types.backup/vite/plugins/expose-id-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Normalize path to forward slashes.
+ */
+export declare function normalizePath(p: string): string;
+export declare function hashId(filePath: string, exportName: string): string;
+export declare function makeStubId(filePath: string, exportName: string, isBuild: boolean): string;
+export declare function hashInlineId(filePath: string, fnName: string, index: number): string;
+export interface DetectedImports {
+    loader: boolean;
+    handle: boolean;
+    locationState: boolean;
+    prerenderHandler: boolean;
+    staticHandler: boolean;
+    router: boolean;
+    any: boolean;
+}
+export declare function buildExportMap(program: any): Map<string, string[]>;
+export declare function detectImports(code: string): DetectedImports;
+export declare function skipStringOrComment(code: string, pos: number): number;
+export declare function findMatchingParen(code: string, startPos: number): number;
+export declare function countArgs(code: string, startPos: number, endPos: number): number;
+export declare function findStatementEnd(code: string, pos: number): number;
+export { escapeRegExp } from "../../regex-escape.js";
+/**
+ * Given an index pointing just past a `create*` callee identifier, return the
+ * index of the call's opening `(`, accounting for an optional generic type
+ * argument list `<...>` with arbitrarily nested `<>`. Returns -1 when the next
+ * non-trivia token is neither `<` nor `(` (i.e. not a call site).
+ *
+ * Replaces the single-level `<[^>]*>` regex assumption, which stopped at the
+ * first `>` and so never reached `(` for `createRouter<Config<Env>>(`.
+ *
+ * Whitespace, comments, and strings between the callee and `(` are skipped via
+ * skipStringOrComment. The `<...>` scan only balances angle brackets; it does
+ * not attempt to parse full TS type syntax (sufficient for locating the paren).
+ */
+export declare function findCallParenAfterGenerics(code: string, afterCalleeIndex: number): number;

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

@@ -0,0 +1,19 @@
+import type { CreateExportBinding } from "./types.js";
+export declare function isExportOnlyFile(code: string, bindings: CreateExportBinding[]): boolean;
+export declare function countCreateCallsForNames(code: string, fnNames: string[]): number;
+export declare function offsetToLineColumn(code: string, index: number): {
+    line: number;
+    column: number;
+};
+export declare function findUnsupportedCreateCallSites(code: string, fnNames: string[], supportedBindings: CreateExportBinding[]): Array<{
+    line: number;
+    column: number;
+}>;
+export declare function getImportedFnNames(code: string, importedName: string): string[];
+export declare function getCalledIdentifierFromCall(callExpr: any): string | null;
+export declare function collectCreateExportBindingsFallback(code: string, fnNames: string[]): CreateExportBinding[];
+export declare function collectCreateExportBindings(code: string, fnNames: string[], program?: any): CreateExportBinding[];
+export declare function buildUnsupportedShapeWarning(filePath: string, fnName: string, sites?: Array<{
+    line: number;
+    column: number;
+}>): string;

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

@@ -0,0 +1,10 @@
+import MagicString from "magic-string";
+import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
+export declare function transformHandles(bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;
+export declare function transformLocationState(bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;
+export declare function generateWholeFileStubs(cfg: HandlerTransformConfig, bindings: CreateExportBinding[], code: string, filePath: string, isBuild: boolean): {
+    code: string;
+    map: null;
+} | null;
+export declare function stubHandlerExprs(cfg: HandlerTransformConfig, bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;
+export declare function transformHandlerIds(cfg: HandlerTransformConfig, bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;

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

@@ -0,0 +1,8 @@
+import type MagicString from "magic-string";
+import type { CreateExportBinding } from "./types.js";
+export declare function hasCreateLoaderImport(code: string): boolean;
+export declare function generateClientLoaderStubs(bindings: CreateExportBinding[], code: string, filePath: string, isBuild: boolean): {
+    code: string;
+    map?: undefined;
+} | null;
+export declare function transformLoaders(bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;

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

@@ -0,0 +1,13 @@
+import type { Plugin } from "vite";
+import MagicString from "magic-string";
+export declare function transformRouter(code: string, filePath: string, routerFnNames: string[], absolutePath?: string, warn?: (message: string) => void): {
+    code: string;
+    map: ReturnType<MagicString["generateMap"]>;
+} | null;
+/**
+ * Inject stable $$id into createRouter() calls at compile time.
+ * This must be a separate plugin without enforce:"post" because running
+ * at "post" priority changes Vite's dep optimization timing and can cause
+ * ERR_OUTDATED_OPTIMIZED_DEP / React dual-instance issues.
+ */
+export declare function exposeRouterId(): Plugin;

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

@@ -0,0 +1,29 @@
+export interface HandlerTransformConfig {
+    fnName: string;
+    brand: string;
+}
+export interface CreateExportBinding {
+    localName: string;
+    exportNames: string[];
+    callExprStart: number;
+    callOpenParenPos: number;
+    callCloseParenPos: number;
+    argCount: number;
+    statementEnd: number;
+}
+export interface StrictCreateTransformConfig {
+    fnName: "createLoader" | "createHandle" | "createLocationState";
+}
+export declare const PRERENDER_CONFIG: HandlerTransformConfig;
+export declare const STATIC_CONFIG: HandlerTransformConfig;
+export declare const STRICT_CREATE_CONFIGS: StrictCreateTransformConfig[];
+export interface ExposeInternalIdsApi {
+    /** Tracks absolute module IDs that contain prerender handler exports.
+     *  key: absolute module ID (filesystem path)
+     *  value: array of export names (e.g., ["ArticlesIndex", "ArticleDetail"]) */
+    prerenderHandlerModules: Map<string, string[]>;
+    /** Tracks absolute module IDs that contain static handler exports.
+     *  key: absolute module ID (filesystem path)
+     *  value: array of export names (e.g., ["DocsNav", "DocShell"]) */
+    staticHandlerModules: Map<string, string[]>;
+}