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

package/build/reach.js

@@ -0,0 +1,302 @@
+// Server reach (SERVER-REACH, spec docs/design/specs/2026-10-20-server-reach-design.md): which server-only modules each
+// route's browser graph reaches, before the build. A page route that reaches one through its own module and plain
+// helper modules becomes a document route (links load its document; its module leaves the client build); a component
+// module on the way (shared, client-rendered on every client navigation to the routes using it), a layout or an error
+// page reaching one is RV3011. Build-time only (Node): sources are read, compiled / type-stripped and parsed here.
+import { readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { parseSync, transformWithOxc } from "vite";
+import { compile } from "@rivetjs/compiler";
+import { docsUrl } from "@rivetjs/compiler/codes";
+import { isServerOnly, SERVER_ONLY_MARKER } from "@rivetjs/compiler/vite";
+export const RV_REACH = "RV3011";
+const SCANNED = /\.[cm]?[jt]sx?$/;
+const COMPONENT = /\.[jt]sx$/;
+// Browser imports per module, by mtime (dev re-runs read only changed files).
+const edgeCache = new Map();
+function namesOf(entries) {
+    return entries.map(({ importName }) => (importName.kind === "Name" ? importName.name : importName.kind === "Default" ? "default" : "*"));
+}
+/** Browser imports of one module: route modules after the server split, `.tsx` as the compiler emits them, `.ts` type-stripped. */
+async function edgesOf(file, route, config) {
+    let mtime;
+    try {
+        mtime = statSync(file).mtimeMs;
+    }
+    catch {
+        return [];
+    }
+    const cached = edgeCache.get(file);
+    if (cached && cached.mtime === mtime && cached.route === route)
+        return cached.edges;
+    const source = readFileSync(file, "utf8");
+    let code;
+    if (route || COMPONENT.test(file)) {
+        const result = compile(source, { target: "dom", filename: file, ...(route ? { serverExports: true } : {}) });
+        // A module that does not compile fails the real build with its own diagnostic; scan its imports as written.
+        if (!result.diagnostics.length)
+            code = result.code;
+    }
+    if (code === undefined && /\.[cm]?[jt]sx?$/.test(file) && !/\.[cm]?js$/.test(file))
+        code = (await transformWithOxc(source, file, { jsx: "preserve" }, undefined, config).catch(() => ({ code: source }))).code;
+    const parsed = parseSync(file.replace(/\.[^./\\]+$/, ".jsx"), code ?? source);
+    const edges = [];
+    const text = code ?? source;
+    for (const item of parsed.module.staticImports) {
+        // Type-only entries survive only where stripping failed: never browser imports.
+        const entries = item.entries.filter((entry) => !entry.isType);
+        if (item.entries.length && !entries.length)
+            continue;
+        edges.push({ spec: item.moduleRequest.value, names: namesOf(entries) });
+    }
+    for (const item of parsed.module.staticExports)
+        for (const entry of item.entries)
+            if (entry.moduleRequest && !entry.isType)
+                edges.push({ spec: entry.moduleRequest.value, names: entry.importName.kind === "Name" ? [entry.importName.name] : ["*"] });
+    for (const item of parsed.module.dynamicImports) {
+        const literal = /^\s*(["'`])([^"'`$]*)\1\s*$/.exec(text.slice(item.moduleRequest.start, item.moduleRequest.end));
+        if (literal)
+            edges.push({ spec: literal[2], names: ["*"] });
+    }
+    edgeCache.set(file, { mtime, route, edges });
+    return edges;
+}
+/** Display path: root-relative inside the root, else `<package name>/<path in the package>`. */
+function displayer(root) {
+    const packages = new Map();
+    const packageOf = (dir) => {
+        for (let at = dir;; at = dirname(at)) {
+            let name = packages.get(at);
+            if (name === undefined) {
+                try {
+                    name = JSON.parse(readFileSync(join(at, "package.json"), "utf8")).name ?? null;
+                }
+                catch {
+                    name = null;
+                }
+                packages.set(at, name);
+            }
+            if (name)
+                return { dir: at, name };
+            if (dirname(at) === at)
+                return null;
+        }
+    };
+    return (id) => {
+        if (!isAbsolute(id))
+            return id;
+        const rel = relative(root, id);
+        if (!rel.startsWith("..") && !isAbsolute(rel))
+            return rel.split(sep).join("/");
+        const pkg = packageOf(dirname(id));
+        return pkg ? pkg.name + "/" + relative(pkg.dir, id).split(sep).join("/") : id;
+    };
+}
+const list = (routes) => (routes.length <= 5 ? routes.join(", ") : routes.slice(0, 5).join(", ") + ` and ${routes.length - 5} more`);
+/** Walk every route's browser graph and classify the routes (see the module comment). */
+export async function analyzeReach(options) {
+    const { root, routesDir, table, serverOnly, routeModules } = options;
+    const show = displayer(root);
+    const abs = (file) => join(routesDir, file);
+    const graph = new Map();
+    const resolved = new Map();
+    const resolveCached = async (spec, importer) => {
+        const key = importer + "\0" + spec;
+        if (!resolved.has(key))
+            resolved.set(key, await options.resolve(spec, importer).catch(() => undefined));
+        return resolved.get(key);
+    };
+    const scannable = (id) => isAbsolute(id) && !id.includes("?") && !id.includes("\0") && SCANNED.test(id) && !id.split(sep).includes("node_modules");
+    const visit = async (seeds) => {
+        const queue = seeds.filter((seed) => !graph.has(seed));
+        for (const seed of queue)
+            graph.set(seed, []);
+        while (queue.length) {
+            const file = queue.shift();
+            const targets = [];
+            for (const edge of await edgesOf(file, routeModules.has(file), options.config)) {
+                const id = await resolveCached(edge.spec, file);
+                const clean = id?.split("?")[0];
+                if (isServerOnly(serverOnly, edge.spec, clean)) {
+                    targets.push({ key: id === undefined || id.startsWith("\0") ? edge.spec : clean, serverOnly: true, spec: edge.spec, names: edge.names });
+                    continue;
+                }
+                if (!id || !scannable(id))
+                    continue;
+                targets.push({ key: id, serverOnly: false, spec: edge.spec, names: edge.names });
+                if (!graph.has(id))
+                    (graph.set(id, []), queue.push(id));
+            }
+            graph.set(file, targets);
+        }
+    };
+    const pages = [...new Set(table.routes.flatMap((route) => (route.page ? [route.page] : [])))];
+    const layouts = [...new Set(table.routes.flatMap((route) => route.layouts.flatMap((layout) => (layout.page ? [layout.page] : []))))];
+    const specials = [
+        ...new Set([
+            table.notFound,
+            table.error,
+            ...(table.notFounds ?? []).map((entry) => entry.page),
+            ...table.routes.flatMap((route) => [route.notFound, route.error]),
+        ].filter((file) => !!file)),
+    ];
+    await visit([...pages, ...layouts, ...specials].map(abs));
+    // Fixpoints (monotone booleans over a graph with cycles): reaches a server-only module; reaches one through a component.
+    const reaches = new Set(), viaComponent = new Set();
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const [file, targets] of graph) {
+            if (!reaches.has(file) && targets.some((t) => t.serverOnly || reaches.has(t.key)))
+                (reaches.add(file), (changed = true));
+            if (!viaComponent.has(file) && targets.some((t) => !t.serverOnly && ((COMPONENT.test(t.key) && reaches.has(t.key)) || viaComponent.has(t.key))))
+                (viaComponent.add(file), (changed = true));
+        }
+    }
+    // Shortest display chain from `from` to a server-only module; `component`: through a component module (not `from`).
+    const chainFrom = (from, component) => {
+        const seen = new Set([from + "\0" + !component]);
+        const queue = [{ file: from, passed: !component, back: null }];
+        while (queue.length) {
+            const state = queue.shift();
+            for (const target of graph.get(state.file) ?? []) {
+                if (target.serverOnly) {
+                    if (!state.passed)
+                        continue;
+                    const files = [];
+                    for (let at = state; at; at = at.back)
+                        files.unshift(at.file);
+                    // Component chains start at the first component (the page and its helpers are the routes' own).
+                    const first = component ? files.findIndex((file, i) => i > 0 && COMPONENT.test(file)) : 0;
+                    return [...files.slice(Math.max(first, 0)).map(show), target.key.startsWith("/") ? show(target.key) : target.key];
+                }
+                const passed = state.passed || COMPONENT.test(target.key);
+                const key = target.key + "\0" + passed;
+                if (seen.has(key) || !reaches.has(target.key))
+                    continue;
+                seen.add(key);
+                queue.push({ file: target.key, passed, back: state });
+            }
+        }
+        return [show(from)];
+    };
+    const reachMode = options.reach ?? "error";
+    const documents = new Map();
+    const problems = [];
+    const byChain = new Map();
+    const patternsOf = (page) => table.routes.filter((route) => route.page === page).map((route) => route.pattern);
+    for (const page of pages) {
+        const file = abs(page);
+        if (!reaches.has(file))
+            continue;
+        const targets = graph.get(file) ?? [];
+        // `import "@rivetjs/router/server-only"` in the page module: the page itself is server-rendered only.
+        const declared = targets.some((t) => t.serverOnly && t.spec === SERVER_ONLY_MARKER);
+        const component = !declared && targets.some((t) => !t.serverOnly && ((COMPONENT.test(t.key) && reaches.has(t.key)) || viaComponent.has(t.key)));
+        if (component) {
+            const chain = chainFrom(file, true);
+            const key = chain.join("\0");
+            let group = byChain.get(key);
+            if (!group)
+                byChain.set(key, (group = { chain, routes: new Set(), files: new Set() }));
+            for (const pattern of patternsOf(page))
+                group.routes.add(pattern);
+            group.files.add(page);
+            if (reachMode === "error")
+                continue;
+        }
+        documents.set(page, chainFrom(file, false));
+    }
+    const docs = "\n  docs: " + docsUrl(RV_REACH);
+    for (const { chain, routes, files } of byChain.values()) {
+        const severity = reachMode === "warn" ? "warning" : "error";
+        const what = routes.size === 1 ? "client-navigated page route" : "client-navigated page routes";
+        problems.push({
+            severity,
+            kind: "component",
+            chain,
+            routes: [...routes],
+            files: [...files],
+            message: `[rivet:router] ${RV_REACH} ${chain.join(" → ")} (server-only), rendered by ${list([...routes])} (${what})` +
+                (severity === "warning" ? "; rendered as document routes (links load their documents)" : "") +
+                "\n  fix: pass the data to the component as props (inlined at build time, or read in the page's `load(…)`), keep server-only modules out of components, or make the page a document route (`import \"" +
+                SERVER_ONLY_MARKER +
+                '"` in the page module); `rivetRouter({ serverOnly: { reach: "warn" } })` turns this into a warning (those pages render as document routes)' +
+                docs,
+        });
+    }
+    for (const [kind, files] of [
+        ["layout", layouts],
+        ["special", specials],
+    ])
+        for (const page of files) {
+            const file = abs(page);
+            if (!reaches.has(file))
+                continue;
+            const chain = chainFrom(file, false);
+            const folder = dirname(page) === "." ? "" : "/" + dirname(page).split(sep).join("/");
+            const routes = kind === "layout"
+                ? table.routes.filter((route) => route.page && route.layouts.some((layout) => layout.page === page)).map((route) => route.pattern)
+                : table.routes.filter((route) => route.notFound === page || route.error === page).map((route) => route.pattern);
+            problems.push({
+                severity: "error",
+                kind,
+                chain,
+                routes,
+                files: [page],
+                message: `[rivet:router] ${RV_REACH} ${chain.join(" → ")} (server-only), rendered by ${kind === "layout" ? `the layout of every page under ${folder || "/"}` : "an error / not-found page"} (client-rendered on navigation and resume)` +
+                    "\n  fix: read the data in the layout's `load(…)` (or a server-only helper called from it) and render it from props; layouts and error pages cannot be document routes" +
+                    docs,
+            });
+        }
+    // Browser graphs: modules of client-rendered routes (non-document pages, layouts, error pages) vs. document pages only.
+    const closure = (seeds) => {
+        const out = new Set();
+        for (const stack = [...seeds]; stack.length;) {
+            const file = stack.pop();
+            if (out.has(file))
+                continue;
+            out.add(file);
+            for (const target of graph.get(file) ?? [])
+                if (!target.serverOnly)
+                    stack.push(target.key);
+        }
+        return out;
+    };
+    const navigable = closure([...pages.filter((page) => !documents.has(page)), ...layouts, ...specials].map(abs));
+    const documentOnly = new Set([...closure([...documents.keys()].map(abs))].filter((file) => !navigable.has(file)));
+    const targets = new Map(), names = new Map(), chains = new Map();
+    for (const [file, edges] of graph)
+        for (const target of edges) {
+            if (!target.serverOnly)
+                continue;
+            targets.set(file + "\0" + target.spec, target.key);
+            let set = names.get(target.key);
+            if (!set)
+                names.set(target.key, (set = new Set()));
+            for (const name of target.names)
+                set.add(name);
+        }
+    // Stand-in messages: the first document page's chain to each server-only module it reaches.
+    for (const page of documents.keys()) {
+        const file = abs(page);
+        for (const reached of closure([file]))
+            for (const target of graph.get(reached) ?? [])
+                if (target.serverOnly && !chains.has(target.key) && documentOnly.has(reached)) {
+                    const chain = chainFrom(file, false);
+                    chains.set(target.key, chain[chain.length - 1] === (target.key.startsWith("/") ? show(target.key) : target.key) ? chain.slice(0, -1) : [show(file), show(reached)]);
+                }
+    }
+    return { documents, problems, documentOnly, targets, names, chains };
+}
+/** Normalize `rivetRouter({ serverOnly })`. */
+export function serverOnlyOption(option) {
+    if (option === undefined)
+        return { modules: [], reach: "error" };
+    const modules = Array.isArray(option) ? option : (option.modules ?? []);
+    const reach = Array.isArray(option) ? "error" : (option.reach ?? "error");
+    if (!modules.every((pattern) => typeof pattern === "string" || pattern instanceof RegExp))
+        throw new Error("rivetRouter: serverOnly modules must be module ids (strings) or RegExps");
+    if (reach !== "error" && reach !== "warn")
+        throw new Error(`rivetRouter: serverOnly.reach must be "error" or "warn" (got ${JSON.stringify(reach)})`);
+    return { modules, reach };
+}

package/build/route-css.d.ts

@@ -0,0 +1,54 @@
+import type { InlineStyleManifest } from "../server/inline-styles.js";
+import type { Rollup, ViteDevServer } from "vite";
+import type { RouteTable } from "./routes.js";
+/** Client build asset: route id → stylesheet URLs (written only when some route has CSS). */
+export declare const ROUTE_CSS = ".vite/rivet-route-css.json";
+/** Stylesheet URLs per route id from a client bundle (empty when no route module imports CSS). */
+export declare function bundleRouteCSS(bundle: Rollup.OutputBundle, table: RouteTable, routesDir: string, base: string): Record<string, string[]>;
+/**
+ * One stylesheet per route: a route whose modules import several stylesheets (per-component CSS, `@rivetjs/ui`)
+ * links them as one merged asset (`assets/route-<hash>.css`, the files joined in link order; routes with the same
+ * list share it), so a page has one render-blocking route sheet next to the global styles. Lists of one file stay.
+ * Returns the merged assets to emit and the route map pointing at them. `prefix` names the asset (docs-kit example
+ * frames: `frame`).
+ */
+export declare function mergeRouteCSS(bundle: Rollup.OutputBundle, css: Record<string, string[]>, base: string, prefix?: string): {
+    routes: Record<string, string[]>;
+    assets: {
+        fileName: string;
+        source: string;
+    }[];
+};
+/** Client build asset: the stylesheets the handler may write inline (`InlineStyleManifest`; written only when some are). */
+export declare const INLINE_CSS = ".vite/rivet-inline-css.json";
+/**
+ * `rivetRouter({ inlineStylesheets })` (Astro's `build.inlineStylesheets` model, decided per page on compressed bytes):
+ * `"auto"` (default) / `{ maxTotalBrotli }`, `"always"`, `"never"`.
+ */
+export type InlineStylesheets = "auto" | "always" | "never" | {
+    readonly maxTotalBrotli?: number;
+};
+/** `auto`: all of a page's sheets inline when their brotli sizes add up to at most this. */
+export declare const MAX_TOTAL_BROTLI = 6144;
+/**
+ * The inline stylesheet manifest (`.vite/rivet-inline-css.json`, `server/inline-styles.ts` decides per page), or
+ * `undefined` when no sheet qualifies (`"never"`, nothing listed). Listed: every client CSS asset and merged route sheet
+ * (keys = the URLs the handler links, `base` + file name) without relative `url()` / `@import` references (they resolve
+ * against the sheet's URL) that could ever go inline — `"always"`: all; `"auto"`: brotli size ≤ `maxTotalBrotli` (the
+ * per-page total) or raw size ≤ `limit` (Vite `build.assetsInlineLimit`, the per-sheet fallback). Brotli at quality 11.
+ */
+export declare function inlineCSS(bundle: Rollup.OutputBundle, extra: readonly {
+    fileName: string;
+    source: string;
+}[], base: string, mode: InlineStylesheets, limit: number): InlineStyleManifest | undefined;
+/**
+ * Drops repeated top-level `@property` / `@keyframes` blocks and `@layer a, b;` statements that are byte-identical to an
+ * earlier one (each per-component stylesheet carries the ones it uses; a repeat changes nothing). Strings and comments
+ * are skipped; anything else is kept as is.
+ */
+export declare function dedupeTopLevel(css: string): string;
+/**
+ * Dev: stylesheets in the SSR module graph of a route's modules (loaded first), as `?direct` links
+ * (no flash before the client graph injects its `<style>`s; `entry.dev.tsx` then removes them).
+ */
+export declare function devRouteCSS(server: ViteDevServer, table: RouteTable, routesDir: string, id: string, exclude: ReadonlySet<string>): Promise<string[]>;

package/build/route-css.js

@@ -0,0 +1,216 @@
+// Per-route stylesheets: the CSS a route's layouts and page can render (their chunks' static
+// import closure), outer → inner, so SSR links exactly the route's CSS in the head.
+import { createHash } from "node:crypto";
+import { brotliCompressSync, constants } from "node:zlib";
+import { resolve } from "node:path";
+/** Client build asset: route id → stylesheet URLs (written only when some route has CSS). */
+export const ROUTE_CSS = ".vite/rivet-route-css.json";
+/** An app entry (router `styles`, CSR app), not a compiler resume chunk. */
+const isStylesEntry = (chunk) => chunk.isEntry && !chunk.facadeModuleId?.includes("rivet-resume-chunk:");
+const routeFiles = (table, routesDir, id) => {
+    const route = table.routes.find((r) => r.id === id);
+    if (!route?.page)
+        return [];
+    return [...route.layouts.flatMap((l) => (l.page ? [l.page] : [])), route.page].map((file) => resolve(routesDir, file));
+};
+/** Stylesheet URLs per route id from a client bundle (empty when no route module imports CSS). */
+export function bundleRouteCSS(bundle, table, routesDir, base) {
+    const chunks = Object.values(bundle).filter((o) => o.type === "chunk");
+    const byFile = new Map(chunks.map((c) => [c.fileName, c]));
+    const owner = new Map();
+    for (const chunk of chunks)
+        for (const id of chunk.moduleIds)
+            owner.set(id.split("?")[0], chunk);
+    // Entry CSS (router `styles`) is linked on every page already. Resume chunks are entries too (compiler inputs,
+    // `\0rivet-resume-chunk:`) but their CSS is a component's: it stays per route.
+    const global = new Set(chunks.filter(isStylesEntry).flatMap((c) => [...(c.viteMetadata?.importedCss ?? [])]));
+    const out = {};
+    for (const id of new Set(table.routes.map((r) => r.id))) {
+        const css = [];
+        const seen = new Set();
+        // Post-order: a chunk's static imports' CSS precedes its own.
+        const visit = (chunk) => {
+            if (seen.has(chunk.fileName))
+                return;
+            seen.add(chunk.fileName);
+            for (const file of chunk.imports) {
+                const imported = byFile.get(file);
+                if (imported)
+                    visit(imported);
+            }
+            for (const file of chunk.viteMetadata?.importedCss ?? [])
+                if (!global.has(file) && !css.includes(base + file))
+                    css.push(base + file);
+        };
+        for (const file of routeFiles(table, routesDir, id)) {
+            const chunk = owner.get(file);
+            if (chunk)
+                visit(chunk);
+        }
+        if (css.length)
+            out[id] = css;
+    }
+    return out;
+}
+/**
+ * One stylesheet per route: a route whose modules import several stylesheets (per-component CSS, `@rivetjs/ui`)
+ * links them as one merged asset (`assets/route-<hash>.css`, the files joined in link order; routes with the same
+ * list share it), so a page has one render-blocking route sheet next to the global styles. Lists of one file stay.
+ * Returns the merged assets to emit and the route map pointing at them. `prefix` names the asset (docs-kit example
+ * frames: `frame`).
+ */
+export function mergeRouteCSS(bundle, css, base, prefix = "route") {
+    const assets = new Map();
+    const routes = {};
+    for (const [id, list] of Object.entries(css)) {
+        const sources = list.map((href) => bundle[href.slice(base.length)]);
+        if (list.length < 2 || sources.some((asset) => asset?.type !== "asset")) {
+            routes[id] = list;
+            continue;
+        }
+        const source = dedupeTopLevel(sources.map((asset) => unmarked(String(asset.source))).join("\n"));
+        const fileName = `assets/${prefix}-${createHash("sha256").update(source).digest("base64url").slice(0, 8)}.css`;
+        assets.set(fileName, source + "\n");
+        routes[id] = [base + fileName];
+    }
+    return { routes, assets: [...assets].map(([fileName, source]) => ({ fileName, source })) };
+}
+// Vite's CSS chunk marker (`/*$vite$:1*/`): still in the bundle's CSS assets during `generateBundle` (Vite drops it when
+// it writes its own assets, not from sources copied elsewhere).
+const unmarked = (css) => css.replace(/\/\*\$vite\$:\d+\*\/\n?/g, "").trim();
+/** Client build asset: the stylesheets the handler may write inline (`InlineStyleManifest`; written only when some are). */
+export const INLINE_CSS = ".vite/rivet-inline-css.json";
+/** `auto`: all of a page's sheets inline when their brotli sizes add up to at most this. */
+export const MAX_TOTAL_BROTLI = 6144;
+// A `url()` / `@import` the document would resolve against its own URL instead of the sheet's: `./` / `../` / bare
+// paths (Vite writes base-absolute URLs unless `base` is relative). Site-absolute, scheme, protocol-relative, `data:`
+// and fragment-only references resolve the same from both.
+const RELATIVE_REFERENCE = /(?:url\(\s*|@import\s+)(["']?)(?![a-z][\w+.-]*:|\/|#|["')\s])/i;
+/**
+ * The inline stylesheet manifest (`.vite/rivet-inline-css.json`, `server/inline-styles.ts` decides per page), or
+ * `undefined` when no sheet qualifies (`"never"`, nothing listed). Listed: every client CSS asset and merged route sheet
+ * (keys = the URLs the handler links, `base` + file name) without relative `url()` / `@import` references (they resolve
+ * against the sheet's URL) that could ever go inline — `"always"`: all; `"auto"`: brotli size ≤ `maxTotalBrotli` (the
+ * per-page total) or raw size ≤ `limit` (Vite `build.assetsInlineLimit`, the per-sheet fallback). Brotli at quality 11.
+ */
+export function inlineCSS(bundle, extra, base, mode, limit) {
+    if (mode === "never")
+        return undefined;
+    const always = mode === "always";
+    const maxTotalBrotli = typeof mode === "object" ? (mode.maxTotalBrotli ?? MAX_TOTAL_BROTLI) : MAX_TOTAL_BROTLI;
+    const sheets = {};
+    const all = [
+        ...Object.values(bundle).flatMap((o) => (o.type === "asset" && o.fileName.endsWith(".css") ? [{ fileName: o.fileName, source: String(o.source) }] : [])),
+        ...extra,
+    ];
+    for (const { fileName, source } of all) {
+        const css = unmarked(source);
+        if (!css || RELATIVE_REFERENCE.test(css))
+            continue;
+        const bytes = Buffer.byteLength(css);
+        const br = brotliCompressSync(css, { params: { [constants.BROTLI_PARAM_QUALITY]: 11, [constants.BROTLI_PARAM_SIZE_HINT]: bytes } }).length;
+        if (always || br <= maxTotalBrotli || bytes <= limit)
+            sheets[base + fileName] = { css, bytes, br };
+    }
+    return Object.keys(sheets).length ? { mode: always ? "always" : "auto", maxTotalBrotli, limit, sheets } : undefined;
+}
+/**
+ * Drops repeated top-level `@property` / `@keyframes` blocks and `@layer a, b;` statements that are byte-identical to an
+ * earlier one (each per-component stylesheet carries the ones it uses; a repeat changes nothing). Strings and comments
+ * are skipped; anything else is kept as is.
+ */
+export function dedupeTopLevel(css) {
+    const seen = new Set();
+    let out = "";
+    let depth = 0;
+    for (let i = 0; i < css.length;) {
+        const ch = css[i];
+        if (ch === '"' || ch === "'") {
+            let j = i + 1;
+            while (j < css.length && css[j] !== ch)
+                j += css[j] === "\\" ? 2 : 1;
+            out += css.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (ch === "/" && css[i + 1] === "*") {
+            const j = css.indexOf("*/", i + 2);
+            const end = j < 0 ? css.length : j + 2;
+            out += css.slice(i, end);
+            i = end;
+        }
+        else if (depth === 0 && ch === "@" && /^@(property|keyframes|-webkit-keyframes|layer)\b/.test(css.slice(i, i + 20))) {
+            const end = blockEnd(css, i);
+            const block = css.slice(i, end);
+            const isStatement = block.endsWith(";");
+            if (!(/^@layer/.test(block) && !isStatement) && seen.has(block)) {
+                i = end;
+                continue;
+            }
+            if (!/^@layer/.test(block) || isStatement)
+                seen.add(block);
+            if (/^@layer/.test(block) && !isStatement) {
+                // A layer block: keep its head, scan its body (nested rules are not deduplicated).
+                out += ch;
+                i++;
+                continue;
+            }
+            out += block;
+            i = end;
+        }
+        else {
+            if (ch === "{")
+                depth++;
+            else if (ch === "}")
+                depth--;
+            out += ch;
+            i++;
+        }
+    }
+    return out;
+}
+/** End (exclusive) of the at-rule starting at `at`: after its `;` (statement) or its balanced `{…}` block. */
+function blockEnd(css, at) {
+    let depth = 0;
+    for (let i = at; i < css.length; i++) {
+        const ch = css[i];
+        if (ch === '"' || ch === "'") {
+            for (i++; i < css.length && css[i] !== ch; i += css[i] === "\\" ? 2 : 1)
+                ;
+        }
+        else if (ch === ";" && depth === 0)
+            return i + 1;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}" && --depth === 0)
+            return i + 1;
+    }
+    return css.length;
+}
+const CSS_REQUEST = /\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)/;
+const NOT_LINKED = /[?&](?:inline|url|raw)\b/;
+/**
+ * Dev: stylesheets in the SSR module graph of a route's modules (loaded first), as `?direct` links
+ * (no flash before the client graph injects its `<style>`s; `entry.dev.tsx` then removes them).
+ */
+export async function devRouteCSS(server, table, routesDir, id, exclude) {
+    const environment = server.environments.ssr;
+    const css = [];
+    const seen = new Set();
+    const visit = (node) => {
+        if (!node?.id || seen.has(node.id))
+            return;
+        seen.add(node.id);
+        for (const imported of node.importedModules)
+            visit(imported);
+        if (CSS_REQUEST.test(node.url) && !NOT_LINKED.test(node.url) && !exclude.has(node.url.split("?")[0])) {
+            const href = node.url + (node.url.includes("?") ? "&" : "?") + "direct";
+            if (!css.includes(href))
+                css.push(href);
+        }
+    };
+    for (const file of routeFiles(table, routesDir, id)) {
+        await server.ssrLoadModule(file);
+        visit(environment.moduleGraph.getModuleById(file));
+    }
+    return css;
+}

package/build/routes.d.ts

@@ -0,0 +1,55 @@
+/** A layout or special page found along a route's folder chain. */
+export interface RouteModule {
+    /** Universal module (component), relative to the routes directory, posix separators. */
+    readonly page?: string;
+    /**
+     * Server-only module: a sibling `*.server.ts` (guard, load, entries, actions, headers, request
+     * handlers), or an endpoint-only plain `x.ts` exporting request handlers.
+     */
+    readonly server?: string;
+    /** The page module itself declares server exports (`load(…)`, `onGet(…)` calls, `prerender`…). */
+    readonly inline?: boolean;
+    /** Page module with `export const live = true`: its `data` prop is an accessor revalidated in place. */
+    readonly live?: boolean;
+}
+/** One matchable route. Optional segments expand into several entries sharing an `id`. */
+export interface RouteEntry extends RouteModule {
+    /** Stable id: the file path without extension, e.g. `blog/[slug]`. */
+    readonly id: string;
+    /** Router pattern for `compileRoutes`, e.g. `/blog/:slug`, `/docs/*rest`. */
+    readonly pattern: string;
+    /** Parameter names in pattern order. */
+    readonly params: readonly string[];
+    /** Layouts from the outermost folder inward. */
+    readonly layouts: readonly RouteModule[];
+    /** Nearest `_404` / `_error` page modules. */
+    readonly notFound?: string;
+    readonly error?: string;
+}
+export interface RouteTable {
+    /** Ordered: the first matching entry wins. */
+    readonly routes: readonly RouteEntry[];
+    /** Root-level `_404` / `_error` for URLs that match no route. */
+    readonly notFound?: string;
+    readonly error?: string;
+    /** `_404` pages under static folders for unmatched URLs, longest URL prefix first (root excluded). */
+    readonly notFounds?: readonly {
+        readonly prefix: string;
+        readonly page: string;
+    }[];
+}
+/**
+ * Build the route table from file paths relative to the routes directory (posix separators).
+ * `exports`: server export kinds per module file (`load`, `onGet`, … the wrapper names, `?` for a re-export
+ * from a server-only module, plus the flags `prerender` / `live`; `scanRoutes` reads them): pages/layouts
+ * with any are `inline`, plain `.ts` files with a request handler are endpoint routes.
+ */
+export declare function routeTable(files: readonly string[], exports?: ReadonlyMap<string, readonly string[]>): RouteTable;
+/** Scan a routes directory and build its table (reads modules for their server exports). */
+export declare function scanRoutes(dir: string): Promise<RouteTable>;
+/**
+ * Server export kinds of route modules (pages, layouts, plain `.ts` files), by file (see `routeTable`);
+ * `prerender` and `live` pages are listed with their flag. Throws on a module whose exports misdeclare the
+ * route (RV3010 untagged magic name, duplicate kind): the file and the compiler's message.
+ */
+export declare function _serverExportsOf(dir: string, files: readonly string[]): Promise<Map<string, string[]>>;