bosia 0.8.4 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.8.4",
+	"version": "0.8.6",
 	"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/core/build.ts

@@ -10,6 +10,7 @@ import { prerenderStaticRoutes, generateStaticSite } from "./prerender.ts";
 import { loadEnv, classifyEnvVars } from "./env.ts";
 import { generateEnvModules } from "./envCodegen.ts";
 import { BOSIA_NODE_PATH, OUT_DIR, resolveBosiaBin } from "./paths.ts";
+import { finalizeTailwindCss, TW_TEMP_BASENAME } from "./twHash.ts";
 import { loadPlugins } from "./config.ts";
 import type { BuildContext } from "./types/plugin.ts";
 import { loadAppHtmlTemplate, writeAppHtmlSegments } from "./appHtml.ts";
@@ -113,15 +114,21 @@ ensureRootDirs();
 // 2d. Generate .bosia/env.server.ts, .bosia/env.client.ts, .bosia/types/env.d.ts
 generateEnvModules(classifiedEnv);
 
-// 3. Start Tailwind CSS (async — runs concurrently with client+server builds)
+// 3. Start Tailwind CSS (async — runs concurrently with client+server builds).
+// Output goes to a temp name in dist/client; after the build we content-hash it
+// and rename to bosia-tw-<hash>.css so it gets immutable caching and rebuilds
+// bust browser caches only when the CSS actually changed. mkdir up front —
+// Bun.build writes the same dir concurrently and mkdir is idempotent.
+mkdirSync(join(OUT_DIR, "client"), { recursive: true });
 const tailwindBin = resolveBosiaBin("tailwindcss");
+const tailwindTempPath = join(OUT_DIR, "client", TW_TEMP_BASENAME);
 const tailwindProc = Bun.spawn(
 	[
 		tailwindBin,
 		"-i",
 		"./src/app.css",
 		"-o",
-		"./public/bosia-tw.css",
+		tailwindTempPath,
 		...(isProduction ? ["--minify"] : []),
 	],
 	{
@@ -191,7 +198,8 @@ if (tailwindExitCode !== 0) {
 	console.error("❌ Tailwind CSS build failed:\n" + stderr);
 	process.exit(1);
 }
-console.log("✅ Tailwind CSS built: public/bosia-tw.css");
+const twFile = finalizeTailwindCss(tailwindTempPath);
+console.log(`✅ Tailwind CSS built: ${OUT_DIR}/client/${twFile}`);
 
 if (!clientResult.success) {
 	console.error("❌ Client build failed:");
@@ -253,6 +261,7 @@ const distManifest = {
 		jsFiles.find((f) => f.startsWith("hydrate")) ??
 		"hydrate.js",
 	serverEntry,
+	tw: twFile,
 };
 writeFileSync(`${OUT_DIR}/manifest.json`, JSON.stringify(distManifest, null, 2));
 console.log(`✅ Client bundle: ${jsFiles.join(", ")}`);

package/src/core/cache.ts

@@ -88,14 +88,15 @@ class LRU<K, V> {
 		this.map.set(key, v);
 		return v;
 	}
-	set(key: K, value: V): K | undefined {
+	set(key: K, value: V): { key: K; value: V } | undefined {
 		if (this.map.has(key)) this.map.delete(key);
 		this.map.set(key, value);
 		if (this.map.size > this.cap) {
 			const oldest = this.map.keys().next().value as K | undefined;
 			if (oldest !== undefined) {
+				const evicted = this.map.get(oldest) as V;
 				this.map.delete(oldest);
-				return oldest;
+				return { key: oldest, value: evicted };
 			}
 		}
 		return undefined;
@@ -217,7 +218,7 @@ export function cacheSet(key: string, entry: CacheEntry, cookies?: Cookies): voi
 	// Drop any existing entry's index pointers first
 	cacheDeleteKey(key);
 	const evicted = htmlCache.set(key, entry);
-	if (evicted) cacheDeleteIndexOnly(evicted);
+	if (evicted) cacheDeleteIndexOnly(evicted.key, evicted.value);
 	for (const tag of entry.tags) {
 		let set = tagIndex.get(tag);
 		if (!set) {
@@ -257,9 +258,14 @@ function cacheDeleteKey(key: string): void {
 }
 
 /** Cleanup index pointers for a key after LRU evicted it. */
-function cacheDeleteIndexOnly(key: string): void {
-	for (const set of tagIndex.values()) set.delete(key);
-	for (const [tag, set] of tagIndex) if (set.size === 0) tagIndex.delete(tag);
+function cacheDeleteIndexOnly(key: string, entry: CacheEntry): void {
+	for (const tag of entry.tags) {
+		const set = tagIndex.get(tag);
+		if (set) {
+			set.delete(key);
+			if (set.size === 0) tagIndex.delete(tag);
+		}
+	}
 	const path = pathOfKey(key);
 	const pset = pathIndex.get(path);
 	if (pset) {

package/src/core/client/App.svelte

@@ -63,6 +63,26 @@
 	let firstNav = true;
 	let navDoneTimer: ReturnType<typeof setTimeout> | null = null;
 
+	// Scroll after a nav settles: forward navs go to top (or the URL hash);
+	// back/forward navs restore the position saved for that history entry.
+	// Runs after tick() so the destination page's real height is in the DOM.
+	// goto({ noScroll: true }) flips `router.suppressScroll` for one nav.
+	function settleScroll() {
+		if (router.isPush && !router.suppressScroll) {
+			const hash = window.location.hash;
+			tick().then(() => {
+				if (!scrollToHash(hash)) window.scrollTo(0, 0);
+			});
+		} else if (!router.isPush) {
+			const pos = router.pendingScroll;
+			// ponytail: single post-tick restore; content that loads later (images
+			// without dimensions) can still shift it. Revisit only if reported.
+			if (pos) tick().then(() => window.scrollTo(pos.x, pos.y));
+		}
+		router.pendingScroll = null;
+		router.suppressScroll = false;
+	}
+
 	$effect(() => {
 		if (ssrMode) return;
 
@@ -247,13 +267,7 @@
 					appState.errorComponent = errMod.default;
 					appState.errorProps = { error: { status: errStatus, message: errMessage } };
 					appState.errorDepth = K;
-					if (router.isPush && !router.suppressScroll) {
-						const hash = window.location.hash;
-						tick().then(() => {
-							if (!scrollToHash(hash)) window.scrollTo(0, 0);
-						});
-					}
-					router.suppressScroll = false;
+					settleScroll();
 					settle({ url, params: match.params });
 				} catch {
 					window.location.href = path;
@@ -342,16 +356,7 @@
 			appState.errorProps = null;
 			appState.errorDepth = null;
 
-			// Scroll to top on forward navigation (not on popstate/back-forward).
-			// goto({ noScroll: true }) flips `router.suppressScroll` for one nav.
-			// If the destination URL has a hash, scroll to that element instead.
-			if (router.isPush && !router.suppressScroll) {
-				const hash = window.location.hash;
-				tick().then(() => {
-					if (!scrollToHash(hash)) window.scrollTo(0, 0);
-				});
-			}
-			router.suppressScroll = false;
+			settleScroll();
 
 			// Update document title and meta description from server metadata
 			if (result?.metadata) {

package/src/core/client/router.svelte.ts

@@ -16,6 +16,20 @@ function buildTarget(path: string): { url: URL; params: Record<string, string> }
 	return { url, params: match?.params ?? {} };
 }
 
+// ─── Scroll restoration ───
+// Positions keyed by a per-entry index stamped into `history.state.bosiaIndex`.
+// `scrollRestoration = "manual"` because the browser restores at popstate time,
+// before the SPA has rendered the destination page — it clamps against the
+// wrong document height. We restore ourselves after the nav settles (App.svelte).
+// Persisted to sessionStorage on unload so reload / back-into-app still restores.
+const SCROLL_KEY = "bosia:scroll";
+let scrollPositions: Record<number, { x: number; y: number }> = {};
+let historyIndex = 0;
+
+function saveScroll() {
+	scrollPositions[historyIndex] = { x: window.scrollX, y: window.scrollY };
+}
+
 export function scrollToHash(hash: string): boolean {
 	if (typeof document === "undefined" || !hash) return false;
 	const raw = hash.startsWith("#") ? hash.slice(1) : hash;
@@ -45,6 +59,8 @@ export const router = new (class Router {
 	lastNavType: NavType = "enter";
 	/** Set by `goto({ noScroll: true })`; consumed once by App.svelte after the next nav settles. */
 	suppressScroll = false;
+	/** Saved scroll position for the entry a popstate landed on; consumed once by App.svelte after the nav settles. */
+	pendingScroll: { x: number; y: number } | null = null;
 
 	navigate(path: string, opts: { replace?: boolean; source?: NavType } = {}) {
 		if (this.currentRoute === path) return;
@@ -74,12 +90,15 @@ export const router = new (class Router {
 
 		this.lastNavType = navType;
 		this.isPush = true;
+		this.pendingScroll = null;
 		this.currentRoute = finalPath;
 		if (typeof history !== "undefined") {
 			if (opts.replace) {
-				history.replaceState({}, "", finalPath);
+				history.replaceState({ bosiaIndex: historyIndex }, "", finalPath);
 			} else {
-				history.pushState({}, "", finalPath);
+				saveScroll();
+				historyIndex++;
+				history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 			}
 		}
 	}
@@ -87,6 +106,22 @@ export const router = new (class Router {
 	init() {
 		if (typeof window === "undefined") return;
 
+		history.scrollRestoration = "manual";
+		try {
+			scrollPositions = JSON.parse(sessionStorage.getItem(SCROLL_KEY) ?? "{}");
+		} catch {
+			scrollPositions = {};
+		}
+		const stamped = history.state?.bosiaIndex != null;
+		historyIndex = stamped ? history.state.bosiaIndex : 0;
+		history.replaceState({ ...history.state, bosiaIndex: historyIndex }, "");
+		// Restore after a reload — manual mode means the browser won't. Only for
+		// entries we stamped before (a fresh visit has no bosiaIndex in state).
+		const initial = scrollPositions[historyIndex];
+		if (stamped && initial) {
+			requestAnimationFrame(() => window.scrollTo(initial.x, initial.y));
+		}
+
 		// Intercept <a> clicks for client-side navigation
 		window.addEventListener("click", (e) => {
 			// Let browser handle non-primary buttons, modifier-clicks, already-handled events
@@ -110,7 +145,9 @@ export const router = new (class Router {
 				e.preventDefault();
 				const finalPath = anchor.pathname + anchor.search + anchor.hash;
 				if (this.currentRoute !== finalPath) {
-					history.pushState({}, "", finalPath);
+					saveScroll();
+					historyIndex++;
+					history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 					this.currentRoute = finalPath;
 				}
 				scrollToHash(anchor.hash);
@@ -122,8 +159,13 @@ export const router = new (class Router {
 		});
 
 		// Browser back/forward
-		window.addEventListener("popstate", () => {
+		window.addEventListener("popstate", (e) => {
 			const finalPath = window.location.pathname + window.location.search + window.location.hash;
+			// Save the position of the entry we're leaving (historyIndex is still
+			// the old entry's), then look up where the landed-on entry was.
+			saveScroll();
+			historyIndex = e.state?.bosiaIndex ?? 0;
+			this.pendingScroll = scrollPositions[historyIndex] ?? null;
 			// Fire beforeNavigate listeners; popstate can't be reliably cancelled
 			// (browser history already advanced), so we surface the event for
 			// observation only — `cancel()` is a no-op for this source.
@@ -147,6 +189,14 @@ export const router = new (class Router {
 		// listeners can warn-on-leave (return value ignored; cancellation here
 		// requires `beforeunload`, not in scope).
 		window.addEventListener("beforeunload", () => {
+			// ponytail: beforeunload can be skipped on mobile page-discard; add a
+			// visibilitychange persist if restore-after-reload proves flaky there.
+			saveScroll();
+			try {
+				sessionStorage.setItem(SCROLL_KEY, JSON.stringify(scrollPositions));
+			} catch {
+				// sessionStorage unavailable (private mode / quota) — skip persistence.
+			}
 			const fromTarget = buildTarget(this.currentRoute);
 			const nav: Navigation = {
 				from: fromTarget,

package/src/core/dev.ts

@@ -138,11 +138,50 @@ async function runBuild(): Promise<boolean> {
 const DEV_PORT = Number(process.env.PORT) || 9000;
 const APP_PORT = DEV_PORT + 1; // internal, hidden from user
 
+// A previous dev session's app-server child can outlive its parent: an unclean
+// stop (SIGKILL, IDE stop button, crash) skips graceful cleanup, or a shutdown
+// slower than the SIGTERM grace window orphans it. The orphan keeps APP_PORT
+// bound and answers the new proxy with bundle hashes that no longer exist on
+// disk → "ENOENT reading +page-<hash>.js" 500s. Reap whatever is listening on
+// APP_PORT before we spawn, so a stale child can never shadow the fresh build.
+async function reapStaleAppServer(port: number) {
+	try {
+		const proc = spawn(["lsof", "-ti", `tcp:${port}`, "-sTCP:LISTEN"], {
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		const out = await new Response(proc.stdout).text();
+		await proc.exited;
+		const pids = [...new Set(out.split("\n").map((s) => s.trim()))]
+			.map(Number)
+			.filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid);
+		for (const pid of pids) {
+			try {
+				process.kill(pid, "SIGKILL");
+				console.log(`🧹 Reaped stale app server holding port ${port} (pid ${pid})`);
+			} catch {}
+		}
+		if (pids.length) await Bun.sleep(200); // let the port free before we bind
+	} catch {
+		// lsof unavailable or errored — fail open; a real conflict surfaces on bind.
+	}
+}
+
 async function startAppServer() {
 	if (appProcess) {
 		intentionalKill = true;
-		appProcess.kill();
-		await appProcess.exited;
+		appProcess.kill("SIGTERM");
+		// Escalate to SIGKILL if the child won't stop — otherwise `await exited`
+		// hangs the rebuild forever, or (on a slow exit) the child lingers on
+		// APP_PORT and shadows the next spawn.
+		const exited = await Promise.race([
+			appProcess.exited.then(() => true),
+			Bun.sleep(3_000).then(() => false),
+		]);
+		if (!exited) {
+			appProcess.kill("SIGKILL");
+			await appProcess.exited;
+		}
 		intentionalKill = false;
 	}
 
@@ -421,6 +460,9 @@ const devServer = Bun.serve({
 
 // ─── Initial Build ────────────────────────────────────────
 
+// Clear any orphaned app server from a previous session before the first spawn.
+await reapStaleAppServer(APP_PORT);
+
 await buildAndRestart();
 
 console.log(`\n🌐 Open http://localhost:${DEV_PORT}\n`);
@@ -428,7 +470,7 @@ console.log(`\n🌐 Open http://localhost:${DEV_PORT}\n`);
 // ─── File Watcher ─────────────────────────────────────────
 // Watch src/ recursively. Skip generated files to avoid loops.
 
-const GENERATED = [join(process.cwd(), ".bosia"), join(process.cwd(), "public", "bosia-tw.css")];
+const GENERATED = [join(process.cwd(), ".bosia")];
 
 function isGenerated(path: string): boolean {
 	return GENERATED.some((g) => path.startsWith(g));
@@ -586,7 +628,13 @@ async function shutdown() {
 
 	if (appProcess) {
 		appProcess.kill("SIGTERM");
-		await Promise.race([appProcess.exited, Bun.sleep(2_500)]);
+		const exited = await Promise.race([
+			appProcess.exited.then(() => true),
+			Bun.sleep(2_500).then(() => false),
+		]);
+		// Don't orphan a slow-to-stop child (it would keep APP_PORT bound and
+		// break the next `bun run dev`). Force it down before we exit.
+		if (!exited) appProcess.kill("SIGKILL");
 	}
 
 	// Everything is stopped — exit now rather than waiting for the loop to drain.

package/src/core/html.ts

@@ -9,7 +9,7 @@ import { interpolateSegment } from "./appHtml.ts";
 // Maps hashed filenames → script/link tags.
 // Cached at startup; server restarts on rebuild in dev anyway.
 
-export const distManifest: { js: string[]; css: string[]; entry: string } = (() => {
+export const distManifest: { js: string[]; css: string[]; entry: string; tw?: string } = (() => {
 	const p = `${OUT_DIR}/manifest.json`;
 	return existsSync(p)
 		? JSON.parse(readFileSync(p, "utf-8"))
@@ -19,6 +19,14 @@ export const distManifest: { js: string[]; css: string[]; entry: string } = (()
 export const isDev = process.env.NODE_ENV !== "production";
 const cacheBust = isDev ? `?v=${Date.now()}` : "";
 
+/** Tailwind stylesheet link. Content-hashed name needs no cache buster — the
+ *  hash IS the buster. Fallback keeps older dist/ artifacts (no `tw` field) styled. */
+function twCssLink(): string {
+	return distManifest.tw
+		? `<link rel="stylesheet" href="/dist/client/${distManifest.tw}">`
+		: `<link rel="stylesheet" href="/bosia-tw.css${cacheBust}">`;
+}
+
 /** Inline theme bootstrap — runs before paint to avoid FOUC. theme ∈ light|dark|system (missing = system). */
 const THEME_INIT_JS =
 	"try{var t=localStorage.getItem('theme');" +
@@ -161,7 +169,7 @@ export function buildHtml(
 		return (
 			headOpenInterpolated +
 			`\n  ${faviconLine}${cssLinks}\n` +
-			`  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">\n` +
+			`  ${twCssLink()}\n` +
 			`  <script${n}>${THEME_INIT_JS}</script>\n` +
 			`  ${fallbackTitle}${head}` +
 			headCloseInterpolated +
@@ -180,7 +188,7 @@ export function buildHtml(
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
   ${head}
   ${cssLinks}
-  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">
+  ${twCssLink()}
   <script${n}>${THEME_INIT_JS}</script>
 </head>
 <body>
@@ -213,7 +221,7 @@ export function buildHtmlShellOpen(
 		return (
 			headOpenInterpolated +
 			`\n  ${faviconLine}${cssLinks}\n` +
-			`  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">\n` +
+			`  ${twCssLink()}\n` +
 			`  <script${n}>${THEME_INIT_JS}</script>\n` +
 			`  <link rel="modulepreload" href="/dist/client/${distManifest.entry}${cacheBust}">`
 		);
@@ -225,7 +233,7 @@ export function buildHtmlShellOpen(
 		`  <meta name="viewport" content="width=device-width, initial-scale=1.0">\n` +
 		`  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n` +
 		`  ${cssLinks}\n` +
-		`  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">\n` +
+		`  ${twCssLink()}\n` +
 		`  <script${n}>${THEME_INIT_JS}</script>\n` +
 		`  <link rel="modulepreload" href="/dist/client/${distManifest.entry}${cacheBust}">`
 	);

package/src/core/plugin.ts

@@ -82,13 +82,13 @@ export function makeBosiaPlugin(target: "browser" | "bun" = "bun") {
 			});
 
 			// "tailwindcss" inside app.css is a Tailwind CLI directive —
-			// it's already compiled to public/bosia-tw.css by the CLI step.
+			// it's already compiled to dist/client/bosia-tw-<hash>.css by the CLI step.
 			// Return an empty CSS module so Bun's CSS bundler doesn't choke on it.
 			build.onResolve({ filter: /^tailwindcss$/ }, () => ({
 				path: "tailwindcss",
 				namespace: "bosia-empty-css",
 			}));
-			// app.css is processed by Tailwind CLI into public/bosia-tw.css and
+			// app.css is processed by Tailwind CLI into dist/client/bosia-tw-<hash>.css and
 			// loaded via <link> tag in HTML. User layouts often `import "../app.css"`
 			// for IDE/Tailwind tooling — bundle as JS no-op so Bun doesn't emit a
 			// CSS chunk per dynamic-imported route (identical content → output

package/src/core/plugins/inspector/bun-plugin.ts

@@ -1,12 +1,10 @@
 import { parse, compile } from "svelte/compiler";
 import MagicString from "magic-string";
-import { basename, relative } from "node:path";
+import { relative } from "node:path";
 import type { BunPlugin } from "bun";
 import { svelteMapCache } from "../../svelteCompiler.ts";
 import { lineColFromOffset } from "../../sourceLoc.ts";
 
-const VIRTUAL_NS = "bosia-inspector-css";
-
 type AnyNode = {
 	type?: string;
 	name?: string;
@@ -124,7 +122,6 @@ const fnv = (s: string): string => {
 export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPlugin {
 	const { cwd, target, dev } = opts;
 	const generate: "client" | "server" = target === "browser" ? "client" : "server";
-	const virtualCss = new Map<string, string>();
 
 	return {
 		name: "bosia-inspector",
@@ -139,7 +136,11 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 					generate,
 					dev,
 					hmr: dev,
-					css: "external",
+					// Mirror the prod compiler (svelteCompiler.ts): client injects scoped
+					// CSS into the JS via `append_styles`, server discards it. No CSS
+					// chunks means Bun's `splitting:true` output-path collisions can't
+					// arise, so no runtime-injection workaround is needed.
+					css: generate === "client" ? "injected" : "external",
 					preserveWhitespace: dev,
 					preserveComments: dev,
 					cssHash: ({ css }) => `svelte-${fnv(css)}`,
@@ -164,39 +165,9 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 					svelteMapCache.set(args.path, m);
 				}
 
-				let js = dev ? fixBindShadow(result.js.code) : result.js.code;
-				// Inject component <style> blocks via runtime JS, not CSS chunks.
-				// Bun's `splitting: true` names CSS chunks after the importing JS
-				// chunk's `[name]`, not the virtual module's uid — so when several
-				// routes (e.g. multiple `+page.svelte`) transitively import the same
-				// styled component, each route emits its own CSS sidecar named
-				// `+page-<contentHash>.css`. Identical content → identical hash →
-				// "Multiple files share the same output path". Runtime injection
-				// avoids CSS chunking entirely.
-				if (result.css?.code?.trim() && generate !== "server") {
-					const safeBase = basename(args.path).replace(/\./g, "_");
-					const uid = `${safeBase}-${fnv(args.path)}-style.css`;
-					const virtualName = `${VIRTUAL_NS}:${uid}`;
-					virtualCss.set(virtualName, result.css.code);
-					js += `\nimport ${JSON.stringify(virtualName)};`;
-				}
-
+				const js = dev ? fixBindShadow(result.js.code) : result.js.code;
 				return { contents: js, loader: "ts" };
 			});
-
-			build.onResolve({ filter: new RegExp(`^${VIRTUAL_NS}:`) }, (args) => ({
-				path: args.path,
-				namespace: VIRTUAL_NS,
-			}));
-
-			build.onLoad({ filter: /.*/, namespace: VIRTUAL_NS }, (args) => {
-				const css = virtualCss.get(args.path) ?? "";
-				virtualCss.delete(args.path);
-				const contents = css
-					? `(()=>{const s=document.createElement('style');s.textContent=${JSON.stringify(css)};document.head.appendChild(s);})();`
-					: "";
-				return { contents, loader: "js" };
-			});
 		},
 	};
 }

package/src/core/prerender.ts

@@ -300,8 +300,9 @@ export function generateStaticSite(): void {
 
 	// Mirror `public/` → `dist/static/` on every build (not only SSG builds) so
 	// production containers can ship dist/ alone. Without this, apps with zero
-	// prerendered routes (pure SSR) would lose bosia-tw.css and favicons when
-	// public/ is dropped from the image.
+	// prerendered routes (pure SSR) would lose favicons and other public assets
+	// when public/ is dropped from the image. (bosia-tw-<hash>.css lives in
+	// dist/client/ and is served from the client walk, no mirror needed.)
 	if (!hasPublic && !hasPrerender) {
 		console.log("\n⏭️  No public/ or prerendered pages — skipping static site output");
 		return;
@@ -310,7 +311,7 @@ export function generateStaticSite(): void {
 	console.log("\n📦 Generating static site...");
 	mkdirSync(`${OUT_DIR}/static`, { recursive: true });
 
-	// 1. Public assets (bosia-tw.css, favicon, etc.) — preserves /bosia-tw.css path
+	// 1. Public assets (favicon, etc.) — preserves absolute /... paths
 	if (hasPublic) {
 		cpSync("./public", `${OUT_DIR}/static`, { recursive: true });
 	}

package/src/core/server.ts

@@ -1141,7 +1141,10 @@ app.listen(PORT, () => {
 			`\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`,
+				`   by anything else should set \`export const cache = false\`.\n` +
+				`   Note: the runtime auto-warns only on uncovered *cookie* reads — it CANNOT\n` +
+				`   detect header-based personalisation, so custom auth headers (X-Api-Key,\n` +
+				`   X-Auth-Token, …) must be added to CACHE_KEYS by hand.\n`,
 		);
 	}
 });

package/src/core/twHash.ts

@@ -0,0 +1,18 @@
+import { readFileSync, renameSync } from "fs";
+import { join, dirname } from "path";
+
+/** Temp filename Tailwind CLI writes to before the content-hash rename. */
+export const TW_TEMP_BASENAME = ".bosia-tw.build.css";
+
+/**
+ * Content-hash the compiled Tailwind CSS and rename it to its final
+ * `bosia-tw-<hash>.css` name (matches staticManifest's HASHED_BASENAME rule,
+ * so it gets immutable caching). Returns the final basename.
+ */
+export function finalizeTailwindCss(tempPath: string): string {
+	const bytes = readFileSync(tempPath);
+	const hash = new Bun.CryptoHasher("sha256").update(bytes).digest("hex").slice(0, 10);
+	const name = `bosia-tw-${hash}.css`;
+	renameSync(tempPath, join(dirname(tempPath), name));
+	return name;
+}