@c9up/aurora 0.1.37 → 0.1.39

package/dist/AuroraManager.d.ts

@@ -105,6 +105,12 @@ export declare 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>;
     /**

package/dist/AuroraManager.js

@@ -129,9 +129,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() {
-        return serveAssets({ root: this.pages.root });
+        return serveAssets({
+            root: this.pages.root,
+            ...(process.env.NODE_ENV === "production"
+                ? {}
+                : { cacheControl: "no-cache" }),
+        });
     }
     /**
      * Handler for `@c9up/comet`'s runtime (the RPC client). Mount on

package/dist/AuroraProvider.js

@@ -20,10 +20,12 @@ import { isAbsolute, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AuroraManager } from "./AuroraManager.js";
 import { auroraRoute } from "./route.js";
-import { setAurora } from "./services/main.js";
+import { clearAurora, getAurora, setAurora } from "./services/main.js";
 import { renderToString } from "./ssr.js";
 export default class AuroraProvider {
     app;
+    /** What this provider bound, so shutdown only clears its own. */
+    #owned;
     constructor(app) {
         this.app = app;
     }
@@ -46,11 +48,15 @@ export default class AuroraProvider {
         // Force-resolve so `setAurora` runs even if the app never
         // touches the singleton from a preload.
         const manager = await this.app.container.resolve(AuroraManager);
+        this.#owned = manager;
         setAurora(manager);
     }
     async start() {
-        // 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
@@ -77,7 +83,15 @@ export default class AuroraProvider {
         }
     }
     async ready() { }
-    async shutdown() { }
+    async shutdown() {
+        // Release the module-level singleton, while it is still ours. A stopped
+        // application left a dead Aurora manager reachable through `services/main`, and
+        // with two applications in one process the survivor's binding must not
+        // be the one cleared.
+        if (this.#owned !== undefined && getAurora() === this.#owned)
+            clearAurora();
+        this.#owned = undefined;
+    }
     /**
      * Resolve the user-supplied config:
      *   - relative `pages.root` (e.g. `./resources/pages`) is joined to

package/dist/form.d.ts

@@ -43,7 +43,7 @@ export interface FormValidationOutcome {
  * Anything schema-shaped (a `@c9up/rune` schema satisfies this).
  *
  * Both spellings are accepted, and `validateResult` wins when present: rune
- * reserves `validate()` for the VineJS contract (async, throwing), and reading
+ * reserves `validate()` for the async, throwing contract, and reading
  * `.valid` off a Promise yields `undefined` — the form would then report itself
  * invalid with no error to show.
  */

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

@@ -1,4 +1,3 @@
-import "./augmentations.js";
 export type { CookieCodec, CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
 export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { type ClassValue, clsx, cn, twMerge } from "./cn.js";

package/dist/index.js

@@ -4,7 +4,15 @@
 // node:fs / node:path / node:url live in `@c9up/aurora/server`. Keeping them off
 // this barrel is what lets a browser bundle import the client primitives without
 // the bundler dragging Node built-ins through the import graph.
-import "./augmentations.js";
+//
+// `./augmentations.js` is NOT loaded here either, and for a related reason: it
+// augments ream's HttpContext and ContainerBindings, so it names `@c9up/ream`
+// and drags ream's whole source into any program that imports this barrel. A
+// component library that only wants `component`/`html` was compiling ream's
+// decorated console commands under its own tsconfig, which does not enable
+// decorators — a build failure, in a package that never mentions ream. The
+// augmentations load from `@c9up/aurora/server` and `@c9up/aurora/provider`,
+// which is where every type they describe is reachable from anyway.
 export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { clsx, cn, twMerge } from "./cn.js";
 export { command } from "./command.js";

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/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,3 +1,4 @@
+import "./augmentations.js";
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
 export { type AuroraRequestRenderer, auroraContext, } from "./middleware.js";
 export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";

package/dist/server.js

@@ -4,6 +4,12 @@
 // importing client primitives (component/html/hydrate/render) never pulls the
 // Node built-ins through the import graph. Server code imports from
 // `@c9up/aurora/server`; the client `.` entry stays node-free.
+//
+// The ream augmentations (`ctx.aurora`, the `aurora` container binding) load
+// here rather than from the client barrel: everything they describe is
+// server-side, and naming `@c9up/ream` from the browser entry pulled ream's
+// source into every consumer's program — including ones that never use it.
+import "./augmentations.js";
 export { AuroraManager } from "./AuroraManager.js";
 export { auroraContext, } from "./middleware.js";
 export { Pages } from "./Pages.js";

package/dist/services/main.d.ts

@@ -14,5 +14,14 @@ import type { AuroraManager } from "../AuroraManager.js";
 export declare function setAurora(value: AuroraManager): void;
 /** @internal Read the singleton (or `undefined` pre-boot). */
 export declare function getAurora(): AuroraManager | undefined;
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead Aurora manager reachable through `services/main`.
+ *
+ * The caller checks ownership first (`getAurora() === mine`): two applications
+ * share this module in one process, and the one shutting down must not clear
+ * what the other has since bound.
+ */
+export declare function clearAurora(): void;
 declare const aurora: AuroraManager;
 export default aurora;

package/dist/services/main.js

@@ -18,6 +18,17 @@ export function setAurora(value) {
 export function getAurora() {
     return instance;
 }
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead Aurora manager reachable through `services/main`.
+ *
+ * The caller checks ownership first (`getAurora() === mine`): two applications
+ * share this module in one process, and the one shutting down must not clear
+ * what the other has since bound.
+ */
+export function clearAurora() {
+    instance = undefined;
+}
 const aurora = new Proxy({}, {
     get(_target, prop) {
         // A module loader inspects what it imports before anyone uses it: it reads

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "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",

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

@@ -26,7 +26,7 @@ import type {
 	AssetsRequest,
 	AssetsResponse,
 } from "./server/serveAssets.js";
-import { setAurora } from "./services/main.js";
+import { clearAurora, getAurora, setAurora } from "./services/main.js";
 import { renderToString } from "./ssr.js";
 
 interface AuroraContainer {
@@ -50,6 +50,9 @@ interface ReamRouter {
 }
 
 export default class AuroraProvider {
+	/** What this provider bound, so shutdown only clears its own. */
+	#owned: AuroraManager | undefined;
+
 	constructor(protected app: AuroraAppContext) {}
 
 	register(): void {
@@ -75,12 +78,16 @@ export default class AuroraProvider {
 		// touches the singleton from a preload.
 		const manager =
 			await this.app.container.resolve<AuroraManager>(AuroraManager);
+		this.#owned = manager;
 		setAurora(manager);
 	}
 
 	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
@@ -114,7 +121,14 @@ export default class AuroraProvider {
 	}
 
 	async ready(): Promise<void> {}
-	async shutdown(): Promise<void> {}
+	async shutdown(): Promise<void> {
+		// Release the module-level singleton, while it is still ours. A stopped
+		// application left a dead Aurora manager reachable through `services/main`, and
+		// with two applications in one process the survivor's binding must not
+		// be the one cleared.
+		if (this.#owned !== undefined && getAurora() === this.#owned) clearAurora();
+		this.#owned = undefined;
+	}
 
 	/**
 	 * Resolve the user-supplied config:

package/src/form.ts

@@ -45,7 +45,7 @@ export interface FormValidationOutcome {
  * Anything schema-shaped (a `@c9up/rune` schema satisfies this).
  *
  * Both spellings are accepted, and `validateResult` wins when present: rune
- * reserves `validate()` for the VineJS contract (async, throwing), and reading
+ * reserves `validate()` for the async, throwing contract, and reading
  * `.valid` off a Promise yields `undefined` — the form would then report itself
  * invalid with no error to show.
  */

package/src/hydrate.ts

@@ -143,7 +143,10 @@ function renderValueToNodes(
 		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) return [value as ChildNode];

package/src/index.ts

@@ -4,7 +4,15 @@
 // node:fs / node:path / node:url live in `@c9up/aurora/server`. Keeping them off
 // this barrel is what lets a browser bundle import the client primitives without
 // the bundler dragging Node built-ins through the import graph.
-import "./augmentations.js";
+//
+// `./augmentations.js` is NOT loaded here either, and for a related reason: it
+// augments ream's HttpContext and ContainerBindings, so it names `@c9up/ream`
+// and drags ream's whole source into any program that imports this barrel. A
+// component library that only wants `component`/`html` was compiling ream's
+// decorated console commands under its own tsconfig, which does not enable
+// decorators — a build failure, in a package that never mentions ream. The
+// augmentations load from `@c9up/aurora/server` and `@c9up/aurora/provider`,
+// which is where every type they describe is reachable from anyway.
 
 export type {
 	CookieCodec,

package/src/render.ts

@@ -31,6 +31,42 @@ import {
 
 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;
+}
+
+/**
+ * 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: Array<EffectCallback>,
+	cleanups: Disposer[],
+): void {
+	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
@@ -42,22 +78,19 @@ export function render(
 ): Disposer {
 	const cleanups: Disposer[] = [];
 	const mountedNodes: ChildNode[] = [];
-	const mountHooks: Array<EffectCallback> = [];
+	const queue: MountQueue = { hooks: [], flushed: false };
 
-	const fragment = mount(result, cleanups, mountedNodes, mountHooks);
+	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 () => {
@@ -92,7 +125,7 @@ export function mount(
 	result: TemplateResult,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): DocumentFragment {
 	const tpl = getTemplate(result.strings);
 	const fragment = tpl.element.content.cloneNode(true) as DocumentFragment;
@@ -100,7 +133,7 @@ export function mount(
 	// Forward any component()-attached lifecycle from this result.
 	const lifecycle = readComponentLifecycle(result);
 	if (lifecycle) {
-		for (const hook of lifecycle.mountHooks) mountHooks.push(hook);
+		for (const hook of lifecycle.mountHooks) queue.hooks.push(hook);
 		for (const c of lifecycle.cleanups) cleanups.push(c);
 	}
 
@@ -148,7 +181,7 @@ export function mount(
 		if (slot.kind === "attr" && slot.staticParts !== undefined) {
 			collectMultiAttr(slot, node as Element, result.values[i], multiGroups);
 		} else {
-			applySlot(slot, node, result.values[i], cleanups, mounted, mountHooks);
+			applySlot(slot, node, result.values[i], cleanups, mounted, queue);
 		}
 	}
 
@@ -185,18 +218,11 @@ function applySlot(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): void {
 	switch (slot.kind) {
 		case "text":
-			applyTextSlot(
-				slot,
-				node as Comment,
-				value,
-				cleanups,
-				mounted,
-				mountHooks,
-			);
+			applyTextSlot(slot, node as Comment, value, cleanups, mounted, queue);
 			return;
 		case "attr":
 			applyAttrSlot(slot, node as Element, value, cleanups);
@@ -225,7 +251,7 @@ function applyTextSlot(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): void {
 	let currentNodes: ChildNode[] = [];
 	// Per-render disposers for whatever the slot currently shows. A
@@ -246,18 +272,36 @@ function applyTextSlot(
 		disposeLocal();
 		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: MountQueue = { hooks: [], flushed: queue.flushed };
+		const nodes = renderValueIntoNodes(newValue, localCleanups, mounted, own);
 		const parent = anchor.parentNode;
 		if (!parent) return;
 		for (const n of nodes) {
 			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") {
@@ -282,18 +326,18 @@ function renderValueIntoNodes(
 	value: unknown,
 	cleanups: Disposer[],
 	mounted: ChildNode[],
-	mountHooks: Array<EffectCallback>,
+	queue: MountQueue,
 ): ChildNode[] {
 	if (value === null || value === undefined || value === false) return [];
 	if (Array.isArray(value)) {
 		const out: ChildNode[] = [];
 		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/src/server/serveAssets.ts

@@ -10,6 +10,7 @@
  * `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";
@@ -28,6 +29,27 @@ export function packageAssetDir(specifier: string): string {
 	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: string | undefined, tag: string): boolean {
+	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: string): string =>
+		value.startsWith("W/") ? value.slice(2) : value;
+	const current = bare(tag);
+	return header
+		.split(",")
+		.some((candidate) => bare(candidate.trim()) === current);
+}
+
 const CONTENT_TYPES: Record<string, string> = {
 	".js": "text/javascript; charset=utf-8",
 	".mjs": "text/javascript; charset=utf-8",
@@ -44,6 +66,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;
@@ -65,6 +93,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;
 }
@@ -144,10 +176,26 @@ export function serveAssets(
 			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/src/server.ts

@@ -4,6 +4,12 @@
 // importing client primitives (component/html/hydrate/render) never pulls the
 // Node built-ins through the import graph. Server code imports from
 // `@c9up/aurora/server`; the client `.` entry stays node-free.
+//
+// The ream augmentations (`ctx.aurora`, the `aurora` container binding) load
+// here rather than from the client barrel: everything they describe is
+// server-side, and naming `@c9up/ream` from the browser entry pulled ream's
+// source into every consumer's program — including ones that never use it.
+import "./augmentations.js";
 
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
 export {

package/src/services/main.ts

@@ -24,6 +24,18 @@ export function getAurora(): AuroraManager | undefined {
 	return instance;
 }
 
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead Aurora manager reachable through `services/main`.
+ *
+ * The caller checks ownership first (`getAurora() === mine`): two applications
+ * share this module in one process, and the one shutting down must not clear
+ * what the other has since bound.
+ */
+export function clearAurora(): void {
+	instance = undefined;
+}
+
 const aurora: AuroraManager = new Proxy({} as AuroraManager, {
 	get(_target, prop) {
 		// A module loader inspects what it imports before anyone uses it: it reads