@c9up/aurora 0.1.39 → 0.1.40

package/dist/Pages.d.ts

@@ -76,3 +76,29 @@ export declare class Pages {
      */
     urlFor(name: string): string;
 }
+/**
+ * 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 declare function pageImportError(name: string, absolute: string, cause: unknown, isDev: boolean): Error;

package/dist/Pages.js

@@ -13,8 +13,11 @@
  * Sub-paths are allowed; the last `/`-separated segment is the file
  * 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";
 /**
  * `Pages` is a tiny resolver — no caching, no glob, no magic. The
  * server imports the module dynamically on every render so editors +
@@ -64,39 +67,45 @@ export class Pages {
         assertSafeName(name);
         const absolute = resolvePath(this.root, `${name}${this.extension}`);
         if (!absolute.startsWith(this.root + sep) && absolute !== this.root) {
-            throw new Error(`[aurora] page path "${name}" resolves outside the pages root`);
+            throw new AuroraError("E_AURORA_PAGE_OUTSIDE_ROOT", `[aurora] page path "${name}" resolves outside the pages root`);
         }
         // `pathToFileURL` so Windows + ESM stay happy. Node's ESM
         // loader caches modules by URL, so a stable URL would freeze
         // 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;
         try {
             mod = (await import(urlHref));
         }
         catch (err) {
-            throw new Error(`[aurora] page "${name}" not found at ${absolute} — ${err.message}`);
+            throw pageImportError(name, absolute, err, isDev);
         }
         if (typeof mod.default !== "function") {
-            throw new Error(`[aurora] page "${name}" must default-export a factory function`);
+            throw new AuroraError("E_AURORA_PAGE_INVALID_EXPORT", `[aurora] page "${name}" must default-export a factory function`);
         }
         return mod.default;
     }
@@ -109,12 +118,56 @@ export class Pages {
         return `${this.urlPrefix}/${name}${this.extension}`;
     }
 }
+/**
+ * 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, absolute, cause, isDev) {
+    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) {
     if (name.length === 0 ||
         name.startsWith("/") ||
         name.startsWith("\\") ||
         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/dist/browser.js

@@ -11,6 +11,7 @@
  * without `typeof window` guards at every call site. Node-free — part of the
  * client barrel.
  */
+import { AuroraError } from "./errors.js";
 import { effect, onCleanup, signal } from "./reactive.js";
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export function redirect(url) {
@@ -321,7 +322,7 @@ function safeNavigationUrl(url) {
     if (normalized.startsWith("javascript:") ||
         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/dist/component.js

@@ -18,12 +18,13 @@
  * signals the setup function captures. The compiled template is what
  * actually moves on screen.
  */
+import { AuroraError } from "./errors.js";
 import { setOwner } from "./reactive.js";
 const contextStack = [];
 function activeContext() {
     const ctx = contextStack[contextStack.length - 1];
     if (!ctx) {
-        throw new Error("[aurora] onMount / onUnmount called outside component() — only valid inside a component setup function.");
+        throw new AuroraError("E_AURORA_OUTSIDE_COMPONENT", "[aurora] onMount / onUnmount called outside component() — only valid inside a component setup function.");
     }
     return ctx;
 }

package/dist/devPageHooks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+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>;
+export declare function initialize(data: {
+    root?: unknown;
+} | undefined): void;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<ResolveResult>;
+export {};

package/dist/devPageHooks.js

@@ -0,0 +1,62 @@
+/**
+ * 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";
+/** The pages directory, handed over at registration. */
+let root = null;
+export function initialize(data) {
+    root =
+        typeof data?.root === "string" && data.root.length > 0 ? data.root : null;
+}
+export async function resolve(specifier, context, nextResolve) {
+    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;
+    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/dist/devPageReload.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function newestMtime(root: string): number | null;
+/**
+ * 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 declare function registerDevPageHooks(root: string): Promise<void>;

package/dist/devPageReload.js

@@ -0,0 +1,136 @@
+/**
+ * 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 { 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) {
+    let newest = null;
+    const walk = (directory, depth) => {
+        // 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;
+        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) {
+    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/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare class AuroraError extends Error {
+    readonly code: AuroraErrorCode;
+    constructor(code: AuroraErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+/**
+ * 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 {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}

package/dist/html.js

@@ -20,6 +20,7 @@
  * No custom directives, no fragments-in-attribute-name, no comment-only
  * placeholders.
  */
+import { AuroraError } from "./errors.js";
 import { isTemplateResult, TEMPLATE_RESULT_BRAND, } from "./types.js";
 const TEMPLATE_CACHE = new WeakMap();
 /** Sentinel inserted at every `${...}` site. Read back during the walk. */
@@ -183,7 +184,7 @@ function collectSlots(root, classification) {
                 if (cls === undefined)
                     return;
                 if (cls.region !== "text") {
-                    throw new Error(`[aurora] internal classification mismatch at slot ${slotIndex}`);
+                    throw new AuroraError("E_AURORA_INTERNAL", `[aurora] internal classification mismatch at slot ${slotIndex}`);
                 }
                 const slot = { kind: "text", path: [...path] };
                 slots.push(slot);

package/dist/index.d.ts

@@ -4,6 +4,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, FormField, FormOptions, FormSchema, FormValidate, } from "./form.js";
 export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";

package/dist/index.js

@@ -17,6 +17,7 @@ export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forw
 export { clsx, cn, twMerge } from "./cn.js";
 export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
+export { AuroraError } from "./errors.js";
 export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";
 export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";

package/dist/liveRegistry.js

@@ -10,6 +10,7 @@
  * `get(id)?.dispatch(...)`; disconnect → `disposeOwner(uid)`. Transport-agnostic
  * and node-free (only `mountLiveSession` + `crypto.randomUUID`, both isomorphic).
  */
+import { AuroraError } from "./errors.js";
 import { mountLiveSession, } from "./liveSession.js";
 /** Create an isolated live-session registry (one per app / per relay instance). */
 export function createLiveRegistry() {
@@ -39,7 +40,7 @@ export function createLiveRegistry() {
         mount(name, ownerId) {
             const factory = defs.get(name);
             if (!factory) {
-                throw new Error(`[aurora:live] unknown live component "${name}" — register it with registry.define("${name}", …) before mounting.`);
+                throw new AuroraError("E_AURORA_UNKNOWN_LIVE_COMPONENT", `[aurora:live] unknown live component "${name}" — register it with registry.define("${name}", …) before mounting.`);
             }
             const id = crypto.randomUUID();
             const handle = {