bosia 0.5.9 → 0.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.5.9",
+	"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/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/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/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/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>