@c9up/aurora 0.1.13 → 0.1.15

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)
@@ -376,6 +448,19 @@ function hydrateSlot(
 	mountHooks: Array<EffectCallback>,
 	markerCursor: MarkerCursor,
 ): void {
+	// 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);
@@ -405,6 +490,24 @@ function hydrateSlot(
  * 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: MarkerPair): Text {
+	for (
+		let n = pair.start.nextSibling;
+		n !== null && n !== pair.end;
+		n = n.nextSibling
+	) {
+		if (n.nodeType === 3 /* TEXT */) return n as Text;
+	}
+	const doc = pair.end.ownerDocument ?? document;
+	const fresh = doc.createTextNode("");
+	pair.end.parentNode?.insertBefore(fresh, pair.end);
+	return fresh;
+}
+
 function hydrateTextSlot(
 	commentMarker: Node,
 	value: unknown,
@@ -412,14 +515,85 @@ function hydrateTextSlot(
 	mountHooks: Array<EffectCallback>,
 	markerCursor: MarkerCursor,
 ): void {
-	// 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 as () => unknown)
+			: 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: ChildNode[] = [];
+		for (
+			let n = pair.start.nextSibling;
+			n !== null && n !== pair.end;
+			n = n.nextSibling
+		) {
+			range.push(n as ChildNode);
+		}
+		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: Node,
+	value: unknown,
+	cleanups: Disposer[],
+	mountHooks: Array<EffectCallback>,
+	markerCursor: MarkerCursor,
+): void {
 	if (isSignal(value) || typeof value === "function") {
 		const fn = value as () => unknown;
 		// First, evaluate eagerly to detect a structured value (nested

package/src/index.ts

@@ -34,6 +34,7 @@ export {
 	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";
@@ -126,3 +127,4 @@ export {
 } from "./rpc.js";
 export { renderToString } from "./ssr.js";
 export type { TemplateResult } from "./types.js";
+export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/src/render.ts

@@ -118,6 +118,19 @@ export function mount(
 			}
 			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 as Element, result.values[i], multiGroups);
 		} else {

package/src/server/renderPage.ts

@@ -25,6 +25,7 @@
 
 import type { Pages } from "../Pages.js";
 import { renderToString } from "../ssr.js";
+import { setRouteManifest } from "../url.js";
 
 /**
  * Structural slice of the host framework's response. Same shape
@@ -62,6 +63,14 @@ 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 async function renderPage<P>(
@@ -71,6 +80,10 @@ export async function renderPage<P>(
 	props: P,
 	options: RenderPageOptions = {},
 ): Promise<void> {
+	// 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.
@@ -100,11 +113,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/src/ssr.ts

@@ -66,41 +66,23 @@ function stringifyTemplateResult(result: TemplateResult): string {
 		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}-->`;
-			} 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.
+			if (inAttr) {
+				out += stringifyValue(value, true);
+			} 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;
 			}
 		}
 	}
@@ -111,27 +93,6 @@ function stringifyTemplateResult(result: TemplateResult): string {
 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: unknown): boolean {
-	if (!isSignal(value) && typeof value !== "function") return false;
-	let evaluated: unknown;
-	try {
-		evaluated = isSignal(value)
-			? (value as () => unknown)()
-			: (value as () => unknown)();
-	} 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/src/url.ts

@@ -0,0 +1,91 @@
+/**
+ * `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: Record<string, string> = {};
+
+/**
+ * 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: Record<string, string>): void {
+	manifest = { ...routes };
+}
+
+/** The currently-installed route manifest (mainly for tests/introspection). */
+export function getRouteManifest(): Record<string, string> {
+	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: string,
+	params?: Record<string, string | number>,
+	query?: Record<string, string | number>,
+): string {
+	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;
+}