bosia 0.4.6 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.4.6",
+	"version": "0.5.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/client/App.svelte

@@ -3,7 +3,8 @@
 	import { findMatch } from "../matcher.ts";
 	import { clientRoutes } from "bosia:routes";
 	import { consumePrefetch, prefetchCache, dataUrl } from "./prefetch.ts";
-	import { appState } from "./appState.svelte.ts";
+	import { appState, clearDirty } from "./appState.svelte.ts";
+	import { captureSnapshot, liveContext, shouldRerun, type CacheEntry } from "./loaderCache.ts";
 	import { pickErrorPage } from "../errorMatch.ts";
 
 	let {
@@ -49,6 +50,10 @@
 	$effect(() => {
 		if (ssrMode) return;
 
+		// Subscribe to `invalidationTick` so `invalidate()` can wake the effect
+		// without a URL change.
+		void appState.invalidationTick;
+
 		const path = router.currentRoute;
 		const pathname = path.split("?")[0].split("#")[0];
 		const match = findMatch(clientRoutes, pathname);
@@ -68,6 +73,43 @@
 		navDone = false;
 		navigating = true;
 
+		// ─── Loader cache: decide which loaders need to re-run ─────────────
+		// For each layout depth + the page, compare the cached entry (if any)
+		// against the live URL/params and the dirty set. If everything is
+		// cacheable, skip the fetch entirely.
+		const url = new URL(path, window.location.origin);
+		const ctx = liveContext(pathname, match.params, url);
+		const layoutIds = (match.route as any).layoutIds as (string | null)[];
+		const pageId = (match.route as any).pageId as string | null;
+
+		const layoutRunFlags: boolean[] = layoutIds.map((id) => {
+			if (id === null) return false; // no server loader at this depth
+			const entry = appState.loaderCache.layouts[id];
+			if (!entry) return true; // never loaded → must run
+			return shouldRerun(entry, appState.dirty, ctx);
+		});
+
+		let pageRun = false;
+		if (pageId !== null) {
+			const entry = appState.loaderCache.page;
+			if (!entry || entry.nodeId !== pageId) {
+				pageRun = true;
+			} else {
+				pageRun = shouldRerun(entry, appState.dirty, ctx);
+			}
+		}
+
+		// 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.
+		const maskBits =
+			(pageRun ? "1" : "0") + layoutRunFlags.map((b) => (b ? "1" : "0")).join("");
+
+		// Clear dirty set now — we've baked it into the mask.
+		clearDirty();
+
 		// Load components + data in parallel, then update state atomically
 		// to avoid a flash of stale/empty data before the fetch completes.
 		const cached = match.route.hasServerData ? consumePrefetch(path) : null;
@@ -75,7 +117,7 @@
 		const dataFetch = cached
 			? Promise.resolve(cached)
 			: match.route.hasServerData
-				? fetch(dataUrl(path))
+				? fetch(dataUrl(path, maskBits))
 						.then((r) => r.json())
 						.catch(() => null)
 				: Promise.resolve(null);
@@ -143,9 +185,83 @@
 			}
 			PageComponent = pageMod.default;
 			layoutComponents = layoutMods.map((m: any) => m.default);
-			appState.pageData = result?.pageData ?? {};
-			appState.layoutData = result?.layoutData ?? [];
-			appState.routeParams = result?.pageData?.params ?? match.params;
+
+			// Merge sparse server response with the existing client cache.
+			// Slots the server returned null for were intentionally skipped — we
+			// must pull their data from the cache to keep rendering correct.
+			const respLayoutData: (Record<string, any> | null)[] = result?.layoutData ?? [];
+			const respLayoutDeps: (any | null)[] = result?.layoutDeps ?? [];
+			const respPageData: Record<string, any> | null | undefined = result?.pageData;
+			const respPageDeps: any = result?.pageDeps ?? null;
+
+			const mergedLayoutData: Record<string, any>[] = [];
+			for (let i = 0; i < layoutIds.length; i++) {
+				const id = layoutIds[i];
+				if (id === null) {
+					mergedLayoutData.push({});
+					continue;
+				}
+				if (respLayoutData[i] !== null && respLayoutData[i] !== undefined) {
+					const entry: CacheEntry = {
+						nodeId: id,
+						data: respLayoutData[i] as Record<string, any>,
+						deps: respLayoutDeps[i] ?? {
+							keys: [],
+							urls: [],
+							params: [],
+							searchParams: [],
+							cookies: [],
+							uses_url: false,
+						},
+						snapshot: captureSnapshot(
+							respLayoutDeps[i] ?? {
+								keys: [],
+								urls: [],
+								params: [],
+								searchParams: [],
+								cookies: [],
+								uses_url: false,
+							},
+							ctx,
+						),
+					};
+					appState.loaderCache.layouts[id] = entry;
+					mergedLayoutData.push(entry.data);
+				} else {
+					const cachedEntry = appState.loaderCache.layouts[id];
+					mergedLayoutData.push(cachedEntry?.data ?? {});
+				}
+			}
+
+			let mergedPageData: Record<string, any>;
+			if (respPageData !== null && respPageData !== undefined) {
+				const deps = respPageDeps ?? {
+					keys: [],
+					urls: [],
+					params: [],
+					searchParams: [],
+					cookies: [],
+					uses_url: false,
+				};
+				const entry: CacheEntry = {
+					nodeId: pageId ?? "",
+					data: respPageData,
+					deps,
+					snapshot: captureSnapshot(deps, ctx),
+				};
+				if (pageId !== null) appState.loaderCache.page = entry;
+				mergedPageData = respPageData;
+			} else if (appState.loaderCache.page && appState.loaderCache.page.nodeId === pageId) {
+				mergedPageData = appState.loaderCache.page.data;
+			} else {
+				mergedPageData = {};
+			}
+
+			// Always overlay current match.params — cached pageData carries the
+			// stale params from when the loader ran, so trust the live match.
+			appState.pageData = { ...mergedPageData, params: match.params };
+			appState.layoutData = mergedLayoutData;
+			appState.routeParams = match.params;
 			// Successful navigation — clear any prior error state.
 			appState.errorComponent = null;
 			appState.errorProps = null;

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

@@ -7,8 +7,7 @@
 // `ssrMode` and reads from `ssrXxx` props directly during SSR,
 // so concurrent requests don't share these cells.
 
-import { dataUrl } from "./prefetch.ts";
-import { router } from "./router.svelte.ts";
+import type { CacheEntry, DirtyState } from "./loaderCache.ts";
 
 class AppState {
 	pageData = $state<Record<string, any>>({});
@@ -21,43 +20,31 @@ class AppState {
 	errorComponent = $state<any>(null);
 	errorProps = $state<{ error: { status: number; message: string } } | null>(null);
 	errorDepth = $state<number | null>(null);
+	// Loader cache — keyed by stable id (codegen-emitted server file path).
+	// Mirrors the most recent successful run of each layout/page server loader.
+	// Wiped on hard refresh, never persisted.
+	loaderCache: { page: CacheEntry | null; layouts: Record<string, CacheEntry> } = {
+		page: null,
+		layouts: {},
+	};
+	// Pending invalidations consumed by the next data fetch. Mutated by
+	// `invalidate()` / `invalidateAll()` and cleared after the request fires.
+	dirty: DirtyState = {
+		all: false,
+		keys: new Set<string>(),
+		urls: new Set<string>(),
+		urlMatchers: [],
+	};
+	// Bumped by `invalidate*()` to wake the App.svelte nav effect, so calling
+	// `invalidate("k")` re-runs the loader pipeline without changing the URL.
+	invalidationTick = $state(0);
 }
 
 export const appState = new AppState();
 
-/**
- * Re-fetch loader data for the given path and apply to `appState`.
- * Used by `use:enhance` after a successful action — mirrors SvelteKit's
- * `invalidateAll` default. No-op if the fetch fails or returns an error.
- */
-export async function refreshData(path: string): Promise<void> {
-	try {
-		const res = await fetch(dataUrl(path));
-		if (!res.ok) return;
-		const result = await res.json();
-		if (result?.redirect) {
-			router.navigate(result.redirect);
-			return;
-		}
-		if (result?.error) return;
-		appState.pageData = result?.pageData ?? {};
-		appState.layoutData = result?.layoutData ?? [];
-		appState.routeParams = result?.pageData?.params ?? appState.routeParams;
-		if (result?.metadata) {
-			if (result.metadata.title) document.title = result.metadata.title;
-			if (result.metadata.description) {
-				let meta = document.querySelector(
-					'meta[name="description"]',
-				) as HTMLMetaElement | null;
-				if (!meta) {
-					meta = document.createElement("meta");
-					meta.name = "description";
-					document.head.appendChild(meta);
-				}
-				meta.content = result.metadata.description;
-			}
-		}
-	} catch {
-		// best-effort — silently swallow
-	}
+export function clearDirty(): void {
+	appState.dirty.all = false;
+	appState.dirty.keys.clear();
+	appState.dirty.urls.clear();
+	appState.dirty.urlMatchers = [];
 }

package/src/core/client/enhance.ts

@@ -5,7 +5,7 @@
 // full page reload. Falls back to native form submission when JS is
 // disabled because nothing is wired up until this action runs.
 
-import { appState, refreshData } from "./appState.svelte.ts";
+import { appState } from "./appState.svelte.ts";
 import { router } from "./router.svelte.ts";
 
 export type ActionResult =
@@ -53,7 +53,11 @@ async function applyResult(
 	appState.form = result.data;
 	if (reset) form.reset();
 	if (invalidateAll) {
-		await refreshData(window.location.pathname + window.location.search);
+		// Form actions invalidate the page loader only by default — layouts
+		// stay cached. Loaders that need to react to a mutation should call
+		// `invalidate("app:key")` from the action's submit handler.
+		appState.loaderCache.page = null;
+		appState.invalidationTick = appState.invalidationTick + 1;
 	}
 }
 

package/src/core/client/hydrate.ts

@@ -5,10 +5,22 @@ import { initPrefetch } from "./prefetch.ts";
 import { findMatch, compileRoutes, canonicalPathname } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
 import { appState } from "./appState.svelte.ts";
+import { captureSnapshot, liveContext, type CacheEntry } from "./loaderCache.ts";
+import type { LoaderDeps } from "../hooks.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by App.svelte and router via module reference)
 compileRoutes(clientRoutes);
 
+function readJsonScript<T>(id: string): T | null {
+	const el = document.getElementById(id);
+	if (!el) return null;
+	try {
+		return JSON.parse(el.textContent ?? "null") as T;
+	} catch {
+		return null;
+	}
+}
+
 // ─── Hydration ────────────────────────────────────────────
 
 async function main() {
@@ -49,9 +61,9 @@ async function main() {
 		router.params = match.params;
 	}
 
-	const ssrPageData = (window as any).__BOSIA_PAGE_DATA__ ?? {};
-	const ssrLayoutData = (window as any).__BOSIA_LAYOUT_DATA__ ?? [];
-	const ssrFormData = (window as any).__BOSIA_FORM_DATA__ ?? null;
+	const ssrPageData = readJsonScript<Record<string, any>>("__bosia-page-data__") ?? {};
+	const ssrLayoutData = readJsonScript<Record<string, any>[]>("__bosia-layout-data__") ?? [];
+	const ssrFormData = readJsonScript<Record<string, any>>("__bosia-form-data__");
 
 	// Seed shared client state so `use:enhance` and other helpers
 	// start from the same values App.svelte renders during hydration.
@@ -60,6 +72,42 @@ async function main() {
 	appState.routeParams = ssrPageData?.params ?? match?.params ?? {};
 	appState.form = ssrFormData;
 
+	// Seed the loader cache from window globals emitted server-side so the
+	// next client navigation can decide which loaders to skip without an
+	// extra fetch round-trip.
+	if (match) {
+		const url = new URL(window.location.href);
+		const ctx = liveContext(window.location.pathname, match.params, url);
+		const ssrPageDeps: LoaderDeps | null = (window as any).__BOSIA_PAGE_DEPS__ ?? null;
+		const ssrLayoutDeps: (LoaderDeps | null)[] = (window as any).__BOSIA_LAYOUT_DEPS__ ?? [];
+		const pageId = (match.route as any).pageId as string | null;
+		const layoutIds = (match.route as any).layoutIds as (string | null)[];
+
+		if (pageId !== null && ssrPageDeps && ssrPageData) {
+			const entry: CacheEntry = {
+				nodeId: pageId,
+				data: ssrPageData,
+				deps: ssrPageDeps,
+				snapshot: captureSnapshot(ssrPageDeps, ctx),
+			};
+			appState.loaderCache.page = entry;
+		}
+		for (let i = 0; i < layoutIds.length; i++) {
+			const id = layoutIds[i];
+			if (id === null) continue;
+			const deps = ssrLayoutDeps[i];
+			const data = ssrLayoutData[i];
+			if (!deps || !data) continue;
+			const entry: CacheEntry = {
+				nodeId: id,
+				data,
+				deps,
+				snapshot: captureSnapshot(deps, ctx),
+			};
+			appState.loaderCache.layouts[id] = entry;
+		}
+	}
+
 	const target = document.getElementById("app")!;
 	const props = {
 		ssrMode: false,

package/src/core/client/loaderCache.ts

@@ -0,0 +1,127 @@
+// ─── Client-Side Loader Cache ─────────────────────────────
+// Stores the result of each server loader run by stable id (the
+// +page.server.ts / +layout.server.ts path emitted by codegen) along
+// with the LoaderDeps record captured server-side. On each client
+// navigation we use the cache + a "dirty" set populated by the
+// `invalidate()` API to decide which loaders need to re-run, sending
+// the decision as an `_invalidated=<bits>` query param so the server
+// can skip the loaders that haven't conceptually changed.
+//
+// Cache lives in browser memory only — wiped on hard refresh.
+
+import type { LoaderDeps } from "../hooks.ts";
+
+export type CacheSnapshot = {
+	pathname: string;
+	params: Record<string, string>;
+	searchParams: Record<string, string | null>;
+	cookies: Record<string, string | undefined>;
+};
+
+export type CacheEntry = {
+	nodeId: string;
+	data: Record<string, any>;
+	deps: LoaderDeps;
+	snapshot: CacheSnapshot;
+};
+
+export type EvalContext = {
+	pathname: string;
+	params: Record<string, string>;
+	url: URL;
+	cookies: Record<string, string | undefined>;
+};
+
+function readDocumentCookies(): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (typeof document === "undefined") return out;
+	for (const pair of document.cookie.split(";")) {
+		const idx = pair.indexOf("=");
+		if (idx === -1) continue;
+		const name = pair.slice(0, idx).trim();
+		const value = pair.slice(idx + 1).trim();
+		if (name) {
+			try {
+				out[name] = decodeURIComponent(value);
+			} catch {
+				out[name] = value;
+			}
+		}
+	}
+	return out;
+}
+
+export function liveContext(
+	pathname: string,
+	params: Record<string, string>,
+	url: URL,
+): EvalContext {
+	return {
+		pathname,
+		params,
+		url,
+		cookies: readDocumentCookies(),
+	};
+}
+
+/** Capture only the values relevant to a loader's tracked deps. */
+export function captureSnapshot(deps: LoaderDeps, ctx: EvalContext): CacheSnapshot {
+	const params: Record<string, string> = {};
+	for (const k of deps.params) params[k] = ctx.params[k] ?? "";
+	const searchParams: Record<string, string | null> = {};
+	for (const k of deps.searchParams) searchParams[k] = ctx.url.searchParams.get(k);
+	const cookies: Record<string, string | undefined> = {};
+	for (const k of deps.cookies) cookies[k] = ctx.cookies[k];
+	return { pathname: ctx.pathname, params, searchParams, cookies };
+}
+
+export type DirtyState = {
+	all: boolean;
+	keys: Set<string>;
+	urls: Set<string>;
+	urlMatchers: Array<(u: URL) => boolean>;
+};
+
+export function shouldRerun(entry: CacheEntry, dirty: DirtyState, next: EvalContext): boolean {
+	if (dirty.all) return true;
+	const { deps, snapshot } = entry;
+	// Dirty keys
+	for (const k of deps.keys) {
+		if (dirty.keys.has(k)) return true;
+	}
+	// Dirty URLs (string match or predicate match)
+	if (deps.urls.length > 0) {
+		for (const u of deps.urls) {
+			if (dirty.urls.has(u)) return true;
+			for (const fn of dirty.urlMatchers) {
+				try {
+					if (fn(new URL(u))) return true;
+				} catch {
+					// ignore malformed URL deps
+				}
+			}
+		}
+	}
+	// Param value changes
+	for (const k of deps.params) {
+		if (snapshot.params[k] !== (next.params[k] ?? "")) return true;
+	}
+	// Search param value changes
+	for (const k of deps.searchParams) {
+		if (snapshot.searchParams[k] !== next.url.searchParams.get(k)) return true;
+	}
+	// Cookie value changes
+	for (const k of deps.cookies) {
+		if (k === "*") {
+			// Broad cookie read — re-run on any cookie change. Detect by
+			// comparing the full incoming jar against the captured slice.
+			// In practice an empty captured slice will never equal the live
+			// jar once any cookie exists, so we re-run whenever cookies do.
+			return true;
+		}
+		if (snapshot.cookies[k] !== next.cookies[k]) return true;
+	}
+	// Pathname change for loaders that read the URL
+	if (deps.uses_url && snapshot.pathname !== next.pathname) return true;
+	return false;
+}

package/src/core/client/navigation.ts

@@ -0,0 +1,59 @@
+// ─── Public Invalidation API ──────────────────────────────
+// Counterpart to SvelteKit's `invalidate()` / `invalidateAll()`. Marks
+// loader cache entries dirty and triggers the App.svelte nav effect to
+// re-run only the loaders whose dependencies were invalidated.
+//
+// Usage:
+//   import { invalidate, invalidateAll } from "bosia/client";
+//   await invalidate("app:user");
+//   await invalidate("/api/posts");
+//   await invalidate((url) => url.pathname.startsWith("/api/"));
+//   await invalidateAll();
+
+import { appState } from "./appState.svelte.ts";
+
+type InvalidateTarget = string | URL | ((url: URL) => boolean);
+
+function bumpTick() {
+	appState.invalidationTick = appState.invalidationTick + 1;
+}
+
+/**
+ * Mark a dependency as invalid; the next navigation (and any in-progress
+ * navigation that hasn't started its fetch yet) will re-run loaders that
+ * declared a matching `depends()` key, fetched a matching URL, or — when
+ * given a predicate — fetched any URL the predicate returns true for.
+ *
+ * Returns a promise that resolves after the nav effect has flushed.
+ */
+export function invalidate(target: InvalidateTarget): Promise<void> {
+	if (typeof target === "function") {
+		appState.dirty.urlMatchers.push(target);
+	} else {
+		const str = typeof target === "string" ? target : target.href;
+		const isUrl = str.startsWith("/") || str.includes("://");
+		if (isUrl) {
+			try {
+				// Normalize to an absolute URL — fetches the loader recorded are
+				// always absolute, so a relative `/api/foo` must be promoted here.
+				const abs = new URL(str, window.location.origin).href;
+				appState.dirty.urls.add(abs);
+			} catch {
+				appState.dirty.urls.add(str);
+			}
+		} else {
+			appState.dirty.keys.add(str);
+		}
+	}
+	bumpTick();
+	return Promise.resolve();
+}
+
+/**
+ * Mark every loader as invalid. Next navigation re-runs all of them.
+ */
+export function invalidateAll(): Promise<void> {
+	appState.dirty.all = true;
+	bumpTick();
+	return Promise.resolve();
+}

package/src/core/client/prefetch.ts

@@ -2,11 +2,52 @@
 // Supports `data-bosia-preload="hover"` and `data-bosia-preload="viewport"`
 // on <a> elements or their ancestors.
 
+import { findMatch } from "../matcher.ts";
+import { clientRoutes } from "bosia:routes";
+import { appState } from "./appState.svelte.ts";
+import { liveContext, shouldRerun } from "./loaderCache.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.
+ */
+export function buildMaskBits(path: string): string | null {
+	const url = new URL(path, window.location.origin);
+	const pathname = url.pathname;
+	const match = findMatch(clientRoutes, pathname);
+	if (!match) return null;
+	const ctx = liveContext(pathname, match.params, url);
+	const layoutIds = (match.route as any).layoutIds as (string | null)[];
+	const pageId = (match.route as any).pageId as string | null;
+
+	const layoutRunFlags = layoutIds.map((id) => {
+		if (id === null) return false;
+		const entry = appState.loaderCache.layouts[id];
+		if (!entry) return true;
+		return shouldRerun(entry, appState.dirty, ctx);
+	});
+
+	let pageRun = false;
+	if (pageId !== null) {
+		const entry = appState.loaderCache.page;
+		if (!entry || entry.nodeId !== pageId) pageRun = true;
+		else pageRun = shouldRerun(entry, appState.dirty, ctx);
+	}
+
+	return (pageRun ? "1" : "0") + layoutRunFlags.map((b) => (b ? "1" : "0")).join("");
+}
+
 /** Builds the `/__bosia/data/…` URL for a given client path. */
-export function dataUrl(path: string): string {
+export function dataUrl(path: string, invalidatedBits?: string): string {
 	const url = new URL(path, window.location.origin);
 	let p = url.pathname.replace(/\/$/, "");
-	return `/__bosia/data${p || "/index"}.json${url.search}`;
+	let qs = url.search;
+	if (invalidatedBits) {
+		const sep = qs ? "&" : "?";
+		qs = `${qs}${sep}_invalidated=${invalidatedBits}`;
+	}
+	return `/__bosia/data${p || "/index"}.json${qs}`;
 }
 
 export const prefetchCache = new Map<string, { data: any; ts: number }>();
@@ -33,7 +74,11 @@ export async function prefetchPath(path: string): Promise<void> {
 
 	pending.add(path);
 	try {
-		const res = await fetch(dataUrl(path));
+		// 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).
+		const maskBits = buildMaskBits(path) ?? undefined;
+		const res = await fetch(dataUrl(path, maskBits));
 		if (res.ok) {
 			if (prefetchCache.size >= MAX_PREFETCH_ENTRIES) {
 				const oldest = prefetchCache.keys().next().value;

package/src/core/hooks.ts

@@ -56,6 +56,33 @@ export type LoadEvent = {
 	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 	parent: () => Promise<Record<string, any>>;
 	metadata: Record<string, any> | null;
+	/**
+	 * Declare custom dependency keys for this loader. The client cache
+	 * will re-run the loader when `invalidate(key)` is called with any
+	 * of these keys. Keys are arbitrary strings, but conventionally
+	 * namespaced (e.g. `"app:user"`).
+	 */
+	depends: (...keys: string[]) => void;
+};
+
+/**
+ * Tracked dependencies captured for a single loader during one run.
+ * Shipped to the client so subsequent client-side navigations can
+ * decide whether to re-run the loader.
+ */
+export type LoaderDeps = {
+	/** `depends(...keys)` declarations. */
+	keys: string[];
+	/** Absolute URLs passed to the loader's `fetch()`. */
+	urls: string[];
+	/** Route params the loader read (`params.X`). */
+	params: string[];
+	/** Search params the loader read (`url.searchParams.get(X)` / `.has(X)`). */
+	searchParams: string[];
+	/** Cookies the loader read (`cookies.get(X)`). */
+	cookies: string[];
+	/** True if the loader read `url.pathname`/`url.origin`/`url.hash`/`url.href`. */
+	uses_url: boolean;
 };
 
 export type ResolveFunction = (event: RequestEvent) => MaybePromise<Response>;

package/src/core/html.ts

@@ -37,6 +37,22 @@ export function safeJsonStringify(data: unknown): string {
 	return json.replace(/[<>&\u2028\u2029]/g, (c) => map[c]);
 }
 
+const SCRIPT_HAZARD_RE = /<(\/script|!--)/gi;
+
+/** Escapes JSON for safe embedding inside <script type="application/json"> blocks.
+ *  Blocks premature </script> and <!-- (HTML script-data escape state) without
+ *  the JS-context overhead of safeJsonStringify. */
+export function safeJsonForScript(data: unknown): string {
+	let json: string;
+	try {
+		json = JSON.stringify(data);
+	} catch {
+		console.error("safeJsonForScript: failed to serialize data (circular reference?)");
+		json = "null";
+	}
+	return json.replace(SCRIPT_HAZARD_RE, "\\u003c$1");
+}
+
 // ─── Public Env Injection ─────────────────────────────────
 
 /**
@@ -78,6 +94,8 @@ export function buildHtml(
 	lang?: string,
 	ssr = true,
 	nonce?: string,
+	pageDeps: any = null,
+	layoutDeps: any[] | null = null,
 ): string {
 	const cssLinks = (distManifest.css ?? [])
 		.map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
@@ -92,12 +110,26 @@ export function buildHtml(
 			? `\n  <script${n}>window.__BOSIA_ENV__=${safeJsonStringify(publicEnv)};</script>`
 			: "";
 
-	const formScript =
-		formData != null ? `window.__BOSIA_FORM_DATA__=${safeJsonStringify(formData)};` : "";
 	const ssrFlag = ssr ? "" : "window.__BOSIA_SSR__=false;";
 
+	const depsScript =
+		pageDeps !== null || layoutDeps !== null
+			? `window.__BOSIA_PAGE_DEPS__=${safeJsonStringify(pageDeps)};window.__BOSIA_LAYOUT_DEPS__=${safeJsonStringify(layoutDeps ?? [])};`
+			: "";
+
+	const sysScript =
+		ssrFlag || depsScript ? `\n  <script${n}>${ssrFlag}${depsScript}</script>` : "";
+
+	const dataIslands = csr
+		? `\n  <script${n} type="application/json" id="__bosia-page-data__">${safeJsonForScript(pageData)}</script>` +
+			`\n  <script${n} type="application/json" id="__bosia-layout-data__">${safeJsonForScript(layoutData)}</script>` +
+			(formData != null
+				? `\n  <script${n} type="application/json" id="__bosia-form-data__">${safeJsonForScript(formData)}</script>`
+				: "")
+		: "";
+
 	const scripts = csr
-		? `${envScript}\n  <script${n}>${ssrFlag}window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};window.__BOSIA_LAYOUT_DATA__=${safeJsonStringify(layoutData)};${formScript}</script>\n  <script${n} type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`
+		? `${envScript}${dataIslands}${sysScript}\n  <script${n} type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`
 		: isDev
 			? `\n  <script${n}>!function r(){var e=new EventSource("/__bosia/sse");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`
 			: "";
@@ -208,6 +240,8 @@ export function buildHtmlTail(
 	ssr = true,
 	bodyEndExtras?: string[],
 	nonce?: string,
+	pageDeps: any = null,
+	layoutDeps: any[] | null = null,
 ): string {
 	const n = nonceAttr(nonce);
 	let out = `<script${n}>document.getElementById('__bs__').remove()</script>`;
@@ -219,12 +253,19 @@ export function buildHtmlTail(
 		if (Object.keys(publicEnv).length > 0) {
 			out += `\n<script${n}>window.__BOSIA_ENV__=${safeJsonStringify(publicEnv)};</script>`;
 		}
-		const formInject =
-			formData != null ? `window.__BOSIA_FORM_DATA__=${safeJsonStringify(formData)};` : "";
+		out += `\n<script${n} type="application/json" id="__bosia-page-data__">${safeJsonForScript(pageData)}</script>`;
+		out += `\n<script${n} type="application/json" id="__bosia-layout-data__">${safeJsonForScript(layoutData)}</script>`;
+		if (formData != null) {
+			out += `\n<script${n} type="application/json" id="__bosia-form-data__">${safeJsonForScript(formData)}</script>`;
+		}
 		const ssrFlag = ssr ? "" : "window.__BOSIA_SSR__=false;";
-		out +=
-			`\n<script${n}>${ssrFlag}window.__BOSIA_PAGE_DATA__=${safeJsonStringify(pageData)};` +
-			`window.__BOSIA_LAYOUT_DATA__=${safeJsonStringify(layoutData)};${formInject}</script>`;
+		const depsInject =
+			pageDeps !== null || layoutDeps !== null
+				? `window.__BOSIA_PAGE_DEPS__=${safeJsonStringify(pageDeps)};window.__BOSIA_LAYOUT_DEPS__=${safeJsonStringify(layoutDeps ?? [])};`
+				: "";
+		if (ssrFlag || depsInject) {
+			out += `\n<script${n}>${ssrFlag}${depsInject}</script>`;
+		}
 		out += `\n<script${n} type="module" src="/dist/client/${distManifest.entry}${cacheBust}"></script>`;
 	} else if (isDev) {
 		out += `\n<script${n}>!function r(){var e=new EventSource("/__bosia/sse");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`;

package/src/core/renderer.ts

@@ -3,7 +3,7 @@ import { render } from "svelte/server";
 import { findMatch } from "./matcher.ts";
 import { serverRoutes, errorPage } from "bosia:routes";
 import type { RouteMatch } from "./types.ts";
-import type { Cookies } from "./hooks.ts";
+import type { Cookies, LoaderDeps } from "./hooks.ts";
 import { CSP_ENABLED } from "./csp.ts";
 import { HttpError, Redirect } from "./errors.ts";
 import { pickErrorPage, type ErrorOrigin } from "./errorMatch.ts";
@@ -158,9 +158,134 @@ function stampErrorContext(
 	e.partialLayoutData ??= [...partialLayoutData];
 }
 
+// ─── Per-Loader Dependency Tracking ──────────────────────
+// Wraps `params`, `url`, `cookies`, and `fetch` with proxies/closures
+// that record every key read during a single loader run. The client
+// cache uses these records to skip re-runs on subsequent navigations
+// when none of the tracked inputs changed.
+
+function emptyDeps(): LoaderDeps {
+	return {
+		keys: [],
+		urls: [],
+		params: [],
+		searchParams: [],
+		cookies: [],
+		uses_url: false,
+	};
+}
+
+function trackedParams(params: Record<string, string>, deps: LoaderDeps): Record<string, string> {
+	return new Proxy(params, {
+		get(target, prop) {
+			if (typeof prop === "string") {
+				if (!deps.params.includes(prop)) deps.params.push(prop);
+			}
+			return Reflect.get(target, prop);
+		},
+	});
+}
+
+const URL_TRACKED_PROPS = new Set(["pathname", "origin", "hash", "href", "host", "hostname"]);
+
+function trackedUrl(url: URL, deps: LoaderDeps): URL {
+	const trackedSearch = new Proxy(url.searchParams, {
+		get(target, prop) {
+			if (prop === "get" || prop === "has" || prop === "getAll") {
+				return (key: string) => {
+					if (typeof key === "string" && !deps.searchParams.includes(key)) {
+						deps.searchParams.push(key);
+					}
+					return (target as any)[prop](key);
+				};
+			}
+			const value = Reflect.get(target, prop);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+	return new Proxy(url, {
+		get(target, prop) {
+			if (prop === "searchParams") return trackedSearch;
+			if (prop === "search") {
+				// Whole search string read → treat as broad searchParams dep
+				deps.uses_url = true;
+				return target.search;
+			}
+			if (typeof prop === "string" && URL_TRACKED_PROPS.has(prop)) {
+				deps.uses_url = true;
+			}
+			const value = Reflect.get(target, prop);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}
+
+function trackedCookies(cookies: Cookies, deps: LoaderDeps): Cookies {
+	return {
+		get(name: string) {
+			if (!deps.cookies.includes(name)) deps.cookies.push(name);
+			return cookies.get(name);
+		},
+		getAll() {
+			// Broad read — treat as wildcard; record empty marker so any cookie
+			// invalidation triggers re-run. Use a sentinel "*" to mean "all".
+			if (!deps.cookies.includes("*")) deps.cookies.push("*");
+			return cookies.getAll();
+		},
+		set(name, value, options) {
+			cookies.set(name, value, options);
+		},
+		delete(name, options) {
+			cookies.delete(name, options);
+		},
+	};
+}
+
+function trackedFetch(
+	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>,
+	origin: string,
+	deps: LoaderDeps,
+): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response> {
+	return (input, init) => {
+		let href: string | null = null;
+		try {
+			if (typeof input === "string") href = new URL(input, origin).href;
+			else if (input instanceof URL) href = input.href;
+			else href = new URL(input.url, origin).href;
+		} catch {
+			href = null;
+		}
+		if (href && !deps.urls.includes(href)) deps.urls.push(href);
+		return fetch(input, init);
+	};
+}
+
+function makeDepends(deps: LoaderDeps): (...keys: string[]) => void {
+	return (...keys: string[]) => {
+		for (const k of keys) {
+			if (typeof k === "string" && !deps.keys.includes(k)) deps.keys.push(k);
+		}
+	};
+}
+
 // ─── Route Data Loader ───────────────────────────────────
 // Runs layout + page server loaders for a given URL.
 // Used by both SSR and the /__bosia/data JSON endpoint.
+//
+// `mask` controls selective re-runs from the client data endpoint:
+//   - undefined → run everything (SSR, first nav)
+//   - layouts[i] === true → run that layout; false → skip, emit null
+//   - page === true → run page; false → skip, emit null
+// When skipped, the parent() chain still receives the *combined parent
+// data* contributed by previously-cached layers, which the client
+// reconstructs and forwards in the request body. For now (initial
+// implementation), skipped loaders contribute `{}` to parent and the
+// response slot is `null`; the client merges with its cached data.
+
+export type LoaderMask = {
+	page: boolean;
+	layouts: boolean[];
+};
 
 export async function loadRouteData(
 	url: URL,
@@ -169,89 +294,155 @@ export async function loadRouteData(
 	cookies: Cookies,
 	metadataData: Record<string, any> | null = null,
 	match?: RouteMatch<(typeof serverRoutes)[number]> | null,
+	mask?: LoaderMask,
 ) {
 	match ??= findMatch(serverRoutes, url.pathname);
 	if (!match) return null;
 
 	const { route, params } = match;
 	const fetch = makeFetch(req, url);
-	const layoutData: Record<string, any>[] = [];
+	const origin = url.origin;
+	const layoutData: (Record<string, any> | null)[] = [];
+	const layoutDeps: (LoaderDeps | null)[] = [];
 	let parentData: Record<string, any> = {};
 
 	// Run layout server loaders root → leaf, each gets parent() data
 	for (const ls of route.layoutServers) {
+		const skip = mask && mask.layouts[ls.depth] === false;
 		try {
+			if (skip) {
+				layoutData[ls.depth] = null;
+				layoutDeps[ls.depth] = null;
+				// Skipped layers contribute {} to the parent chain. The client
+				// already has their data and renders it from cache, so dependent
+				// loaders that DO re-run will see stale parent() data here. This
+				// is the same trade-off SvelteKit makes; loaders that need fresh
+				// upstream data should call `depends()` on a shared key.
+				continue;
+			}
 			const mod = await ls.loader();
 			if (typeof mod.load === "function") {
 				// Snapshot per layer so loaders cannot mutate the shared accumulator,
 				// preserving the same isolation semantics as the previous merge-on-call code.
 				const snapshot = { ...parentData };
 				const parent = async () => snapshot;
+				const deps = emptyDeps();
 				const result =
 					(await withTimeout(
-						mod.load({ params, url, locals, cookies, parent, fetch, metadata: null }),
+						mod.load({
+							params: trackedParams(params, deps),
+							url: trackedUrl(url, deps),
+							locals,
+							cookies: trackedCookies(cookies, deps),
+							parent,
+							fetch: trackedFetch(fetch, origin, deps),
+							metadata: null,
+							depends: makeDepends(deps),
+						}),
 						LOAD_TIMEOUT,
 						`layout load (depth=${ls.depth}, ${url.pathname})`,
 					)) ?? {};
 				layoutData[ls.depth] = result;
+				layoutDeps[ls.depth] = deps;
 				parentData = { ...parentData, ...result };
+			} else {
+				layoutData[ls.depth] = {};
+				layoutDeps[ls.depth] = emptyDeps();
 			}
 		} catch (err) {
 			if (err instanceof Redirect) throw err;
 			if (err instanceof HttpError) {
-				stampErrorContext(err, ls.depth, "layout", layoutData);
+				stampErrorContext(
+					err,
+					ls.depth,
+					"layout",
+					layoutData.map((d) => d ?? {}),
+				);
 				throw err;
 			}
 			if (isDev) console.error("Layout server load error:", err);
 			else console.error("Layout server load error:", (err as Error).message ?? err);
 			const wrapped = new HttpError(500, "Internal Server Error");
-			stampErrorContext(wrapped, ls.depth, "layout", layoutData);
+			stampErrorContext(
+				wrapped,
+				ls.depth,
+				"layout",
+				layoutData.map((d) => d ?? {}),
+			);
 			throw wrapped;
 		}
 	}
 
 	// Run page server loader
-	let pageData: Record<string, any> = {};
+	let pageData: Record<string, any> | null = null;
+	let pageDeps: LoaderDeps | null = null;
 	let csr = true;
 	let ssr = true;
+	const skipPage = mask && mask.page === false;
 	if (route.pageServer) {
 		try {
 			const mod = await route.pageServer();
 			if (mod.csr === false) csr = false;
 			if (mod.ssr === false) ssr = false;
-			if (typeof mod.load === "function") {
+			if (skipPage) {
+				pageData = null;
+				pageDeps = null;
+			} else if (typeof mod.load === "function") {
 				const snapshot = { ...parentData };
 				const parent = async () => snapshot;
+				const deps = emptyDeps();
 				pageData =
 					(await withTimeout(
 						mod.load({
-							params,
-							url,
+							params: trackedParams(params, deps),
+							url: trackedUrl(url, deps),
 							locals,
-							cookies,
+							cookies: trackedCookies(cookies, deps),
 							parent,
-							fetch,
+							fetch: trackedFetch(fetch, origin, deps),
 							metadata: metadataData,
+							depends: makeDepends(deps),
 						}),
 						LOAD_TIMEOUT,
 						`page load (${url.pathname})`,
 					)) ?? {};
+				pageDeps = deps;
+			} else {
+				pageData = {};
+				pageDeps = emptyDeps();
 			}
 		} catch (err) {
 			if (err instanceof Redirect) throw err;
 			if (err instanceof HttpError) {
-				stampErrorContext(err, route.layoutModules.length, "page", layoutData);
+				stampErrorContext(
+					err,
+					route.layoutModules.length,
+					"page",
+					layoutData.map((d) => d ?? {}),
+				);
 				throw err;
 			}
 			if (isDev) console.error("Page server load error:", err);
 			else console.error("Page server load error:", (err as Error).message ?? err);
 			const wrapped = new HttpError(500, "Internal Server Error");
-			stampErrorContext(wrapped, route.layoutModules.length, "page", layoutData);
+			stampErrorContext(
+				wrapped,
+				route.layoutModules.length,
+				"page",
+				layoutData.map((d) => d ?? {}),
+			);
 			throw wrapped;
 		}
+	} else {
+		pageData = {};
+		pageDeps = emptyDeps();
 	}
 
-	return { pageData: { ...pageData, params }, layoutData, csr, ssr };
+	// `params` are always attached to pageData for client-side router consumption.
+	// When pageData is skipped, the client merges its cached pageData with current
+	// route params separately, so we keep the `null` sentinel here.
+	const pageOut = pageData === null ? null : { ...pageData, params };
+	return { pageData: pageOut, layoutData, csr, ssr, pageDeps, layoutDeps };
 }
 
 // ─── Metadata Loader ─────────────────────────────────────
@@ -399,6 +590,10 @@ export async function renderSSRStream(
 		pluginRenderFragments("bodyEnd", renderCtx),
 	]);
 
+	// SSR always runs every loader, so coerce types from the optional sparse shape.
+	const layoutDataFull = (data.layoutData as Record<string, any>[]).map((d) => d ?? {});
+	const pageDataFull = data.pageData ?? {};
+
 	// ssr=false → no render() needed; ship shell + hydration as a single response.
 	// ssr=false && csr=false is meaningless (nothing renders) — force csr=true.
 	if (!data.ssr) {
@@ -413,13 +608,15 @@ export async function renderSSRStream(
 			buildHtmlTail(
 				"",
 				"",
-				data.pageData,
-				data.layoutData,
+				pageDataFull,
+				layoutDataFull,
 				true,
 				null,
 				false,
 				bodyEndExtras,
 				nonce,
+				data.pageDeps,
+				data.layoutDeps,
 			);
 		return new Response(html, {
 			headers: { "Content-Type": "text/html; charset=utf-8" },
@@ -435,8 +632,8 @@ export async function renderSSRStream(
 				ssrMode: true,
 				ssrPageComponent: pageMod.default,
 				ssrLayoutComponents: layoutMods.map((m: any) => m.default),
-				ssrPageData: data.pageData,
-				ssrLayoutData: data.layoutData,
+				ssrPageData: pageDataFull,
+				ssrLayoutData: layoutDataFull,
 			},
 		}));
 	} catch (err) {
@@ -451,7 +648,7 @@ export async function renderSSRStream(
 			route,
 			route.layoutModules.length,
 			"page",
-			data.layoutData,
+			layoutDataFull,
 			nonce,
 		);
 	}
@@ -464,13 +661,15 @@ export async function renderSSRStream(
 			buildHtmlTail(
 				body,
 				head,
-				data.pageData,
-				data.layoutData,
+				pageDataFull,
+				layoutDataFull,
 				data.csr,
 				null,
 				true,
 				bodyEndExtras,
 				nonce,
+				data.pageDeps,
+				data.layoutDeps,
 			),
 		),
 	];
@@ -556,6 +755,10 @@ export async function renderPageWithFormData(
 			nonce,
 		);
 
+	// Form-action re-render always runs every loader (no client mask).
+	const layoutDataFull = (data.layoutData as Record<string, any>[]).map((d) => d ?? {});
+	const pageDataFull = data.pageData ?? {};
+
 	if (!data.ssr) {
 		if (!data.csr && isDev) {
 			console.warn(
@@ -565,13 +768,15 @@ export async function renderPageWithFormData(
 		const html = buildHtml(
 			"",
 			"",
-			data.pageData,
-			data.layoutData,
+			pageDataFull,
+			layoutDataFull,
 			true,
 			formData,
 			undefined,
 			false,
 			nonce,
+			data.pageDeps,
+			data.layoutDeps,
 		);
 		return compress(html, "text/html; charset=utf-8", req, status);
 	}
@@ -581,8 +786,8 @@ export async function renderPageWithFormData(
 			ssrMode: true,
 			ssrPageComponent: pageMod.default,
 			ssrLayoutComponents: layoutMods.map((m: any) => m.default),
-			ssrPageData: data.pageData,
-			ssrLayoutData: data.layoutData,
+			ssrPageData: pageDataFull,
+			ssrLayoutData: layoutDataFull,
 			ssrFormData: formData,
 		},
 	});
@@ -590,13 +795,15 @@ export async function renderPageWithFormData(
 	const html = buildHtml(
 		body,
 		head,
-		data.pageData,
-		data.layoutData,
+		pageDataFull,
+		layoutDataFull,
 		data.csr,
 		formData,
 		undefined,
 		true,
 		nonce,
+		data.pageDeps,
+		data.layoutDeps,
 	);
 	return compress(html, "text/html; charset=utf-8", req, status);
 }
@@ -615,7 +822,7 @@ export async function renderErrorPage(
 	route?: any,
 	errorDepth?: number,
 	errorOrigin?: ErrorOrigin,
-	partialLayoutData?: Record<string, any>[],
+	partialLayoutData?: (Record<string, any> | null)[],
 	nonce?: string,
 ): Promise<Response> {
 	// Strip the nonce from emitted scripts when CSP is off — the attribute

package/src/core/routeFile.ts

@@ -40,6 +40,11 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push("  hasServerData: boolean;");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
+	// Stable ids per node, used by the client loader cache to detect whether
+	// a layout/page at a given depth is the same as last nav's (skip) or new
+	// (re-run). One id per layout in order, plus an optional page id.
+	lines.push("  pageId: string | null;");
+	lines.push("  layoutIds: (string | null)[];");
 	lines.push("}> = [");
 	for (const r of pages) {
 		const layoutImports = r.layouts
@@ -52,6 +57,15 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 			)
 			.join(", ");
 		const hasServerData = !!(r.pageServer || r.layoutServers.length > 0);
+		const pageId = r.pageServer ? JSON.stringify(r.pageServer) : "null";
+		// Map +layout.server.ts paths to their layout depth, leaving nulls for
+		// layouts that have no server loader. Length matches layouts.length so
+		// client cache can index by depth.
+		const layoutIdByDepth: (string | null)[] = new Array(r.layouts.length).fill(null);
+		for (const ls of r.layoutServers) layoutIdByDepth[ls.depth] = ls.path;
+		const layoutIds = layoutIdByDepth
+			.map((id) => (id === null ? "null" : JSON.stringify(id)))
+			.join(", ");
 		lines.push("  {");
 		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
@@ -59,6 +73,8 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    hasServerData: ${hasServerData},`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
+		lines.push(`    pageId: ${pageId},`);
+		lines.push(`    layoutIds: [${layoutIds}],`);
 		lines.push("  },");
 	}
 	lines.push("];\n");
@@ -157,6 +173,8 @@ function generateClientRoutesFile(
 	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push("  hasServerData: boolean;");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
+	lines.push("  pageId: string | null;");
+	lines.push("  layoutIds: (string | null)[];");
 	lines.push("}> = [");
 	for (const r of pages) {
 		const layoutImports = r.layouts
@@ -169,6 +187,12 @@ function generateClientRoutesFile(
 			)
 			.join(", ");
 		const hasServerData = !!(r.pageServer || r.layoutServers.length > 0);
+		const pageId = r.pageServer ? JSON.stringify(r.pageServer) : "null";
+		const layoutIdByDepth: (string | null)[] = new Array(r.layouts.length).fill(null);
+		for (const ls of r.layoutServers) layoutIdByDepth[ls.depth] = ls.path;
+		const layoutIds = layoutIdByDepth
+			.map((id) => (id === null ? "null" : JSON.stringify(id)))
+			.join(", ");
 		lines.push("  {");
 		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
@@ -176,6 +200,8 @@ function generateClientRoutesFile(
 		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    hasServerData: ${hasServerData},`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
+		lines.push(`    pageId: ${pageId},`);
+		lines.push(`    layoutIds: [${layoutIds}],`);
 		lines.push("  },");
 	}
 	lines.push("];\n");

package/src/core/server.ts

@@ -112,6 +112,23 @@ function isValidRoutePath(path: string, origin: string): boolean {
 	}
 }
 
+/**
+ * Decode an `_invalidated` bitmask string. Char 0 = page, char i+1 = layout
+ * depth i, '1' = run, '0' = skip. Missing/extra chars default to run.
+ */
+function buildMaskFromBits(
+	bits: string,
+	layoutCount: number,
+): { page: boolean; layouts: boolean[] } {
+	const page = bits[0] !== "0";
+	const layouts: boolean[] = [];
+	for (let i = 0; i < layoutCount; i++) {
+		const c = bits[i + 1];
+		layouts.push(c !== "0");
+	}
+	return { page, layouts };
+}
+
 /** Extract action name from URL searchParams — `?/login` → "login", no slash key → "default". */
 function parseActionName(url: URL): string {
 	for (const key of url.searchParams.keys()) {
@@ -146,15 +163,41 @@ async function resolve(event: RequestEvent): Promise<Response> {
 			return Response.json({ error: "Invalid path", status: 400 }, { status: 400 });
 		}
 		const routeUrl = new URL(routePathStr, url.origin);
+		let invalidatedBits: string | null = null;
 		for (const [key, val] of url.searchParams.entries()) {
+			if (key === "_invalidated") {
+				invalidatedBits = val;
+				continue;
+			}
 			routeUrl.searchParams.append(key, val);
 		}
 		// Rewrite event.url so logging middleware sees the real page path, not /__bosia/data
 		event.url = routeUrl;
 		try {
 			const pageMatch = findMatch(serverRoutes, routeUrl.pathname);
+			// Build mask from `?_invalidated=<bits>` where char 0 = page,
+			// char i+1 = layout depth i, '1' = run, '0' = skip. Absent → run all.
+			// Mask is sized to the total layout count (matching client `layoutIds`),
+			// not the count of layout servers, so depths without a server loader
+			// still occupy a bit position and stay aligned with the client.
+			const mask = invalidatedBits
+				? buildMaskFromBits(
+						invalidatedBits,
+						pageMatch?.route
+							? ((pageMatch.route as any).layoutModules?.length ?? 0)
+							: 0,
+					)
+				: undefined;
 			const runLoad = async () => {
-				const data = await loadRouteData(routeUrl, locals, request, cookies);
+				const data = await loadRouteData(
+					routeUrl,
+					locals,
+					request,
+					cookies,
+					null,
+					pageMatch,
+					mask,
+				);
 
 				let metadata = null;
 				if (pageMatch) {
@@ -176,12 +219,17 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				return { data, metadata, cookiesAccessed: (cookies as CookieJar).accessed };
 			};
 
-			// Dedup public routes by URL only. `(private)` scope routes (per-user content)
-			// skip the cache to prevent cross-user data leaks. See dedup.ts.
+			// Dedup public routes by URL + mask. `(private)` scope routes (per-user
+			// content) skip the cache to prevent cross-user data leaks. The mask is
+			// part of the key so concurrent requests for the same URL with different
+			// invalidation patterns don't collapse onto each other. See dedup.ts.
+			const dedupK = invalidatedBits
+				? `${dedupKey(routeUrl)}|m=${invalidatedBits}`
+				: dedupKey(routeUrl);
 			const result =
 				pageMatch?.route.scope === "private"
 					? await runLoad()
-					: await dedup(dedupKey(routeUrl), runLoad);
+					: await dedup(dedupK, runLoad);
 
 			const cookiesWereAccessed = (cookies as CookieJar).accessed || result.cookiesAccessed;
 			const cc = cookiesWereAccessed

package/src/lib/client.ts

@@ -10,3 +10,4 @@
 
 export { enhance } from "../core/client/enhance.ts";
 export type { SubmitFunction, ActionResult } from "../core/client/enhance.ts";
+export { invalidate, invalidateAll } from "../core/client/navigation.ts";

package/src/lib/index.ts

@@ -10,6 +10,7 @@ export type { HttpError, Redirect, RedirectOptions, ActionFailure } from "../cor
 export type {
 	RequestEvent,
 	LoadEvent,
+	LoaderDeps,
 	MetadataEvent,
 	Metadata,
 	Handle,