@c9up/aurora 0.1.13 → 0.1.15

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)
@@ -278,6 +328,17 @@ function resolvePathLive(_root, path, rootNodes) {
     return node;
 }
 function hydrateSlot(slot, node, value, cleanups, mountHooks, markerCursor) {
+    // Type guard: an attr/bool/prop/event slot needs an Element. On a SSR↔client
+    // structural desync the path can resolve to an EXISTING node of the wrong
+    // type (Text/Comment); casting it to Element and calling setAttribute would
+    // throw "setAttribute is not a function". Skip the binding (fail-soft) rather
+    // than crash hydration. Text slots accept text/comment/element, so they pass.
+    if (slot.kind !== "text" && node.nodeType !== 1) {
+        if (typeof console !== "undefined") {
+            console.warn(`[aurora] hydrate: slot (${slot.kind}) path ${slot.path.join(".")} resolved to a non-element node — skipping binding`);
+        }
+        return;
+    }
     switch (slot.kind) {
         case "text":
             hydrateTextSlot(node, value, cleanups, mountHooks, markerCursor);
@@ -306,15 +367,74 @@ function hydrateSlot(slot, node, value, cleanups, mountHooks, markerCursor) {
  * existing text node in place. For nested TemplateResults, we
  * recursively hydrate against the captured sibling range.
  */
+/**
+ * First text node inside a marker pair's range, or a fresh empty one inserted
+ * before the end marker (when the SSR value was empty → no text node yet).
+ */
+function reactiveTextNode(pair) {
+    for (let n = pair.start.nextSibling; n !== null && n !== pair.end; n = n.nextSibling) {
+        if (n.nodeType === 3 /* TEXT */)
+            return n;
+    }
+    const doc = pair.end.ownerDocument ?? document;
+    const fresh = doc.createTextNode("");
+    pair.end.parentNode?.insertBefore(fresh, pair.end);
+    return fresh;
+}
 function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCursor) {
-    // The path lands on the comment marker that EXISTS in the parsed
-    // template but not in SSR output. Hydration walks the live siblings
-    // to find the text node that holds the SSR value.
-    // Strategy: the comment was located at child index N inside its
-    // parent; SSR wrote the value as the immediately-preceding text
-    // node (or nothing for null/false). Live node here is whatever the
-    // path resolution returned — often a text node, sometimes an
-    // element (for nested templates). We rebind in-place.
+    // Every text slot is SSR-wrapped in a <!--$-->…<!--/$--> pair, and its path
+    // resolves (via collapseMarkerRanges) to the start marker. Consume the
+    // matching pair in document order and bind within its range.
+    const pair = markerCursor.pairs[markerCursor.i];
+    if (pair === undefined) {
+        // Legacy markup without per-slot markers (mismatched older SSR build).
+        legacyHydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCursor);
+        return;
+    }
+    markerCursor.i += 1;
+    const reactiveFn = isSignal(value) || typeof value === "function"
+        ? value
+        : null;
+    const current = reactiveFn ? reactiveFn() : value;
+    // Structured value (nested template / array): reactive → swap on change;
+    // direct → adopt the SSR range once (inner bindings wired against it).
+    if (isTemplateResult(current) || Array.isArray(current)) {
+        if (reactiveFn) {
+            hydrateReactiveStructured(reactiveFn, pair, cleanups, mountHooks, markerCursor);
+            return;
+        }
+        const range = [];
+        for (let n = pair.start.nextSibling; n !== null && n !== pair.end; n = n.nextSibling) {
+            range.push(n);
+        }
+        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);
+        }
+        return;
+    }
+    // Scalar: a reactive scalar updates the range's text node on change; a static
+    // scalar is already rendered between the markers (nothing to wire).
+    if (reactiveFn) {
+        const textNode = reactiveTextNode(pair);
+        const dispose = effect(() => {
+            const v = reactiveFn();
+            textNode.data = v == null || v === false ? "" : String(v);
+        });
+        cleanups.push(dispose);
+    }
+}
+/**
+ * Pre-marker fallback — best-effort hydration when the SSR markup carries no
+ * per-slot boundary markers (a mismatched older SSR build). Current builds wrap
+ * every text slot, so this path is dead for matched server/client versions.
+ */
+function legacyHydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCursor) {
     if (isSignal(value) || typeof value === "function") {
         const fn = value;
         // First, evaluate eagerly to detect a structured value (nested

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+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";
@@ -21,3 +22,4 @@ export { type AuroraHttpContext, type AuroraResponse, type AuroraRouteConfig, au
 export { createRpcClient, isRpcError, type RpcCall, type RpcClient, type RpcClientOptions, RpcError, type RpcResult, } from "./rpc.js";
 export { renderToString } from "./ssr.js";
 export type { TemplateResult } from "./types.js";
+export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+export { clsx, cn, twMerge } from "./cn.js";
 export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
 export { form } from "./form.js";
@@ -16,3 +17,4 @@ export { render } from "./render.js";
 export { auroraRoute, } from "./route.js";
 export { createRpcClient, isRpcError, RpcError, } from "./rpc.js";
 export { renderToString } from "./ssr.js";
+export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/dist/render.js

@@ -80,6 +80,17 @@ export function mount(result, cleanups, mounted, mountHooks) {
             }
             continue;
         }
+        // Type guard: an attr/bool/prop/event slot needs an Element. On a
+        // structural desync the path can land on an EXISTING node of the wrong
+        // type (Text/Comment) — casting it to Element and calling setAttribute
+        // would throw "setAttribute is not a function". Degrade like the null
+        // case (skip the binding) instead of crashing the whole render.
+        if (slot.kind !== "text" && node.nodeType !== 1) {
+            if (typeof console !== "undefined") {
+                console.warn(`[aurora] render: slot ${i} (${slot.kind}) path ${slot.path.join(".")} resolved to a non-element node — skipping binding`);
+            }
+            continue;
+        }
         if (slot.kind === "attr" && slot.staticParts !== undefined) {
             collectMultiAttr(slot, node, result.values[i], multiGroups);
         }

package/dist/server/renderPage.d.ts

@@ -58,5 +58,13 @@ export interface RenderPageOptions {
      * targets.
      */
     rootId?: string;
+    /**
+     * Named-route manifest (`name → path-pattern`) for the isomorphic
+     * `urlFor()` helper — build it with Ream's `router.namedManifest()`. It is
+     * installed server-side before the page renders AND serialized into the page
+     * so the hydrate bootstrap re-installs it, making `urlFor` work identically
+     * in SSR and the browser. Omit if the app doesn't use `urlFor`.
+     */
+    routes?: Record<string, string>;
 }
 export declare function renderPage<P>(ctx: RenderHttpContext, pages: Pages, name: string, props: P, options?: RenderPageOptions): Promise<void>;

package/dist/server/renderPage.js

@@ -23,7 +23,12 @@
  *   </body>
  */
 import { renderToString } from "../ssr.js";
+import { setRouteManifest } from "../url.js";
 export async function renderPage(ctx, pages, name, props, options = {}) {
+    // Install the route manifest BEFORE rendering so a page calling `urlFor`
+    // during SSR resolves against the same map the client will get.
+    if (options.routes)
+        setRouteManifest(options.routes);
     const factory = await pages.resolve(name);
     // The factory must be invoked the SAME way client-side for hydrate
     // to find matching slots — `Page(props)` is the contract.
@@ -51,11 +56,13 @@ ${options.headExtra ?? ""}
         props,
         url: pageUrl,
         rootId,
+        routes: options.routes ?? {},
     })}</script>
 <script type="module">
-import { hydrate } from '@c9up/aurora'
+import { hydrate, setRouteManifest } from '@c9up/aurora'
 import Page from ${JSON.stringify(pageUrl)}
 const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
+setRouteManifest(data.routes ?? {})
 hydrate(document.getElementById(data.rootId), () => Page(data.props))
 </script>
 </body>

package/dist/ssr.js

@@ -62,45 +62,25 @@ function stringifyTemplateResult(result) {
         if (i < values.length && !skipValue) {
             const value = values[i];
             const inAttr = isInsideAttribute(out);
-            if (!inAttr && isReactiveStructuredSlot(value)) {
-                // Reactive text slot whose value is a nested template /
-                // array — wrap the rendered content in boundary markers so
-                // hydration can locate the exact node range and SWAP it when
-                // the signal changes client-side. Without these markers a
-                // nested-template slot hydrates once and then goes stale
-                // (no way to find where the subtree starts/ends). Scalar
-                // reactive slots (`${signal}` → text) are NOT wrapped: their
-                // hydration updates the text node in place, no range needed.
-                out += `<!--${SLOT_START}-->`;
-                out += stringifyValue(value, false);
-                out += `<!--${SLOT_END}-->`;
+            if (inAttr) {
+                out += stringifyValue(value, true);
             }
-            else if (!inAttr && isTemplateResult(value)) {
-                // DIRECT (non-reactive) nested template — component composition,
-                // e.g. `${Layout({ children })}` or `${table}`. It renders to a
-                // node RANGE just like a reactive structured slot, so it needs the
-                // SAME boundary markers: the client template counts every slot as
-                // ONE comment node, so without a markable range a multi-node child
-                // shifts the childNode indices of every FOLLOWING sibling slot →
-                // dead bindings / "slot path not found". Hydration collapses the
-                // marked range back to one node so sibling paths stay aligned.
+            else {
+                // Text-region slot — ALWAYS wrap in boundary markers so the SSR
+                // node structure matches the client template, which keeps exactly
+                // ONE comment node per slot. An inlined value otherwise MERGES
+                // with adjacent static text or sibling values when the browser
+                // parses the SSR HTML (`<p>Hello ${x}!</p>` → ONE text node, not
+                // three), dropping the node count and desyncing the slot AND every
+                // following sibling binding (text, attr, event). Hydration
+                // collapses each `<!--$-->…<!--/$-->` range back to one node
+                // (collapseMarkerRanges) so paths align exactly; the range also
+                // anchors scalar text updates and nested-template swaps. Same
+                // part-marker approach as lit-html / Solid.
                 out += `<!--${SLOT_START}-->`;
                 out += stringifyValue(value, false);
                 out += `<!--${SLOT_END}-->`;
             }
-            else if (inAttr) {
-                out += stringifyValue(value, true);
-            }
-            else {
-                // Text-region scalar slot. An empty result (e.g. `cond ? x : ''`)
-                // would emit NO node and desync the path-based hydration of the
-                // following sibling slots (their @input/@submit bindings break).
-                // Emit an empty-comment placeholder so the position is preserved
-                // — lit-html / Solid do the same; hydration materializes the text
-                // node there.
-                const text = stringifyValue(value, false);
-                out += text === "" ? "<!---->" : text;
-            }
         }
     }
     return out;
@@ -108,28 +88,6 @@ function stringifyTemplateResult(result) {
 /** Boundary-marker comment payloads (kept in sync with hydrate.ts). */
 const SLOT_START = "$";
 const SLOT_END = "/$";
-/**
- * True when `value` is a reactive expression (signal / function) whose
- * current evaluation is a structured node payload (a nested
- * TemplateResult, or an array). These are the slots that can SWAP their
- * subtree on a client-side change and therefore need boundary markers
- * for hydration to find the range. A reactive slot resolving to a
- * scalar (string / number) is updated in place and needs no markers.
- */
-function isReactiveStructuredSlot(value) {
-    if (!isSignal(value) && typeof value !== "function")
-        return false;
-    let evaluated;
-    try {
-        evaluated = isSignal(value)
-            ? value()
-            : value();
-    }
-    catch {
-        return false;
-    }
-    return isTemplateResult(evaluated) || Array.isArray(evaluated);
-}
 /**
  * Returns true if the position at the end of `htmlSoFar` lives inside
  * the value region of an HTML tag (between `<` and `>`). The check

package/dist/url.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `urlFor` — isomorphic named-route URL builder (AdonisJS v7 parity), the client
+ * half of Ream's `router.urlFor()`.
+ *
+ * Routes live server-side in Ream's router; this helper builds URLs from a
+ * serialized `name → path-pattern` manifest so the SAME `urlFor(name, params)`
+ * works in a page during SSR and after hydration in the browser — no more
+ * hard-coded paths like `redirect('/login')` / `href: '/team'`.
+ *
+ *   urlFor('users.show', { id: 42 })        // → '/users/42'
+ *   urlFor('auth.login')                    // → '/login'
+ *   urlFor('search', {}, { q: 'ream', p: 2 })// → '/search?q=ream&p=2'
+ *
+ * The manifest is populated by {@link setRouteManifest}: `renderPage` calls it
+ * server-side from `options.routes` (build it with `router.namedManifest()`), and
+ * injects the same map into the page so the hydrate bootstrap re-sets it client
+ * side. Node-free — part of aurora's client runtime.
+ */
+/**
+ * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
+ * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
+ * Replaces any previous manifest. Routes are static per app, so this is set once
+ * per environment (server boot / page render, and the hydrate bootstrap).
+ */
+export declare function setRouteManifest(routes: Record<string, string>): void;
+/** The currently-installed route manifest (mainly for tests/introspection). */
+export declare function getRouteManifest(): Record<string, string>;
+/**
+ * Build a URL for a named route — fills `:param` placeholders, drops unprovided
+ * optional (`:name?`) segments, appends `query` as a query string, and throws on
+ * an unknown route or a missing required param. Mirrors Ream's `router.urlFor`.
+ */
+export declare function urlFor(name: string, params?: Record<string, string | number>, query?: Record<string, string | number>): string;

package/dist/url.js

@@ -0,0 +1,68 @@
+/**
+ * `urlFor` — isomorphic named-route URL builder (AdonisJS v7 parity), the client
+ * half of Ream's `router.urlFor()`.
+ *
+ * Routes live server-side in Ream's router; this helper builds URLs from a
+ * serialized `name → path-pattern` manifest so the SAME `urlFor(name, params)`
+ * works in a page during SSR and after hydration in the browser — no more
+ * hard-coded paths like `redirect('/login')` / `href: '/team'`.
+ *
+ *   urlFor('users.show', { id: 42 })        // → '/users/42'
+ *   urlFor('auth.login')                    // → '/login'
+ *   urlFor('search', {}, { q: 'ream', p: 2 })// → '/search?q=ream&p=2'
+ *
+ * The manifest is populated by {@link setRouteManifest}: `renderPage` calls it
+ * server-side from `options.routes` (build it with `router.namedManifest()`), and
+ * injects the same map into the page so the hydrate bootstrap re-sets it client
+ * side. Node-free — part of aurora's client runtime.
+ */
+let manifest = {};
+/**
+ * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
+ * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
+ * Replaces any previous manifest. Routes are static per app, so this is set once
+ * per environment (server boot / page render, and the hydrate bootstrap).
+ */
+export function setRouteManifest(routes) {
+    manifest = { ...routes };
+}
+/** The currently-installed route manifest (mainly for tests/introspection). */
+export function getRouteManifest() {
+    return { ...manifest };
+}
+/**
+ * Build a URL for a named route — fills `:param` placeholders, drops unprovided
+ * optional (`:name?`) segments, appends `query` as a query string, and throws on
+ * an unknown route or a missing required param. Mirrors Ream's `router.urlFor`.
+ */
+export function urlFor(name, params, query) {
+    const pattern = manifest[name];
+    if (pattern === undefined) {
+        const known = Object.keys(manifest);
+        throw new Error(`[aurora] urlFor: unknown route '${name}'. ${known.length > 0
+            ? `Known: ${known.join(", ")}`
+            : "No routes registered — was the manifest passed to render() / setRouteManifest() called?"}`);
+    }
+    let url = pattern;
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            // Word-boundary substitution so `:id` doesn't corrupt `:idx`.
+            const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            url = url.replace(new RegExp(`:${escaped}\\??(?![\\w])`, "g"), encodeURIComponent(String(value)));
+        }
+    }
+    // Strip remaining optional placeholders (`:name?` not provided).
+    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(", ")}`);
+    }
+    if (query) {
+        const qs = Object.entries(query)
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join("&");
+        if (qs)
+            url += `${url.includes("?") ? "&" : "?"}${qs}`;
+    }
+    return url;
+}

package/package.json

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