bosia 1.2.2 → 1.2.4

package/src/core/prerender.ts

@@ -7,6 +7,8 @@ import type { RuntimeTarget } from "./types/plugin.ts";
 import { BOSIA_NODE_PATH, OUT_DIR } from "./paths.ts";
 import { currentBase } from "./appBase.ts";
 import { prerenderSkipReason, wantsPrerender } from "./scanner.ts";
+import { isDynamic, segmentName, segmentRank } from "./matcher.ts";
+import { HEALTH_PATH, isFrameworkPath, isStaticPath } from "./staticPath.ts";
 
 /** Acquire an OS-assigned ephemeral port. Tiny TOCTOU race window; acceptable for build-time use. */
 export function getEphemeralPort(): Promise<number> {
@@ -54,8 +56,10 @@ const PRERENDER_CONCURRENCY = Number(process.env.PRERENDER_CONCURRENCY) || 6;
 
 // ─── Prerendering ─────────────────────────────────────────
 
-interface PrerenderTarget {
+export interface PrerenderTarget {
 	path: string;
+	/** Route pattern the path came from (`/[slug]`); equals `path` for a static route. */
+	route: string;
 	kind: "page" | "api";
 	/** Page targets only; APIs always write a single `.json` file regardless of slash mode. */
 	trailingSlash: TrailingSlash;
@@ -68,23 +72,43 @@ interface PrerenderTarget {
  * concrete values from an `entries()` record.
  */
 export function substituteParams(pattern: string, entry: Record<string, string>): string {
-	let resolved = pattern;
-	for (const [key, value] of Object.entries(entry)) {
-		// `..` and `\` are never legitimate in a route segment — they let a build
-		// emit prerendered HTML outside the intended output tree. Forward slashes
-		// are only allowed for catch-all (`[...key]`) segments, which by design
-		// expand to multiple path parts. Validate accordingly.
-		const isRest = pattern.includes(`[...${key}]`);
-		if (/\\|\.\./.test(value) || (!isRest && value.includes("/"))) {
-			throw new Error(
-				`Prerender entries(): unsafe value "${value}" for [${key}] — ` +
-					`path traversal characters are not allowed in dynamic segment values.`,
-			);
-		}
-		resolved = resolved.replace(`[...${key}]`, value);
-		resolved = resolved.replace(`[${key}]`, value);
-	}
-	return resolved;
+	// Per segment, so an inserted value is never re-read as a placeholder.
+	return pattern
+		.split("/")
+		.map((seg, i, segs) => {
+			const rank = segmentRank(seg);
+			if (!rank) return seg;
+			const name = segmentName(seg);
+			if (entry[name] == null || !Object.hasOwn(entry, name))
+				throw new Error(`entries() gave no value for ${seg}`);
+			// A catch-all may end in one "/" ("guide/intro/"); the out path drops it.
+			const value = rank === 2 ? String(entry[name]).replace(/\/$/, "") : String(entry[name]);
+			const bad = (why: string): never => {
+				throw new Error(
+					`entries() value ${JSON.stringify(String(entry[name]))} for ${seg} is unsafe — ${why}`,
+				);
+			};
+			// Strict on purpose (decided 2026-10-14): ASCII unreserved URL characters only, so the
+			// fetched URL, the file written and a static host's lookup all agree, with nothing to
+			// percent-encode or decode. `50%-off`, `café`, `what%3F` fail by design: slugify them.
+			// No part may end in `.`: the URL parser folds `.`/`..`, and Windows drops trailing
+			// dots (`v1.` → `v1`), so the page would land on another route's file. No part may
+			// start with `.` either: static hosts hide dotfiles (`.env`).
+			const parts = rank === 2 ? value.split("/") : [value];
+			if (!parts.every((part) => /^(?!\.)[A-Za-z0-9._~-]*[A-Za-z0-9_~-]$/.test(part)))
+				bad(
+					`use only ASCII letters, digits, - _ . ~${rank === 2 ? " and /" : ""}, with no empty parts or leading/trailing \`.\``,
+				);
+			// Windows device names: writing `nul.html` hits the device, not a file.
+			if (parts.some((part) => /^(con|prn|aux|nul|com\d|lpt\d)(\.|$)/i.test(part)))
+				bad("Windows device names (con, nul, com1, …) are not allowed");
+			// Only the URL's last part names a file: `index` is written as `<parent>/index.html`,
+			// which serves the parent URL; `post.html` as `post.html.html`, never served for it.
+			if (i === segs.length - 1 && /^index$|\.(html|json)$/i.test(parts.at(-1)!))
+				bad("the last part can't be `index` or end with .html or .json");
+			return value;
+		})
+		.join("/");
 }
 
 /**
@@ -112,6 +136,11 @@ export function prerenderDataPath(routePath: string): string {
 	return routePath === "/" ? "/index.json" : `${routePath.replace(/\/$/, "")}.json`;
 }
 
+/** Where a page's data payload is written. */
+export function prerenderDataOutPath(routePath: string): string {
+	return `${OUT_DIR}/prerendered/__bosia/data${prerenderDataPath(routePath)}`;
+}
+
 /**
  * Output filename for a prerendered API route. Always emits a single `.json`
  * file at the route's path (no trailing-slash variants — static hosts serve
@@ -121,6 +150,42 @@ export function prerenderApiOutPath(routePath: string): string {
 	return `${OUT_DIR}/prerendered${routePath.replace(/\/$/, "")}.json`;
 }
 
+/** A dynamic prerender route whose entries() can't be used. build.ts prints `message` and exits. */
+export class PrerenderEntriesError extends Error {
+	override name = "PrerenderEntriesError";
+}
+
+/**
+ * Throws when a dynamic route's path would save the wrong thing. Pure, so the invariant
+ * tests (test/prerender-invariants.test.ts) can sweep every value × slash mode × kind.
+ */
+export function checkPrerenderPaths(
+	paths: string[],
+	kind: "page" | "api",
+	ts: TrailingSlash,
+): void {
+	for (const p of paths) {
+		// `dist/` and `__bosia/` are the framework's folders in static/: `dist/client` is copied
+		// after the pages, so on macOS/Windows a page folder `DIST/` would swallow the bundle
+		// (served as `DIST/client/…`, a 404 on case-sensitive hosts). A page `/dist` also fails:
+		// `/dist/` is answered as a static file, not 308'd to it.
+		// Lowercased for case-insensitive disks; a page's `/` form is tested too, so `/dist` fails.
+		const lower = p.toLowerCase();
+		if (isFrameworkPath(kind === "page" ? `${lower}/` : lower))
+			throw new Error(`entries() gives ${p}; dist and __bosia are the framework's folders`);
+		// The server answers `/_health`, and for pages any static-file ending like `.png`, itself,
+		// so the saved file would hold its reply, not the route. Checked on the slash-less form:
+		// `/logo.png` 404s before the 308 to `/logo.png/`, and the `/` form adds only the prefixes
+		// rejected above (the invariant test checks both forms).
+		if (p === HEALTH_PATH || (kind === "page" && isStaticPath(p)))
+			throw new Error(`entries() gives ${p}, a URL the server answers itself`);
+		// generateStaticSite copies prerendered/ over static/, where the 404 probe saves
+		// 404.html. A static src/routes/404 page may replace it on purpose; a slug may not.
+		if (kind === "page" && ts === "never" && lower === "/404")
+			throw new Error("an entries() value would overwrite 404.html, the not-found page");
+	}
+}
+
 /** Dynamic route → import module, call entries(), expand to concrete targets. */
 async function expandDynamicRoute(
 	pattern: string,
@@ -130,23 +195,22 @@ async function expandDynamicRoute(
 ): Promise<PrerenderTarget[]> {
 	try {
 		const mod = await import(join(process.cwd(), filePath));
-		if (typeof mod.entries !== "function") {
-			console.warn(`   ⚠️  ${pattern} has prerender=true but no entries() export — skipped`);
-			return [];
-		}
+		if (typeof mod.entries !== "function")
+			throw new Error("prerender = true on a dynamic route needs an entries() export");
 		const entryList: Record<string, string>[] = await mod.entries();
-		return entryList.map((entry) => ({
-			path: substituteParams(pattern, entry),
-			kind,
-			trailingSlash: ts,
-		}));
+		// A repeated value (a tag on two posts) is written once. Only within this route:
+		// the same URL from two routes is a clash, reported by findPrerenderClash.
+		const paths = [...new Set(entryList.map((entry) => substituteParams(pattern, entry)))];
+		checkPrerenderPaths(paths, kind, ts);
+		return paths.map((path) => ({ path, route: pattern, kind, trailingSlash: ts }));
 	} catch (err) {
-		console.error(`   ❌ Failed to resolve entries() for ${pattern}:`, err);
-		return [];
+		// Fail the build: skipping the route would silently drop every page it lists.
+		const why = err instanceof Error ? err.message : String(err);
+		throw new PrerenderEntriesError(`Prerender failed for ${pattern}: ${why}`, { cause: err });
 	}
 }
 
-async function detectPrerenderRoutes(manifest: RouteManifest): Promise<PrerenderTarget[]> {
+export async function detectPrerenderRoutes(manifest: RouteManifest): Promise<PrerenderTarget[]> {
 	const pageTasks = manifest.pages.map(async (route): Promise<PrerenderTarget[]> => {
 		if (!route.pageServer) return [];
 		const filePath = join("src", "routes", route.pageServer);
@@ -158,24 +222,73 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 			return [];
 		}
 		const ts = route.trailingSlash;
-		if (route.pattern.includes("[")) return expandDynamicRoute(route.pattern, filePath, "page", ts);
-		return [{ path: route.pattern, kind: "page", trailingSlash: ts }];
+		if (isDynamic(route.pattern)) return expandDynamicRoute(route.pattern, filePath, "page", ts);
+		return [{ path: route.pattern, route: route.pattern, kind: "page", trailingSlash: ts }];
 	});
 
 	const apiTasks = manifest.apis.map(async (route): Promise<PrerenderTarget[]> => {
 		const filePath = join("src", "routes", route.server);
 		const content = await Bun.file(filePath).text();
 		if (!wantsPrerender(content)) return [];
-		if (route.pattern.includes("["))
+		if (isDynamic(route.pattern))
 			return expandDynamicRoute(route.pattern, filePath, "api", "never");
-		return [{ path: route.pattern, kind: "api", trailingSlash: "never" }];
+		return [{ path: route.pattern, route: route.pattern, kind: "api", trailingSlash: "never" }];
 	});
 
-	// Unbounded Promise.all over all routes; each task holds only small text reads
+	// Unbounded Promise.allSettled over all routes; each task holds only small text reads
 	// and route metadata, so RAM stays trivial. Chunk it if route counts ever hit
 	// tens of thousands (open file descriptors would be the first limit).
-	const results = await Promise.all([...pageTasks, ...apiTasks]);
-	return results.flat();
+	const results = await Promise.allSettled([...pageTasks, ...apiTasks]);
+	// List every broken entries() route in one error, not just the first.
+	const failed = results.flatMap((r) => (r.status === "rejected" ? [r.reason] : []));
+	const other = failed.find((e) => !(e instanceof PrerenderEntriesError));
+	if (other) throw other;
+	// One `❌` per route; a multi-line message (a ZodError) stays under its own mark.
+	if (failed.length)
+		throw new PrerenderEntriesError(failed.map((e) => `❌ ${e.message}`).join("\n"), {
+			cause: failed,
+		});
+	const targets = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+	const clash = findPrerenderClash(targets);
+	if (clash.length) throw new PrerenderEntriesError(clash.join("\n"));
+	return targets;
+}
+
+/**
+ * Files two targets would both write. macOS/Windows ignore case, so `About` and `about`
+ * (or folders `A/` and `a/`) merge; a file and a folder can't share a path either.
+ * Every folder level counts, and so do data payloads.
+ */
+export function findPrerenderClash(targets: PrerenderTarget[]): string[] {
+	const owners = new Map<string, { path: string; who: string; file: boolean }>();
+	const clashes: string[] = [];
+	for (const t of targets) {
+		// Name the route a slug came from, so the message says which file to fix.
+		const who = t.route === t.path ? t.path : `${t.path} (from ${t.route})`;
+		let clash = "";
+		const files =
+			t.kind === "api"
+				? [prerenderApiOutPath(t.path)]
+				: [prerenderOutPath(t.path, t.trailingSlash), prerenderDataOutPath(t.path)];
+		// One ❌ per URL, but every file is still recorded so a later target can't slip past it.
+		for (const out of files) {
+			const segs = out.split("/");
+			for (let i = 1; i <= segs.length; i++) {
+				const path = segs.slice(0, i).join("/");
+				const file = i === segs.length;
+				const key = path.toLowerCase();
+				const prev = owners.get(key);
+				if (!prev) owners.set(key, { path, who, file });
+				// Only two folders with the exact same name may share a path.
+				else if (!clash && (prev.path !== path || file || prev.file)) {
+					const what = file && prev.file ? "file" : "path";
+					clash = `❌ Prerender: ${prev.who} and ${who} write the same ${what} (${path})`;
+				}
+			}
+		}
+		if (clash) clashes.push(clash);
+	}
+	return clashes;
 }
 
 export async function prerenderStaticRoutes(
@@ -302,7 +415,7 @@ export async function prerenderStaticRoutes(
 				});
 				if (dataRes.ok) {
 					const dataJson = await dataRes.text();
-					const dataOutPath = `${OUT_DIR}/prerendered/__bosia/data${dataPath}`;
+					const dataOutPath = prerenderDataOutPath(routePath);
 					mkdirSync(dataOutPath.substring(0, dataOutPath.lastIndexOf("/")), {
 						recursive: true,
 					});

package/src/core/routeFile.ts

@@ -2,6 +2,7 @@ import { writeFileSync, mkdirSync } from "fs";
 import type { RouteManifest } from "./types.ts";
 import { currentBase } from "./appBase.ts";
 import { toPosix } from "./paths.ts";
+import { segmentRank } from "./matcher.ts";
 
 /**
  * The pattern the *client* router matches against. It sees real browser URLs, so
@@ -28,23 +29,26 @@ function clientPattern(pattern: string): string {
 //   serverRoutes  — used by SSR renderer (+ pageServer + layoutServers)
 //   apiRoutes     — used by API handler
 
-function routePriority(pattern: string): number {
-	if (!pattern.includes("[")) return 0; // exact
-	if (!pattern.includes("[...")) return 1; // dynamic
-	return 2; // catch-all
-}
-
-function sortRoutes<T extends { pattern: string }>(routes: T[]): T[] {
-	return [...routes].sort((a, b) => {
-		const pa = routePriority(a.pattern);
-		const pb = routePriority(b.pattern);
-		if (pa !== pb) return pa - pb;
-		// same tier: more segments first, then alphabetical
-		const sa = a.pattern.split("/").length;
-		const sb = b.pattern.split("/").length;
-		if (sa !== sb) return sb - sa;
-		return a.pattern.localeCompare(b.pattern);
-	});
+/** Most specific first: compared segment by segment, the first differing kind
+ *  decides (so `/label/[id]` beats `/[a]/[b]`, `/blog/[...r]` beats `/[a]/about`).
+ *  Ties fall back to more segments first, then alphabetical. findMatch takes the
+ *  first match, so this order is the routing precedence. */
+export function sortRoutes<T extends { pattern: string }>(routes: T[]): T[] {
+	return routes
+		.map((route) => ({ route, ranks: route.pattern.split("/").filter(Boolean).map(segmentRank) }))
+		.sort((a, b) => {
+			const ra = a.ranks;
+			const rb = b.ranks;
+			for (let i = 0; i < Math.min(ra.length, rb.length); i++) {
+				if (ra[i] !== rb[i]) return ra[i]! - rb[i]!;
+			}
+			if (ra.length !== rb.length) return rb.length - ra.length;
+			// plain code-unit compare: same order on every machine, unlike localeCompare
+			const pa = a.route.pattern;
+			const pb = b.route.pattern;
+			return pa < pb ? -1 : pa > pb ? 1 : 0;
+		})
+		.map((x) => x.route);
 }
 
 /** `defaultTitle` is what a page with no title of its own is called: app.html's

package/src/core/routeTypes.ts

@@ -1,7 +1,9 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import type { RouteManifest } from "./types.ts";
+import { segmentName, segmentRank } from "./matcher.ts";
 import { toPosix } from "./paths.ts";
+import { PARAM_NAME } from "./scanner.ts";
 
 // ─── Route Types Generator ────────────────────────────────
 // Generates .bosia/types/src/routes/**/$types.d.ts for each
@@ -23,13 +25,7 @@ function paramsForDir(dir: string): string[] {
 		.filter((s) => !/^\(.*\)$/.test(s));
 	const out: string[] = [];
 	for (const seg of segs) {
-		const catchAll = seg.match(/^\[\.\.\.(\w+)\]$/);
-		if (catchAll) {
-			out.push(catchAll[1]!);
-			continue;
-		}
-		const dyn = seg.match(/^\[(\w+)\]$/);
-		if (dyn) out.push(dyn[1]!);
+		if (segmentRank(seg)) out.push(segmentName(seg));
 	}
 	return out;
 }
@@ -75,8 +71,11 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		const srcBase = `${up}src/routes/${segments.length ? segments.join("/") + "/" : ""}`;
 
 		const params = paramsForDir(dir);
+		// Quoted fallback: a cached manifest (BOSIA_SKIP_ROUTE_SCAN) may predate the name check.
 		const paramsType =
-			params.length === 0 ? `{}` : `{ ${params.map((p) => `${p}: string`).join("; ")} }`;
+			params.length === 0
+				? `{}`
+				: `{ ${params.map((p) => `${PARAM_NAME.test(p) ? p : JSON.stringify(p)}: string`).join("; ")} }`;
 
 		const lines: string[] = ["// AUTO-GENERATED by bosia — do not edit\n"];
 		lines.push(`import type { LoadEvent, MetadataEvent, RequestEvent, Metadata } from 'bosia';`);
@@ -101,7 +100,9 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 
 		if (info.pageServer) {
 			lines.push(``);
-			lines.push(`import type { load as _pageLoad } from '${srcBase}+page.server.ts';`);
+			lines.push(
+				`import type { load as _pageLoad } from ${JSON.stringify(srcBase + "+page.server.ts")};`,
+			);
 			lines.push(`export type PageServerLoad = (event: _LoadEvent) => any;`);
 			lines.push(
 				`export type PageMetadataLoad = (event: _MetadataEvent) => Metadata | Promise<Metadata>;`,
@@ -131,7 +132,9 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		// ActionData — union of all action return types, unwrapping ActionFailure
 		if (info.pageServer) {
 			lines.push(``);
-			lines.push(`import type { actions as _actions } from '${srcBase}+page.server.ts';`);
+			lines.push(
+				`import type { actions as _actions } from ${JSON.stringify(srcBase + "+page.server.ts")};`,
+			);
 			lines.push(
 				`type _ActionReturn<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;`,
 			);
@@ -144,7 +147,9 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		}
 
 		if (info.layoutServer) {
-			lines.push(`\nimport type { load as _layoutLoad } from '${srcBase}+layout.server.ts';`);
+			lines.push(
+				`\nimport type { load as _layoutLoad } from ${JSON.stringify(srcBase + "+layout.server.ts")};`,
+			);
 			lines.push(`export type LayoutServerLoad = (event: _LoadEvent) => any;`);
 			lines.push(`export type LayoutData = Awaited<ReturnType<typeof _layoutLoad>>;`);
 			lines.push(`export type LayoutProps = { data: LayoutData; params: Params; children: any };`);

package/src/core/scanner.ts

@@ -1,6 +1,7 @@
 import { readdirSync, existsSync, readFileSync } from "fs";
 import { join } from "path";
 import type { PageRoute, ApiRoute, RouteManifest, TrailingSlash } from "./types.ts";
+import { segmentName, segmentRank } from "./matcher.ts";
 
 // ─── Route Scanner ───────────────────────────────────────
 // Walks src/routes/ and produces a RouteManifest.
@@ -192,19 +193,22 @@ export function scanRoutes(): RouteManifest {
 
 	walk("", [], [], [], [], "never", null);
 
-	// Warn when a catch-all exists but no exact route covers its prefix.
-	// e.g. "/[...slug]" matches everything EXCEPT "/" (which needs its own +page.svelte).
-	const exactPatterns = new Set(
-		pages.filter((p) => !p.pattern.includes("[")).map((p) => p.pattern),
-	);
+	// Invalid segments first, so they get their own message, not a conflict or warning.
+	checkParams(pages, (p) => p.page);
+	checkParams(apis, (a) => a.server);
+
+	// Warn when a trailing catch-all exists but no page covers its prefix.
+	// e.g. "/[...slug]" matches everything EXCEPT "/" (which needs its own +page.svelte),
+	// "/[lang]/[...rest]" needs "/[lang]" for "/en".
+	const pageKeys = new Set(pages.map((p) => routeKey(p.pattern)));
 	for (const p of pages) {
-		const m = p.pattern.match(/^(.*?)\/\[\.\.\.(\w+)\]$/);
-		if (m) {
-			const exactEquivalent = m[1] || "/";
-			if (!exactPatterns.has(exactEquivalent)) {
+		const cut = p.pattern.lastIndexOf("/");
+		if (segmentRank(p.pattern.slice(cut + 1)) === 2) {
+			const exactEquivalent = p.pattern.slice(0, cut) || "/";
+			if (!pageKeys.has(routeKey(exactEquivalent))) {
 				console.warn(
-					`⚠️  No exact route for "${exactEquivalent}" — the catch-all "${p.pattern}" will NOT match it.\n` +
-						`   Add a +page.svelte at the "${exactEquivalent}" level to serve that URL.`,
+					`⚠️  The catch-all "${p.pattern}" doesn't match "${exactEquivalent}" itself.\n` +
+						`   Add a +page.svelte at "${exactEquivalent}" unless another route already serves it.`,
 				);
 			}
 		}
@@ -228,7 +232,7 @@ export function scanRoutes(): RouteManifest {
 function preventConflicts<T extends { pattern: string }>(routes: T[], fileOf: (r: T) => string) {
 	const seen = new Map<string, T>();
 	for (const r of routes) {
-		const key = r.pattern.replace(/\[\.\.\.\w+\]/g, "[...]").replace(/\[\w+\]/g, "[]");
+		const key = routeKey(r.pattern);
 		const first = seen.get(key);
 		if (!first) {
 			seen.set(key, r);
@@ -244,7 +248,62 @@ function preventConflicts<T extends { pattern: string }>(routes: T[], fileOf: (r
 	}
 }
 
-/** Two route files resolve to the same URL. Callers print `message` and exit. */
+const KINDS = ["", "[]", "[...]"];
+
+/** The URL shape of a pattern, param names dropped: `/[lang]/[...rest]` → `/[]/[...]`. */
+function routeKey(pattern: string): string {
+	return pattern.replace(/[^/]+/g, (seg) => {
+		const rank = segmentRank(seg);
+		return rank ? KINDS[rank]! : seg;
+	});
+}
+
+/**
+ * Fail on params the matcher can't serve: brackets that don't wrap a whole
+ * segment, a `[...rest]` that isn't the last segment, `__proto__`, or one name
+ * bound twice. Mid-path catch-alls (`docs/[...path]/edit`) are left out on
+ * purpose: each needs an unanchored `(.+)` (several backtrack for seconds on a
+ * long URL) and span-aware ranking.
+ * Add both together if that route shape is ever needed.
+ */
+function checkParams<T extends { pattern: string }>(routes: T[], fileOf: (r: T) => string) {
+	for (const r of routes) {
+		const segs = r.pattern.split("/").filter(Boolean);
+		const names = new Set<string>();
+		const fail = (problem: string) => {
+			throw new RouteConflictError(
+				`The "${r.pattern}" route is invalid: ${problem}.\n   src/routes/${fileOf(r)}`,
+			);
+		};
+		for (const [i, seg] of segs.entries()) {
+			const rank = segmentRank(seg);
+			if (!rank) {
+				// `[...]`, `[.x]` would match only their literal text.
+				if (/^\[[^[\]/]*\]$/.test(seg)) fail(BAD_NAME(seg));
+				// `[id].json`, `post-[slug]`, `[[lang]]`.
+				if (/[[\]]/.test(seg)) fail(`${seg} must be a whole segment like [slug] or [...rest]`);
+				continue;
+			}
+			const name = segmentName(seg);
+			if (rank === 2 && i !== segs.length - 1) fail(`${seg} must be the last part of the route`);
+			if (!PARAM_NAME.test(name)) fail(BAD_NAME(seg));
+			// params is a plain object: assigning "__proto__" sets the prototype, not a key.
+			if (name === "__proto__") fail(`"__proto__" can't be a param name`);
+			if (names.has(name)) fail(`the param "${name}" is used twice`);
+			names.add(name);
+		}
+	}
+}
+
+// Strict on purpose (decided 2026-10-14): an ASCII TypeScript identifier, so `params.name`
+// always works: `[slug]`, `[x123]`, `[user_id]`, `[_id]`, `[$id]`. `[post-id]`, `[file.name]`,
+// `[slüg]` fail by design, with one message (no per-typo hints).
+export const PARAM_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const BAD_NAME = (seg: string) =>
+	`${seg}: a param name uses ASCII letters, digits, _ and $, and can't start with a digit (like [slug], [user_id] or [...rest])`;
+
+/** A route tree the build refuses (two files at one URL, or an invalid param).
+ *  Callers print `message` and exit. */
 export class RouteConflictError extends Error {
 	override name = "RouteConflictError";
 }

package/src/core/server.ts

@@ -15,6 +15,7 @@ import { NO_FRAME_GUARD_HEADER, type Handle, type RequestEvent } from "./hooks.t
 import { HttpError, Redirect, ActionFailure, isHttpError, isRedirect } from "./errors.ts";
 import { CookieJar } from "./cookies.ts";
 import { safePath } from "./safePath.ts";
+import { HEALTH_PATH, isFrameworkPath, isStaticPath } from "./staticPath.ts";
 import { checkCsrf } from "./csrf.ts";
 import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
@@ -25,7 +26,6 @@ import {
 	compress,
 	compressBytes,
 	encodeForRequest,
-	isStaticPath,
 	distManifest,
 	PRECOMPRESSED,
 	type Encoded,
@@ -372,7 +372,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	const method = request.method.toUpperCase();
 
 	// Health check endpoint — for load balancers and orchestrators
-	if (path === "/_health") {
+	if (path === HEALTH_PATH) {
 		if (shuttingDown) {
 			return Response.json({ status: "shutting_down" }, { status: 503 });
 		}
@@ -593,7 +593,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// by a user `+server.ts`, so serve them straight from the manifest before the
 	// API scan. A miss falls through to the normal path (which 404s). Keeps the
 	// api-before-static ordering intact for every user-facing path.
-	if (staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
+	if (staticManifest && isFrameworkPath(path)) {
 		const hit = lookupStatic(staticManifest, path);
 		if (hit) return serveStatic(hit, request);
 	}
@@ -1144,7 +1144,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 	}
 
 	// Reject new non-health requests during shutdown
-	if (shuttingDown && url.pathname !== "/_health") {
+	if (shuttingDown && url.pathname !== HEALTH_PATH) {
 		return new Response("Service Unavailable", {
 			status: 503,
 			headers: { "Retry-After": "5" },
@@ -1154,7 +1154,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 	// Shed load above MAX_INFLIGHT. Checked before any work so the 503 is
 	// cheap. /_health stays available so the orchestrator can still tell the
 	// process is alive (and decide whether to restart or scale out).
-	if (inFlight >= MAX_INFLIGHT && url.pathname !== "/_health") {
+	if (inFlight >= MAX_INFLIGHT && url.pathname !== HEALTH_PATH) {
 		return new Response("Service Unavailable", {
 			status: 503,
 			headers: { "Retry-After": "1" },
@@ -1215,7 +1215,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		const path = event.url.pathname;
 		let response: Response | null = null;
 		let staticTried = false;
-		if (!dataReq && staticManifest && (path.startsWith("/dist/") || path.startsWith("/__bosia/"))) {
+		if (!dataReq && staticManifest && isFrameworkPath(path)) {
 			response = await serveStaticFile(path, request);
 			staticTried = true;
 		}

package/src/core/staticPath.ts

@@ -0,0 +1,35 @@
+// URLs the server answers as static files, never as pages. No imports and no top-level
+// work: the build loads this before loadEnv(), so it must not touch env or the base path.
+
+const STATIC_EXTS = new Set([
+	".ico",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".svg",
+	".css",
+	".js",
+	".woff",
+	".woff2",
+	".ttf",
+	".xml",
+	".txt",
+	".json",
+	".webmanifest",
+]);
+
+// The server answers these itself; prerender rejects entries() values that reach them.
+export const HEALTH_PATH = "/_health";
+
+// The framework's own folders: built assets and data/runtime endpoints.
+export function isFrameworkPath(path: string): boolean {
+	return path.startsWith("/dist/") || path.startsWith("/__bosia/");
+}
+
+export function isStaticPath(path: string): boolean {
+	if (isFrameworkPath(path)) return true;
+	const dot = path.lastIndexOf(".");
+	return dot !== -1 && STATIC_EXTS.has(path.slice(dot));
+}

package/templates/demo/src/routes/(public)/blog/[slug]/+page.server.ts

@@ -29,7 +29,7 @@ This page lives at routes/(public)/blog/[slug]/+page.svelte but is served at /bl
 
 The matched value is available as params.slug inside +page.server.ts load() and inside the page component via the params prop.
 
-The route matcher uses 3-pass priority: exact matches first, then dynamic segments, then catch-all routes.`,
+The route matcher compares routes part by part: a fixed name beats a param, which beats a catch-all.`,
 	},
 };