@rivetjs/router 0.0.0-stage → 0.1.0-alpha.1

package/build/vite.js

@@ -0,0 +1,861 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Vite plugin: scan routes, write `.rivet/` codegen, compile it with the Rivet plugin (resume mode
+// for server/static apps), default the build inputs, and serve requests in dev.
+import { lstat, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { rivet, _factsResolve, declaredServerOnly, isServerOnly, serverOnlyStub, } from "@rivetjs/compiler/vite";
+import { updateEditorManifest } from "@rivetjs/compiler/editor";
+import { scanRoutes, _serverExportsOf } from "./routes.js";
+import { generate } from "./codegen.js";
+import { normalizeBase } from "../shared/base.js";
+import { slashPath } from "../shared/slash.js";
+import { DATA_PARAM } from "../shared/data.js";
+import { compileRules } from "../server/route-cache.js";
+/** Build-time helper for other Vite plugins (docs-kit example frames): one merged sheet per stylesheet list. */
+export { mergeRouteCSS } from "./route-css.js";
+import { bundleRouteCSS, devRouteCSS, INLINE_CSS, inlineCSS, mergeRouteCSS, ROUTE_CSS } from "./route-css.js";
+import { devHandler, devReport, listenClientErrors } from "./dev-errors.js";
+import { lazyRowsBuild, lazyRowsHarness } from "./lazy-rows.js";
+import { analyzeReach, serverOnlyOption, RV_REACH } from "./reach.js";
+import { compileRoutes } from "@rivetjs/runtime/router/server";
+import { adapterOptions, targetBuildConfig, targetEntryPlugin } from "../adapters/target-build.js";
+/** The router's own base-path module (its `BASE` reads Vite's `BASE_URL`). */
+const BASE_MODULE = fileURLToPath(new URL("../shared/base.js", import.meta.url));
+/** The router's trailing-slash module (its `TRAILING_SLASH` constant is rewritten when the option is set). */
+const SLASH_MODULE = fileURLToPath(new URL("../shared/slash.js", import.meta.url));
+const SLASH_DEFAULT = '"ignore" as TrailingSlash';
+/** The shell cache loader (`SHELL_BUILD`, rewritten to an `import()` when a route rule has `shell`). */
+const SHELL_MODULE = fileURLToPath(new URL("../server/shell-build.js", import.meta.url));
+/** `SHELL_BUILD`'s declaration in the source (`.ts`, with its type cast) and in the published `.js` (cast stripped). */
+const SHELL_DEFAULT = /export const SHELL_BUILD = undefined(?: as [^;]+)?;/;
+/** The shell cache module the rewritten loader imports (by file path: also what keeps it in the published package). */
+const SHELL_CACHE = fileURLToPath(new URL("../server/shell-cache.js", import.meta.url));
+const posix = (path) => path.split(sep).join("/");
+const EMPTY = "\0rivet-router-empty";
+/** Client build: a document route's page module as `.rivet/app.tsx` imports it (no browser code for the page). */
+const DOCUMENT_PAGE = "\0rivet-document-page:";
+/** Browser stand-in of a server-only module imported only from document routes' graphs (`serverOnlyStub`). */
+const STAND_IN = "\0rivet-server-only:";
+/** The file behind a module id (virtual compiler parts `\0rivet-resume-part:/abs/file.tsx?…` included), no query. */
+const fileOf = (id) => (id.startsWith("\0") ? id.slice(id.indexOf(":") + 1) : id).split("?")[0];
+/** Write generated files whose contents changed; returns whether anything changed. */
+async function sync(dir, files) {
+    await mkdir(dir, { recursive: true });
+    let changed = false;
+    for (const [name, contents] of Object.entries(files)) {
+        const path = join(dir, name);
+        const current = await readFile(path, "utf8").catch(() => null);
+        if (current === contents)
+            continue;
+        await writeFile(path, contents);
+        changed = true;
+    }
+    return changed;
+}
+const SOURCE = /\.[cm]?[jt]sx?$/;
+const FEATURES = [
+    ["searchParams", /\b(?:useSearchParams|SearchParams)\b/],
+    ["navigate", /\b(?:navigate|invalidate|revalidate|setSearchParams)\b/],
+    ["params", /\buseParams\b/],
+    ["activeLinks", /<Link\b[^>]*?\sactive\b/],
+    ["prefetch", /\bprefetch\s*=\s*\{?\s*["'](?:document|prerender)["']/],
+];
+/** Every `RouterUsage` flag (FEATURES + `forms`). */
+const USAGE = [...FEATURES.map(([name]) => name), "forms"];
+const none = () => ({ searchParams: false, navigate: false, forms: false, params: false, activeLinks: false, prefetch: false });
+/** Features one source text uses: names in a file importing `@rivetjs/router` (`URLSearchParams` does not count). */
+function featuresOf(text, into) {
+    // Forms (enhanced submits follow redirects / revalidate through the router): `@rivetjs/forms`, or ui's `Form`.
+    if (text.includes("@rivetjs/forms") || (text.includes("@rivetjs/ui") && /\bForm\b/.test(text)))
+        into.forms = into.navigate = true;
+    if (!text.includes("@rivetjs/router"))
+        return;
+    for (const [name, pattern] of FEATURES)
+        if (pattern.test(text))
+            into[name] = true;
+}
+/** Never sources: dot entries (`.rivet`, `.git`), `node_modules`, build output (`dist`, `dist-<lane>`, `dist.x`). */
+const OUTPUT = /^(?:\.|node_modules$|dist(?:$|[-_.]))/;
+async function scan(dir, into, seen) {
+    if (seen.has(dir))
+        return;
+    seen.add(dir);
+    // Concurrent builds may create or remove files mid-walk: a vanished entry is skipped (ENOENT).
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!OUTPUT.test(entry.name))
+                await scan(path, into, seen);
+        }
+        else if (!entry.name.startsWith(".") && SOURCE.test(entry.name)) {
+            const text = await readFile(path, "utf8").catch((error) => {
+                if (error.code === "ENOENT" || error.code === "EISDIR")
+                    return "";
+                throw error;
+            });
+            featuresOf(text, into);
+        }
+    }
+}
+/**
+ * Which router features the project's sources use: every source under `root` (skipping
+ * `node_modules`, `dist` and dot directories) plus the sources of linked (workspace / `npm link`)
+ * dependencies of `root/package.json`, except `@rivetjs/*` packages. Text based: a name that appears
+ * in a file importing `@rivetjs/router` counts (false positives only cost bytes); published
+ * dependencies are not scanned (set `rivetRouter({ navigate, params, searchParams })`).
+ */
+export async function routerUsage(root, options = {}) {
+    const usage = none(), 
+    // `exclude`: absolute directories never walked (the Vite build `outDir`, the generated `.rivet/`).
+    seen = new Set((options.exclude ?? []).map((dir) => resolve(root, dir)).filter((dir) => dir !== resolve(root)));
+    await scan(root, usage, seen);
+    const pkg = JSON.parse(await readFile(join(root, "package.json"), "utf8").catch(() => "{}"));
+    for (const name of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
+        if (name.startsWith("@rivetjs/"))
+            continue;
+        for (let dir = root;; dir = dirname(dir)) {
+            const path = join(dir, "node_modules", name);
+            const link = await lstat(path).catch(() => null);
+            if (link?.isSymbolicLink())
+                await scan(await realpath(path), usage, seen);
+            if (link || dir === dirname(dir))
+                break;
+        }
+    }
+    return usage;
+}
+/** Regenerate `.rivet/` for a project root; returns the resume modules and whether files changed. */
+export async function generateRoutes(root, options = {}) {
+    const routesDir = posix(options.routes ?? "src/routes");
+    const outDir = posix(options.outDir ?? ".rivet");
+    const table = await scanRoutes(resolve(root, routesDir));
+    const generated = generate(table, {
+        routesDir,
+        outDir,
+        document: posix(options.document ?? "src/document.ts"),
+        mode: options.mode ?? "server",
+        ...(options.head ? { head: options.head } : {}),
+        ...(options.transitions ? { transitions: options.transitions } : {}),
+        ...(options.announce === false ? { announce: false } : {}),
+        ...(options.base ? { base: options.base } : {}),
+        ...(options.searchParams ? { searchParams: true } : {}),
+        ...(options.navigate ? { navigate: true } : {}),
+        ...(options.forms ? { forms: true } : {}),
+        ...(options.params ? { params: true } : {}),
+        ...(options.activeLinks ? { activeLinks: true } : {}),
+        ...(options.prefetch ? { prefetch: options.prefetch } : {}),
+        ...(options.prefetchEagerness ? { prefetchEagerness: options.prefetchEagerness } : {}),
+        ...(options.prefetchPaths === false ? { prefetchPaths: false } : {}),
+        ...(options.trailingSlash && options.trailingSlash !== "ignore" ? { trailingSlash: options.trailingSlash } : {}),
+        ...(options.preload?.background !== undefined ? { preloadBackground: options.preload.background } : {}),
+        ...(options.routeRules && Object.keys(options.routeRules).length ? { routeRules: options.routeRules } : {}),
+        ...(options.clientRouter !== undefined ? { clientRouter: options.clientRouter } : {}),
+        ...(options.documents?.length ? { documents: options.documents } : {}),
+        ...(options.derived ? { derived: true } : {}),
+    });
+    const changed = await sync(resolve(root, outDir), generated.files);
+    // No router contexts: the compiler's default resume entry (drop a stale generated one).
+    const resumeEntry = "entry.resume.ts" in generated.files;
+    if (!resumeEntry)
+        await rm(resolve(root, outDir, "entry.resume.ts"), { force: true });
+    // Editors: route ids/patterns/files for links (go to route, unknown-route warnings). Best effort.
+    try {
+        const routes = table.routes.filter((route) => route.page).map((route) => ({ id: route.id, pattern: route.pattern, file: routesDir + "/" + route.page }));
+        updateEditorManifest(root, { routesDir, routes });
+    }
+    catch { }
+    return { table, resumeModules: generated.resumeModules, changed, resumeEntry };
+}
+/** Routes-relative modules that declare server exports (in-file pages/layouts, plain `.ts` endpoints). */
+function serverFiles(table) {
+    const files = new Set();
+    for (const route of table.routes)
+        for (const module of [route, ...route.layouts]) {
+            if (module.inline && module.page)
+                files.add(module.page);
+            // Live pages (`export const live = true`) as `live:<page>`: toggling the flag regenerates the App.
+            if (module.live && module.page)
+                files.add("live:" + module.page);
+            if (module.server && !/\.server\.[cm]?[jt]s$/.test(module.server))
+                files.add(module.server);
+        }
+    return files;
+}
+/** Root-relative page/layout/special modules of a table: compiled with `serverExports`. */
+function routeModules(table, routesDir) {
+    const files = new Set();
+    for (const route of table.routes)
+        for (const module of [route, ...route.layouts]) {
+            if (module.page)
+                files.add(module.page);
+            // Plain `.ts` endpoints too (T7): a page importing a constant from one gets its handlers split out.
+            if (module.server && !/\.server\.[cm]?[jt]s$/.test(module.server))
+                files.add(module.server);
+        }
+    return [...files].map((file) => posix(join(routesDir, file)));
+}
+/**
+ * File routes for Vite: the routing plugin plus the Rivet compiler configured for the generated app.
+ * `vite build` builds the browser side into `dist/client`; `vite build --ssr` the server entry into
+ * `dist/server` (both overridable through `build`). `vite` serves pages through the same handler.
+ * In `csr` mode the client build also writes `index.html` and there is no server build.
+ */
+const STATIC_DATA = /^([^?#]*\/)_data\.json(?:[?#]|$)/;
+/**
+ * Dev server, static mode: a `<page>/_data.json` request (the file the static adapter prerenders
+ * beside each page, `client/index.ts` `dataURL(url, "static")`) becomes that page's data request,
+ * as `adapters/static.ts` `prerender` renders it: the page path in its canonical form, no query.
+ */
+function staticData(req, slash) {
+    const hit = STATIC_DATA.exec(req.url ?? "");
+    if (!hit || (req.method !== "GET" && req.method !== "HEAD"))
+        return;
+    const page = hit[1] === "/" ? "/" : hit[1].slice(0, -1);
+    req.url = slashPath(page, slash) + "?" + DATA_PARAM + "=data";
+    req.headers.accept = "application/json";
+}
+/** The router's Vite plugins: file routes, typed routes, server code split, data requests and build adapters. */
+export function rivetRouter(options = {}) {
+    const routesDir = options.routes ?? "src/routes";
+    const outDir = options.outDir ?? ".rivet";
+    const styles = options.styles ?? [];
+    const mode = options.mode ?? "server";
+    const documentPath = options.document ?? "src/document.ts";
+    const codegen = {
+        routes: routesDir,
+        outDir,
+        document: documentPath,
+        mode,
+        transitions: options.transitions,
+        announce: options.announce,
+        ...(options.trailingSlash ? { trailingSlash: options.trailingSlash } : {}),
+        ...(options.prefetchEagerness ? { prefetchEagerness: options.prefetchEagerness } : {}),
+        ...(options.prefetchPaths === false ? { prefetchPaths: false } : {}),
+        ...(options.preload ? { preload: options.preload } : {}),
+        ...(options.routeRules ? { routeRules: options.routeRules } : {}),
+        ...(options.clientRouter !== undefined ? { clientRouter: options.clientRouter } : {}),
+        // Derived resume model (M2 R5): the generated `Root` boundary carries the route payload as data.
+        ...(options.resume?.model === "derived" && mode !== "csr" ? { derived: true } : {}),
+    };
+    if (options.routeRules !== undefined) {
+        // Checked at config time (same checks as at server start, except the origin `isr` needs: a server option), and
+        // kept to JSON (the server entry inlines it).
+        compileRules(options.routeRules, true);
+        const json = (value) => typeof value === "string" ||
+            typeof value === "boolean" ||
+            (typeof value === "number" && Number.isFinite(value)) ||
+            (Array.isArray(value)
+                ? value.every(json)
+                : typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every(json));
+        if (!json(options.routeRules))
+            throw new Error("rivetRouter: routeRules must be JSON data (numbers, strings, booleans; use isr: true for no expiry)");
+    }
+    const background = options.preload?.background;
+    if (background !== undefined && !(Number.isFinite(background) && background >= 0))
+        throw new Error(`rivetRouter: preload.background must be a non-negative number of bytes (got ${JSON.stringify(background)})`);
+    if (options.prefetch !== undefined && typeof options.prefetch !== "boolean" && options.prefetch !== "document" && options.prefetch !== "prerender")
+        throw new Error(`rivetRouter: prefetch must be a boolean, "document" or "prerender" (got ${JSON.stringify(options.prefetch)})`);
+    if (options.prefetchEagerness !== undefined && !["conservative", "moderate", "eager"].includes(options.prefetchEagerness))
+        throw new Error(`rivetRouter: prefetchEagerness must be "conservative", "moderate" or "eager" (got ${JSON.stringify(options.prefetchEagerness)})`);
+    if (options.prefetchPaths !== undefined && typeof options.prefetchPaths !== "boolean")
+        throw new Error(`rivetRouter: prefetchPaths must be a boolean (got ${JSON.stringify(options.prefetchPaths)})`);
+    const inlineOption = options.inlineStylesheets;
+    if (inlineOption !== undefined &&
+        !(typeof inlineOption === "string"
+            ? ["auto", "always", "never"].includes(inlineOption)
+            : typeof inlineOption === "object" &&
+                inlineOption !== null &&
+                Object.keys(inlineOption).every((key) => key === "maxTotalBrotli") &&
+                (inlineOption.maxTotalBrotli === undefined || (Number.isSafeInteger(inlineOption.maxTotalBrotli) && inlineOption.maxTotalBrotli >= 0))))
+        throw new Error(`rivetRouter: inlineStylesheets must be "auto", "always", "never" or { maxTotalBrotli: <bytes> } (got ${JSON.stringify(inlineOption)})`);
+    const serverOnly = serverOnlyOption(options.serverOnly);
+    const slash = options.trailingSlash ?? "ignore";
+    const shellBuild = Object.values(options.routeRules ?? {}).some((rule) => Boolean(rule?.shell));
+    if (slash !== "ignore" && slash !== "never" && slash !== "always")
+        throw new Error(`rivetRouter: trailingSlash must be "ignore", "never" or "always" (got ${JSON.stringify(slash)})`);
+    // Filled in `config`, which runs before the compiler plugin reads it in `configResolved`.
+    // Page chunks prefetch on navigation intent, not at idle (the App chunk loads eagerly for clicks).
+    // The generated App prefetches the hovered route's page itself: page chunks are not chunk lazies (`lazyOwned`).
+    const resume = {
+        lazy: "intent",
+        ...options.resume,
+        lazyOwned: [...(options.resume?.lazyOwned ?? []), posix(join(outDir, "app.tsx"))],
+        modules: [...(options.resume?.modules ?? [])],
+        dev: options.dev?.resume !== false,
+        // Every app component module a route imports resumes without being listed in `resume.modules`.
+        appModules: options.resume?.appModules ?? true,
+        // Lazy rows measurement builds (`RIVET_LAZY_ROWS=on` + the harness flag of the lazy-rows tools): the option on.
+        ...(lazyRowsBuild() ? { lazyRows: true } : {}),
+        // Derived model (M2 R5): `.rivet/app.tsx`'s default export (`Root`) is an independent root boundary (its props =
+        // the route payload as data), like a route module's default export.
+        ...(options.resume?.model === "derived" && mode !== "csr" ? { roots: [...(options.resume.roots ?? []), posix(join(outDir, "app.tsx"))] } : {}),
+    };
+    // The generated resume entry (when there is one) provides the router's contexts (navigation state,
+    // search params) to resumed regions.
+    const ownEntry = resume.entry;
+    // Dev resumed pages read it live (the compiler's dev manifest): kept in step on regeneration too.
+    const entryFor = (generated) => {
+        if (ownEntry)
+            resume.entry = ownEntry;
+        else if (generated)
+            resume.entry = posix(join(outDir, "entry.resume.ts"));
+        else
+            delete resume.entry;
+    };
+    let root = process.cwd();
+    let table = { routes: [] };
+    // Server reach (`build/reach.ts`): computed in `configResolved` (before any module compiles), re-run in dev after edits.
+    let reach = null, reachDirty = false, reachRun = Promise.resolve(), resolvedConfig = null, resolver = null, patterns = [...serverOnly.modules], building = false;
+    // Document routes' page files (absolute → routes-relative), client builds.
+    let documentPages = new Map();
+    /** Walk the routes' browser graphs; true when the document routes changed (codegen input). */
+    const analyze = async () => {
+        if (!resolvedConfig || mode === "csr")
+            return false;
+        resolver ??= resolvedConfig.createResolver();
+        const resolveFor = resolver;
+        reach = await analyzeReach({
+            root,
+            routesDir: resolve(root, routesDir),
+            table,
+            resolve: (spec, importer) => resolveFor(spec, importer, false, false),
+            serverOnly: patterns,
+            reach: serverOnly.reach,
+            routeModules: new Set(routeModules(table, routesDir).map((file) => resolve(root, file))),
+            config: resolvedConfig,
+        });
+        documentPages = new Map([...reach.documents.keys()].map((page) => [resolve(root, routesDir, page), page]));
+        const documents = [...reach.documents.keys()].sort();
+        if (documents.join("\0") === (codegen.documents ?? []).join("\0"))
+            return false;
+        codegen.documents = documents;
+        return true;
+    };
+    const devtools = options.devtools ?? true;
+    const css = options.css ? { css: options.css } : {};
+    // Filled in `config` and on route changes: in-file server exports leave the browser build.
+    const serverExports = { modules: [] };
+    let inFile = new Set(); // routes-relative files with server exports + `live:<page>` (dev change detection)
+    // Dev regenerations run one at a time (two writing `.rivet/` at once race); closing the server
+    // waits for the running one and drops queued ones.
+    let regenerations = Promise.resolve();
+    let closed = false;
+    const icons = options.staticIcons === undefined ? {} : { staticIcons: options.staticIcons };
+    const compilerOptions = mode === "csr" ? { devtools, serverExports, ...css, ...icons } : { resume, devtools, serverExports, ...css, ...icons };
+    const bridges = options.bridges?.length ? options.bridges : undefined;
+    if (bridges && mode === "csr")
+        throw new Error("rivetRouter: framework bridges need server or static mode (islands are server-rendered)");
+    const plugins = options.images || bridges
+        ? rivet({ ...compilerOptions, images: options.images, bridges })
+        : [rivet(compilerOptions)];
+    // With bridges the framework plugins come first: the compiler is the plugin named `vite-plugin-rivet`.
+    const compiler = plugins.find((plugin) => plugin.name === "vite-plugin-rivet");
+    const clientEntry = () => resolve(root, outDir, "entry.client.tsx");
+    const adapter = adapterOptions(options.adapter);
+    if (adapter && mode === "csr")
+        throw new Error("rivetRouter: CSR apps have no server build (adapter)");
+    // i18n client builds: the locale suffix of Vite's base (`/<locale>`), and the app base without it.
+    let suffix = "", appBase = "";
+    // i18n client builds: RegExp source of the app paths this build's locale serves (other locales' URLs load documents).
+    let localePaths = null;
+    // i18n dev server: every locale's path pattern (one client for all locales; see the base.ts transform).
+    let devLocalePaths = null;
+    // Z5: the client build's output (captured before Vite rewrites dynamic imports) and, per importing
+    // chunk, the files its static graph already loaded.
+    let clientBundle;
+    const loadedBy = new Map();
+    const preloadDeps = (file, deps, { hostId }) => {
+        if (!clientBundle)
+            return deps;
+        let loaded = loadedBy.get(hostId);
+        if (!loaded) {
+            loaded = new Set();
+            for (const stack = [hostId]; stack.length;) {
+                const next = stack.pop();
+                if (loaded.has(next))
+                    continue;
+                loaded.add(next);
+                const chunk = clientBundle[next];
+                if (chunk?.type === "chunk")
+                    stack.push(...chunk.imports);
+            }
+            loadedBy.set(hostId, loaded);
+        }
+        const rest = deps.filter((dep) => !loaded.has(dep));
+        // Only the imported chunk itself left: `import()` fetches it anyway (a preload list would repeat its URL).
+        return rest.length === 1 && rest[0] === file ? [] : rest;
+    };
+    const router = {
+        name: "vite-plugin-rivet-router",
+        enforce: "pre",
+        async config(config, env) {
+            root = resolve(config.root ?? process.cwd());
+            // `trailingSlash`: the server bundle must carry its own copy of the router (its policy constant
+            // is rewritten in this build), even where the package would otherwise be external.
+            if (slash !== "ignore") {
+                const kept = config.ssr?.noExternal;
+                if (kept !== true)
+                    (config.ssr ??= {}).noExternal = [...(kept === undefined ? [] : Array.isArray(kept) ? kept : [kept]), "@rivetjs/router"];
+            }
+            const names = new Set();
+            let i18nLocale = null;
+            localePaths = null;
+            devLocalePaths = null;
+            const scan = (list) => {
+                if (Array.isArray(list))
+                    list.forEach(scan);
+                else if (list && typeof list === "object" && "name" in list) {
+                    const name = String(list.name);
+                    names.add(name);
+                    if (name === "vite-plugin-rivet-i18n") {
+                        const api = list.api;
+                        i18nLocale = api?.locale ?? null;
+                        localePaths = api?.clientPaths ?? null;
+                        if (env.command === "serve")
+                            devLocalePaths = api?.devPaths ?? null;
+                    }
+                }
+            };
+            scan(config.plugins);
+            // `@rivetjs/i18n/vite` client builds (one per locale, its config hook runs first) serve a
+            // locale's assets under `<base><locale>/`; routes and `BASE` keep the app base.
+            suffix = i18nLocale && env.command === "build" && !config.build?.ssr && !env.isSsrBuild ? "/" + i18nLocale : "";
+            // One base for assets (Vite) and routes (codegen).
+            if (options.base !== undefined)
+                config.base = normalizeBase(options.base) + suffix + "/";
+            appBase = normalizeBase(config.base);
+            if (suffix && appBase.endsWith(suffix))
+                appBase = appBase.slice(0, -suffix.length);
+            codegen.base = appBase;
+            // Kit's plugin (`kit()` from @rivetjs/kit/vite) turns component head on unless `head: "early"`.
+            const head = options.head ?? (names.has("vite-plugin-rivet-kit") ? "components" : "early");
+            if (head === "components" && mode !== "csr")
+                codegen.head = "components";
+            const usage = await routerUsage(root, { exclude: [config.build?.outDir ?? "dist", outDir] });
+            for (const name of USAGE)
+                codegen[name] = options[name] ?? usage[name];
+            const generated = await generateRoutes(root, codegen);
+            entryFor(generated.resumeEntry);
+            const { resumeModules } = generated;
+            table = generated.table;
+            serverExports.modules.splice(0, serverExports.modules.length, ...routeModules(table, routesDir));
+            inFile = serverFiles(table);
+            const extra = options.resume?.modules ?? [];
+            resume.modules.splice(0, resume.modules.length, ...new Set([...resumeModules, ...extra]));
+            const ssr = config.build?.ssr;
+            const input = config.build?.rollupOptions?.input;
+            if (ssr && mode === "csr")
+                throw new Error("rivetRouter: CSR apps have no server build");
+            const serverOut = config.build?.outDir ?? "dist/server";
+            if (ssr === true && adapter)
+                return targetBuildConfig(adapter, resolve(root, outDir, "entry.server.tsx"), serverOut);
+            if (ssr === true)
+                return { build: { ssr: resolve(root, outDir, "entry.server.tsx"), outDir: serverOut } };
+            if (ssr)
+                return;
+            // Keyed by file name, so stylesheets land flat in `assets/` (`styles-<hash>.css`).
+            const stylesInput = Object.fromEntries(styles.map((path) => [
+                posix(path)
+                    .split("/")
+                    .pop()
+                    .replace(/\.[^.]+$/, ""),
+                resolve(root, path),
+            ]));
+            // Resumed pages have no application entry, only stylesheets (the compiler emits the resume
+            // runtime and symbol chunks itself). CSR apps start from the generated client entry.
+            const defaultInput = mode === "csr" ? { app: clientEntry(), ...stylesInput } : styles.length ? stylesInput : { "rivet-empty": EMPTY };
+            return {
+                // Pages come from the app handler (or the CSR shell), not an index.html fallback.
+                appType: config.appType ?? "custom",
+                build: {
+                    outDir: config.build?.outDir ?? "dist/client",
+                    manifest: config.build?.manifest ?? true,
+                    // Z5: a dynamic import (route page, lazy component) preloads only what its importer has not
+                    // loaded statically: the App chunk lists no shared runtime chunks per route (routes-500 −26 KB min).
+                    ...(config.build?.modulePreload === undefined ? { modulePreload: { resolveDependencies: preloadDeps } } : {}),
+                    ...(input === undefined ? { rollupOptions: { input: defaultInput } } : {}),
+                },
+            };
+        },
+        // Server reach: every route's browser graph, before the first module compiles (codegen marks document routes).
+        async configResolved(config) {
+            resolvedConfig = config;
+            resolver = null;
+            building = config.command === "build";
+            patterns = [...serverOnly.modules, ...declaredServerOnly(config.plugins)];
+            if (mode === "csr")
+                return;
+            if (await analyze())
+                await generateRoutes(root, codegen);
+        },
+        buildStart() {
+            if (!building || !reach)
+                return;
+            const client = this.environment?.config?.consumer !== "server";
+            // Warnings once (client build); errors fail either build.
+            if (client)
+                for (const problem of reach.problems)
+                    if (problem.severity === "warning")
+                        this.warn(problem.message);
+            const errors = reach.problems.filter((problem) => problem.severity === "error");
+            if (errors.length)
+                this.error({ message: errors.map((problem) => problem.message).join("\n\n"), plugin: "vite-plugin-rivet-router", pluginCode: RV_REACH });
+        },
+        resolveId(id, importer, resolveOptions) {
+            if (id === EMPTY || id.startsWith(DOCUMENT_PAGE) || id.startsWith(STAND_IN))
+                return id;
+            // `x.server.ts` modules hold secrets and server code: never part of a browser graph.
+            if (!importer || resolveOptions?.ssr || this.environment?.config?.consumer === "server")
+                return null;
+            // The compiler's resume grouping resolves every specifier its facts list (type-only imports too): not an import.
+            if (_factsResolve(id, importer))
+                return null;
+            const from = fileOf(importer);
+            // Client build: the App's import of a document route's page — the browser never renders it (links load its document).
+            if (building && documentPages.size && /^\.\.?\//.test(id) && from === resolve(root, outDir, "app.tsx")) {
+                const page = documentPages.get(resolve(dirname(from), id.split("?")[0]));
+                if (page)
+                    return DOCUMENT_PAGE + page;
+            }
+            if (isServerOnly(patterns, id)) {
+                // Reached only from document routes' graphs (their resumed parts): a stand-in that throws on use, never the module.
+                if (reach?.documentOnly.has(from))
+                    return STAND_IN + (reach.targets.get(from + "\0" + id) ?? id);
+                this.error({
+                    message: `[rivet:router] ${id} is server-only and cannot be imported by browser code (imported from ${posix(importer)})` +
+                        "\n  fix: read it in a server export (`load(…)`, `actions(…)`, `onGet(…)`, …) and pass the data to the page; type-only imports (`import type`) are fine" +
+                        "\n  docs: https://rivetjs.severyn.pro/guides/security/server-only-code",
+                    id: importer,
+                    plugin: "vite-plugin-rivet-router",
+                });
+            }
+            return null;
+        },
+        load(id) {
+            if (id === EMPTY)
+                return "export {};\n";
+            if (id.startsWith(DOCUMENT_PAGE)) {
+                const page = id.slice(DOCUMENT_PAGE.length);
+                const message = `[rivet:router] ${posix(join(routesDir, page))} is a document route (its browser graph reaches a server-only module): its links load the document, the browser never renders it`;
+                return `export default function DocumentRoute() {\n  throw new Error(${JSON.stringify(message)});\n}\n`;
+            }
+            if (id.startsWith(STAND_IN)) {
+                const key = id.slice(STAND_IN.length);
+                const shown = key.startsWith("/") ? posix(relative(root, key)) : key;
+                return serverOnlyStub(shown, reach?.chains.get(key) ?? [], reach?.names.get(key) ?? []);
+            }
+            return null;
+        },
+        // i18n client build: `BASE` is the app base, not the locale's asset base (`BASE_URL`). Only this
+        // build's copy of shared/base.ts changes, so other apps' bundles stay byte-identical.
+        // `trailingSlash`: the policy constant (client and server bundles); unset, the module stays as is.
+        transform(code, id, transformOptions) {
+            if (shellBuild && id.split("?")[0] === SHELL_MODULE) {
+                if (!SHELL_DEFAULT.test(code))
+                    this.error("rivetRouter: server/shell-build.ts no longer declares SHELL_BUILD as expected");
+                return { code: code.replace(SHELL_DEFAULT, `export const SHELL_BUILD = () => import(${JSON.stringify(SHELL_CACHE)});`), map: null };
+            }
+            if (slash !== "ignore" && id.split("?")[0] === SLASH_MODULE) {
+                if (!code.includes(SLASH_DEFAULT))
+                    this.error("rivetRouter: shared/slash.ts no longer declares TRAILING_SLASH as expected");
+                return { code: code.replace(SLASH_DEFAULT, JSON.stringify(slash) + " as TrailingSlash"), map: null };
+            }
+            // i18n dev: one client serves every locale, so `underBase` also requires the target's locale to be
+            // the page's (read once at load): another locale's URL loads its document, as in a build.
+            if (devLocalePaths && !transformOptions?.ssr && id.split("?")[0] === BASE_MODULE) {
+                const decl = "export function underBase(";
+                if (!code.includes(decl))
+                    this.error("rivetRouter: shared/base.ts no longer declares underBase as expected");
+                return {
+                    code: code.replace(decl, "function _inBase(") +
+                        `\nconst _LOCALES = ${JSON.stringify(devLocalePaths)}.map((source) => new RegExp(source, "i"));\n` +
+                        'const _localeOf = (pathname, base) => { const path = base ? pathname.slice(base.length) || "/" : pathname; return _LOCALES.findIndex((re) => re.test(path)); };\n' +
+                        'const _PAGE = typeof location === "undefined" ? -1 : _localeOf(location.pathname, BASE);\n' +
+                        "export function underBase(pathname, base = BASE) {\n" +
+                        "  return _inBase(pathname, base) && (_PAGE < 0 || _localeOf(pathname, base) === _PAGE);\n}\n",
+                    map: null,
+                };
+            }
+            if (!suffix || id.split("?")[0] !== BASE_MODULE)
+                return null;
+            const read = /\(import\.meta(?: as [^)]*)?\)\.env\?\.BASE_URL|import\.meta\.env\?\.BASE_URL/;
+            if (!read.test(code))
+                this.error("rivetRouter: shared/base.ts no longer reads import.meta.env.BASE_URL as expected");
+            let out = code.replace(read, JSON.stringify(appBase + "/"));
+            // Another locale's URL is another client build (its inlined messages, its chunks): the
+            // browser loads its document; the client router and navigate() never switch locale in place.
+            if (localePaths) {
+                const decl = "export function underBase(";
+                if (!out.includes(decl))
+                    this.error("rivetRouter: shared/base.ts no longer declares underBase as expected");
+                out =
+                    out.replace(decl, "function _inBase(") +
+                        `\nconst _LOCALE = new RegExp(${JSON.stringify(localePaths)}, "i");\n` +
+                        "export function underBase(pathname, base = BASE) {\n" +
+                        '  return _inBase(pathname, base) && _LOCALE.test(base ? pathname.slice(base.length) || "/" : pathname);\n}\n';
+            }
+            return { code: out, map: null };
+        },
+        async generateBundle(_options, bundle) {
+            for (const [name, output] of Object.entries(bundle))
+                if (output.type === "chunk" && output.facadeModuleId === EMPTY)
+                    delete bundle[name];
+            if (this.environment?.config?.consumer === "server")
+                return;
+            clientBundle = bundle;
+            loadedBy.clear();
+            if (mode !== "csr") {
+                // Route modules' CSS (component stylesheets, css`` sheets), linked per route by the handler.
+                // Several stylesheets of one route are merged into one route sheet (`mergeRouteCSS`).
+                const base = this.environment?.config?.base ?? "/";
+                const { routes: css, assets } = mergeRouteCSS(bundle, bundleRouteCSS(bundle, table, resolve(root, routesDir), base), base);
+                for (const asset of assets)
+                    this.emitFile({ type: "asset", ...asset });
+                if (Object.keys(css).length)
+                    this.emitFile({ type: "asset", fileName: ROUTE_CSS, source: JSON.stringify(css, null, 2) + "\n" });
+                // Sheets the handler may write inline (`inlineStylesheets`; decided per page, `server/inline-styles.ts`).
+                const limit = this.environment?.config?.build.assetsInlineLimit;
+                const inline = inlineCSS(bundle, assets, base, options.inlineStylesheets ?? "auto", typeof limit === "number" ? limit : 4096);
+                if (inline)
+                    this.emitFile({ type: "asset", fileName: INLINE_CSS, source: JSON.stringify(inline) + "\n" });
+                return;
+            }
+            const base = this.environment?.config?.base ?? "/";
+            const entry = Object.values(bundle).find((output) => output.type === "chunk" && output.facadeModuleId === clientEntry());
+            if (!entry || entry.type !== "chunk")
+                return;
+            const css = new Set(entry.viteMetadata?.importedCss ?? []);
+            const sources = new Set(styles.map((path) => posix(path)));
+            for (const output of Object.values(bundle))
+                if (output.type === "asset" && output.fileName.endsWith(".css") && output.originalFileNames.some((name) => sources.has(posix(name))))
+                    css.add(output.fileName);
+            const { shellHTML } = await import("../adapters/csr.js");
+            const document = await loadDocument(resolve(root, documentPath));
+            const source = shellHTML(document, { script: base + entry.fileName, styles: [...css].map((file) => base + file) });
+            this.emitFile({ type: "asset", fileName: "index.html", source });
+        },
+        async closeServer() {
+            closed = true;
+            await regenerations;
+        },
+        configureServer(server) {
+            const routesPath = resolve(root, routesDir);
+            const regenerate = async (file) => (resolve(file).startsWith(routesPath + sep) ? refresh() : false);
+            closed = false;
+            const refresh = () => {
+                const run = regenerations.then(async () => {
+                    if (closed)
+                        return false;
+                    const { changed, table: next, resumeEntry } = await generateRoutes(root, codegen);
+                    entryFor(resumeEntry);
+                    table = next;
+                    serverExports.modules.splice(0, serverExports.modules.length, ...routeModules(table, routesDir));
+                    inFile = serverFiles(table);
+                    // A new route table (or new document routes): the browser graphs are walked again on the next page request.
+                    if (changed)
+                        reachDirty = true;
+                    if (changed && !closed)
+                        server.ws.send({ type: "full-reload" });
+                    return changed;
+                });
+                regenerations = run.catch(() => { });
+                return run;
+            };
+            // A failed regeneration is logged (an unhandled rejection would end the dev server's process).
+            const logged = (fn) => (file) => void fn(file).catch((error) => server.config.logger.error("rivet router: " + (error instanceof Error ? (error.stack ?? error.message) : String(error))));
+            server.watcher.on("add", logged(regenerate));
+            server.watcher.on("unlink", logged(regenerate));
+            // Any source edit can change what a route's browser graph reaches (re-walked lazily, changed files only).
+            const stale = (file) => {
+                if (SOURCE.test(file))
+                    reachDirty = true;
+            };
+            server.watcher.on("add", stale);
+            server.watcher.on("unlink", stale);
+            server.watcher.on("change", stale);
+            // Dev server reach: a page's RV3011 reports on its load (terminal once per report, overlay on every load of an
+            // error); new document routes regenerate the App (full reload).
+            const reported = new Set();
+            let routeMatch;
+            const devReach = async (url) => {
+                if (mode === "csr")
+                    return [];
+                if (reachDirty) {
+                    reachDirty = false;
+                    const run = reachRun.then(async () => {
+                        if (!closed && (await analyze()))
+                            await refresh();
+                    });
+                    reachRun = run.catch(() => { });
+                    await run;
+                }
+                if (!reach?.problems.length)
+                    return [];
+                if (routeMatch?.table !== table) {
+                    const at = (pattern) => (codegen.base ? (pattern === "/" ? codegen.base : codegen.base + pattern) : pattern);
+                    const match = compileRoutes(table.routes.filter((route) => route.page).map((route) => ({ path: at(route.pattern), render: () => route })));
+                    routeMatch = { table, match: (target) => match(target)?.route.render(undefined, null) };
+                }
+                const route = routeMatch.match(url);
+                if (!route)
+                    return [];
+                const files = new Set([route.page, route.notFound, route.error, ...route.layouts.map((layout) => layout.page)].filter(Boolean));
+                const found = reach.problems.filter((problem) => problem.files.some((file) => files.has(file)));
+                for (const problem of found)
+                    if (!reported.has(problem.message)) {
+                        reported.add(problem.message);
+                        if (problem.severity === "error")
+                            server.config.logger.error(problem.message);
+                        else
+                            server.config.logger.warn(problem.message);
+                    }
+                return found;
+            };
+            // A source starts using a router feature (search params, navigate(), useParams()): generate it
+            // from now on (regenerate + full reload). A dev server never turns one off again.
+            const features = async (file) => {
+                if (!SOURCE.test(file) || /(?:^|[\\/])(?:node_modules|dist(?:[-_.][^\\/]*)?|\.[^\\/]*)[\\/]/.test(relative(root, file)))
+                    return false;
+                const found = none();
+                featuresOf(await readFile(file, "utf8").catch(() => ""), found);
+                const added = USAGE.filter((name) => found[name] && !codegen[name] && options[name] === undefined);
+                if (!added.length)
+                    return false;
+                for (const name of added)
+                    codegen[name] = true;
+                await refresh();
+                return true;
+            };
+            server.watcher.on("add", logged(features));
+            // An edit can add or remove in-file server exports: only then does the route table change
+            // (regenerated without touching other edits). Server-only edits (`*.server.ts`, in-file
+            // loaders) refetch the route data and re-mount the page (`rivet:data`).
+            server.watcher.on("change", logged(async (file) => {
+                if (await features(file))
+                    return;
+                const path = posix(file);
+                if (/\.server\.[cm]?[jt]sx?$/.test(path))
+                    return server.ws.send({ type: "custom", event: "rivet:data" });
+                if (!resolve(file).startsWith(routesPath + sep))
+                    return;
+                const name = posix(relative(routesPath, resolve(file)));
+                const names = (await _serverExportsOf(routesPath, [name])).get(name) ?? [];
+                const has = names.some((n) => n !== "live");
+                if ((has !== inFile.has(name) || names.includes("live") !== inFile.has("live:" + name)) && (await regenerate(file)))
+                    return;
+                if (has)
+                    server.ws.send({ type: "custom", event: "rivet:data" });
+            }));
+            const devStyles = styles.map((path) => "/" + posix(path));
+            // i18n (`@rivetjs/i18n/vite`): dev pages render their locale's variant, and a non-default
+            // locale loads the dev entry with `?rivet-locale=` (its client modules compile for that locale).
+            const i18n = server.config.plugins.find((p) => p.name === "vite-plugin-rivet-i18n")?.api?.config;
+            const devEntry = server.config.base + posix(join(outDir, "entry.dev.tsx"));
+            const devMount = server.config.base + posix(join(outDir, "dev-mount.tsx"));
+            // Dev errors: server failures reach the overlay and a dev error page; browser ones are forwarded.
+            listenClientErrors(server);
+            // Dev SSR records like production (resume recorder, dev manifest): serialization errors surface.
+            const devResume = compiler.api.devResume;
+            const onError = devReport(server, () => table, routesPath, (id) => devResume.describe(id));
+            // Pages resume like production; opted out, or a non-default i18n locale (its client graph
+            // compiles per locale, chunks do not yet): client-render without the recorded state.
+            const devMode = (locale) => !resume.dev || (i18n && locale && locale !== i18n.defaultLocale) ? "check" : "resume";
+            const listeners = new WeakMap();
+            // After Vite's own middlewares (modules, assets): pages and data go through the app handler.
+            return () => {
+                server.middlewares.use(async (req, res, next) => {
+                    try {
+                        if (mode === "csr") {
+                            if (req.method !== "GET" && req.method !== "HEAD")
+                                return next();
+                            const { shellHTML } = await import("../adapters/csr.js");
+                            const document = (await server.ssrLoadModule("/" + posix(documentPath))).default;
+                            const shell = shellHTML(document, { script: "/" + posix(join(outDir, "entry.client.tsx")), styles: devStyles });
+                            const html = await server.transformIndexHtml(req.url ?? "/", shell);
+                            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
+                            res.end(req.method === "HEAD" ? undefined : html);
+                            return;
+                        }
+                        // The entry re-exports createApp: handler and app load through one SSR graph (one runtime).
+                        const entry = (await server.ssrLoadModule("/" + posix(join(outDir, "entry.server.tsx"))));
+                        // One app per entry namespace: Vite hands out a new one once an edit invalidates the graph.
+                        let listener = listeners.get(entry);
+                        if (!listener) {
+                            const { createListener } = await import("../adapters/node.js");
+                            const handler = entry.createApp({
+                                entry,
+                                styles: devStyles,
+                                routeStyles: (id) => devRouteCSS(server, table, resolve(root, routesDir), id, new Set(devStyles)),
+                                dev: true,
+                                // Read per page: the dev manifest grows as Vite compiles modules.
+                                devResume: {
+                                    get manifest() {
+                                        return devResume.manifest();
+                                    },
+                                    mode: devMode,
+                                },
+                                // The DevTools agent (when on) runs first, before any framework module evaluates.
+                                devScripts: (locale) => [
+                                    ...compiler.api.devtoolsScripts(),
+                                    server.config.base + "@vite/client",
+                                    // Resumed: the entry that switches to client rendering on a hot update; else the mount itself.
+                                    devMode(locale) === "resume"
+                                        ? devEntry
+                                        : i18n && locale && locale !== i18n.defaultLocale
+                                            ? devMount + "?rivet-locale=" + encodeURIComponent(locale)
+                                            : devMount,
+                                ],
+                                ...(i18n ? { i18n: { locales: i18n.locales } } : {}),
+                                onError,
+                            });
+                            listener = createListener({ handler: devHandler(handler, server, () => table, devReach), compress: false }).listener;
+                            listeners.set(entry, listener);
+                        }
+                        // Vite's base middleware strips the base from `req.url`: route patterns carry it.
+                        const original = req.originalUrl;
+                        if (codegen.base && original)
+                            req.url = original;
+                        // Static mode: client navigation reads prerendered `<page>/_data.json` files, which only the
+                        // build writes. Dev answers them from the data endpoint, as the static adapter renders them.
+                        if (mode === "static")
+                            staticData(req, slash);
+                        listener(req, res);
+                    }
+                    catch (error) {
+                        // Never reject (connect does not await middlewares; an unhandled rejection ends the dev server).
+                        try {
+                            if (error instanceof Error)
+                                server.ssrFixStacktrace(error);
+                        }
+                        catch {
+                            /* Keep the original stack. */
+                        }
+                        next(error);
+                    }
+                });
+            };
+        },
+    };
+    return [
+        router,
+        ...plugins,
+        // Measurement only (`RIVET_LAZY_ROWS=swap`, dev / lazy-rows tools): inert otherwise.
+        lazyRowsHarness(() => resolve(root, outDir, "entry.server.tsx")),
+        ...(adapter ? [targetEntryPlugin(adapter, { serverEntry: () => resolve(root, outDir, "entry.server.tsx"), mode: () => mode })] : []),
+    ];
+}
+/** Import the document shell module at build time (Node strips its types). */
+async function loadDocument(path) {
+    const module = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href, true)));
+    if (typeof module.default !== "function")
+        throw new Error(`${path}: default export must be a DocumentShell function`);
+    return module.default;
+}