bosia 1.2.5 → 1.2.6

package/src/core/client/App.svelte

@@ -3,7 +3,7 @@
 	import { router, scrollToHash } from "./router.svelte.ts";
 	import { findMatch } from "../matcher.ts";
 	import { clientRoutes, defaultTitle } from "bosia:routes";
-	import { consumePrefetch, prefetchCache, dataUrl, readDataResponse } from "./prefetch.ts";
+	import { consumePrefetch, clearPrefetches, dataUrl, readDataResponse } from "./prefetch.ts";
 	import { appState, clearDirty } from "./appState.svelte.ts";
 	import { captureSnapshot, liveContext, shouldRerun, type CacheEntry } from "./loaderCache.ts";
 	import { pickErrorPage } from "../errorMatch.ts";
@@ -350,18 +350,26 @@
 
 		// Load components + data in parallel, then update state atomically
 		// to avoid a flash of stale/empty data before the fetch completes.
-		const cached = match.route.hasServerData && !invalidated ? consumePrefetch(path) : null;
-		prefetchCache.clear(); // clear remaining entries on navigation — matches SvelteKit behavior
+		// `fresh` covers `invalidated` plus dirty keys/URLs: a prefetch sent before
+		// an invalidate() skipped `_fresh`, so it may hold the server's stale copy.
+		const cached = match.route.hasServerData && !fresh ? consumePrefetch(path, maskBits) : null;
+		clearPrefetches(); // clear remaining entries on navigation — matches SvelteKit behavior
 		// A prerendered route's data is a fixed file, so there is nothing to omit.
 		const prerendered = match.route.prerender;
+		const fetchData = () =>
+			fetch(dataUrl(path, prerendered ? undefined : maskBits, fresh && !prerendered))
+				.then(readDataResponse)
+				// Only a failed request reaches here now — offline, DNS, aborted.
+				// A response that arrived is read for what it says, not discarded.
+				.catch(() => null);
 		const dataFetch = cached
-			? Promise.resolve(cached)
+			? // A prefetch still in flight: wait for it; fetch again if it failed or
+				// errored (a hover-time 500 shouldn't stand in for the click's answer).
+				cached instanceof Promise
+				? cached.then((data) => (data && !data.error ? data : fetchData()))
+				: Promise.resolve(cached)
 			: match.route.hasServerData
-				? fetch(dataUrl(path, prerendered ? undefined : maskBits, fresh && !prerendered))
-						.then(readDataResponse)
-						// Only a failed request reaches here now — offline, DNS, aborted.
-						// A response that arrived is read for what it says, not discarded.
-						.catch(() => null)
+				? fetchData()
 				: Promise.resolve(null);
 
 		// Scrolls first: waiting goto()/use:enhance calls resume after the scroll.

package/src/core/client/prefetch.ts

@@ -109,21 +109,46 @@ function errorMessage(res: Response): string {
 	return res.statusText || "Internal Server Error";
 }
 
-export const prefetchCache = new Map<string, { data: any; ts: number }>();
+// `mask`: the `_invalidated` bits the prefetch sent (null = asked for every layer).
+const prefetchCache = new Map<string, { data: any; ts: number; mask: string | null }>();
 const MAX_PREFETCH_ENTRIES = 50;
 
-// In-flight fetch deduplication
-const pending = new Set<string>();
+// In-flight prefetches. A click that lands while its prefetch is still loading
+// (a tap: touchstart prefetches ~100ms before the click) waits for that fetch
+// instead of sending the same `/__bosia/data` request a second time. It gets
+// whatever the response said (data, a redirect, an error), read like the
+// router's own fetch; `null` only when the request itself failed.
+// `clearPrefetches()` empties it on every navigation, so a prefetch that started
+// before it neither fills the cache nor serves a later click.
+const pending = new Map<string, { run: Promise<any | null>; mask: string | null }>();
 
-/** Returns cached prefetch data for a path and removes it from cache. */
-export function consumePrefetch(path: string): any | null {
+/**
+ * Prefetched data for a path, or the in-flight prefetch's promise (resolves to
+ * the data, or `null` when the prefetch can't be used — fetch it yourself).
+ * The entry is consumed: a second call gets `null`. `mask` is the navigation's
+ * own `_invalidated` bits: a prefetch built against the loader cache as it was
+ * at hover time may have left out a layer this navigation needs.
+ */
+export function consumePrefetch(path: string, mask: string): any | Promise<any | null> | null {
+	const inflight = pending.get(path);
+	if (inflight) {
+		pending.delete(path);
+		return inflight.mask === null || inflight.mask === mask ? inflight.run : null;
+	}
 	const entry = prefetchCache.get(path);
 	if (entry === undefined) return null;
 	prefetchCache.delete(path);
 	if (Date.now() - entry.ts > 30_000) return null;
+	if (entry.mask !== null && entry.mask !== mask) return null;
 	return entry.data;
 }
 
+/** Drops every prefetch, finished or in flight — call on navigation. */
+export function clearPrefetches(): void {
+	prefetchCache.clear();
+	pending.clear();
+}
+
 /** Prefetches data for a path and stores in cache. No-op if already cached/in-flight. */
 export async function prefetchPath(path: string): Promise<void> {
 	// Nothing to fetch for the page we're on. A click also focuses its link, so
@@ -152,27 +177,35 @@ export async function prefetchPath(path: string): Promise<void> {
 	// A route without server data never fetches on click either.
 	if (!warmMatch?.route.hasServerData) return;
 
-	pending.add(path);
-	try {
-		// Send the same mask as a real client nav would so the server leaves out
-		// layers the client already holds. Falls back to sending everything when
-		// the route can't be matched (e.g. external/unknown URL).
-		const maskBits = buildMaskBits(path) ?? undefined;
-		const res = await fetch(dataUrl(path, maskBits));
-		// `ok` alone would cache a guard's login page (200 after the redirect was
-		// followed) as if it were this route's data.
-		if (res.ok && !res.redirected && isJsonResponse(res)) {
-			if (prefetchCache.size >= MAX_PREFETCH_ENTRIES) {
-				const oldest = prefetchCache.keys().next().value;
-				if (oldest !== undefined) prefetchCache.delete(oldest);
-			}
-			prefetchCache.set(path, { data: await res.json(), ts: Date.now() });
+	// Only a plain data response is kept for a later click; `ok` alone would
+	// cache a guard's login page (200 after the redirect was followed).
+	let storable = false;
+	// Send the same mask as a real client nav would so the server leaves out
+	// layers the client already holds. Falls back to sending everything when
+	// the route can't be matched (e.g. external/unknown URL).
+	const mask = buildMaskBits(path);
+	const run = (async (): Promise<any | null> => {
+		try {
+			const res = await fetch(dataUrl(path, mask ?? undefined));
+			storable = res.ok && !res.redirected && isJsonResponse(res);
+			return await readDataResponse(res);
+		} catch {
+			// Silently ignore — prefetch is best-effort
+			return null;
 		}
-	} catch {
-		// Silently ignore — prefetch is best-effort
-	} finally {
-		pending.delete(path);
+	})();
+	pending.set(path, { run, mask });
+	const data = await run;
+	// Consumed by a click, or dropped by a navigation, while in flight.
+	if (pending.get(path)?.run !== run) return;
+	pending.delete(path);
+	// A guard's redirect is the session's answer now, not in 30s.
+	if (data === null || !storable || data.error || data.redirect) return;
+	if (prefetchCache.size >= MAX_PREFETCH_ENTRIES) {
+		const oldest = prefetchCache.keys().next().value;
+		if (oldest !== undefined) prefetchCache.delete(oldest);
 	}
+	prefetchCache.set(path, { data, ts: Date.now(), mask });
 }
 
 function getLinkHref(anchor: HTMLAnchorElement): string | null {

package/src/core/cors.ts

@@ -29,7 +29,23 @@ function parseHeaderList(value: string): string[] {
  * response with `Access-Control-Allow-Origin: X` to a different origin Y.
  */
 export function applyCorsVary(headers: Headers): void {
-	headers.set("Vary", "Origin");
+	mergeVary(headers, "Origin");
+}
+
+/**
+ * Add `value` to the Vary header, keeping what is there: `set("Vary", "Origin")`
+ * dropped `Accept-Encoding`, so a CDN could hand a brotli body to a client that
+ * never asked for one.
+ */
+export function mergeVary(headers: Headers, value: string): void {
+	const current = headers.get("Vary");
+	if (!current) {
+		headers.set("Vary", value);
+		return;
+	}
+	const parts = current.split(",").map((p) => p.trim().toLowerCase());
+	if (parts.includes("*") || parts.includes(value.toLowerCase())) return;
+	headers.set("Vary", `${current}, ${value}`);
 }
 
 /**

package/src/core/dedup.ts

@@ -8,7 +8,8 @@
 // different users never share a loader result. Custom session cookie names
 // must be listed in CACHE_KEYS. See docs/guides/request-deduplication.md.
 
-const inflight = new Map<string, Promise<unknown>>();
+type Inflight = { promise: Promise<unknown>; start: number };
+const inflight = new Map<string, Inflight>();
 
 /** Build a stable dedup key from a URL: normalized path + sorted query. */
 export function dedupKey(url: URL): string {
@@ -19,11 +20,54 @@ export function dedupKey(url: URL): string {
 	return search ? `${path}?${search}` : path;
 }
 
-/** Coalesce concurrent calls under `key`. `fn` runs at most once per inflight window. */
-export function dedup<T>(key: string, fn: () => Promise<T>): Promise<T> {
+/**
+ * Coalesce concurrent calls under `key`. `fn` runs at most once per inflight
+ * window. With `maxAgeMs` > 0 a call is joined only until it is that old:
+ * one that never settles (a hung loader with LOAD_TIMEOUT=0) would otherwise
+ * take every later request for the key down with it. A call that started
+ * before `replaceStartedBefore` is replaced rather than joined (the caller
+ * knows it is stuck); later calls join the new one.
+ */
+export function dedup<T>(
+	key: string,
+	fn: () => Promise<T>,
+	maxAgeMs = 0,
+	replaceStartedBefore = -Infinity,
+): Promise<T> {
 	const existing = inflight.get(key);
-	if (existing) return existing as Promise<T>;
-	const promise = fn().finally(() => inflight.delete(key));
-	inflight.set(key, promise);
-	return promise as Promise<T>;
+	if (existing && existing.start >= replaceStartedBefore) {
+		if (maxAgeMs <= 0) return existing.promise as Promise<T>;
+		const left = maxAgeMs - (performance.now() - existing.start);
+		if (left > 0) {
+			// Joined until the call reaches maxAgeMs; then the first joiner
+			// replaces it and the rest join the new call. One timer per joiner:
+			// on Workers a timer dies with the request that set it.
+			const joined = existing.promise as Promise<T>;
+			return new Promise<T>((resolve, reject) => {
+				const timer = setTimeout(() => {
+					const stuck = inflight.get(key) === existing;
+					dedup(key, fn, maxAgeMs, stuck ? Infinity : -Infinity).then(resolve, reject);
+				}, left);
+				(timer as { unref?: () => void }).unref?.();
+				joined.then(
+					(v) => {
+						clearTimeout(timer);
+						resolve(v);
+					},
+					(e) => {
+						clearTimeout(timer);
+						reject(e);
+					},
+				);
+			});
+		}
+	}
+	const entry: Inflight = { promise: null as unknown as Promise<T>, start: performance.now() };
+	const promise = fn().finally(() => {
+		// Never drops a newer call that replaced a stale one.
+		if (inflight.get(key) === entry) inflight.delete(key);
+	});
+	entry.promise = promise;
+	inflight.set(key, entry);
+	return promise;
 }

package/src/core/env.ts

@@ -30,6 +30,9 @@ const FRAMEWORK_VARS = new Set([
 	"CACHE_KEYS",
 	"CACHE_MAX_ENTRIES",
 	"CACHE_MAX_BODY_BYTES",
+	"CACHE_MAX_BYTES",
+	"CACHE_WAIT_TIMEOUT",
+	"CACHE_IGNORE_PARAMS",
 	"ASSET_CACHE_MAX_BYTES",
 	"ASSET_CACHE_MAX_FILE_BYTES",
 ]);

package/src/core/hooks.ts

@@ -3,7 +3,7 @@
 // Usage in src/hooks.server.ts:
 //
 //   import { sequence } from "bosia";
-//   export const handle = sequence(authHandle, loggingHandle);
+//   export const handle = sequence(authHandle, guardHandle);
 
 // ─── Cookie Types ─────────────────────────────────────────
 

package/src/core/html.ts

@@ -674,6 +674,18 @@ export function compress(
 	return compressBytes(textEncoder.encode(body), contentType, req, status, extraHeaders);
 }
 
+/**
+ * The Vary value for a body that may be compressed: a loader's or handler's
+ * own `vary` (e.g. `Cookie`) used to replace `Accept-Encoding`, so a CDN could
+ * hand brotli to a client that never asked for it.
+ */
+export function varyWithEncoding(vary: string | undefined): string {
+	if (!vary) return "Accept-Encoding";
+	const parts = vary.split(",").map((p) => p.trim().toLowerCase());
+	if (parts.includes("*") || parts.includes("accept-encoding")) return vary;
+	return `${vary}, Accept-Encoding`;
+}
+
 /** `encoded`: the result of `encodeForRequest` when the caller already has it
  *  (a cache write reuses the same bytes); omitted, it is built here. */
 export function compressBytes(
@@ -688,8 +700,8 @@ export function compressBytes(
 	// override them instead of getting comma-joined by Headers.
 	const headers: Record<string, string> = {
 		"content-type": contentType,
-		vary: "Accept-Encoding",
 		...extraHeaders,
+		vary: varyWithEncoding(extraHeaders?.vary),
 	};
 	if (encoded) {
 		return new Response(encoded.encoded, {

package/src/core/plugins/access-log.ts

@@ -0,0 +1,128 @@
+import type { BosiaPlugin } from "../types/plugin.ts";
+
+export interface AccessLogEntry {
+	method: string;
+	/** Path without the query string. */
+	path: string;
+	/** The status the client got. */
+	status: number;
+	/** Time to build the response, in milliseconds (not to deliver its body). */
+	ms: number;
+	request: Request;
+}
+
+export interface AccessLogOptions {
+	/** Return false to skip a line, e.g. `(e) => e.status >= 400 || e.ms > 200`. */
+	filter?: (entry: AccessLogEntry) => boolean;
+	/** One line per request, without the trailing newline. */
+	format?: (entry: AccessLogEntry) => string;
+	/** Where lines go. Defaults to console.log, one call per batch. May be async;
+	 *  a failed write loses that batch, never the request or the process. */
+	write?: (chunk: string) => void | Promise<unknown>;
+	/**
+	 * Lines are collected and written together at most this often (ms). One
+	 * write per request costs a syscall each: on a pipe (`docker logs`, systemd)
+	 * that was ~11–14µs of CPU per request, batched ~3µs. 0 writes every line at
+	 * once. Defaults to 100 on Bun, 0 on Workers (no timers after a response).
+	 */
+	flushMs?: number;
+}
+
+/** Flush early once this much is waiting, so a burst never piles up here. */
+const MAX_BUFFER_CHARS = 64 * 1024;
+
+function defaultFormat(e: AccessLogEntry): string {
+	return `[${e.method}] ${e.path} ${e.status} (${e.ms.toFixed(1)}ms)`;
+}
+
+/**
+ * One console.log per batch. On Bun it blocks until the pipe takes every byte;
+ * `process.stdout.write` queued on a slow pipe and lost the queue at exit, and
+ * `fs.writeSync(1)` wrote part of a batch (non-blocking stdout) and dropped the
+ * rest — ~870 of 3000 lines in a test, both ways. Like any console.log, a log
+ * reader that stops reading slows the server.
+ */
+function defaultWrite(chunk: string): void {
+	console.log(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk);
+}
+
+/** Path of a request URL without allocating a URL object. */
+function pathOf(url: string): string {
+	const start = url.indexOf("/", url.indexOf("//") + 2);
+	if (start === -1) return "/";
+	const q = url.indexOf("?", start);
+	return q === -1 ? url.slice(start) : url.slice(start, q);
+}
+
+/**
+ * Logs one line per request: method, path, status, duration. Opt-in — the
+ * app templates no longer log every request from `hooks.server.ts`; a reverse
+ * proxy (nginx, Caddy) can keep the access log instead.
+ *
+ * Reads the final response (`onResponse`), so the status is what the client
+ * got whatever other plugins did, and every request is logged exactly once.
+ */
+export function accessLog(options: AccessLogOptions = {}): BosiaPlugin {
+	const format = options.format ?? defaultFormat;
+	const write = options.write ?? defaultWrite;
+	// Workers drops timers once the response is sent: a batch would never flush.
+	const flushMs = typeof Bun === "undefined" ? 0 : (options.flushMs ?? 100);
+	const filter = options.filter;
+
+	let buffer = "";
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	const flush = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+		if (buffer === "") return;
+		const out = buffer;
+		buffer = "";
+		try {
+			const done = write(out);
+			if (done instanceof Promise) done.catch(() => {});
+		} catch {
+			// A broken sink loses this batch, not the request or the process.
+		}
+	};
+	let exitHooked = false;
+
+	const log = (entry: AccessLogEntry) => {
+		if (filter && !filter(entry)) return;
+		buffer += format(entry) + "\n";
+		if (flushMs <= 0 || buffer.length >= MAX_BUFFER_CHARS) flush();
+		else if (!timer) {
+			// Lines still waiting when the server drains and exits. Added on the
+			// first buffered line, so `bosia build` (which loads the config too)
+			// never registers one.
+			if (!exitHooked && typeof process !== "undefined" && typeof process.once === "function") {
+				exitHooked = true;
+				process.once("exit", flush);
+			}
+			timer = setTimeout(flush, flushMs);
+			(timer as { unref?: () => void }).unref?.();
+		}
+	};
+
+	return {
+		name: "access-log",
+		backend: {
+			before(app) {
+				// onResponse swallows a throw here (a broken filter/format/sink),
+				// so logging can never change or fail a response.
+				return app.onResponse(({ request, response, start }) => {
+					log({
+						method: request.method,
+						path: pathOf(request.url),
+						status: response.status,
+						ms: performance.now() - start,
+						request,
+					});
+				});
+			},
+		},
+	};
+}
+
+export default accessLog;

package/src/core/prerender.ts

@@ -380,6 +380,7 @@ function targetLabel(t: PrerenderTarget): string {
  * Targets whose URL another route serves: `/blog/[slug]` giving `new` while
  * `src/routes/blog/new` exists, or a page slug at a `+server.ts` URL (an API
  * wins, as in server.ts matchRoutes). Saving it would freeze the other route.
+ * Checked ignoring case too: on a macOS/Windows host `blog/New.html` answers `/blog/new`.
  */
 export function findMisownedTargets(
 	manifest: Pick<RouteManifest, "pages" | "apis">,
@@ -388,19 +389,155 @@ export function findMisownedTargets(
 	// Copies: findMatch caches a compiled regex on each route object it sees.
 	const pages = sortRoutes(manifest.pages.map((r) => ({ pattern: r.pattern })));
 	const apis = sortRoutes(manifest.apis.map((r) => ({ pattern: r.pattern })));
-	const out = new Map<PrerenderTarget, string>();
-	for (const t of targets) {
+	// The server's own matcher decides who serves the URL exactly.
+	const ownerOf = (t: PrerenderTarget) => {
 		const api = findMatch(apis, t.path)?.route.pattern;
-		let owner = api;
+		if (t.kind === "api") return api;
 		// A page loses to any API at its URL, even a +server.ts in its own folder.
-		if (t.kind === "page")
-			owner = api ? `${api} (+server.ts)` : findMatch(pages, t.path)?.route.pattern;
-		if (owner && owner !== t.route)
+		return api ? `${api} (+server.ts)` : findMatch(pages, t.path)?.route.pattern;
+	};
+	// Split once, in match order, for the case pass: every API first, then pages. An API
+	// target meets pages too: a live `/API/ALL` page is hidden by a saved `api/all` file.
+	const shape = (pattern: string, api: boolean): RouteShape => {
+		const parts = pattern.split("/").filter(Boolean);
+		const ranks = parts.map(segmentRank);
+		const lower = parts.map((p) => p.toLowerCase());
+		return { pattern, api, parts, lower, ranks, rest: ranks.at(-1) === 2 };
+	};
+	const order = [
+		...apis.map((r) => shape(r.pattern, true)),
+		...pages.map((r) => shape(r.pattern, false)),
+	];
+	const out = new Map<PrerenderTarget, string>();
+	for (const t of targets) {
+		const owner = ownerOf(t);
+		if (owner && owner !== t.route) {
 			out.set(t, `❌ Prerender: ${targetLabel(t)} is served by ${owner}, not this route`);
+			continue;
+		}
+		// No route answers the URL (a hand-built table): nothing to measure a case clash by.
+		if (!owner) continue;
+		const problem = caseProblem(t, order);
+		if (problem) out.set(t, problem);
 	}
 	return out;
 }
 
+interface RouteShape {
+	pattern: string;
+	api: boolean;
+	parts: string[];
+	lower: string[];
+	ranks: (0 | 1 | 2)[];
+	/** Ends in `[...rest]`, so it takes paths longer than its parts. */
+	rest: boolean;
+}
+
+/**
+ * This route serves the URL exactly (findMatch said so). A route matching only ignoring
+ * case (a static part spelled `NEW` for `new`) then clashes if it wins some spelling: it
+ * ranks above this route, or the spelling differs at one of this route's static parts so
+ * this route can't answer it. On a host that ignores case the saved file answers that
+ * spelling. Overlaps through params alone (`/[...rest]` catching `/BLOG/new`) are allowed,
+ * or every catch-all next to a prerendered page would fail. A route ranked higher still
+ * that takes the very same spellings isn't looked for; the check may then name a route
+ * that never answers.
+ */
+function caseProblem(t: PrerenderTarget, order: RouteShape[]): string | null {
+	const path = t.path.split("/").filter(Boolean);
+	const pathLower = path.map((p) => p.toLowerCase());
+	let own: PartMatch[] | null = null;
+	let hit: { r: RouteShape; kinds: PartMatch[]; above: boolean } | null = null;
+	for (const r of order) {
+		// Cheap filter first: most routes can't match on part count alone.
+		if (r.rest ? path.length < r.parts.length : path.length !== r.parts.length) continue;
+		const kinds = matchPartsFolded(r.parts, r.lower, r.ranks, path, pathLower);
+		if (!kinds) continue;
+		if (r.pattern === t.route && r.api === (t.kind === "api")) {
+			own = kinds;
+			if (hit) break; // a route above already wins a spelling
+		} else if (!kinds.includes("case")) continue;
+		else if (!own) hit ??= { r, kinds, above: true };
+		else if (escapesOwn(kinds, own, path)) {
+			hit = { r, kinds, above: false };
+			break;
+		}
+	}
+	// findMatch said this route serves the URL, so the walk must find it too; if not, the two
+	// matchers have drifted apart and every case clash would pass unseen.
+	if (!own)
+		throw new Error(
+			`Bosia internal: the prerender case check can't match ${t.path} to ${t.route}; please report it`,
+		);
+	if (!hit) return null;
+	const { r, kinds, above } = hit;
+	// The spelling it wins: its own static parts. Ranked below, every param under this
+	// route's static part changes case too, which also steers clear of routes in between
+	// (`/BLOG/NEW`, not `/blog/NEW` that `/blog/[slug]` takes).
+	const spelling = kinds.map((k, j) => {
+		if (k !== "param") return r.parts[j]!;
+		return (!above && own[j] === "same" && otherCase(path[j]!)) || path[j]!;
+	});
+	const name = r.api && t.kind === "page" ? `${r.pattern} (+server.ts)` : r.pattern;
+	return `❌ Prerender: ${targetLabel(t)} would also answer /${spelling.join("/")} on hosts that ignore case (macOS/Windows), which ${name} serves`;
+}
+
+/** How one part of a URL meets a route part: `same` static, `case` static spelled in
+ *  another case, `param`. A match with no `case` is an exact match. */
+type PartMatch = "same" | "case" | "param";
+
+/**
+ * Match a route's parts against a URL's parts ignoring case, by compilePattern's rules: only
+ * a last `[...rest]` takes several parts, any other bracket part is one param. `null` when
+ * they don't match. `lower`/`pathLower` are the same parts in `toLowerCase`, made once by the
+ * caller. ASCII case only in effect: Unicode forms and special folds (`ς`/`σ`) aren't merged.
+ * Keep in step with matcher.ts compilePattern.
+ */
+function matchPartsFolded(
+	parts: string[],
+	lower: string[],
+	ranks: (0 | 1 | 2)[],
+	path: string[],
+	pathLower: string[],
+): PartMatch[] | null {
+	const kinds: PartMatch[] = [];
+	for (const [i, seg] of parts.entries()) {
+		if (ranks[i] === 2 && i === parts.length - 1) {
+			if (path.length <= i) return null;
+			for (let j = i; j < path.length; j++) kinds.push("param");
+			return kinds;
+		}
+		const part = path[i];
+		if (part === undefined) return null;
+		if (ranks[i]) kinds.push("param");
+		else if (part === seg) kinds.push("same");
+		else if (pathLower[i] === lower[i]) kinds.push("case");
+		else return null;
+	}
+	return kinds.length === path.length ? kinds : null;
+}
+
+/** Some part where this route is static has a spelling the other route takes and this one doesn't. */
+function escapesOwn(kinds: PartMatch[], own: PartMatch[], path: string[]): boolean {
+	return kinds.some(
+		(k, j) => own[j] === "same" && (k === "case" || (k === "param" && otherCase(path[j]!))),
+	);
+}
+
+/**
+ * `s` with every letter in the other case, keeping only swaps that lowercase back to the same
+ * letter (`ß` → `SS` and `İ` → `i̇` change length, so they stay). `null` if nothing swaps.
+ */
+function otherCase(s: string): string | null {
+	const swapped = [...s]
+		.map((c) => {
+			const o = c === c.toUpperCase() ? c.toLowerCase() : c.toUpperCase();
+			return o.length === c.length && o.toLowerCase() === c.toLowerCase() ? o : c;
+		})
+		.join("");
+	return swapped === s ? null : swapped;
+}
+
 /**
  * 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.