bosia 0.8.5 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.8.5",
+	"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.
@@ -63,6 +81,27 @@
 	let firstNav = true;
 	let navDoneTimer: ReturnType<typeof setTimeout> | null = null;
 
+	// Scroll after a nav settles: forward navs go to top (or the URL hash);
+	// back/forward navs restore the position saved for that history entry.
+	// Runs after tick() so the destination page's real height is in the DOM.
+	// goto({ noScroll: true }) flips `router.suppressScroll` for one nav.
+	function settleScroll() {
+		if (router.isPush && !router.suppressScroll) {
+			const hash = window.location.hash;
+			tick().then(() => {
+				if (!scrollToHash(hash)) window.scrollTo(0, 0);
+			});
+		} else if (!router.isPush) {
+			const pos = router.pendingScroll;
+			// 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(() => {
 		if (ssrMode) return;
 
@@ -82,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
 		}
 
@@ -247,13 +288,7 @@
 					appState.errorComponent = errMod.default;
 					appState.errorProps = { error: { status: errStatus, message: errMessage } };
 					appState.errorDepth = K;
-					if (router.isPush && !router.suppressScroll) {
-						const hash = window.location.hash;
-						tick().then(() => {
-							if (!scrollToHash(hash)) window.scrollTo(0, 0);
-						});
-					}
-					router.suppressScroll = false;
+					settleScroll();
 					settle({ url, params: match.params });
 				} catch {
 					window.location.href = path;
@@ -342,16 +377,7 @@
 			appState.errorProps = null;
 			appState.errorDepth = null;
 
-			// Scroll to top on forward navigation (not on popstate/back-forward).
-			// goto({ noScroll: true }) flips `router.suppressScroll` for one nav.
-			// If the destination URL has a hash, scroll to that element instead.
-			if (router.isPush && !router.suppressScroll) {
-				const hash = window.location.hash;
-				tick().then(() => {
-					if (!scrollToHash(hash)) window.scrollTo(0, 0);
-				});
-			}
-			router.suppressScroll = false;
+			settleScroll();
 
 			// Update document title and meta description from server metadata
 			if (result?.metadata) {
@@ -399,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}
@@ -429,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

@@ -16,6 +16,38 @@ function buildTarget(path: string): { url: URL; params: Record<string, string> }
 	return { url, params: match?.params ?? {} };
 }
 
+// ─── Scroll restoration ───
+// Positions keyed by a per-entry index stamped into `history.state.bosiaIndex`.
+// `scrollRestoration = "manual"` because the browser restores at popstate time,
+// before the SPA has rendered the destination page — it clamps against the
+// wrong document height. We restore ourselves after the nav settles (App.svelte).
+// Persisted to sessionStorage on unload so reload / back-into-app still restores.
+const SCROLL_KEY = "bosia:scroll";
+let scrollPositions: Record<number, { x: number; y: number }> = {};
+let historyIndex = 0;
+
+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;
@@ -45,6 +77,14 @@ export const router = new (class Router {
 	lastNavType: NavType = "enter";
 	/** Set by `goto({ noScroll: true })`; consumed once by App.svelte after the next nav settles. */
 	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;
@@ -74,12 +114,17 @@ 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({}, "", finalPath);
+				history.replaceState({ bosiaIndex: historyIndex }, "", finalPath);
 			} else {
-				history.pushState({}, "", finalPath);
+				saveScroll();
+				savePageSnapshot();
+				historyIndex++;
+				history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 			}
 		}
 	}
@@ -87,6 +132,28 @@ export const router = new (class Router {
 	init() {
 		if (typeof window === "undefined") return;
 
+		history.scrollRestoration = "manual";
+		try {
+			scrollPositions = JSON.parse(sessionStorage.getItem(SCROLL_KEY) ?? "{}");
+		} 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).
+		const initial = scrollPositions[historyIndex];
+		if (stamped && initial) {
+			requestAnimationFrame(() => window.scrollTo(initial.x, initial.y));
+		}
+
 		// Intercept <a> clicks for client-side navigation
 		window.addEventListener("click", (e) => {
 			// Let browser handle non-primary buttons, modifier-clicks, already-handled events
@@ -110,7 +177,10 @@ export const router = new (class Router {
 				e.preventDefault();
 				const finalPath = anchor.pathname + anchor.search + anchor.hash;
 				if (this.currentRoute !== finalPath) {
-					history.pushState({}, "", finalPath);
+					saveScroll();
+					savePageSnapshot();
+					historyIndex++;
+					history.pushState({ bosiaIndex: historyIndex }, "", finalPath);
 					this.currentRoute = finalPath;
 				}
 				scrollToHash(anchor.hash);
@@ -122,8 +192,15 @@ export const router = new (class Router {
 		});
 
 		// Browser back/forward
-		window.addEventListener("popstate", () => {
+		window.addEventListener("popstate", (e) => {
 			const finalPath = window.location.pathname + window.location.search + window.location.hash;
+			// 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.
@@ -147,6 +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", () => {
+			// 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/plugins/inspector/bun-plugin.ts

@@ -1,12 +1,10 @@
 import { parse, compile } from "svelte/compiler";
 import MagicString from "magic-string";
-import { basename, relative } from "node:path";
+import { relative } from "node:path";
 import type { BunPlugin } from "bun";
 import { svelteMapCache } from "../../svelteCompiler.ts";
 import { lineColFromOffset } from "../../sourceLoc.ts";
 
-const VIRTUAL_NS = "bosia-inspector-css";
-
 type AnyNode = {
 	type?: string;
 	name?: string;
@@ -124,7 +122,6 @@ const fnv = (s: string): string => {
 export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPlugin {
 	const { cwd, target, dev } = opts;
 	const generate: "client" | "server" = target === "browser" ? "client" : "server";
-	const virtualCss = new Map<string, string>();
 
 	return {
 		name: "bosia-inspector",
@@ -139,7 +136,11 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 					generate,
 					dev,
 					hmr: dev,
-					css: "external",
+					// Mirror the prod compiler (svelteCompiler.ts): client injects scoped
+					// CSS into the JS via `append_styles`, server discards it. No CSS
+					// chunks means Bun's `splitting:true` output-path collisions can't
+					// arise, so no runtime-injection workaround is needed.
+					css: generate === "client" ? "injected" : "external",
 					preserveWhitespace: dev,
 					preserveComments: dev,
 					cssHash: ({ css }) => `svelte-${fnv(css)}`,
@@ -164,39 +165,9 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 					svelteMapCache.set(args.path, m);
 				}
 
-				let js = dev ? fixBindShadow(result.js.code) : result.js.code;
-				// Inject component <style> blocks via runtime JS, not CSS chunks.
-				// Bun's `splitting: true` names CSS chunks after the importing JS
-				// chunk's `[name]`, not the virtual module's uid — so when several
-				// routes (e.g. multiple `+page.svelte`) transitively import the same
-				// styled component, each route emits its own CSS sidecar named
-				// `+page-<contentHash>.css`. Identical content → identical hash →
-				// "Multiple files share the same output path". Runtime injection
-				// avoids CSS chunking entirely.
-				if (result.css?.code?.trim() && generate !== "server") {
-					const safeBase = basename(args.path).replace(/\./g, "_");
-					const uid = `${safeBase}-${fnv(args.path)}-style.css`;
-					const virtualName = `${VIRTUAL_NS}:${uid}`;
-					virtualCss.set(virtualName, result.css.code);
-					js += `\nimport ${JSON.stringify(virtualName)};`;
-				}
-
+				const js = dev ? fixBindShadow(result.js.code) : result.js.code;
 				return { contents: js, loader: "ts" };
 			});
-
-			build.onResolve({ filter: new RegExp(`^${VIRTUAL_NS}:`) }, (args) => ({
-				path: args.path,
-				namespace: VIRTUAL_NS,
-			}));
-
-			build.onLoad({ filter: /.*/, namespace: VIRTUAL_NS }, (args) => {
-				const css = virtualCss.get(args.path) ?? "";
-				virtualCss.delete(args.path);
-				const contents = css
-					? `(()=>{const s=document.createElement('style');s.textContent=${JSON.stringify(css)};document.head.appendChild(s);})();`
-					: "";
-				return { contents, loader: "js" };
-			});
 		},
 	};
 }

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";