bosia 0.5.8 → 0.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.5.8",
+	"version": "0.5.10",
 	"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/cli/font.ts

@@ -0,0 +1,45 @@
+import { join } from "path";
+import { existsSync } from "fs";
+import { mergeFontImports } from "./fonts.ts";
+
+// ─── bun x bosia@latest add font <family> <url> ─────────────
+// Prepends a Google-Fonts-style `@import url(...)` to src/app.css
+// with a `/* bosia-font: <family> */` marker so it's idempotent
+// and survives Tailwind v4 / LightningCSS @import-ordering rules.
+//
+// Why a dedicated command: appending the @import at the bottom
+// (or anywhere after `@import "tailwindcss"`) causes LightningCSS
+// to silently drop the rule from public/bosia-tw.css. Hand-edits
+// frequently get this wrong; this command always prepends.
+
+export async function runAddFont(family: string | undefined, url: string | undefined) {
+	if (!family || !url) {
+		console.error(
+			"❌ Please provide a font family and URL.\n" +
+				'   Usage: bun x bosia@latest add font "<Family>" "<@import url>"\n' +
+				'   Example: bun x bosia@latest add font "Fredoka" \\\n' +
+				'            "https://fonts.googleapis.com/css2?family=Fredoka:wght@400;700&display=swap"',
+		);
+		process.exit(1);
+	}
+
+	const cwd = process.cwd();
+	const appCssPath = join(cwd, "src", "app.css");
+
+	if (!existsSync(appCssPath)) {
+		console.error(`❌ src/app.css not found at ${appCssPath}`);
+		process.exit(1);
+	}
+
+	const added = mergeFontImports(appCssPath, { [family]: url });
+
+	if (added.length === 0) {
+		console.log(`⬡ Font already present: ${family} (no changes)`);
+		return;
+	}
+
+	console.log(`✅ Added font: ${family}`);
+	console.log(`   ✍️  src/app.css ← @import url("${url}");`);
+	console.log("\n💡 Next: declare it on a token in src/app.css, e.g.");
+	console.log('   @theme { --font-display: "' + family + '", sans-serif; }');
+}

package/src/cli/index.ts

@@ -48,6 +48,9 @@ async function main() {
 				const themeFlags = args.filter((a) => a.startsWith("--"));
 				const { runAddTheme } = await import("./theme.ts");
 				await runAddTheme(positional[1], themeFlags);
+			} else if (sub === "font") {
+				const { runAddFont } = await import("./font.ts");
+				await runAddFont(positional[1], positional[2]);
 			} else {
 				const { runAdd } = await import("./add.ts");
 				await runAdd(positional, flags);
@@ -77,6 +80,7 @@ Commands:
   add <component...> [-y]   Add one or more UI components from the registry
   add block <cat>/<name>    Add a composed block from the registry
   add theme <name>          Add a theme (tokens.css) from the registry
+  add font <family> <url>   Prepend an @import url(...) for a font family to src/app.css
   feat <feature>            Add a feature scaffold from the registry [--local]
 
 Examples:
@@ -94,6 +98,7 @@ Examples:
   bun x bosia@latest add shop/cart           → src/lib/components/shop/cart/
   bun x bosia@latest add block cards/feature-editorial
   bun x bosia@latest add theme editorial
+  bun x bosia@latest add font "Fredoka" "https://fonts.googleapis.com/css2?family=Fredoka:wght@400;700&display=swap"
   bun x bosia@latest feat login
 `);
 			break;

package/src/core/appHtml.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+// ─── Types ────────────────────────────────────────────────
+
+export type AppHtmlSegments = {
+	headOpen: string;
+	headClose: string;
+	tail: string;
+	hasCustomFavicon: boolean;
+};
+
+// ─── Cached Singleton ─────────────────────────────────────
+
+let cachedSegments: AppHtmlSegments | undefined;
+
+// ─── Parse & Validate ─────────────────────────────────────
+
+export function loadAppHtmlTemplate(cwd: string = process.cwd()): AppHtmlSegments {
+	const templatePath = join(cwd, "src", "app.html");
+
+	if (!existsSync(templatePath)) {
+		throw new Error(
+			`src/app.html is required but not found. Create src/app.html with %bosia.head% and %bosia.body% placeholders.`,
+		);
+	}
+
+	let template = readFileSync(templatePath, "utf-8");
+
+	// Replace static placeholders at parse time
+	template = replaceStaticPlaceholders(template);
+
+	// Validate required placeholders
+	const missingPlaceholders: string[] = [];
+	if (!template.includes("%bosia.head%")) missingPlaceholders.push("%bosia.head%");
+	if (!template.includes("%bosia.body%")) missingPlaceholders.push("%bosia.body%");
+
+	if (missingPlaceholders.length > 0) {
+		throw new Error(
+			`src/app.html is missing required placeholder(s): ${missingPlaceholders.join(", ")}. ` +
+				`Both %bosia.head% and %bosia.body% must be present.`,
+		);
+	}
+
+	// Split into segments
+	const [headOpen, rest1] = template.split("%bosia.head%", 2);
+	const [headClose, tail] = rest1.split("%bosia.body%", 2);
+
+	// Check for custom favicon
+	const hasCustomFavicon = headOpen.includes('rel="icon"');
+
+	return {
+		headOpen,
+		headClose,
+		tail,
+		hasCustomFavicon,
+	};
+}
+
+function replaceStaticPlaceholders(template: string): string {
+	// Replace %bosia.assets% with BOSIA_ASSETS_BASE env var
+	const assetsBase = process.env.BOSIA_ASSETS_BASE || "";
+	template = template.replaceAll("%bosia.assets%", assetsBase);
+
+	// Replace %bosia.env.PUBLIC_FOO% with process.env.PUBLIC_FOO
+	template = template.replace(/%bosia\.env\.(PUBLIC_[A-Z0-9_]+)%/g, (_match, key: string) => {
+		return process.env[key] ?? "";
+	});
+
+	return template;
+}
+
+// ─── Cached Getter ────────────────────────────────────────
+
+export function getAppHtmlSegments(cwd: string = process.cwd()): AppHtmlSegments {
+	if (cachedSegments !== undefined) {
+		return cachedSegments;
+	}
+	cachedSegments = loadAppHtmlTemplate(cwd);
+	return cachedSegments;
+}
+
+// ─── Cache Invalidation ───────────────────────────────────
+
+export function invalidateAppHtmlCache(): void {
+	cachedSegments = undefined;
+}
+
+// ─── Runtime Interpolation ────────────────────────────────
+
+export function interpolateSegment(
+	segment: string,
+	vars: { nonce?: string; lang?: string },
+): string {
+	let result = segment;
+
+	if (vars.lang) {
+		result = result.replaceAll("%bosia.lang%", vars.lang);
+	}
+
+	if (vars.nonce) {
+		result = result.replaceAll("%bosia.nonce%", vars.nonce);
+	}
+
+	return result;
+}

package/src/core/build.ts

@@ -12,6 +12,7 @@ import { generateEnvModules } from "./envCodegen.ts";
 import { BOSIA_NODE_PATH, OUT_DIR, resolveBosiaBin } from "./paths.ts";
 import { loadPlugins } from "./config.ts";
 import type { BuildContext } from "./types/plugin.ts";
+import { loadAppHtmlTemplate } from "./appHtml.ts";
 
 // Resolved from this file's location inside the bosia package
 const CORE_DIR = import.meta.dir;
@@ -79,6 +80,20 @@ if (manifest.apis.length > 0) {
 	}
 }
 
+// 1b. Load & validate src/app.html template (required)
+let appHtml: any;
+try {
+	appHtml = loadAppHtmlTemplate(process.cwd());
+	console.log(
+		"📄 Loaded src/app.html (favicon override: " +
+			(appHtml.hasCustomFavicon ? "yes" : "no") +
+			")",
+	);
+} catch (err) {
+	console.error(`❌ src/app.html validation failed:\n${(err as Error).message}`);
+	process.exit(1);
+}
+
 for (const p of userPlugins) {
 	if (p.build?.postScan) {
 		await p.build.postScan(manifest, buildCtx);

package/src/core/client/App.svelte

@@ -6,6 +6,8 @@
 	import { appState, clearDirty } from "./appState.svelte.ts";
 	import { captureSnapshot, liveContext, shouldRerun, type CacheEntry } from "./loaderCache.ts";
 	import { pickErrorPage } from "../errorMatch.ts";
+	import { fireAfterNavigate, type Navigation } from "./navListeners.ts";
+	import { drainNavResolvers } from "./navigation.ts";
 
 	let {
 		ssrMode = false,
@@ -129,6 +131,18 @@
 						.catch(() => null)
 				: Promise.resolve(null);
 
+		const settle = (target: { url: URL; params: Record<string, string> } | null) => {
+			const nav: Navigation = {
+				from: null,
+				to: target,
+				type: router.lastNavType,
+				willUnload: false,
+				cancel: () => {},
+			};
+			fireAfterNavigate(nav);
+			drainNavResolvers();
+		};
+
 		Promise.all([
 			match.route.page(),
 			Promise.all(match.route.layouts.map((l: any) => l())),
@@ -184,7 +198,9 @@
 					appState.errorComponent = errMod.default;
 					appState.errorProps = { error: { status: errStatus, message: errMessage } };
 					appState.errorDepth = K;
-					if (router.isPush) window.scrollTo(0, 0);
+					if (router.isPush && !router.suppressScroll) window.scrollTo(0, 0);
+					router.suppressScroll = false;
+					settle({ url, params: match.params });
 				} catch {
 					window.location.href = path;
 				}
@@ -272,8 +288,10 @@
 			appState.errorProps = null;
 			appState.errorDepth = null;
 
-			// Scroll to top on forward navigation (not on popstate/back-forward)
-			if (router.isPush) window.scrollTo(0, 0);
+			// Scroll to top on forward navigation (not on popstate/back-forward).
+			// goto({ noScroll: true }) flips `router.suppressScroll` for one nav.
+			if (router.isPush && !router.suppressScroll) window.scrollTo(0, 0);
+			router.suppressScroll = false;
 
 			// Update document title and meta description from server metadata
 			if (result?.metadata) {
@@ -290,6 +308,8 @@
 					meta.content = result.metadata.description;
 				}
 			}
+
+			settle({ url, params: match.params });
 		});
 
 		return () => {

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

@@ -38,6 +38,10 @@ class AppState {
 	// 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);
+	// Resolvers waiting for the next navigation to settle. Drained by
+	// App.svelte after each nav effect finishes (success or error). Used by
+	// `goto()` to return a Promise that mirrors SvelteKit's contract.
+	navResolvers: Array<() => void> = [];
 }
 
 export const appState = new AppState();

package/src/core/client/hydrate.ts

@@ -130,7 +130,11 @@ async function main() {
 	}
 }
 
-main();
+main().catch((err) => {
+	// Without this, a hydration failure leaves "Loading..." stuck on screen
+	// with no console signal. Surface it loudly instead.
+	console.error("[bosia] hydration failed", err);
+});
 
 // ─── Hot Reload (dev only) ────────────────────────────────
 

package/src/core/client/navListeners.ts

@@ -0,0 +1,51 @@
+// ─── Navigation lifecycle registry ────────────────────────
+// Shared listener storage for `beforeNavigate` / `afterNavigate`. Kept in a
+// dedicated module so `router.svelte.ts` can fire events without importing
+// `navigation.ts` (which transitively imports the router — would deadlock
+// the ESM evaluation cycle).
+
+export interface NavigationTarget {
+	url: URL;
+	params: Record<string, string>;
+}
+
+export interface Navigation {
+	from: NavigationTarget | null;
+	to: NavigationTarget | null;
+	type: "link" | "goto" | "popstate" | "form" | "enter";
+	willUnload: boolean;
+	cancel: () => void;
+}
+
+export type BeforeNavigateCallback = (nav: Navigation) => void | Promise<void>;
+export type AfterNavigateCallback = (nav: Navigation) => void;
+
+export const beforeListeners = new Set<BeforeNavigateCallback>();
+export const afterListeners = new Set<AfterNavigateCallback>();
+
+/** Returns true when navigation should proceed, false when a listener cancelled it. */
+export function fireBeforeNavigate(nav: Navigation): boolean {
+	let cancelled = false;
+	nav.cancel = () => {
+		cancelled = true;
+	};
+	for (const fn of beforeListeners) {
+		try {
+			fn(nav);
+		} catch (err) {
+			console.warn("[bosia] beforeNavigate listener threw", err);
+		}
+		if (cancelled) return false;
+	}
+	return true;
+}
+
+export function fireAfterNavigate(nav: Navigation): void {
+	for (const fn of afterListeners) {
+		try {
+			fn(nav);
+		} catch (err) {
+			console.warn("[bosia] afterNavigate listener threw", err);
+		}
+	}
+}

package/src/core/client/navigation.ts

@@ -10,10 +10,47 @@
 //   await invalidate((url) => url.pathname.startsWith("/api/"));
 //   await invalidateAll();
 
+import { onDestroy } from "svelte";
 import { appState } from "./appState.svelte.ts";
+import { router } from "./router.svelte.ts";
+import {
+	afterListeners,
+	beforeListeners,
+	type AfterNavigateCallback,
+	type BeforeNavigateCallback,
+} from "./navListeners.ts";
 
 type InvalidateTarget = string | URL | ((url: URL) => boolean);
 
+export type { Navigation, NavigationTarget } from "./navListeners.ts";
+
+/**
+ * Register a callback that runs before each client-side navigation. The
+ * callback may call `nav.cancel()` to block the navigation. Auto-unregisters
+ * when the calling Svelte component is destroyed.
+ */
+export function beforeNavigate(fn: BeforeNavigateCallback): void {
+	beforeListeners.add(fn);
+	try {
+		onDestroy(() => beforeListeners.delete(fn));
+	} catch {
+		// Not inside a component — caller is responsible for lifetime.
+	}
+}
+
+/**
+ * Register a callback that runs after each client-side navigation settles.
+ * Auto-unregisters when the calling Svelte component is destroyed.
+ */
+export function afterNavigate(fn: AfterNavigateCallback): void {
+	afterListeners.add(fn);
+	try {
+		onDestroy(() => afterListeners.delete(fn));
+	} catch {
+		// Not inside a component — caller is responsible for lifetime.
+	}
+}
+
 function bumpTick() {
 	appState.invalidationTick = appState.invalidationTick + 1;
 }
@@ -57,3 +94,65 @@ export function invalidateAll(): Promise<void> {
 	bumpTick();
 	return Promise.resolve();
 }
+
+// ─── goto ─────────────────────────────────────────────────
+// Programmatic SPA navigation. Counterpart to SvelteKit's `goto()`.
+//
+// Usage:
+//   import { goto } from "bosia/client";
+//   await goto("/dashboard");
+//   await goto("/login", { replaceState: true, invalidateAll: true });
+
+export interface GotoOptions {
+	/** Use `history.replaceState` instead of `history.pushState`. */
+	replaceState?: boolean;
+	/** Mark every loader dirty so the next nav re-runs all of them. */
+	invalidateAll?: boolean;
+	/** Skip the default scroll-to-top after navigation. */
+	noScroll?: boolean;
+	/** Reserved — not yet honored by the framework. */
+	keepFocus?: boolean;
+	/** Reserved — not yet honored (no shallow routing). */
+	state?: Record<string, unknown>;
+}
+
+/**
+ * Navigate to `url` via the client router. Returns a Promise that resolves
+ * after the navigation has settled (loaders ran, components mounted) or
+ * immediately if the URL matches the current route.
+ */
+export function goto(url: string, opts: GotoOptions = {}): Promise<void> {
+	if (typeof window === "undefined") return Promise.resolve();
+
+	if (opts.invalidateAll) {
+		appState.dirty.all = true;
+	}
+	if (opts.noScroll) {
+		router.suppressScroll = true;
+	}
+
+	const beforePath = router.currentRoute;
+
+	return new Promise<void>((resolve) => {
+		appState.navResolvers.push(resolve);
+		router.navigate(url, { replace: opts.replaceState, source: "goto" });
+		// `navigate()` short-circuits when `currentRoute === path` — the nav
+		// effect won't fire, so nothing will drain the resolver. Resolve now.
+		if (router.currentRoute === beforePath) {
+			drainNavResolvers();
+		}
+	});
+}
+
+/** Internal — App.svelte calls this after each nav effect settles. */
+export function drainNavResolvers(): void {
+	const queue = appState.navResolvers;
+	appState.navResolvers = [];
+	for (const fn of queue) {
+		try {
+			fn();
+		} catch (err) {
+			console.warn("[bosia] navResolver threw", err);
+		}
+	}
+}

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

@@ -4,6 +4,17 @@
 
 import { findMatch, canonicalPathname } from "../matcher.ts";
 import { clientRoutes } from "bosia:routes";
+import { fireBeforeNavigate, type Navigation } from "./navListeners.ts";
+
+export type NavType = "link" | "goto" | "popstate" | "form" | "enter";
+
+function buildTarget(path: string): { url: URL; params: Record<string, string> } | null {
+	if (typeof window === "undefined") return null;
+	const pathname = path.split("?")[0].split("#")[0];
+	const match = findMatch(clientRoutes, pathname);
+	const url = new URL(path, window.location.origin);
+	return { url, params: match?.params ?? {} };
+}
 
 export const router = new (class Router {
 	currentRoute = $state(
@@ -14,8 +25,12 @@ export const router = new (class Router {
 	params = $state<Record<string, string>>({});
 	/** True when navigation was triggered by a link click / navigate() call, false on popstate (back/forward). */
 	isPush = $state(true);
+	/** Source of the most recent navigation — feeds the Navigation object passed to lifecycle hooks. */
+	lastNavType: NavType = "enter";
+	/** Set by `goto({ noScroll: true })`; consumed once by App.svelte after the next nav settles. */
+	suppressScroll = false;
 
-	navigate(path: string) {
+	navigate(path: string, opts: { replace?: boolean; source?: NavType } = {}) {
 		if (this.currentRoute === path) return;
 		// Unknown route — let the server handle it (renders +error.svelte with 404)
 		const queryHash = path.slice(path.split("?")[0].split("#")[0].length);
@@ -31,10 +46,28 @@ export const router = new (class Router {
 			(match.route as any).trailingSlash ?? "never",
 		);
 		const finalPath = canonical !== null ? canonical + queryHash : path;
+
+		const navType: NavType = opts.source ?? "link";
+		const fromTarget = buildTarget(this.currentRoute);
+		const toTarget = buildTarget(finalPath);
+		const nav: Navigation = {
+			from: fromTarget,
+			to: toTarget,
+			type: navType,
+			willUnload: false,
+			cancel: () => {},
+		};
+		if (!fireBeforeNavigate(nav)) return;
+
+		this.lastNavType = navType;
 		this.isPush = true;
 		this.currentRoute = finalPath;
 		if (typeof history !== "undefined") {
-			history.pushState({}, "", finalPath);
+			if (opts.replace) {
+				history.replaceState({}, "", finalPath);
+			} else {
+				history.pushState({}, "", finalPath);
+			}
 		}
 	}
 
@@ -57,14 +90,45 @@ export const router = new (class Router {
 			if (anchor.protocol !== "https:" && anchor.protocol !== "http:") return;
 
 			e.preventDefault();
-			this.navigate(anchor.pathname + anchor.search + anchor.hash);
+			this.navigate(anchor.pathname + anchor.search + anchor.hash, { source: "link" });
 		});
 
 		// Browser back/forward
 		window.addEventListener("popstate", () => {
-			this.isPush = false;
-			this.currentRoute =
+			const finalPath =
 				window.location.pathname + window.location.search + window.location.hash;
+			// 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.
+			const fromTarget = buildTarget(this.currentRoute);
+			const toTarget = buildTarget(finalPath);
+			const nav: Navigation = {
+				from: fromTarget,
+				to: toTarget,
+				type: "popstate",
+				willUnload: false,
+				cancel: () => {},
+			};
+			fireBeforeNavigate(nav);
+
+			this.lastNavType = "popstate";
+			this.isPush = false;
+			this.currentRoute = finalPath;
+		});
+
+		// Full-page unload — fire beforeNavigate with willUnload=true so
+		// listeners can warn-on-leave (return value ignored; cancellation here
+		// requires `beforeunload`, not in scope).
+		window.addEventListener("beforeunload", () => {
+			const fromTarget = buildTarget(this.currentRoute);
+			const nav: Navigation = {
+				from: fromTarget,
+				to: null,
+				type: "link",
+				willUnload: true,
+				cancel: () => {},
+			};
+			fireBeforeNavigate(nav);
 		});
 	}
 })();

package/src/core/html.ts

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from "fs";
 import { getDeclaredEnvKeys } from "./env.ts";
 import { nonceAttr } from "./csp.ts";
 import { OUT_DIR } from "./paths.ts";
+import type { AppHtmlSegments } from "./appHtml.ts";
+import { interpolateSegment } from "./appHtml.ts";
 
 // ─── Dist Manifest ───────────────────────────────────────
 // Maps hashed filenames → script/link tags.
@@ -98,6 +100,7 @@ export function buildHtml(
 	pageDeps: any = null,
 	layoutDeps: any[] | null = null,
 	bodyEndExtras?: string[],
+	segments?: AppHtmlSegments,
 ): string {
 	const cssLinks = (distManifest.css ?? [])
 		.map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
@@ -138,6 +141,31 @@ export function buildHtml(
 
 	const bodyEnd = bodyEndExtras?.length ? "\n  " + bodyEndExtras.join("\n  ") : "";
 
+	if (segments) {
+		const safeKey = safeLang(lang);
+		const headOpenInterpolated = interpolateSegment(segments.headOpen, {
+			lang: safeKey,
+			nonce,
+		});
+		const headCloseInterpolated = interpolateSegment(segments.headClose, { nonce });
+		const tailInterpolated = interpolateSegment(segments.tail, { nonce });
+		const faviconLine = segments.hasCustomFavicon
+			? ""
+			: `  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n`;
+
+		return (
+			headOpenInterpolated +
+			`\n  ${faviconLine}${cssLinks}\n` +
+			`  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">\n` +
+			`  <script${n}>try{var t=localStorage.getItem('theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme: dark)').matches))document.documentElement.classList.add('dark');else document.documentElement.classList.remove('dark')}catch(_){}</script>\n` +
+			`  ${fallbackTitle}${head}` +
+			headCloseInterpolated +
+			`\n${SPINNER}` +
+			`\n  <div id="app">${body}</div>${scripts}${bodyEnd}` +
+			tailInterpolated
+		);
+	}
+
 	return `<!DOCTYPE html>
 <html lang="${safeLang(lang)}">
 <head>
@@ -161,12 +189,31 @@ export function buildHtml(
 import type { Metadata } from "./hooks.ts";
 
 /** Chunk 1: everything from <!DOCTYPE> through CSS/modulepreload links (head still open) */
-export function buildHtmlShellOpen(lang?: string, nonce?: string): string {
+export function buildHtmlShellOpen(
+	lang?: string,
+	nonce?: string,
+	segments?: AppHtmlSegments,
+): string {
 	const key = safeLang(lang);
 	const n = nonceAttr(nonce);
 	const cssLinks = (distManifest.css ?? [])
 		.map((f: string) => `<link rel="stylesheet" href="/dist/client/${f}">`)
 		.join("\n  ");
+
+	if (segments) {
+		const headOpenInterpolated = interpolateSegment(segments.headOpen, { lang: key, nonce });
+		const faviconLine = segments.hasCustomFavicon
+			? ""
+			: `  <link rel="icon" type="image/svg+xml" href="/favicon.svg">\n`;
+		return (
+			headOpenInterpolated +
+			`\n  ${faviconLine}${cssLinks}\n` +
+			`  <link rel="stylesheet" href="/bosia-tw.css${cacheBust}">\n` +
+			`  <script${n}>try{var t=localStorage.getItem('theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme: dark)').matches))document.documentElement.classList.add('dark');else document.documentElement.classList.remove('dark')}catch(_){}</script>\n` +
+			`  <link rel="modulepreload" href="/dist/client/${distManifest.entry}${cacheBust}">`
+		);
+	}
+
 	return (
 		`<!DOCTYPE html>\n<html lang="${key}">\n<head>\n` +
 		`  <meta charset="UTF-8">\n` +
@@ -188,7 +235,11 @@ const SPINNER =
 	`@keyframes __bs__{to{transform:rotate(360deg)}}</style><i></i></div>`;
 
 /** Chunk 2: metadata tags + close </head> + open <body> + spinner */
-export function buildMetadataChunk(metadata: Metadata | null, headExtras?: string[]): string {
+export function buildMetadataChunk(
+	metadata: Metadata | null,
+	headExtras?: string[],
+	segments?: AppHtmlSegments,
+): string {
 	let out = "\n";
 	if (metadata) {
 		if (metadata.title) out += `  <title>${escapeHtml(metadata.title)}</title>\n`;
@@ -218,7 +269,14 @@ export function buildMetadataChunk(metadata: Metadata | null, headExtras?: strin
 			if (fragment) out += `  ${fragment}\n`;
 		}
 	}
-	out += `</head>\n<body>\n${SPINNER}`;
+
+	if (segments) {
+		const headCloseInterpolated = interpolateSegment(segments.headClose, {});
+		out += headCloseInterpolated + `\n${SPINNER}`;
+	} else {
+		out += `</head>\n<body>\n${SPINNER}`;
+	}
+
 	return out;
 }
 
@@ -246,6 +304,7 @@ export function buildHtmlTail(
 	nonce?: string,
 	pageDeps: any = null,
 	layoutDeps: any[] | null = null,
+	segments?: AppHtmlSegments,
 ): string {
 	const n = nonceAttr(nonce);
 	let out = `<script${n}>document.getElementById('__bs__').remove()</script>`;
@@ -279,7 +338,14 @@ export function buildHtmlTail(
 			if (fragment) out += `\n${fragment}`;
 		}
 	}
-	out += `\n</body>\n</html>`;
+
+	if (segments) {
+		const tailInterpolated = interpolateSegment(segments.tail, { nonce });
+		out += `\n${tailInterpolated}`;
+	} else {
+		out += `\n</body>\n</html>`;
+	}
+
 	return out;
 }
 

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

@@ -159,12 +159,14 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 				}
 
 				let js = dev ? fixBindShadow(result.js.code) : result.js.code;
-				// Skip empty CSS — multiple +page.svelte routes with no <style> would
-				// otherwise each emit an empty CSS chunk, all hashing to the same
-				// content → Bun fails with "Multiple files share the same output path".
-				// Also strip dots from basename: Bun's `[name]-[hash].[ext]` chunk
-				// naming treats the first `.` as the extension boundary, so
-				// `+page.svelte-…` collapses to `[name]="+page"` for every route.
+				// 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`;
@@ -184,7 +186,10 @@ export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPl
 			build.onLoad({ filter: /.*/, namespace: VIRTUAL_NS }, (args) => {
 				const css = virtualCss.get(args.path) ?? "";
 				virtualCss.delete(args.path);
-				return { contents: css, loader: "css" };
+				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

@@ -20,6 +20,8 @@ import type { Metadata } from "./hooks.ts";
 import { loadPlugins } from "./config.ts";
 import { reportDevErrorFromCatch } from "./devErrorReport.ts";
 import type { BosiaPlugin, RenderContext } from "./types/plugin.ts";
+import { getAppHtmlSegments } from "./appHtml.ts";
+import type { AppHtmlSegments } from "./appHtml.ts";
 
 // Plugins are loaded once per process at module init via top-level await elsewhere
 // (server.ts), but renderer is also reachable from build/prerender contexts where
@@ -99,6 +101,11 @@ if (INTERNAL_HOSTS.size > 0) {
 	console.log(`🍪 Internal hosts (cookies forwarded): ${[...INTERNAL_HOSTS].join(", ")}`);
 }
 
+// ─── App HTML Template ───────────────────────────────────
+// Required; loaded once per process; cached singleton with invalidation for HMR
+
+const appHtmlSegments: AppHtmlSegments = getAppHtmlSegments();
+
 // ─── Session-Aware Fetch ─────────────────────────────────
 // Passed to load() functions so they can call internal APIs with the
 // current user's cookies automatically forwarded. Cookie is attached
@@ -607,8 +614,8 @@ export async function renderSSRStream(
 			);
 		}
 		const html =
-			buildHtmlShellOpen(metadata?.lang, nonce) +
-			buildMetadataChunk(metadata, headExtras) +
+			buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments) +
+			buildMetadataChunk(metadata, headExtras, appHtmlSegments) +
 			buildHtmlTail(
 				"",
 				"",
@@ -621,6 +628,7 @@ export async function renderSSRStream(
 				nonce,
 				data.pageDeps,
 				data.layoutDeps,
+				appHtmlSegments,
 			);
 		return new Response(html, {
 			headers: { "Content-Type": "text/html; charset=utf-8" },
@@ -659,8 +667,8 @@ export async function renderSSRStream(
 
 	// Pre-compute all chunks; pull-based stream gives Bun native backpressure.
 	const chunks: Uint8Array[] = [
-		enc.encode(buildHtmlShellOpen(metadata?.lang, nonce)),
-		enc.encode(buildMetadataChunk(metadata, headExtras)),
+		enc.encode(buildHtmlShellOpen(metadata?.lang, nonce, appHtmlSegments)),
+		enc.encode(buildMetadataChunk(metadata, headExtras, appHtmlSegments)),
 		enc.encode(
 			buildHtmlTail(
 				body,
@@ -674,6 +682,7 @@ export async function renderSSRStream(
 				nonce,
 				data.pageDeps,
 				data.layoutDeps,
+				appHtmlSegments,
 			),
 		),
 	];
@@ -781,6 +790,8 @@ export async function renderPageWithFormData(
 			nonce,
 			data.pageDeps,
 			data.layoutDeps,
+			undefined,
+			appHtmlSegments,
 		);
 		return compress(html, "text/html; charset=utf-8", req, status);
 	}
@@ -808,6 +819,8 @@ export async function renderPageWithFormData(
 		nonce,
 		data.pageDeps,
 		data.layoutDeps,
+		undefined,
+		appHtmlSegments,
 	);
 	return compress(html, "text/html; charset=utf-8", req, status);
 }
@@ -887,6 +900,7 @@ export async function renderErrorPage(
 					null,
 					null,
 					bodyEndExtras,
+					appHtmlSegments,
 				);
 				return compress(html, "text/html; charset=utf-8", req, status);
 			} catch (err) {
@@ -924,6 +938,7 @@ export async function renderErrorPage(
 				null,
 				null,
 				bodyEndExtras,
+				appHtmlSegments,
 			);
 			return compress(html, "text/html; charset=utf-8", req, status);
 		} catch (err) {

package/src/lib/client.ts

@@ -10,4 +10,11 @@
 
 export { enhance } from "../core/client/enhance.ts";
 export type { SubmitFunction, ActionResult } from "../core/client/enhance.ts";
-export { invalidate, invalidateAll } from "../core/client/navigation.ts";
+export {
+	afterNavigate,
+	beforeNavigate,
+	goto,
+	invalidate,
+	invalidateAll,
+} from "../core/client/navigation.ts";
+export type { GotoOptions, Navigation, NavigationTarget } from "../core/client/navigation.ts";

package/templates/default/public/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#f0f0f0" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#f0f0f0" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#f0f0f0" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/default/public/logo-light.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#1a1a1a" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#1a1a1a" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#1a1a1a" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/default/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="%bosia.lang%">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		%bosia.head%
+	</head>
+	<body>
+		%bosia.body%
+	</body>
+</html>

package/templates/demo/public/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#f0f0f0" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#f0f0f0" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#f0f0f0" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/demo/public/logo-light.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#1a1a1a" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#1a1a1a" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#1a1a1a" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/demo/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="%bosia.lang%" data-theme="neutral">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		%bosia.head%
+	</head>
+	<body>
+		%bosia.body%
+	</body>
+</html>

package/templates/todo/public/logo-dark.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#f0f0f0" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#f0f0f0" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#f0f0f0" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#f0f0f0" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/todo/public/logo-light.svg

@@ -0,0 +1,14 @@
+<svg width="200" height="200" viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
+  <!-- Top block -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="28" rx="6"/>
+  <rect fill="#1a1a1a" x="86" y="50" width="60" height="28" rx="6"/>
+
+  <!-- Middle block -->
+  <rect fill="#1a1a1a" x="86" y="86" width="72" height="28" rx="6"/>
+
+  <!-- Bottom block -->
+  <rect fill="#1a1a1a" x="86" y="122" width="60" height="28" rx="6"/>
+
+  <!-- Connector bar on left -->
+  <rect fill="#1a1a1a" x="50" y="50" width="28" height="100" rx="6"/>
+</svg>

package/templates/todo/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="%bosia.lang%">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		%bosia.head%
+	</head>
+	<body>
+		%bosia.body%
+	</body>
+</html>