bosia 0.8.3 → 0.8.4

package/README.md

@@ -18,6 +18,20 @@ File-based routing inspired by SvelteKit, built on top of the Bun runtime and El
 - **Dev server with HMR** — file watcher + SSE browser reload, no page blink
 - **Tailwind CSS v4** — compiled at build time, shadcn-inspired design tokens out of the box
 - **CLI** — `bosia create`, `bosia dev`, `bosia build`, `bosia add`, `bosia feat`
+- **UI registry** — shadcn-style, copy-paste source you own: **60 components**, **100+ blocks**, **10 pages**, **19 themes**
+
+## UI Registry
+
+`bosia add` copies source directly into your project — no runtime package to import:
+
+```bash
+bun x bosia@latest add button card data-table   # 60 primitives
+bun x bosia@latest add block heros/product       # 100+ composed sections
+bun x bosia@latest add page storefront/home      # 10 ready-to-wire pages
+bun x bosia@latest add theme editorial           # 19 token themes
+```
+
+See the [registry docs](https://bosia.dev) for the full catalog.
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.8.3",
+	"version": "0.8.4",
 	"type": "module",
 	"description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing No Node.js, no Vite, no adapters.",
 	"keywords": [

package/src/ambient.d.ts

@@ -20,7 +20,6 @@ declare module "bosia:routes" {
 		pageServer: Loader | null;
 		layoutServers: { loader: Loader; depth: number }[];
 		trailingSlash: TrailingSlash;
-		scope: "public" | "private";
 	}>;
 
 	export const apiRoutes: Array<{

package/src/core/cache.ts

@@ -5,7 +5,9 @@
 //
 // See docs/guides/response-cache.md.
 
+import { brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import type { Cookies, LoaderDeps } from "./hooks.ts";
+import type { CookieJar } from "./cookies.ts";
 import { dedupKey } from "./dedup.ts";
 
 // ─── Config ──────────────────────────────────────────────
@@ -28,22 +30,31 @@ function parseMaxEntries(raw: string | undefined): number {
 	return n;
 }
 
-// `invalidate` / `invalidateAll` are re-exported from the public `bosia`
-// barrel, so this module also evaluates in the browser bundle. Guard every
-// `process.env` read — otherwise hydration throws `ReferenceError: Can't
-// find variable: process` (Safari) the moment the barrel is imported.
+function parseMaxBodyBytes(raw: string | undefined): number {
+	const DEFAULT = 2_097_152; // 2MB; 0 = unlimited
+	if (!raw) return DEFAULT;
+	const n = parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 0) return DEFAULT;
+	return n;
+}
+
+// Server-only module (imported by core/renderer.ts, core/server.ts,
+// lib/server.ts — never the client barrel; client `invalidate` lives in
+// core/client/navigation.ts). The `process` guards below are kept as
+// defense in case a future refactor pulls this into a browser bundle.
 const env: Record<string, string | undefined> =
 	typeof process !== "undefined" && process.env ? process.env : {};
 const isServer = typeof process !== "undefined";
 
 export const CACHE_KEYS: readonly string[] = parseCacheKeys(env.CACHE_KEYS);
 export const CACHE_MAX_ENTRIES = parseMaxEntries(env.CACHE_MAX_ENTRIES);
+export const CACHE_MAX_BODY_BYTES = parseMaxBodyBytes(env.CACHE_MAX_BODY_BYTES);
 export const CACHE_ENABLED = CACHE_MAX_ENTRIES > 0;
 
 if (isServer) {
 	if (CACHE_ENABLED) {
 		console.log(
-			`💾 Response cache: max ${CACHE_MAX_ENTRIES} entries, identity keys [${CACHE_KEYS.join(", ")}]`,
+			`💾 Response cache: max ${CACHE_MAX_ENTRIES} entries, max body ${CACHE_MAX_BODY_BYTES === 0 ? "unlimited" : `${CACHE_MAX_BODY_BYTES} bytes`}, identity keys [${CACHE_KEYS.join(", ")}]`,
 		);
 	} else {
 		console.log("💾 Response cache: disabled (CACHE_MAX_ENTRIES=0)");
@@ -111,31 +122,28 @@ const pathIndex = new Map<string, Set<string>>(); // pathname → cacheKeys
 
 // ─── Key building ────────────────────────────────────────
 
-/** FNV-1a 32-bit hash. Compact, no dep, collision-tolerant for an identity bucket. */
-function fnv1a(s: string): string {
-	let h = 0x811c9dc5;
-	for (let i = 0; i < s.length; i++) {
-		h ^= s.charCodeAt(i);
-		h = Math.imul(h, 0x01000193);
-	}
-	return (h >>> 0).toString(36);
+/** SHA-256 truncated to 64 bits — identity buckets must not collide across users. */
+function identityDigest(s: string): string {
+	return new Bun.CryptoHasher("sha256").update(s).digest("hex").slice(0, 16);
 }
 
-export function computeIdentityHash(req: Request, cookies: Cookies): string {
+export function computeIdentityHash(req: Request, cookies: Pick<CookieJar, "peek">): string {
 	const headers = req.headers;
 	const parts: string[] = [];
 	for (const name of CACHE_KEYS) {
-		const cv = cookies.get(name);
+		// peek, not get — building the identity must not count as a cookie read
+		// (get flips `accessed`, which forces Cache-Control: private downstream).
+		const cv = cookies.peek(name);
 		if (cv) parts.push(`c:${name}=${cv}`);
 		const hv = headers.get(name);
 		if (hv) parts.push(`h:${name}=${hv}`);
 	}
 	if (parts.length === 0) return "0";
 	parts.sort();
-	return fnv1a(parts.join("&"));
+	return identityDigest(parts.join("&"));
 }
 
-export function computeCacheKey(url: URL, req: Request, cookies: Cookies): string {
+export function computeCacheKey(url: URL, req: Request, cookies: Pick<CookieJar, "peek">): string {
 	return `${dedupKey(url)}|i=${computeIdentityHash(req, cookies)}`;
 }
 
@@ -175,8 +183,37 @@ export function cacheGet(key: string): CacheEntry | undefined {
 	return htmlCache.get(key);
 }
 
-export function cacheSet(key: string, entry: CacheEntry): void {
+// ─── Uncovered-cookie warning ────────────────────────────
+// The identity hash only sees cookies named in CACHE_KEYS. If a loader read a
+// cookie outside that list and the response got cached anyway, the response
+// may be personalised on something the cache key can't distinguish — users
+// could be served each other's pages. Warn loudly (dev AND prod), once per
+// cookie name per process.
+
+const warnedUncoveredCookies = new Set<string>();
+
+export function warnUncoveredCookies(cookies: Cookies): void {
+	const readNames = (cookies as { readNames?: ReadonlySet<string> }).readNames;
+	if (!readNames) return;
+	for (const name of readNames) {
+		if (CACHE_KEYS.includes(name) || warnedUncoveredCookies.has(name)) continue;
+		warnedUncoveredCookies.add(name);
+		console.warn(
+			`\n🚨 [bosia] SECURITY WARNING — possible cross-user cache leak 🚨\n` +
+				`   A cached response's loader read the cookie "${name}", which is NOT in CACHE_KEYS.\n` +
+				`   The cache key cannot tell users apart by this cookie: if the page content\n` +
+				`   depends on it, one user's page can be served to another.\n` +
+				`   Fix (pick one):\n` +
+				`     - Add it to the identity key list: CACHE_KEYS=${[...CACHE_KEYS, name].join(",")}\n` +
+				`     - Or opt the route out of caching: export const cache = false\n`,
+		);
+	}
+}
+
+export function cacheSet(key: string, entry: CacheEntry, cookies?: Cookies): void {
 	if (!CACHE_ENABLED) return;
+	if (CACHE_MAX_BODY_BYTES > 0 && entry.raw.length > CACHE_MAX_BODY_BYTES) return;
+	if (cookies) warnUncoveredCookies(cookies);
 	// Drop any existing entry's index pointers first
 	cacheDeleteKey(key);
 	const evicted = htmlCache.set(key, entry);
@@ -247,16 +284,16 @@ export function buildCompressedVariants(body: Bytes): {
 	} catch {
 		gzip = null;
 	}
-	// brotliCompressSync exists in Bun >= 1.1.5 but is missing from older
-	// @types/bun shipments — cast through any so the call stays loose.
-	const brotliFn = (Bun as unknown as { brotliCompressSync?: (b: Bytes) => Uint8Array })
-		.brotliCompressSync;
-	if (brotliFn) {
-		try {
-			brotli = brotliFn(body) as Bytes;
-		} catch {
-			brotli = null;
-		}
+	try {
+		// Quality 5: ~20x faster than the default 11, still beats gzip on size.
+		// This runs sync in a microtask — 11 would block the event loop ~17ms/500KB.
+		brotli = new Uint8Array(
+			brotliCompressSync(body, {
+				params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 },
+			}),
+		) as Bytes;
+	} catch {
+		brotli = null;
 	}
 	return { gzip, brotli };
 }
@@ -274,6 +311,35 @@ export function concatChunks(chunks: Uint8Array[]): Bytes {
 	return out;
 }
 
+// ─── Miss coalescing ─────────────────────────────────────
+// Stampede protection for cache misses. The first miss on a key becomes the
+// leader (gets `release`); concurrent misses become waiters (get `wait`).
+// Waiters re-check cacheGet after the wait resolves — hit: serve it; miss
+// (leader skipped the write): build independently, no re-leadering. Distinct
+// from dedup(), which shares the *result*; this shares only the *wait*.
+//
+// INVARIANT: the leader must call release() exactly once, after its cacheSet
+// attempt completed or was skipped. A missed release() hangs waiters for the
+// process lifetime — callers guard with try/finally.
+
+const missGates = new Map<string, { promise: Promise<void>; release: () => void }>();
+
+export function coalesceMiss(
+	key: string,
+): { release: () => void; wait?: undefined } | { wait: Promise<void>; release?: undefined } {
+	const existing = missGates.get(key);
+	if (existing) return { wait: existing.promise };
+	let resolve!: () => void;
+	const promise = new Promise<void>((r) => (resolve = r));
+	const release = () => {
+		// Idempotent, and never deletes a successor leader's gate.
+		if (missGates.get(key)?.promise === promise) missGates.delete(key);
+		resolve();
+	};
+	missGates.set(key, { promise, release });
+	return { release };
+}
+
 // ─── Serve a cache hit ───────────────────────────────────
 
 export function serveCached(entry: CacheEntry, req: Request): Response {

package/src/core/cookies.ts

@@ -58,6 +58,7 @@ export class CookieJar implements Cookies {
 	private _outgoing: string[] = [];
 	private _defaults: CookieOptions;
 	private _accessed = false;
+	private _readNames = new Set<string>();
 	private _isHttps: boolean;
 
 	constructor(cookieHeader: string, isHttps = false) {
@@ -70,11 +71,23 @@ export class CookieJar implements Cookies {
 
 	get(name: string): string | undefined {
 		this._accessed = true;
+		if (name in this._incoming) this._readNames.add(name);
+		return this._incoming[name];
+	}
+
+	/**
+	 * Read an incoming cookie WITHOUT flipping `accessed` or recording the name
+	 * in `readNames`. Framework-internal (identity hashing must not count as a
+	 * cookie read); deliberately absent from the public `Cookies` interface so
+	 * loaders can't bypass dependency tracking.
+	 */
+	peek(name: string): string | undefined {
 		return this._incoming[name];
 	}
 
 	getAll(): Record<string, string> {
 		this._accessed = true;
+		for (const name of Object.keys(this._incoming)) this._readNames.add(name);
 		return { ...this._incoming };
 	}
 
@@ -82,6 +95,11 @@ export class CookieJar implements Cookies {
 		return this._accessed;
 	}
 
+	/** Names of incoming cookies that were actually read (present in the request). */
+	get readNames(): ReadonlySet<string> {
+		return this._readNames;
+	}
+
 	set(name: string, value: string, options?: CookieOptions): void {
 		if (!VALID_COOKIE_NAME.test(name)) throw new Error(`Invalid cookie name: ${name}`);
 		const opts = { ...this._defaults, ...options };

package/src/core/dedup.ts

@@ -1,12 +1,12 @@
 // ─── Request Deduplication ──────────────────────────────
-// Concurrent in-flight coalescing for public routes. When N parallel requests
-// hit the same URL, run the loader once and share the resolved value across
-// all N waiters. Settled responses are NOT cached — once the promise resolves,
-// the entry is dropped, so the next request runs the loader again.
+// Concurrent in-flight coalescing. When N parallel requests hit the same URL,
+// run the loader once and share the resolved value across all N waiters.
+// Settled responses are NOT cached — once the promise resolves, the entry is
+// dropped, so the next request runs the loader again.
 //
-// Scope decision lives in the scanner: routes under a `(private)` group skip
-// dedup entirely. Per-user routes MUST be private — sharing a loader result
-// across users would leak data. See docs/guides/request-deduplication.md.
+// The caller's key includes the CACHE_KEYS identity hash (see cache.ts), so
+// 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>>();
 

package/src/core/renderer.ts

@@ -7,14 +7,17 @@ import type { Cookies, LoaderDeps } from "./hooks.ts";
 import { CSP_ENABLED } from "./csp.ts";
 import {
 	CACHE_ENABLED,
+	CACHE_MAX_BODY_BYTES,
 	buildCompressedVariants,
 	cacheGet,
 	cacheSet,
+	coalesceMiss,
 	collectTags,
 	computeCacheKey,
 	concatChunks,
 	serveCached,
 } from "./cache.ts";
+import type { CookieJar } from "./cookies.ts";
 import { HttpError, Redirect } from "./errors.ts";
 import { pickErrorPage, type ErrorOrigin } from "./errorMatch.ts";
 import App from "./client/App.svelte";
@@ -532,27 +535,96 @@ export async function renderSSRStream(
 	const cacheable =
 		CACHE_ENABLED && !CSP_ENABLED && pageMod.cache !== false && req.method === "GET";
 	let cacheKey: string | null = null;
+	let releaseMiss: (() => void) | null = null;
 	if (cacheable) {
-		cacheKey = computeCacheKey(url, req, cookies);
+		cacheKey = computeCacheKey(url, req, cookies as CookieJar);
 		if (!cacheBypass) {
 			const hit = cacheGet(cacheKey);
 			if (hit) return serveCached(hit, req);
+			// Miss coalescing: the first miss leads the build; concurrent misses
+			// wait, then re-check the cache. A waiter that still misses (leader
+			// skipped the write) builds independently — no re-leadering.
+			const gate = coalesceMiss(cacheKey);
+			if (gate.wait) {
+				await gate.wait;
+				const rehit = cacheGet(cacheKey);
+				if (rehit) return serveCached(rehit, req);
+			} else {
+				releaseMiss = gate.release;
+			}
 		}
 	}
 
-	// ── Pre-stream phase: resolve metadata before committing to a 200 ──
-	// Errors here return a proper error response with correct status code.
-	let metadata: Metadata | null = null;
+	// INVARIANT: releaseMiss must fire exactly once — a missed release() hangs
+	// coalesced waiters for the process lifetime. Every early return and throw
+	// below must stay inside this try; the cache-write path hands the release
+	// off to its cacheSet microtask by nulling releaseMiss first.
 	try {
-		metadata = await loadMetadata(route, params, url, locals, cookies, req);
-	} catch (err) {
-		if (err instanceof Redirect) {
-			return Response.redirect(err.location, err.status);
+		// ── Pre-stream phase: resolve metadata before committing to a 200 ──
+		// Errors here return a proper error response with correct status code.
+		let metadata: Metadata | null = null;
+		try {
+			metadata = await loadMetadata(route, params, url, locals, cookies, req);
+		} catch (err) {
+			if (err instanceof Redirect) {
+				return Response.redirect(err.location, err.status);
+			}
+			if (err instanceof HttpError) {
+				return renderErrorPage(
+					err.status,
+					err.message,
+					url,
+					req,
+					route,
+					undefined,
+					undefined,
+					undefined,
+					nonce,
+				);
+			}
+			if (isDev) console.error("Metadata load error:", err);
+			else console.error("Metadata load error:", (err as Error).message ?? err);
+			if (isDev) reportDevErrorFromCatch(err);
+			// Continue with null metadata — don't break the page for a metadata failure
 		}
-		if (err instanceof HttpError) {
+
+		// ── Pre-stream phase: run load() + module imports in parallel before committing to a 200 ──
+		// This ensures HttpError/Redirect from load() can return a proper response before any bytes are sent.
+		const metadataData = metadata?.data ?? null;
+		let data: Awaited<ReturnType<typeof loadRouteData>>;
+		let layoutMods: any[];
+
+		try {
+			[data, layoutMods] = await Promise.all([
+				loadRouteData(url, locals, req, cookies, metadataData, match),
+				Promise.all(route.layoutModules.map((l: () => Promise<any>) => l())),
+			]);
+		} catch (err) {
+			if (err instanceof Redirect) return Response.redirect(err.location, err.status);
+			if (err instanceof HttpError) {
+				const e = err as HttpError & {
+					errorDepth?: number;
+					errorOrigin?: ErrorOrigin;
+					partialLayoutData?: Record<string, any>[];
+				};
+				return renderErrorPage(
+					err.status,
+					err.message,
+					url,
+					req,
+					route,
+					e.errorDepth,
+					e.errorOrigin,
+					e.partialLayoutData,
+					nonce,
+				);
+			}
+			if (isDev) console.error("SSR load error:", err);
+			else console.error("SSR load error:", (err as Error).message ?? err);
+			if (isDev) reportDevErrorFromCatch(err);
 			return renderErrorPage(
-				err.status,
-				err.message,
+				500,
+				"Internal Server Error",
 				url,
 				req,
 				route,
@@ -562,222 +634,189 @@ export async function renderSSRStream(
 				nonce,
 			);
 		}
-		if (isDev) console.error("Metadata load error:", err);
-		else console.error("Metadata load error:", (err as Error).message ?? err);
-		if (isDev) reportDevErrorFromCatch(err);
-		// Continue with null metadata — don't break the page for a metadata failure
-	}
 
-	// ── Pre-stream phase: run load() + module imports in parallel before committing to a 200 ──
-	// This ensures HttpError/Redirect from load() can return a proper response before any bytes are sent.
-	const metadataData = metadata?.data ?? null;
-	let data: Awaited<ReturnType<typeof loadRouteData>>;
-	let layoutMods: any[];
-
-	try {
-		[data, layoutMods] = await Promise.all([
-			loadRouteData(url, locals, req, cookies, metadataData, match),
-			Promise.all(route.layoutModules.map((l: () => Promise<any>) => l())),
-		]);
-	} catch (err) {
-		if (err instanceof Redirect) return Response.redirect(err.location, err.status);
-		if (err instanceof HttpError) {
-			const e = err as HttpError & {
-				errorDepth?: number;
-				errorOrigin?: ErrorOrigin;
-				partialLayoutData?: Record<string, any>[];
-			};
+		if (!data)
 			return renderErrorPage(
-				err.status,
-				err.message,
+				404,
+				"Not Found",
 				url,
 				req,
-				route,
-				e.errorDepth,
-				e.errorOrigin,
-				e.partialLayoutData,
+				undefined,
+				undefined,
+				undefined,
+				undefined,
 				nonce,
 			);
-		}
-		if (isDev) console.error("SSR load error:", err);
-		else console.error("SSR load error:", (err as Error).message ?? err);
-		if (isDev) reportDevErrorFromCatch(err);
-		return renderErrorPage(
-			500,
-			"Internal Server Error",
-			url,
-			req,
-			route,
-			undefined,
-			undefined,
-			undefined,
-			nonce,
-		);
-	}
 
-	if (!data)
-		return renderErrorPage(
-			404,
-			"Not Found",
+		const enc = new TextEncoder();
+		const renderCtx: RenderContext = {
+			request: req,
 			url,
-			req,
-			undefined,
-			undefined,
-			undefined,
-			undefined,
-			nonce,
-		);
-
-	const enc = new TextEncoder();
-	const renderCtx: RenderContext = {
-		request: req,
-		url,
-		route: { pattern: route.pattern },
-		metadata,
-	};
-	const [headExtras, bodyEndExtras] = await Promise.all([
-		pluginRenderFragments("head", renderCtx),
-		pluginRenderFragments("bodyEnd", renderCtx),
-	]);
+			route: { pattern: route.pattern },
+			metadata,
+		};
+		const [headExtras, bodyEndExtras] = await Promise.all([
+			pluginRenderFragments("head", renderCtx),
+			pluginRenderFragments("bodyEnd", renderCtx),
+		]);
 
-	// SSR always runs every loader, so coerce types from the optional sparse shape.
-	const layoutDataFull = (data.layoutData as Record<string, any>[]).map((d) => d ?? {});
-	const pageDataFull = data.pageData ?? {};
+		// SSR always runs every loader, so coerce types from the optional sparse shape.
+		const layoutDataFull = (data.layoutData as Record<string, any>[]).map((d) => d ?? {});
+		const pageDataFull = data.pageData ?? {};
 
-	// ssr=false → no render() needed; ship shell + hydration as a single response.
-	// ssr=false && csr=false is meaningless (nothing renders) — force csr=true.
-	if (!data.ssr) {
-		if (!data.csr && isDev) {
-			console.warn(
-				`⚠️  ${url.pathname}: ssr=false && csr=false renders nothing — forcing csr=true`,
-			);
+		// ssr=false → no render() needed; ship shell + hydration as a single response.
+		// ssr=false && csr=false is meaningless (nothing renders) — force csr=true.
+		if (!data.ssr) {
+			if (!data.csr && isDev) {
+				console.warn(
+					`⚠️  ${url.pathname}: ssr=false && csr=false renders nothing — forcing csr=true`,
+				);
+			}
+			const html =
+				buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments) +
+				buildMetadataChunk(metadata, headExtras, appHtmlSegments) +
+				buildHtmlTail(
+					"",
+					"",
+					pageDataFull,
+					layoutDataFull,
+					true,
+					null,
+					false,
+					bodyEndExtras,
+					nonce,
+					data.pageDeps,
+					data.layoutDeps,
+					appHtmlSegments,
+				);
+			return new Response(html, {
+				headers: { "Content-Type": "text/html; charset=utf-8" },
+			});
 		}
-		const html =
-			buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments) +
-			buildMetadataChunk(metadata, headExtras, appHtmlSegments) +
-			buildHtmlTail(
-				"",
-				"",
-				pageDataFull,
+
+		// Render-first: run render() before committing to a 200. Failure → proper error page
+		// with correct status code, instead of a bare <p> mixed into an already-flushed shell.
+		let body: string, head: string;
+		try {
+			({ body, head } = render(App, {
+				props: {
+					ssrMode: true,
+					ssrPageComponent: pageMod.default,
+					ssrLayoutComponents: layoutMods.map((m: any) => m.default),
+					ssrPageData: pageDataFull,
+					ssrLayoutData: layoutDataFull,
+				},
+			}));
+		} catch (err) {
+			if (isDev) console.error("SSR render error:", err);
+			else console.error("SSR render error:", (err as Error).message ?? err);
+			if (isDev) reportDevErrorFromCatch(err);
+			// Render-phase errors fall through to deepest boundary like a page error.
+			return renderErrorPage(
+				500,
+				"Internal Server Error",
+				url,
+				req,
+				route,
+				route.layoutModules.length,
+				"page",
 				layoutDataFull,
-				true,
-				null,
-				false,
-				bodyEndExtras,
 				nonce,
-				data.pageDeps,
-				data.layoutDeps,
-				appHtmlSegments,
 			);
-		return new Response(html, {
-			headers: { "Content-Type": "text/html; charset=utf-8" },
-		});
-	}
-
-	// Render-first: run render() before committing to a 200. Failure → proper error page
-	// with correct status code, instead of a bare <p> mixed into an already-flushed shell.
-	let body: string, head: string;
-	try {
-		({ body, head } = render(App, {
-			props: {
-				ssrMode: true,
-				ssrPageComponent: pageMod.default,
-				ssrLayoutComponents: layoutMods.map((m: any) => m.default),
-				ssrPageData: pageDataFull,
-				ssrLayoutData: layoutDataFull,
-			},
-		}));
-	} catch (err) {
-		if (isDev) console.error("SSR render error:", err);
-		else console.error("SSR render error:", (err as Error).message ?? err);
-		if (isDev) reportDevErrorFromCatch(err);
-		// Render-phase errors fall through to deepest boundary like a page error.
-		return renderErrorPage(
-			500,
-			"Internal Server Error",
-			url,
-			req,
-			route,
-			route.layoutModules.length,
-			"page",
-			layoutDataFull,
-			nonce,
-		);
-	}
+		}
 
-	// Pre-compute all chunks; pull-based stream gives Bun native backpressure.
-	const chunks: Uint8Array[] = [
-		enc.encode(buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments)),
-		enc.encode(buildMetadataChunk(metadata, headExtras, appHtmlSegments)),
-		enc.encode(
-			buildHtmlTail(
-				body,
-				head,
-				pageDataFull,
-				layoutDataFull,
-				data.csr,
-				null,
-				true,
-				bodyEndExtras,
-				nonce,
-				data.pageDeps,
-				data.layoutDeps,
-				appHtmlSegments,
+		// Pre-compute all chunks; pull-based stream gives Bun native backpressure.
+		const chunks: Uint8Array[] = [
+			enc.encode(buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments)),
+			enc.encode(buildMetadataChunk(metadata, headExtras, appHtmlSegments)),
+			enc.encode(
+				buildHtmlTail(
+					body,
+					head,
+					pageDataFull,
+					layoutDataFull,
+					data.csr,
+					null,
+					true,
+					bodyEndExtras,
+					nonce,
+					data.pageDeps,
+					data.layoutDeps,
+					appHtmlSegments,
+				),
 			),
-		),
-	];
-
-	// ── Response cache: write after chunks built, before stream creation ──
-	// Skip if the handler set cookies — cached response can't reproduce
-	// per-request Set-Cookie headers. Compression runs in a microtask so
-	// the response goes out first.
-	if (cacheable && cacheKey && (cookies as any).outgoing?.length === 0) {
-		const fullBody = concatChunks(chunks);
-		const tags = collectTags(data.layoutDeps ?? null, data.pageDeps ?? null);
-		const keyForWrite = cacheKey;
-		queueMicrotask(() => {
-			const { gzip, brotli } = buildCompressedVariants(fullBody);
-			cacheSet(keyForWrite, {
-				raw: fullBody,
-				gzip,
-				brotli,
-				contentType: "text/html; charset=utf-8",
-				status: 200,
-				extraHeaders: {},
-				tags,
-			});
-		});
-	}
-
-	let i = 0;
-	let cancelled = false;
-	const onAbort = () => {
-		cancelled = true;
-	};
-	req.signal.addEventListener("abort", onAbort, { once: true });
-
-	const stream = new ReadableStream<Uint8Array>({
-		pull(controller) {
-			if (cancelled || i >= chunks.length) {
-				controller.close();
-				req.signal.removeEventListener("abort", onAbort);
-				return;
-			}
-			controller.enqueue(chunks[i++]);
-			if (i >= chunks.length) {
-				controller.close();
-				req.signal.removeEventListener("abort", onAbort);
+		];
+
+		// ── Response cache: write after chunks built, before stream creation ──
+		// Skip if the handler set cookies — cached response can't reproduce
+		// per-request Set-Cookie headers. Compression runs in a microtask so
+		// the response goes out first.
+		if (cacheable && cacheKey && (cookies as any).outgoing?.length === 0) {
+			const fullBody = concatChunks(chunks);
+			// Oversized bodies skip early so they never pay compression; cacheSet
+			// re-checks as the authoritative guard.
+			if (CACHE_MAX_BODY_BYTES === 0 || fullBody.length <= CACHE_MAX_BODY_BYTES) {
+				const tags = collectTags(data.layoutDeps ?? null, data.pageDeps ?? null);
+				const keyForWrite = cacheKey;
+				// Hand the gate release to the write microtask: waiters resume only
+				// after cacheSet ran, so their re-check hits.
+				const rel = releaseMiss;
+				releaseMiss = null;
+				queueMicrotask(() => {
+					try {
+						const { gzip, brotli } = buildCompressedVariants(fullBody);
+						cacheSet(
+							keyForWrite,
+							{
+								raw: fullBody,
+								gzip,
+								brotli,
+								contentType: "text/html; charset=utf-8",
+								status: 200,
+								extraHeaders: {},
+								tags,
+							},
+							cookies,
+						);
+					} finally {
+						rel?.();
+					}
+				});
 			}
-		},
-		cancel() {
+		}
+
+		let i = 0;
+		let cancelled = false;
+		const onAbort = () => {
 			cancelled = true;
-			req.signal.removeEventListener("abort", onAbort);
-		},
-	});
+		};
+		req.signal.addEventListener("abort", onAbort, { once: true });
+
+		const stream = new ReadableStream<Uint8Array>({
+			pull(controller) {
+				if (cancelled || i >= chunks.length) {
+					controller.close();
+					req.signal.removeEventListener("abort", onAbort);
+					return;
+				}
+				controller.enqueue(chunks[i++]);
+				if (i >= chunks.length) {
+					controller.close();
+					req.signal.removeEventListener("abort", onAbort);
+				}
+			},
+			cancel() {
+				cancelled = true;
+				req.signal.removeEventListener("abort", onAbort);
+			},
+		});
 
-	return new Response(stream, {
-		headers: { "Content-Type": "text/html; charset=utf-8" },
-	});
+		return new Response(stream, {
+			headers: { "Content-Type": "text/html; charset=utf-8" },
+		});
+	} finally {
+		releaseMiss?.();
+	}
 }
 
 // ─── Form Action Page Renderer ───────────────────────────

package/src/core/routeFile.ts

@@ -94,7 +94,6 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 	lines.push("  layoutServers: { loader: () => Promise<any>; depth: number }[];");
 	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
-	lines.push('  scope: "public" | "private";');
 	lines.push("}> = [");
 	for (const r of pages) {
 		const layoutImports = r.layouts
@@ -122,7 +121,6 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 		lines.push(`    layoutServers: [${layoutServerImports}],`);
 		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
-		lines.push(`    scope: ${JSON.stringify(r.scope)},`);
 		lines.push("  },");
 	}
 	lines.push("];\n");

package/src/core/scanner.ts

@@ -46,7 +46,6 @@ export function scanRoutes(): RouteManifest {
 		layoutServerChain: { path: string; depth: number }[],
 		errorPageChain: { path: string; depth: number }[],
 		inheritedTrailingSlash: TrailingSlash,
-		inheritedScope: "public" | "private",
 	) {
 		const fullDir = join(ROUTES_DIR, dir);
 		if (!existsSync(fullDir)) return;
@@ -110,7 +109,6 @@ export function scanRoutes(): RouteManifest {
 				layoutServers: [...currentLayoutServers],
 				errorPages: [...currentErrorPages],
 				trailingSlash: effectiveTs,
-				scope: inheritedScope,
 			});
 		}
 
@@ -122,9 +120,6 @@ export function scanRoutes(): RouteManifest {
 			const dirName = entry.name;
 			// Route groups like (public), (auth) are invisible in URLs
 			const isGroup = /^\(.*\)$/.test(dirName);
-			// `(private)` anywhere in the chain marks descendants as per-user (dedup off)
-			const childScope: "public" | "private" =
-				inheritedScope === "private" || dirName === "(private)" ? "private" : "public";
 
 			walk(
 				dir ? join(dir, dirName) : dirName,
@@ -133,12 +128,11 @@ export function scanRoutes(): RouteManifest {
 				currentLayoutServers,
 				currentErrorPages,
 				currentTrailingSlash,
-				childScope,
 			);
 		}
 	}
 
-	walk("", [], [], [], [], "never", "public");
+	walk("", [], [], [], [], "never");
 
 	// 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).

package/src/core/server.ts

@@ -24,15 +24,19 @@ import { buildCspHeader, CSP_DIRECTIVES_TEMPLATE, CSP_ENABLED, generateNonce } f
 import { isDev, compress, isStaticPath } from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
-import { buildStaticManifest, lookupStatic } from "./staticManifest.ts";
-import { dedup, dedupKey } from "./dedup.ts";
+import { buildPrerenderManifest, buildStaticManifest, lookupStatic } from "./staticManifest.ts";
+import { dedup } from "./dedup.ts";
 import {
 	CACHE_ENABLED,
+	CACHE_KEYS,
+	CACHE_MAX_BODY_BYTES,
 	buildCompressedVariants,
 	cacheGet,
 	cacheSet,
+	coalesceMiss,
 	computeCacheKey,
 	serveCached,
+	warnUncoveredCookies,
 } from "./cache.ts";
 import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import {
@@ -187,6 +191,7 @@ function parseActionName(url: URL): string {
 // Dev keeps the per-request fallthrough so files dropped into `public/` mid-session
 // are served without a restart (dev's watcher doesn't fire on `public/`).
 const staticManifest = isDev ? null : buildStaticManifest(OUT_DIR);
+const prerenderManifest = isDev ? null : buildPrerenderManifest(OUT_DIR);
 
 async function resolve(event: RequestEvent): Promise<Response> {
 	const { request, url, locals, cookies } = event;
@@ -284,15 +289,18 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				return { data, metadata, cookiesAccessed: (cookies as CookieJar).accessed };
 			};
 
-			// Dedup public routes by URL + mask. `(private)` scope routes (per-user
-			// content) skip the cache to prevent cross-user data leaks. The mask is
-			// part of the key so concurrent requests for the same URL with different
-			// invalidation patterns don't collapse onto each other. See dedup.ts.
-			const dedupK = invalidatedBits
-				? `${dedupKey(routeUrl)}|m=${invalidatedBits}`
-				: dedupKey(routeUrl);
-			const result =
-				pageMatch?.route.scope === "private" ? await runLoad() : await dedup(dedupK, runLoad);
+			// Dedup concurrent identical requests. The key includes the CACHE_KEYS
+			// identity hash, so different users never share a loader result — same
+			// isolation contract as the response cache. The mask is part of the key
+			// so concurrent requests for the same URL with different invalidation
+			// patterns don't collapse onto each other. See dedup.ts.
+			const dedupK =
+				computeCacheKey(routeUrl, request, cookies as CookieJar) +
+				(invalidatedBits ? `|m=${invalidatedBits}` : "");
+			const result = await dedup(dedupK, runLoad);
+			// Identity only covers CACHE_KEYS — warn if a loader read a session
+			// cookie outside that list (dedup could then mix users' results).
+			warnUncoveredCookies(cookies);
 
 			const cookiesWereAccessed = (cookies as CookieJar).accessed || result.cookiesAccessed;
 			const cc = cookiesWereAccessed ? "private, no-cache" : "public, max-age=0, must-revalidate";
@@ -359,6 +367,10 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// `.webp` URLs that would otherwise be intercepted by isStaticPath).
 	const apiMatch = await resolveApiMatch(apiRoutes, path);
 	if (apiMatch) {
+		// INVARIANT: once set, releaseApiMiss must fire exactly once — a missed
+		// release() hangs coalesced waiters for the process lifetime. The cache
+		// write path hands it off to its microtask by nulling it first.
+		let releaseApiMiss: (() => void) | null = null;
 		try {
 			const mod = await apiMatch.route.module();
 			const handler = mod[method];
@@ -383,10 +395,20 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				CACHE_ENABLED && !CSP_ENABLED && (mod as any).cache !== false && method === "GET";
 			let apiCacheKey: string | null = null;
 			if (apiCacheable) {
-				apiCacheKey = computeCacheKey(url, request, cookies);
+				apiCacheKey = computeCacheKey(url, request, cookies as CookieJar);
 				if (!url.searchParams.has("_invalidated")) {
 					const hit = cacheGet(apiCacheKey);
 					if (hit) return serveCached(hit, request);
+					// Miss coalescing: first miss runs the handler; concurrent misses
+					// wait, re-check the cache, and on a still-miss run independently.
+					const gate = coalesceMiss(apiCacheKey);
+					if (gate.wait) {
+						await gate.wait;
+						const rehit = cacheGet(apiCacheKey);
+						if (rehit) return serveCached(rehit, request);
+					} else {
+						releaseApiMiss = gate.release;
+					}
 				}
 			}
 
@@ -433,23 +455,36 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				const extraHeaders = captureCacheableHeaders(response.headers);
 				const contentType = responseContentType || "application/octet-stream";
 				const keyForWrite = apiCacheKey;
+				// Hand the gate release to the write microtask: waiters resume only
+				// after the cacheSet attempt, so their re-check hits.
+				const rel = releaseApiMiss;
+				releaseApiMiss = null;
 				queueMicrotask(async () => {
 					try {
 						const buf = new Uint8Array(await cloned.arrayBuffer());
+						// Oversized bodies skip early so they never pay compression;
+						// cacheSet re-checks as the authoritative guard.
+						if (CACHE_MAX_BODY_BYTES > 0 && buf.length > CACHE_MAX_BODY_BYTES) return;
 						const { gzip, brotli } = buildCompressedVariants(buf);
 						// API endpoints have no LoaderDeps in v0.6 — invalidation is
 						// URL/prefix only. See ROADMAP for deferred tag support.
-						cacheSet(keyForWrite, {
-							raw: buf,
-							gzip,
-							brotli,
-							contentType,
-							status: 200,
-							extraHeaders,
-							tags: [],
-						});
+						cacheSet(
+							keyForWrite,
+							{
+								raw: buf,
+								gzip,
+								brotli,
+								contentType,
+								status: 200,
+								extraHeaders,
+								tags: [],
+							},
+							cookies,
+						);
 					} catch {
 						/* drop silently — cache population is best-effort */
+					} finally {
+						rel?.();
 					}
 				});
 			}
@@ -480,6 +515,8 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				});
 			}
 			return Response.json({ error: "Internal Server Error" }, { status: 500 });
+		} finally {
+			releaseApiMiss?.();
 		}
 	}
 
@@ -497,11 +534,18 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			return new Response("Not Found", { status: 404 });
 		}
 		// Dev: keep the per-request fallthrough so files dropped into `public/`
-		// mid-session are served without a restart.
-		if (path.startsWith("/dist/client/")) {
+		// mid-session are served without a restart. Decode once — filenames on
+		// disk are raw; safePath still runs after so traversal stays blocked.
+		let decodedPath: string;
+		try {
+			decodedPath = decodeURIComponent(path);
+		} catch {
+			return new Response("Not Found", { status: 404 });
+		}
+		if (decodedPath.startsWith("/dist/client/")) {
 			const resolved = safePath(
 				`${OUT_DIR}/client`,
-				path.split("?")[0].slice("/dist/client".length),
+				decodedPath.split("?")[0].slice("/dist/client".length),
 			);
 			if (resolved) {
 				const file = Bun.file(resolved);
@@ -511,17 +555,17 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			}
 			return new Response("Not Found", { status: 404 });
 		}
-		const pubPath = safePath("./public", path);
+		const pubPath = safePath("./public", decodedPath);
 		if (pubPath) {
 			const pub = Bun.file(pubPath);
 			if (await pub.exists()) return new Response(pub);
 		}
-		const distPath = safePath(OUT_DIR, path);
+		const distPath = safePath(OUT_DIR, decodedPath);
 		if (distPath) {
 			const dist = Bun.file(distPath);
 			if (await dist.exists()) return new Response(dist);
 		}
-		const staticPath = safePath(`${OUT_DIR}/static`, path);
+		const staticPath = safePath(`${OUT_DIR}/static`, decodedPath);
 		if (staticPath) {
 			const staticFile = Bun.file(staticPath);
 			if (await staticFile.exists()) return new Response(staticFile);
@@ -535,22 +579,18 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	// in dev would mask errors (the badge stays empty, the SSE reload script
 	// isn't injected, and the page can't auto-recover when the source is fixed).
 	// Live SSR every request in dev so /about behaves like every other route.
-	if (!isDev) {
-		// Try both `<path>/index.html` (always/ignore mode) and `<path>.html` (never mode)
-		const prerenderCandidates =
-			path === "/" ? ["index.html"] : [`${path}/index.html`, `${path.replace(/\/$/, "")}.html`];
-		for (const candidate of prerenderCandidates) {
-			const prerenderPath = safePath(`${OUT_DIR}/prerendered`, candidate);
-			if (!prerenderPath) continue;
-			const prerenderFile = Bun.file(prerenderPath);
-			if (await prerenderFile.exists()) {
-				return new Response(prerenderFile, {
-					headers: {
-						"Content-Type": "text/html; charset=utf-8",
-						"Cache-Control": "public, max-age=3600",
-					},
-				});
-			}
+	if (prerenderManifest) {
+		// Keys come from a boot-time walk of `dist/prerendered/`, not from the
+		// URL, so no safePath needed — a non-matching path is just a miss.
+		const key = path === "/" ? "/" : path.replace(/\/$/, "");
+		const abs = prerenderManifest.get(key);
+		if (abs) {
+			return new Response(Bun.file(abs), {
+				headers: {
+					"Content-Type": "text/html; charset=utf-8",
+					"Cache-Control": "public, max-age=3600",
+				},
+			});
 		}
 	}
 
@@ -1008,7 +1048,6 @@ function loadBuiltManifest(): RouteManifest {
 			layoutServers: [],
 			errorPages: [],
 			trailingSlash: r.trailingSlash,
-			scope: r.scope,
 		})),
 		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, server: "" })),
 		errorPage: null,
@@ -1095,6 +1134,16 @@ for (const plugin of plugins) {
 app.listen(PORT, () => {
 	// In dev mode the proxy owns the user-facing port — don't print the internal port
 	if (!isDev) console.log(`⬡ Bosia server running at http://localhost:${PORT}`);
+	// Last line of startup on purpose — the cache identity contract is the one
+	// config mistake that leaks one user's page to another, so it stays visible.
+	if (CACHE_ENABLED) {
+		console.log(
+			`\n🔑 Response cache tells users apart ONLY by these cookies/headers: [${CACHE_KEYS.join(", ")}]\n` +
+				`   Using a different session cookie or auth header? Add its name to CACHE_KEYS,\n` +
+				`   or one user's personalised page can be served to another. Routes personalised\n` +
+				`   by anything else should set \`export const cache = false\`.\n`,
+		);
+	}
 });
 
 async function shutdown() {

package/src/core/staticManifest.ts

@@ -100,10 +100,44 @@ export function buildStaticManifest(outDir: string): StaticManifest {
 }
 
 export function lookupStatic(manifest: StaticManifest, urlPath: string): StaticEntry | null {
-	const key = urlPath.split("?")[0];
+	const raw = urlPath.split("?")[0];
+	// Manifest keys are raw filenames; URLs arrive percent-encoded.
+	let key: string;
+	try {
+		key = decodeURIComponent(raw);
+	} catch {
+		return null; // malformed encoding → 404
+	}
 	return manifest.get(key) ?? null;
 }
 
+/**
+ * Boot-time map of URL path → absolute file path for `dist/prerendered/`.
+ * `index.html` → `/`, `foo/index.html` → `/foo`, `foo.html` → `/foo`.
+ * On collision the `…/index.html` variant wins (mirrors the old runtime
+ * candidate order). Replaces per-request `Bun.file().exists()` probes.
+ */
+export function buildPrerenderManifest(outDir: string): Map<string, string> {
+	const manifest = new Map<string, string>();
+	const root = join(resolvePath(outDir), "prerendered");
+	for (const { abs, rel } of walk(root)) {
+		if (!rel.endsWith(".html")) continue;
+		let key: string;
+		let isIndex = false;
+		if (rel === "index.html") {
+			key = "/";
+			isIndex = true;
+		} else if (rel.endsWith("/index.html")) {
+			key = `/${rel.slice(0, -"/index.html".length)}`;
+			isIndex = true;
+		} else {
+			key = `/${rel.slice(0, -".html".length)}`;
+		}
+		if (isIndex || !manifest.has(key)) manifest.set(key, abs);
+	}
+	return manifest;
+}
+
 // Re-export for tests that want to confirm a file-on-disk exists at the entry.
 export function entryFileExists(entry: StaticEntry): boolean {
 	try {

package/src/core/types.ts

@@ -26,12 +26,6 @@ export interface PageRoute {
 	errorPages: { path: string; depth: number }[];
 	/** Effective trailing-slash mode (page wins over layout chain). Defaults to "never". */
 	trailingSlash: TrailingSlash;
-	/**
-	 * Dedup scope. `"public"` (default) → loader runs once for concurrent identical
-	 * URLs. `"private"` → loader runs per-request (use for per-user routes).
-	 * Set by placing the route under a `(private)` group folder anywhere in the chain.
-	 */
-	scope: "public" | "private";
 }
 
 /** An API route discovered from the file system */