@sigil-dev/grimoire 0.8.5 → 0.8.6

package/src/server/index.ts

@@ -17,12 +17,12 @@ import type { GrimoireConfig, WsRouteHandler } from "../types";
 import { buildProject } from "./build";
 import { createCookies } from "./cookie-utils";
 import type {
-	Handle,
-	HandleError,
-	HandleFetch,
-	InitFunction,
-	RequestEvent,
-	ResolveFunction,
+    Handle,
+    HandleError,
+    HandleFetch,
+    InitFunction,
+    RequestEvent,
+    ResolveFunction,
 } from "./hooks";
 import { runDeserializeLocals, runHook, runRequestHooks } from "./plugins";
 
@@ -31,621 +31,627 @@ const logger = log.scope("server");
  * Try to load hooks.server.ts from the project root.
  */
 async function loadHooks(projectRoot: string): Promise<{
-	handle?: Handle;
-	init?: InitFunction;
-	handleError?: HandleError;
-	handleFetch?: HandleFetch;
+    handle?: Handle;
+    init?: InitFunction;
+    handleError?: HandleError;
+    handleFetch?: HandleFetch;
 }> {
-	const hooksPath = `${projectRoot}/hooks.server.ts`;
-	try {
-		const mod = await import(hooksPath);
-		return {
-			handle: mod.handle,
-			init: mod.init,
-			handleError: mod.handleError,
-			handleFetch: mod.handleFetch,
-		};
-	} catch {
-		// no hooks file — that's fine
-		return {};
-	}
+    const hooksPath = `${projectRoot}/hooks.server.ts`;
+    try {
+        const mod = await import(hooksPath);
+        return {
+            handle: mod.handle,
+            init: mod.init,
+            handleError: mod.handleError,
+            handleFetch: mod.handleFetch,
+        };
+    } catch {
+        // no hooks file — that's fine
+        return {};
+    }
 }
 
 interface _WsInternalData {
-	params: Record<string, string>;
-	// always present at runtime — optional only to satisfy TypeScript;
-	// upgrade block gates on mod.websocket before calling server.upgrade()
-	__handler?: WsRouteHandler<any>;
-	[key: string]: unknown;
+    params: Record<string, string>;
+    // always present at runtime — optional only to satisfy TypeScript;
+    // upgrade block gates on mod.websocket before calling server.upgrade()
+    __handler?: WsRouteHandler<any>;
+    [key: string]: unknown;
 }
 
 export async function createServer(config: GrimoireConfig = {}) {
-	// run config hooks
-	let finalConfig = config;
-	const earlyPlugins = config.plugins ?? [];
-	for (const plugin of earlyPlugins) {
-		finalConfig = plugin.config?.(finalConfig) ?? finalConfig;
-	}
-
-	const {
-		port = 3000,
-		host = "localhost",
-		plugins = [],
-		dev = false,
-		routes = "src/routes",
-		cspNonce,
-		//biome-ignore lint: not implemented yet
-		devEditor = "code",
-		_skipBuild = false,
-	} = finalConfig;
-
-	let tree: any;
-	if (!config._skipBuild) {
-		const { result, tree: _tree } = await buildProject(finalConfig, plugins);
-		if (!result.success) throw new Error("Grimoire: build failed");
-		tree = _tree;
-	} else {
-		// worker — build already done by loom, just scan routes
-		const routesDir = isAbsolute(routes) ? routes : join(process.cwd(), routes);
-		const { scanRoutes } = await import("../routing/scanner");
-		tree = await scanRoutes(routesDir, process.cwd());
-	}
-
-	// SSR plugin should NOT INTNERCEPT FILES BUNDLEDFOR CLIENT
-	// WHAT ARE WE DOINGGGGGGGGG
-	registerSSRPlugin(plugins);
-
-	const graph = new DevGraph();
-	const hmr = dev ? new HmrServer() : null;
-
-	if (dev) {
-		const { ensureRuntimeBundle } = await import("../dev/runtime-bundle.ts");
-		await ensureRuntimeBundle(process.cwd());
-
-		// clean dev-modules cache from previous session
-		const { rmSync, mkdirSync } = await import("node:fs");
-		const devModulesDir = join(process.cwd(), ".grimoire/dev-modules");
-		try {
-			rmSync(devModulesDir, { recursive: true, force: true });
-		} catch {}
-		mkdirSync(devModulesDir, { recursive: true });
-
-		// register route files and scan their imports for the graph
-		const srcDir = isAbsolute(routes) ? routes : join(process.cwd(), routes);
-		const allFiles = [
-			...tree.routes,
-			...tree.layouts,
-			...tree.servers,
-			...tree.errors,
-		];
-
-		await Promise.all(
-			allFiles.map(async (rf) => {
-				graph.getOrCreate(rf.filePath, rf.filePath);
-				graph.markRoute(rf.filePath, rf);
-				try {
-					const source = await Bun.file(rf.filePath).text();
-					const imports = new Bun.Transpiler({ loader: "tsx" }).scanImports(
-						source,
-					);
-					for (const imp of imports) {
-						if (imp.path.startsWith(".") || imp.path.startsWith("$lib")) {
-							const resolved = imp.path.startsWith("$lib")
-								? join(process.cwd(), "src/lib", imp.path.slice(5))
-								: join(dirname(rf.filePath), imp.path);
-							graph.addEdge(rf.filePath, resolved);
-							// also register lib files as graph nodes
-							graph.getOrCreate(resolved, resolved);
-						}
-					}
-				} catch {}
-			}),
-		);
-
-		startWatcher(srcDir, (f) =>
-			handleChange(f, graph, hmr!, srcDir, process.cwd(), tree),
-		);
-	}
-
-	const loader = dev
-		? makeDevLoader(graph, process.cwd())
-		: (p: string) => import(p);
-	// Load hooks.server.ts
-	const {
-		handle: hooksHandle,
-		init: hooksInit,
-		handleError: hooksHandleError,
-		handleFetch: hooksHandleFetch,
-	} = await loadHooks(process.cwd());
-
-	// Run init hook if present
-	await hooksInit?.();
-
-	// Register alias plugin so dynamically-imported +server.ts routes can resolve custom aliases
-	const aliases = finalConfig.alias ?? {};
-	if (Object.keys(aliases).length > 0) {
-		bunPlugin({
-			name: "grimoire-alias",
-			setup(build) {
-				for (const [prefix, target] of Object.entries(aliases)) {
-					const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-					build.onResolve(
-						{ filter: new RegExp(`^${escaped}(/|$)`) },
-						(args) => ({
-							path: args.path.replace(prefix, join(process.cwd(), target)),
-						}),
-					);
-				}
-			},
-		});
-	}
-	const server = Bun.serve({
-		port,
-		hostname: host,
-		fetch: async (req) => {
-			const rawLocals = req.headers.get("X-Grimoire-Locals");
-			const locals: App.Locals = rawLocals
-				? ((await runDeserializeLocals(plugins, rawLocals)) ?? {})
-				: {};
-			const url = new URL(req.url);
-
-			if (dev && url.pathname === "/__grimoire__/hmr") {
-				//@ts-expect-error holy shut up
-				if (server.upgrade(req, { data: { __hmrClient: true } })) {
-					return undefined as unknown as Response;
-				}
-				return new Response("Upgrade Required", { status: 426 });
-			}
-			if (dev && url.pathname === "/__grimoire__/hmr-client.js") {
-				return new Response(HMR_CLIENT_SOURCE, {
-					headers: { "Content-Type": "application/javascript" },
-				});
-			}
-			if (dev && url.pathname === "/__grimoire__/open") {
-				const file = url.searchParams.get("file") ?? "";
-				const line = url.searchParams.get("line") ?? "1";
-				const col = url.searchParams.get("col") ?? "1";
-				const editor = finalConfig.devEditor ?? "code";
-				//@ts-expect-error Bun spawn has werird types just shut up
-				Bun.spawn([editor, "--goto", `${file}:${line}:${col}`]);
-				return new Response(null, { status: 204 });
-			}
-			if (dev && url.pathname.startsWith("/__grimoire__/dep/")) {
-				const depName = decodeURIComponent(
-					url.pathname.slice("/__grimoire__/dep/".length).replace(/\.js$/, ""),
-				);
-
-				// grimoire shim
-				if (depName.includes("@sigil-dev__grimoire")) {
-					return Response.redirect("/__grimoire__/grimoire-client.js", 302);
-				}
-
-				// convert URL-safe name back to package name
-				// @codex__shared → @codex/shared
-				const pkgName = depName.startsWith("@")
-					? depName.replace("__", "/")
-					: depName;
-
-				const depsDir = join(process.cwd(), ".grimoire/deps");
-				mkdirSync(depsDir, { recursive: true });
-				const outFile = join(depsDir, `${depName}.js`);
-
-				if (!(await Bun.file(outFile).exists())) {
-					logger.debug("bundling dep:", pkgName);
-					try {
-						const entry = Bun.resolveSync(pkgName, process.cwd());
-						const result = await Bun.build({
-							entrypoints: [entry],
-							outdir: depsDir,
-							naming: `${depName}.js`,
-							target: "browser",
-							format: "esm",
-							minify: false,
-							external: ["@sigil-dev/runtime"],
-						});
-						if (!result.success) {
-							logger.error("dep bundle failed:", pkgName, result.logs);
-							return new Response(
-								`throw new Error("failed to bundle dep: ${pkgName}")`,
-								{ headers: { "Content-Type": "application/javascript" } },
-							);
-						}
-						logger.debug("bundled dep:", pkgName);
-					} catch (e: any) {
-						return new Response(
-							`throw new Error("dep not found: ${pkgName}: ${e.message}")`,
-							{ headers: { "Content-Type": "application/javascript" } },
-						);
-					}
-				}
-
-				return new Response(Bun.file(outFile), {
-					headers: {
-						"Content-Type": "application/javascript",
-						"Cache-Control": "no-store",
-					},
-				});
-			}
-
-			if (dev && url.pathname.startsWith("/__grimoire__/m/")) {
-				const clientPath = decodeURIComponent(
-					url.pathname.slice("/__grimoire__/m/".length),
-				);
-				const v = url.searchParams.get("v");
-
-				if (v) {
-					// versioned request — serve from dev-modules cache
-					// find the cache file for this version
-					const { createHash } = await import("node:crypto");
-					const absPath = join(process.cwd(), clientPath.replace(/\.js$/, ""));
-					const fileHash = createHash("md5")
-						.update(absPath)
-						.digest("hex")
-						.slice(0, 8);
-					const cachePath = join(
-						process.cwd(),
-						`.grimoire/dev-modules/${fileHash}_v${v}.js`,
-					);
-					const file = Bun.file(cachePath);
-					if (await file.exists()) {
-						return new Response(file, {
-							headers: {
-								"Content-Type": "application/javascript",
-								"Cache-Control": "no-store",
-							},
-						});
-					}
-				}
-
-				// unversioned or cache miss — compile on demand
-				const absPath = join(process.cwd(), clientPath.replace(/\.js$/, ""));
-				try {
-					const { compileForBrowser } = await import("../dev/compile-module");
-					const result = await compileForBrowser(absPath, process.cwd());
-					return new Response(result.js, {
-						headers: {
-							"Content-Type": "application/javascript",
-							"Cache-Control": "no-store",
-						},
-					});
-				} catch (e: any) {
-					return new Response(`throw new Error(${JSON.stringify(e.message)})`, {
-						headers: { "Content-Type": "application/javascript" },
-					});
-				}
-			}
-
-			return runRequestHooks(plugins, req, async () => {
-				const publicFile = Bun.file(`${process.cwd()}/public${url.pathname}`);
-				if (await publicFile.exists()) {
-					return new Response(publicFile);
-				}
-
-				const HTTP_METHODS = [
-					"GET",
-					"POST",
-					"PUT",
-					"PATCH",
-					"DELETE",
-					"HEAD",
-					"OPTIONS",
-				] as const;
-
-				// Build event BEFORE matching — handle() runs pre-match like SvelteKit
-				const cookieHeader = req.headers.get("cookie") ?? "";
-				const cookies = createCookies(cookieHeader);
-				const setHeadersMap: Record<string, string> = {};
-
-				const event: RequestEvent = {
-					request: req,
-					url,
-					params: {},
-					locals,
-					cookies,
-					route: { id: "" },
-					fetch: globalThis.fetch,
-					setHeaders: (headers) => Object.assign(setHeadersMap, headers),
-				};
-
-				if (hooksHandleFetch) {
-					event.fetch = (reqInfo: RequestInfo | URL, init?: RequestInit) => {
-						const r = new Request(reqInfo, init);
-						return Promise.resolve(
-							hooksHandleFetch({ request: r, fetch: globalThis.fetch, event }),
-						);
-					};
-				}
-
-				const resolve: ResolveFunction = async (evt) => {
-					// matching happens here — after handle() has run
-					const matched = matchRoute(tree, evt.url);
-
-					if (!matched) {
-						const error = findClosestError(tree.errors, evt.url.pathname);
-						if (error) {
-							const mod = await loader(error.filePath);
-							const html = mod.default({ status: 404, message: "Not Found" });
-							return new Response(html, {
-								status: 404,
-								headers: { "Content-Type": "text/html" },
-							});
-						}
-						return new Response("Not Found", { status: 404 });
-					}
-
-					// patch event with match results so handle() epilogue can read them
-					evt.params = matched.params;
-					evt.route = { id: matched.route.path };
-
-					// API routes (+server.ts)
-					if (matched.route.type === "server") {
-						const mod = await loader(matched.route.filePath);
-
-						const isWsUpgrade =
-							evt.request.headers.get("upgrade")?.toLowerCase() === "websocket";
-						if (isWsUpgrade && mod.websocket) {
-							let extraData: Record<string, unknown> = {};
-							if (mod.upgrade) {
-								try {
-									const result = await mod.upgrade({
-										request: evt.request,
-										params: matched.params,
-										url: evt.url,
-										locals: evt.locals,
-									});
-									if (result && typeof result === "object") extraData = result;
-								} catch {
-									return new Response("Upgrade Required", { status: 426 });
-								}
-							}
-							const wsData: _WsInternalData = {
-								params: matched.params,
-								__handler: mod.websocket,
-								...extraData,
-							};
-							//@ts-expect-error i dont know what you are talking about please
-							if (server.upgrade(req, { data: wsData })) {
-								return undefined as unknown as Response;
-							}
-							return new Response("Upgrade Required", { status: 426 });
-						}
-
-						const handler = mod[evt.request.method];
-						if (!handler) {
-							return new Response("Method Not Allowed", { status: 405 });
-						}
-						return handler({
-							request: evt.request,
-							params: matched.params,
-							url: evt.url,
-							locals: evt.locals,
-						});
-					}
-
-					// form actions (+page.server.ts)
-					if (
-						matched.pageServer &&
-						HTTP_METHODS.includes(evt.request.method as any)
-					) {
-						const mod = await loader(matched.pageServer.filePath);
-
-						if (
-							mod.csrf !== false &&
-							evt.request.method !== "GET" &&
-							evt.request.method !== "HEAD"
-						) {
-							const cookieToken = cookies.get("_csrf");
-							const formData = await evt.request
-								.clone()
-								.formData()
-								.catch(() => null);
-							const bodyToken = formData?.get("_csrf");
-							if (!cookieToken || cookieToken !== String(bodyToken)) {
-								return new Response("Forbidden", { status: 403 });
-							}
-						}
-
-						const handler = mod[evt.request.method];
-						if (handler) {
-							let result: any;
-							try {
-								result = await handler({
-									request: evt.request,
-									params: matched.params,
-									url: evt.url,
-									locals: evt.locals,
-								});
-							} catch (e) {
-								if (isRedirectResult(e)) {
-									return new Response(null, {
-										status: e.status,
-										headers: { Location: e.location },
-									});
-								}
-								if (isErrorResult(e)) {
-									const isApi = evt.request.headers
-										.get("accept")
-										?.includes("application/json");
-									if (isApi) {
-										return Response.json(
-											{ error: true, status: e.status, message: e.message },
-											{ status: e.status },
-										);
-									}
-									const errorPage = findClosestError(
-										tree.errors,
-										evt.url.pathname,
-									);
-									if (errorPage) {
-										const errMod = await loader(errorPage.filePath);
-										const html = errMod.default({
-											status: e.status,
-											message: e.message,
-										});
-										return new Response(html, {
-											status: e.status,
-											headers: { "Content-Type": "text/html" },
-										});
-									}
-									return new Response(e.message, { status: e.status });
-								}
-								throw e;
-							}
-
-							if (isFailResult(result)) {
-								return Response.json(
-									{ fail: true, status: result.status, data: result.data },
-									{ status: result.status },
-								);
-							}
-
-							const redirectTo =
-								result?.redirect ?? evt.request.headers.get("referer") ?? "/";
-							return new Response(null, {
-								status: 303,
-								headers: { Location: redirectTo },
-							});
-						}
-						if (evt.request.method !== "GET") {
-							return new Response("Method Not Allowed", { status: 405 });
-						}
-					}
-
-					// page routes
-					const response = await renderRoute(
-						matched,
-						evt.request,
-						tree.errors,
-						loader,
-						evt.locals,
-						plugins,
-						cspNonce,
-						dev,
-					);
-
-					if (evt.request.headers.get("x-grimoire-navigate") === "1") {
-						return response;
-					}
-
-					const hasRenderPlugins = plugins.some((p) => p.onRouteRender);
-					if (hasRenderPlugins) {
-						let html = await response.text();
-						for (const plugin of plugins) {
-							html =
-								(await plugin.onRouteRender?.(html, {
-									route: matched.route,
-									request: evt.request,
-									params: matched.params,
-									data: undefined,
-								})) ?? html;
-						}
-						return new Response(html, {
-							headers: { "Content-Type": "text/html" },
-						});
-					}
-
-					return response;
-				};
-
-				let response: Response;
-				try {
-					if (!hooksHandle) {
-						response = await resolve(event);
-					} else {
-						response = await hooksHandle({ event, resolve });
-					}
-				} catch (err) {
-					console.error(
-						`[grimoire] ${event.request.method} ${event.url.pathname} failed:`,
-						err,
-					);
-					await hooksHandleError?.({
-						error: err,
-						event,
-						status: 500,
-						message: "Internal Server Error",
-					});
-					const errorHtmlPath = `${process.cwd()}/error.html`;
-					try {
-						const errorFile = Bun.file(errorHtmlPath);
-						if (await errorFile.exists()) {
-							return new Response(errorFile, {
-								status: 500,
-								headers: { "Content-Type": "text/html" },
-							});
-						}
-					} catch {}
-					const message =
-						process.env.NODE_ENV === "production"
-							? "Internal Server Error"
-							: `${err instanceof Error ? `${err.message}\n${err.stack}` : String(err)}`;
-					return new Response(message, { status: 500 });
-				}
-
-				const setCookieHeaders = cookies.toHeaders();
-				if (
-					setCookieHeaders.length > 0 ||
-					Object.keys(setHeadersMap).length > 0
-				) {
-					const headers = new Headers(response.headers);
-					for (const [k, v] of Object.entries(setHeadersMap)) {
-						headers.set(k, v);
-					}
-					for (const sc of setCookieHeaders) {
-						headers.append("Set-Cookie", sc);
-					}
-					response = new Response(response.body, {
-						status: response.status,
-						statusText: response.statusText,
-						headers,
-					});
-				}
-
-				return response;
-			});
-		},
-		websocket: {
-			open(ws: ServerWebSocket<any>) {
-				if (ws.data.__hmrClient) {
-					hmr?.addClient(ws);
-					return;
-				}
-				(ws.data as _WsInternalData).__handler?.open?.(ws);
-			},
-			message(ws: ServerWebSocket<any>, data: string | Buffer) {
-				if (ws.data.__hmrClient) return;
-				(ws.data as _WsInternalData).__handler?.message?.(ws, data);
-			},
-			close(ws: ServerWebSocket<any>, code: number, reason?: string) {
-				if (ws.data.__hmrClient) {
-					hmr?.removeClient(ws);
-					return;
-				}
-				(ws.data as _WsInternalData).__handler?.close?.(ws, code, reason);
-			},
-			drain(ws: ServerWebSocket<any>) {
-				if (ws.data.__hmrClient) return;
-				(ws.data as _WsInternalData).__handler?.drain?.(ws);
-			},
-		},
-	});
-
-	let stopping = false;
-	const handleShutdown = async () => {
-		if (stopping) return;
-		stopping = true;
-		await runHook(plugins, "onStop", "shutdown");
-		server.stop();
-		process.exit(0);
-	};
-	process.on("SIGINT", handleShutdown);
-	process.on("SIGTERM", handleShutdown);
-
-	await runHook(plugins, "onStart", {
-		port: server.port,
-		hostname: server.hostname,
-		stop: () => server.stop(),
-	});
-	// console.log(`Grimoire running at http://${host}:${port}`);
-	return server;
+    // run config hooks
+    let finalConfig = config;
+    const earlyPlugins = config.plugins ?? [];
+    for (const plugin of earlyPlugins) {
+        finalConfig = plugin.config?.(finalConfig) ?? finalConfig;
+    }
+
+    const {
+        port = 3000,
+        host = "localhost",
+        plugins = [],
+        dev = false,
+        routes = "src/routes",
+        cspNonce,
+        //biome-ignore lint: not implemented yet
+        devEditor = "code",
+        _skipBuild = false,
+    } = finalConfig;
+
+    let tree: any;
+    if (!config._skipBuild) {
+        const { result, tree: _tree } = await buildProject(finalConfig, plugins);
+        if (!result.success) throw new Error("Grimoire: build failed");
+        tree = _tree;
+    } else {
+        // worker — build already done by loom, just scan routes
+        const routesDir = isAbsolute(routes) ? routes : join(process.cwd(), routes);
+        const { scanRoutes } = await import("../routing/scanner");
+        tree = await scanRoutes(routesDir, process.cwd());
+    }
+
+    // SSR plugin should NOT INTNERCEPT FILES BUNDLEDFOR CLIENT
+    // WHAT ARE WE DOINGGGGGGGGG
+    registerSSRPlugin(plugins);
+
+    const graph = new DevGraph();
+    const hmr = dev ? new HmrServer() : null;
+
+    if (dev) {
+        const { ensureRuntimeBundle } = await import("../dev/runtime-bundle.ts");
+        await ensureRuntimeBundle(process.cwd());
+
+        // clean dev-modules cache from previous session
+        const { rmSync, mkdirSync } = await import("node:fs");
+        const devModulesDir = join(process.cwd(), ".grimoire/dev-modules");
+        try {
+            rmSync(devModulesDir, { recursive: true, force: true });
+        } catch { }
+        mkdirSync(devModulesDir, { recursive: true });
+
+        // register route files and scan their imports for the graph
+        const srcDir = isAbsolute(routes) ? routes : join(process.cwd(), routes);
+        const allFiles = [
+            ...tree.routes,
+            ...tree.layouts,
+            ...tree.servers,
+            ...tree.errors,
+        ];
+
+        await Promise.all(
+            allFiles.map(async (rf) => {
+                graph.getOrCreate(rf.filePath, rf.filePath);
+                graph.markRoute(rf.filePath, rf);
+                try {
+                    const source = await Bun.file(rf.filePath).text();
+                    const imports = new Bun.Transpiler({ loader: "tsx" }).scanImports(
+                        source,
+                    );
+                    for (const imp of imports) {
+                        if (imp.path.startsWith(".") || imp.path.startsWith("$lib")) {
+                            const resolved = imp.path.startsWith("$lib")
+                                ? join(process.cwd(), "src/lib", imp.path.slice(5))
+                                : join(dirname(rf.filePath), imp.path);
+                            graph.addEdge(rf.filePath, resolved);
+                            // also register lib files as graph nodes
+                            graph.getOrCreate(resolved, resolved);
+                        }
+                    }
+                } catch { }
+            }),
+        );
+
+        startWatcher(srcDir, (f) =>
+            handleChange(f, graph, hmr!, srcDir, process.cwd(), tree),
+        );
+    }
+
+    const loader = dev
+        ? makeDevLoader(graph, process.cwd())
+        : (p: string) => import(p);
+    // Load hooks.server.ts
+    const {
+        handle: hooksHandle,
+        init: hooksInit,
+        handleError: hooksHandleError,
+        handleFetch: hooksHandleFetch,
+    } = await loadHooks(process.cwd());
+
+    // Run init hook if present
+    await hooksInit?.();
+
+    // Register alias plugin so dynamically-imported +server.ts routes can resolve custom aliases
+    const aliases = finalConfig.alias ?? {};
+    if (Object.keys(aliases).length > 0) {
+        bunPlugin({
+            name: "grimoire-alias",
+            setup(build) {
+                for (const [prefix, target] of Object.entries(aliases)) {
+                    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                    build.onResolve(
+                        { filter: new RegExp(`^${escaped}(/|$)`) },
+                        (args) => ({
+                            path: args.path.replace(prefix, join(process.cwd(), target)),
+                        }),
+                    );
+                }
+            },
+        });
+    }
+    const server = Bun.serve({
+        port,
+        hostname: host,
+        fetch: async (req) => {
+            const rawLocals = req.headers.get("X-Grimoire-Locals");
+            const locals: App.Locals = rawLocals
+                ? ((await runDeserializeLocals(plugins, rawLocals)) ?? {})
+                : {};
+            const url = new URL(req.url);
+
+            if (dev && url.pathname === "/__grimoire__/hmr") {
+                //@ts-expect-error holy shut up
+                if (server.upgrade(req, { data: { __hmrClient: true } })) {
+                    return undefined as unknown as Response;
+                }
+                return new Response("Upgrade Required", { status: 426 });
+            }
+            if (dev && url.pathname === "/__grimoire__/hmr-client.js") {
+                return new Response(HMR_CLIENT_SOURCE, {
+                    headers: { "Content-Type": "application/javascript" },
+                });
+            }
+            if (dev && url.pathname === "/__grimoire__/open") {
+                const file = url.searchParams.get("file") ?? "";
+                const line = url.searchParams.get("line") ?? "1";
+                const col = url.searchParams.get("col") ?? "1";
+                const editor = finalConfig.devEditor ?? "code";
+                //@ts-expect-error Bun spawn has werird types just shut up
+                Bun.spawn([editor, "--goto", `${file}:${line}:${col}`]);
+                return new Response(null, { status: 204 });
+            }
+            if (dev && url.pathname.startsWith("/__grimoire__/dep/")) {
+                const depName = decodeURIComponent(
+                    url.pathname.slice("/__grimoire__/dep/".length).replace(/\.js$/, ""),
+                );
+
+                // grimoire shim
+                if (depName.includes("@sigil-dev__grimoire")) {
+                    return Response.redirect("/__grimoire__/grimoire-client.js", 302);
+                }
+
+                // convert URL-safe name back to package name
+                // @codex__shared → @codex/shared
+                const pkgName = depName.startsWith("@")
+                    ? depName.replace("__", "/")
+                    : depName;
+
+                const depsDir = join(process.cwd(), ".grimoire/deps");
+                mkdirSync(depsDir, { recursive: true });
+                const outFile = join(depsDir, `${depName}.js`);
+
+                if (!(await Bun.file(outFile).exists())) {
+                    logger.debug("bundling dep:", pkgName);
+                    try {
+                        const entry = Bun.resolveSync(pkgName, process.cwd());
+                        const result = await Bun.build({
+                            entrypoints: [entry],
+                            outdir: depsDir,
+                            naming: `${depName}.js`,
+                            target: "browser",
+                            format: "esm",
+                            minify: false,
+                            external: ["@sigil-dev/runtime"],
+                        });
+                        if (!result.success) {
+                            logger.error("dep bundle failed:", pkgName, result.logs);
+                            return new Response(
+                                `throw new Error("failed to bundle dep: ${pkgName}")`,
+                                { headers: { "Content-Type": "application/javascript" } },
+                            );
+                        }
+                        logger.debug("bundled dep:", pkgName);
+                    } catch (e: any) {
+                        return new Response(
+                            `throw new Error("dep not found: ${pkgName}: ${e.message}")`,
+                            { headers: { "Content-Type": "application/javascript" } },
+                        );
+                    }
+                }
+
+                return new Response(Bun.file(outFile), {
+                    headers: {
+                        "Content-Type": "application/javascript",
+                        "Cache-Control": "no-store",
+                    },
+                });
+            }
+
+            if (dev && url.pathname.startsWith("/__grimoire__/m/")) {
+                const clientPath = decodeURIComponent(
+                    url.pathname.slice("/__grimoire__/m/".length),
+                );
+                const v = url.searchParams.get("v");
+
+                if (v) {
+                    // versioned request — serve from dev-modules cache
+                    // find the cache file for this version
+                    const { createHash } = await import("node:crypto");
+                    const absPath = join(process.cwd(), clientPath.replace(/\.js$/, ""));
+                    const fileHash = createHash("md5")
+                        .update(absPath)
+                        .digest("hex")
+                        .slice(0, 8);
+                    const cachePath = join(
+                        process.cwd(),
+                        `.grimoire/dev-modules/${fileHash}_v${v}.js`,
+                    );
+                    const file = Bun.file(cachePath);
+                    if (await file.exists()) {
+                        return new Response(file, {
+                            headers: {
+                                "Content-Type": "application/javascript",
+                                "Cache-Control": "no-store",
+                            },
+                        });
+                    }
+                }
+
+                // unversioned or cache miss — compile on demand
+                const absPath = join(process.cwd(), clientPath.replace(/\.js$/, ""));
+                try {
+                    const { compileForBrowser } = await import("../dev/compile-module");
+                    const result = await compileForBrowser(absPath, process.cwd());
+                    return new Response(result.js, {
+                        headers: {
+                            "Content-Type": "application/javascript",
+                            "Cache-Control": "no-store",
+                        },
+                    });
+                } catch (e: any) {
+                    return new Response(`throw new Error(${JSON.stringify(e.message)})`, {
+                        headers: { "Content-Type": "application/javascript" },
+                    });
+                }
+            }
+
+            return runRequestHooks(plugins, req, async () => {
+                const publicFile = Bun.file(`${process.cwd()}/public${url.pathname}`);
+                if (await publicFile.exists()) {
+                    return new Response(publicFile);
+                }
+
+                const HTTP_METHODS = [
+                    "GET",
+                    "POST",
+                    "PUT",
+                    "PATCH",
+                    "DELETE",
+                    "HEAD",
+                    "OPTIONS",
+                ] as const;
+
+                // Build event BEFORE matching — handle() runs pre-match like SvelteKit
+                const cookieHeader = req.headers.get("cookie") ?? "";
+                const cookies = createCookies(cookieHeader);
+                const setHeadersMap: Record<string, string> = {};
+
+                const event: RequestEvent = {
+                    request: req,
+                    url,
+                    params: {},
+                    locals,
+                    cookies,
+                    route: { id: "" },
+                    fetch: globalThis.fetch,
+                    setHeaders: (headers) => Object.assign(setHeadersMap, headers),
+                };
+
+                if (hooksHandleFetch) {
+                    event.fetch = (reqInfo: RequestInfo | URL, init?: RequestInit) => {
+                        const r = new Request(reqInfo, init);
+                        return Promise.resolve(
+                            hooksHandleFetch({ request: r, fetch: globalThis.fetch, event }),
+                        );
+                    };
+                }
+                const patchedFetch: typeof fetch = (input, init) => {
+                    const resolved = typeof input === "string" && input.startsWith("/")
+                        ? new URL(input, url.origin).toString()
+                        : input;
+                    return globalThis.fetch(resolved as any, init);
+                };
+                const resolve: ResolveFunction = async (evt) => {
+                    // matching happens here — after handle() has run
+                    const matched = matchRoute(tree, evt.url);
+
+                    if (!matched) {
+                        const error = findClosestError(tree.errors, evt.url.pathname);
+                        if (error) {
+                            const mod = await loader(error.filePath);
+                            const html = mod.default({ status: 404, message: "Not Found" });
+                            return new Response(html, {
+                                status: 404,
+                                headers: { "Content-Type": "text/html" },
+                            });
+                        }
+                        return new Response("Not Found", { status: 404 });
+                    }
+
+                    // patch event with match results so handle() epilogue can read them
+                    evt.params = matched.params;
+                    evt.route = { id: matched.route.path };
+
+                    // API routes (+server.ts)
+                    if (matched.route.type === "server") {
+                        const mod = await loader(matched.route.filePath);
+
+                        const isWsUpgrade =
+                            evt.request.headers.get("upgrade")?.toLowerCase() === "websocket";
+                        if (isWsUpgrade && mod.websocket) {
+                            let extraData: Record<string, unknown> = {};
+                            if (mod.upgrade) {
+                                try {
+                                    const result = await mod.upgrade({
+                                        request: evt.request,
+                                        params: matched.params,
+                                        url: evt.url,
+                                        locals: evt.locals,
+                                    });
+                                    if (result && typeof result === "object") extraData = result;
+                                } catch {
+                                    return new Response("Upgrade Required", { status: 426 });
+                                }
+                            }
+                            const wsData: _WsInternalData = {
+                                params: matched.params,
+                                __handler: mod.websocket,
+                                ...extraData,
+                            };
+                            //@ts-expect-error i dont know what you are talking about please
+                            if (server.upgrade(req, { data: wsData })) {
+                                return undefined as unknown as Response;
+                            }
+                            return new Response("Upgrade Required", { status: 426 });
+                        }
+
+                        const handler = mod[evt.request.method];
+                        if (!handler) {
+                            return new Response("Method Not Allowed", { status: 405 });
+                        }
+                        return handler({
+                            request: evt.request,
+                            params: matched.params,
+                            url: evt.url,
+                            locals: evt.locals,
+                        });
+                    }
+
+                    // form actions (+page.server.ts)
+                    if (
+                        matched.pageServer &&
+                        HTTP_METHODS.includes(evt.request.method as any)
+                    ) {
+                        const mod = await loader(matched.pageServer.filePath);
+
+                        if (
+                            mod.csrf !== false &&
+                            evt.request.method !== "GET" &&
+                            evt.request.method !== "HEAD"
+                        ) {
+                            const cookieToken = cookies.get("_csrf");
+                            const formData = await evt.request
+                                .clone()
+                                .formData()
+                                .catch(() => null);
+                            const bodyToken = formData?.get("_csrf");
+                            if (!cookieToken || cookieToken !== String(bodyToken)) {
+                                return new Response("Forbidden", { status: 403 });
+                            }
+                        }
+
+                        const handler = mod[evt.request.method];
+                        if (handler) {
+                            let result: any;
+                            try {
+                                result = await handler({
+                                    request: evt.request,
+                                    params: matched.params,
+                                    url: evt.url,
+                                    locals: evt.locals,
+                                    fetch: patchedFetch,
+                                });
+                            } catch (e) {
+                                if (isRedirectResult(e)) {
+                                    return new Response(null, {
+                                        status: e.status,
+                                        headers: { Location: e.location },
+                                    });
+                                }
+                                if (isErrorResult(e)) {
+                                    const isApi = evt.request.headers
+                                        .get("accept")
+                                        ?.includes("application/json");
+                                    if (isApi) {
+                                        return Response.json(
+                                            { error: true, status: e.status, message: e.message },
+                                            { status: e.status },
+                                        );
+                                    }
+                                    const errorPage = findClosestError(
+                                        tree.errors,
+                                        evt.url.pathname,
+                                    );
+                                    if (errorPage) {
+                                        const errMod = await loader(errorPage.filePath);
+                                        const html = errMod.default({
+                                            status: e.status,
+                                            message: e.message,
+                                        });
+                                        return new Response(html, {
+                                            status: e.status,
+                                            headers: { "Content-Type": "text/html" },
+                                        });
+                                    }
+                                    return new Response(e.message, { status: e.status });
+                                }
+                                throw e;
+                            }
+
+                            if (isFailResult(result)) {
+                                return Response.json(
+                                    { fail: true, status: result.status, data: result.data },
+                                    { status: result.status },
+                                );
+                            }
+
+                            const redirectTo =
+                                result?.redirect ?? evt.request.headers.get("referer") ?? "/";
+                            return new Response(null, {
+                                status: 303,
+                                headers: { Location: redirectTo },
+                            });
+                        }
+                        if (evt.request.method !== "GET") {
+                            return new Response("Method Not Allowed", { status: 405 });
+                        }
+                    }
+
+                    // page routes
+                    const response = await renderRoute(
+                        matched,
+                        evt.request,
+                        tree.errors,
+                        loader,
+                        evt.locals,
+                        plugins,
+                        cspNonce,
+                        dev,
+                        patchedFetch
+                    );
+
+                    if (evt.request.headers.get("x-grimoire-navigate") === "1") {
+                        return response;
+                    }
+
+                    const hasRenderPlugins = plugins.some((p) => p.onRouteRender);
+                    if (hasRenderPlugins) {
+                        let html = await response.text();
+                        for (const plugin of plugins) {
+                            html =
+                                (await plugin.onRouteRender?.(html, {
+                                    route: matched.route,
+                                    request: evt.request,
+                                    params: matched.params,
+                                    data: undefined,
+                                })) ?? html;
+                        }
+                        return new Response(html, {
+                            headers: { "Content-Type": "text/html" },
+                        });
+                    }
+
+                    return response;
+                };
+
+                let response: Response;
+                try {
+                    if (!hooksHandle) {
+                        response = await resolve(event);
+                    } else {
+                        response = await hooksHandle({ event, resolve });
+                    }
+                } catch (err) {
+                    logger.error(
+                        `${event.request.method} ${event.url.pathname} failed:`,
+                        err,
+                    );
+                    await hooksHandleError?.({
+                        error: err,
+                        event,
+                        status: 500,
+                        message: "Internal Server Error",
+                    });
+                    const errorHtmlPath = `${process.cwd()}/error.html`;
+                    try {
+                        const errorFile = Bun.file(errorHtmlPath);
+                        if (await errorFile.exists()) {
+                            return new Response(errorFile, {
+                                status: 500,
+                                headers: { "Content-Type": "text/html" },
+                            });
+                        }
+                    } catch { }
+                    const message =
+                        process.env.NODE_ENV === "production"
+                            ? "Internal Server Error"
+                            : `${err instanceof Error ? `${err.message}\n${err.stack}` : String(err)}`;
+                    return new Response(message, { status: 500 });
+                }
+
+                const setCookieHeaders = cookies.toHeaders();
+                if (
+                    setCookieHeaders.length > 0 ||
+                    Object.keys(setHeadersMap).length > 0
+                ) {
+                    const headers = new Headers(response.headers);
+                    for (const [k, v] of Object.entries(setHeadersMap)) {
+                        headers.set(k, v);
+                    }
+                    for (const sc of setCookieHeaders) {
+                        headers.append("Set-Cookie", sc);
+                    }
+                    response = new Response(response.body, {
+                        status: response.status,
+                        statusText: response.statusText,
+                        headers,
+                    });
+                }
+
+                return response;
+            });
+        },
+        websocket: {
+            open(ws: ServerWebSocket<any>) {
+                if (ws.data.__hmrClient) {
+                    hmr?.addClient(ws);
+                    return;
+                }
+                (ws.data as _WsInternalData).__handler?.open?.(ws);
+            },
+            message(ws: ServerWebSocket<any>, data: string | Buffer) {
+                if (ws.data.__hmrClient) return;
+                (ws.data as _WsInternalData).__handler?.message?.(ws, data);
+            },
+            close(ws: ServerWebSocket<any>, code: number, reason?: string) {
+                if (ws.data.__hmrClient) {
+                    hmr?.removeClient(ws);
+                    return;
+                }
+                (ws.data as _WsInternalData).__handler?.close?.(ws, code, reason);
+            },
+            drain(ws: ServerWebSocket<any>) {
+                if (ws.data.__hmrClient) return;
+                (ws.data as _WsInternalData).__handler?.drain?.(ws);
+            },
+        },
+    });
+
+    let stopping = false;
+    const handleShutdown = async () => {
+        if (stopping) return;
+        stopping = true;
+        await runHook(plugins, "onStop", "shutdown");
+        server.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", handleShutdown);
+    process.on("SIGTERM", handleShutdown);
+
+    await runHook(plugins, "onStart", {
+        port: server.port,
+        hostname: server.hostname,
+        stop: () => server.stop(),
+    });
+    return server;
 }