bosia 1.2.1 → 1.2.3

package/src/core/prerender.ts

@@ -1,11 +1,13 @@
-import { writeFileSync, mkdirSync, cpSync, existsSync } from "fs";
+import { writeFileSync, mkdirSync, cpSync, existsSync, readFileSync } from "fs";
 import { createServer } from "net";
 import { join } from "path";
 import type { RouteManifest, TrailingSlash } from "./types.ts";
+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";
 
 /** Acquire an OS-assigned ephemeral port. Tiny TOCTOU race window; acceptable for build-time use. */
 export function getEphemeralPort(): Promise<number> {
@@ -28,6 +30,26 @@ export function getEphemeralPort(): Promise<number> {
 
 const CORE_DIR = import.meta.dir;
 
+/**
+ * True when the app's wrangler config serves `404.html` for unknown paths
+ * (`not_found_handling: "404-page"`) and `public/404.html` doesn't provide one,
+ * so a failed 404 probe must fail the build. Reads the text, skipping whole-line
+ * `//` and `#` comments; a block comment around the key still counts.
+ */
+export function needsStatic404(cwd = process.cwd()): boolean {
+	if (existsSync(join(cwd, "public", "404.html"))) return false;
+	for (const name of ["wrangler.jsonc", "wrangler.json", "wrangler.toml"]) {
+		const file = join(cwd, name);
+		if (!existsSync(file)) continue;
+		const text = readFileSync(file, "utf-8")
+			.split("\n")
+			.filter((line) => !/^\s*(\/\/|#)/.test(line))
+			.join("\n");
+		return /not_found_handling"?\s*[:=]\s*"404-page"/.test(text);
+	}
+	return false;
+}
+
 const PRERENDER_TIMEOUT = Number(process.env.PRERENDER_TIMEOUT) || 5_000; // 5s default
 const PRERENDER_CONCURRENCY = Number(process.env.PRERENDER_CONCURRENCY) || 6;
 
@@ -47,23 +69,38 @@ 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) => {
+			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 "${entry[name]}" for ${seg} is unsafe — ${why}`);
+			};
+			// Check what the server will see: `%2e%2e` and `%2F` decode to `..` and `/`.
+			let decoded = value;
+			try {
+				decoded = decodeURIComponent(value);
+			} catch {
+				bad("invalid percent-encoding");
+			}
+			// `..` and `\` let a build write outside the output tree.
+			if (/\\|\.\./.test(decoded)) bad("path traversal characters are not allowed");
+			// The fetched URL would differ from the file written.
+			if (/[?#]/.test(decoded)) bad("`?` and `#` are not allowed");
+			if (rank === 1 && decoded.includes("/")) bad("`/` is only allowed in a [...rest] param");
+			// An empty or "." part would land on the parent route's file.
+			if (decoded.split("/").some((part) => part === "" || part === "."))
+				bad("empty or `.` parts are not allowed");
+			return value;
+		})
+		.join("/");
 }
 
 /**
@@ -100,6 +137,11 @@ 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";
+}
+
 /** Dynamic route → import module, call entries(), expand to concrete targets. */
 async function expandDynamicRoute(
 	pattern: string,
@@ -109,10 +151,8 @@ 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),
@@ -120,8 +160,9 @@ async function expandDynamicRoute(
 			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 });
 	}
 }
 
@@ -137,7 +178,7 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 			return [];
 		}
 		const ts = route.trailingSlash;
-		if (route.pattern.includes("[")) return expandDynamicRoute(route.pattern, filePath, "page", ts);
+		if (isDynamic(route.pattern)) return expandDynamicRoute(route.pattern, filePath, "page", ts);
 		return [{ path: route.pattern, kind: "page", trailingSlash: ts }];
 	});
 
@@ -145,7 +186,7 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 		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" }];
 	});
@@ -157,23 +198,44 @@ async function detectPrerenderRoutes(manifest: RouteManifest): Promise<Prerender
 	return results.flat();
 }
 
-export async function prerenderStaticRoutes(manifest: RouteManifest): Promise<void> {
+export async function prerenderStaticRoutes(
+	manifest: RouteManifest,
+	target: RuntimeTarget = "bun",
+): Promise<void> {
 	const targets = await detectPrerenderRoutes(manifest);
-	if (targets.length === 0) return;
+	// On Workers the worker answers unknown paths, so 404.html is never required.
+	const require404 = target !== "workers" && needsStatic404();
+	// No routes to prerender: start the server only for the required 404.html.
+	if (targets.length === 0 && !require404) return;
 
-	console.log(`\n🖨️  Prerendering ${targets.length} route(s)...`);
+	console.log(
+		targets.length
+			? `\n🖨️  Prerendering ${targets.length} route(s)...`
+			: "\n🖨️  Building 404.html (wrangler sets 404-page)...",
+	);
 
 	const port = await getEphemeralPort();
+	// No BOSIA_REUSE_PORT: the child must fail to bind rather than share a port
+	// with another server, whose pages we'd then save as ours. The ready loop
+	// stops once the child exits, but a server that grabbed the port first can
+	// still answer /_health before the child dies. Have /_health echo a nonce
+	// from the child's env if that race ever shows up.
+	const { BOSIA_REUSE_PORT: _, ...env } = process.env;
 	const child = Bun.spawn(["bun", "run", `${OUT_DIR}/server/index.js`], {
 		env: {
-			...process.env,
+			...env,
 			NODE_ENV: "production",
 			PORT: String(port),
 			NODE_PATH: BOSIA_NODE_PATH,
 		},
 		stdout: "ignore",
-		stderr: "ignore",
+		// Show render errors (a throwing +error.svelte, a crashing loader).
+		stderr: "inherit",
 	});
+	// exitCode stays null when a signal kills the child (OOM, segfault), so
+	// watch `exited` instead.
+	let exited = false;
+	child.exited.then(() => (exited = true));
 
 	const signals: NodeJS.Signals[] = ["SIGINT", "SIGTERM"];
 	let receivedSignal: NodeJS.Signals | null = null;
@@ -191,7 +253,7 @@ export async function prerenderStaticRoutes(manifest: RouteManifest): Promise<vo
 		const base = `http://localhost:${port}${currentBase()}`;
 		let ready = false;
 		const deadline = Date.now() + 10_000;
-		while (Date.now() < deadline) {
+		while (Date.now() < deadline && !exited) {
 			try {
 				const res = await fetch(`${base}/_health`);
 				if (res.ok) {
@@ -204,8 +266,14 @@ export async function prerenderStaticRoutes(manifest: RouteManifest): Promise<vo
 			await Bun.sleep(50);
 		}
 
-		if (!ready) {
-			console.error("❌ Prerender server failed to start");
+		if (!ready || exited) {
+			const why = child.signalCode ?? `exit code ${child.exitCode ?? "none"}`;
+			if (require404)
+				throw new Error(
+					`Prerender server failed to start (${why}), so 404.html could not be built, but ` +
+						`wrangler sets not_found_handling "404-page". Fix the server, or add public/404.html.`,
+				);
+			console.error(`❌ Prerender server failed to start (${why})`);
 			return;
 		}
 
@@ -286,7 +354,38 @@ export async function prerenderStaticRoutes(manifest: RouteManifest): Promise<vo
 			Array.from({ length: Math.min(PRERENDER_CONCURRENCY, targets.length) }, worker),
 		);
 
-		console.log("✅ Prerendering complete");
+		// Static hosts (Cloudflare assets) serve index.html with a 200 for unknown
+		// paths unless a 404.html exists. Save the server's own 404 page while it's up.
+		// Goes to dist/static, not prerendered/, so the Bun server doesn't route /404
+		// to it, though it (and static hosts) still serve /404.html with a 200.
+		// Skipped on Workers: the worker answers unknown paths, and an uploaded file
+		// would only add that soft 404. A public/404.html overwrites it.
+		// One probe, one locale: add per-locale probe paths (e.g. /id/404.html) when asked.
+		if (target !== "workers")
+			try {
+				const res = await fetch(`${base}/__bosia-404-probe`, {
+					signal: AbortSignal.timeout(PRERENDER_TIMEOUT),
+				});
+				if (res.status !== 404) throw new Error(`expected a 404 page, got ${res.status}`);
+				// No +error.svelte (or it crashed) → plain-text "Not Found", not a page.
+				if (!res.headers.get("content-type")?.includes("text/html"))
+					throw new Error(`expected an HTML 404 page, got ${res.headers.get("content-type")}`);
+				mkdirSync(`${OUT_DIR}/static`, { recursive: true });
+				writeFileSync(`${OUT_DIR}/static/404.html`, await res.text());
+				console.log(`   ✅ 404 page → ${OUT_DIR}/static/404.html`);
+			} catch (err) {
+				// Only a deploy that serves 404.html needs it; elsewhere (an app whose
+				// hooks redirect every request) a missing one is fine, so just warn.
+				const reason = (err as Error).message;
+				if (require404)
+					throw new Error(
+						`404.html could not be built (${reason}), but wrangler sets ` +
+							`not_found_handling "404-page". Make unknown paths answer 404, or add public/404.html.`,
+					);
+				console.warn(`   ⚠️  404.html skipped: ${reason}`);
+			}
+
+		if (targets.length) console.log("✅ Prerendering complete");
 	} finally {
 		for (const sig of signals) process.off(sig, onSignal);
 		child.kill();

package/src/core/renderer.ts

@@ -45,7 +45,7 @@ import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import { dev500Response } from "./dev-500.ts";
 import type { BosiaPlugin, RenderContext } from "./types/plugin.ts";
 import { getAppHtmlSegments } from "./appHtml.ts";
-import { hasTitle } from "./headScan.ts";
+import { errorTitle, hasTitle } from "./headScan.ts";
 import type { AppHtmlSegments } from "./appHtml.ts";
 
 // Shared, stateless — one instance instead of a fresh allocation per stream.
@@ -1217,7 +1217,7 @@ export async function renderErrorPage(
 	// head, so a real title hasTitle misses still comes first), except when
 	// app.html has its own <title>: that would come first, so the status title
 	// takes the metadata slot ahead of it instead.
-	const statusTitle = `${status} — ${message}`;
+	const statusTitle = errorTitle(status, message);
 	const errMeta = (head: string): Metadata | null =>
 		appHtmlHasTitle(appHtmlSegments) && !hasTitle(head) ? { title: statusTitle } : null;
 

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,6 +1,7 @@
 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";
 
 // ─── Route Types Generator ────────────────────────────────
@@ -23,13 +24,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;
 }
@@ -76,7 +71,9 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 
 		const params = paramsForDir(dir);
 		const paramsType =
-			params.length === 0 ? `{}` : `{ ${params.map((p) => `${p}: string`).join("; ")} }`;
+			params.length === 0
+				? `{}`
+				: `{ ${params.map((p) => `${/^[A-Za-z_$][\w$]*$/.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 +98,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 +130,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 +145,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,66 @@ 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]`, `[id].json`, `post-[slug]`, `[[lang]]` would match only their literal text.
+				if (/^\[(\.\.\.)?[^[\]/]*\]$/.test(seg))
+					fail(`${seg} needs a param name that doesn't start with a dot, like [slug] or [...rest]`);
+				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`);
+			const dots = rank === 2 ? "..." : "";
+			if (name.includes("="))
+				fail(`${seg}: param matchers aren't supported, use [${dots}${name.split("=")[0]}]`);
+			if (name.endsWith("?"))
+				fail(`${seg}: optional params aren't supported, use [${dots}${name.slice(0, -1)}]`);
+			if (/^…|[.…]$/.test(name))
+				fail(`${seg}: did you mean [...${name.replace(/^…|[.…]+$/g, "")}]?`);
+			if (!PARAM_NAME.test(name))
+				fail(`${seg}: a param name uses letters, digits, _, $, - and inner dots only`);
+			// 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);
+		}
+	}
+}
+
+// `[slüg]`, `[$id]`, `[my-path]`, `[file.name]`, `[1st]`; no spaces, quotes, `…` or edge dots.
+const PARAM_NAME = /^[\p{L}\p{N}_$-]+(\.[\p{L}\p{N}_$-]+)*$/u;
+
+/** 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/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.`,
 	},
 };