bosia 1.1.3 → 1.1.5

package/src/core/cache.ts

@@ -12,6 +12,7 @@ import type { Cookies, LoaderDeps } from "./hooks.ts";
 import type { CookieJar } from "./cookies.ts";
 import { dedupKey } from "./dedup.ts";
 import { compressionOn, encodeBytes, PRECOMPRESSED } from "./html.ts";
+import { matchesEtag } from "./etag.ts";
 
 // ─── Config ──────────────────────────────────────────────
 
@@ -76,6 +77,9 @@ export type CacheEntry = {
 	status: number;
 	extraHeaders: Record<string, string>;
 	tags: string[];
+	/** Digest of `raw`, filled in by `cacheSet`; the ETag is built from it per
+	 *  encoding so a gzip and a brotli copy are never mistaken for each other. */
+	etag?: string;
 };
 
 // ─── Tiny LRU ────────────────────────────────────────────
@@ -218,6 +222,8 @@ export function cacheSet(key: string, entry: CacheEntry, cookies?: Cookies): voi
 	if (!CACHE_ENABLED) return;
 	if (CACHE_MAX_BODY_BYTES > 0 && entry.raw.length > CACHE_MAX_BODY_BYTES) return;
 	if (cookies) warnUncoveredCookies(cookies);
+	// Runs in the deferred write, after the response went out — never on a hit.
+	entry.etag ??= createHash("sha1").update(entry.raw).digest("base64url").slice(0, 22);
 	// Drop any existing entry's index pointers first
 	cacheDeleteKey(key);
 	const evicted = htmlCache.set(key, entry);
@@ -279,26 +285,35 @@ function cacheDeleteIndexOnly(key: string, entry: CacheEntry): void {
 
 // ─── Compression helpers ─────────────────────────────────
 
-/** Build gzip + brotli copies of body. Sync — call it from `deferCacheWrite`. */
-export function buildCompressedVariants(body: Bytes): {
+/**
+ * Build gzip + brotli copies of body. Sync — call it from `deferCacheWrite`.
+ * `prebuilt`: a variant already encoded for the response (at cache quality),
+ * reused as-is so a miss compresses each encoding once.
+ */
+export function buildCompressedVariants(
+	body: Bytes,
+	prebuilt: { gzip?: Bytes; brotli?: Bytes } = {},
+): {
 	gzip: Bytes | null;
 	brotli: Bytes | null;
 } {
 	const COMPRESS_MIN_BYTES = 2048;
 	if (!compressionOn || body.length < COMPRESS_MIN_BYTES) return { gzip: null, brotli: null };
-	let gzip: Bytes | null = null;
-	let brotli: Bytes | null = null;
-	try {
-		gzip = encodeBytes(body, "gzip");
-	} catch {
-		gzip = null;
+	let gzip: Bytes | null = prebuilt.gzip ?? null;
+	let brotli: Bytes | null = prebuilt.brotli ?? null;
+	if (!gzip) {
+		try {
+			gzip = encodeBytes(body, "gzip", "cache");
+		} catch {
+			gzip = null;
+		}
 	}
-	try {
-		// Quality 5 (set in encodeBytes): ~20x faster than the default 11, still
-		// beats gzip on size. 11 would block the event loop ~17ms/500KB.
-		brotli = encodeBytes(body, "br");
-	} catch {
-		brotli = null;
+	if (!brotli) {
+		try {
+			brotli = encodeBytes(body, "br", "cache");
+		} catch {
+			brotli = null;
+		}
 	}
 	return { gzip, brotli };
 }
@@ -309,9 +324,6 @@ export function buildCompressedVariants(body: Bytes): {
  * the body ran ahead of the first byte. `setImmediate` yields to I/O first.
  * Workers keeps the microtask — it compresses nothing (the edge does), and a
  * timer after the response returns is not guaranteed to run there.
- *
- * On a miss the variant sent to the client is compressed twice (response +
- * cache). Off the critical path; pass the built variant in if it ever shows up.
  */
 export function deferCacheWrite(fn: () => void | Promise<void>): void {
 	if (compressionOn) setImmediate(fn);
@@ -372,15 +384,31 @@ export function serveCached(entry: CacheEntry, req: Request): Response {
 		"x-bosia-cache": "HIT",
 		...entry.extraHeaders,
 	};
+	let body: Bytes = entry.raw;
+	let encoding: "br" | "gzip" | null = null;
 	if (entry.brotli && accept.includes("br")) {
-		headers["content-encoding"] = "br";
-		return new Response(entry.brotli, { ...PRECOMPRESSED, status: entry.status, headers });
+		body = entry.brotli;
+		encoding = "br";
+	} else if (entry.gzip && accept.includes("gzip")) {
+		body = entry.gzip;
+		encoding = "gzip";
+	}
+	if (entry.etag) {
+		const suffix = encoding === "br" ? "-br" : encoding === "gzip" ? "-gz" : "";
+		const etag = `"${entry.etag}${suffix}"`;
+		headers["etag"] = etag;
+		// A browser or CDN re-checking a copy it already holds gets a 304 with
+		// no body instead of the whole page again.
+		if (entry.status === 200 && matchesEtag(req.headers.get("if-none-match"), etag)) {
+			delete headers["content-type"];
+			return new Response(null, { status: 304, headers });
+		}
 	}
-	if (entry.gzip && accept.includes("gzip")) {
-		headers["content-encoding"] = "gzip";
-		return new Response(entry.gzip, { ...PRECOMPRESSED, status: entry.status, headers });
+	if (encoding) {
+		headers["content-encoding"] = encoding;
+		return new Response(body, { ...PRECOMPRESSED, status: entry.status, headers });
 	}
-	return new Response(entry.raw, { status: entry.status, headers });
+	return new Response(body, { status: entry.status, headers });
 }
 
 // ─── Invalidation API ────────────────────────────────────

package/src/core/client/App.svelte

@@ -3,13 +3,7 @@
 	import { router, scrollToHash } from "./router.svelte.ts";
 	import { findMatch } from "../matcher.ts";
 	import { clientRoutes } from "bosia:routes";
-	import {
-		consumePrefetch,
-		prefetchCache,
-		dataUrl,
-		buildParentSnapshots,
-		readDataResponse,
-	} from "./prefetch.ts";
+	import { consumePrefetch, prefetchCache, dataUrl, readDataResponse } from "./prefetch.ts";
 	import { appState, clearDirty } from "./appState.svelte.ts";
 	import { captureSnapshot, liveContext, shouldRerun, type CacheEntry } from "./loaderCache.ts";
 	import { pickErrorPage } from "../errorMatch.ts";
@@ -209,12 +203,20 @@
 		}
 
 		// Build `_invalidated=<bits>` — char 0 = page, char i+1 = layouts[i].
-		// '1' = run, '0' = skip. Always sent so the server honors cached layers.
-		// We always issue the fetch (even when all loaders skip) so page-level
-		// metadata stays fresh on every navigation; only the loaders flagged in
-		// the mask actually run server-side.
+		// '1' = send, '0' = omit (the client renders that layer from its cache;
+		// the server still runs layout loaders, which may be guards).
+		// We always issue the fetch (even when every layer is cached) so page-level
+		// metadata stays fresh on every navigation.
 		const maskBits = (pageRun ? "1" : "0") + layoutRunFlags.map((b) => (b ? "1" : "0")).join("");
 
+		// An invalidate() since the last nav — tick bump or any dirty entry —
+		// must read past the server's response cache, not just re-run loaders.
+		const fresh =
+			invalidated ||
+			appState.dirty.keys.size > 0 ||
+			appState.dirty.urls.size > 0 ||
+			appState.dirty.urlMatchers.length > 0;
+
 		// Clear dirty set now — we've baked it into the mask.
 		clearDirty();
 
@@ -222,25 +224,12 @@
 		// to avoid a flash of stale/empty data before the fetch completes.
 		const cached = match.route.hasServerData && !invalidated ? consumePrefetch(path) : null;
 		prefetchCache.clear(); // clear remaining entries on navigation — matches SvelteKit behavior
-		// Forward cached parent data for skipped layers so downstream loaders see
-		// real parent() data, not {}. POST only when there's something to carry —
-		// keeps the no-skip case a cacheable/dedupable GET.
-		// A prerendered route's data is a fixed file, so there is nothing to skip —
-		// and on Workers the asset server answers anything but GET with 405.
+		// A prerendered route's data is a fixed file, so there is nothing to omit.
 		const prerendered = match.route.prerender;
-		const snapshots = prerendered ? {} : buildParentSnapshots(path, maskBits);
-		const dataInit: RequestInit =
-			Object.keys(snapshots).length > 0
-				? {
-						method: "POST",
-						headers: { "Content-Type": "application/json" },
-						body: JSON.stringify({ parentSnapshots: snapshots }),
-					}
-				: {};
 		const dataFetch = cached
 			? Promise.resolve(cached)
 			: match.route.hasServerData
-				? fetch(dataUrl(path, prerendered ? undefined : maskBits), dataInit)
+				? fetch(dataUrl(path, prerendered ? undefined : maskBits, fresh && !prerendered))
 						.then(readDataResponse)
 						// Only a failed request reaches here now — offline, DNS, aborted.
 						// A response that arrived is read for what it says, not discarded.

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

@@ -8,8 +8,14 @@
 // App.svelte), mirroring the modern SvelteKit `$app/state` direction. Route
 // components should destructure `params` from `$props()`. `page.params` was
 // removed in 1.1.0.
+//
+// `page.route.id` is the matched route's folder path with groups kept
+// (`/(private)/dashboard/[id]`), the same id hooks and loaders get. `null` when
+// no route matches, e.g. on the 404 page.
 
 import { router } from "./router.svelte.ts";
+import { findMatch } from "../matcher.ts";
+import { clientRoutes } from "bosia:routes";
 
 class Page {
 	// Real on the server too: the renderer seeds `router.currentRoute`/`.origin`
@@ -18,12 +24,21 @@ class Page {
 	// render that seeded nothing at all — a bare unit test, never a served request.
 	#url = $derived.by(() => new URL(router.currentRoute, router.origin || "http://localhost/"));
 
+	// clientRoutes carry the BASE_PATH prefix, and so does `router.currentRoute`
+	// (the renderer puts it back before SSR), so the pathname matches as-is.
+	#route = $derived.by(() => ({
+		id: findMatch(clientRoutes, this.#url.pathname)?.route.id ?? null,
+	}));
+
 	get url() {
 		return this.#url;
 	}
 	get pathname() {
 		return this.#url.pathname;
 	}
+	get route() {
+		return this.#route;
+	}
 }
 
 export const page = new Page();

package/src/core/client/prefetch.ts

@@ -10,8 +10,9 @@ import { base } from "./base.ts";
 
 /**
  * Build the `_invalidated` mask bits for a target path using the current
- * client loader cache. Char 0 = page, char i+1 = layout depth i; '1' = run,
- * '0' = skip. Returns `null` when the route cannot be matched.
+ * client loader cache. Char 0 = page, char i+1 = layout depth i; '1' = send,
+ * '0' = the client already holds it (the server still runs layout loaders,
+ * since they may be guards). Returns `null` when the route cannot be matched.
  */
 export function buildMaskBits(path: string): string | null {
 	const url = new URL(path, window.location.origin);
@@ -42,37 +43,10 @@ export function buildMaskBits(path: string): string | null {
 }
 
 /**
- * Build `parentSnapshots` (layout depth → cached data) for a target path from
- * the current loader cache, given the mask bits from `buildMaskBits`. For each
- * layout depth whose mask bit is '0' (skipped) and whose cached entry exists,
- * forward that layer's data so server-side downstream loaders see real
- * `parent()` data instead of `{}`. Returns `{}` when nothing to carry.
- *
- * Client-supplied perf hint only — the server never trusts it for authz.
+ * Builds the `/__bosia/data/…` URL for a given client path. `fresh` marks a
+ * fetch that follows an `invalidate()`, so the server skips its cached copy.
  */
-export function buildParentSnapshots(
-	path: string,
-	maskBits: string,
-): Record<number, Record<string, any>> {
-	const snapshots: Record<number, Record<string, any>> = {};
-	const url = new URL(path, window.location.origin);
-	const match = findMatch(clientRoutes, url.pathname);
-	if (!match) return snapshots;
-	const layoutIds = (match.route as any).layoutIds as (string | null)[];
-
-	layoutIds.forEach((id, depth) => {
-		// maskBits char 0 = page, char depth+1 = layout depth. '0' = skipped.
-		if (maskBits[depth + 1] !== "0") return;
-		if (id === null) return;
-		const entry = appState.loaderCache.layouts[id];
-		if (entry) snapshots[depth] = entry.data;
-	});
-
-	return snapshots;
-}
-
-/** Builds the `/__bosia/data/…` URL for a given client path. */
-export function dataUrl(path: string, invalidatedBits?: string): string {
+export function dataUrl(path: string, invalidatedBits?: string, fresh = false): string {
 	const url = new URL(path, window.location.origin);
 	let p = url.pathname.replace(/\/$/, "");
 	let qs = url.search;
@@ -80,6 +54,7 @@ export function dataUrl(path: string, invalidatedBits?: string): string {
 		const sep = qs ? "&" : "?";
 		qs = `${qs}${sep}_invalidated=${invalidatedBits}`;
 	}
+	if (fresh) qs = `${qs}${qs ? "&" : "?"}_fresh=1`;
 	// The one place a path is still taken apart, and it is URL construction rather
 	// than navigation: the data endpoint is `<base>/__bosia/data` + the *app* path,
 	// so the mount prefix moves from the front of the route to the front of the
@@ -151,35 +126,39 @@ export function consumePrefetch(path: string): any | null {
 
 /** Prefetches data for a path and stores in cache. No-op if already cached/in-flight. */
 export async function prefetchPath(path: string): Promise<void> {
+	// Nothing to fetch for the page we're on. A click also focuses its link, so
+	// the focusin trigger fires ~100ms after the navigation it belongs to.
+	if (path === window.location.pathname + window.location.search) return;
 	// Warm the route's +loading.svelte chunk alongside its data, so the skeleton
 	// paints instantly on click instead of cold-importing after the old page lingers.
 	const warmMatch = findMatch(clientRoutes, new URL(path, window.location.origin).pathname);
-	(warmMatch?.route as { loading?: (() => Promise<unknown>) | null } | undefined)?.loading?.();
+	// Also warm the page and layout chunks: a route not visited yet otherwise
+	// downloads its code only after the click. Errors are swallowed — a stale
+	// chunk is the click's to report, not the hover's (hydrate.ts reloads on it).
+	if (warmMatch) {
+		const route = warmMatch.route as typeof warmMatch.route & {
+			loading?: (() => Promise<unknown>) | null;
+		};
+		for (const load of [route.loading, route.page, ...route.layouts]) {
+			load?.().catch(() => {});
+		}
+	}
 
 	const existing = prefetchCache.get(path);
 	if (existing && Date.now() - existing.ts <= 30_000) return;
 	if (existing) prefetchCache.delete(path);
 	if (pending.has(path)) return;
 
+	// A route without server data never fetches on click either.
+	if (!warmMatch?.route.hasServerData) return;
+
 	pending.add(path);
 	try {
-		// Send the same mask as a real client nav would so the server can skip
-		// loaders whose tracked inputs haven't changed. Falls back to running
-		// everything when the route can't be matched (e.g. external/unknown URL).
+		// Send the same mask as a real client nav would so the server leaves out
+		// layers the client already holds. Falls back to sending everything when
+		// the route can't be matched (e.g. external/unknown URL).
 		const maskBits = buildMaskBits(path) ?? undefined;
-		// Forward cached parent data for skipped layers so a prefetched response
-		// is computed with real parent() data, not {}. POST only when there's
-		// something to carry — keeps the no-skip case a cacheable/dedupable GET.
-		const snapshots = maskBits ? buildParentSnapshots(path, maskBits) : {};
-		const init: RequestInit =
-			Object.keys(snapshots).length > 0
-				? {
-						method: "POST",
-						headers: { "Content-Type": "application/json" },
-						body: JSON.stringify({ parentSnapshots: snapshots }),
-					}
-				: {};
-		const res = await fetch(dataUrl(path, maskBits), init);
+		const res = await fetch(dataUrl(path, maskBits));
 		// `ok` alone would cache a guard's login page (200 after the redirect was
 		// followed) as if it were this route's data.
 		if (res.ok && !res.redirected && isJsonResponse(res)) {
@@ -228,23 +207,39 @@ function observeViewportLinks(container: Element | Document = document) {
 	return observer;
 }
 
+/** The link a hover/touch/focus event is on, when it sits under `data-bosia-preload="hover"`. */
+function hoverLinkHref(target: EventTarget | null): string | null {
+	if (!(target instanceof Element)) return null;
+	// Early exit: skip if no [data-bosia-preload="hover"] ancestor exists
+	const preloadEl = target.closest("[data-bosia-preload]");
+	if (!preloadEl || preloadEl.getAttribute("data-bosia-preload") !== "hover") return null;
+	const anchor = target.closest("a") as HTMLAnchorElement | null;
+	return anchor ? getLinkHref(anchor) : null;
+}
+
 export function initPrefetch(): void {
-	// ── Hover strategy (event delegation, 20ms debounce) ─────
+	// ── Hover strategy (event delegation, 100ms debounce) ────
 	let hoverTimer: ReturnType<typeof setTimeout> | null = null;
 
-	document.addEventListener("mouseover", (e) => {
-		if (!(e.target instanceof Element)) return;
-		// Early exit: skip if no [data-bosia-preload="hover"] ancestor exists
-		const preloadEl = e.target.closest("[data-bosia-preload]");
-		if (!preloadEl || preloadEl.getAttribute("data-bosia-preload") !== "hover") return;
-		const anchor = e.target.closest("a") as HTMLAnchorElement | null;
-		if (!anchor) return;
-		const href = getLinkHref(anchor);
+	const onIntent = (e: Event) => {
+		const href = hoverLinkHref(e.target);
 		if (!href) return;
-
 		if (hoverTimer) clearTimeout(hoverTimer);
 		hoverTimer = setTimeout(() => prefetchPath(href), 100);
-	});
+	};
+	document.addEventListener("mouseover", onIntent);
+	// Keyboard users tab onto a link before pressing Enter — same signal.
+	document.addEventListener("focusin", onIntent);
+	// Touch screens have no hover; a touch is followed by the click within
+	// ~100ms or not at all, so start right away instead of debouncing.
+	document.addEventListener(
+		"touchstart",
+		(e) => {
+			const href = hoverLinkHref(e.target);
+			if (href) prefetchPath(href);
+		},
+		{ passive: true },
+	);
 
 	document.addEventListener("mouseout", () => {
 		if (hoverTimer) {

package/src/core/dev.ts

@@ -1,5 +1,5 @@
 import { spawn, type Subprocess } from "bun";
-import { readdirSync, statSync, watch, type Dirent } from "fs";
+import { readdirSync, rmSync, statSync, watch, type Dirent } from "fs";
 import { join } from "path";
 import { loadEnv } from "./env.ts";
 import { BOSIA_NODE_PATH } from "./paths.ts";
@@ -12,6 +12,12 @@ import { affectsRouteManifest, shouldIgnoreForRebuild } from "./devWatch.ts";
 // but dev.ts itself never reads it.
 const DEV_OUT_DIR = ".bosia/dev";
 
+// Compiled-component cache shared by every rebuild in this session (see
+// svelteCompiler.ts). Outside DEV_OUT_DIR, which each build clears. Emptied
+// here, once per `bosia dev`, so it only ever holds this session's entries.
+const SVELTE_CACHE_DIR = ".bosia/cache/svelte";
+rmSync(SVELTE_CACHE_DIR, { recursive: true, force: true });
+
 // Snapshot pure shell env BEFORE any loadEnv call pollutes process.env.
 // On `.env*` change we restore from this snapshot, then re-run loadEnv,
 // so removed/renamed keys no longer linger in the dev process.
@@ -142,6 +148,10 @@ async function runBuild(): Promise<boolean> {
 			...process.env,
 			BOSIA_OUT_DIR: DEV_OUT_DIR,
 			BOSIA_SKIP_ROUTE_SCAN: skipScan ? "1" : "0",
+			// The dev server never serves prerendered pages or dist/static, so the
+			// build skips producing them (~25% of a rebuild on the demo).
+			BOSIA_DEV_BUILD: "1",
+			BOSIA_SVELTE_CACHE_DIR: SVELTE_CACHE_DIR,
 		},
 	});
 	return (await proc.exited) === 0;

package/src/core/env.ts

@@ -3,6 +3,7 @@ import { join } from "path";
 
 // ─── Framework-reserved vars ─────────────────────────────
 // These are controlled by Bosia itself — users access them via process.env directly.
+// `test/env.test.ts` scans `src/` and fails when Bosia reads a name missing here.
 const FRAMEWORK_VARS = new Set([
 	"PORT",
 	"NODE_ENV",
@@ -20,8 +21,24 @@ const FRAMEWORK_VARS = new Set([
 	"LOAD_TIMEOUT",
 	"METADATA_TIMEOUT",
 	"PRERENDER_TIMEOUT",
+	"PRERENDER_CONCURRENCY",
+	"IDLE_TIMEOUT",
+	"MAX_INFLIGHT",
+	"TRUST_PROXY",
+	"CSP_DIRECTIVES",
+	"DISABLE_X_FRAME_OPTIONS",
+	"CACHE_KEYS",
+	"CACHE_MAX_ENTRIES",
+	"CACHE_MAX_BODY_BYTES",
+	"ASSET_CACHE_MAX_BYTES",
+	"ASSET_CACHE_MAX_FILE_BYTES",
 ]);
 
+/** Framework-owned: a listed name, or anything under the reserved `BOSIA_` prefix. */
+export function isFrameworkVar(name: string): boolean {
+	return FRAMEWORK_VARS.has(name) || name.startsWith("BOSIA_");
+}
+
 // ─── .env File Parser ────────────────────────────────────
 
 /** Valid JS/TS identifier: starts with letter/underscore, then alphanumeric/underscore. */
@@ -173,7 +190,7 @@ export function loadEnv(mode: string, dir?: string): Record<string, string> {
 	// Return only non-framework vars
 	const result: Record<string, string> = {};
 	for (const key of declaredNames) {
-		if (!FRAMEWORK_VARS.has(key)) {
+		if (!isFrameworkVar(key)) {
 			result[key] = process.env[key] ?? merged[key] ?? "";
 		}
 	}

package/src/core/etag.ts

@@ -0,0 +1,13 @@
+// ─── ETag matching ───────────────────────────────────────
+// Shared by static files (staticManifest.ts) and cached responses (cache.ts).
+// No runtime imports: cache.ts also runs on Cloudflare Workers.
+
+/** True when an `If-None-Match` header names `etag` (or `*`). Weak tags match too. */
+export function matchesEtag(header: string | null, etag: string): boolean {
+	if (!header) return false;
+	for (const raw of header.split(",")) {
+		const t = raw.trim();
+		if (t === "*" || t === etag || (t.startsWith("W/") && t.slice(2) === etag)) return true;
+	}
+	return false;
+}

package/src/core/hooks.ts

@@ -58,6 +58,19 @@ export type RequestEvent = {
 	 */
 	locals: Record<string, any> & { nonce?: string };
 	params: Record<string, string>;
+	/**
+	 * The matched route. `id` is its folder under `src/routes` with groups kept,
+	 * e.g. `"/(private)/dashboard/[id]"`; `null` when nothing matched. Set before
+	 * `handle` runs, for page, client-navigation data, form and API requests
+	 * alike, so one check guards a whole group:
+	 *
+	 * ```ts
+	 * if (event.route.id?.startsWith("/(private)") && !event.locals.user) {
+	 * 	throw redirect(303, "/login");
+	 * }
+	 * ```
+	 */
+	route: { id: string | null };
 	cookies: Cookies;
 	/**
 	 * True when the client router is fetching this page's loader data for a
@@ -79,6 +92,8 @@ export type RequestEvent = {
 export type LoadEvent = {
 	url: URL;
 	params: Record<string, string>;
+	/** The route being rendered; see `RequestEvent.route`. */
+	route: { id: string };
 	locals: Record<string, any>;
 	cookies: Cookies;
 	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
@@ -169,6 +184,8 @@ export type Handle = (input: {
 
 export type MetadataEvent = {
 	params: Record<string, string>;
+	/** The route being rendered; see `RequestEvent.route`. */
+	route: { id: string };
 	url: URL;
 	locals: Record<string, any>;
 	cookies: Cookies;