@c9up/aurora 0.1.33 → 0.1.36

package/dist/AuroraProvider.d.ts

@@ -15,6 +15,7 @@
  * framework with a container — non-Ream hosts get the singleton bindings
  * and skip the route auto-registration silently.
  */
+import "./augmentations.js";
 interface AuroraContainer {
     singleton(token: unknown, factory: () => unknown): void;
     resolve<T = unknown>(token: unknown): Promise<T>;

package/dist/AuroraProvider.js

@@ -15,6 +15,7 @@
  * framework with a container — non-Ream hosts get the singleton bindings
  * and skip the route auto-registration silently.
  */
+import "./augmentations.js";
 import { isAbsolute, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AuroraManager } from "./AuroraManager.js";

package/dist/augmentations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
+ * tokens aurora binds.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the ones it owns. Nothing filled
+ * these in, so resolving by the string token answered `unknown` and every call
+ * site had to assert a type it could not prove.
+ *
+ * Loaded from the package barrel, so importing Aurora anywhere in the
+ * application is enough — nobody writes a `declare module` of their own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+import type { AuroraManager } from "./AuroraManager.js";
+declare module "@c9up/ream/types" {
+    interface ContainerBindings {
+        /** The Aurora manager, bound by `AuroraProvider`. */
+        aurora: AuroraManager;
+    }
+}

package/dist/augmentations.js

@@ -0,0 +1,17 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
+ * tokens aurora binds.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the ones it owns. Nothing filled
+ * these in, so resolving by the string token answered `unknown` and every call
+ * site had to assert a type it could not prove.
+ *
+ * Loaded from the package barrel, so importing Aurora anywhere in the
+ * application is enough — nobody writes a `declare module` of their own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+export {};

package/dist/browser.js

@@ -403,7 +403,7 @@ export const cookie = {
         if (typeof document === "undefined") {
             const scoped = cookieStoreReader?.();
             if (scoped && Object.hasOwn(scoped, name))
-                return scoped[name];
+                return scoped[name] ?? null;
             return cookieSeed[name] ?? null;
         }
         const prefix = `${encodeURIComponent(name)}=`;

package/dist/html.js

@@ -36,6 +36,10 @@ function classifySlots(strings) {
     let insideComment = false;
     for (let i = 0; i < strings.length - 1; i++) {
         const segment = strings[i];
+        // `i` is bounded by the loop; naming the miss is what carries that
+        // bound into the character scan below.
+        if (segment === undefined)
+            continue;
         for (let j = 0; j < segment.length; j++) {
             if (insideComment) {
                 // Comments swallow everything (including stray `<` / `>`) up
@@ -77,13 +81,10 @@ function classifySlots(strings) {
  * detects when scanning attribute values.
  */
 function buildMarkup(strings, classification) {
-    let out = strings[0];
-    for (let i = 0; i < classification.length; i++) {
-        out +=
-            classification[i].region === "text"
-                ? TEXT_NODE_MARKER
-                : attrPlaceholder(i);
-        out += strings[i + 1];
+    let out = strings[0] ?? "";
+    for (const [i, slot] of classification.entries()) {
+        out += slot.region === "text" ? TEXT_NODE_MARKER : attrPlaceholder(i);
+        out += strings[i + 1] ?? "";
     }
     return out;
 }
@@ -154,7 +155,7 @@ function collectSlots(root, classification) {
             const staticParts = [];
             const slotCountInThisAttr = (parts.length - 1) / 2;
             for (let i = 0; i < parts.length; i += 2) {
-                staticParts.push(parts[i]);
+                staticParts.push(parts[i] ?? "");
             }
             for (let i = 0; i < slotCountInThisAttr; i++) {
                 const slot = {
@@ -178,9 +179,9 @@ function collectSlots(root, classification) {
         if (node.nodeType === 8 /* Comment */) {
             const data = node.data;
             if (data === MARKER) {
-                if (slotIndex >= classification.length)
-                    return;
                 const cls = classification[slotIndex];
+                if (cls === undefined)
+                    return;
                 if (cls.region !== "text") {
                     throw new Error(`[aurora] internal classification mismatch at slot ${slotIndex}`);
                 }

package/dist/http.d.ts

@@ -15,7 +15,8 @@
  * Node-free and isomorphic — uses the global `fetch` (browsers, Node 18+,
  * Workers, Bun, Deno). Part of the client barrel.
  */
-export interface HttpClientOptions {
+import { type XsrfOptions } from "./xsrf.js";
+export interface HttpClientOptions extends XsrfOptions {
     /** Prepended to every request URL, unless the URL is already absolute. */
     baseURL?: string;
     /** Headers merged into every request. */
@@ -49,6 +50,12 @@ export interface HttpRequestOptions<T = unknown> {
     headers?: Record<string, string>;
     /** Per-request bearer token override (`null` to force-omit). */
     token?: string | null;
+    /**
+     * Turn the automatic `X-XSRF-TOKEN` header off for this request. Rarely
+     * needed: it is already a no-op cross-origin, outside a browser, and when
+     * the cookie is absent.
+     */
+    xsrf?: boolean;
     /** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
     signal?: AbortSignal;
     /** Per-request timeout in ms (overrides the client default). Aborts with a `TimeoutError`. */

package/dist/http.js

@@ -20,6 +20,7 @@
  * Node-free and isomorphic — uses the global `fetch` (browsers, Node 18+,
  * Workers, Bun, Deno). Part of the client barrel.
  */
+import { xsrfHeaderFor } from "./xsrf.js";
 /** Thrown on a non-2xx response. Carries the status, the `Response`, and the parsed body. */
 export class HttpError extends Error {
     status;
@@ -148,6 +149,7 @@ export class HttpClient {
     #credentials;
     #timeout;
     #allowCrossOriginAuth;
+    #xsrf;
     constructor(options = {}) {
         this.#baseURL = options.baseURL ?? "";
         this.#headers = { ...options.headers };
@@ -155,6 +157,11 @@ export class HttpClient {
         this.#credentials = options.credentials;
         this.#timeout = options.timeout;
         this.#allowCrossOriginAuth = options.allowCrossOriginAuth ?? false;
+        this.#xsrf = {
+            xsrf: options.xsrf,
+            xsrfCookieName: options.xsrfCookieName,
+            xsrfHeaderName: options.xsrfHeaderName,
+        };
     }
     /** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
     setHeader(name, value) {
@@ -282,6 +289,18 @@ export class HttpClient {
             (!crossOrigin || allowCrossOriginAuth)) {
             headers.Authorization = `Bearer ${token}`;
         }
+        // The client's half of the signed double-submit check. Same-origin only,
+        // and never over a header the caller set: an explicit value is intent.
+        const xsrf = xsrfHeaderFor(finalUrl, {
+            ...this.#xsrf,
+            xsrf: options.xsrf ?? this.#xsrf.xsrf,
+        });
+        if (xsrf !== undefined) {
+            for (const [name, value] of Object.entries(xsrf)) {
+                if (!hasHeader(headers, name))
+                    headers[name] = value;
+            }
+        }
         let payload;
         if (body !== undefined && body !== null) {
             if (shouldJsonEncode(body)) {

package/dist/hydrate.js

@@ -319,8 +319,7 @@ function hydrateTemplateResult(result, liveNodes, cleanups, mountHooks, markerCu
     // between. Binding each slot on its own would have the last writer win and
     // wipe the statics, which is what render.ts already avoids server-side.
     const multiGroups = new Map();
-    for (let i = 0; i < tpl.slots.length; i++) {
-        const slot = tpl.slots[i];
+    for (const [i, slot] of tpl.slots.entries()) {
         const liveNode = resolvePathLive(slot.path, liveNodes);
         if (!liveNode) {
             // Path missed in the live DOM — SSR markup diverges from the
@@ -421,10 +420,15 @@ function resolvePathLive(path, rootNodes) {
     // 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++) {
+    const [head, ...rest] = path;
+    if (head === undefined)
+        return null;
+    let node = children[head] ?? null;
+    for (const step of rest) {
+        if (!node)
+            break;
         children = collapseMarkerRanges(Array.from(node.childNodes));
-        node = children[path[i]] ?? null;
+        node = children[step] ?? null;
     }
     return node;
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import "./augmentations.js";
 export type { CookieCodec, CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
 export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { type ClassValue, clsx, cn, twMerge } from "./cn.js";

package/dist/index.js

@@ -1,3 +1,10 @@
+// ─── Client surface (node-free — safe to bundle for the browser) ──────
+//
+// Server-only exports (AuroraManager, Pages, renderPage, serveAssets) that pull
+// node:fs / node:path / node:url live in `@c9up/aurora/server`. Keeping them off
+// this barrel is what lets a browser bundle import the client primitives without
+// the bundler dragging Node built-ins through the import graph.
+import "./augmentations.js";
 export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { clsx, cn, twMerge } from "./cn.js";
 export { command } from "./command.js";

package/dist/liveClient.js

@@ -76,7 +76,14 @@ export function buildLiveTransport(relayClient, http, options = {}) {
     return {
         subscribe: (channel, handler) => relayClient.subscribe(channel, handler),
         post: (id, event, payload) => {
-            void http.post(path, { id, event, payload });
+            // A post that fails means the server never saw this interaction, so
+            // the component's server-side state and what the user is looking at
+            // have diverged — silence is the worst possible answer. Unhandled,
+            // it was also a bare `Uncaught (in promise)` with no clue which
+            // event was lost.
+            void (async () => http.post(path, { id, event, payload }))().catch((err) => {
+                console.warn(`[aurora/live] '${event}' on ${id} did not reach the server; this component is now out of sync:`, err);
+            });
         },
     };
 }

package/dist/relay.js

@@ -17,6 +17,7 @@
  * `@c9up/aurora`. Node-side code that pulls it will trip on
  * `EventSource` being undefined.
  */
+import { xsrfHeaderFor } from "./xsrf.js";
 const STATE = {
     sse: null,
     uid: null,
@@ -229,11 +230,11 @@ function postUnsubscribe(channel) {
 }
 /**
  * POST a `{ uid, channel }` handshake to a relay endpoint. Sends the
- * signed-CSRF trio blackhole expects: the `XSRF-TOKEN` cookie echoed as
- * the `X-XSRF-TOKEN` header plus `credentials: 'include'` so the cookie
+ * signed-CSRF trio the security layer expects: the `XSRF-TOKEN` cookie echoed
+ * as the `X-XSRF-TOKEN` header plus `credentials: 'include'` so the cookie
  * itself rides along. Without both, the POST is rejected by the signed
- * double-submit guard. Mirrors `HttpClient.#retrieveXsrfToken` /
- * `createRequest` in `@adonisjs/transmit-client`.
+ * double-submit guard. The header comes from the one reader in `xsrf.ts`,
+ * which `HttpClient` uses too.
  */
 async function postHandshake(url, channel) {
     const headers = {
@@ -241,9 +242,7 @@ async function postHandshake(url, channel) {
     };
     if (CONFIG.bearer)
         headers.authorization = `Bearer ${CONFIG.bearer}`;
-    const xsrf = retrieveXsrfToken();
-    if (xsrf !== null)
-        headers["x-xsrf-token"] = xsrf;
+    Object.assign(headers, xsrfHeaderFor(url) ?? {});
     const res = await fetch(url, {
         method: "POST",
         headers,
@@ -254,27 +253,6 @@ async function postHandshake(url, channel) {
         throw new Error(`HTTP ${res.status}`);
     }
 }
-/**
- * Read the `XSRF-TOKEN` cookie so it can be echoed as the `X-XSRF-TOKEN`
- * header (signed double-submit CSRF). Browser-only — returns `null` under
- * SSR / any environment without `document`.
- */
-function retrieveXsrfToken() {
-    if (typeof document === "undefined")
-        return null;
-    const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
-    if (!match)
-        return null;
-    try {
-        return decodeURIComponent(match[1]);
-    }
-    catch {
-        // A malformed cookie must not break subscribe/unsubscribe handshakes. The
-        // server will reject an invalid token normally; the client should not throw
-        // before it even sends the request.
-        return match[1];
-    }
-}
 function safeJson(raw) {
     if (typeof raw !== "string")
         return null;

package/dist/render.js

@@ -80,8 +80,7 @@ export function mount(result, cleanups, mounted, mountHooks) {
     // none, and silently never bound. Fragments exist precisely so a component
     // needs no wrapper element; they must not cost the slots that follow them.
     const resolved = tpl.slots.map((slot) => resolvePath(fragment, slot.path));
-    for (let i = 0; i < tpl.slots.length; i++) {
-        const slot = tpl.slots[i];
+    for (const [i, slot] of tpl.slots.entries()) {
         const node = resolved[i];
         if (node === null || node === undefined) {
             // Path didn't resolve — skip this binding rather than crash (see

package/dist/rpc.js

@@ -21,43 +21,25 @@
 import { createRpcClient as createCometRpcClient } from "@c9up/comet";
 import { HttpClient } from "./http.js";
 export { isRpcError, RpcError, } from "@c9up/comet";
-/**
- * Read a cookie's raw value from `document.cookie`. Returns `undefined`
- * server-side (no `document`) or when the cookie is absent. The value is sent
- * verbatim — double-submit compares it byte-for-byte against the cookie, so it
- * must not be decoded.
- */
-function readCookie(name) {
-    if (typeof document === "undefined")
-        return undefined;
-    const prefix = `${name}=`;
-    for (const part of document.cookie.split(";")) {
-        const trimmed = part.trimStart();
-        if (trimmed.startsWith(prefix))
-            return trimmed.slice(prefix.length);
-    }
-    return undefined;
-}
 /**
  * Create a JSON-RPC client bound to aurora's HttpClient transport. Inherits the
  * supplied (or a fresh) HttpClient's base URL, auth headers, and timeouts, and
  * (by default) auto-attaches the `X-XSRF-TOKEN` CSRF header from the cookie.
  */
 export function createRpcClient(options = {}) {
-    const http = options.http ?? new HttpClient({ headers: options.headers });
-    const xsrfEnabled = options.xsrf ?? true;
-    const cookieName = options.xsrfCookieName ?? "XSRF-TOKEN";
-    const headerName = options.xsrfHeaderName ?? "X-XSRF-TOKEN";
+    const http = options.http ??
+        new HttpClient({
+            headers: options.headers,
+            xsrf: options.xsrf,
+            xsrfCookieName: options.xsrfCookieName,
+            xsrfHeaderName: options.xsrfHeaderName,
+        });
     return createCometRpcClient({
         url: options.url,
-        transport: (url, body, { signal }) => {
-            let headers;
-            if (xsrfEnabled) {
-                const token = readCookie(cookieName);
-                if (token !== undefined)
-                    headers = { [headerName]: token };
-            }
-            return http.post(url, body, { signal, headers });
-        },
+        // The header comes from the transport, which attaches it for every
+        // request it sends. Adding it here as well meant a caller who passed
+        // their own `http` got a client that read the cookie and one that did
+        // not, depending on which constructor argument they used.
+        transport: (url, body, { signal }) => http.post(url, body, { signal, xsrf: options.xsrf }),
     });
 }

package/dist/ssr.js

@@ -45,19 +45,31 @@ function stringifyTemplateResult(result) {
     // the matching value, and consume the closing `"` from the next
     // segment. This three-step coordination is why the loop holds a
     // `pendingClosingQuote` flag.
-    let pendingClosingQuote = false;
+    // Which quote closes the directive currently being skipped, so the closing
+    // one consumed is the one that was opened. Undefined when none is pending.
+    let pendingClosingQuote;
     const scanner = new TagScanner();
-    for (let i = 0; i < strings.length; i++) {
-        let segment = strings[i];
-        if (pendingClosingQuote) {
-            segment = segment.replace(/^"/, "");
-            pendingClosingQuote = false;
+    for (const [i, raw] of strings.entries()) {
+        let segment = raw;
+        if (pendingClosingQuote !== undefined) {
+            segment =
+                pendingClosingQuote === '"'
+                    ? segment.replace(/^"/, "")
+                    : segment.replace(/^'/, "");
+            pendingClosingQuote = undefined;
         }
-        const directiveMatch = segment.match(/\s([@?.][\w-]+)="$/);
+        // Both quote styles. Matching only `="` left `@click='${handler}'`
+        // unrecognised, so the handler fell through to `stringifyValue`, which
+        // CALLED it — a client event handler running on the server, its return
+        // value written into the HTML, and any exception swallowed.
+        const directiveMatch = segment.match(/\s([@?.][\w-]+)=("|'|)$/);
         const skipValue = directiveMatch !== null;
         if (directiveMatch) {
-            segment = segment.slice(0, segment.length - directiveMatch[0].length);
-            pendingClosingQuote = true;
+            const [whole = "", , quote] = directiveMatch;
+            segment = segment.slice(0, segment.length - whole.length);
+            // Only a quoted directive leaves a closing quote to swallow.
+            pendingClosingQuote =
+                quote === '"' ? '"' : quote === "'" ? "'" : undefined;
         }
         out += segment;
         scanner.consume(segment);
@@ -147,10 +159,10 @@ function stringifyValue(value, inAttribute) {
     if (isSignal(value))
         return stringifyValue(value(), inAttribute);
     if (typeof value === "function") {
-        // In attribute position: directive handlers (`@click`, `?disabled`,
-        // `.prop`) have already been stripped by `stripDirectiveBefore`.
-        // A function reaching this point is a reactive-expression text
-        // slot (`${() => ...}`), which we evaluate eagerly server-side.
+        // A function here is a reactive expression — `class="${() => …}"` in an
+        // attribute, `${() => …}` in text — and is evaluated eagerly
+        // server-side. Directive values (`@click`, `?disabled`, `.prop`) never
+        // reach this point: the scanner skips them, whatever quoting they use.
         try {
             return stringifyValue(value(), inAttribute);
         }

package/dist/xsrf.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Echoing the CSRF cookie back as a header, in one place.
+ *
+ * The signed double-submit guard on the server reads `XSRF-TOKEN` from the
+ * cookie jar and compares it to `X-XSRF-TOKEN` on the request. A browser sends
+ * the cookie on its own; the header is the client's half, and it is the half
+ * that says "this request came from our own page", because a cross-site caller
+ * can cause the cookie to ride along but cannot read it.
+ *
+ * This lived three times over. `rpc.ts` and `relay.ts` each had a copy, and
+ * both described theirs as mirroring `HttpClient.#retrieveXsrfToken` — a method
+ * `HttpClient` never had. So the client the docs tell you to submit a form with
+ * sent no header at all, and every POST through it was refused the moment an
+ * application turned CSRF on. One reader now, used by all three.
+ */
+/** The cookie the server seeds. */
+export declare const XSRF_COOKIE_NAME = "XSRF-TOKEN";
+/** The header it is echoed in (the Axios/Angular convention the server reads). */
+export declare const XSRF_HEADER_NAME = "X-XSRF-TOKEN";
+/** Per-client switches for the automatic header. */
+export interface XsrfOptions {
+    /**
+     * Echo the CSRF cookie as a header on same-origin requests. Default `true`.
+     * A no-op outside a browser and when the cookie is absent — a bearer-authed
+     * API is CSRF-exempt and seeds no cookie, so nothing is sent there either.
+     */
+    xsrf?: boolean;
+    /** Cookie to read the token from. Default `XSRF-TOKEN`. */
+    xsrfCookieName?: string;
+    /** Header to echo it in. Default `X-XSRF-TOKEN`. */
+    xsrfHeaderName?: string;
+}
+/**
+ * Read a cookie's raw value from `document.cookie`.
+ *
+ * Verbatim, never decoded: the server compares the header to the cookie
+ * byte-for-byte. The token is hex + `.` + base64url, so there is nothing a
+ * decode could change — but a decode that ever did change something would turn
+ * a valid request into a rejected one, silently.
+ *
+ * Returns `undefined` server-side (no `document`) or when the cookie is absent.
+ */
+export declare function readXsrfCookie(name?: string): string | undefined;
+/**
+ * Is this URL served by the page's own origin?
+ *
+ * The question is not "does it match the client's baseURL" — a client whose
+ * baseURL IS a third-party API would pass that one. A CSRF token authenticates
+ * the page's session; sending it anywhere else hands a working token to whoever
+ * runs that host.
+ *
+ * A relative URL is same-origin by construction. Outside a browser there is no
+ * page and no cookie, so the answer is no.
+ */
+export declare function isSameOriginAsPage(url: string): boolean;
+/**
+ * The header to add for `url`, or `undefined` when there is nothing to send.
+ *
+ * Absent cookie, disabled, cross-origin target, or no browser: nothing. The
+ * caller merges the result rather than being handed an empty object, so a call
+ * site cannot accidentally overwrite a header it set itself.
+ */
+export declare function xsrfHeaderFor(url: string, options?: XsrfOptions): Record<string, string> | undefined;

package/dist/xsrf.js

@@ -0,0 +1,81 @@
+/// <reference lib="dom" />
+/**
+ * Echoing the CSRF cookie back as a header, in one place.
+ *
+ * The signed double-submit guard on the server reads `XSRF-TOKEN` from the
+ * cookie jar and compares it to `X-XSRF-TOKEN` on the request. A browser sends
+ * the cookie on its own; the header is the client's half, and it is the half
+ * that says "this request came from our own page", because a cross-site caller
+ * can cause the cookie to ride along but cannot read it.
+ *
+ * This lived three times over. `rpc.ts` and `relay.ts` each had a copy, and
+ * both described theirs as mirroring `HttpClient.#retrieveXsrfToken` — a method
+ * `HttpClient` never had. So the client the docs tell you to submit a form with
+ * sent no header at all, and every POST through it was refused the moment an
+ * application turned CSRF on. One reader now, used by all three.
+ */
+/** The cookie the server seeds. */
+export const XSRF_COOKIE_NAME = "XSRF-TOKEN";
+/** The header it is echoed in (the Axios/Angular convention the server reads). */
+export const XSRF_HEADER_NAME = "X-XSRF-TOKEN";
+/**
+ * Read a cookie's raw value from `document.cookie`.
+ *
+ * Verbatim, never decoded: the server compares the header to the cookie
+ * byte-for-byte. The token is hex + `.` + base64url, so there is nothing a
+ * decode could change — but a decode that ever did change something would turn
+ * a valid request into a rejected one, silently.
+ *
+ * Returns `undefined` server-side (no `document`) or when the cookie is absent.
+ */
+export function readXsrfCookie(name = XSRF_COOKIE_NAME) {
+    if (typeof document === "undefined")
+        return undefined;
+    const prefix = `${name}=`;
+    for (const part of document.cookie.split(";")) {
+        const trimmed = part.trimStart();
+        if (trimmed.startsWith(prefix))
+            return trimmed.slice(prefix.length);
+    }
+    return undefined;
+}
+/**
+ * Is this URL served by the page's own origin?
+ *
+ * The question is not "does it match the client's baseURL" — a client whose
+ * baseURL IS a third-party API would pass that one. A CSRF token authenticates
+ * the page's session; sending it anywhere else hands a working token to whoever
+ * runs that host.
+ *
+ * A relative URL is same-origin by construction. Outside a browser there is no
+ * page and no cookie, so the answer is no.
+ */
+export function isSameOriginAsPage(url) {
+    if (typeof window === "undefined")
+        return false;
+    if (!/^[a-z][a-z\d+\-.]*:\/\//i.test(url))
+        return true;
+    try {
+        return new URL(url).origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The header to add for `url`, or `undefined` when there is nothing to send.
+ *
+ * Absent cookie, disabled, cross-origin target, or no browser: nothing. The
+ * caller merges the result rather than being handed an empty object, so a call
+ * site cannot accidentally overwrite a header it set itself.
+ */
+export function xsrfHeaderFor(url, options = {}) {
+    if (options.xsrf === false)
+        return undefined;
+    if (!isSameOriginAsPage(url))
+        return undefined;
+    const token = readXsrfCookie(options.xsrfCookieName ?? XSRF_COOKIE_NAME);
+    if (token === undefined)
+        return undefined;
+    return { [options.xsrfHeaderName ?? XSRF_HEADER_NAME]: token };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.33",
+  "version": "0.1.36",
   "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",
@@ -56,12 +56,13 @@
     "@biomejs/biome": "^2.4.10",
     "@c9up/comet": "^0.1.0",
     "@types/node": "^22.19.15",
-    "@vitest/browser": "4.1.9",
-    "@vitest/browser-playwright": "4.1.9",
-    "happy-dom": "^15.11.7",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
+    "jsdom": "^30.0.1",
     "playwright": "^1.61.1",
     "typescript": "^6.0.2",
-    "vitest": "4.1.9"
+    "vitest": "4.1.9",
+    "@c9up/ream": "^0.2.0"
   },
   "files": [
     "LICENSE",

package/src/AuroraProvider.ts

@@ -16,6 +16,7 @@
  * and skip the route auto-registration silently.
  */
 
+import "./augmentations.js";
 import { isAbsolute, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";

package/src/augmentations.ts

@@ -0,0 +1,28 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make(...)` returns for the
+ * tokens aurora binds.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the ones it owns. Nothing filled
+ * these in, so resolving by the string token answered `unknown` and every call
+ * site had to assert a type it could not prove.
+ *
+ * Loaded from the package barrel, so importing Aurora anywhere in the
+ * application is enough — nobody writes a `declare module` of their own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+
+// Referenced so the augmentation below resolves the module it augments.
+import type {} from "@c9up/ream/types";
+
+import type { AuroraManager } from "./AuroraManager.js";
+
+declare module "@c9up/ream/types" {
+	interface ContainerBindings {
+		/** The Aurora manager, bound by `AuroraProvider`. */
+		aurora: AuroraManager;
+	}
+}

package/src/browser.ts

@@ -510,7 +510,7 @@ export const cookie = {
 	get(name: string): string | null {
 		if (typeof document === "undefined") {
 			const scoped = cookieStoreReader?.();
-			if (scoped && Object.hasOwn(scoped, name)) return scoped[name];
+			if (scoped && Object.hasOwn(scoped, name)) return scoped[name] ?? null;
 			return cookieSeed[name] ?? null;
 		}
 		const prefix = `${encodeURIComponent(name)}=`;

package/src/html.ts

@@ -64,6 +64,9 @@ function classifySlots(strings: readonly string[]): RawSlot[] {
 	let insideComment = false;
 	for (let i = 0; i < strings.length - 1; i++) {
 		const segment = strings[i];
+		// `i` is bounded by the loop; naming the miss is what carries that
+		// bound into the character scan below.
+		if (segment === undefined) continue;
 		for (let j = 0; j < segment.length; j++) {
 			if (insideComment) {
 				// Comments swallow everything (including stray `<` / `>`) up
@@ -111,13 +114,10 @@ function buildMarkup(
 	strings: readonly string[],
 	classification: readonly RawSlot[],
 ): string {
-	let out = strings[0];
-	for (let i = 0; i < classification.length; i++) {
-		out +=
-			classification[i].region === "text"
-				? TEXT_NODE_MARKER
-				: attrPlaceholder(i);
-		out += strings[i + 1];
+	let out = strings[0] ?? "";
+	for (const [i, slot] of classification.entries()) {
+		out += slot.region === "text" ? TEXT_NODE_MARKER : attrPlaceholder(i);
+		out += strings[i + 1] ?? "";
 	}
 	return out;
 }
@@ -195,7 +195,7 @@ function collectSlots(
 			const staticParts: string[] = [];
 			const slotCountInThisAttr = (parts.length - 1) / 2;
 			for (let i = 0; i < parts.length; i += 2) {
-				staticParts.push(parts[i]);
+				staticParts.push(parts[i] ?? "");
 			}
 			for (let i = 0; i < slotCountInThisAttr; i++) {
 				const slot: AttrSlot = {
@@ -220,8 +220,8 @@ function collectSlots(
 		if (node.nodeType === 8 /* Comment */) {
 			const data = (node as Comment).data;
 			if (data === MARKER) {
-				if (slotIndex >= classification.length) return;
 				const cls = classification[slotIndex];
+				if (cls === undefined) return;
 				if (cls.region !== "text") {
 					throw new Error(
 						`[aurora] internal classification mismatch at slot ${slotIndex}`,

package/src/http.ts

@@ -21,7 +21,9 @@
  * Workers, Bun, Deno). Part of the client barrel.
  */
 
-export interface HttpClientOptions {
+import { type XsrfOptions, xsrfHeaderFor } from "./xsrf.js";
+
+export interface HttpClientOptions extends XsrfOptions {
 	/** Prepended to every request URL, unless the URL is already absolute. */
 	baseURL?: string;
 	/** Headers merged into every request. */
@@ -56,6 +58,12 @@ export interface HttpRequestOptions<T = unknown> {
 	headers?: Record<string, string>;
 	/** Per-request bearer token override (`null` to force-omit). */
 	token?: string | null;
+	/**
+	 * Turn the automatic `X-XSRF-TOKEN` header off for this request. Rarely
+	 * needed: it is already a no-op cross-origin, outside a browser, and when
+	 * the cookie is absent.
+	 */
+	xsrf?: boolean;
 	/** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
 	signal?: AbortSignal;
 	/** Per-request timeout in ms (overrides the client default). Aborts with a `TimeoutError`. */
@@ -216,6 +224,7 @@ export class HttpClient {
 	readonly #credentials?: RequestCredentials;
 	readonly #timeout?: number;
 	readonly #allowCrossOriginAuth: boolean;
+	readonly #xsrf: XsrfOptions;
 
 	constructor(options: HttpClientOptions = {}) {
 		this.#baseURL = options.baseURL ?? "";
@@ -224,6 +233,11 @@ export class HttpClient {
 		this.#credentials = options.credentials;
 		this.#timeout = options.timeout;
 		this.#allowCrossOriginAuth = options.allowCrossOriginAuth ?? false;
+		this.#xsrf = {
+			xsrf: options.xsrf,
+			xsrfCookieName: options.xsrfCookieName,
+			xsrfHeaderName: options.xsrfHeaderName,
+		};
 	}
 
 	/** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
@@ -392,6 +406,18 @@ export class HttpClient {
 			headers.Authorization = `Bearer ${token}`;
 		}
 
+		// The client's half of the signed double-submit check. Same-origin only,
+		// and never over a header the caller set: an explicit value is intent.
+		const xsrf = xsrfHeaderFor(finalUrl, {
+			...this.#xsrf,
+			xsrf: options.xsrf ?? this.#xsrf.xsrf,
+		});
+		if (xsrf !== undefined) {
+			for (const [name, value] of Object.entries(xsrf)) {
+				if (!hasHeader(headers, name)) headers[name] = value;
+			}
+		}
+
 		let payload: BodyInit | undefined;
 		if (body !== undefined && body !== null) {
 			if (shouldJsonEncode(body)) {

package/src/hydrate.ts

@@ -416,8 +416,7 @@ function hydrateTemplateResult(
 	// wipe the statics, which is what render.ts already avoids server-side.
 	const multiGroups = new Map<string, MultiAttrGroup>();
 
-	for (let i = 0; i < tpl.slots.length; i++) {
-		const slot = tpl.slots[i];
+	for (const [i, slot] of tpl.slots.entries()) {
 		const liveNode = resolvePathLive(slot.path, liveNodes);
 		if (!liveNode) {
 			// Path missed in the live DOM — SSR markup diverges from the
@@ -554,10 +553,13 @@ function resolvePathLive(path: NodePath, rootNodes: ChildNode[]): Node | 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++) {
+	const [head, ...rest] = path;
+	if (head === undefined) return null;
+	let node: Node | null = children[head] ?? null;
+	for (const step of rest) {
+		if (!node) break;
 		children = collapseMarkerRanges(Array.from(node.childNodes));
-		node = children[path[i]] ?? null;
+		node = children[step] ?? null;
 	}
 	return node;
 }

package/src/index.ts

@@ -4,6 +4,8 @@
 // node:fs / node:path / node:url live in `@c9up/aurora/server`. Keeping them off
 // this barrel is what lets a browser bundle import the client primitives without
 // the bundler dragging Node built-ins through the import graph.
+import "./augmentations.js";
+
 export type {
 	CookieCodec,
 	CookieOptions,

package/src/liveClient.ts

@@ -118,7 +118,19 @@ export function buildLiveTransport(
 		subscribe: (channel, handler) =>
 			relayClient.subscribe<SlotPatch[]>(channel, handler),
 		post: (id, event, payload) => {
-			void http.post(path, { id, event, payload });
+			// A post that fails means the server never saw this interaction, so
+			// the component's server-side state and what the user is looking at
+			// have diverged — silence is the worst possible answer. Unhandled,
+			// it was also a bare `Uncaught (in promise)` with no clue which
+			// event was lost.
+			void (async () => http.post(path, { id, event, payload }))().catch(
+				(err: unknown) => {
+					console.warn(
+						`[aurora/live] '${event}' on ${id} did not reach the server; this component is now out of sync:`,
+						err,
+					);
+				},
+			);
 		},
 	};
 }

package/src/relay.ts

@@ -18,6 +18,8 @@
  * `EventSource` being undefined.
  */
 
+import { xsrfHeaderFor } from "./xsrf.js";
+
 /**
  * Connection lifecycle status. Mirrors `@adonisjs/transmit-client`'s
  * `TransmitStatus` (minus `initializing`, which the singleton never
@@ -313,19 +315,18 @@ function postUnsubscribe(channel: string): Promise<void> {
 
 /**
  * POST a `{ uid, channel }` handshake to a relay endpoint. Sends the
- * signed-CSRF trio blackhole expects: the `XSRF-TOKEN` cookie echoed as
- * the `X-XSRF-TOKEN` header plus `credentials: 'include'` so the cookie
+ * signed-CSRF trio the security layer expects: the `XSRF-TOKEN` cookie echoed
+ * as the `X-XSRF-TOKEN` header plus `credentials: 'include'` so the cookie
  * itself rides along. Without both, the POST is rejected by the signed
- * double-submit guard. Mirrors `HttpClient.#retrieveXsrfToken` /
- * `createRequest` in `@adonisjs/transmit-client`.
+ * double-submit guard. The header comes from the one reader in `xsrf.ts`,
+ * which `HttpClient` uses too.
  */
 async function postHandshake(url: string, channel: string): Promise<void> {
 	const headers: Record<string, string> = {
 		"content-type": "application/json",
 	};
 	if (CONFIG.bearer) headers.authorization = `Bearer ${CONFIG.bearer}`;
-	const xsrf = retrieveXsrfToken();
-	if (xsrf !== null) headers["x-xsrf-token"] = xsrf;
+	Object.assign(headers, xsrfHeaderFor(url) ?? {});
 	const res = await fetch(url, {
 		method: "POST",
 		headers,
@@ -337,25 +338,6 @@ async function postHandshake(url: string, channel: string): Promise<void> {
 	}
 }
 
-/**
- * Read the `XSRF-TOKEN` cookie so it can be echoed as the `X-XSRF-TOKEN`
- * header (signed double-submit CSRF). Browser-only — returns `null` under
- * SSR / any environment without `document`.
- */
-function retrieveXsrfToken(): string | null {
-	if (typeof document === "undefined") return null;
-	const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
-	if (!match) return null;
-	try {
-		return decodeURIComponent(match[1]);
-	} catch {
-		// A malformed cookie must not break subscribe/unsubscribe handshakes. The
-		// server will reject an invalid token normally; the client should not throw
-		// before it even sends the request.
-		return match[1];
-	}
-}
-
 function safeJson<T>(raw: unknown): T | null {
 	if (typeof raw !== "string") return null;
 	try {

package/src/render.ts

@@ -119,8 +119,7 @@ export function mount(
 		resolvePath(fragment, slot.path),
 	);
 
-	for (let i = 0; i < tpl.slots.length; i++) {
-		const slot = tpl.slots[i];
+	for (const [i, slot] of tpl.slots.entries()) {
 		const node = resolved[i];
 		if (node === null || node === undefined) {
 			// Path didn't resolve — skip this binding rather than crash (see

package/src/rpc.ts

@@ -54,41 +54,27 @@ export interface RpcClientOptions {
 	xsrfHeaderName?: string;
 }
 
-/**
- * Read a cookie's raw value from `document.cookie`. Returns `undefined`
- * server-side (no `document`) or when the cookie is absent. The value is sent
- * verbatim — double-submit compares it byte-for-byte against the cookie, so it
- * must not be decoded.
- */
-function readCookie(name: string): string | undefined {
-	if (typeof document === "undefined") return undefined;
-	const prefix = `${name}=`;
-	for (const part of document.cookie.split(";")) {
-		const trimmed = part.trimStart();
-		if (trimmed.startsWith(prefix)) return trimmed.slice(prefix.length);
-	}
-	return undefined;
-}
-
 /**
  * Create a JSON-RPC client bound to aurora's HttpClient transport. Inherits the
  * supplied (or a fresh) HttpClient's base URL, auth headers, and timeouts, and
  * (by default) auto-attaches the `X-XSRF-TOKEN` CSRF header from the cookie.
  */
 export function createRpcClient(options: RpcClientOptions = {}): RpcClient {
-	const http = options.http ?? new HttpClient({ headers: options.headers });
-	const xsrfEnabled = options.xsrf ?? true;
-	const cookieName = options.xsrfCookieName ?? "XSRF-TOKEN";
-	const headerName = options.xsrfHeaderName ?? "X-XSRF-TOKEN";
+	const http =
+		options.http ??
+		new HttpClient({
+			headers: options.headers,
+			xsrf: options.xsrf,
+			xsrfCookieName: options.xsrfCookieName,
+			xsrfHeaderName: options.xsrfHeaderName,
+		});
 	return createCometRpcClient({
 		url: options.url,
-		transport: (url, body, { signal }) => {
-			let headers: Record<string, string> | undefined;
-			if (xsrfEnabled) {
-				const token = readCookie(cookieName);
-				if (token !== undefined) headers = { [headerName]: token };
-			}
-			return http.post<unknown>(url, body, { signal, headers });
-		},
+		// The header comes from the transport, which attaches it for every
+		// request it sends. Adding it here as well meant a caller who passed
+		// their own `http` got a client that read the cookie and one that did
+		// not, depending on which constructor argument they used.
+		transport: (url, body, { signal }) =>
+			http.post<unknown>(url, body, { signal, xsrf: options.xsrf }),
 	});
 }

package/src/ssr.ts

@@ -49,19 +49,31 @@ function stringifyTemplateResult(result: TemplateResult): string {
 	// the matching value, and consume the closing `"` from the next
 	// segment. This three-step coordination is why the loop holds a
 	// `pendingClosingQuote` flag.
-	let pendingClosingQuote = false;
+	// Which quote closes the directive currently being skipped, so the closing
+	// one consumed is the one that was opened. Undefined when none is pending.
+	let pendingClosingQuote: '"' | "'" | undefined;
 	const scanner = new TagScanner();
-	for (let i = 0; i < strings.length; i++) {
-		let segment = strings[i];
-		if (pendingClosingQuote) {
-			segment = segment.replace(/^"/, "");
-			pendingClosingQuote = false;
+	for (const [i, raw] of strings.entries()) {
+		let segment = raw;
+		if (pendingClosingQuote !== undefined) {
+			segment =
+				pendingClosingQuote === '"'
+					? segment.replace(/^"/, "")
+					: segment.replace(/^'/, "");
+			pendingClosingQuote = undefined;
 		}
-		const directiveMatch = segment.match(/\s([@?.][\w-]+)="$/);
+		// Both quote styles. Matching only `="` left `@click='${handler}'`
+		// unrecognised, so the handler fell through to `stringifyValue`, which
+		// CALLED it — a client event handler running on the server, its return
+		// value written into the HTML, and any exception swallowed.
+		const directiveMatch = segment.match(/\s([@?.][\w-]+)=("|'|)$/);
 		const skipValue = directiveMatch !== null;
 		if (directiveMatch) {
-			segment = segment.slice(0, segment.length - directiveMatch[0].length);
-			pendingClosingQuote = true;
+			const [whole = "", , quote] = directiveMatch;
+			segment = segment.slice(0, segment.length - whole.length);
+			// Only a quoted directive leaves a closing quote to swallow.
+			pendingClosingQuote =
+				quote === '"' ? '"' : quote === "'" ? "'" : undefined;
 		}
 		out += segment;
 		scanner.consume(segment);
@@ -148,10 +160,10 @@ function stringifyValue(value: unknown, inAttribute: boolean): string {
 	if (value === true) return inAttribute ? "" : "true";
 	if (isSignal(value)) return stringifyValue(value(), inAttribute);
 	if (typeof value === "function") {
-		// In attribute position: directive handlers (`@click`, `?disabled`,
-		// `.prop`) have already been stripped by `stripDirectiveBefore`.
-		// A function reaching this point is a reactive-expression text
-		// slot (`${() => ...}`), which we evaluate eagerly server-side.
+		// A function here is a reactive expression — `class="${() => …}"` in an
+		// attribute, `${() => …}` in text — and is evaluated eagerly
+		// server-side. Directive values (`@click`, `?disabled`, `.prop`) never
+		// reach this point: the scanner skips them, whatever quoting they use.
 		try {
 			return stringifyValue((value as () => unknown)(), inAttribute);
 		} catch {

package/src/xsrf.ts

@@ -0,0 +1,97 @@
+/// <reference lib="dom" />
+/**
+ * Echoing the CSRF cookie back as a header, in one place.
+ *
+ * The signed double-submit guard on the server reads `XSRF-TOKEN` from the
+ * cookie jar and compares it to `X-XSRF-TOKEN` on the request. A browser sends
+ * the cookie on its own; the header is the client's half, and it is the half
+ * that says "this request came from our own page", because a cross-site caller
+ * can cause the cookie to ride along but cannot read it.
+ *
+ * This lived three times over. `rpc.ts` and `relay.ts` each had a copy, and
+ * both described theirs as mirroring `HttpClient.#retrieveXsrfToken` — a method
+ * `HttpClient` never had. So the client the docs tell you to submit a form with
+ * sent no header at all, and every POST through it was refused the moment an
+ * application turned CSRF on. One reader now, used by all three.
+ */
+
+/** The cookie the server seeds. */
+export const XSRF_COOKIE_NAME = "XSRF-TOKEN";
+
+/** The header it is echoed in (the Axios/Angular convention the server reads). */
+export const XSRF_HEADER_NAME = "X-XSRF-TOKEN";
+
+/** Per-client switches for the automatic header. */
+export interface XsrfOptions {
+	/**
+	 * Echo the CSRF cookie as a header on same-origin requests. Default `true`.
+	 * A no-op outside a browser and when the cookie is absent — a bearer-authed
+	 * API is CSRF-exempt and seeds no cookie, so nothing is sent there either.
+	 */
+	xsrf?: boolean;
+	/** Cookie to read the token from. Default `XSRF-TOKEN`. */
+	xsrfCookieName?: string;
+	/** Header to echo it in. Default `X-XSRF-TOKEN`. */
+	xsrfHeaderName?: string;
+}
+
+/**
+ * Read a cookie's raw value from `document.cookie`.
+ *
+ * Verbatim, never decoded: the server compares the header to the cookie
+ * byte-for-byte. The token is hex + `.` + base64url, so there is nothing a
+ * decode could change — but a decode that ever did change something would turn
+ * a valid request into a rejected one, silently.
+ *
+ * Returns `undefined` server-side (no `document`) or when the cookie is absent.
+ */
+export function readXsrfCookie(
+	name: string = XSRF_COOKIE_NAME,
+): string | undefined {
+	if (typeof document === "undefined") return undefined;
+	const prefix = `${name}=`;
+	for (const part of document.cookie.split(";")) {
+		const trimmed = part.trimStart();
+		if (trimmed.startsWith(prefix)) return trimmed.slice(prefix.length);
+	}
+	return undefined;
+}
+
+/**
+ * Is this URL served by the page's own origin?
+ *
+ * The question is not "does it match the client's baseURL" — a client whose
+ * baseURL IS a third-party API would pass that one. A CSRF token authenticates
+ * the page's session; sending it anywhere else hands a working token to whoever
+ * runs that host.
+ *
+ * A relative URL is same-origin by construction. Outside a browser there is no
+ * page and no cookie, so the answer is no.
+ */
+export function isSameOriginAsPage(url: string): boolean {
+	if (typeof window === "undefined") return false;
+	if (!/^[a-z][a-z\d+\-.]*:\/\//i.test(url)) return true;
+	try {
+		return new URL(url).origin === window.location.origin;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The header to add for `url`, or `undefined` when there is nothing to send.
+ *
+ * Absent cookie, disabled, cross-origin target, or no browser: nothing. The
+ * caller merges the result rather than being handed an empty object, so a call
+ * site cannot accidentally overwrite a header it set itself.
+ */
+export function xsrfHeaderFor(
+	url: string,
+	options: XsrfOptions = {},
+): Record<string, string> | undefined {
+	if (options.xsrf === false) return undefined;
+	if (!isSameOriginAsPage(url)) return undefined;
+	const token = readXsrfCookie(options.xsrfCookieName ?? XSRF_COOKIE_NAME);
+	if (token === undefined) return undefined;
+	return { [options.xsrfHeaderName ?? XSRF_HEADER_NAME]: token };
+}