@sigil-dev/grimoire 0.3.0

package/src/head.ts

@@ -0,0 +1,27 @@
+import { createContext, getContext, setContext } from "@sigil-dev/runtime";
+
+const HeadKey = createContext<string[]>();
+
+export function initHead(): void {
+	setContext(HeadKey, []);
+}
+
+export function collectHead(): string {
+	return (getContext(HeadKey) ?? []).join("\n    ");
+}
+
+export function Head({
+	children,
+}: {
+	children: string | Node;
+}): string | Comment {
+	if (typeof document === "undefined") {
+		const buf = getContext(HeadKey);
+		if (buf) buf.push(children as string);
+		return "";
+	}
+	if (children instanceof Node) {
+		document.head.appendChild(children);
+	}
+	return document.createComment("head");
+}

package/src/headers.ts

@@ -0,0 +1,114 @@
+import type { GrimoirePlugin } from "./types";
+
+export interface SecurityHeadersConfig {
+	/** Content-Security-Policy. Set false to omit. */
+	contentSecurityPolicy?: string | false;
+	/** X-Content-Type-Options. Default: "nosniff" */
+	contentTypeOptions?: string | false;
+	/** X-Frame-Options. Default: "DENY" */
+	frameOptions?: string | false;
+	/** X-XSS-Protection. Default: "0" (modern browsers; "1; mode=block" for legacy) */
+	xssProtection?: string | false;
+	/** Referrer-Policy. Default: "strict-origin-when-cross-origin" */
+	referrerPolicy?: string | false;
+	/** Strict-Transport-Security. Set false to omit. */
+	strictTransportSecurity?: string | false;
+	/** Permissions-Policy. Default: "camera=(), microphone=(), geolocation=()" */
+	permissionsPolicy?: string | false;
+	/** Per-route overrides: path pattern → partial config */
+	routes?: Record<string, Partial<SecurityHeadersConfig>>;
+}
+
+const DEFAULTS: Required<Omit<SecurityHeadersConfig, "routes">> = {
+	contentSecurityPolicy:
+		"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;",
+	contentTypeOptions: "nosniff",
+	frameOptions: "DENY",
+	xssProtection: "0",
+	referrerPolicy: "strict-origin-when-cross-origin",
+	strictTransportSecurity: "max-age=31536000; includeSubDomains",
+	permissionsPolicy: "camera=(), microphone=(), geolocation=()",
+};
+
+function resolveHeaders(
+	config: SecurityHeadersConfig,
+	pathname: string,
+): Record<string, string> {
+	// Start with defaults, overlay user config
+	const merged = { ...DEFAULTS, ...config };
+	delete (merged as any).routes;
+
+	// Apply route overrides
+	if (config.routes) {
+		for (const pattern in config.routes) {
+			if (pathname.startsWith(pattern)) {
+				Object.assign(merged, config.routes[pattern]);
+			}
+		}
+	}
+
+	const headers: Record<string, string> = {};
+
+	if (merged.contentSecurityPolicy !== false)
+		headers["Content-Security-Policy"] = merged.contentSecurityPolicy;
+	if (merged.contentTypeOptions !== false)
+		headers["X-Content-Type-Options"] = merged.contentTypeOptions;
+	if (merged.frameOptions !== false)
+		headers["X-Frame-Options"] = merged.frameOptions;
+	if (merged.xssProtection !== false)
+		headers["X-XSS-Protection"] = merged.xssProtection;
+	if (merged.referrerPolicy !== false)
+		headers["Referrer-Policy"] = merged.referrerPolicy;
+	if (merged.strictTransportSecurity !== false)
+		headers["Strict-Transport-Security"] = merged.strictTransportSecurity;
+	if (merged.permissionsPolicy !== false)
+		headers["Permissions-Policy"] = merged.permissionsPolicy;
+
+	return headers;
+}
+
+/**
+ * Security headers plugin.
+ * Adds standard security headers to all responses.
+ *
+ * Usage:
+ *
+ *   import { securityHeaders } from "@sigil-dev/grimoire/headers";
+ *
+ *   createServer({
+ *     plugins: [
+ *       securityHeaders({
+ *         // override defaults
+ *         frameOptions: "SAMEORIGIN",
+ *         // per-route
+ *         routes: {
+ *           "/admin": { contentSecurityPolicy: "default-src 'self'" },
+ *         },
+ *       }),
+ *     ],
+ *   });
+ */
+export function securityHeaders(
+	config: SecurityHeadersConfig = {},
+): GrimoirePlugin {
+	return {
+		name: "grimoire-security-headers",
+		async onRequest(req, next) {
+			const res = await next();
+			const url = new URL(req.url);
+			const headers = resolveHeaders(config, url.pathname);
+
+			// Clone response with security headers
+			const newHeaders = new Headers(res.headers);
+			for (const [key, value] of Object.entries(headers)) {
+				newHeaders.set(key, value);
+			}
+
+			return new Response(res.body, {
+				status: res.status,
+				statusText: res.statusText,
+				headers: newHeaders,
+			});
+		},
+	};
+}

package/src/hooks.ts

@@ -0,0 +1,93 @@
+/**
+ * SvelteKit-style server hooks.
+ *
+ * Create a hooks.server.ts in your project root:
+ *
+ *   import type { Handle } from "@sigil-dev/grimoire/hooks";
+ *
+ *   export const handle: Handle = async ({ event, resolve }) => {
+ *     event.locals.user = await getUser(event.cookies.get("session"));
+ *     const response = await resolve(event);
+ *     response.headers.set("x-custom", "value");
+ *     return response;
+ *   };
+ *
+ *   // optional: runs once at server start
+ *   export const init = () => {
+ *     console.log("Server started");
+ *   };
+ *
+ * Chain multiple handlers with sequence():
+ *
+ *   import { sequence } from "@sigil-dev/grimoire/hooks";
+ *   import { logger } from "./hooks/logger";
+ *   import { auth } from "./hooks/auth";
+ *
+ *   export const handle = sequence(logger, auth);
+ */
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export interface RequestEvent {
+	request: Request;
+	url: URL;
+	params: Record<string, string>;
+	locals: Record<string, any>;
+	cookies: Cookies;
+	setHeaders: (headers: Record<string, string>) => void;
+}
+
+export interface Cookies {
+	get(name: string): string | undefined;
+	set(name: string, value: string, options?: CookieOptions): void;
+	delete(name: string): void;
+}
+
+export interface CookieOptions {
+	path?: string;
+	domain?: string;
+	maxAge?: number;
+	expires?: Date;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: "strict" | "lax" | "none";
+}
+
+export type ResolveFunction = (event: RequestEvent) => MaybePromise<Response>;
+
+export type Handle = (input: {
+	event: RequestEvent;
+	resolve: ResolveFunction;
+}) => MaybePromise<Response>;
+
+export type InitFunction = () => void | Promise<void>;
+
+/**
+ * Chain multiple Handle functions into one.
+ * First handler in the array runs first.
+ */
+export function sequence(...handlers: Handle[]): Handle {
+	return async ({ event, resolve }) => {
+		let i = 0;
+
+		const next: ResolveFunction = async (evt) => {
+			if (i < handlers.length) {
+				const handler = handlers[i++];
+				return handler({ event: evt, resolve: next });
+			}
+			return resolve(evt);
+		};
+
+		return next(event);
+	};
+}
+
+/**
+ * Create a hooks object with handle and optional init.
+ */
+export function createHooks(
+	handle: Handle,
+	init?: InitFunction,
+): { handle: Handle; init?: InitFunction } {
+	return { handle, init };
+}

package/src/hydrate.ts

@@ -0,0 +1,22 @@
+import { routes } from "#grimoire-routes";
+import { withEffectScope } from "./scope.ts";
+import { initRouter } from "./client-router.ts";
+
+const stateEl = document.getElementById("__grimoire_state__");
+let initialDispose: (() => void) | undefined;
+
+if (stateEl) {
+	const state = JSON.parse(stateEl.textContent!);
+	const Page = routes[state.pattern];
+	if (Page) {
+		const slot = document.getElementById("grimoire-page");
+		if (slot) {
+			(globalThis as any).__nodes = Array.from(slot.childNodes);
+			initialDispose = withEffectScope(() => {
+				Page({ ...state.data, params: state.params });
+			});
+		}
+	}
+}
+
+initRouter(routes, initialDispose);

package/src/manifest-gen.ts

@@ -0,0 +1,26 @@
+import type { RouteFile } from "./scanner";
+
+/**
+ * Generates a manifest module that re-exports page route components keyed
+ * by route path. Emits plain JS so the same output is valid as both `.ts`
+ * and `.js`.
+ *
+ * If `fileMap` is provided, original `filePath`s are remapped to compiled
+ * `.js` paths (used after pre-transforming routes to plain JS).
+ */
+export function generateManifest(
+	routes: RouteFile[],
+	fileMap?: Map<string, string>,
+): string {
+	const pages = routes.filter((r) => r.type === "page" || r.type === "simple");
+	const imports = pages
+		.map((r, i) => {
+			const path = fileMap?.get(r.filePath) ?? r.filePath;
+			return `import __Page${i} from ${JSON.stringify(path)};`;
+		})
+		.join("\n");
+	const map = pages
+		.map((r, i) => `  ${JSON.stringify(r.path)}: __Page${i},`)
+		.join("\n");
+	return `${imports}\nexport const routes = {\n${map}\n};\n`;
+}

package/src/plugins.ts

@@ -0,0 +1,25 @@
+import type { GrimoirePlugin } from "./types";
+
+export async function runHook(
+	plugins: GrimoirePlugin[],
+	hook: keyof GrimoirePlugin,
+	...args: any
+): Promise<void> {
+	for (const plugin of plugins) {
+		await (plugin[hook] as any)?.(...args);
+	}
+}
+
+export async function runRequestHooks(
+	plugins: GrimoirePlugin[],
+	req: Request,
+	final: () => Promise<Response>,
+): Promise<Response> {
+	const chain = plugins
+		.filter((p) => p.onRequest)
+		.reduceRight(
+			(next, plugin) => async () => plugin.onRequest!(req, next),
+			final,
+		);
+	return chain();
+}

package/src/redirect.ts

@@ -0,0 +1,35 @@
+/**
+ * Throw a redirect from a load function or form action.
+ * The server catches it and returns a 3xx Response.
+ *
+ * Usage in +page.server.ts:
+ *
+ *   import { redirect } from "@sigil-dev/grimoire";
+ *
+ *   export async function load({ locals }) {
+ *     if (!locals.user) throw redirect(302, "/login");
+ *     return { user: locals.user };
+ *   }
+ *
+ *   export async function POST({ request }) {
+ *     // ... process form
+ *     throw redirect(303, "/dashboard");
+ *   }
+ */
+export interface RedirectResult {
+	__redirect: true;
+	status: number;
+	location: string;
+}
+
+export function redirect(status: number, location: string): never {
+	throw { __redirect: true, status, location } as RedirectResult;
+}
+
+export function isRedirectResult(value: unknown): value is RedirectResult {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as any).__redirect === true
+	);
+}

package/src/renderer.ts

@@ -0,0 +1,142 @@
+import { SafeHtml } from "@sigil-dev/runtime";
+import { isErrorResult } from "./error";
+import { runWithContext } from "./context";
+import { collectHead, initHead } from "./head";
+import { isRedirectResult } from "./redirect";
+import type { MatchedRoute } from "./router";
+import type { LoadContext } from "./types";
+
+export type ModuleLoader = (path: string) => Promise<any>;
+
+export async function renderRoute(
+	matched: MatchedRoute,
+	req: Request,
+	loadModule: ModuleLoader = (path) => import(path),
+	locals: Record<string, any> = {},
+): Promise<Response> {
+	return runWithContext(async () => {
+		const context: LoadContext = {
+			request: req,
+			params: matched.params,
+			url: new URL(req.url),
+			locals,
+		};
+
+		initHead();
+
+		let layoutData: unknown;
+		if (matched.layoutServer) {
+			try {
+				const mod = await import(matched.layoutServer.filePath);
+				layoutData = await mod.load?.(context);
+			} catch (e) {
+				if (isRedirectResult(e)) {
+					return new Response(null, {
+						status: e.status,
+						headers: { Location: e.location },
+					});
+				}
+				if (isErrorResult(e)) {
+					return new Response(e.message, { status: e.status });
+				}
+				throw e;
+			}
+		}
+
+		let pageData: unknown;
+		if (matched.pageServer) {
+			try {
+				const mod = await import(matched.pageServer.filePath);
+				pageData = await mod.load?.(context);
+			} catch (e) {
+				if (isRedirectResult(e)) {
+					return new Response(null, {
+						status: e.status,
+						headers: { Location: e.location },
+					});
+				}
+				if (isErrorResult(e)) {
+					return new Response(e.message, { status: e.status });
+				}
+				throw e;
+			}
+		}
+
+		const pageMod = await import(matched.route.filePath);
+		const pageHtml = pageMod.default({
+			...(pageData as Record<string, unknown>),
+			params: matched.params,
+		});
+
+		// collect head AFTER page render so <Head> calls are captured
+		const headHtml = collectHead();
+
+		// navigation request: return JSON, client handles rendering
+		if (req.headers.get("x-grimoire-navigate") === "1") {
+			return Response.json({
+				data: pageData ?? {},
+				params: matched.params,
+				pattern: matched.route.path,
+				head: headHtml,
+			});
+		}
+
+		const wrappedPage = `<div id="grimoire-page">${String(pageHtml)}</div>`;
+
+		let bodyHtml: string = wrappedPage;
+		if (matched.layout) {
+			const layoutMod = await import(matched.layout.filePath);
+			bodyHtml = String(layoutMod.default({
+				...(layoutData as Record<string, unknown>),
+				children: new SafeHtml(wrappedPage),
+			}));
+		}
+
+		const stateJson = JSON.stringify({
+			params: matched.params,
+			data: pageData,
+			pattern: matched.route.path,
+		});
+
+		// --- Streaming SSR ---
+		// Send DOCTYPE + head skeleton immediately (browser starts resource fetch).
+		// Then stream body + full head content + state as they become available.
+		const stream = new ReadableStream({
+			start(controller) {
+				// 1. Document skeleton — browser starts parsing, fetches CSS/JS
+				controller.enqueue(
+					`<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <script type="module" src="/__grimoire__/hydrate.js"></script>`,
+				);
+
+				// 2. Head content (captured from <Head> component calls during render)
+				if (headHtml) {
+					controller.enqueue(`\n${headHtml}`);
+				}
+
+				controller.enqueue(`\n</head>
+<body>
+    <div id="app">`);
+
+				// 3. Page body
+				controller.enqueue(bodyHtml);
+
+				// 4. State script + closing tags
+				controller.enqueue(`</div>
+    <script id="__grimoire_state__" type="application/json">${stateJson}</script>
+</body>
+</html>`);
+
+				controller.close();
+			},
+		});
+
+		return new Response(stream, {
+			headers: { "Content-Type": "text/html" },
+		});
+	});
+}

package/src/router.ts

@@ -0,0 +1,94 @@
+// packages/grimoire/src/router.ts
+import type { RouteFile, RouteTree } from "./scanner";
+
+export interface MatchedRoute {
+	route: RouteFile;
+	params: Record<string, string>;
+	layout?: RouteFile;
+	layoutServer?: RouteFile;
+	pageServer?: RouteFile;
+}
+
+export function matchRoute(tree: RouteTree, url: URL): MatchedRoute | null {
+	const pathname = url.pathname;
+
+	// check server routes first
+	for (const server of tree.servers) {
+		const params = matchPattern(server.path, pathname);
+		if (params !== null) return { route: server, params };
+	}
+
+	// then pages
+	for (const route of tree.routes) {
+		if (route.type === "pageServer") continue;
+		const params = matchPattern(route.path, pathname);
+		if (params === null) continue;
+
+		// find applicable layout (longest matching prefix wins)
+		const layout = tree.layouts
+			.filter(
+				(l) =>
+					l.type === "layout" &&
+					pathname.startsWith(l.path === "/" ? "/" : l.path),
+			)
+			.sort((a, b) => b.path.length - a.path.length)[0];
+
+		const layoutServer = tree.layouts
+			.filter(
+				(l) =>
+					l.type === "layoutServer" &&
+					pathname.startsWith(l.path === "/" ? "/" : l.path),
+			)
+			.sort((a, b) => b.path.length - a.path.length)[0];
+
+		const pageServer = tree.routes.find(
+			(r) => r.type === "pageServer" && r.path === route.path,
+		);
+
+		return { route, params, layout, layoutServer, pageServer };
+	}
+
+	return null;
+}
+
+export function findClosestError(
+	tree: RouteTree,
+	pathname: string,
+): RouteFile | null {
+	const segments = pathname.split("/").filter(Boolean);
+
+	// walk from most specific to root
+	while (segments.length >= 0) {
+		const prefix = `/${segments.join("/")}`;
+		const error = tree.errors.find(
+			(e) => e.path === prefix || e.path === prefix + "/",
+		);
+		if (error) return error;
+		if (segments.length === 0) break;
+		segments.pop();
+	}
+	return null;
+}
+
+function matchPattern(
+	pattern: string,
+	pathname: string,
+): Record<string, string> | null {
+	const patternParts = pattern.split("/").filter(Boolean);
+	const pathParts = pathname.split("/").filter(Boolean);
+
+	if (patternParts.length !== pathParts.length) return null;
+
+	const params: Record<string, string> = {};
+	for (let i = 0; i < patternParts.length; i++) {
+		const patternPart = patternParts[i]!;
+		const pathPart = pathParts[i]!;
+
+		if (patternPart.startsWith(":")) {
+			params[patternPart.slice(1)] = pathPart;
+		} else if (patternPart !== pathPart) {
+			return null;
+		}
+	}
+	return params;
+}

package/src/scanner.ts

@@ -0,0 +1,97 @@
+import { basename, join, relative } from "node:path";
+
+export interface RouteFile {
+	path: string; // URL (ie /blog/:slug)
+	filePath: string; // absolute disk path;
+	clientPath: string; // Relative path (/src/routes/spells/+page.tsx)
+	type:
+		| "page"
+		| "pageServer"
+		| "layout"
+		| "layoutServer"
+		| "server"
+		| "error"
+		| "simple";
+	paramNames: string[]; // ["slug"] in /blog/:slug
+}
+
+export interface RouteTree {
+	routes: RouteFile[];
+	layouts: RouteFile[]; // layout + layout.server
+	servers: RouteFile[]; // +server.ts API routes
+	errors: RouteFile[]; // +error.tsx
+}
+
+export function filePathToRoutePath(
+	filePath: string,
+	routesDir: string,
+): { pattern: string; params: string[] } {
+	const rel = relative(routesDir, filePath)
+		.replace(/\\/g, "/") // windows
+		.replace(/\.(tsx?|jsx?)$/, "");
+
+	const params: string[] = [];
+	const pattern =
+		rel
+			.replace(/\/?(\+\w+(\.\w+)?|index)$/, "") // index/+page → directory
+			.replace(/\[([^\]]+)\]/g, (_, p) => {
+				// [param] → :param
+				params.push(p);
+				return `:${p}`;
+			})
+			.replace(/^\/?/, "/") || // ensure leading slash
+		"/";
+
+	return { pattern, params };
+}
+
+export async function scanRoutes(
+	routesDir: string,
+	viteRoot: string = routesDir,
+): Promise<RouteTree> {
+	const glob = new Bun.Glob("**/*.{tsx,ts,jsx,js}");
+	const routes: RouteFile[] = [];
+	const layouts: RouteFile[] = [];
+	const servers: RouteFile[] = [];
+	const errors: RouteFile[] = [];
+
+	for await (const file of glob.scan(routesDir)) {
+		const filePath = join(routesDir, file);
+		const name = basename(file).replace(/\.(tsx?|jsx?)$/, "");
+		const { pattern, params } = filePathToRoutePath(filePath, routesDir);
+
+		let type: RouteFile["type"];
+		if (name === "+page") type = "page";
+		else if (name === "+page.server") type = "pageServer";
+		else if (name === "+layout") type = "layout";
+		else if (name === "+layout.server") type = "layoutServer";
+		else if (name === "+server") type = "server";
+		else if (name === "+error") type = "error";
+		else type = "simple";
+
+		const clientPath = "/" + relative(viteRoot, filePath).replace(/\\/g, "/");
+
+		const routeFile: RouteFile = {
+			path: pattern,
+			filePath,
+			clientPath, // add this
+			type,
+			paramNames: params,
+		};
+
+		if (type === "simple" || type === "page" || type === "pageServer")
+			routes.push(routeFile);
+		if (type === "layout" || type === "layoutServer") layouts.push(routeFile);
+		if (type === "server") servers.push(routeFile);
+		if (type === "error") errors.push(routeFile);
+	}
+
+	// sort so static routes match before dynamic ones
+	routes.sort((a, b) => {
+		const aScore = a.paramNames.length;
+		const bScore = b.paramNames.length;
+		return aScore - bScore;
+	});
+
+	return { routes, layouts, servers, errors };
+}

package/src/scope.ts

@@ -0,0 +1,22 @@
+/**
+ * Open an effect scope: run fn() and return a dispose function that tears down
+ * every createEffect registered during that call.
+ *
+ * Communicates with @sigil-dev/runtime's createEffect via globalThis.__sigilEffectScope
+ * so this file does not need to import from @sigil-dev/runtime (which would pull the
+ * runtime source into Bun.build and break the test sandbox).
+ */
+export function withEffectScope(fn: () => void): () => void {
+	const prev = (globalThis as any).__sigilEffectScope;
+	const disposers: (() => void)[] = [];
+	(globalThis as any).__sigilEffectScope = disposers;
+	try {
+		fn();
+	} finally {
+		(globalThis as any).__sigilEffectScope = prev;
+	}
+	return () => {
+		for (const d of disposers) d();
+		disposers.length = 0;
+	};
+}