bosia 0.5.12 → 0.6.0

package/package.json

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

package/src/core/cache.ts

@@ -0,0 +1,357 @@
+// ─── Server-side Response Cache ──────────────────────────
+// Skips load() + render() + compression on cache hit. Keyed by URL + identity
+// (cookies/headers from CACHE_KEYS). Invalidated by tag (LoaderDeps.keys),
+// fetch URL (LoaderDeps.urls), or exact/prefix path.
+//
+// See docs/guides/response-cache.md.
+
+import type { Cookies, LoaderDeps } from "./hooks.ts";
+import { dedupKey } from "./dedup.ts";
+
+// ─── Config ──────────────────────────────────────────────
+
+function parseCacheKeys(raw: string | undefined): string[] {
+	const value = raw?.trim();
+	if (value === undefined || value === "") {
+		return ["session", "sid", "auth", "token", "jwt", "Authorization"];
+	}
+	return value
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+function parseMaxEntries(raw: string | undefined): number {
+	if (!raw) return 500;
+	const n = parseInt(raw, 10);
+	if (!Number.isFinite(n) || n < 0) return 500;
+	return n;
+}
+
+export const CACHE_KEYS: readonly string[] = parseCacheKeys(process.env.CACHE_KEYS);
+export const CACHE_MAX_ENTRIES = parseMaxEntries(process.env.CACHE_MAX_ENTRIES);
+export const CACHE_ENABLED = CACHE_MAX_ENTRIES > 0;
+
+if (CACHE_ENABLED) {
+	console.log(
+		`💾 Response cache: max ${CACHE_MAX_ENTRIES} entries, identity keys [${CACHE_KEYS.join(", ")}]`,
+	);
+} else {
+	console.log("💾 Response cache: disabled (CACHE_MAX_ENTRIES=0)");
+}
+
+// ─── Entry shape ─────────────────────────────────────────
+
+type Bytes = Uint8Array<ArrayBuffer>;
+
+export type CacheEntry = {
+	raw: Bytes;
+	gzip: Bytes | null;
+	brotli: Bytes | null;
+	contentType: string;
+	status: number;
+	extraHeaders: Record<string, string>;
+	tags: string[];
+};
+
+// ─── Tiny LRU ────────────────────────────────────────────
+// Uses Map's insertion-order iteration. get() promotes by re-inserting.
+
+class LRU<K, V> {
+	private map = new Map<K, V>();
+	constructor(private cap: number) {}
+	get(key: K): V | undefined {
+		const v = this.map.get(key);
+		if (v === undefined) return undefined;
+		this.map.delete(key);
+		this.map.set(key, v);
+		return v;
+	}
+	set(key: K, value: V): K | 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) {
+				this.map.delete(oldest);
+				return oldest;
+			}
+		}
+		return undefined;
+	}
+	delete(key: K): boolean {
+		return this.map.delete(key);
+	}
+	keys(): IterableIterator<K> {
+		return this.map.keys();
+	}
+	clear(): void {
+		this.map.clear();
+	}
+	get size(): number {
+		return this.map.size;
+	}
+}
+
+// ─── Storage ─────────────────────────────────────────────
+
+const htmlCache = new LRU<string, CacheEntry>(CACHE_MAX_ENTRIES || 1);
+const tagIndex = new Map<string, Set<string>>();
+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);
+}
+
+export function computeIdentityHash(req: Request, cookies: Cookies): string {
+	const headers = req.headers;
+	const parts: string[] = [];
+	for (const name of CACHE_KEYS) {
+		const cv = cookies.get(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("&"));
+}
+
+export function computeCacheKey(url: URL, req: Request, cookies: Cookies): string {
+	return `${dedupKey(url)}|i=${computeIdentityHash(req, cookies)}`;
+}
+
+/** Extract pathname portion of a cacheKey for path-based invalidation. */
+function pathOfKey(key: string): string {
+	const qIdx = key.indexOf("?");
+	const pIdx = key.indexOf("|");
+	const end = qIdx === -1 ? pIdx : Math.min(qIdx, pIdx);
+	return end === -1 ? key : key.slice(0, end);
+}
+
+// ─── Tag collection ──────────────────────────────────────
+
+export function collectTags(
+	layoutDeps: (LoaderDeps | null)[] | null,
+	pageDeps: LoaderDeps | null,
+): string[] {
+	const tags = new Set<string>();
+	if (layoutDeps) {
+		for (const deps of layoutDeps) {
+			if (!deps) continue;
+			for (const k of deps.keys) tags.add(`k:${k}`);
+			for (const u of deps.urls) tags.add(`u:${u}`);
+		}
+	}
+	if (pageDeps) {
+		for (const k of pageDeps.keys) tags.add(`k:${k}`);
+		for (const u of pageDeps.urls) tags.add(`u:${u}`);
+	}
+	return [...tags];
+}
+
+// ─── Public-ish: read / write ────────────────────────────
+
+export function cacheGet(key: string): CacheEntry | undefined {
+	if (!CACHE_ENABLED) return undefined;
+	return htmlCache.get(key);
+}
+
+export function cacheSet(key: string, entry: CacheEntry): void {
+	if (!CACHE_ENABLED) return;
+	// Drop any existing entry's index pointers first
+	cacheDeleteKey(key);
+	const evicted = htmlCache.set(key, entry);
+	if (evicted) cacheDeleteIndexOnly(evicted);
+	for (const tag of entry.tags) {
+		let set = tagIndex.get(tag);
+		if (!set) {
+			set = new Set();
+			tagIndex.set(tag, set);
+		}
+		set.add(key);
+	}
+	const path = pathOfKey(key);
+	let pset = pathIndex.get(path);
+	if (!pset) {
+		pset = new Set();
+		pathIndex.set(path, pset);
+	}
+	pset.add(key);
+}
+
+/** Remove a key from htmlCache AND its index pointers. */
+function cacheDeleteKey(key: string): void {
+	const entry = htmlCache.get(key);
+	if (entry) {
+		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) {
+		pset.delete(key);
+		if (pset.size === 0) pathIndex.delete(path);
+	}
+	htmlCache.delete(key);
+}
+
+/** 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);
+	const path = pathOfKey(key);
+	const pset = pathIndex.get(path);
+	if (pset) {
+		pset.delete(key);
+		if (pset.size === 0) pathIndex.delete(path);
+	}
+}
+
+// ─── Compression helpers ─────────────────────────────────
+
+/** Build gzip + brotli copies of body. Sync, runs in microtask. */
+export function buildCompressedVariants(body: Bytes): {
+	gzip: Bytes | null;
+	brotli: Bytes | null;
+} {
+	const COMPRESS_MIN_BYTES = 2048;
+	if (body.length < COMPRESS_MIN_BYTES) return { gzip: null, brotli: null };
+	let gzip: Bytes | null = null;
+	let brotli: Bytes | null = null;
+	try {
+		gzip = Bun.gzipSync(body) as 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;
+		}
+	}
+	return { gzip, brotli };
+}
+
+/** Concatenate multiple Uint8Array chunks into one buffer. */
+export function concatChunks(chunks: Uint8Array[]): Bytes {
+	let total = 0;
+	for (const c of chunks) total += c.length;
+	const out = new Uint8Array(new ArrayBuffer(total));
+	let off = 0;
+	for (const c of chunks) {
+		out.set(c, off);
+		off += c.length;
+	}
+	return out;
+}
+
+// ─── Serve a cache hit ───────────────────────────────────
+
+export function serveCached(entry: CacheEntry, req: Request): Response {
+	const accept = req.headers.get("accept-encoding") ?? "";
+	const headers: Record<string, string> = {
+		"Content-Type": entry.contentType,
+		Vary: "Accept-Encoding",
+		"X-Bosia-Cache": "HIT",
+		...entry.extraHeaders,
+	};
+	if (entry.brotli && accept.includes("br")) {
+		headers["Content-Encoding"] = "br";
+		return new Response(entry.brotli, { status: entry.status, headers });
+	}
+	if (entry.gzip && accept.includes("gzip")) {
+		headers["Content-Encoding"] = "gzip";
+		return new Response(entry.gzip, { status: entry.status, headers });
+	}
+	return new Response(entry.raw, { status: entry.status, headers });
+}
+
+// ─── Invalidation API ────────────────────────────────────
+
+/**
+ * Evict all cache entries matching `key`.
+ *
+ * - `invalidate("app:user")` → evict entries tagged with depends("app:user")
+ *   (matches the loader's tag list).
+ * - `invalidate("/api/posts")` → evict entries tagged with a fetch URL whose
+ *   path equals `/api/posts`, AND entries whose own path equals `/api/posts`.
+ */
+export function invalidate(key: string): number {
+	if (!CACHE_ENABLED) return 0;
+	let count = 0;
+	const tagKey = key.startsWith("/") ? `u:${key}` : `k:${key}`;
+	const fromTag = tagIndex.get(tagKey);
+	if (fromTag) {
+		// Also collect URL tag matches where the loader fetched an absolute URL
+		// whose pathname == key. Conservative: also match the bare `k:` tag in
+		// case the user uses a key that starts with `/` but isn't a URL.
+		for (const k of [...fromTag]) {
+			cacheDeleteKey(k);
+			count++;
+		}
+	}
+	if (key.startsWith("/")) {
+		// Match absolute URL tags too: any `u:<origin><key>` recorded by trackedFetch.
+		for (const [tag, set] of tagIndex) {
+			if (tag.startsWith("u:") && tag.endsWith(key)) {
+				for (const k of [...set]) {
+					cacheDeleteKey(k);
+					count++;
+				}
+			}
+		}
+		// Match cache entries whose own path equals key
+		const pset = pathIndex.get(key);
+		if (pset) {
+			for (const k of [...pset]) {
+				cacheDeleteKey(k);
+				count++;
+			}
+		}
+	}
+	return count;
+}
+
+/**
+ * Evict every entry whose path starts with `prefix`.
+ * Use for bulk eviction (e.g. `invalidateAll("/products/")`).
+ */
+export function invalidateAll(prefix: string): number {
+	if (!CACHE_ENABLED) return 0;
+	let count = 0;
+	for (const [path, set] of [...pathIndex]) {
+		if (path.startsWith(prefix)) {
+			for (const k of [...set]) {
+				cacheDeleteKey(k);
+				count++;
+			}
+		}
+	}
+	return count;
+}
+
+/** Test-only: clear everything. */
+export function cacheClear(): void {
+	htmlCache.clear();
+	tagIndex.clear();
+	pathIndex.clear();
+}

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

@@ -66,18 +66,40 @@ function injectLocs(source: string, relPath: string): string {
 	if (!ast.fragment) return source;
 
 	const ms = new MagicString(source);
+	const safeAttr = relPath.replace(/"/g, """);
+	// HTML comment data cannot contain `--`; neutralise defensively. (Almost no
+	// real path contains it, but a stray `--foo` directory shouldn't break parsing.)
+	const safeComment = relPath.replace(/--/g, "__");
 	walk(ast.fragment, (node) => {
-		if (node.type !== "RegularElement") return;
-		const name = node.name ?? "";
-		if (!name) return;
-		if (name === "script" || name === "style") return;
-		if (/^[A-Z]/.test(name)) return;
-		if (name.includes(":")) return;
-		if (typeof node.start !== "number") return;
-		const insertAt = node.start + 1 + name.length;
-		const { line, col } = lineColFromOffset(source, node.start);
-		const safe = relPath.replace(/"/g, """);
-		ms.appendLeft(insertAt, ` data-bosia-loc="${safe}:${line}:${col}"`);
+		if (node.type === "RegularElement") {
+			const name = node.name ?? "";
+			if (!name) return;
+			if (name === "script" || name === "style") return;
+			if (/^[A-Z]/.test(name)) return;
+			if (name.includes(":")) return;
+			if (typeof node.start !== "number") return;
+			const insertAt = node.start + 1 + name.length;
+			const { line, col } = lineColFromOffset(source, node.start);
+			ms.appendLeft(insertAt, ` data-bosia-loc="${safeAttr}:${line}:${col}"`);
+			return;
+		}
+		// Bracket component invocations with HTML comments so the runtime can
+		// walk DOM siblings to reconstruct the call-site chain (Page → Layout →
+		// Button). Without this the per-element `data-bosia-loc` only points at
+		// the component's *definition* file, which is misleading when the user
+		// (or an AI agent) wants to edit the page that rendered it. Comments
+		// survive into the rendered DOM because `preserveComments: dev` is set
+		// on the compile call below.
+		if (
+			node.type === "Component" ||
+			node.type === "SvelteComponent" ||
+			node.type === "SvelteSelf"
+		) {
+			if (typeof node.start !== "number" || typeof node.end !== "number") return;
+			const { line, col } = lineColFromOffset(source, node.start);
+			ms.appendLeft(node.start, `<!--bosia:o=${safeComment}:${line}:${col}-->`);
+			ms.appendRight(node.end, `<!--bosia:c-->`);
+		}
 	});
 	return ms.toString();
 }

package/src/core/plugins/inspector/overlay.ts

@@ -26,7 +26,7 @@ function ensureOutline(){
   outline.style.cssText="position:fixed;pointer-events:none;border:2px solid #f73b27;background:rgba(247,59,39,.08);z-index:2147483646;border-radius:2px;transition:all .05s linear;display:none";
   document.body.appendChild(outline);
   tip=document.createElement("div");
-  tip.style.cssText="position:fixed;pointer-events:none;background:#111;color:#fff;font:11px/1.4 ui-monospace,monospace;padding:3px 6px;border-radius:3px;z-index:2147483647;display:none;white-space:nowrap";
+  tip.style.cssText="position:fixed;pointer-events:none;background:#111;color:#fff;font:11px/1.4 ui-monospace,monospace;padding:3px 6px;border-radius:3px;z-index:2147483647;display:none;white-space:nowrap;max-width:90vw;overflow:hidden;text-overflow:ellipsis";
   document.body.appendChild(tip);
 }
 function hideOutline(){if(outline)outline.style.display="none";if(tip)tip.style.display="none"}
@@ -43,6 +43,38 @@ function showOutline(el,loc){
 function parseLoc(s){var m=/^(.+):(\\d+):(\\d+)$/.exec(s);if(!m)return null;return{file:m[1],line:+m[2],col:+m[3]}}
 function findTarget(e){var n=e.target;while(n&&n.nodeType===1){if(n.hasAttribute&&n.hasAttribute("data-bosia-loc"))return n;n=n.parentNode}return null}
 
+// Walk DOM ancestors collecting <Component> call-site markers (<!--bosia:o=…-->
+// / <!--bosia:c-->) into an outermost-first array. At each ancestor we scan
+// previous siblings tracking a depth counter so an earlier sibling component's
+// open marker doesn't get attributed to a later sibling's element.
+function collectStack(el){
+  var stack=[],cur=el;
+  while(cur){
+    var depth=0,sib=cur.previousSibling;
+    while(sib){
+      if(sib.nodeType===8){
+        var v=sib.nodeValue||"";
+        if(v==="bosia:c") depth++;
+        else if(v.lastIndexOf("bosia:o=",0)===0){
+          if(depth>0) depth--;
+          else stack.push(v.slice(8));
+        }
+      }
+      sib=sib.previousSibling;
+    }
+    var p=cur.parentNode;
+    if(!p||p.nodeType!==1) break;
+    cur=p;
+  }
+  return stack.reverse();
+}
+function chainString(el){
+  var stack=collectStack(el);
+  var leaf=el.getAttribute("data-bosia-loc")||"";
+  if(!stack.length) return leaf;
+  return stack.concat(leaf).join(" → ");
+}
+
 function toast(msg,err){
   var t=document.createElement("div");
   t.textContent=msg;
@@ -62,10 +94,12 @@ function send(payload,onOk,onErr){
 function closeForm(){if(form){form.remove();form=null}}
 function openForm(loc,el){
   closeForm();
+  var chain=chainString(el);
   var r=el.getBoundingClientRect();
   form=document.createElement("div");
   form.style.cssText="position:fixed;left:"+r.left+"px;top:"+(r.bottom+6)+"px;background:#fff;color:#111;border:1px solid #d4d4d8;border-radius:8px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:10px;width:340px;z-index:2147483647;font:13px ui-sans-serif,system-ui,sans-serif";
-  form.innerHTML='<div style="font-size:11px;color:#71717a;margin-bottom:6px;font-family:ui-monospace,monospace">'+loc.file+":"+loc.line+'</div>'+
+  var header='<div style="font-size:11px;color:#71717a;margin-bottom:6px;font-family:ui-monospace,monospace;word-break:break-all">'+chain+'</div>';
+  form.innerHTML=header+
     '<textarea placeholder="Describe a fix (Enter to send, Esc to cancel, empty = open in editor)" style="width:100%;min-height:64px;border:1px solid #e4e4e7;border-radius:4px;padding:6px;font:13px ui-sans-serif,system-ui,sans-serif;resize:vertical;box-sizing:border-box;outline:none"></textarea>'+
     '<div style="margin-top:8px;display:flex;gap:6px;justify-content:flex-end">'+
     '<button data-cancel style="padding:4px 10px;border:1px solid #e4e4e7;background:#fff;border-radius:4px;cursor:pointer;font-size:12px">Cancel</button>'+
@@ -75,9 +109,12 @@ function openForm(loc,el){
   var ta=form.querySelector("textarea");
   ta.focus();
   function submit(){
-    var comment=ta.value.trim();
+    var userComment=ta.value.trim();
     var payload={file:loc.file,line:loc.line,col:loc.col};
-    if(comment)payload.comment=comment;
+    if(userComment){
+      var tree=chain.indexOf(" → ")>=0?("Component tree (outer → leaf): "+chain+"\\n\\n"):"";
+      payload.comment=tree+userComment;
+    }
     send(payload,function(j){toast(j.mode==="ai"?"sent to AI":"opened "+loc.file+":"+loc.line)});
     closeForm();
   }
@@ -100,7 +137,7 @@ window.addEventListener("mousemove",function(e){
   if(!altDown||form){hideOutline();return}
   var el=findTarget(e);
   if(!el){hideOutline();return}
-  showOutline(el,el.getAttribute("data-bosia-loc"));
+  showOutline(el,chainString(el));
 },true);
 
 window.addEventListener("click",function(e){
@@ -137,7 +174,7 @@ if(ERR_ENABLED){
     var t=e.target;
     if(!t||!t.closest)return;
     var el=t.closest("[data-bosia-loc]");
-    if(el)lastInteraction=el.getAttribute("data-bosia-loc");
+    if(el)lastInteraction=chainString(el);
   }
   window.addEventListener("mousedown",trackInteraction,true);
   window.addEventListener("keydown",trackInteraction,true);

package/src/core/renderer.ts

@@ -5,6 +5,16 @@ import { serverRoutes, errorPage } from "bosia:routes";
 import type { RouteMatch } from "./types.ts";
 import type { Cookies, LoaderDeps } from "./hooks.ts";
 import { CSP_ENABLED } from "./csp.ts";
+import {
+	CACHE_ENABLED,
+	buildCompressedVariants,
+	cacheGet,
+	cacheSet,
+	collectTags,
+	computeCacheKey,
+	concatChunks,
+	serveCached,
+} from "./cache.ts";
 import { HttpError, Redirect } from "./errors.ts";
 import { pickErrorPage, type ErrorOrigin } from "./errorMatch.ts";
 import App from "./client/App.svelte";
@@ -503,6 +513,28 @@ export async function renderSSRStream(
 	const { route, params } = match;
 	const nonce = CSP_ENABLED && typeof locals.nonce === "string" ? locals.nonce : undefined;
 
+	// ── Response cache: short-circuit on hit ──
+	// Look up cached HTML before doing anything expensive (metadata, load,
+	// render, compress). Key includes URL + identity hash (cookies/headers
+	// from CACHE_KEYS), so per-user pages stay isolated. Routes opt out via
+	// `export const cache = false`. See cache.ts and docs/guides/response-cache.md.
+	const pageMod: any = await route.pageModule();
+	const cacheBypass = url.searchParams.has("_invalidated");
+	// CSP is incompatible with response cache — the per-request nonce is baked
+	// into the cached HTML but the CSP header is re-derived each request, so a
+	// cached page would ship with a dead nonce and the browser would block its
+	// inline scripts. Operators who turn on CSP_DIRECTIVES forfeit the cache.
+	const cacheable =
+		CACHE_ENABLED && !CSP_ENABLED && pageMod.cache !== false && req.method === "GET";
+	let cacheKey: string | null = null;
+	if (cacheable) {
+		cacheKey = computeCacheKey(url, req, cookies);
+		if (!cacheBypass) {
+			const hit = cacheGet(cacheKey);
+			if (hit) return serveCached(hit, req);
+		}
+	}
+
 	// ── 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;
@@ -535,13 +567,11 @@ export async function renderSSRStream(
 	// 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 pageMod: any;
 	let layoutMods: any[];
 
 	try {
-		[data, pageMod, layoutMods] = await Promise.all([
+		[data, layoutMods] = await Promise.all([
 			loadRouteData(url, locals, req, cookies, metadataData, match),
-			route.pageModule(),
 			Promise.all(route.layoutModules.map((l: () => Promise<any>) => l())),
 		]);
 	} catch (err) {
@@ -692,6 +722,28 @@ export async function renderSSRStream(
 		),
 	];
 
+	// ── 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 = () => {

package/src/core/routeTypes.ts

@@ -84,6 +84,10 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		lines.push(``);
 		lines.push(`export type Params = ${paramsType};`);
 		lines.push(``);
+		lines.push(`/** Set \`export const cache: CacheOption = false;\` in +page(.server).ts`);
+		lines.push(` *  or +server.ts to opt the route out of the server response cache. */`);
+		lines.push(`export type CacheOption = false;`);
+		lines.push(``);
 		lines.push(`type _LoadEvent = Omit<LoadEvent, 'params'> & { params: Params };`);
 		lines.push(`type _MetadataEvent = Omit<MetadataEvent, 'params'> & { params: Params };`);
 		lines.push(`type _RequestEvent = Omit<RequestEvent, 'params'> & { params: Params };`);

package/src/core/server.ts

@@ -25,6 +25,14 @@ import { isDev, compress, isStaticPath } from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
 import { dedup, dedupKey } from "./dedup.ts";
+import {
+	CACHE_ENABLED,
+	buildCompressedVariants,
+	cacheGet,
+	cacheSet,
+	computeCacheKey,
+	serveCached,
+} from "./cache.ts";
 import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import {
 	loadRouteData,
@@ -56,6 +64,27 @@ if (existsSync(hooksPath)) {
 
 // ─── Env Helpers ─────────────────────────────────────────
 
+// Headers that must not be baked into a cache entry. Content-Length is
+// recomputed by Bun, content-encoding/transfer-encoding depend on the chosen
+// variant, and security/CORS/Set-Cookie headers are applied by handleRequest.
+const NON_CACHEABLE_HEADERS = new Set([
+	"content-length",
+	"content-encoding",
+	"transfer-encoding",
+	"content-type",
+	"set-cookie",
+	"vary",
+	"x-bosia-cache",
+]);
+
+function captureCacheableHeaders(headers: Headers): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [k, v] of headers) {
+		if (!NON_CACHEABLE_HEADERS.has(k.toLowerCase())) out[k] = v;
+	}
+	return out;
+}
+
 function splitCsvEnv(key: string): string[] | undefined {
 	return (
 		process.env[key]
@@ -379,7 +408,63 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			}
 
 			event.params = apiMatch.params;
-			return await handler({ request, params: apiMatch.params, url, locals, cookies });
+
+			// ── Response cache for +server.ts GET handlers ──
+			// CSP is skipped because cached responses would ship with a stale
+			// nonce (see renderer.ts for the same gate). The cache key includes
+			// URL + identity so per-user responses stay isolated.
+			const apiCacheable =
+				CACHE_ENABLED && !CSP_ENABLED && (mod as any).cache !== false && method === "GET";
+			let apiCacheKey: string | null = null;
+			if (apiCacheable) {
+				apiCacheKey = computeCacheKey(url, request, cookies);
+				if (!url.searchParams.has("_invalidated")) {
+					const hit = cacheGet(apiCacheKey);
+					if (hit) return serveCached(hit, request);
+				}
+			}
+
+			const response = await handler({
+				request,
+				params: apiMatch.params,
+				url,
+				locals,
+				cookies,
+			});
+
+			if (
+				apiCacheable &&
+				apiCacheKey &&
+				response.status === 200 &&
+				(cookies as CookieJar).outgoing.length === 0
+			) {
+				const cloned = response.clone();
+				const extraHeaders = captureCacheableHeaders(response.headers);
+				const contentType =
+					response.headers.get("content-type") ?? "application/octet-stream";
+				const keyForWrite = apiCacheKey;
+				queueMicrotask(async () => {
+					try {
+						const buf = new Uint8Array(await cloned.arrayBuffer());
+						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: [],
+						});
+					} catch {
+						/* drop silently — cache population is best-effort */
+					}
+				});
+			}
+
+			return response;
 		} catch (err) {
 			if (isDev) console.error("API route error:", err);
 			else console.error("API route error:", (err as Error).message ?? err);
@@ -630,6 +715,16 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		});
 	}
 
+	// Shed load above MAX_INFLIGHT. Checked before any work so the 503 is
+	// cheap. /_health stays available so the orchestrator can still tell the
+	// process is alive (and decide whether to restart or scale out).
+	if (inFlight >= MAX_INFLIGHT && url.pathname !== "/_health") {
+		return new Response("Service Unavailable", {
+			status: 503,
+			headers: { "Retry-After": "1" },
+		});
+	}
+
 	inFlight++;
 	try {
 		// Handle CORS preflight before CSRF check (OPTIONS is CSRF-exempt)
@@ -762,6 +857,29 @@ const IDLE_TIMEOUT = parseIdleTimeout(process.env.IDLE_TIMEOUT);
 
 console.log(`⏱  Idle timeout: ${IDLE_TIMEOUT}s`);
 
+// ─── Concurrency Ceiling ──────────────────────────────────
+// Soft cap on in-flight requests, parsed from MAX_INFLIGHT env var.
+// Default is unlimited so existing apps see no behavior change. When set,
+// requests above the cap get a fast 503 + Retry-After before any work is
+// done — protects single-replica container deploys from OOM under spike
+// traffic. /_health is exempt so orchestrator liveness probes still work
+// while the app sheds load.
+
+function parseMaxInflight(value?: string): number {
+	if (!value) return Infinity;
+	const trimmed = value.trim();
+	if (trimmed === "" || trimmed.toLowerCase() === "infinity") return Infinity;
+	const n = parseInt(trimmed, 10);
+	if (!Number.isFinite(n) || n <= 0) throw new Error(`Invalid MAX_INFLIGHT: "${value}"`);
+	return n;
+}
+
+const MAX_INFLIGHT = parseMaxInflight(process.env.MAX_INFLIGHT);
+
+if (Number.isFinite(MAX_INFLIGHT)) {
+	console.log(`🚦 Max in-flight requests: ${MAX_INFLIGHT}`);
+}
+
 // ─── Graceful Shutdown State ──────────────────────────────
 
 let shuttingDown = false;
@@ -909,4 +1027,22 @@ async function shutdown() {
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);
 
+// Prod-only fatal handlers. The dev inspector plugin installs its own
+// uncaughtException/unhandledRejection listeners that route errors into the
+// overlay and let the dev runner's crash-backoff restart the process. In prod
+// there's no inspector — without these handlers an unhandled rejection from a
+// background timer or plugin hook orphans the process with no log context.
+// Log + exit(1) lets the orchestrator (Podman/k8s) restart cleanly.
+if (!isDev) {
+	process.on("uncaughtException", (err: Error) => {
+		console.error("[FATAL] uncaughtException:", err?.stack ?? err);
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason: unknown) => {
+		const e = reason as Error | undefined;
+		console.error("[FATAL] unhandledRejection:", e?.stack ?? reason);
+		process.exit(1);
+	});
+}
+
 export { app };

package/src/lib/index.ts

@@ -6,6 +6,7 @@
 export { cn, getServerTime } from "./utils.ts";
 export { sequence } from "../core/hooks.ts";
 export { error, redirect, fail } from "../core/errors.ts";
+export { invalidate, invalidateAll } from "../core/cache.ts";
 export type { HttpError, Redirect, RedirectOptions, ActionFailure } from "../core/errors.ts";
 export type {
 	RequestEvent,

package/templates/default/.env.example

@@ -14,7 +14,7 @@
 # Import in your code:
 #   import { PUBLIC_STATIC_APP_NAME, DB_PASSWORD } from '$env';
 #
-# Framework vars (PORT, NODE_ENV, BODY_SIZE_LIMIT, CSRF_ALLOWED_ORIGINS,
+# Framework vars (PORT, NODE_ENV, BODY_SIZE_LIMIT, MAX_INFLIGHT, CSRF_ALLOWED_ORIGINS,
 # CORS_*, LOAD_TIMEOUT, METADATA_TIMEOUT, PRERENDER_TIMEOUT) are NOT exposed via $env —
 # access them via process.env directly.
 # ────────────────────────────────────────────────────────────────────────────────
@@ -30,6 +30,25 @@ PUBLIC_STATIC_APP_NAME=My Bosia App
 # Maximum request body size. Supports K/M/G suffixes or "Infinity". Defaults to 512K.
 # BODY_SIZE_LIMIT=512K
 
+# Soft cap on concurrent in-flight requests. Requests above the cap get a fast
+# 503 + Retry-After before any work is done — protects single-replica container
+# deploys from OOM under traffic spikes. Defaults to Infinity (no cap).
+# /_health is exempt so orchestrator liveness probes keep working under load.
+# MAX_INFLIGHT=500
+
+# Server response cache (skip-render). Caches HTML SSR pages and +server.ts GET
+# handlers in-memory, keyed by URL + identity (cookies/headers from CACHE_KEYS).
+# Per-user pages stay isolated. Disable per-route with `export const cache = false`.
+# See guides/response-cache for details.
+#
+# Identity keys: cookies AND headers with any of these names contribute to the
+# cache key, so logged-in users never see each other's pages. Default covers
+# common session cookie/header names. Leave blank to use the default.
+# CACHE_KEYS=session,sid,auth,token,jwt,Authorization
+#
+# Max cache entries (LRU). Set to 0 to disable the cache entirely. Defaults to 500.
+# CACHE_MAX_ENTRIES=500
+
 # Timeout for load() functions (layout + page) in milliseconds. Defaults to 5000 (5s).
 # Set to 0 or Infinity to disable.
 # LOAD_TIMEOUT=5000

package/templates/demo/.env.example

@@ -4,6 +4,18 @@ PORT=9000
 # Maximum request body size. Supports K/M/G suffixes or "Infinity". Defaults to 512K.
 BODY_SIZE_LIMIT=512K
 
+# Soft cap on concurrent in-flight requests. Requests above the cap get a fast
+# 503 + Retry-After before any work is done — protects single-replica container
+# deploys from OOM under traffic spikes. Defaults to Infinity (no cap).
+# /_health is exempt so orchestrator liveness probes keep working under load.
+# MAX_INFLIGHT=500
+
+# Server response cache (skip-render). Caches HTML SSR pages and +server.ts GET
+# handlers in-memory, keyed by URL + identity (cookies/headers from CACHE_KEYS).
+# Per-user pages stay isolated. Disable per-route with `export const cache = false`.
+# CACHE_KEYS=session,sid,auth,token,jwt,Authorization
+# CACHE_MAX_ENTRIES=500
+
 # Comma-separated list of allowed CORS origins for CSRF validation.
 # Leave unset to allow same-origin requests only.
 # Example: https://app.example.com, https://admin.example.com