bosia 0.8.3 → 0.8.5

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.5",
 	"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/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

@@ -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)");
@@ -77,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;
@@ -111,31 +123,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,12 +184,41 @@ 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);
-	if (evicted) cacheDeleteIndexOnly(evicted);
+	if (evicted) cacheDeleteIndexOnly(evicted.key, evicted.value);
 	for (const tag of entry.tags) {
 		let set = tagIndex.get(tag);
 		if (!set) {
@@ -220,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) {
@@ -247,16 +290,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 +317,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/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/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 });
 	}