bosia 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "A fast, batteries-included fullstack framework — SSR · Svelte 5 Runes · Bun · ElysiaJS. File-based routing inspired by SvelteKit. No Node.js, no Vite, no adapters.",
 	"keywords": [
@@ -32,7 +32,8 @@
 	],
 	"exports": {
 		".": "./src/lib/index.ts",
-		"./client": "./src/lib/client.ts"
+		"./client": "./src/lib/client.ts",
+		"./plugins/server-timing": "./src/core/plugins/server-timing.ts"
 	},
 	"bin": {
 		"bosia": "src/cli/index.ts"

package/src/core/build.ts

@@ -10,6 +10,8 @@ import { prerenderStaticRoutes, generateStaticSite } from "./prerender.ts";
 import { loadEnv, classifyEnvVars } from "./env.ts";
 import { generateEnvModules } from "./envCodegen.ts";
 import { BOSIA_NODE_PATH, resolveBosiaBin } from "./paths.ts";
+import { loadPlugins } from "./config.ts";
+import type { BuildContext } from "./types/plugin.ts";
 
 // Resolved from this file's location inside the bosia package
 const CORE_DIR = import.meta.dir;
@@ -21,7 +23,24 @@ const isProduction = process.env.NODE_ENV === "production";
 const buildStart = performance.now();
 console.log("🏗️  Starting Bosia build...\n");
 
-// 0. Load .env files (before cleaning .bosia so loadEnv can set process.env early)
+// 0. Load plugins from bosia.config.ts
+const userPlugins = await loadPlugins(process.cwd());
+if (userPlugins.length > 0) {
+	console.log(`🔌 Plugins: ${userPlugins.map((p) => p.name).join(", ")}`);
+}
+
+const buildCtx: BuildContext = {
+	mode: isProduction ? "production" : "development",
+	cwd: process.cwd(),
+};
+
+for (const p of userPlugins) {
+	if (p.build?.preBuild) {
+		await p.build.preBuild(buildCtx);
+	}
+}
+
+// 0a. Load .env files (before cleaning .bosia so loadEnv can set process.env early)
 const envMode = isProduction ? "production" : "development";
 const envVars = loadEnv(envMode);
 const classifiedEnv = classifyEnvVars(envVars);
@@ -36,6 +55,7 @@ try {
 
 // 1. Scan routes
 const manifest = scanRoutes();
+buildCtx.manifest = manifest;
 console.log(`📂 Found ${manifest.pages.length} page route(s):`);
 for (const r of manifest.pages) {
 	console.log(`   ${r.pattern} → ${r.page}${r.pageServer ? " (server)" : ""}`);
@@ -47,6 +67,12 @@ if (manifest.apis.length > 0) {
 	}
 }
 
+for (const p of userPlugins) {
+	if (p.build?.postScan) {
+		await p.build.postScan(manifest, buildCtx);
+	}
+}
+
 // 2. Generate .bosia/routes.ts (single file replaces all old code generators)
 generateRoutesFile(manifest);
 
@@ -82,6 +108,10 @@ const tailwindPromise = tailwindProc.exited;
 const clientPlugin = makeBosiaPlugin("browser");
 const serverPlugin = makeBosiaPlugin("bun");
 
+// Collect Bun build plugins contributed by user plugins, per target.
+const userClientBunPlugins = userPlugins.flatMap((p) => p.build?.bunPlugins?.("browser") ?? []);
+const userServerBunPlugins = userPlugins.flatMap((p) => p.build?.bunPlugins?.("bun") ?? []);
+
 // Build-time defines: inline PUBLIC_STATIC_* and STATIC_* vars
 const staticDefines: Record<string, string> = {};
 for (const [key, value] of Object.entries(classifiedEnv.publicStatic)) {
@@ -104,7 +134,7 @@ const clientPromise = Bun.build({
 		"process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV ?? "development"),
 		...staticDefines,
 	},
-	plugins: [clientPlugin, SveltePlugin()],
+	plugins: [clientPlugin, ...userClientBunPlugins, SveltePlugin()],
 });
 
 const serverPromise = Bun.build({
@@ -115,7 +145,7 @@ const serverPromise = Bun.build({
 	naming: { entry: "index.[ext]", chunk: "[name]-[hash].[ext]" },
 	minify: isProduction,
 	external: ["elysia"],
-	plugins: [serverPlugin, SveltePlugin()],
+	plugins: [serverPlugin, ...userServerBunPlugins, SveltePlugin()],
 });
 
 const [tailwindExitCode, clientResult, serverResult] = await Promise.all([
@@ -174,10 +204,19 @@ writeFileSync("./dist/manifest.json", JSON.stringify(distManifest, null, 2));
 console.log(`✅ Client bundle: ${jsFiles.join(", ")}`);
 console.log(`✅ Server entry:  dist/server/${serverEntry}`);
 
+// 8b. Persist route manifest for runtime plugins (backend.after consumers like OpenAPI).
+writeFileSync("./dist/route-manifest.json", JSON.stringify(manifest, null, 2));
+
 // 9. Prerender static routes
 await prerenderStaticRoutes(manifest);
 
 // 10. Generate static site output (HTML + client assets + public → dist/static/)
 generateStaticSite();
 
+for (const p of userPlugins) {
+	if (p.build?.postBuild) {
+		await p.build.postBuild(buildCtx);
+	}
+}
+
 console.log(`\n🎉 Build complete in ${Math.round(performance.now() - buildStart)}ms!`);

package/src/core/client/App.svelte

@@ -4,6 +4,7 @@
 	import { clientRoutes } from "bosia:routes";
 	import { consumePrefetch, prefetchCache, dataUrl } from "./prefetch.ts";
 	import { appState } from "./appState.svelte.ts";
+	import { pickErrorPage } from "../errorMatch.ts";
 
 	let {
 		ssrMode = false,
@@ -12,6 +13,9 @@
 		ssrPageData = {},
 		ssrLayoutData = [],
 		ssrFormData = null,
+		ssrErrorComponent = null,
+		ssrErrorProps = null,
+		ssrErrorDepth = null,
 	}: {
 		ssrMode?: boolean;
 		ssrPageComponent?: any;
@@ -19,6 +23,9 @@
 		ssrPageData?: Record<string, any>;
 		ssrLayoutData?: Record<string, any>[];
 		ssrFormData?: any;
+		ssrErrorComponent?: any;
+		ssrErrorProps?: { error: { status: number; message: string } } | null;
+		ssrErrorDepth?: number | null;
 	} = $props();
 
 	let PageComponent = $state<any>(ssrPageComponent);
@@ -30,6 +37,9 @@
 	const layoutData = $derived(ssrMode ? (ssrLayoutData ?? []) : appState.layoutData);
 	const routeParams = $derived(ssrMode ? (ssrPageData?.params ?? {}) : appState.routeParams);
 	const formData = $derived(ssrMode ? ssrFormData : appState.form);
+	const ErrorComponent = $derived(ssrMode ? ssrErrorComponent : appState.errorComponent);
+	const errorProps = $derived(ssrMode ? ssrErrorProps : appState.errorProps);
+	const errorDepth = $derived(ssrMode ? ssrErrorDepth : appState.errorDepth);
 	let navigating = $state(false);
 	let navDone = $state(false);
 	// Skip bar on the very first effect run (initial hydration — data already present)
@@ -74,7 +84,7 @@
 			match.route.page(),
 			Promise.all(match.route.layouts.map((l: any) => l())),
 			dataFetch,
-		]).then(([pageMod, layoutMods, result]: [any, any[], any]) => {
+		]).then(async ([pageMod, layoutMods, result]: [any, any[], any]) => {
 			if (cancelled) return;
 			navigating = false;
 			navDone = true;
@@ -86,8 +96,49 @@
 				return;
 			}
 			if (result?.error || (result === null && match.route.hasServerData)) {
-				// Data fetch failed (e.g. static hosting with no server) — full page load
-				window.location.href = path;
+				// New shape: { error: { status, message }, errorDepth, errorOrigin }
+				const errInfo = result?.error;
+				const errStatus =
+					typeof errInfo === "object" && errInfo !== null
+						? (errInfo.status ?? 500)
+						: (result?.status ?? 500);
+				const errMessage =
+					typeof errInfo === "object" && errInfo !== null
+						? (errInfo.message ?? "Internal Server Error")
+						: typeof errInfo === "string"
+							? errInfo
+							: "Internal Server Error";
+				const errDepth: number =
+					typeof result?.errorDepth === "number"
+						? result.errorDepth
+						: match.route.layouts.length;
+				const errOrigin = result?.errorOrigin === "layout" ? "layout" : "page";
+				const picked = pickErrorPage(match.route.errorPages ?? [], errDepth, errOrigin);
+				if (!picked) {
+					// No nested boundary — full reload so server can render global error page
+					window.location.href = path;
+					return;
+				}
+				try {
+					const K = picked.depth;
+					const [errMod, ...layoutModsForError] = await Promise.all([
+						picked.loader(),
+						...match.route.layouts.slice(0, K).map((l: any) => l()),
+					]);
+					if (cancelled) return;
+					layoutComponents = layoutModsForError.map((m: any) => m.default);
+					const newLayoutData: Record<string, any>[] = [];
+					for (let i = 0; i < K; i++) newLayoutData.push({});
+					appState.layoutData = newLayoutData;
+					appState.pageData = {};
+					appState.routeParams = match.params;
+					appState.errorComponent = errMod.default;
+					appState.errorProps = { error: { status: errStatus, message: errMessage } };
+					appState.errorDepth = K;
+					if (router.isPush) window.scrollTo(0, 0);
+				} catch {
+					window.location.href = path;
+				}
 				return;
 			}
 			PageComponent = pageMod.default;
@@ -95,6 +146,10 @@
 			appState.pageData = result?.pageData ?? {};
 			appState.layoutData = result?.layoutData ?? [];
 			appState.routeParams = result?.pageData?.params ?? match.params;
+			// Successful navigation — clear any prior error state.
+			appState.errorComponent = null;
+			appState.errorProps = null;
+			appState.errorDepth = null;
 
 			// Scroll to top on forward navigation (not on popstate/back-forward)
 			if (router.isPush) window.scrollTo(0, 0);
@@ -133,25 +188,34 @@
 	<div class="bosia-bar done"></div>
 {/if}
 
-{#if layoutComponents.length > 0}
-	{@render renderLayout(0)}
+{#if ErrorComponent}
+	{@const depth = errorDepth ?? 0}
+	{#if depth > 0 && layoutComponents.length > 0}
+		{@render renderLayout(0, depth)}
+	{:else}
+		<ErrorComponent {...errorProps ?? {}} />
+	{/if}
+{:else if layoutComponents.length > 0}
+	{@render renderLayout(0, layoutComponents.length)}
 {:else if PageComponent}
 	<PageComponent data={{ ...pageData, params: routeParams }} form={formData} />
 {:else}
 	<p>Loading...</p>
 {/if}
 
-{#snippet renderLayout(index: number)}
+{#snippet renderLayout(index: number, leafDepth: number)}
 	{@const Layout = layoutComponents[index]}
 	{@const data = layoutData[index] ?? {}}
 
-	{#if index < layoutComponents.length - 1}
+	{#if index < leafDepth - 1}
 		<Layout {data}>
-			{@render renderLayout(index + 1)}
+			{@render renderLayout(index + 1, leafDepth)}
 		</Layout>
 	{:else}
 		<Layout {data}>
-			{#if PageComponent}
+			{#if ErrorComponent}
+				<ErrorComponent {...errorProps ?? {}} />
+			{:else if PageComponent}
 				<PageComponent data={{ ...pageData, params: routeParams }} form={formData} />
 			{:else}
 				<p>Loading...</p>

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

@@ -15,6 +15,12 @@ class AppState {
 	layoutData = $state<Record<string, any>[]>([]);
 	routeParams = $state<Record<string, string>>({});
 	form = $state<any>(null);
+	// Nested-error boundary state — set when a client navigation hits an
+	// error and a matching +error.svelte is found. Cleared on every
+	// successful navigation in App.svelte.
+	errorComponent = $state<any>(null);
+	errorProps = $state<{ error: { status: number; message: string } } | null>(null);
+	errorDepth = $state<number | null>(null);
 }
 
 export const appState = new AppState();

package/src/core/config.ts

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+import type { BosiaConfig, BosiaPlugin } from "./types/plugin.ts";
+
+let cached: BosiaConfig | null = null;
+let cachedFromPath: string | null = null;
+
+const CONFIG_NAMES = ["bosia.config.ts", "bosia.config.js", "bosia.config.mjs"];
+
+function findConfigPath(cwd: string): string | null {
+	for (const name of CONFIG_NAMES) {
+		const p = join(cwd, name);
+		if (existsSync(p)) return p;
+	}
+	return null;
+}
+
+/**
+ * Resolve and load `bosia.config.ts` (or `.js`/`.mjs`) from cwd. Returns the
+ * default export. If no config is present, returns `{ plugins: [] }`.
+ *
+ * Cached per-cwd. Compiled via `Bun.build({ target: "bun" })` so user code can
+ * use TypeScript and bare-specifier imports.
+ */
+export async function loadBosiaConfig(cwd: string = process.cwd()): Promise<BosiaConfig> {
+	if (cached && cachedFromPath === cwd) return cached;
+
+	const configPath = findConfigPath(cwd);
+	if (!configPath) {
+		cached = { plugins: [] };
+		cachedFromPath = cwd;
+		return cached;
+	}
+
+	const result = await Bun.build({
+		entrypoints: [configPath],
+		target: "bun",
+		format: "esm",
+		external: ["bosia", "elysia", "bun", "svelte", "svelte/server"],
+	});
+
+	if (!result.success || !result.outputs[0]) {
+		const logs = result.logs.map((l) => String(l)).join("\n");
+		throw new Error(`Failed to compile ${configPath}:\n${logs}`);
+	}
+
+	const code = await result.outputs[0].text();
+	// Write inside cwd so bare-specifier imports (e.g. `bosia/plugins/...`) resolve via
+	// the project's own node_modules. /tmp would have no node_modules to walk into.
+	const cacheDir = join(cwd, ".bosia");
+	mkdirSync(cacheDir, { recursive: true });
+	const tmpFile = join(
+		cacheDir,
+		`config.${Date.now()}.${Math.random().toString(36).slice(2)}.mjs`,
+	);
+	await Bun.write(tmpFile, code);
+
+	let mod: { default?: BosiaConfig };
+	try {
+		mod = await import(tmpFile);
+	} finally {
+		try {
+			await Bun.file(tmpFile).delete();
+		} catch {}
+	}
+
+	const config = mod.default;
+	if (!config || typeof config !== "object") {
+		throw new Error(
+			`${configPath} must export a default object (use \`export default defineConfig({...})\` or \`export default {...} satisfies BosiaConfig\`).`,
+		);
+	}
+
+	const plugins = Array.isArray(config.plugins) ? config.plugins : [];
+	const normalized: BosiaConfig = { plugins };
+
+	cached = normalized;
+	cachedFromPath = cwd;
+	return normalized;
+}
+
+/** Test-only — drops the in-memory cache so tests can reload fresh config files. */
+export function resetConfigCache(): void {
+	cached = null;
+	cachedFromPath = null;
+}
+
+/** Convenience: load and return only the plugin list. */
+export async function loadPlugins(cwd?: string): Promise<BosiaPlugin[]> {
+	const config = await loadBosiaConfig(cwd);
+	return config.plugins ?? [];
+}

package/src/core/dev.ts

@@ -163,7 +163,7 @@ function scheduleBuild() {
 // Owns the SSE connection so it survives app server restarts.
 // All other requests are proxied to the app server.
 
-Bun.serve({
+const devServer = Bun.serve({
 	port: DEV_PORT,
 	idleTimeout: 255,
 	async fetch(req) {
@@ -242,7 +242,7 @@ function isGenerated(path: string): boolean {
 	return GENERATED.some((g) => path.startsWith(g));
 }
 
-watch(join(process.cwd(), "src"), { recursive: true }, (_event, filename) => {
+const srcWatcher = watch(join(process.cwd(), "src"), { recursive: true }, (_event, filename) => {
 	if (!filename) return;
 	const abs = join(process.cwd(), "src", filename);
 	if (isGenerated(abs)) return;
@@ -257,7 +257,7 @@ watch(join(process.cwd(), "src"), { recursive: true }, (_event, filename) => {
 
 const ENV_FILES = new Set([".env", ".env.local", ".env.development", ".env.development.local"]);
 
-watch(process.cwd(), { recursive: false }, (_event, filename) => {
+const envWatcher = watch(process.cwd(), { recursive: false }, (_event, filename) => {
 	if (!filename || !ENV_FILES.has(filename)) return;
 	console.log(`[watch] env changed: ${filename}`);
 	reloadEnv();
@@ -274,14 +274,23 @@ console.log("👀 Watching src/ for changes...\n");
 
 let shuttingDown = false;
 async function shutdown() {
-	if (shuttingDown) process.exit(130);
+	if (shuttingDown) return; // re-entry from process-group signals or impatient ^C — drain is already running
 	shuttingDown = true;
 	intentionalKill = true;
+
+	if (buildTimer) clearTimeout(buildTimer);
+	srcWatcher.close();
+	envWatcher.close();
+	devServer.stop(true); // closes SSE conns → abort listeners clear ping intervals
+
 	if (appProcess) {
 		appProcess.kill("SIGTERM");
 		await Promise.race([appProcess.exited, Bun.sleep(2_500)]);
 	}
-	process.exit(0);
+
+	// Safety net: if any stray handle still holds the loop, force clean exit.
+	// .unref() so the timer itself doesn't keep the loop alive when drain succeeds.
+	setTimeout(() => process.exit(0), 1_500).unref();
 }
 
 process.on("SIGINT", shutdown);

package/src/core/errorMatch.ts

@@ -0,0 +1,33 @@
+// ─── Nested Error-Page Matcher ────────────────────────────
+// Picks the deepest +error.svelte boundary that protects the failing
+// code. Shared by SSR (renderer.ts) and CSR (App.svelte) so client
+// and server agree on which boundary catches a thrown error.
+//
+// Catch rules (SvelteKit-compatible):
+//   - "page"   origin: error in +page / +page.server at depth = layouts.length
+//              → caught by deepest entry where `depth ≤ errorDepth`.
+//   - "layout" origin: error in +layout.server (or layout render) at depth L
+//              → caught by deepest entry where `depth < errorDepth`. An error
+//              page in the same dir as the failing layout cannot catch its own
+//              layout — it would render *inside* the broken layout.
+
+export type ErrorOrigin = "page" | "layout";
+
+export interface ErrorPageEntry<L = unknown> {
+	loader: L;
+	depth: number;
+}
+
+export function pickErrorPage<L>(
+	errorPages: readonly ErrorPageEntry<L>[],
+	errorDepth: number,
+	origin: ErrorOrigin,
+): ErrorPageEntry<L> | null {
+	let best: ErrorPageEntry<L> | null = null;
+	for (const ep of errorPages) {
+		const ok = origin === "page" ? ep.depth <= errorDepth : ep.depth < errorDepth;
+		if (!ok) continue;
+		if (!best || ep.depth > best.depth) best = ep;
+	}
+	return best;
+}

package/src/core/html.ts

@@ -150,7 +150,7 @@ 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): string {
+export function buildMetadataChunk(metadata: Metadata | null, headExtras?: string[]): string {
 	let out = "\n";
 	if (metadata) {
 		if (metadata.title) out += `  <title>${escapeHtml(metadata.title)}</title>\n`;
@@ -175,6 +175,11 @@ export function buildMetadataChunk(metadata: Metadata | null): string {
 	} else {
 		out += `  <title>Bosia App</title>\n`;
 	}
+	if (headExtras?.length) {
+		for (const fragment of headExtras) {
+			if (fragment) out += `  ${fragment}\n`;
+		}
+	}
 	out += `</head>\n<body>\n${SPINNER}`;
 	return out;
 }
@@ -199,6 +204,7 @@ export function buildHtmlTail(
 	csr: boolean,
 	formData: any = null,
 	ssr = true,
+	bodyEndExtras?: string[],
 ): string {
 	let out = `<script>document.getElementById('__bs__').remove()</script>`;
 	out += `\n<div id="app">${body}</div>`;
@@ -219,6 +225,11 @@ export function buildHtmlTail(
 	} else if (isDev) {
 		out += `\n<script>!function r(){var e=new EventSource("/__bosia/sse");e.addEventListener("reload",()=>location.reload());e.onopen=()=>r._ok||(r._ok=1);e.onerror=()=>{e.close();setTimeout(r,2000)}}()</script>`;
 	}
+	if (bodyEndExtras?.length) {
+		for (const fragment of bodyEndExtras) {
+			if (fragment) out += `\n${fragment}`;
+		}
+	}
 	out += `\n</body>\n</html>`;
 	return out;
 }

package/src/core/plugins/server-timing.ts

@@ -0,0 +1,51 @@
+import type { BosiaPlugin } from "../types/plugin.ts";
+
+export interface ServerTimingOptions {
+	/** Header name (defaults to standard `Server-Timing`). */
+	header?: string;
+	/** Metric name (defaults to `handler`). */
+	metric?: string;
+}
+
+/**
+ * Adds a `Server-Timing` response header that reports how long each request
+ * spent inside the framework's handler. Measured from `onRequest` to
+ * `onAfterHandle` — so for streaming SSR routes this is "time to start
+ * streaming," not full end-to-end. Headers must flush before the body, so a
+ * true end-to-end value cannot be reported in a response header.
+ */
+export function serverTiming(options: ServerTimingOptions = {}): BosiaPlugin {
+	const headerName = options.header ?? "Server-Timing";
+	const metric = options.metric ?? "handler";
+
+	return {
+		name: "server-timing",
+		backend: {
+			before(app) {
+				const starts = new WeakMap<Request, number>();
+				return app
+					.onRequest(({ request }) => {
+						starts.set(request, performance.now());
+					})
+					.onAfterHandle(({ request, response, set }) => {
+						const start = starts.get(request);
+						if (start === undefined) return;
+						const dur = (performance.now() - start).toFixed(2);
+						const value = `${metric};dur=${dur}`;
+
+						// Set on Response objects directly when possible (preserves immutability semantics)
+						if (response instanceof Response) {
+							response.headers.set(headerName, value);
+							return;
+						}
+
+						// Otherwise, push into Elysia's outbound header bag.
+						const headers = (set.headers ??= {}) as Record<string, string>;
+						headers[headerName] = value;
+					});
+			},
+		},
+	};
+}
+
+export default serverTiming;

package/src/core/renderer.ts

@@ -4,6 +4,7 @@ import { findMatch } from "./matcher.ts";
 import { serverRoutes, errorPage } from "bosia:routes";
 import type { Cookies } from "./hooks.ts";
 import { HttpError, Redirect } from "./errors.ts";
+import { pickErrorPage, type ErrorOrigin } from "./errorMatch.ts";
 import App from "./client/App.svelte";
 import {
 	buildHtml,
@@ -14,6 +15,32 @@ import {
 	isDev,
 } from "./html.ts";
 import type { Metadata } from "./hooks.ts";
+import { loadPlugins } from "./config.ts";
+import type { BosiaPlugin, RenderContext } from "./types/plugin.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
+// loadPlugins() may not have been called yet. The function is cached, so awaiting
+// per request is cheap (Map hit on second call).
+async function pluginRenderFragments(
+	hook: "head" | "bodyEnd",
+	ctx: RenderContext,
+): Promise<string[]> {
+	const plugins = await loadPlugins();
+	const out: string[] = [];
+	for (const p of plugins as BosiaPlugin[]) {
+		const fn = p.render?.[hook];
+		if (!fn) continue;
+		try {
+			const fragment = await fn(ctx);
+			if (fragment) out.push(fragment);
+		} catch (err) {
+			if (isDev) console.error(`Plugin "${p.name}" render.${hook} failed:`, err);
+			else console.error(`Plugin "${p.name}" render.${hook} failed:`, (err as Error).message);
+		}
+	}
+	return out;
+}
 
 // ─── Timeout Helpers ─────────────────────────────────────
 
@@ -107,6 +134,28 @@ function makeFetch(req: Request, url: URL) {
 	};
 }
 
+// ─── Error Context Stamping ──────────────────────────────
+// Annotate an HttpError with the layout depth and origin where it was
+// thrown, plus the partial layoutData accumulated so far. The data
+// endpoint forwards this to the client; the SSR catch sites use it to
+// render the right nested boundary inside the right layout chain.
+
+function stampErrorContext(
+	err: HttpError,
+	depth: number,
+	origin: ErrorOrigin,
+	partialLayoutData: Record<string, any>[],
+): void {
+	const e = err as HttpError & {
+		errorDepth?: number;
+		errorOrigin?: ErrorOrigin;
+		partialLayoutData?: Record<string, any>[];
+	};
+	e.errorDepth ??= depth;
+	e.errorOrigin ??= origin;
+	e.partialLayoutData ??= [...partialLayoutData];
+}
+
 // ─── Route Data Loader ───────────────────────────────────
 // Runs layout + page server loaders for a given URL.
 // Used by both SSR and the /__bosia/data JSON endpoint.
@@ -143,10 +192,16 @@ export async function loadRouteData(
 					)) ?? {};
 			}
 		} catch (err) {
-			if (err instanceof HttpError || err instanceof Redirect) throw err;
+			if (err instanceof Redirect) throw err;
+			if (err instanceof HttpError) {
+				stampErrorContext(err, ls.depth, "layout", layoutData);
+				throw err;
+			}
 			if (isDev) console.error("Layout server load error:", err);
 			else console.error("Layout server load error:", (err as Error).message ?? err);
-			throw new HttpError(500, "Internal Server Error");
+			const wrapped = new HttpError(500, "Internal Server Error");
+			stampErrorContext(wrapped, ls.depth, "layout", layoutData);
+			throw wrapped;
 		}
 	}
 
@@ -181,10 +236,16 @@ export async function loadRouteData(
 					)) ?? {};
 			}
 		} catch (err) {
-			if (err instanceof HttpError || err instanceof Redirect) throw err;
+			if (err instanceof Redirect) throw err;
+			if (err instanceof HttpError) {
+				stampErrorContext(err, route.layoutModules.length, "page", layoutData);
+				throw err;
+			}
 			if (isDev) console.error("Page server load error:", err);
 			else console.error("Page server load error:", (err as Error).message ?? err);
-			throw new HttpError(500, "Internal Server Error");
+			const wrapped = new HttpError(500, "Internal Server Error");
+			stampErrorContext(wrapped, route.layoutModules.length, "page", layoutData);
+			throw wrapped;
 		}
 	}
 
@@ -244,7 +305,7 @@ export async function renderSSRStream(
 			return Response.redirect(err.location, err.status);
 		}
 		if (err instanceof HttpError) {
-			return renderErrorPage(err.status, err.message, url, req);
+			return renderErrorPage(err.status, err.message, url, req, route);
 		}
 		if (isDev) console.error("Metadata load error:", err);
 		else console.error("Metadata load error:", (err as Error).message ?? err);
@@ -266,15 +327,41 @@ export async function renderSSRStream(
 		]);
 	} catch (err) {
 		if (err instanceof Redirect) return Response.redirect(err.location, err.status);
-		if (err instanceof HttpError) return renderErrorPage(err.status, err.message, url, req);
+		if (err instanceof HttpError) {
+			const e = err as HttpError & {
+				errorDepth?: number;
+				errorOrigin?: ErrorOrigin;
+				partialLayoutData?: Record<string, any>[];
+			};
+			return renderErrorPage(
+				err.status,
+				err.message,
+				url,
+				req,
+				route,
+				e.errorDepth,
+				e.errorOrigin,
+				e.partialLayoutData,
+			);
+		}
 		if (isDev) console.error("SSR load error:", err);
 		else console.error("SSR load error:", (err as Error).message ?? err);
-		return renderErrorPage(500, "Internal Server Error", url, req);
+		return renderErrorPage(500, "Internal Server Error", url, req, route);
 	}
 
 	if (!data) return renderErrorPage(404, "Not Found", url, req);
 
 	const enc = new TextEncoder();
+	const renderCtx: RenderContext = {
+		request: req,
+		url,
+		route: { pattern: route.pattern },
+		metadata,
+	};
+	const [headExtras, bodyEndExtras] = await Promise.all([
+		pluginRenderFragments("head", renderCtx),
+		pluginRenderFragments("bodyEnd", renderCtx),
+	]);
 
 	// ssr=false → no render() needed; ship shell + hydration as a single response.
 	// ssr=false && csr=false is meaningless (nothing renders) — force csr=true.
@@ -286,8 +373,8 @@ export async function renderSSRStream(
 		}
 		const html =
 			buildHtmlShellOpen(metadata?.lang) +
-			buildMetadataChunk(metadata) +
-			buildHtmlTail("", "", data.pageData, data.layoutData, true, null, false);
+			buildMetadataChunk(metadata, headExtras) +
+			buildHtmlTail("", "", data.pageData, data.layoutData, true, null, false, bodyEndExtras);
 		return new Response(html, {
 			headers: { "Content-Type": "text/html; charset=utf-8" },
 		});
@@ -309,14 +396,35 @@ export async function renderSSRStream(
 	} catch (err) {
 		if (isDev) console.error("SSR render error:", err);
 		else console.error("SSR render error:", (err as Error).message ?? err);
-		return renderErrorPage(500, "Internal Server Error", url, req);
+		// Render-phase errors fall through to deepest boundary like a page error.
+		return renderErrorPage(
+			500,
+			"Internal Server Error",
+			url,
+			req,
+			route,
+			route.layoutModules.length,
+			"page",
+			data.layoutData,
+		);
 	}
 
 	// Pre-compute all chunks; pull-based stream gives Bun native backpressure.
 	const chunks: Uint8Array[] = [
 		enc.encode(buildHtmlShellOpen(metadata?.lang)),
-		enc.encode(buildMetadataChunk(metadata)),
-		enc.encode(buildHtmlTail(body, head, data.pageData, data.layoutData, data.csr)),
+		enc.encode(buildMetadataChunk(metadata, headExtras)),
+		enc.encode(
+			buildHtmlTail(
+				body,
+				head,
+				data.pageData,
+				data.layoutData,
+				data.csr,
+				null,
+				true,
+				bodyEndExtras,
+			),
+		),
 	];
 
 	let i = 0;
@@ -411,18 +519,71 @@ export async function renderPageWithFormData(
 }
 
 // ─── Error Page Renderer ──────────────────────────────────
+// 1. If a route is known, try the nearest nested +error.svelte and render
+//    it inside the matching prefix of the layout chain.
+// 2. Otherwise fall back to the global root +error.svelte.
+// 3. Otherwise return a plain-text response.
 
 export async function renderErrorPage(
 	status: number,
 	message: string,
 	url: URL,
 	req: Request,
+	route?: any,
+	errorDepth?: number,
+	errorOrigin?: ErrorOrigin,
+	partialLayoutData?: Record<string, any>[],
 ): Promise<Response> {
+	// 1. Nested boundary
+	if (route && errorDepth !== undefined && route.errorPages?.length) {
+		const origin = errorOrigin ?? "page";
+		const picked = pickErrorPage<() => Promise<any>>(
+			route.errorPages as { loader: () => Promise<any>; depth: number }[],
+			errorDepth,
+			origin,
+		);
+		if (picked) {
+			try {
+				const K = picked.depth;
+				const [errorMod, layoutMods] = await Promise.all([
+					picked.loader(),
+					Promise.all(
+						route.layoutModules.slice(0, K).map((l: () => Promise<any>) => l()),
+					),
+				]);
+				const layoutData: Record<string, any>[] = [];
+				for (let i = 0; i < K; i++) layoutData.push(partialLayoutData?.[i] ?? {});
+				const { body, head } = render(App, {
+					props: {
+						ssrMode: true,
+						ssrLayoutComponents: layoutMods.map((m: any) => m.default),
+						ssrLayoutData: layoutData,
+						ssrErrorComponent: errorMod.default,
+						ssrErrorProps: { error: { status, message } },
+						ssrErrorDepth: K,
+					},
+				});
+				// csr=false: no client hydration on the error page itself.
+				const html = buildHtml(body, head, { status, message }, layoutData, false);
+				return compress(html, "text/html; charset=utf-8", req, status);
+			} catch (err) {
+				if (isDev) console.error("Nested error page render failed:", err);
+				else
+					console.error(
+						"Nested error page render failed:",
+						(err as Error).message ?? err,
+					);
+				// fall through to global / text fallback
+			}
+		}
+	}
+
+	// 2. Global root error page
 	if (errorPage) {
 		try {
 			const mod = await errorPage();
 			// Render the error component directly — NOT through App.svelte.
-			// App.svelte always remaps ssrPageData to a `data` prop, but +error.svelte
+			// App.svelte remaps ssrPageData to a `data` prop, but +error.svelte
 			// expects `error` as a direct prop: `let { error } = $props()`.
 			const { body, head } = render(mod.default, {
 				props: { error: { status, message } },

package/src/core/routeFile.ts

@@ -37,6 +37,7 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 	lines.push("  pattern: string;");
 	lines.push("  page: () => Promise<any>;");
 	lines.push("  layouts: (() => Promise<any>)[];");
+	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push("  hasServerData: boolean;");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
 	lines.push("}> = [");
@@ -44,11 +45,18 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 		const layoutImports = r.layouts
 			.map((l) => `() => import(${JSON.stringify(toImportPath(l))})`)
 			.join(", ");
+		const errorPageImports = r.errorPages
+			.map(
+				(ep) =>
+					`{ loader: () => import(${JSON.stringify(toImportPath(ep.path))}), depth: ${ep.depth} }`,
+			)
+			.join(", ");
 		const hasServerData = !!(r.pageServer || r.layoutServers.length > 0);
 		lines.push("  {");
 		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
 		lines.push(`    layouts: [${layoutImports}],`);
+		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    hasServerData: ${hasServerData},`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
 		lines.push("  },");
@@ -62,6 +70,7 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 	lines.push("  layoutModules: (() => Promise<any>)[];");
 	lines.push("  pageServer: (() => Promise<any>) | null;");
 	lines.push("  layoutServers: { loader: () => Promise<any>; depth: number }[];");
+	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
 	lines.push('  scope: "public" | "private";');
 	lines.push("}> = [");
@@ -75,6 +84,12 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 					`{ loader: () => import(${JSON.stringify(toImportPath(ls.path))}), depth: ${ls.depth} }`,
 			)
 			.join(", ");
+		const errorPageImports = r.errorPages
+			.map(
+				(ep) =>
+					`{ loader: () => import(${JSON.stringify(toImportPath(ep.path))}), depth: ${ep.depth} }`,
+			)
+			.join(", ");
 		lines.push("  {");
 		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
 		lines.push(`    pageModule: () => import(${JSON.stringify(toImportPath(r.page))}),`);
@@ -83,6 +98,7 @@ export function generateRoutesFile(manifest: RouteManifest): void {
 			`    pageServer: ${r.pageServer ? `() => import(${JSON.stringify(toImportPath(r.pageServer))})` : "null"},`,
 		);
 		lines.push(`    layoutServers: [${layoutServerImports}],`);
+		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
 		lines.push(`    scope: ${JSON.stringify(r.scope)},`);
 		lines.push("  },");
@@ -138,6 +154,7 @@ function generateClientRoutesFile(
 	lines.push("  pattern: string;");
 	lines.push("  page: () => Promise<any>;");
 	lines.push("  layouts: (() => Promise<any>)[];");
+	lines.push("  errorPages: { loader: () => Promise<any>; depth: number }[];");
 	lines.push("  hasServerData: boolean;");
 	lines.push('  trailingSlash: "never" | "always" | "ignore";');
 	lines.push("}> = [");
@@ -145,11 +162,18 @@ function generateClientRoutesFile(
 		const layoutImports = r.layouts
 			.map((l) => `() => import(${JSON.stringify(toImportPath(l))})`)
 			.join(", ");
+		const errorPageImports = r.errorPages
+			.map(
+				(ep) =>
+					`{ loader: () => import(${JSON.stringify(toImportPath(ep.path))}), depth: ${ep.depth} }`,
+			)
+			.join(", ");
 		const hasServerData = !!(r.pageServer || r.layoutServers.length > 0);
 		lines.push("  {");
 		lines.push(`    pattern: ${JSON.stringify(r.pattern)},`);
 		lines.push(`    page: () => import(${JSON.stringify(toImportPath(r.page))}),`);
 		lines.push(`    layouts: [${layoutImports}],`);
+		lines.push(`    errorPages: [${errorPageImports}],`);
 		lines.push(`    hasServerData: ${hasServerData},`);
 		lines.push(`    trailingSlash: ${JSON.stringify(r.trailingSlash)},`);
 		lines.push("  },");

package/src/core/routeTypes.ts

@@ -34,8 +34,11 @@ function paramsForDir(dir: string): string[] {
 }
 
 export function generateRouteTypes(manifest: RouteManifest): void {
-	// Collect { dir → { pageServer?, layoutServer? } }
-	const dirs = new Map<string, { pageServer?: string; layoutServer?: string }>();
+	// Collect { dir → { pageServer?, layoutServer?, hasErrorPage? } }
+	const dirs = new Map<
+		string,
+		{ pageServer?: string; layoutServer?: string; hasErrorPage?: boolean }
+	>();
 
 	for (const route of manifest.pages) {
 		const pageDir = routeDirOf(route.page);
@@ -48,9 +51,17 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 			if (!dirs.has(lsDir)) dirs.set(lsDir, {});
 			dirs.get(lsDir)!.layoutServer = ls.path;
 		}
+		for (const ep of route.errorPages ?? []) {
+			const epDir = routeDirOf(ep.path);
+			if (!dirs.has(epDir)) dirs.set(epDir, {});
+			dirs.get(epDir)!.hasErrorPage = true;
+		}
 	}
 
-	if (manifest.errorPage && !dirs.has(".")) dirs.set(".", {});
+	if (manifest.errorPage) {
+		if (!dirs.has(".")) dirs.set(".", {});
+		dirs.get(".")!.hasErrorPage = true;
+	}
 
 	for (const [dir, info] of dirs) {
 		// Path segments of the route dir (empty array for root ".")
@@ -98,7 +109,7 @@ export function generateRouteTypes(manifest: RouteManifest): void {
 		}
 		lines.push(`export type PageProps = { data: PageData };`);
 
-		if (dir === "." && manifest.errorPage) {
+		if (info.hasErrorPage) {
 			lines.push(``);
 			lines.push(`export type PageError = { status: number; message: string };`);
 			lines.push(`export type ErrorProps = { error: PageError };`);

package/src/core/scanner.ts

@@ -43,6 +43,7 @@ export function scanRoutes(): RouteManifest {
 		urlSegments: string[],
 		layoutChain: string[],
 		layoutServerChain: { path: string; depth: number }[],
+		errorPageChain: { path: string; depth: number }[],
 		inheritedTrailingSlash: TrailingSlash,
 		inheritedScope: "public" | "private",
 	) {
@@ -54,6 +55,7 @@ export function scanRoutes(): RouteManifest {
 		// Accumulate layouts for this level
 		const currentLayouts = [...layoutChain];
 		const currentLayoutServers = [...layoutServerChain];
+		const currentErrorPages = [...errorPageChain];
 		let currentTrailingSlash = inheritedTrailingSlash;
 
 		if (items.some((i) => i.isFile() && i.name === "+layout.svelte")) {
@@ -68,6 +70,14 @@ export function scanRoutes(): RouteManifest {
 			const ts = readTrailingSlash(join(ROUTES_DIR, layoutServerPath));
 			if (ts) currentTrailingSlash = ts;
 		}
+		if (items.some((i) => i.isFile() && i.name === "+error.svelte")) {
+			// depth = number of layouts wrapping this dir (this dir's layout included).
+			// An error page at depth K renders inside layouts[0..K-1].
+			currentErrorPages.push({
+				path: join(dir, "+error.svelte"),
+				depth: currentLayouts.length,
+			});
+		}
 
 		// API route (+server.ts)
 		if (items.some((i) => i.isFile() && i.name === "+server.ts")) {
@@ -94,6 +104,7 @@ export function scanRoutes(): RouteManifest {
 				layouts: [...currentLayouts],
 				pageServer: pageServerFile,
 				layoutServers: [...currentLayoutServers],
+				errorPages: [...currentErrorPages],
 				trailingSlash: effectiveTs,
 				scope: inheritedScope,
 			});
@@ -116,13 +127,14 @@ export function scanRoutes(): RouteManifest {
 				isGroup ? [...urlSegments] : [...urlSegments, dirName],
 				currentLayouts,
 				currentLayoutServers,
+				currentErrorPages,
 				currentTrailingSlash,
 				childScope,
 			);
 		}
 	}
 
-	walk("", [], [], [], "never", "public");
+	walk("", [], [], [], [], "never", "public");
 
 	// Warn when a catch-all exists but no exact route covers its prefix.
 	// e.g. "/[...slug]" matches everything EXCEPT "/" (which needs its own +page.svelte).

package/src/core/server.ts

@@ -1,10 +1,12 @@
 import { Elysia } from "elysia";
 
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { join, resolve as resolvePath } from "path";
 
 import { findMatch, compileRoutes, canonicalPathname } from "./matcher.ts";
 import { apiRoutes, serverRoutes } from "bosia:routes";
+import { loadPlugins } from "./config.ts";
+import type { RouteManifest } from "./types.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by renderer.ts via module reference)
 compileRoutes(apiRoutes);
@@ -210,8 +212,16 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				);
 			}
 			if (err instanceof HttpError) {
+				const e = err as HttpError & {
+					errorDepth?: number;
+					errorOrigin?: "page" | "layout";
+				};
 				return compress(
-					JSON.stringify({ error: err.message, status: err.status }),
+					JSON.stringify({
+						error: { status: err.status, message: err.message },
+						errorDepth: e.errorDepth ?? null,
+						errorOrigin: e.errorOrigin ?? null,
+					}),
 					"application/json",
 					request,
 					err.status,
@@ -586,16 +596,68 @@ let shuttingDown = false;
 let inFlight = 0;
 let drainResolve: (() => void) | null = null;
 
+// ─── Plugin Loading ───────────────────────────────────────
+
+const plugins = await loadPlugins(process.cwd());
+if (plugins.length > 0) {
+	console.log(`🔌 Loaded ${plugins.length} plugin(s): ${plugins.map((p) => p.name).join(", ")}`);
+}
+
+// Read the build-time route manifest so plugins.backend.after can introspect routes.
+function loadBuiltManifest(): RouteManifest {
+	const path = "./dist/route-manifest.json";
+	if (existsSync(path)) {
+		try {
+			return JSON.parse(readFileSync(path, "utf-8"));
+		} catch {}
+	}
+	// Fallback: synthesize from runtime arrays (no file paths, just patterns).
+	return {
+		pages: serverRoutes.map((r: any) => ({
+			pattern: r.pattern,
+			page: "",
+			layouts: [],
+			pageServer: r.pageServer ? "" : null,
+			layoutServers: [],
+			errorPages: [],
+			trailingSlash: r.trailingSlash,
+			scope: r.scope,
+		})),
+		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, server: "" })),
+		errorPage: null,
+	};
+}
+
+const routeManifest = loadBuiltManifest();
+
 // ─── Elysia App ───────────────────────────────────────────
 
 const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : isDev ? 9001 : 9000;
 
-const app = new Elysia({ serve: { maxRequestBodySize: BODY_SIZE_LIMIT } })
-	.onError(({ error }) => {
+// Elysia's chained generics drift when plugins add routes — track the app as a
+// loose `Elysia` so plugin-extended types stay assignable.
+let app: Elysia = new Elysia({ serve: { maxRequestBodySize: BODY_SIZE_LIMIT } }).onError(
+	({ error }) => {
 		if (isDev) console.error("Uncaught server error:", error);
 		else console.error("Uncaught server error:", (error as Error)?.message ?? error);
 		return Response.json({ error: "Internal Server Error" }, { status: 500 });
-	})
+	},
+) as unknown as Elysia;
+
+// Plugins.backend.before — runs before framework middleware/routes.
+// Plugin-registered routes here BYPASS the framework (CSRF, hooks, etc.).
+for (const plugin of plugins) {
+	if (plugin.backend?.before) {
+		try {
+			app = (await plugin.backend.before(app)) ?? app;
+		} catch (err) {
+			console.error(`❌ Plugin "${plugin.name}" backend.before failed:`, err);
+			throw err;
+		}
+	}
+}
+
+app = app
 	// Static files are served by resolve() with path traversal protection and security headers
 	// API routes must intercept all HTTP methods before the GET catch-all
 	.onBeforeHandle(async ({ request }) => {
@@ -604,31 +666,43 @@ const app = new Elysia({ serve: { maxRequestBodySize: BODY_SIZE_LIMIT } })
 		return handleRequest(request, url);
 	})
 	// SSR pages
-	.get("*", ({ request }) => {
+	.get("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
 	})
 	// Non-GET catch-alls so onBeforeHandle fires for API routes on other methods
-	.post("*", ({ request }) => {
+	.post("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
 	})
-	.put("*", ({ request }) => {
+	.put("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
 	})
-	.patch("*", ({ request }) => {
+	.patch("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
 	})
-	.delete("*", ({ request }) => {
+	.delete("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
 	})
-	.options("*", ({ request }) => {
+	.options("*", ({ request }: { request: Request }) => {
 		const url = new URL(request.url);
 		return handleRequest(request, url);
-	});
+	}) as unknown as Elysia;
+
+// Plugins.backend.after — runs after framework routes; receives the route manifest.
+for (const plugin of plugins) {
+	if (plugin.backend?.after) {
+		try {
+			app = (await plugin.backend.after(app, { manifest: routeManifest })) ?? app;
+		} catch (err) {
+			console.error(`❌ Plugin "${plugin.name}" backend.after failed:`, err);
+			throw err;
+		}
+	}
+}
 
 app.listen(PORT, () => {
 	// In dev mode the proxy owns the user-facing port — don't print the internal port

package/src/core/types/plugin.ts

@@ -0,0 +1,81 @@
+// ─── Bosia Plugin Types ──────────────────────────────────
+// Public surface for first-party and third-party plugins.
+
+import type { Elysia } from "elysia";
+import type { BunPlugin } from "bun";
+import type { RouteManifest } from "../types.ts";
+import type { Metadata } from "../hooks.ts";
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type BuildTarget = "browser" | "bun";
+
+export interface BuildContext {
+	mode: "production" | "development";
+	cwd: string;
+	manifest?: RouteManifest;
+}
+
+export interface DevContext {
+	cwd: string;
+}
+
+export interface RenderContext {
+	request: Request;
+	url: URL;
+	route: { pattern: string } | null;
+	metadata: Metadata | null;
+}
+
+export interface BosiaPlugin {
+	name: string;
+
+	/**
+	 * Mount points around the framework's HTTP backend. Currently typed as
+	 * `Elysia` (the underlying backend), but the namespace is intentionally
+	 * abstract so the API survives a future backend swap.
+	 */
+	backend?: {
+		/** Runs before framework middleware/routes — can register routes that bypass Bosia. */
+		before?: (app: Elysia) => MaybePromise<Elysia>;
+		/** Runs after framework routes — receives the route manifest for introspection. */
+		after?: (app: Elysia, ctx: { manifest: RouteManifest }) => MaybePromise<Elysia>;
+	};
+
+	/** Build pipeline hooks. */
+	build?: {
+		preBuild?: (ctx: BuildContext) => MaybePromise<void>;
+		postScan?: (manifest: RouteManifest, ctx: BuildContext) => MaybePromise<void>;
+		bunPlugins?: (target: BuildTarget) => BunPlugin[];
+		postBuild?: (ctx: BuildContext) => MaybePromise<void>;
+	};
+
+	/** Dev pipeline hooks (wired in v0.5.0+). */
+	dev?: {
+		onStart?: (ctx: DevContext) => MaybePromise<void>;
+		onFileChange?: (path: string) => MaybePromise<void>;
+	};
+
+	/** SSR render hooks — emitted strings are injected into the streaming HTML. */
+	render?: {
+		/** Injected before `</head>`, after framework metadata. */
+		head?: (ctx: RenderContext) => MaybePromise<string>;
+		/** Injected before `</body>`, after hydration script. */
+		bodyEnd?: (ctx: RenderContext) => MaybePromise<string>;
+	};
+
+	/** Client lifecycle (wired in v0.5.0+). */
+	client?: {
+		onHydrate?: () => void;
+		onNavigate?: (to: URL, from: URL) => void;
+	};
+}
+
+export interface BosiaConfig {
+	plugins?: BosiaPlugin[];
+}
+
+/** Identity helper for type inference in `bosia.config.ts`. */
+export function defineConfig(config: BosiaConfig): BosiaConfig {
+	return config;
+}

package/src/core/types.ts

@@ -15,6 +15,13 @@ export interface PageRoute {
 	pageServer: string | null;
 	/** Chain of +layout.server.ts files root → leaf, with their layout depth */
 	layoutServers: { path: string; depth: number }[];
+	/**
+	 * Chain of +error.svelte files root → leaf. `depth` is the layout depth this
+	 * boundary protects: errors thrown by code at depth ≥ `depth` (page) or
+	 * depth > `depth` (layout) are caught by this page. Depth 0 = wrapped by no
+	 * layouts; depth N = wrapped by layouts[0..N-1].
+	 */
+	errorPages: { path: string; depth: number }[];
 	/** Effective trailing-slash mode (page wins over layout chain). Defaults to "never". */
 	trailingSlash: TrailingSlash;
 	/**

package/src/lib/index.ts

@@ -19,3 +19,12 @@ export type {
 } from "../core/hooks.ts";
 export type { CsrfConfig } from "../core/csrf.ts";
 export type { CorsConfig } from "../core/cors.ts";
+export { defineConfig } from "../core/types/plugin.ts";
+export type {
+	BosiaPlugin,
+	BosiaConfig,
+	BuildContext,
+	DevContext,
+	RenderContext,
+	BuildTarget,
+} from "../core/types/plugin.ts";