@c9up/aurora 0.1.12 → 0.1.14

package/src/command.ts

@@ -91,14 +91,32 @@ class CommandRunner<TArgs extends unknown[], TData>
 		this.#loading(true);
 		this.#error(null);
 		try {
-			const result = await this.#task(...args);
+			let result: TData;
+			try {
+				result = await this.#task(...args);
+			} catch (error) {
+				if (id !== this.#runId) return; // superseded — drop
+				this.#error(error);
+				for (const handler of this.#onFail) handler(error);
+				return;
+			}
 			if (id !== this.#runId) return; // superseded by a newer run — drop
 			this.#data(result);
-			for (const handler of this.#onSuccess) handler(result);
-		} catch (error) {
-			if (id !== this.#runId) return; // superseded — drop
-			this.#error(error);
-			for (const handler of this.#onFail) handler(error);
+			// onSuccess runs OUTSIDE the task's failure boundary: success is
+			// decided by the task, never by the callback. A throw here (e.g. a
+			// render error after the data lands) is a handler bug — surfacing it
+			// as a task failure would route to onFail, which on a guarded page
+			// masquerades as a logout. Report it, but never reclassify it.
+			try {
+				for (const handler of this.#onSuccess) handler(result);
+			} catch (handlerError) {
+				if (typeof console !== "undefined") {
+					console.error(
+						"[aurora] a command onSuccess handler threw — not treated as a task failure:",
+						handlerError,
+					);
+				}
+			}
 		} finally {
 			if (id === this.#runId) {
 				this.#loading(false);

package/src/hydrate.ts

@@ -320,15 +320,50 @@ function hydrateTemplateResult(
  * Text-slot paths point to a comment marker that doesn't exist in
  * hydration markup — we tolerate the miss and return null.
  */
+/**
+ * Collapse each top-level `<!--$-->…<!--/$-->` range in `nodes` to a SINGLE
+ * entry (its start marker), dropping the in-range content + end marker from the
+ * count. SSR expands a structured slot (reactive OR a direct nested template)
+ * to a node RANGE, but the parsed client template counts every slot as exactly
+ * ONE comment node — so without this collapse the extra range nodes shift the
+ * childNode index of every FOLLOWING sibling slot (dead bindings / "slot path
+ * not found"). Nested ranges (depth > 0) are skipped wholesale: they belong to
+ * the outer slot's content and are hydrated when we recurse into it.
+ */
+function collapseMarkerRanges(nodes: ChildNode[]): ChildNode[] {
+	const out: ChildNode[] = [];
+	let depth = 0;
+	for (const n of nodes) {
+		if (n.nodeType === 8 /* Comment */) {
+			const data = (n as Comment).data;
+			if (data === SLOT_START) {
+				if (depth === 0) out.push(n); // the whole range counts as one node
+				depth += 1;
+				continue;
+			}
+			if (data === SLOT_END) {
+				if (depth > 0) depth -= 1;
+				continue;
+			}
+		}
+		if (depth === 0) out.push(n);
+	}
+	return out;
+}
+
 function resolvePathLive(
 	_root: ParentNode,
 	path: NodePath,
 	rootNodes: ChildNode[],
 ): Node | null {
 	if (path.length === 0) return null;
-	let node: Node | null = rootNodes[path[0]] ?? null;
+	// Collapse marker ranges at EVERY level so the live child list matches the
+	// parsed template's one-node-per-slot shape (see collapseMarkerRanges).
+	let children = collapseMarkerRanges(rootNodes);
+	let node: Node | null = children[path[0]] ?? null;
 	for (let i = 1; node && i < path.length; i++) {
-		node = node.childNodes[path[i]] ?? null;
+		children = collapseMarkerRanges(Array.from(node.childNodes));
+		node = children[path[i]] ?? null;
 	}
 	return node;
 }
@@ -341,6 +376,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);
@@ -370,6 +418,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,
@@ -377,14 +443,82 @@ 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);
+		}
+		// A direct (non-reactive) array is static SSR markup; per-item reactive
+		// bindings aren't individually re-hydrated (use `${() => arr.map(…)}`).
+		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
@@ -451,6 +585,27 @@ function hydrateTextSlot(
 		return;
 	}
 	if (isTemplateResult(value)) {
+		// DIRECT nested template (component composition, `${Layout({…})}`). SSR
+		// wrapped it in a boundary-marker pair (same scheme as a reactive
+		// structured slot). Consume the pair in document order and hydrate the
+		// nested template against its captured range — wiring inner bindings to
+		// the SSR nodes and keeping the marker cursor aligned.
+		const pair = markerCursor.pairs[markerCursor.i];
+		if (pair !== undefined) {
+			markerCursor.i += 1;
+			const range: ChildNode[] = [];
+			for (
+				let n = pair.start.nextSibling;
+				n !== null && n !== pair.end;
+				n = n.nextSibling
+			) {
+				range.push(n as ChildNode);
+			}
+			hydrateTemplateResult(value, range, cleanups, mountHooks, markerCursor);
+			return;
+		}
+		// Legacy markup without markers (older SSR build): best-effort against
+		// the single resolved node.
 		hydrateTemplateResult(
 			value,
 			[commentMarker as ChildNode],

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

@@ -107,6 +107,30 @@ export function mount(
 	for (let i = 0; i < tpl.slots.length; i++) {
 		const slot = tpl.slots[i];
 		const node = resolvePath(fragment, slot.path);
+		if (node === null) {
+			// Path didn't resolve — skip this binding rather than crash (see
+			// resolvePath). Degrades to a dead binding; the surrounding render
+			// (and any command driving it) survives.
+			if (typeof console !== "undefined") {
+				console.warn(
+					`[aurora] render: slot ${i} (${slot.kind}) path ${slot.path.join(".")} did not resolve — skipping binding`,
+				);
+			}
+			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 {
@@ -124,9 +148,20 @@ export function mount(
 	return fragment;
 }
 
-function resolvePath(root: ParentNode, path: NodePath): Node {
+function resolvePath(root: ParentNode, path: NodePath): Node | null {
 	let node: Node = root;
-	for (const i of path) node = node.childNodes[i];
+	for (const i of path) {
+		const next = node.childNodes[i];
+		// Fail-soft: a path step that runs off the live child list means the
+		// tree diverged from the parsed template (a hydration desync). Return
+		// null so the caller skips the binding instead of dereferencing
+		// `undefined.childNodes` and crashing the whole render — which, when the
+		// render runs inside a command's onSuccess, used to masquerade as a
+		// task failure (and on a guarded page, a logout). Mirrors
+		// `resolvePathLive` in hydrate.ts.
+		if (next === undefined) return null;
+		node = next;
+	}
 	return node;
 }
 

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,29 +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.
+			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;
 			}
 		}
 	}
@@ -99,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;
+}