@c9up/aurora 0.1.12 → 0.1.14

package/dist/command.js

@@ -61,19 +61,35 @@ class CommandRunner {
         this.#loading(true);
         this.#error(null);
         try {
-            const result = await this.#task(...args);
+            let result;
+            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) {

package/dist/hydrate.js

@@ -231,16 +231,64 @@ function hydrateTemplateResult(result, liveNodes, cleanups, mountHooks, markerCu
  * 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) {
+    const out = [];
+    let depth = 0;
+    for (const n of nodes) {
+        if (n.nodeType === 8 /* Comment */) {
+            const data = n.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, path, rootNodes) {
     if (path.length === 0)
         return null;
-    let node = 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 = 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;
 }
 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);
@@ -269,15 +317,70 @@ 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);
+        }
+        // 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, value, cleanups, mountHooks, markerCursor) {
     if (isSignal(value) || typeof value === "function") {
         const fn = value;
         // First, evaluate eagerly to detect a structured value (nested
@@ -332,6 +435,23 @@ function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCurso
         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 = [];
+            for (let n = pair.start.nextSibling; n !== null && n !== pair.end; n = n.nextSibling) {
+                range.push(n);
+            }
+            hydrateTemplateResult(value, range, cleanups, mountHooks, markerCursor);
+            return;
+        }
+        // Legacy markup without markers (older SSR build): best-effort against
+        // the single resolved node.
         hydrateTemplateResult(value, [commentMarker], cleanups, mountHooks, markerCursor);
         return;
     }

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

@@ -71,6 +71,26 @@ export function mount(result, cleanups, mounted, mountHooks) {
     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, result.values[i], multiGroups);
         }
@@ -88,8 +108,19 @@ export function mount(result, cleanups, mounted, mountHooks) {
 }
 function resolvePath(root, path) {
     let 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;
 }
 function applySlot(slot, node, value, cleanups, mounted, mountHooks) {

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,31 +62,24 @@ 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}-->`;
-            }
-            else if (inAttr) {
+            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;
+                // 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}-->`;
             }
         }
     }
@@ -95,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.12",
+  "version": "0.1.14",
   "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",