@c9up/aurora 0.1.14 → 0.1.15

package/README.md

@@ -24,7 +24,7 @@ providers: [
 
 ## Entry points
 
-- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, the `HttpClient` fetch wrapper, `command()` (async action + reactive loading/data/error), and `form()` (reactive form controller; optional rune validation + rosetta i18n)
+- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, the `HttpClient` fetch wrapper, `createRpcClient()` (JSON-RPC 2.0), `command()` (async action + reactive loading/data/error), `form()` (reactive form controller; optional rune validation + rosetta i18n), `urlFor()` (isomorphic named-route URLs, paired with Ream's `router.namedManifest()`), and `cn()` (zero-dependency Tailwind v4 class merge — `clsx` + `tailwind-merge` reimplemented)
 - `@c9up/aurora/provider` — Ream IoC provider
 - `@c9up/aurora/services/main` — container service accessor
 - `@c9up/aurora/relay` — realtime adapter

package/dist/AuroraManager.d.ts

@@ -22,13 +22,31 @@ export interface AuroraManagerConfig {
      * Override only if you want to serve a custom build.
      */
     auroraDistRoot?: string;
+    /**
+     * URL prefix the asset routes mount under. The aurora runtime is served
+     * from `<assetsPrefix>/aurora/*` and the app's pages from
+     * `<assetsPrefix>/pages/*`, and the SSR importmap + page URLs derive from
+     * it. Default `/_assets` (the leading underscore namespaces framework
+     * assets away from app routes, Next.js `/_next` style). Set e.g. `/assets`
+     * for an underscore-free scheme. An explicit `pages.urlPrefix` still wins.
+     */
+    assetsPrefix?: string;
 }
 export declare class AuroraManager {
     readonly pages: Pages;
     readonly auroraDistRoot: string;
+    /** Resolved asset prefix (default `/_assets`). */
+    readonly assetsPrefix: string;
+    /** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
+    readonly auroraAssetPath: string;
+    /** Mount path for the app's pages — `<assetsPrefix>/pages`. */
+    readonly pageAssetPath: string;
     constructor(config: AuroraManagerConfig);
     /**
-     * SSR + hydrate + ship the document.
+     * SSR + hydrate + ship the document. The importmap default points
+     * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
+     * `options.importmap` still overrides (e.g. to remap to an app-curated
+     * browser entry).
      */
     render(ctx: RenderHttpContext, name: string, props: unknown, options?: RenderPageOptions): Promise<void>;
     /**

package/dist/AuroraManager.js

@@ -17,18 +17,46 @@ import { Pages } from "./Pages.js";
 import { renderPage, } from "./server/renderPage.js";
 import { serveAssets } from "./server/serveAssets.js";
 const DEFAULT_AURORA_DIST = resolvePath(dirname(fileURLToPath(import.meta.url)), "../dist");
+/** Normalize an asset prefix: ensure a leading slash, drop trailing slashes. */
+function normalizePrefix(prefix) {
+    const withLead = prefix.startsWith("/") ? prefix : `/${prefix}`;
+    return withLead.replace(/\/+$/, "") || "/";
+}
 export class AuroraManager {
     pages;
     auroraDistRoot;
+    /** Resolved asset prefix (default `/_assets`). */
+    assetsPrefix;
+    /** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
+    auroraAssetPath;
+    /** Mount path for the app's pages — `<assetsPrefix>/pages`. */
+    pageAssetPath;
     constructor(config) {
-        this.pages = new Pages(config.pages);
+        this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
+        this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
+        this.pageAssetPath = `${this.assetsPrefix}/pages`;
+        // Pages serve their compiled JS from the same prefix unless the app
+        // pins an explicit urlPrefix.
+        this.pages = new Pages({
+            ...config.pages,
+            urlPrefix: config.pages.urlPrefix ?? this.pageAssetPath,
+        });
         this.auroraDistRoot = config.auroraDistRoot ?? DEFAULT_AURORA_DIST;
     }
     /**
-     * SSR + hydrate + ship the document.
+     * SSR + hydrate + ship the document. The importmap default points
+     * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
+     * `options.importmap` still overrides (e.g. to remap to an app-curated
+     * browser entry).
      */
     render(ctx, name, props, options) {
-        return renderPage(ctx, this.pages, name, props, options);
+        return renderPage(ctx, this.pages, name, props, {
+            ...options,
+            importmap: {
+                "@c9up/aurora": `${this.auroraAssetPath}/index.js`,
+                ...options?.importmap,
+            },
+        });
     }
     /**
      * Handler for aurora's pre-built ESM runtime. Mount on

package/dist/AuroraProvider.js

@@ -63,8 +63,10 @@ export default class AuroraProvider {
             return;
         const router = this.app.container.resolve("router");
         const manager = this.app.container.resolve(AuroraManager);
-        router.get("/_assets/aurora/*", adaptHandler(manager.auroraAssetsHandler()));
-        router.get("/_assets/pages/*", adaptHandler(manager.pageAssetsHandler()));
+        // Mount paths derive from the configured `assetsPrefix` (default
+        // `/_assets`) — set `config.aurora.assetsPrefix` to change the scheme.
+        router.get(`${manager.auroraAssetPath}/*`, adaptHandler(manager.auroraAssetsHandler()));
+        router.get(`${manager.pageAssetPath}/*`, adaptHandler(manager.pageAssetsHandler()));
     }
     async ready() { }
     async shutdown() { }

package/dist/hydrate.js

@@ -115,11 +115,17 @@ function hydrateReactiveStructured(fn, pair, cleanups, mountHooks, markerCursor)
         if (firstRun) {
             firstRun = false;
             // Reuse SSR markup: hydrate reactive bindings INSIDE the nested
-            // template against the captured nodes. Inner boundary markers
-            // are consumed from the same cursor (document order).
+            // value against the captured nodes. Inner boundary markers are
+            // consumed from the same cursor (document order) — for an ARRAY this
+            // MUST recurse into every item, else the items' marker pairs go
+            // unconsumed and the cursor desyncs, wiring slots AFTER the list to
+            // the wrong range (SSR list "present but not painted").
             if (isTemplateResult(next)) {
                 hydrateTemplateResult(next, currentNodes, localCleanups, mountHooks, markerCursor);
             }
+            else if (Array.isArray(next)) {
+                hydrateArrayItems(next, currentNodes, localCleanups, mountHooks, markerCursor);
+            }
             return;
         }
         // Signal changed post-hydration: tear down the old subtree's
@@ -146,6 +152,50 @@ function hydrateReactiveStructured(fn, pair, cleanups, mountHooks, markerCursor)
         localCleanups = [];
     });
 }
+/**
+ * Top-level live (SSR) node count a value contributes inside an array slot: a
+ * TemplateResult contributes its template's root-node count, a nested array the
+ * sum of its items, a non-empty scalar one text node, null/undefined/false none.
+ * Used to slice the array's range per item during hydration.
+ */
+function liveNodeCount(value) {
+    if (value === null || value === undefined || value === false)
+        return 0;
+    if (isTemplateResult(value)) {
+        return getTemplate(value.strings).element.content.childNodes.length;
+    }
+    if (Array.isArray(value)) {
+        let n = 0;
+        for (const v of value)
+            n += liveNodeCount(v);
+        return n;
+    }
+    return 1; // scalar → one inlined text node
+}
+/**
+ * Hydrate the items of a reactive array against the SSR nodes inside its marker
+ * range. Each item is hydrated against its own slice of the (marker-collapsed)
+ * range, IN ORDER, so every item's inner marker pairs are consumed in document
+ * order and the global cursor stays aligned for slots AFTER the list. Item
+ * templates need a stable top-level node count (the common
+ * `arr.map(x => html`<li>…</li>`)` shape — single root, no surrounding
+ * whitespace); bare adjacent scalar items can merge in the browser, so use
+ * template items for hydrated lists.
+ */
+function hydrateArrayItems(items, rangeNodes, cleanups, mountHooks, markerCursor) {
+    const nodes = collapseMarkerRanges(rangeNodes);
+    let offset = 0;
+    for (const item of items) {
+        const count = liveNodeCount(item);
+        if (isTemplateResult(item)) {
+            hydrateTemplateResult(item, nodes.slice(offset, offset + count), cleanups, mountHooks, markerCursor);
+        }
+        else if (Array.isArray(item)) {
+            hydrateArrayItems(item, nodes.slice(offset, offset + count), cleanups, mountHooks, markerCursor);
+        }
+        offset += count;
+    }
+}
 /**
  * Adopt SSR markup inside `container`. `factory` is the same function
  * that was rendered server-side — its output (a TemplateResult tree)
@@ -360,8 +410,12 @@ function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCurso
         if (isTemplateResult(current)) {
             hydrateTemplateResult(current, range, cleanups, mountHooks, markerCursor);
         }
-        // A direct (non-reactive) array is static SSR markup; per-item reactive
-        // bindings aren't individually re-hydrated (use `${() => arr.map(…)}`).
+        else if (Array.isArray(current)) {
+            // Direct (non-reactive) array — hydrate each item so its inner marker
+            // pairs are consumed and the cursor stays aligned (same as a reactive
+            // array's first run).
+            hydrateArrayItems(current, range, cleanups, mountHooks, markerCursor);
+        }
         return;
     }
     // Scalar: a reactive scalar updates the range's text node on change; a static

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "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",
@@ -46,7 +46,10 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.15",
+    "@vitest/browser": "4.1.6",
+    "@vitest/browser-playwright": "^4.1.9",
     "happy-dom": "^15.11.7",
+    "playwright": "^1.61.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   },
@@ -68,6 +71,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "biome check src/",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "test:browser": "vitest run -c vitest.browser.config.ts"
   }
 }

package/src/AuroraManager.ts

@@ -30,6 +30,15 @@ export interface AuroraManagerConfig {
 	 * Override only if you want to serve a custom build.
 	 */
 	auroraDistRoot?: string;
+	/**
+	 * URL prefix the asset routes mount under. The aurora runtime is served
+	 * from `<assetsPrefix>/aurora/*` and the app's pages from
+	 * `<assetsPrefix>/pages/*`, and the SSR importmap + page URLs derive from
+	 * it. Default `/_assets` (the leading underscore namespaces framework
+	 * assets away from app routes, Next.js `/_next` style). Set e.g. `/assets`
+	 * for an underscore-free scheme. An explicit `pages.urlPrefix` still wins.
+	 */
+	assetsPrefix?: string;
 }
 
 const DEFAULT_AURORA_DIST = resolvePath(
@@ -37,17 +46,40 @@ const DEFAULT_AURORA_DIST = resolvePath(
 	"../dist",
 );
 
+/** Normalize an asset prefix: ensure a leading slash, drop trailing slashes. */
+function normalizePrefix(prefix: string): string {
+	const withLead = prefix.startsWith("/") ? prefix : `/${prefix}`;
+	return withLead.replace(/\/+$/, "") || "/";
+}
+
 export class AuroraManager {
 	readonly pages: Pages;
 	readonly auroraDistRoot: string;
+	/** Resolved asset prefix (default `/_assets`). */
+	readonly assetsPrefix: string;
+	/** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
+	readonly auroraAssetPath: string;
+	/** Mount path for the app's pages — `<assetsPrefix>/pages`. */
+	readonly pageAssetPath: string;
 
 	constructor(config: AuroraManagerConfig) {
-		this.pages = new Pages(config.pages);
+		this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
+		this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
+		this.pageAssetPath = `${this.assetsPrefix}/pages`;
+		// Pages serve their compiled JS from the same prefix unless the app
+		// pins an explicit urlPrefix.
+		this.pages = new Pages({
+			...config.pages,
+			urlPrefix: config.pages.urlPrefix ?? this.pageAssetPath,
+		});
 		this.auroraDistRoot = config.auroraDistRoot ?? DEFAULT_AURORA_DIST;
 	}
 
 	/**
-	 * SSR + hydrate + ship the document.
+	 * SSR + hydrate + ship the document. The importmap default points
+	 * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
+	 * `options.importmap` still overrides (e.g. to remap to an app-curated
+	 * browser entry).
 	 */
 	render(
 		ctx: RenderHttpContext,
@@ -55,7 +87,13 @@ export class AuroraManager {
 		props: unknown,
 		options?: RenderPageOptions,
 	): Promise<void> {
-		return renderPage(ctx, this.pages, name, props, options);
+		return renderPage(ctx, this.pages, name, props, {
+			...options,
+			importmap: {
+				"@c9up/aurora": `${this.auroraAssetPath}/index.js`,
+				...options?.importmap,
+			},
+		});
 	}
 
 	/**

package/src/AuroraProvider.ts

@@ -91,8 +91,16 @@ export default class AuroraProvider {
 		if (!this.app.container.has("router")) return;
 		const router = this.app.container.resolve<ReamRouter>("router");
 		const manager = this.app.container.resolve<AuroraManager>(AuroraManager);
-		router.get("/_assets/aurora/*", adaptHandler(manager.auroraAssetsHandler()));
-		router.get("/_assets/pages/*", adaptHandler(manager.pageAssetsHandler()));
+		// Mount paths derive from the configured `assetsPrefix` (default
+		// `/_assets`) — set `config.aurora.assetsPrefix` to change the scheme.
+		router.get(
+			`${manager.auroraAssetPath}/*`,
+			adaptHandler(manager.auroraAssetsHandler()),
+		);
+		router.get(
+			`${manager.pageAssetPath}/*`,
+			adaptHandler(manager.pageAssetsHandler()),
+		);
 	}
 
 	async ready(): Promise<void> {}

package/src/hydrate.ts

@@ -174,8 +174,11 @@ function hydrateReactiveStructured(
 		if (firstRun) {
 			firstRun = false;
 			// Reuse SSR markup: hydrate reactive bindings INSIDE the nested
-			// template against the captured nodes. Inner boundary markers
-			// are consumed from the same cursor (document order).
+			// value against the captured nodes. Inner boundary markers are
+			// consumed from the same cursor (document order) — for an ARRAY this
+			// MUST recurse into every item, else the items' marker pairs go
+			// unconsumed and the cursor desyncs, wiring slots AFTER the list to
+			// the wrong range (SSR list "present but not painted").
 			if (isTemplateResult(next)) {
 				hydrateTemplateResult(
 					next,
@@ -184,6 +187,14 @@ function hydrateReactiveStructured(
 					mountHooks,
 					markerCursor,
 				);
+			} else if (Array.isArray(next)) {
+				hydrateArrayItems(
+					next,
+					currentNodes,
+					localCleanups,
+					mountHooks,
+					markerCursor,
+				);
 			}
 			return;
 		}
@@ -213,6 +224,67 @@ function hydrateReactiveStructured(
 	});
 }
 
+/**
+ * Top-level live (SSR) node count a value contributes inside an array slot: a
+ * TemplateResult contributes its template's root-node count, a nested array the
+ * sum of its items, a non-empty scalar one text node, null/undefined/false none.
+ * Used to slice the array's range per item during hydration.
+ */
+function liveNodeCount(value: unknown): number {
+	if (value === null || value === undefined || value === false) return 0;
+	if (isTemplateResult(value)) {
+		return getTemplate(value.strings).element.content.childNodes.length;
+	}
+	if (Array.isArray(value)) {
+		let n = 0;
+		for (const v of value) n += liveNodeCount(v);
+		return n;
+	}
+	return 1; // scalar → one inlined text node
+}
+
+/**
+ * Hydrate the items of a reactive array against the SSR nodes inside its marker
+ * range. Each item is hydrated against its own slice of the (marker-collapsed)
+ * range, IN ORDER, so every item's inner marker pairs are consumed in document
+ * order and the global cursor stays aligned for slots AFTER the list. Item
+ * templates need a stable top-level node count (the common
+ * `arr.map(x => html`<li>…</li>`)` shape — single root, no surrounding
+ * whitespace); bare adjacent scalar items can merge in the browser, so use
+ * template items for hydrated lists.
+ */
+function hydrateArrayItems(
+	items: unknown[],
+	rangeNodes: ChildNode[],
+	cleanups: Disposer[],
+	mountHooks: Array<EffectCallback>,
+	markerCursor: MarkerCursor,
+): void {
+	const nodes = collapseMarkerRanges(rangeNodes);
+	let offset = 0;
+	for (const item of items) {
+		const count = liveNodeCount(item);
+		if (isTemplateResult(item)) {
+			hydrateTemplateResult(
+				item,
+				nodes.slice(offset, offset + count),
+				cleanups,
+				mountHooks,
+				markerCursor,
+			);
+		} else if (Array.isArray(item)) {
+			hydrateArrayItems(
+				item,
+				nodes.slice(offset, offset + count),
+				cleanups,
+				mountHooks,
+				markerCursor,
+			);
+		}
+		offset += count;
+	}
+}
+
 /**
  * Adopt SSR markup inside `container`. `factory` is the same function
  * that was rendered server-side — its output (a TemplateResult tree)
@@ -489,9 +561,12 @@ function hydrateTextSlot(
 		}
 		if (isTemplateResult(current)) {
 			hydrateTemplateResult(current, range, cleanups, mountHooks, markerCursor);
+		} else if (Array.isArray(current)) {
+			// Direct (non-reactive) array — hydrate each item so its inner marker
+			// pairs are consumed and the cursor stays aligned (same as a reactive
+			// array's first run).
+			hydrateArrayItems(current, range, cleanups, mountHooks, markerCursor);
 		}
-		// A direct (non-reactive) array is static SSR markup; per-item reactive
-		// bindings aren't individually re-hydrated (use `${() => arr.map(…)}`).
 		return;
 	}