@sigil-dev/grimoire 0.3.0 → 0.5.0

package/src/renderer.ts

@@ -2,17 +2,34 @@ import { SafeHtml } from "@sigil-dev/runtime";
 import { isErrorResult } from "./error";
 import { runWithContext } from "./context";
 import { collectHead, initHead } from "./head";
+import { runHook } from "./plugins";
 import { isRedirectResult } from "./redirect";
-import type { MatchedRoute } from "./router";
-import type { LoadContext } from "./types";
+import { findClosestError, type MatchedRoute } from "./router";
+import type { RouteFile } from "./scanner";
+import type { GrimoirePlugin, LoadContext, Route } from "./types";
 
 export type ModuleLoader = (path: string) => Promise<any>;
 
+async function renderErrorPage(
+	errorRoutes: RouteFile[],
+	pathname: string,
+	status: number,
+	message: string,
+): Promise<Response | null> {
+	const errorPage = findClosestError(errorRoutes, pathname);
+	if (!errorPage) return null;
+	const mod = await import(errorPage.filePath);
+	const html = mod.default({ status, message });
+	return new Response(html, { status, headers: { "Content-Type": "text/html" } });
+}
+
 export async function renderRoute(
 	matched: MatchedRoute,
 	req: Request,
+	errorRoutes: RouteFile[] = [],
 	loadModule: ModuleLoader = (path) => import(path),
 	locals: Record<string, any> = {},
+	plugins: GrimoirePlugin[] = [],
 ): Promise<Response> {
 	return runWithContext(async () => {
 		const context: LoadContext = {
@@ -24,6 +41,15 @@ export async function renderRoute(
 
 		initHead();
 
+		const route: Route = {
+			path: matched.route.path,
+			params: matched.params,
+			filePath: matched.route.filePath,
+			loadPath: matched.pageServer?.filePath,
+			layoutPath: matched.layout?.filePath,
+		};
+		await runHook(plugins, "onRouteLoad", route, context);
+
 		let layoutData: unknown;
 		if (matched.layoutServer) {
 			try {
@@ -37,7 +63,10 @@ export async function renderRoute(
 					});
 				}
 				if (isErrorResult(e)) {
-					return new Response(e.message, { status: e.status });
+					return (
+						(await renderErrorPage(errorRoutes, context.url.pathname, e.status, e.message)) ??
+						new Response(e.message, { status: e.status })
+					);
 				}
 				throw e;
 			}
@@ -56,7 +85,10 @@ export async function renderRoute(
 					});
 				}
 				if (isErrorResult(e)) {
-					return new Response(e.message, { status: e.status });
+					return (
+						(await renderErrorPage(errorRoutes, context.url.pathname, e.status, e.message)) ??
+						new Response(e.message, { status: e.status })
+					);
 				}
 				throw e;
 			}
@@ -64,7 +96,7 @@ export async function renderRoute(
 
 		const pageMod = await import(matched.route.filePath);
 		const pageHtml = pageMod.default({
-			...(pageData as Record<string, unknown>),
+			data: pageData,
 			params: matched.params,
 		});
 
@@ -87,7 +119,7 @@ export async function renderRoute(
 		if (matched.layout) {
 			const layoutMod = await import(matched.layout.filePath);
 			bodyHtml = String(layoutMod.default({
-				...(layoutData as Record<string, unknown>),
+				data: layoutData,
 				children: new SafeHtml(wrappedPage),
 			}));
 		}

package/src/router.ts

@@ -52,7 +52,7 @@ export function matchRoute(tree: RouteTree, url: URL): MatchedRoute | null {
 }
 
 export function findClosestError(
-	tree: RouteTree,
+	errors: RouteFile[],
 	pathname: string,
 ): RouteFile | null {
 	const segments = pathname.split("/").filter(Boolean);
@@ -60,7 +60,7 @@ export function findClosestError(
 	// walk from most specific to root
 	while (segments.length >= 0) {
 		const prefix = `/${segments.join("/")}`;
-		const error = tree.errors.find(
+		const error = errors.find(
 			(e) => e.path === prefix || e.path === prefix + "/",
 		);
 		if (error) return error;

package/src/scanner.ts

@@ -93,5 +93,25 @@ export async function scanRoutes(
 		return aScore - bScore;
 	});
 
+	assertNoDuplicatePaths(routes.filter(r => r.type === "page" || r.type === "simple"), "page");
+	assertNoDuplicatePaths(routes.filter(r => r.type === "pageServer"), "page server");
+	assertNoDuplicatePaths(layouts.filter(l => l.type === "layout"), "layout");
+	assertNoDuplicatePaths(layouts.filter(l => l.type === "layoutServer"), "layout server");
+	assertNoDuplicatePaths(servers, "API route");
+	assertNoDuplicatePaths(errors, "error page");
+
 	return { routes, layouts, servers, errors };
 }
+
+function assertNoDuplicatePaths(files: RouteFile[], label: string): void {
+	const seen = new Map<string, string>();
+	for (const file of files) {
+		const existing = seen.get(file.path);
+		if (existing) {
+			throw new Error(
+				`Duplicate ${label} at "${file.path}": "${existing}" and "${file.clientPath}"`,
+			);
+		}
+		seen.set(file.path, file.clientPath);
+	}
+}

package/src/server.ts

@@ -3,18 +3,12 @@ import { isErrorResult } from "./error";
 import type { Handle, InitFunction, RequestEvent, ResolveFunction } from "./hooks";
 import { isRedirectResult } from "./redirect";
 import { createCookies } from "./cookie-utils";
-import { sigil } from "@sigil-dev/compiler/bun";
-import { mkdir } from "fs/promises";
-import { isAbsolute, join } from "path";
-import { generateManifest } from "./manifest-gen";
+import { buildProject } from "./build";
 import { runHook, runRequestHooks } from "./plugins";
 import { renderRoute } from "./renderer";
 import { findClosestError, matchRoute } from "./router";
-import { scanRoutes } from "./scanner";
 import { registerSSRPlugin } from "./ssrPlugin";
-import { transformRoutes } from "./transform-routes";
-import { generateTypes } from "./typegen";
-import type { GrimoireConfig } from "./types";
+import type { GrimoireConfig, WsRouteHandler } from "./types";
 
 /**
  * Try to load hooks.server.ts from the project root.
@@ -22,7 +16,7 @@ import type { GrimoireConfig } from "./types";
 async function loadHooks(
 	projectRoot: string,
 ): Promise<{ handle?: Handle; init?: InitFunction }> {
-	const hooksPath = join(projectRoot, "hooks.server.ts");
+	const hooksPath = `${projectRoot}/hooks.server.ts`;
 	try {
 		const mod = await import(hooksPath);
 		return { handle: mod.handle, init: mod.init };
@@ -32,14 +26,19 @@ async function loadHooks(
 	}
 }
 
-export async function createServer(config: GrimoireConfig = {}) {
+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;
+}
 
-	registerSSRPlugin();
+export async function createServer(config: GrimoireConfig = {}) {
 	const {
 		port = 3000,
 		host = "localhost",
 		plugins = [],
-		routes = "src/routes",
 	} = config;
 
 	// run config hooks
@@ -48,71 +47,11 @@ export async function createServer(config: GrimoireConfig = {}) {
 		finalConfig = plugin.config?.(finalConfig) ?? finalConfig;
 	}
 
-	// scan routes once at startup
-	const routesDir = isAbsolute(routes)
-		? routes.replace(/\0/g, "")
-		: join(process.cwd(), routes).replace(/\0/g, "");
-	const tree = await scanRoutes(routesDir, process.cwd());
-
-	await mkdir(join(process.cwd(), ".grimoire"), { recursive: true });
-
-	await generateTypes(tree, {
-		projectRoot: process.cwd(),
-		routesDir,
-		outDir: join(process.cwd(), ".grimoire/types"),
-	});
+	registerSSRPlugin(plugins);
 
-	const compiledDir = join(process.cwd(), ".grimoire/compiled");
-	await mkdir(compiledDir, { recursive: true });
-
-	// Bun 1.3.13 bug: Bun.build's native parser runs before onLoad hooks fire,
-	// so .tsx files with TS syntax crash the bundler even with a sigil plugin.
-	// Fix: pre-transform route files to plain JS before Bun.build sees them,
-	// then generate per-mode manifests pointing at the compiled .js files.
-	const pageRoutes = tree.routes.filter(
-		(r) => r.type === "page" || r.type === "simple",
-	);
-	const [hydrateFiles, domFiles] = await Promise.all([
-		transformRoutes(pageRoutes, compiledDir, "hydrate"),
-		transformRoutes(pageRoutes, compiledDir, "dom"),
-	]);
-
-	const hydrateManifest = join(process.cwd(), ".grimoire/_routes.hydrate.js");
-	const domManifest = join(process.cwd(), ".grimoire/_routes.dom.js");
-	await Promise.all([
-		Bun.write(hydrateManifest, generateManifest(pageRoutes, hydrateFiles)),
-		Bun.write(domManifest, generateManifest(pageRoutes, domFiles)),
-	]);
-
-	const makeRoutesPlugin = (manifestPath: string) => ({
-		name: "grimoire-routes",
-		setup(build: any) {
-			build.onResolve({ filter: /^#grimoire-routes$/ }, () => ({
-				path: manifestPath,
-			}));
-		},
-	});
-
-	const [hydrateResult, domResult] = await Promise.all([
-		Bun.build({
-			entrypoints: [join(import.meta.dir, "./hydrate.ts")],
-			outdir: join(process.cwd(), "public/__grimoire__"),
-			plugins: [sigil({ mode: "hydrate" }), makeRoutesPlugin(hydrateManifest)],
-		}),
-		Bun.build({
-			entrypoints: [join(import.meta.dir, "./client.ts")],
-			outdir: join(process.cwd(), "public/__grimoire__"),
-			plugins: [sigil({ mode: "dom" }), makeRoutesPlugin(domManifest)],
-		}),
-	]);
-
-	if (!hydrateResult.success) {
-		for (const log of hydrateResult.logs) console.error(log);
-		throw new Error("Grimoire: hydrate bundle build failed");
-	}
-	if (!domResult.success) {
-		for (const log of domResult.logs) console.error(log);
-		throw new Error("Grimoire: dom bundle build failed");
+	const { result, tree } = await buildProject(finalConfig, plugins);
+	if (!result.success) {
+		throw new Error("Grimoire: build failed");
 	}
 
 	// Load hooks.server.ts
@@ -125,11 +64,16 @@ export async function createServer(config: GrimoireConfig = {}) {
 		port,
 		hostname: host,
 		fetch: async (req) => {
+			// Shared locals object for this request — same reference across all route handlers.
+			// hooks.server.ts handle() runs via resolve() for page routes only.
+			// For server/WebSocket routes, auth must use cookies/headers in upgrade().
+			const locals: App.Locals = {};
+
 			return runRequestHooks(plugins, req, async () => {
 				const url = new URL(req.url);
 
 				const publicFile = Bun.file(
-					join(process.cwd(), "public", url.pathname),
+					`${process.cwd()}/public${url.pathname}`,
 				);
 				if (await publicFile.exists()) {
 					return new Response(publicFile);
@@ -138,7 +82,7 @@ export async function createServer(config: GrimoireConfig = {}) {
 				const matched = matchRoute(tree, url);
 
 				if (!matched) {
-					const error = findClosestError(tree, url.pathname);
+					const error = findClosestError(tree.errors, url.pathname);
 					if (error) {
 						const mod = await import(error.filePath);
 						const html = mod.default({ status: 404, message: "Not Found" });
@@ -150,14 +94,45 @@ export async function createServer(config: GrimoireConfig = {}) {
 					return new Response("Not Found", { status: 404 });
 				}
 
-				// API routes — no hooks
+				// API routes (+server.ts)
 				if (matched.route.type === "server") {
 					const mod = await import(matched.route.filePath);
+
+					// WebSocket upgrade path
+					const isWsUpgrade = req.headers.get("upgrade")?.toLowerCase() === "websocket";
+					if (isWsUpgrade && mod.websocket) {
+						let extraData: Record<string, unknown> = {};
+						if (mod.upgrade) {
+							try {
+								const result = await mod.upgrade({
+									request: req,
+									params: matched.params,
+									url,
+									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,
+						};
+						if (server.upgrade(req, { data: wsData })) {
+							// Bun sends the 101 response — return undefined to signal no HTTP response
+							return undefined as unknown as Response;
+						}
+						return new Response("Upgrade Required", { status: 426 });
+					}
+
+					// HTTP method dispatch
 					const handler = mod[req.method];
 					if (!handler) {
 						return new Response("Method Not Allowed", { status: 405 });
 					}
-					return handler({ request: req, params: matched.params, url });
+					return handler({ request: req, params: matched.params, url, locals });
 				}
 
 				const HTTP_METHODS = [
@@ -179,7 +154,7 @@ export async function createServer(config: GrimoireConfig = {}) {
 					request: req,
 					url,
 					params: matched.params,
-					locals: {},
+					locals,
 					cookies,
 					setHeaders: (headers) => Object.assign(setHeadersMap, headers),
 				};
@@ -214,7 +189,7 @@ export async function createServer(config: GrimoireConfig = {}) {
 											{ status: e.status },
 										);
 									}
-									const errorPage = findClosestError(tree, evt.url.pathname);
+									const errorPage = findClosestError(tree.errors, evt.url.pathname);
 									if (errorPage) {
 										const errMod = await import(errorPage.filePath);
 										const html = errMod.default({ status: e.status, message: e.message });
@@ -248,7 +223,7 @@ export async function createServer(config: GrimoireConfig = {}) {
 					}
 
 					// page routes
-					const response = await renderRoute(matched, evt.request, undefined, evt.locals);
+					const response = await renderRoute(matched, evt.request, tree.errors, undefined, evt.locals, plugins);
 
 					if (evt.request.headers.get("x-grimoire-navigate") === "1") {
 						return response;
@@ -306,8 +281,33 @@ export async function createServer(config: GrimoireConfig = {}) {
 				return response;
 			});
 		},
+		websocket: {
+			open(ws: ServerWebSocket<_WsInternalData>) {
+				ws.data.__handler?.open?.(ws);
+			},
+			message(ws: ServerWebSocket<_WsInternalData>, data: string | Buffer) {
+				ws.data.__handler?.message?.(ws, data);
+			},
+			close(ws: ServerWebSocket<_WsInternalData>, code: number, reason?: string) {
+				ws.data.__handler?.close?.(ws, code, reason);
+			},
+			drain(ws: ServerWebSocket<_WsInternalData>) {
+				ws.data.__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,

package/src/ssrPlugin.ts

@@ -1,8 +1,9 @@
 // packages/grimoire/src/ssr-plugin.ts
 import { transformSync } from "@babel/core";
 import sigilPlugin from "@sigil-dev/compiler/babel";
+import type { GrimoirePlugin } from "./types";
 
-export function registerSSRPlugin() {
+export function registerSSRPlugin(plugins: GrimoirePlugin[] = []) {
 	Bun.plugin({
 		name: "sigil-ssr",
 		setup(build) {
@@ -16,8 +17,12 @@ export function registerSSRPlugin() {
 					plugins: [[sigilPlugin, { mode: "ssr" }]],
 					filename: path,
 				});
+				let contents = transpiler.transformSync(result?.code ?? "");
+				for (const plugin of plugins) {
+					if (plugin.transform) contents = (await plugin.transform(contents, path)) ?? contents;
+				}
 				return {
-					contents: transpiler.transformSync(result?.code ?? ""),
+					contents,
 					loader: "js" as const,
 				};
 			});

package/src/transform-routes.ts

@@ -2,6 +2,7 @@ import { transformSync } from "@babel/core";
 import sigilPlugin from "@sigil-dev/compiler/babel";
 import { basename, dirname, join, relative, resolve } from "path";
 import type { RouteFile } from "./scanner";
+import type { GrimoirePlugin } from "./types";
 
 const STYLE_RE = /<style[^>]*>([\s\S]*?)<\/style>/gi;
 
@@ -56,6 +57,7 @@ export async function transformRoutes(
 	routes: RouteFile[],
 	outDir: string,
 	mode: "hydrate" | "dom",
+	plugins: GrimoirePlugin[] = [],
 ): Promise<Map<string, string>> {
 	const map = new Map<string, string>();
 	const transpiler = new Bun.Transpiler({ loader: "tsx", target: "browser" });
@@ -76,7 +78,10 @@ export async function transformRoutes(
 				],
 				filename: route.filePath,
 			});
-			const out = transpiler.transformSync(res?.code ?? "");
+			let out = transpiler.transformSync(res?.code ?? "");
+			for (const plugin of plugins) {
+				if (plugin.transform) out = (await plugin.transform(out, route.filePath)) ?? out;
+			}
 			const rel = relative(process.cwd(), route.filePath)
 				.replace(/\.[cm]?[jt]sx?$/, "")
 				.replace(/[^a-zA-Z0-9._-]/g, "_");

package/src/typegen.ts

@@ -111,7 +111,7 @@ function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
 			`  : Record<string, never>;`,
 			"",
 		);
-		lines.push(`export type PageProps = PageData & { params: Params };`, "");
+		lines.push(`export type PageProps = { data: PageData; params: Params };`, "");
 		// PageServerLoad — annotate parameter, NOT return type, to preserve inference
 		lines.push(
 			`/** Annotate the load() parameter only — not the return type — or PageData loses its concrete keys. */`,
@@ -139,7 +139,7 @@ function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
 	} else {
 		lines.push(
 			`export type PageData = Record<string, never>;`,
-			`export type PageProps = { params: Params };`,
+			`export type PageProps = { data: PageData; params: Params };`,
 			`export type PageServerLoad = never;`,
 			`export type Actions = Record<string, never>;`,
 			"",
@@ -161,7 +161,7 @@ function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
 	}
 
 	lines.push(
-		`export type LayoutProps = LayoutData & { params: Params; children?: unknown };`,
+		`export type LayoutProps = { data: LayoutData; params: Params; children?: unknown };`,
 		`export type LayoutServerLoad = (ctx: {`,
 		`  params: Params;`,
 		`  request: Request;`,
@@ -186,6 +186,27 @@ function generateTypesForGroup(group: RouteGroup, outFileDir: string): string {
 			`    locals: App.Locals;`,
 			`  }) => Response | Promise<Response>;`,
 			`};`,
+			``,
+			`export type UpgradeContext = {`,
+			`  request: Request;`,
+			`  params: Params;`,
+			`  url: URL;`,
+			`  locals: App.Locals;`,
+			`};`,
+			``,
+			`type _UpgradeReturn = "upgrade" extends keyof _SRV`,
+			`  ? _SRV["upgrade"] extends (...args: any[]) => any`,
+			`    ? Awaited<ReturnType<_SRV["upgrade"]>>`,
+			`    : {}`,
+			`  : {};`,
+			`export type WsData = { params: Params } & Omit<_UpgradeReturn, "__handler">;`,
+			``,
+			`export type WebSocketHandler = {`,
+			`  open?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
+			`  message?(ws: ServerWebSocket<WsData>, data: string | Buffer): void | Promise<void>;`,
+			`  close?(ws: ServerWebSocket<WsData>, code: number, reason?: string): void | Promise<void>;`,
+			`  drain?(ws: ServerWebSocket<WsData>): void | Promise<void>;`,
+			`};`,
 			"",
 		);
 	}
@@ -210,6 +231,59 @@ function generateAmbient(): string {
 		"  interface Locals extends Record<string, unknown> {}",
 		"}",
 		"",
+		"// Available in all route files without import.",
+		"// Params default to Record<string,string>; for per-route typed params import from './$types'.",
+		"// Note: using these globals widens return types — PageData loses concrete keys.",
+		"// For precise data inference annotate load() with PageServerLoad from './$types'.",
+		"",
+		"type PageServerLoad<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
+		"",
+		"type LayoutServerLoad<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Record<string, unknown> | Promise<Record<string, unknown>>;",
+		"",
+		"type RequestHandler<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = (ctx: {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"}) => Response | Promise<Response>;",
+		"",
+		"type PageProps<",
+		"  D extends Record<string, unknown> = Record<string, unknown>,",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = { data: D; params: P };",
+		"",
+		"type LayoutProps<",
+		"  D extends Record<string, unknown> = Record<string, unknown>,",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = { data: D; params: P; children?: unknown };",
+		"",
+		"type ErrorProps = { status: number; message: string };",
+		"",
+		"type UpgradeContext<",
+		"  P extends Record<string, string> = Record<string, string>",
+		"> = {",
+		"  params: P;",
+		"  request: Request;",
+		"  url: URL;",
+		"  locals: App.Locals;",
+		"};",
+		"",
 	].join("\n");
 }
 

package/src/types.ts

@@ -48,7 +48,7 @@ export interface GrimoirePlugin {
 
 	// server lifecycle
 	onStart?(server: Server): void | Promise<void>;
-	onStop?(): void | Promise<void>;
+	onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
 
 	// request pipeline
 	onRequest?(
@@ -58,6 +58,13 @@ export interface GrimoirePlugin {
 
 	// route lifecycle
 	onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
+	/**
+	 * Called after the page HTML is fully rendered.
+	 * NOTE: When any plugin implements this hook, the streaming response is
+	 * buffered into a single string. Streaming is preserved for routes where
+	 * no plugin uses this hook. To avoid buffering, use onRequest to intercept
+	 * at the Response level.
+	 */
 	onRouteRender?(
 		html: string,
 		context: RenderContext,
@@ -69,6 +76,16 @@ export interface GrimoirePlugin {
 
 	// config
 	config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
+
+	/**
+	 * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
+	 * Suitable for string-level transforms (import rewriting, comment injection, etc.).
+	 * Return null/undefined to pass through unchanged.
+	 */
+	transform?(
+		code: string,
+		id: string,
+	): string | null | undefined | Promise<string | null | undefined>;
 }
 
 export interface GrimoireConfig {
@@ -83,3 +100,30 @@ export interface GrimoireConfig {
 export function defineConfig(config: GrimoireConfig): GrimoireConfig {
 	return config;
 }
+
+/** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
+export type PageServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (ctx: TypedLoadContext<P>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
+export type LayoutServerLoad<
+	P extends Record<string, string> = Record<string, string>,
+> = (ctx: TypedLoadContext<P>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
+export type RequestHandler<
+	P extends Record<string, string> = Record<string, string>,
+> = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
+
+/**
+ * Shape of the `websocket` export in a +server.ts file.
+ * T is the resolved ws.data shape (params + upgrade() return value).
+ * For per-route typing import WebSocketHandler from './$types'.
+ */
+export interface WsRouteHandler<T = Record<string, unknown>> {
+	open?(ws: ServerWebSocket<T>): void | Promise<void>;
+	message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
+	close?(ws: ServerWebSocket<T>, code: number, reason?: string): void | Promise<void>;
+	drain?(ws: ServerWebSocket<T>): void | Promise<void>;
+}

package/test/exports.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Verifies that every symbol mentioned in the README is actually exported
+ * from the correct import path. If any of these break, the README is lying.
+ */
+import { describe, expect, test } from "bun:test";
+
+describe("README public API exports", () => {
+	test("main package exports: error, fail, redirect, sequence, defineConfig, Head, createServer, TypedLoadContext", async () => {
+		const mod = await import("@sigil-dev/grimoire");
+		expect(typeof mod.error).toBe("function");
+		expect(typeof mod.fail).toBe("function");
+		expect(typeof mod.redirect).toBe("function");
+		expect(typeof mod.sequence).toBe("function");
+		expect(typeof mod.defineConfig).toBe("function");
+		expect(typeof mod.Head).toBe("function");
+		expect(typeof mod.createServer).toBe("function");
+		// isXxx helpers used internally
+		expect(typeof mod.isErrorResult).toBe("function");
+		expect(typeof mod.isFailResult).toBe("function");
+		expect(typeof mod.isRedirectResult).toBe("function");
+	});
+
+	test("@sigil-dev/grimoire/client exports enhance", async () => {
+		const mod = await import("@sigil-dev/grimoire/client");
+		expect(typeof mod.enhance).toBe("function");
+	});
+
+	test("@sigil-dev/grimoire/hooks exports sequence and createHooks", async () => {
+		const mod = await import("@sigil-dev/grimoire/hooks");
+		expect(typeof mod.sequence).toBe("function");
+		expect(typeof mod.createHooks).toBe("function");
+	});
+
+	test("@sigil-dev/grimoire/headers exports securityHeaders", async () => {
+		const mod = await import("@sigil-dev/grimoire/headers");
+		expect(typeof mod.securityHeaders).toBe("function");
+	});
+});