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

package/adapters/pack.d.ts

@@ -0,0 +1,39 @@
+import type { AdapterOptions } from "./target-build.js";
+export interface PackContext {
+    /** Project (Vite) root. */
+    readonly root: string;
+    /** Build output with `client/` and `server/`. */
+    readonly dist: string;
+    /** Server build directory (`dist/server`). */
+    readonly server: string;
+    /** URL base path (`""` or `/app`). */
+    readonly base: string;
+    /** `server`: a function renders requests; `static`: files only. */
+    readonly mode: "server" | "static";
+}
+/** One prerendered page: its canonical URL path and the file written for it (relative to the static root). */
+export interface PackedPage {
+    readonly url: string;
+    readonly file: string;
+}
+export interface PackResult {
+    /** Directories written (absolute). */
+    readonly outputs: readonly string[];
+    readonly pages: readonly PackedPage[];
+}
+export declare const IMMUTABLE = "public, max-age=31536000, immutable";
+export declare function pack(options: AdapterOptions, context: PackContext): Promise<PackResult | undefined>;
+/** URL path prefixes of content-hashed files (`<base>/assets/`, per locale with i18n). */
+export declare function immutablePrefixes(base: string, locales: readonly string[] | undefined): string[];
+/** Files below `dir`, as `/`-joined relative paths. */
+export declare function listFiles(dir: string): Promise<string[]>;
+export declare const NETLIFY_FUNCTION = "rivet-server";
+/** Compatibility date of the generated Wrangler configuration. */
+export declare const COMPATIBILITY_DATE = "2026-10-01";
+/**
+ * From 2026-08-04 `nodejs_compat` (+ `_v2`) is on by default; turned off explicitly, `nodejs_als` keeps
+ * `node:async_hooks` (https://developers.cloudflare.com/workers/configuration/compatibility-flags/).
+ */
+export declare const WORKER_FLAGS: readonly ["nodejs_als", "no_nodejs_compat", "no_nodejs_compat_v2"];
+/** JSONC → JSON: comments and trailing commas removed outside strings. */
+export declare function stripJSONC(text: string): string;

package/adapters/pack.js

@@ -0,0 +1,360 @@
+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;
+};
+// Packaging for platform targets (Node-only, build time): after `vite build --ssr` wrote
+// `dist/server` (with the target's generated entry), lay the build out the way the platform
+// deploys it. Static files are copied (never the `.vite/` manifests, which the bundle inlines);
+// routes that `export const prerender = true` (every prerenderable route in `mode: "static"`) are
+// rendered to HTML files through the built handler, with a hash CSP (`static.ts`).
+//
+// Platform contracts (verified 2026-10-08):
+// - Vercel Build Output API v3: https://vercel.com/docs/build-output-api/v3 (primitives, configuration)
+// - Netlify Frameworks API: https://docs.netlify.com/build/frameworks/frameworks-api/
+// - Cloudflare Workers static assets: https://developers.cloudflare.com/workers/static-assets/ (+ `_headers`:
+//   https://developers.cloudflare.com/workers/static-assets/headers/), redirected Wrangler configuration:
+//   https://developers.cloudflare.com/workers/wrangler/configuration/#generated-wrangler-configuration
+import { cp, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readManifests } from "./build.js";
+import { assemble } from "./assemble.js";
+import { prerender } from "./static.js";
+import { loadServer } from "../server/module.js";
+export const IMMUTABLE = "public, max-age=31536000, immutable";
+const GENERATOR = "@rivetjs/router";
+export async function pack(options, context) {
+    switch (options.name) {
+        case "vercel":
+            return packVercel(options, context);
+        case "netlify":
+            return packNetlify(options, context);
+        case "cloudflare":
+            return packCloudflare(options, context);
+        default:
+            return undefined;
+    }
+}
+/** URL path prefixes of content-hashed files (`<base>/assets/`, per locale with i18n). */
+export function immutablePrefixes(base, locales) {
+    return locales?.length ? locales.map((locale) => `${base}/${locale}/assets/`) : [`${base}/assets/`];
+}
+/** Copy the client build into `to`, without dot-named build metadata (`.vite/`); `.well-known/` stays. */
+async function copyClient(dist, to) {
+    await mkdir(to, { recursive: true });
+    const from = resolve(dist, "client");
+    await cp(from, to, {
+        recursive: true,
+        dereference: true,
+        filter: (source) => {
+            const name = basename(source);
+            return source === from || !name.startsWith(".") || name === ".well-known";
+        },
+    });
+}
+/** Files below `dir`, as `/`-joined relative paths. */
+export async function listFiles(dir) {
+    const entries = await readdir(dir, { recursive: true, withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isFile()).map((entry) => relative(dir, join(entry.parentPath, entry.name)).split("\\").join("/"));
+}
+const exists = (path) => stat(path).then(() => true, () => false);
+/**
+ * Prerender into `staticRoot` (the directory served at `/`): every prerenderable route in static mode,
+ * routes exporting `prerender = true` in server mode (no 404 page: the function answers misses).
+ */
+async function prerenderInto(options, context, staticRoot, facts = {}) {
+    // Import a private copy of the server build: Node's module cache is keyed by path, so a later build in
+    // the same process (tests, build scripts, watch) would get the first build's modules (chunks import the
+    // entry back by path) and its deleted chunks. The bundle imports only built-ins, so any directory does.
+    const copy = await mkdtemp(join(tmpdir(), "rivet-pack-"));
+    try {
+        await cp(context.server, copy, { recursive: true });
+        const path = pathToFileURL(join(copy, "entry.server.js")).href;
+        const entry = (await import(__rewriteRelativeImportExtension(path, true)));
+        const manifests = await readManifests(context.dist, { ...(options.locales?.length ? { locales: options.locales } : {}), base: entry.base ?? "" });
+        facts.trailingSlash = entry.trailingSlash ?? "ignore";
+        return await prerenderWith(entry, assemble(entry, manifests, {}, path), options, context, staticRoot);
+    }
+    finally {
+        await rm(copy, { recursive: true, force: true });
+    }
+}
+async function prerenderWith(entry, handler, options, context, staticRoot) {
+    let routes = entry.routes;
+    if (context.mode === "server") {
+        const marked = await Promise.all(routes.map(async (route) => route.page && (await loadServer(route.server))?.prerender === true));
+        routes = routes.filter((_, i) => marked[i]);
+        if (!routes.length)
+            return [];
+    }
+    const outDir = staticRoot + context.base;
+    const notFound = join(outDir, "404.html");
+    const kept404 = await exists(notFound);
+    const trailingSlash = entry.trailingSlash ?? "ignore";
+    const report = await prerender({
+        handler,
+        routes,
+        outDir,
+        trailingSlash,
+        ...(context.base ? { base: context.base } : {}),
+        ...(options.csp !== undefined ? { csp: options.csp } : {}),
+    });
+    if (context.mode === "server" && !kept404)
+        await rm(notFound, { force: true });
+    return report.pages.map((url) => ({ url, file: pageFile(url, context.base, trailingSlash) }));
+}
+/** The file `prerender` writes for a canonical page URL, relative to the static root. */
+function pageFile(url, base, trailingSlash) {
+    const local = (base && url.startsWith(base) ? url.slice(base.length) : url) || "/";
+    const path = decodeURIComponent(local).replace(/\/+$/, "");
+    const file = trailingSlash === "never" && path ? path + ".html" : path + "/index.html";
+    return (base + file).replace(/^\/+/, "");
+}
+const json = (value) => JSON.stringify(value, null, 2) + "\n";
+async function write(path, contents) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents);
+}
+/** PCRE-safe literal. */
+const literal = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+// ---------------------------------------------------------------------------------------------
+// Vercel: `.vercel/output/{config.json, static/, functions/_render.func/}`.
+const VERCEL_FUNCTION = "_render";
+async function packVercel(options, context) {
+    const out = resolve(context.root, ".vercel/output");
+    await rm(out, { recursive: true, force: true });
+    const staticRoot = join(out, "static");
+    await copyClient(context.dist, staticRoot + context.base);
+    const pages = await prerenderInto(options, context, staticRoot);
+    const server = context.mode === "server";
+    const isr = server && options.isr ? options.isr : null;
+    const routes = immutablePrefixes(context.base, options.locales).map((prefix) => ({
+        src: `^${literal(prefix)}.+$`,
+        headers: { "cache-control": IMMUTABLE },
+        continue: true,
+    }));
+    // Prerendered `a/index.html` / `a.html` answer at `/a` (Vercel's file system matches exact paths).
+    const overrides = {};
+    const isrRoutes = [];
+    if (server) {
+        const fn = join(out, "functions", VERCEL_FUNCTION + ".func");
+        await cp(context.server, fn, { recursive: true });
+        await write(join(fn, "package.json"), json({ type: "module" }));
+        const config = options.runtime === "edge"
+            ? { runtime: "edge", entrypoint: "vercel.js", ...(options.regions ? { regions: options.regions } : {}) }
+            : {
+                runtime: `nodejs${options.nodeVersion ?? 24}.x`,
+                handler: "vercel.js",
+                launcherType: "Nodejs",
+                shouldAddHelpers: false,
+                supportsResponseStreaming: true,
+                ...(options.regions ? { regions: options.regions } : {}),
+                ...(options.maxDuration !== undefined ? { maxDuration: options.maxDuration } : {}),
+                ...(options.memory !== undefined ? { memory: options.memory } : {}),
+            };
+        await write(join(fn, ".vc-config.json"), json(config));
+    }
+    for (const page of pages) {
+        const path = page.url.replace(/\/+$/, "") || "/";
+        if (isr) {
+            // ISR: a prerender function per page (symlink to the render function) instead of a file;
+            // the page path travels as `__rivet_path` (a prerender function's own path is its name).
+            await rm(join(staticRoot, page.file), { force: true });
+            const name = "_isr" + (path === "/" ? "/index" : path);
+            const link = join(out, "functions", name + ".func");
+            await mkdir(dirname(link), { recursive: true });
+            await symlink(relative(dirname(link), join(out, "functions", VERCEL_FUNCTION + ".func")), link, "dir");
+            await write(join(out, "functions", name + ".prerender-config.json"), json({ expiration: isr.expiration, allowQuery: ["__rivet_path", "_rivet"], passQuery: true }));
+            isrRoutes.push({ src: `^${literal(path === "/" ? "" : path)}/?$`, dest: `/${name}?__rivet_path=${encodeURIComponent(path)}` });
+        }
+        else if (page.file !== "index.html") {
+            overrides[page.file] = { path: page.file.replace(/(\/index)?\.html$/, "") };
+        }
+    }
+    routes.push({ handle: "filesystem" });
+    routes.push(...isrRoutes);
+    if (server)
+        routes.push({ src: "^/.*$", dest: "/" + VERCEL_FUNCTION });
+    else if (await exists(join(staticRoot, context.base, "404.html")))
+        routes.push({ handle: "error" }, { status: 404, src: "^/.*$", dest: `${context.base}/404.html` });
+    await write(join(out, "config.json"), json({ version: 3, routes, ...(Object.keys(overrides).length ? { overrides } : {}) }));
+    return { outputs: [out], pages };
+}
+// ---------------------------------------------------------------------------------------------
+// Netlify: publish dir `dist/netlify`, `.netlify/v1/{config.json, functions|edge-functions/rivet-server/}`.
+export const NETLIFY_FUNCTION = "rivet-server";
+async function packNetlify(options, context) {
+    const publish = resolve(context.dist, "netlify");
+    const v1 = resolve(context.root, ".netlify/v1");
+    await rm(publish, { recursive: true, force: true });
+    for (const dir of ["functions", "edge-functions"])
+        await rm(join(v1, dir, NETLIFY_FUNCTION), { recursive: true, force: true });
+    await copyClient(context.dist, publish + context.base);
+    const pages = await prerenderInto(options, context, publish);
+    const prefixes = immutablePrefixes(context.base, options.locales);
+    const headers = prefixes.map((prefix) => ({ for: prefix + "*", values: { "cache-control": IMMUTABLE } }));
+    if (context.mode === "server") {
+        const name = `"${NETLIFY_FUNCTION}"`;
+        if (options.edge) {
+            // Edge Functions run before static files: answer only paths with no file (`undefined` = continue).
+            const dir = join(v1, "edge-functions", NETLIFY_FUNCTION);
+            await cp(context.server, dir, { recursive: true });
+            const files = await listFiles(publish);
+            const paths = new Set();
+            for (const file of files) {
+                if (prefixes.some((prefix) => ("/" + file).startsWith(prefix)))
+                    continue;
+                paths.add("/" + file);
+                const page = /^(.*?)(?:\/index)?\.html$/.exec(file);
+                if (page)
+                    for (const path of ["/" + page[1], "/" + page[1] + "/"])
+                        paths.add(path.replace(/^\/\/$/, "/"));
+            }
+            await write(join(dir, NETLIFY_FUNCTION + ".js"), [
+                `// Generated by ${GENERATOR}: Netlify Edge Function (Frameworks API). Do not edit.`,
+                'import { create } from "./netlify.js";',
+                `export default create({ staticPaths: ${JSON.stringify([...paths].sort())} });`,
+                `export const config = ${JSON.stringify({ path: "/*", excludedPath: prefixes.map((prefix) => prefix + "*"), name: "Rivet", generator: GENERATOR })};`,
+                "",
+            ].join("\n"));
+        }
+        else {
+            const dir = join(v1, "functions", NETLIFY_FUNCTION);
+            await cp(context.server, dir, { recursive: true });
+            await write(join(dir, "package.json"), json({ type: "module" }));
+            const config = {
+                path: "/*",
+                preferStatic: true,
+                name: "Rivet",
+                generator: GENERATOR,
+                // Already bundled (`ssr.noExternal`): ship the directory as is.
+                nodeBundler: "none",
+                includedFiles: [relative(context.root, dir).split("\\").join("/") + "/**"],
+            };
+            await write(join(dir, NETLIFY_FUNCTION + ".mjs"), [
+                `// Generated by ${GENERATOR}: Netlify Function (Functions v2, Frameworks API). Do not edit.`,
+                'export { default } from "./netlify.js";',
+                `export const config = ${JSON.stringify(config)};`,
+                "",
+            ].join("\n"));
+        }
+    }
+    await write(join(v1, "config.json"), json({ headers }));
+    return { outputs: [publish, v1], pages };
+}
+// ---------------------------------------------------------------------------------------------
+// Cloudflare Workers: `dist/cloudflare/{wrangler.json, static/}` + `.wrangler/deploy/config.json`.
+/** Compatibility date of the generated Wrangler configuration. */
+export const COMPATIBILITY_DATE = "2026-10-01";
+/**
+ * From 2026-08-04 `nodejs_compat` (+ `_v2`) is on by default; turned off explicitly, `nodejs_als` keeps
+ * `node:async_hooks` (https://developers.cloudflare.com/workers/configuration/compatibility-flags/).
+ */
+export const WORKER_FLAGS = ["nodejs_als", "no_nodejs_compat", "no_nodejs_compat_v2"];
+async function packCloudflare(options, context) {
+    const out = resolve(context.dist, "cloudflare");
+    await rm(out, { recursive: true, force: true });
+    const staticRoot = join(out, "static");
+    await copyClient(context.dist, staticRoot + context.base);
+    const facts = {};
+    const pages = await prerenderInto(options, context, staticRoot, facts);
+    const prefixes = immutablePrefixes(context.base, options.locales);
+    await write(join(staticRoot, "_headers"), prefixes.map((prefix) => `${prefix}*\n  Cache-Control: ${IMMUTABLE}\n`).join(""));
+    const user = await userWrangler(context.root);
+    const server = context.mode === "server";
+    const rel = (path) => relative(out, path).split("\\").join("/");
+    const config = {
+        name: (await packageName(context.root)) ?? "rivet-app",
+        compatibility_date: COMPATIBILITY_DATE,
+        // AsyncLocalStorage only (resume state); no Node.js compatibility layer, so the renderer writes
+        // plain Uint8Array slabs (workerd's `Buffer#utf8Write` rejects the in-place writes Node accepts).
+        compatibility_flags: [...WORKER_FLAGS],
+        ...user,
+        ...options.wrangler,
+        ...(server
+            ? {
+                // The server build is already bundled (route modules are relative chunks): upload it as is.
+                main: rel(join(context.server, "worker.js")),
+                base_dir: rel(context.server),
+                no_bundle: true,
+                find_additional_modules: true,
+                rules: [{ type: "ESModule", globs: ["**/*.js"] }],
+            }
+            : {}),
+        assets: {
+            ...(user.assets ?? {}),
+            ...(options.wrangler?.assets ?? {}),
+            directory: "./static",
+            // Prerendered `a/index.html` answers at the router's canonical URL (`/a`, or `/a/` with `trailingSlash: "always"`).
+            html_handling: facts.trailingSlash === "always" ? "force-trailing-slash" : "drop-trailing-slash",
+            ...(server ? {} : { not_found_handling: "404-page" }),
+        },
+    };
+    if (!server)
+        delete config.main;
+    await write(join(out, "wrangler.json"), json(config));
+    const redirect = resolve(context.root, ".wrangler/deploy/config.json");
+    await write(redirect, json({ configPath: relative(dirname(redirect), join(out, "wrangler.json")).split("\\").join("/") }));
+    return { outputs: [out, dirname(redirect)], pages };
+}
+/** The project's own `wrangler.json` / `wrangler.jsonc` (bindings, vars…), merged under the generated config. */
+async function userWrangler(root) {
+    for (const name of ["wrangler.jsonc", "wrangler.json"]) {
+        const text = await readFile(join(root, name), "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        const config = JSON.parse(stripJSONC(text));
+        // Paths in it are relative to the project root; the generated file sets its own.
+        for (const key of ["main", "base_dir", "rules", "no_bundle", "find_additional_modules", "$schema"])
+            delete config[key];
+        return config;
+    }
+    if (await exists(join(root, "wrangler.toml")))
+        console.warn('rivetRouter({ adapter: "cloudflare" }): wrangler.toml is not merged into the generated configuration; use wrangler.jsonc or the adapter\'s `wrangler` option');
+    return {};
+}
+/** JSONC → JSON: comments and trailing commas removed outside strings. */
+export function stripJSONC(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '"') {
+            let end = i + 1;
+            while (end < text.length && text[end] !== '"')
+                end += text[end] === "\\" ? 2 : 1;
+            out += text.slice(i, end + 1);
+            i = end;
+        }
+        else if (char === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (char === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end < 0 ? text.length : end + 1;
+        }
+        else
+            out += char;
+    }
+    return out.replace(/,(\s*[}\]])/g, "$1");
+}
+/** `package.json` name as a Worker name (lower-case letters, digits, dashes). */
+async function packageName(root) {
+    const text = await readFile(join(root, "package.json"), "utf8").catch(() => null);
+    const name = text ? JSON.parse(text).name : undefined;
+    if (typeof name !== "string")
+        return undefined;
+    const cleaned = name
+        .replace(/^@[^/]+\//, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63);
+    return cleaned || undefined;
+}

package/adapters/server-target.d.ts

@@ -0,0 +1,17 @@
+import type { BuildManifests } from "./assemble.js";
+export interface ServerTargetOptions {
+    /** Client build directory (default: `../client/` next to the generated entry). */
+    client?: string | URL;
+    /** Port (default `$PORT`, else 3000). */
+    port?: number;
+    /** Address (default `$HOST`, else `0.0.0.0`: the platform's container network). */
+    hostname?: string;
+    /** Stop gracefully on SIGTERM / SIGINT (default true). */
+    signals?: boolean;
+}
+export declare function listenOptions({ port, hostname }: Pick<ServerTargetOptions, "port" | "hostname">): {
+    port: number;
+    hostname: string;
+};
+/** URL prefixes of hashed files: each client build's `assets/` (one per locale with i18n). */
+export declare function immutableOf(base: string, build: BuildManifests): string[];

package/adapters/server-target.js

@@ -0,0 +1,8 @@
+const env = (name) => globalThis.process?.env?.[name];
+export function listenOptions({ port, hostname }) {
+    return { port: port ?? Number(env("PORT") ?? 3000), hostname: hostname ?? env("HOST") ?? "0.0.0.0" };
+}
+/** URL prefixes of hashed files: each client build's `assets/` (one per locale with i18n). */
+export function immutableOf(base, build) {
+    return build.clients.map((client) => (client.base || base + "/") + "assets/");
+}

package/adapters/static.d.ts

@@ -0,0 +1,84 @@
+import type { AppHandler, AppRoute } from "../server/handler.js";
+import type { AppConfig } from "../server/app.js";
+import type { CSPOptions } from "../shared/csp.js";
+export type { CSPDirectives, CSPOptions } from "../shared/csp.js";
+import { type TrailingSlash } from "../shared/slash.js";
+/** Options of `prerender()`. */
+export interface PrerenderOptions {
+    handler: AppHandler;
+    routes: readonly AppRoute[];
+    outDir: string;
+    /**
+     * The site's origin (`https://example.com`), used for the synthetic page requests: absolute URLs a page builds from
+     * its request URL (canonical links, `og:url`) carry it. Resume state and `_data.json` hold same-origin URL values
+     * relative either way. Unset: requests use the placeholder `http://localhost`, and a page whose state or data still
+     * holds it (a URL string built from the request URL) is an error.
+     */
+    origin?: string;
+    /** CSR shell for routes that can't be prerendered and have no server module; written to `200.html`. */
+    shell?: () => string | Promise<string>;
+    /**
+     * Static pages have no per-request nonce: each page gets a `<meta>` CSP allowing its own inline
+     * scripts by hash (`hashCSP`, given these options: `trustedTypes`, extra `directives` such as
+     * `{ "script-src": "'wasm-unsafe-eval'", "worker-src": "'self' blob:" }`). `false` leaves the pages
+     * as rendered (the host sets headers).
+     */
+    csp?: false | CSPOptions;
+    /** URL base path the route patterns carry (`/app`): files are written relative to it (the host serves `outDir` under it). */
+    base?: string;
+    /**
+     * The app's `trailingSlash` policy (`prerenderBuild` reads it from the build): pages are requested in
+     * canonical form and written as `a.html` (`"never"`, hosts serve it at `/a`) or `a/index.html`
+     * (`"always"`, `"ignore"`). `_data.json` stays at `a/_data.json` either way.
+     */
+    trailingSlash?: TrailingSlash;
+    /**
+     * Zero-JS sites (no page resumes, no CSR shell route): delete the client build's scripts no page references
+     * (`outDir/.vite/manifest.json` chunks outside the static / dynamic import closure of the pages' `<script src>` and
+     * modulepreload links, and the resume loader's `*.deps.js` modules). `prerenderBuild` turns it on (`prune: false` keeps them).
+     */
+    prune?: boolean;
+}
+/** What `prerender()` wrote: page paths and the routes served by the CSR shell. */
+export interface PrerenderReport {
+    pages: string[];
+    /** Route ids served by the CSR shell. */
+    fallback: string[];
+    /** Some page resumes (ships resume state + loader); `false`: every page is zero-JS (no `_data.json` written). */
+    resumes: boolean;
+    /** Script files `prune` deleted (outDir-relative). */
+    pruned?: string[];
+}
+/** Fill a router pattern with params (`:name` encoded, `*name` encoded per segment). */
+export declare function fillPattern(pattern: string, params: Record<string, string>): string;
+/**
+ * Add a CSP `<meta>` to a static page: its inline scripts allowed by SHA-256 hash, script files from
+ * its own origin, no plugins, no `<base>`. (`'strict-dynamic'` would not do: browsers pass a nonce's
+ * trust on to `import()`, but not a hash's, and the resume loader imports its chunks.) Pages without
+ * `<head>` or without inline scripts (and no `options.directives`) are returned unchanged. The `<meta>` goes after a
+ * leading `<meta charset>` and `<meta name="viewport">` (the charset must stay in the first 1024 bytes, first).
+ * `options.directives` merge in (`cspPolicy`): e.g. `{ "script-src": "'wasm-unsafe-eval'", "worker-src": "'self' blob:" }`;
+ * header-only directives (`frame-ancestors`, `report-uri`, `report-to`, `sandbox`) throw.
+ */
+export declare function hashCSP(html: string, options?: CSPOptions): string;
+/**
+ * Prerender every eligible route. Non-prerenderable routes with server modules are errors, and so are two
+ * pages whose paths differ only in letter case (checked before the second one is written).
+ */
+export declare function prerender(options: PrerenderOptions): Promise<PrerenderReport>;
+/**
+ * Prerender a production build (`vite build` + `vite build --ssr`, router `mode: "static"`) into its
+ * client directory, so `<dist>/client` is the deployable site.
+ */
+export declare function prerenderBuild(options?: {
+    dist?: string;
+    origin?: string;
+    shell?: PrerenderOptions["shell"];
+    csp?: PrerenderOptions["csp"];
+    /** Preload planner (`AppConfig.preload`): background prefetch byte budget, `lean` pages (nothing before an interaction). */
+    preload?: AppConfig["preload"];
+    /** i18n: per-locale client builds (see `loadBuild`). */
+    locales?: readonly string[];
+    /** `PrerenderOptions.prune` (default true): a zero-JS site keeps no unreferenced scripts. */
+    prune?: boolean;
+}): Promise<PrerenderReport>;