@c9up/aurora 0.1.38 → 0.1.40

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/hydrate.js

@@ -91,7 +91,10 @@ function renderValueToNodes(value, cleanups, mountHooks, doc) {
         return out;
     }
     if (isTemplateResult(value)) {
-        const frag = mount(value, cleanups, [], mountHooks);
+        // The renderer collects hooks in a queue now; hydrate keeps its own
+        // flat list, so it hands one over and takes back what was collected.
+        const nested = { hooks: mountHooks, flushed: false };
+        const frag = mount(value, cleanups, [], nested);
         return Array.from(frag.childNodes);
     }
     if (value instanceof Node)

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 = {

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/render.d.ts

@@ -9,6 +9,21 @@
  */
 import { type EffectCallback, type TemplateResult } from "./types.js";
 export type Disposer = () => void;
+/**
+ * The `onMount` hooks collected while a tree is built, and whether they have
+ * already been run.
+ *
+ * A bare array was not enough. The root flushes it once, after the fragment is
+ * in the document; a reactive slot that swapped its content LATER kept
+ * appending to that same array, and nothing flushed it again — the component's
+ * setup ran, its `onMount` never did, and the hooks piled up for the life of
+ * the page. The flag is what lets a later update tell "collect these, the root
+ * will run them" from "the root is done, run mine myself".
+ */
+interface MountQueue {
+    hooks: Array<EffectCallback>;
+    flushed: boolean;
+}
 /**
  * Mount a TemplateResult into `container`. Returns a `Disposer` that
  * stops every reactive effect and removes the mounted nodes. Calling it
@@ -22,4 +37,5 @@ export declare function render(result: TemplateResult, container: Element | Docu
  * nested-template subtree when the signal changes after hydration
  * (the swap path — see `hydrateTextSlot`).
  */
-export declare function mount(result: TemplateResult, cleanups: Disposer[], mounted: ChildNode[], mountHooks: Array<EffectCallback>): DocumentFragment;
+export declare function mount(result: TemplateResult, cleanups: Disposer[], mounted: ChildNode[], queue: MountQueue): DocumentFragment;
+export {};

package/dist/render.js

@@ -16,6 +16,24 @@ import { readComponentLifecycle } from "./component.js";
 import { getTemplate } from "./html.js";
 import { effect, isSignal } from "./reactive.js";
 import { isTemplateResult, } from "./types.js";
+/**
+ * Run hooks, sending any teardown to `cleanups`.
+ *
+ * Failures are swallowed per hook: one component's bad `onMount` must not stop
+ * its siblings from mounting.
+ */
+function runMountHooks(hooks, cleanups) {
+    for (const hook of hooks) {
+        try {
+            const teardown = hook();
+            if (typeof teardown === "function")
+                cleanups.push(teardown);
+        }
+        catch {
+            /* swallow — one bad onMount should not block sibling components */
+        }
+    }
+}
 /**
  * Mount a TemplateResult into `container`. Returns a `Disposer` that
  * stops every reactive effect and removes the mounted nodes. Calling it
@@ -24,22 +42,17 @@ import { isTemplateResult, } from "./types.js";
 export function render(result, container) {
     const cleanups = [];
     const mountedNodes = [];
-    const mountHooks = [];
-    const fragment = mount(result, cleanups, mountedNodes, mountHooks);
+    const queue = { hooks: [], flushed: false };
+    const fragment = mount(result, cleanups, mountedNodes, queue);
     container.appendChild(fragment);
     // `onMount` hooks fire after the fragment is live in the document so
     // callbacks that measure / focus / observe see a real DOM. A returned
     // cleanup function joins the unmount queue.
-    for (const hook of mountHooks) {
-        try {
-            const teardown = hook();
-            if (typeof teardown === "function")
-                cleanups.push(teardown);
-        }
-        catch {
-            /* swallow — one bad onMount should not block sibling components */
-        }
-    }
+    runMountHooks(queue.hooks, cleanups);
+    queue.hooks = [];
+    // From here on the root never flushes again, so a slot that mounts
+    // something later has to run its own hooks.
+    queue.flushed = true;
     let disposed = false;
     return () => {
         if (disposed)
@@ -58,14 +71,14 @@ export function render(result, container) {
  * nested-template subtree when the signal changes after hydration
  * (the swap path — see `hydrateTextSlot`).
  */
-export function mount(result, cleanups, mounted, mountHooks) {
+export function mount(result, cleanups, mounted, queue) {
     const tpl = getTemplate(result.strings);
     const fragment = tpl.element.content.cloneNode(true);
     // Forward any component()-attached lifecycle from this result.
     const lifecycle = readComponentLifecycle(result);
     if (lifecycle) {
         for (const hook of lifecycle.mountHooks)
-            mountHooks.push(hook);
+            queue.hooks.push(hook);
         for (const c of lifecycle.cleanups)
             cleanups.push(c);
     }
@@ -106,7 +119,7 @@ export function mount(result, cleanups, mounted, mountHooks) {
             collectMultiAttr(slot, node, result.values[i], multiGroups);
         }
         else {
-            applySlot(slot, node, result.values[i], cleanups, mounted, mountHooks);
+            applySlot(slot, node, result.values[i], cleanups, mounted, queue);
         }
     }
     for (const group of multiGroups.values()) {
@@ -134,10 +147,10 @@ function resolvePath(root, path) {
     }
     return node;
 }
-function applySlot(slot, node, value, cleanups, mounted, mountHooks) {
+function applySlot(slot, node, value, cleanups, mounted, queue) {
     switch (slot.kind) {
         case "text":
-            applyTextSlot(slot, node, value, cleanups, mounted, mountHooks);
+            applyTextSlot(slot, node, value, cleanups, mounted, queue);
             return;
         case "attr":
             applyAttrSlot(slot, node, value, cleanups);
@@ -159,7 +172,7 @@ function applySlot(slot, node, value, cleanups, mounted, mountHooks) {
  * inserted before it, and each re-render swaps out only the nodes it
  * previously inserted.
  */
-function applyTextSlot(_slot, anchor, value, cleanups, mounted, mountHooks) {
+function applyTextSlot(_slot, anchor, value, cleanups, mounted, queue) {
     let currentNodes = [];
     // Per-render disposers for whatever the slot currently shows. A
     // reactive slot that swaps a nested TemplateResult for another must
@@ -179,7 +192,16 @@ function applyTextSlot(_slot, anchor, value, cleanups, mounted, mountHooks) {
         for (const n of currentNodes)
             n.remove();
         currentNodes = [];
-        const nodes = renderValueIntoNodes(newValue, localCleanups, mounted, mountHooks);
+        // This render's hooks are collected apart from the shared queue,
+        // whichever phase we are in, because their TEARDOWNS belong to this
+        // slot: the next swap must dispose what it replaces. Left on the root's
+        // list, a component mounted per row kept its subscription until the
+        // whole page unmounted.
+        //
+        // `flushed` is inherited so a deeper slot built during this render
+        // still knows whether the root has a flush coming.
+        const own = { hooks: [], flushed: queue.flushed };
+        const nodes = renderValueIntoNodes(newValue, localCleanups, mounted, own);
         const parent = anchor.parentNode;
         if (!parent)
             return;
@@ -187,6 +209,20 @@ function applyTextSlot(_slot, anchor, value, cleanups, mounted, mountHooks) {
             parent.insertBefore(n, anchor);
             currentNodes.push(n);
         }
+        if (queue.flushed) {
+            // After insertion, exactly as at the root: an `onMount` that
+            // measures, focuses or observes has to see a live node.
+            runMountHooks(own.hooks, localCleanups);
+            return;
+        }
+        // Still building the initial tree: the nodes are in a detached
+        // fragment, so defer to the root's flush. One wrapper carries them, and
+        // it returns nothing — the real teardowns go to `localCleanups`, not to
+        // the root.
+        const pending = own.hooks;
+        queue.hooks.push(() => {
+            runMountHooks(pending.splice(0), localCleanups);
+        });
     }
     if (isSignal(value) || typeof value === "function") {
         const dispose = effect(() => {
@@ -206,18 +242,18 @@ function applyTextSlot(_slot, anchor, value, cleanups, mounted, mountHooks) {
         cleanups.push(disposeLocal);
     }
 }
-function renderValueIntoNodes(value, cleanups, mounted, mountHooks) {
+function renderValueIntoNodes(value, cleanups, mounted, queue) {
     if (value === null || value === undefined || value === false)
         return [];
     if (Array.isArray(value)) {
         const out = [];
         for (const item of value) {
-            out.push(...renderValueIntoNodes(item, cleanups, mounted, mountHooks));
+            out.push(...renderValueIntoNodes(item, cleanups, mounted, queue));
         }
         return out;
     }
     if (isTemplateResult(value)) {
-        const frag = mount(value, cleanups, mounted, mountHooks);
+        const frag = mount(value, cleanups, mounted, queue);
         return Array.from(frag.childNodes);
     }
     if (value instanceof Node) {

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/serveAssets.d.ts

@@ -28,6 +28,12 @@ export interface AssetsRequest {
      * convention.
      */
     param(name: string): unknown;
+    /**
+     * Read a request header. OPTIONAL, so a host that only implements
+     * `param()` keeps working: without it there is no conditional request and
+     * every response is a full 200, which is what happened before.
+     */
+    header?(name: string): string | undefined;
 }
 export interface AssetsResponse {
     status(code: number): AssetsResponse;
@@ -48,6 +54,10 @@ export interface ServeAssetsOptions {
      * `Cache-Control` value to emit. Defaults to a dev-friendly
      * 60-second TTL. Production deployments should hash the asset
      * name and switch to `public, max-age=31536000, immutable`.
+     *
+     * Note that a TTL alone tells the browser not to ASK for 60 seconds. Pair
+     * it with `no-cache` while developing — the ETag below then makes the
+     * revalidation nearly free.
      */
     cacheControl?: string;
 }

package/dist/server/serveAssets.js

@@ -9,6 +9,7 @@
  * and writes to `ctx.response`. Any context that satisfies
  * `AssetsHttpContext` (Ream, AdonisJS, anything duck-typed) works.
  */
+import { createHash } from "node:crypto";
 import { readFile, realpath } from "node:fs/promises";
 import { dirname, extname, join, resolve as resolvePath, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -25,6 +26,27 @@ import { fileURLToPath } from "node:url";
 export function packageAssetDir(specifier) {
     return dirname(fileURLToPath(import.meta.resolve(specifier)));
 }
+/**
+ * Does `If-None-Match` cover this entity? (RFC 9110 §13.1.2)
+ *
+ * A strict `===` answered 200 for three shapes a real client sends: `*`, a
+ * comma-separated list of tags, and the weak form `W/"…"` — so a browser
+ * holding the exact bytes re-downloaded them anyway, which is most of what the
+ * validator exists to prevent. Written here rather than imported because aurora
+ * does not depend on ream; the same function lives in `ream/src/http/etag.ts`.
+ */
+function matchesIfNoneMatch(header, tag) {
+    if (header === undefined || header === "" || tag === "")
+        return false;
+    // `*` means "any current representation", so a stored copy always matches.
+    if (header.trim() === "*")
+        return true;
+    const bare = (value) => value.startsWith("W/") ? value.slice(2) : value;
+    const current = bare(tag);
+    return header
+        .split(",")
+        .some((candidate) => bare(candidate.trim()) === current);
+}
 const CONTENT_TYPES = {
     ".js": "text/javascript; charset=utf-8",
     ".mjs": "text/javascript; charset=utf-8",
@@ -98,9 +120,25 @@ export function serveAssets(options) {
             ctx.response.status(404).send("asset not found");
             return;
         }
+        // A validator, so a cached copy can be CHECKED rather than only trusted
+        // for a fixed time. Without one an edited module was served stale for
+        // the whole TTL with no way for the browser to ask whether it changed —
+        // in development that is a source file, and the answer is usually yes.
+        //
+        // Hashed from the bytes actually being sent rather than from mtime and
+        // size: a checkout, a rebuild or a touched file all move the metadata
+        // without changing the content, and each would needlessly re-download.
+        const etag = `"${createHash("sha1").update(body).digest("base64url")}"`;
         const type = CONTENT_TYPES[extname(canonicalAbsolute)] ?? "application/octet-stream";
         ctx.response.header("content-type", type);
         ctx.response.header("cache-control", cacheControl);
+        ctx.response.header("etag", etag);
+        if (matchesIfNoneMatch(ctx.request.header?.("if-none-match"), etag)) {
+            // 304 carries no body, and must not: the browser reuses the copy it
+            // already has.
+            ctx.response.status(304).send("");
+            return;
+        }
         ctx.response.send(body);
     };
 }

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.38",
+  "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/AuroraManager.ts

@@ -209,9 +209,20 @@ export class AuroraManager {
 	/**
 	 * Handler for the app's pages directory. Mount on
 	 * `GET /__assets/pages/*`.
+	 *
+	 * `no-cache` while developing — which does NOT mean "do not cache", it
+	 * means "always ask". These are source files: served with the default
+	 * 60-second TTL and no validator, an edited page was handed back stale for
+	 * a minute with no way for the browser even to enquire. The ETag makes the
+	 * question cheap; production keeps the TTL.
 	 */
 	pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
-		return serveAssets({ root: this.pages.root });
+		return serveAssets({
+			root: this.pages.root,
+			...(process.env.NODE_ENV === "production"
+				? {}
+				: { cacheControl: "no-cache" }),
+		});
 	}
 
 	/**

package/src/AuroraProvider.ts

@@ -83,8 +83,11 @@ export default class AuroraProvider {
 	}
 
 	async start(): Promise<void> {
-		// Asset routes are registered in `start()` — after preloads — so apps can
-		// swap aurora's pages root in a preload if they wanted to.
+		// Asset routes are registered in `start()`, which runs BEFORE the
+		// preloads — providers start, then the `starting` hooks, then the
+		// preloads are imported. An earlier version of this comment claimed the
+		// opposite; an app that wanted to swap aurora's pages root has to do it
+		// from a provider, not from a preload.
 		//
 		// Resolve the host router from the container, where Ream registers it as
 		// `'router'` (Ignitor). Reading it from the container — instead of