bosia 0.3.4 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bosia",
-	"version": "0.3.4",
+	"version": "0.4.1",
 	"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,9 @@
 	],
 	"exports": {
 		".": "./src/lib/index.ts",
-		"./client": "./src/lib/client.ts"
+		"./client": "./src/lib/client.ts",
+		"./plugins/server-timing": "./src/core/plugins/server-timing.ts",
+		"./plugins/inspector": "./src/core/plugins/inspector/index.ts"
 	},
 	"bin": {
 		"bosia": "src/cli/index.ts"
@@ -51,6 +53,7 @@
 		"@tailwindcss/cli": "^4.2.1",
 		"bun-plugin-svelte": "^0.0.6",
 		"elysia": "^1.4.26",
+		"magic-string": "^0.30.0",
 		"svelte": "^5.53.6",
 		"tailwind-merge": "^3.5.0",
 		"tailwindcss": "^4.2.1"

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/config.ts

@@ -0,0 +1,94 @@
+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 rawPlugins = Array.isArray(config.plugins) ? config.plugins : [];
+	const plugins = rawPlugins.filter((p): p is BosiaPlugin => Boolean(p));
+	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 ?? []).filter((p): p is BosiaPlugin => Boolean(p));
+}

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/inspector/bun-plugin.ts

@@ -0,0 +1,146 @@
+import { parse, compile } from "svelte/compiler";
+import MagicString from "magic-string";
+import { basename, relative } from "node:path";
+import type { BunPlugin } from "bun";
+
+const VIRTUAL_NS = "bosia-inspector-css";
+
+type AnyNode = {
+	type?: string;
+	name?: string;
+	start?: number;
+	end?: number;
+	[k: string]: unknown;
+};
+
+// Child-bearing keys across Svelte 5 modern AST nodes. Order doesn't matter.
+const CHILD_KEYS = [
+	"nodes", // Fragment
+	"fragment", // RegularElement, KeyBlock, SvelteElement, SvelteComponent
+	"consequent", // IfBlock (Fragment)
+	"alternate", // IfBlock (Fragment | null)
+	"body", // EachBlock, SnippetBlock (Fragment)
+	"fallback", // EachBlock (Fragment | null)
+	"pending", // AwaitBlock (Fragment | null)
+	"then", // AwaitBlock (Fragment | null)
+	"catch", // AwaitBlock (Fragment | null)
+];
+
+function walk(node: unknown, visit: (n: AnyNode) => void) {
+	if (!node) return;
+	if (Array.isArray(node)) {
+		for (const c of node) walk(c, visit);
+		return;
+	}
+	if (typeof node !== "object") return;
+	const n = node as AnyNode;
+	if (typeof n.type === "string") visit(n);
+	for (const key of CHILD_KEYS) {
+		const child = n[key];
+		if (child) walk(child, visit);
+	}
+}
+
+function lineColFromOffset(source: string, offset: number): { line: number; col: number } {
+	let line = 1;
+	let col = 1;
+	for (let i = 0; i < offset && i < source.length; i++) {
+		if (source[i] === "\n") {
+			line++;
+			col = 1;
+		} else {
+			col++;
+		}
+	}
+	return { line, col };
+}
+
+function injectLocs(source: string, relPath: string): string {
+	let ast: { fragment?: AnyNode };
+	try {
+		ast = parse(source, { modern: true }) as unknown as { fragment?: AnyNode };
+	} catch {
+		return source;
+	}
+	if (!ast.fragment) return source;
+
+	const ms = new MagicString(source);
+	walk(ast.fragment, (node) => {
+		if (node.type !== "RegularElement") return;
+		const name = node.name ?? "";
+		if (!name) return;
+		if (name === "script" || name === "style") return;
+		if (/^[A-Z]/.test(name)) return;
+		if (name.includes(":")) return;
+		if (typeof node.start !== "number") return;
+		const insertAt = node.start + 1 + name.length;
+		const { line, col } = lineColFromOffset(source, node.start);
+		const safe = relPath.replace(/"/g, "&quot;");
+		ms.appendLeft(insertAt, ` data-bosia-loc="${safe}:${line}:${col}"`);
+	});
+	return ms.toString();
+}
+
+export interface InspectorBunPluginOptions {
+	cwd: string;
+	target: "browser" | "bun";
+	dev: boolean;
+}
+
+const fnv = (s: string): string => {
+	let h = 2166136261;
+	for (let i = 0; i < s.length; i++) {
+		h ^= s.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+};
+
+export function createInspectorBunPlugin(opts: InspectorBunPluginOptions): BunPlugin {
+	const { cwd, target, dev } = opts;
+	const generate: "client" | "server" = target === "browser" ? "client" : "server";
+	const virtualCss = new Map<string, string>();
+
+	return {
+		name: "bosia-inspector",
+		setup(build) {
+			build.onLoad({ filter: /\.svelte$/ }, async (args) => {
+				const source = await Bun.file(args.path).text();
+				const rel = relative(cwd, args.path);
+				const transformed = injectLocs(source, rel);
+
+				const result = compile(transformed, {
+					filename: args.path,
+					generate,
+					dev,
+					hmr: dev,
+					css: "external",
+					preserveWhitespace: dev,
+					preserveComments: dev,
+					cssHash: ({ css }) => `svelte-${fnv(css)}`,
+				});
+
+				let js = result.js.code;
+				if (result.css?.code && generate !== "server") {
+					const uid = `${basename(args.path)}-${fnv(args.path)}-style.css`;
+					const virtualName = `${VIRTUAL_NS}:${uid}`;
+					virtualCss.set(virtualName, result.css.code);
+					js += `\nimport ${JSON.stringify(virtualName)};`;
+				}
+
+				return { contents: js, loader: "ts" };
+			});
+
+			build.onResolve({ filter: new RegExp(`^${VIRTUAL_NS}:`) }, (args) => ({
+				path: args.path,
+				namespace: VIRTUAL_NS,
+			}));
+
+			build.onLoad({ filter: /.*/, namespace: VIRTUAL_NS }, (args) => {
+				const css = virtualCss.get(args.path) ?? "";
+				virtualCss.delete(args.path);
+				return { contents: css, loader: "css" };
+			});
+		},
+	};
+}

package/src/core/plugins/inspector/index.ts

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { createInspectorBunPlugin } from "./bun-plugin.ts";
+import { getOverlayScript } from "./overlay.ts";
+import type { BosiaPlugin } from "../../types/plugin.ts";
+
+export interface InspectorOptions {
+	/** Editor CLI command. Defaults to `code`. */
+	editor?: "code" | "cursor" | "zed" | (string & {});
+	/** When set, alt+click opens a comment form whose contents POST here. */
+	aiEndpoint?: string;
+	/** Endpoint path the overlay POSTs to. Defaults to `/__bosia/locate`. */
+	endpoint?: string;
+}
+
+function buildEditorArgs(editor: string, file: string, line: number, col: number): string[] {
+	if (editor === "zed") return [`${file}:${line}:${col}`];
+	return ["-g", `${file}:${line}:${col}`];
+}
+
+/**
+ * Inspector plugin — alt+click an element in the running dev page to jump
+ * to its source in your editor, or open a comment form that hands off to an
+ * AI agent. Dev-only: production builds inject nothing and mount no endpoint.
+ */
+export function inspector(options: InspectorOptions = {}): BosiaPlugin | false {
+	if (process.env.NODE_ENV === "production") return false;
+	const editor = options.editor ?? "code";
+	const endpoint = options.endpoint ?? "/__bosia/locate";
+	const aiEndpoint = options.aiEndpoint;
+
+	return {
+		name: "inspector",
+
+		build: {
+			bunPlugins: (target) => [
+				createInspectorBunPlugin({ cwd: process.cwd(), target, dev: true }),
+			],
+		},
+
+		backend: {
+			before(app) {
+				return app.post(endpoint, async ({ body }: { body: unknown }) => {
+					const data = (body ?? {}) as {
+						file?: string;
+						line?: number;
+						col?: number;
+						comment?: string;
+					};
+					const file = typeof data.file === "string" ? data.file : null;
+					const line = Number.isFinite(data.line) ? Number(data.line) : null;
+					const col = Number.isFinite(data.col) ? Number(data.col) : 1;
+					if (!file || line === null) {
+						return new Response(
+							JSON.stringify({ ok: false, error: "missing file/line" }),
+							{
+								status: 400,
+								headers: { "content-type": "application/json" },
+							},
+						);
+					}
+
+					const comment = typeof data.comment === "string" ? data.comment.trim() : "";
+					if (comment && aiEndpoint) {
+						try {
+							let origin: string;
+							try {
+								origin = new URL(aiEndpoint).origin;
+							} catch {
+								origin = "http://localhost";
+							}
+							await fetch(aiEndpoint, {
+								method: "POST",
+								headers: {
+									"content-type": "application/json",
+									origin,
+								},
+								body: JSON.stringify({ file, line, col, comment }),
+							});
+							return { ok: true, mode: "ai" as const };
+						} catch (err) {
+							console.error("[inspector] aiEndpoint POST failed:", err);
+							return new Response(
+								JSON.stringify({ ok: false, error: "ai endpoint failed" }),
+								{
+									status: 502,
+									headers: { "content-type": "application/json" },
+								},
+							);
+						}
+					}
+
+					try {
+						const proc = spawn(editor, buildEditorArgs(editor, file, line, col), {
+							detached: true,
+							stdio: "ignore",
+						});
+						proc.unref();
+						proc.on("error", (err) => {
+							console.error(`[inspector] failed to launch "${editor}":`, err);
+						});
+					} catch (err) {
+						console.error(`[inspector] failed to launch "${editor}":`, err);
+						return new Response(
+							JSON.stringify({ ok: false, error: "editor launch failed" }),
+							{
+								status: 500,
+								headers: { "content-type": "application/json" },
+							},
+						);
+					}
+					return { ok: true, mode: "editor" as const };
+				});
+			},
+		},
+
+		render: {
+			bodyEnd: () => getOverlayScript({ aiEndpoint, endpoint }),
+		},
+	};
+}
+
+export default inspector;

package/src/core/plugins/inspector/overlay.ts

@@ -0,0 +1,116 @@
+import { safeJsonStringify } from "../../html.ts";
+
+export interface OverlayConfig {
+	aiEndpoint?: string;
+	endpoint: string;
+}
+
+export function getOverlayScript(config: OverlayConfig): string {
+	const cfg = safeJsonStringify(config);
+	return (
+		`<script>window.__BOSIA_INSPECTOR__=${cfg};</script>\n` + `<script>${OVERLAY_IIFE}</script>`
+	);
+}
+
+const OVERLAY_IIFE = `(function(){
+var CFG=window.__BOSIA_INSPECTOR__||{};
+var EP=CFG.endpoint||"/__bosia/locate";
+var AI=CFG.aiEndpoint||null;
+var altDown=false,outline=null,tip=null,form=null;
+
+function ensureOutline(){
+  if(outline)return;
+  outline=document.createElement("div");
+  outline.style.cssText="position:fixed;pointer-events:none;border:2px solid #f73b27;background:rgba(247,59,39,.08);z-index:2147483646;border-radius:2px;transition:all .05s linear;display:none";
+  document.body.appendChild(outline);
+  tip=document.createElement("div");
+  tip.style.cssText="position:fixed;pointer-events:none;background:#111;color:#fff;font:11px/1.4 ui-monospace,monospace;padding:3px 6px;border-radius:3px;z-index:2147483647;display:none;white-space:nowrap";
+  document.body.appendChild(tip);
+}
+function hideOutline(){if(outline)outline.style.display="none";if(tip)tip.style.display="none"}
+function showOutline(el,loc){
+  ensureOutline();
+  var r=el.getBoundingClientRect();
+  outline.style.display="block";
+  outline.style.left=r.left+"px";outline.style.top=r.top+"px";
+  outline.style.width=r.width+"px";outline.style.height=r.height+"px";
+  tip.style.display="block";tip.textContent=loc;
+  var ty=r.top-22;if(ty<0)ty=r.bottom+4;
+  tip.style.left=r.left+"px";tip.style.top=ty+"px";
+}
+function parseLoc(s){var m=/^(.+):(\\d+):(\\d+)$/.exec(s);if(!m)return null;return{file:m[1],line:+m[2],col:+m[3]}}
+function findTarget(e){var n=e.target;while(n&&n.nodeType===1){if(n.hasAttribute&&n.hasAttribute("data-bosia-loc"))return n;n=n.parentNode}return null}
+
+function toast(msg,err){
+  var t=document.createElement("div");
+  t.textContent=msg;
+  t.style.cssText="position:fixed;bottom:20px;left:50%;transform:translateX(-50%);background:"+(err?"#dc2626":"#111")+";color:#fff;padding:8px 14px;border-radius:6px;font:13px ui-sans-serif,system-ui,sans-serif;z-index:2147483647;box-shadow:0 4px 12px rgba(0,0,0,.2);opacity:0;transition:opacity .15s";
+  document.body.appendChild(t);
+  requestAnimationFrame(function(){t.style.opacity="1"});
+  setTimeout(function(){t.style.opacity="0";setTimeout(function(){t.remove()},200)},2200);
+}
+
+function send(payload,onOk){
+  fetch(EP,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify(payload)})
+    .then(function(r){return r.json().catch(function(){return{}})})
+    .then(function(j){if(j&&j.ok){onOk&&onOk(j)}else{toast("Inspector: request failed",true)}})
+    .catch(function(){toast("Inspector: network error",true)});
+}
+
+function closeForm(){if(form){form.remove();form=null}}
+function openForm(loc,el){
+  closeForm();
+  var r=el.getBoundingClientRect();
+  form=document.createElement("div");
+  form.style.cssText="position:fixed;left:"+r.left+"px;top:"+(r.bottom+6)+"px;background:#fff;color:#111;border:1px solid #d4d4d8;border-radius:8px;box-shadow:0 8px 24px rgba(0,0,0,.18);padding:10px;width:340px;z-index:2147483647;font:13px ui-sans-serif,system-ui,sans-serif";
+  form.innerHTML='<div style="font-size:11px;color:#71717a;margin-bottom:6px;font-family:ui-monospace,monospace">'+loc.file+":"+loc.line+'</div>'+
+    '<textarea placeholder="Describe a fix (Enter to send, Esc to cancel, empty = open in editor)" style="width:100%;min-height:64px;border:1px solid #e4e4e7;border-radius:4px;padding:6px;font:13px ui-sans-serif,system-ui,sans-serif;resize:vertical;box-sizing:border-box;outline:none"></textarea>'+
+    '<div style="margin-top:8px;display:flex;gap:6px;justify-content:flex-end">'+
+    '<button data-cancel style="padding:4px 10px;border:1px solid #e4e4e7;background:#fff;border-radius:4px;cursor:pointer;font-size:12px">Cancel</button>'+
+    '<button data-send style="padding:4px 10px;border:0;background:#111;color:#fff;border-radius:4px;cursor:pointer;font-size:12px">Send</button>'+
+    '</div>';
+  document.body.appendChild(form);
+  var ta=form.querySelector("textarea");
+  ta.focus();
+  function submit(){
+    var comment=ta.value.trim();
+    var payload={file:loc.file,line:loc.line,col:loc.col};
+    if(comment)payload.comment=comment;
+    send(payload,function(j){toast(j.mode==="ai"?"sent to AI":"opened "+loc.file+":"+loc.line)});
+    closeForm();
+  }
+  form.querySelector("[data-send]").addEventListener("click",submit);
+  form.querySelector("[data-cancel]").addEventListener("click",closeForm);
+  ta.addEventListener("keydown",function(e){
+    if(e.key==="Escape"){e.preventDefault();closeForm()}
+    else if(e.key==="Enter"&&!e.shiftKey){e.preventDefault();submit()}
+  });
+}
+
+window.addEventListener("keydown",function(e){
+  if(e.key==="Alt"||e.altKey)altDown=true;
+  if(e.key==="Escape")closeForm();
+},true);
+window.addEventListener("keyup",function(e){if(e.key==="Alt"){altDown=false;hideOutline()}},true);
+window.addEventListener("blur",function(){altDown=false;hideOutline()});
+
+window.addEventListener("mousemove",function(e){
+  if(!altDown||form){hideOutline();return}
+  var el=findTarget(e);
+  if(!el){hideOutline();return}
+  showOutline(el,el.getAttribute("data-bosia-loc"));
+},true);
+
+window.addEventListener("click",function(e){
+  if(!altDown)return;
+  if(form&&form.contains(e.target))return;
+  var el=findTarget(e);
+  if(!el)return;
+  e.preventDefault();e.stopPropagation();
+  var loc=parseLoc(el.getAttribute("data-bosia-loc"));
+  if(!loc)return;
+  hideOutline();
+  if(AI)openForm(loc,el);
+  else send(loc,function(){toast("opened "+loc.file+":"+loc.line)});
+},true);
+})();`;

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

@@ -15,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 ─────────────────────────────────────
 
@@ -326,6 +352,16 @@ export async function renderSSRStream(
 	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.
@@ -337,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" },
 		});
@@ -376,8 +412,19 @@ export async function renderSSRStream(
 	// 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;

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);
@@ -594,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 }) => {
@@ -612,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 | false | null | undefined)[];
+}
+
+/** Identity helper for type inference in `bosia.config.ts`. */
+export function defineConfig(config: BosiaConfig): BosiaConfig {
+	return config;
+}

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