@c9up/aurora 0.1.39 → 0.1.40

package/dist/relay.js

@@ -17,6 +17,7 @@
  * `@c9up/aurora`. Node-side code that pulls it will trip on
  * `EventSource` being undefined.
  */
+import { AuroraError } from "./errors.js";
 import { xsrfHeaderFor } from "./xsrf.js";
 const STATE = {
     sse: null,
@@ -250,7 +251,7 @@ async function postHandshake(url, channel) {
         credentials: "include",
     });
     if (!res.ok) {
-        throw new Error(`HTTP ${res.status}`);
+        throw new AuroraError("E_AURORA_RELAY_REQUEST_FAILED", `[aurora:relay] HTTP ${res.status}`);
     }
 }
 function safeJson(raw) {

package/dist/server/renderPage.js

@@ -24,6 +24,7 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { setCookieStoreReader } from "../browser.js";
+import { AuroraError } from "../errors.js";
 import { renderToString } from "../ssr.js";
 import { setRouteManifestReader } from "../url.js";
 const renderScope = new AsyncLocalStorage();
@@ -154,7 +155,7 @@ function isPlainRecord(value) {
 function normalizeRootTag(tag) {
     if (/^[a-z][a-z0-9-]*$/i.test(tag))
         return tag.toLowerCase();
-    throw new Error(`[aurora] illegal root tag: ${JSON.stringify(tag)}`);
+    throw new AuroraError("E_AURORA_ILLEGAL_ROOT_TAG", `[aurora] illegal root tag: ${JSON.stringify(tag)}`);
 }
 function rootAttrs(id, className) {
     const attrs = [`id="${escapeAttr(id)}"`];

package/dist/server.d.ts

@@ -1,6 +1,9 @@
 import "./augmentations.js";
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
+export { AuroraError, type AuroraErrorCode } from "./errors.js";
 export { type AuroraRequestRenderer, auroraContext, } from "./middleware.js";
-export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
+export { type PageFactory, Pages, type PagesConfig, 
+/** @internal classification seam, asserted by the tests */
+pageImportError, } from "./Pages.js";
 export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, type SharedProps, type SharedPropsResolver, } from "./server/renderPage.js";
 export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, packageAssetDir, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";

package/dist/server.js

@@ -11,7 +11,10 @@
 // source into every consumer's program — including ones that never use it.
 import "./augmentations.js";
 export { AuroraManager } from "./AuroraManager.js";
+export { AuroraError } from "./errors.js";
 export { auroraContext, } from "./middleware.js";
-export { Pages } from "./Pages.js";
+export { Pages, 
+/** @internal classification seam, asserted by the tests */
+pageImportError, } from "./Pages.js";
 export { renderPage, } from "./server/renderPage.js";
 export { packageAssetDir, serveAssets, } from "./server/serveAssets.js";

package/dist/services/main.js

@@ -9,6 +9,7 @@
  * `() => import('@c9up/aurora/provider')`) or by the app itself via
  * `setAurora(myManager)`.
  */
+import { AuroraError } from "../errors.js";
 let instance;
 /** @internal Bind the singleton (called by AuroraProvider or by the app). */
 export function setAurora(value) {
@@ -41,7 +42,7 @@ const aurora = new Proxy({}, {
             return undefined;
         }
         if (!instance) {
-            throw new Error("[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
+            throw new AuroraError("E_AURORA_NOT_BOOTED", "[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
                 "or `setAurora(myManager)` was called. Wire one of them first.");
         }
         const value = Reflect.get(instance, prop, instance);

package/dist/url.js

@@ -16,6 +16,7 @@
  * injects the same map into the page so the hydrate bootstrap re-sets it client
  * side. Node-free — part of aurora's client runtime.
  */
+import { AuroraError } from "./errors.js";
 let manifest = {};
 let routeManifestReader;
 /**
@@ -51,7 +52,7 @@ export function urlFor(name, params, query) {
     const pattern = routes[name];
     if (pattern === undefined) {
         const known = Object.keys(routes);
-        throw new Error(`[aurora] urlFor: unknown route '${name}'. ${known.length > 0
+        throw new AuroraError("E_AURORA_UNKNOWN_ROUTE", `[aurora] urlFor: unknown route '${name}'. ${known.length > 0
             ? `Known: ${known.join(", ")}`
             : "No routes registered — was the manifest passed to render() / setRouteManifest() called?"}`);
     }
@@ -67,7 +68,7 @@ export function urlFor(name, params, query) {
     url = url.replace(/\/:[A-Za-z_][\w]*\?/g, "");
     const missing = url.match(/:[A-Za-z_][\w]*/g);
     if (missing && missing.length > 0) {
-        throw new Error(`[aurora] urlFor: route '${name}' is missing params ${missing.join(", ")}`);
+        throw new AuroraError("E_AURORA_MISSING_ROUTE_PARAMS", `[aurora] urlFor: route '${name}' is missing params ${missing.join(", ")}`);
     }
     if (query) {
         const qs = Object.entries(query)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,9 @@
       "import": "./dist/rpc.js"
     }
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "peerDependencies": {
     "@c9up/comet": "^0.1.0",
     "@c9up/ream": "^0.2.0"
@@ -53,17 +56,17 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.5.12",
     "@c9up/comet": "^0.1.0",
-    "@types/node": "^22.19.15",
+    "@c9up/ream": "^0.2.0",
+    "@types/node": "^22.20.1",
     "@vitest/browser": "4.1.11",
     "@vitest/browser-playwright": "4.1.11",
-    "@vitest/coverage-v8": "4.1.9",
+    "@vitest/coverage-v8": "4.1.11",
     "jsdom": "^30.0.1",
-    "playwright": "^1.61.1",
-    "typescript": "^6.0.2",
-    "vitest": "4.1.9",
-    "@c9up/ream": "^0.2.0"
+    "playwright": "^1.63.0",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.11"
   },
   "files": [
     "LICENSE",

package/src/Pages.ts

@@ -14,8 +14,11 @@
  * stem (with or without the `.js` extension).
  */
 
+import { existsSync } from "node:fs";
 import { resolve as resolvePath, sep } from "node:path";
 import { pathToFileURL } from "node:url";
+import { newestMtime, registerDevPageHooks } from "./devPageReload.js";
+import { AuroraError } from "./errors.js";
 import type { TemplateResult } from "./types.js";
 
 /** A page module's default export. Receives props, returns a template. */
@@ -101,7 +104,8 @@ export class Pages {
 
 		const absolute = resolvePath(this.root, `${name}${this.extension}`);
 		if (!absolute.startsWith(this.root + sep) && absolute !== this.root) {
-			throw new Error(
+			throw new AuroraError(
+				"E_AURORA_PAGE_OUTSIDE_ROOT",
 				`[aurora] page path "${name}" resolves outside the pages root`,
 			);
 		}
@@ -111,34 +115,37 @@ export class Pages {
 		// the first-imported version of the page for the whole process
 		// lifetime — pages edited on disk would NOT be picked up even
 		// when the app runs under a file watcher. In dev mode we bust
-		// the URL with the file's mtime so a real change yields a new
-		// cache key and triggers a re-import. In production we keep
-		// the stable URL — page sources don't change post-deploy and
-		// busting per-request would leak memory (each unique URL stays
-		// resident in the ESM loader for the process lifetime).
+		// the URL so a real change yields a new cache key and triggers
+		// a re-import. In production we keep the stable URL — page
+		// sources don't change post-deploy and busting per-request
+		// would leak memory (each unique URL stays resident in the ESM
+		// loader for the process lifetime).
+		//
+		// **The token is the newest mtime in the TREE, not this file's.**
+		// A page's layout, its organisms and the services it imports are
+		// separate modules; keyed on the page's own mtime, editing any of
+		// them leaves this URL unchanged, so Node serves the cached page
+		// and never re-resolves what it imports. That made "edit a page"
+		// reload and "edit a template" not, which reads from the outside
+		// as the server caching files. See `devPageReload.ts`, and
+		// `devPageHooks.ts` for the other half: the page re-imports, and
+		// its imports need their own fresh keys to follow.
 		const isDev = process.env.NODE_ENV !== "production";
 		let urlHref = pathToFileURL(absolute).href;
 		if (isDev) {
-			try {
-				const { statSync } = await import("node:fs");
-				urlHref = `${urlHref}?v=${statSync(absolute).mtimeMs}`;
-			} catch {
-				// stat failed → fall back to stable URL; the import below
-				// will surface the underlying ENOENT.
-			}
+			await registerDevPageHooks(this.root);
+			const stamp = newestMtime(this.root);
+			if (stamp !== null) urlHref = `${urlHref}?v=${stamp}`;
 		}
 		let mod: { default?: unknown };
 		try {
 			mod = (await import(urlHref)) as { default?: unknown };
 		} catch (err) {
-			throw new Error(
-				`[aurora] page "${name}" not found at ${absolute} — ${
-					(err as Error).message
-				}`,
-			);
+			throw pageImportError(name, absolute, err, isDev);
 		}
 		if (typeof mod.default !== "function") {
-			throw new Error(
+			throw new AuroraError(
+				"E_AURORA_PAGE_INVALID_EXPORT",
 				`[aurora] page "${name}" must default-export a factory function`,
 			);
 		}
@@ -155,6 +162,68 @@ export class Pages {
 	}
 }
 
+/**
+ * Tell "this page does not exist" apart from "this page exists and its module
+ * graph refused to load".
+ *
+ * `import()` fails for many reasons that say nothing about whether the page is
+ * there: a syntax error anywhere in the graph, a throw at module top level, an
+ * export missing from a transitively imported module. Reporting every one of
+ * them as "not found", against the page's own path, sends the reader to the one
+ * file that is certainly present, while the real cause arrives at the end of the
+ * sentence naming a module the message never said was involved.
+ *
+ * The question is answered from the filesystem, not from the error text. Node
+ * raises `ERR_MODULE_NOT_FOUND` for a missing specifier ANYWHERE in the graph
+ * and names the page in both cases — as the missing module when it IS the page,
+ * and as the IMPORTER when a transitive is missing:
+ *
+ *   Cannot find module '<missing>' imported from '<importer>'
+ *
+ * so a substring test mis-sorts the second. Parsing the message is worse than
+ * fragile anyway: under a loader that is not plain Node (Vite's module runner,
+ * say) the text is different entirely. Whether the page is on disk is the same
+ * question under every loader.
+ *
+ * @internal exported for the tests that assert the classification
+ */
+export function pageImportError(
+	name: string,
+	absolute: string,
+	cause: unknown,
+	isDev: boolean,
+): Error {
+	const error = cause instanceof Error ? cause : new Error(String(cause));
+
+	if (!existsSync(absolute)) {
+		return new AuroraError(
+			"E_AURORA_PAGE_NOT_FOUND",
+			`[aurora] page "${name}" not found at ${absolute}`,
+			{ cause: error },
+		);
+	}
+
+	// A missing export is raised at link time as a SyntaxError, and it names the
+	// specifier it could not satisfy. In dev that has a second cause worth
+	// naming: the page URL is busted by mtime, its imports are not, so a module
+	// edited on disk can stay frozen in the ESM cache for the life of the
+	// process while the page around it is re-read on every request. The export
+	// is then genuinely in the file and genuinely absent from the loaded module.
+	const stale =
+		isDev && error.message.includes("does not provide an export named")
+			? "\n  That export may well be on disk. Only the page URL is cache-busted here," +
+				"\n  so an edited module it imports can stay frozen in this process's ESM cache." +
+				"\n  Restart the server, or run it under a loader hook that invalidates a page's" +
+				"\n  dependents (hot-hook)."
+			: "";
+
+	return new AuroraError(
+		"E_AURORA_PAGE_IMPORT_FAILED",
+		`[aurora] page "${name}" loaded from ${absolute} but its module graph failed: ${error.message}${stale}`,
+		{ cause: error },
+	);
+}
+
 function assertSafeName(name: string): void {
 	if (
 		name.length === 0 ||
@@ -163,6 +232,9 @@ function assertSafeName(name: string): void {
 		name.includes("..") ||
 		name.includes("\0")
 	) {
-		throw new Error(`[aurora] illegal page name: ${JSON.stringify(name)}`);
+		throw new AuroraError(
+			"E_AURORA_ILLEGAL_PAGE_NAME",
+			`[aurora] illegal page name: ${JSON.stringify(name)}`,
+		);
 	}
 }

package/src/browser.ts

@@ -12,6 +12,7 @@
  * client barrel.
  */
 
+import { AuroraError } from "./errors.js";
 import { effect, onCleanup, type Signal, signal } from "./reactive.js";
 
 /** Navigate to `url` with a full page load. No-op during SSR. */
@@ -403,7 +404,10 @@ function safeNavigationUrl(url: string): string {
 		normalized.startsWith("vbscript:") ||
 		normalized.startsWith("data:")
 	) {
-		throw new Error(`[aurora] blocked unsafe navigation URL: ${url}`);
+		throw new AuroraError(
+			"E_AURORA_UNSAFE_URL",
+			`[aurora] blocked unsafe navigation URL: ${url}`,
+		);
 	}
 	return url;
 }

package/src/component.ts

@@ -19,6 +19,7 @@
  * actually moves on screen.
  */
 
+import { AuroraError } from "./errors.js";
 import { setOwner } from "./reactive.js";
 import type { Disposer } from "./render.js";
 import type { EffectCallback, TemplateResult } from "./types.js";
@@ -40,7 +41,8 @@ const contextStack: ComponentContext[] = [];
 function activeContext(): ComponentContext {
 	const ctx = contextStack[contextStack.length - 1];
 	if (!ctx) {
-		throw new Error(
+		throw new AuroraError(
+			"E_AURORA_OUTSIDE_COMPONENT",
 			"[aurora] onMount / onUnmount called outside component() — only valid inside a component setup function.",
 		);
 	}

package/src/devPageHooks.ts

@@ -0,0 +1,86 @@
+/**
+ * The module-resolution hooks that make a page's IMPORTS reloadable in dev.
+ *
+ * **The bug these exist for.** `Pages.resolve` busts the ESM cache for a page
+ * by appending its own mtime, and says why: Node keys modules by URL, so a
+ * stable URL freezes the first-imported version for the process lifetime. That
+ * is right, and it covers exactly one file. A page's imports — the layout, the
+ * organisms, the services it pulls in — resolve RELATIVE to that URL and come
+ * out without a query, so they land on stable URLs that are already cached.
+ * Editing a template therefore changed nothing until the process restarted,
+ * while editing the page itself worked; the difference is invisible from the
+ * outside and reads as "the server caches my files".
+ *
+ * So the query has to follow the imports, and the only place that can happen is
+ * a resolution hook: Node hands every specifier through here before it consults
+ * its cache.
+ *
+ * **An existing query is never replaced.** `Pages` stamps a page with the
+ * NEWEST mtime in the whole tree — that is what makes a page re-import when a
+ * file it imports changes — and stamping it again here with its own mtime would
+ * undo exactly that. A child with no query gets its own mtime instead, so a
+ * module nobody touched keeps its key and stays cached: one edit re-imports the
+ * page and the file that changed, not the subtree.
+ *
+ * Dev only, and registered once — see `registerDevPageHooks`. In production the
+ * registration never happens, so this file is never loaded.
+ */
+
+import { statSync } from "node:fs";
+import { sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface ResolveContext {
+	conditions: string[];
+	importAttributes: Record<string, string>;
+	parentURL?: string;
+}
+
+interface ResolveResult {
+	url: string;
+	format?: string | null;
+	shortCircuit?: boolean;
+	importAttributes?: Record<string, string>;
+}
+
+type NextResolve = (
+	specifier: string,
+	context: ResolveContext,
+) => ResolveResult | Promise<ResolveResult>;
+
+/** The pages directory, handed over at registration. */
+let root: string | null = null;
+
+export function initialize(data: { root?: unknown } | undefined): void {
+	root =
+		typeof data?.root === "string" && data.root.length > 0 ? data.root : null;
+}
+
+export async function resolve(
+	specifier: string,
+	context: ResolveContext,
+	nextResolve: NextResolve,
+): Promise<ResolveResult> {
+	const result = await nextResolve(specifier, context);
+	if (root === null || !result.url.startsWith("file:")) return result;
+
+	// Already versioned by `Pages`: leave it. See the note above — replacing it
+	// with this file's own mtime is precisely the bug, reintroduced one level up.
+	if (result.url.includes("?")) return result;
+
+	let path: string;
+	try {
+		path = fileURLToPath(result.url);
+	} catch {
+		return result;
+	}
+	if (!path.startsWith(root + sep)) return result;
+
+	try {
+		return { ...result, url: `${result.url}?v=${statSync(path).mtimeMs}` };
+	} catch {
+		// Gone between resolution and stat: hand back the plain URL and let the
+		// import raise the real error rather than inventing one here.
+		return result;
+	}
+}

package/src/devPageReload.ts

@@ -0,0 +1,142 @@
+/**
+ * What makes a page pick up a change in something it IMPORTS, in dev.
+ *
+ * Two halves, and neither works alone:
+ *
+ * 1. {@link newestMtime} — the page's cache-busting token becomes the newest
+ *    mtime anywhere under the pages root, not the page file's own. Without
+ *    this, editing a layout leaves the page's key unchanged, so Node never
+ *    re-imports it and never re-resolves anything it pulls in.
+ *
+ * 2. {@link registerDevPageHooks} — a resolution hook that stamps each import
+ *    under that root with its own mtime. Without this, the re-imported page
+ *    resolves its layout to a bare URL that is still in the cache.
+ *
+ * Both are dev-only. In production a page's sources do not change, and
+ * per-request busting would leak: every distinct URL stays resident in the ESM
+ * registry for the process lifetime.
+ *
+ * **Measured 2026-09-19, and re-measured before it was written down.** The
+ * whole approach rests on Node keying modules by full URL, query included, and
+ * on a registered `resolve` hook being consulted for every specifier. Both hold
+ * under plain Node AND under `tsx` — checked at tsx 4.7.0, 4.19.2 and 4.23.13,
+ * under `tsx` and `tsx watch`, with pages written as `.js` and as `.ts`, on
+ * Node 25. Importing `Page.js?v=1` then `Page.js?v=2` yields two instances in
+ * every one of those, and an edited template is visible in the second.
+ *
+ * That is worth stating because the opposite was believed first, and the belief
+ * would have closed the question: "the runner normalises the query away, so
+ * nothing here can work" reads as a fact about tsx and sends the next reader to
+ * configure a watcher instead. **A hook registration that fails silently is
+ * indistinguishable from a runner that ignores hooks** — which is what the
+ * `.js`/`.ts` bug below produced, and why it is the first thing to check if
+ * reloading ever appears not to work. Re-measuring costs two imports:
+ *
+ * ```js
+ * const a = await import("./mod.js?v=1")
+ * const b = await import("./mod.js?v=2")   // a !== b, under every runner tried
+ * ```
+ *
+ * A watcher is still worth having for the server's own sources. It is no longer
+ * needed for pages and templates, and watching them costs a full restart where
+ * this costs one re-import.
+ */
+
+import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The newest mtime under `root`, or `null` when it cannot be read.
+ *
+ * **Directories are skipped by name, not by a filter someone has to remember.**
+ * `node_modules` and dot-directories are the two that would turn a per-render
+ * walk of a page tree into a walk of a dependency tree; everything else under a
+ * pages root is a page, a template or something one of them imports.
+ *
+ * Synchronous on purpose. It runs once per page render in dev, on a directory
+ * of tens of files, and the alternative — awaiting a tree walk before every
+ * import — buys nothing a developer can perceive while making the caller async
+ * for a case production never takes.
+ */
+export function newestMtime(root: string): number | null {
+	let newest: number | null = null;
+
+	const walk = (directory: string, depth: number): void => {
+		// A pages root nested twenty deep is a mistake, not a feature; the cap
+		// is what keeps a symlink loop from becoming an infinite walk.
+		if (depth > 20) return;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(directory, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+			const full = join(directory, entry.name);
+			if (entry.isDirectory()) {
+				walk(full, depth + 1);
+				continue;
+			}
+			try {
+				const { mtimeMs } = statSync(full);
+				if (newest === null || mtimeMs > newest) newest = mtimeMs;
+			} catch {
+				// Deleted mid-walk: it cannot be the newest thing that still exists.
+			}
+		}
+	};
+
+	walk(root, 0);
+	return newest;
+}
+
+let registered = false;
+
+/**
+ * Register the resolution hooks, once per process.
+ *
+ * **Either extension, because this package is run both ways.** Installed, the
+ * hooks are `dist/devPageHooks.js`; from a checkout under a TypeScript runner
+ * they are `src/devPageHooks.ts`, and `module.register` resolves the URL it is
+ * given literally rather than through that runner's extension mapping. Asking
+ * for `.js` alone therefore worked for everybody consuming the package and for
+ * nobody working ON it — the failure mode being that page reloading silently
+ * stops improving.
+ *
+ * **A failure is reported, once, rather than swallowed.** The first version of
+ * this caught everything and said nothing, so the registration threw
+ * `ERR_MODULE_NOT_FOUND` and the only symptom was that templates went on not
+ * reloading — which is the bug this file exists to fix, reproduced one level
+ * up. Degrading is fine; degrading in silence is what costs an afternoon.
+ */
+export async function registerDevPageHooks(root: string): Promise<void> {
+	if (registered) return;
+	registered = true;
+	try {
+		// Imported here rather than at module scope so production never pays for
+		// it: `Pages` only calls this when it is not in production.
+		const { register } = await import("node:module");
+		if (typeof register !== "function") return;
+
+		const here = new URL(".", import.meta.url);
+		const hooks = ["devPageHooks.js", "devPageHooks.ts"]
+			.map((name) => new URL(name, here))
+			.find((candidate) => existsSync(fileURLToPath(candidate)));
+		if (hooks === undefined) {
+			console.warn(
+				"[aurora] page hooks not found beside devPageReload — a page will still reload when edited, but a template it imports will not",
+			);
+			return;
+		}
+
+		register(hooks, import.meta.url, { data: { root } });
+	} catch (error) {
+		console.warn(
+			`[aurora] could not register the page reload hooks: ${
+				error instanceof Error ? error.message : String(error)
+			}`,
+		);
+	}
+}

package/src/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Aurora's errors.
+ *
+ * Every failure aurora raises carries a stable `code`, so a caller can branch
+ * on what went wrong without matching on a message — a message is prose and is
+ * free to improve, a code is a contract. The cohort shape is
+ * `E_<PACKAGE>_<REASON>`.
+ *
+ * This module is imported by browser-side code as well as the server, so it
+ * stays free of Node built-ins.
+ */
+
+export type AuroraErrorCode =
+	/** A page name escapes the pages root — `..`, an absolute path, a NUL. */
+	| "E_AURORA_ILLEGAL_PAGE_NAME"
+	/** The resolved path lands outside the configured pages root. */
+	| "E_AURORA_PAGE_OUTSIDE_ROOT"
+	/** No file for this page name. */
+	| "E_AURORA_PAGE_NOT_FOUND"
+	/** The page is on disk and its module graph refused to load. */
+	| "E_AURORA_PAGE_IMPORT_FAILED"
+	/** The page module loaded but does not default-export a factory. */
+	| "E_AURORA_PAGE_INVALID_EXPORT"
+	/** `renderPage` was given a root tag that is not a plain element name. */
+	| "E_AURORA_ILLEGAL_ROOT_TAG"
+	/** `onMount` / `onUnmount` called outside a `component()` setup function. */
+	| "E_AURORA_OUTSIDE_COMPONENT"
+	/** The manager singleton was read before a provider or `setAurora` set it. */
+	| "E_AURORA_NOT_BOOTED"
+	/** `urlFor` was given a name absent from the route manifest. */
+	| "E_AURORA_UNKNOWN_ROUTE"
+	/** `urlFor` was given a route whose required params were not all supplied. */
+	| "E_AURORA_MISSING_ROUTE_PARAMS"
+	/** A live component was mounted before `registry.define()` named it. */
+	| "E_AURORA_UNKNOWN_LIVE_COMPONENT"
+	/** A relay request came back with a non-2xx status. */
+	| "E_AURORA_RELAY_REQUEST_FAILED"
+	/** A navigation URL failed the same-origin / scheme check. */
+	| "E_AURORA_UNSAFE_URL"
+	/** An invariant inside aurora broke — always a bug in aurora itself. */
+	| "E_AURORA_INTERNAL";
+
+/**
+ * Base class, so a caller can catch every aurora error by one name.
+ *
+ * `options` is the standard `ErrorOptions`, which is how `cause` reaches it:
+ * wrapping a lower-level failure must never drop the stack that points at the
+ * line responsible.
+ */
+export class AuroraError extends Error {
+	readonly code: AuroraErrorCode;
+
+	constructor(code: AuroraErrorCode, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = new.target.name;
+		this.code = code;
+	}
+}

package/src/html.ts

@@ -21,6 +21,8 @@
  * placeholders.
  */
 
+import { AuroraError } from "./errors.js";
+
 import {
 	type AttrSlot,
 	type BooleanAttrSlot,
@@ -223,7 +225,8 @@ function collectSlots(
 				const cls = classification[slotIndex];
 				if (cls === undefined) return;
 				if (cls.region !== "text") {
-					throw new Error(
+					throw new AuroraError(
+						"E_AURORA_INTERNAL",
 						`[aurora] internal classification mismatch at slot ${slotIndex}`,
 					);
 				}

package/src/index.ts

@@ -55,6 +55,7 @@ export { type ClassValue, clsx, cn, twMerge } from "./cn.js";
 export type { Command } from "./command.js";
 export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export { AuroraError, type AuroraErrorCode } from "./errors.js";
 export type {
 	FieldErrors,
 	Form,