bosia 0.8.6 → 0.8.7

package/package.json

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

package/src/core/cache.ts

@@ -350,18 +350,20 @@ export function coalesceMiss(
 
 export function serveCached(entry: CacheEntry, req: Request): Response {
 	const accept = req.headers.get("accept-encoding") ?? "";
+	// Base keys lowercased so lowercased extraHeaders (e.g. loader setHeaders)
+	// override them instead of getting comma-joined by Headers.
 	const headers: Record<string, string> = {
-		"Content-Type": entry.contentType,
-		Vary: "Accept-Encoding",
-		"X-Bosia-Cache": "HIT",
+		"content-type": entry.contentType,
+		vary: "Accept-Encoding",
+		"x-bosia-cache": "HIT",
 		...entry.extraHeaders,
 	};
 	if (entry.brotli && accept.includes("br")) {
-		headers["Content-Encoding"] = "br";
+		headers["content-encoding"] = "br";
 		return new Response(entry.brotli, { status: entry.status, headers });
 	}
 	if (entry.gzip && accept.includes("gzip")) {
-		headers["Content-Encoding"] = "gzip";
+		headers["content-encoding"] = "gzip";
 		return new Response(entry.gzip, { status: entry.status, headers });
 	}
 	return new Response(entry.raw, { status: entry.status, headers });

package/src/core/client/App.svelte

@@ -34,6 +34,24 @@
 
 	let PageComponent = $state<any>(ssrPageComponent);
 	let layoutComponents = $state<any[]>(ssrLayoutComponents ?? []);
+	// Mounted page instance — the two <PageComponent> render spots are mutually
+	// exclusive branches, so one ref suffices. Exposes `export const snapshot`.
+	let pageInstance = $state<any>(null);
+	if (!ssrMode) router.getPageSnapshot = () => pageInstance?.snapshot;
+
+	// Call the landed-on page's snapshot.restore() once it's mounted (post-tick).
+	function settleSnapshot() {
+		const snap = router.pendingSnapshot;
+		if (snap !== undefined)
+			tick().then(() => {
+				try {
+					pageInstance?.snapshot?.restore?.(snap);
+				} catch {
+					// user restore() threw — never break navigation
+				}
+			});
+		router.pendingSnapshot = undefined;
+	}
 	// Network protocol still ships `params` merged into pageData (see renderer.ts).
 	// Strip it at the component boundary so consumers receive `params` only via
 	// the dedicated prop, matching SvelteKit's surface.
@@ -75,12 +93,13 @@
 			});
 		} else if (!router.isPush) {
 			const pos = router.pendingScroll;
-			// ponytail: single post-tick restore; content that loads later (images
+			// single post-tick restore; content that loads later (images
 			// without dimensions) can still shift it. Revisit only if reported.
 			if (pos) tick().then(() => window.scrollTo(pos.x, pos.y));
 		}
 		router.pendingScroll = null;
 		router.suppressScroll = false;
+		settleSnapshot();
 	}
 
 	$effect(() => {
@@ -102,6 +121,8 @@
 		if (isFirst) {
 			currentLayoutPaths = (match.route as any).layoutPaths ?? [];
 			lastSettledPath = pathname;
+			// Restore-after-reload: router.init() staged this entry's snapshot.
+			settleSnapshot();
 			return; // Initial hydration — data already in SSR props, no fetch needed
 		}
 
@@ -404,7 +425,7 @@
 {:else if layoutComponents.length > 0}
 	{@render renderLayout(0, layoutComponents.length)}
 {:else if PageComponent}
-	<PageComponent data={pageData} {params} form={formData} />
+	<PageComponent bind:this={pageInstance} data={pageData} {params} form={formData} />
 {:else}
 	<p>Loading...</p>
 {/if}
@@ -434,7 +455,7 @@
 			{#if ErrorComponent}
 				<ErrorComponent {...errorProps ?? {}} />
 			{:else if PageComponent}
-				<PageComponent data={pageData} {params} form={formData} />
+				<PageComponent bind:this={pageInstance} data={pageData} {params} form={formData} />
 			{:else}
 				<p>Loading...</p>
 			{/if}

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

@@ -30,6 +30,24 @@ function saveScroll() {
 	scrollPositions[historyIndex] = { x: window.scrollX, y: window.scrollY };
 }
 
+// ─── Page snapshots ───
+// `export const snapshot = { capture, restore }` in +page.svelte. Captured
+// alongside scroll on every history mutation, keyed by the same bosiaIndex,
+// restored post-tick by App.svelte. Values must be JSON-serializable — raw in
+// memory, stringified only at the unload flush.
+// page-only; layout snapshots need per-depth instance refs — add if asked.
+const SNAPSHOT_KEY = "bosia:snapshot";
+let pageSnapshots: Record<number, unknown> = {};
+
+function savePageSnapshot() {
+	try {
+		const s = router.getPageSnapshot?.();
+		if (s?.capture) pageSnapshots[historyIndex] = s.capture();
+	} catch {
+		// user capture() threw — never break navigation
+	}
+}
+
 export function scrollToHash(hash: string): boolean {
 	if (typeof document === "undefined" || !hash) return false;
 	const raw = hash.startsWith("#") ? hash.slice(1) : hash;
@@ -61,6 +79,12 @@ export const router = new (class Router {
 	suppressScroll = false;
 	/** Saved scroll position for the entry a popstate landed on; consumed once by App.svelte after the nav settles. */
 	pendingScroll: { x: number; y: number } | null = null;
+	/** Set by App.svelte; returns the mounted page's `export const snapshot` (if any) at capture time. */
+	getPageSnapshot:
+		| (() => { capture: () => unknown; restore: (v: any) => void } | undefined)
+		| null = null;
+	/** Captured snapshot for the entry a popstate/reload landed on; consumed once by App.svelte. `undefined` = nothing to restore. */
+	pendingSnapshot: unknown = undefined;
 
 	navigate(path: string, opts: { replace?: boolean; source?: NavType } = {}) {
 		if (this.currentRoute === path) return;
@@ -91,12 +115,14 @@ export const router = new (class Router {
 		this.lastNavType = navType;
 		this.isPush = true;
 		this.pendingScroll = null;
+		this.pendingSnapshot = undefined;
 		this.currentRoute = finalPath;
 		if (typeof history !== "undefined") {
 			if (opts.replace) {
 				history.replaceState({ bosiaIndex: historyIndex }, "", finalPath);
 			} else {
 				saveScroll();
+				savePageSnapshot();
 				historyIndex++;
 				history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 			}
@@ -112,8 +138,14 @@ export const router = new (class Router {
 		} catch {
 			scrollPositions = {};
 		}
+		try {
+			pageSnapshots = JSON.parse(sessionStorage.getItem(SNAPSHOT_KEY) ?? "{}");
+		} catch {
+			pageSnapshots = {};
+		}
 		const stamped = history.state?.bosiaIndex != null;
 		historyIndex = stamped ? history.state.bosiaIndex : 0;
+		this.pendingSnapshot = stamped ? pageSnapshots[historyIndex] : undefined;
 		history.replaceState({ ...history.state, bosiaIndex: historyIndex }, "");
 		// Restore after a reload — manual mode means the browser won't. Only for
 		// entries we stamped before (a fresh visit has no bosiaIndex in state).
@@ -146,6 +178,7 @@ export const router = new (class Router {
 				const finalPath = anchor.pathname + anchor.search + anchor.hash;
 				if (this.currentRoute !== finalPath) {
 					saveScroll();
+					savePageSnapshot();
 					historyIndex++;
 					history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 					this.currentRoute = finalPath;
@@ -164,8 +197,10 @@ export const router = new (class Router {
 			// Save the position of the entry we're leaving (historyIndex is still
 			// the old entry's), then look up where the landed-on entry was.
 			saveScroll();
+			savePageSnapshot();
 			historyIndex = e.state?.bosiaIndex ?? 0;
 			this.pendingScroll = scrollPositions[historyIndex] ?? null;
+			this.pendingSnapshot = pageSnapshots[historyIndex];
 			// Fire beforeNavigate listeners; popstate can't be reliably cancelled
 			// (browser history already advanced), so we surface the event for
 			// observation only — `cancel()` is a no-op for this source.
@@ -189,14 +224,21 @@ export const router = new (class Router {
 		// listeners can warn-on-leave (return value ignored; cancellation here
 		// requires `beforeunload`, not in scope).
 		window.addEventListener("beforeunload", () => {
-			// ponytail: beforeunload can be skipped on mobile page-discard; add a
+			// beforeunload can be skipped on mobile page-discard; add a
 			// visibilitychange persist if restore-after-reload proves flaky there.
 			saveScroll();
+			savePageSnapshot();
 			try {
 				sessionStorage.setItem(SCROLL_KEY, JSON.stringify(scrollPositions));
 			} catch {
 				// sessionStorage unavailable (private mode / quota) — skip persistence.
 			}
+			try {
+				// Separate try: a non-JSON-serializable snapshot must not kill scroll persistence.
+				sessionStorage.setItem(SNAPSHOT_KEY, JSON.stringify(pageSnapshots));
+			} catch {
+				// sessionStorage unavailable or snapshot not serializable — skip persistence.
+			}
 			const fromTarget = buildTarget(this.currentRoute);
 			const nav: Navigation = {
 				from: fromTarget,

package/src/core/dev.ts

@@ -265,7 +265,7 @@ let buildPending = false;
 async function buildAndRestart(): Promise<boolean> {
 	if (building) {
 		buildPending = true;
-		// ponytail: coalesced into the in-flight build. Managed mode fires one
+		// coalesced into the in-flight build. Managed mode fires one
 		// rebuild per turn so overlap is rare; report optimistic rather than a
 		// false build failure to the host.
 		return true;

package/src/core/hooks.ts

@@ -63,8 +63,38 @@ export type LoadEvent = {
 	 * namespaced (e.g. `"app:user"`).
 	 */
 	depends: (...keys: string[]) => void;
+	/**
+	 * Set response headers for this request. Headers accumulate across
+	 * layout and page loaders and land on both the SSR HTML response and
+	 * the client-navigation data response. Setting the same header twice
+	 * throws, as does `set-cookie` (use the `cookies` API instead).
+	 * No-op during prerendering (only bodies are written to disk).
+	 */
+	setHeaders: (headers: Record<string, string>) => void;
 };
 
+/**
+ * Build a `setHeaders` closure over a shared accumulator. Keys are stored
+ * lowercased; duplicates (any casing) and `set-cookie` throw. Shared across
+ * all loaders of one request so cross-loader duplicates are caught too.
+ */
+export function makeSetHeaders(
+	acc: Record<string, string>,
+): (headers: Record<string, string>) => void {
+	return (headers) => {
+		for (const [key, value] of Object.entries(headers)) {
+			const k = key.toLowerCase();
+			if (k === "set-cookie") {
+				throw new Error('setHeaders() cannot set "set-cookie" — use the cookies API instead');
+			}
+			if (k in acc) {
+				throw new Error(`setHeaders() called twice for header "${k}"`);
+			}
+			acc[k] = value;
+		}
+	};
+}
+
 /**
  * Tracked dependencies captured for a single loader during one run.
  * Shipped to the client so subsequent client-side navigations can

package/src/core/html.ts

@@ -373,9 +373,11 @@ export function compress(
 	status = 200,
 	extraHeaders?: Record<string, string>,
 ): Response {
+	// Base keys lowercased so lowercased extraHeaders (e.g. loader setHeaders)
+	// override them instead of getting comma-joined by Headers.
 	const headers: Record<string, string> = {
-		"Content-Type": contentType,
-		Vary: "Accept-Encoding",
+		"content-type": contentType,
+		vary: "Accept-Encoding",
 		...extraHeaders,
 	};
 	const accept = req.headers.get("accept-encoding") ?? "";
@@ -385,7 +387,7 @@ export function compress(
 	if (!isDev && bytes.length > GZIP_MIN_BYTES && accept.includes("gzip")) {
 		return new Response(Bun.gzipSync(bytes), {
 			status,
-			headers: { ...headers, "Content-Encoding": "gzip" },
+			headers: { ...headers, "content-encoding": "gzip" },
 		});
 	}
 	return new Response(bytes, { status, headers });

package/src/core/renderer.ts

@@ -3,6 +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 { makeSetHeaders } from "./hooks.ts";
 import type { Cookies, LoaderDeps } from "./hooks.ts";
 import { CSP_ENABLED } from "./csp.ts";
 import {
@@ -333,6 +334,10 @@ export async function loadRouteData(
 	const layoutData: (Record<string, any> | null)[] = [];
 	const layoutDeps: (LoaderDeps | null)[] = [];
 	let parentData: Record<string, any> = {};
+	// Shared across layout + page loaders so cross-loader duplicate
+	// setHeaders() calls throw. Keys stored lowercased.
+	const loaderHeaders: Record<string, string> = {};
+	const setHeaders = makeSetHeaders(loaderHeaders);
 
 	// Run layout server loaders root → leaf, each gets parent() data
 	for (const ls of route.layoutServers) {
@@ -366,6 +371,7 @@ export async function loadRouteData(
 							fetch: trackedFetch(fetch, origin, deps),
 							metadata: null,
 							depends: makeDepends(deps),
+							setHeaders,
 						}),
 						LOAD_TIMEOUT,
 						`layout load (depth=${ls.depth}, ${url.pathname})`,
@@ -431,6 +437,7 @@ export async function loadRouteData(
 							fetch: trackedFetch(fetch, origin, deps),
 							metadata: metadataData,
 							depends: makeDepends(deps),
+							setHeaders,
 						}),
 						LOAD_TIMEOUT,
 						`page load (${url.pathname})`,
@@ -472,7 +479,7 @@ export async function loadRouteData(
 	// 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 };
+	return { pageData: pageOut, layoutData, csr, ssr, pageDeps, layoutDeps, loaderHeaders };
 }
 
 // ─── Metadata Loader ─────────────────────────────────────
@@ -690,7 +697,7 @@ export async function renderSSRStream(
 					appHtmlSegments,
 				);
 			return new Response(html, {
-				headers: { "Content-Type": "text/html; charset=utf-8" },
+				headers: { "content-type": "text/html; charset=utf-8", ...data.loaderHeaders },
 			});
 		}
 
@@ -773,7 +780,7 @@ export async function renderSSRStream(
 								brotli,
 								contentType: "text/html; charset=utf-8",
 								status: 200,
-								extraHeaders: {},
+								extraHeaders: data.loaderHeaders,
 								tags,
 							},
 							cookies,
@@ -812,7 +819,7 @@ export async function renderSSRStream(
 		});
 
 		return new Response(stream, {
-			headers: { "Content-Type": "text/html; charset=utf-8" },
+			headers: { "content-type": "text/html; charset=utf-8", ...data.loaderHeaders },
 		});
 	} finally {
 		releaseMiss?.();
@@ -894,7 +901,7 @@ export async function renderPageWithFormData(
 			undefined,
 			appHtmlSegments,
 		);
-		return compress(html, "text/html; charset=utf-8", req, status);
+		return compress(html, "text/html; charset=utf-8", req, status, data.loaderHeaders);
 	}
 
 	const { body, head } = render(App, {
@@ -923,7 +930,7 @@ export async function renderPageWithFormData(
 		undefined,
 		appHtmlSegments,
 	);
-	return compress(html, "text/html; charset=utf-8", req, status);
+	return compress(html, "text/html; charset=utf-8", req, status, data.loaderHeaders);
 }
 
 // ─── Error Page Renderer ──────────────────────────────────

package/src/core/routeTypes.ts

@@ -86,6 +86,14 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		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(
+			`/** \`export const snapshot: Snapshot<T>\` in +page.svelte — captured on nav-away,`,
+		);
+		lines.push(` *  restored on back/forward. Values must be JSON-serializable. */`);
+		lines.push(
+			`export type Snapshot<T = any> = { capture: () => T; restore: (snapshot: T) => void };`,
+		);
+		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

@@ -314,12 +314,18 @@ async function resolve(event: RequestEvent): Promise<Response> {
 					{ "Cache-Control": cc },
 				);
 			}
+			// loaderHeaders must not leak into the JSON body the client router consumes.
+			const { loaderHeaders = {}, ...payload } = result.data;
+			const extra: Record<string, string> = { "cache-control": cc, ...loaderHeaders };
+			// Privacy beats intent: cookie-derived responses stay private even if
+			// a loader set its own cache-control.
+			if (cookiesWereAccessed) extra["cache-control"] = cc;
 			return compress(
-				JSON.stringify({ ...result.data, metadata: result.metadata }),
+				JSON.stringify({ ...payload, metadata: result.metadata }),
 				"application/json",
 				request,
 				200,
-				{ "Cache-Control": cc },
+				extra,
 			);
 		} catch (err) {
 			if (err instanceof Redirect) {

package/src/lib/client.ts

@@ -18,4 +18,7 @@ export {
 	invalidateAll,
 } from "../core/client/navigation.ts";
 export type { GotoOptions, Navigation, NavigationTarget } from "../core/client/navigation.ts";
+/** `export const snapshot: Snapshot<T>` in +page.svelte — captured on nav-away,
+ *  restored on back/forward. Values must be JSON-serializable. */
+export type Snapshot<T = any> = { capture: () => T; restore: (snapshot: T) => void };
 export { page } from "../core/client/page.svelte.ts";