@c9up/aurora 0.1.34 → 0.1.37

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,43 @@
+/**
+ * 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";
+import type { AuroraRequestRenderer } from "./middleware.js";
+declare module "@c9up/ream/types" {
+    interface ContainerBindings {
+        /** The Aurora manager, bound by `AuroraProvider`. */
+        aurora: AuroraManager;
+    }
+}
+declare module "@c9up/ream" {
+    interface HttpContext {
+        /**
+         * Render a page for THIS request — `ctx.aurora.render(name, props)`.
+         *
+         * Attached by the `auroraContext` middleware, which is what the docs tell
+         * an application to register. Without this declaration the property the
+         * middleware sets did not exist as far as the compiler was concerned, so
+         * the shorthand the documentation teaches did not typecheck, and a
+         * controller had to reach for the module-level `aurora.render(ctx, ...)`
+         * or assert its way past it.
+         *
+         * Optional, because the middleware is: an application that never
+         * registers it has no `ctx.aurora`, and saying otherwise would let a
+         * controller call something that is not there.
+         */
+        aurora?: AuroraRequestRenderer;
+    }
+}

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}`);
                 }
@@ -215,11 +216,90 @@ function collectSlots(root, classification) {
     visit(root.content, []);
     return slots;
 }
+/**
+ * Elements that only ever exist inside `<svg>`.
+ *
+ * Names shared with HTML — `a`, `title`, `style`, `script`, `text` in some
+ * dialects — are deliberately absent: seeing one says nothing about which
+ * namespace was meant, and guessing wrong would move an ordinary anchor into
+ * SVG.
+ */
+const SVG_ONLY = new Set([
+    "animate",
+    "animatemotion",
+    "animatetransform",
+    "circle",
+    "clippath",
+    "defs",
+    "desc",
+    "ellipse",
+    "feblend",
+    "fecolormatrix",
+    "fegaussianblur",
+    "femerge",
+    "feoffset",
+    "filter",
+    "foreignobject",
+    "g",
+    "image",
+    "line",
+    "lineargradient",
+    "marker",
+    "mask",
+    "path",
+    "pattern",
+    "polygon",
+    "polyline",
+    "radialgradient",
+    "rect",
+    "stop",
+    "svg",
+    "symbol",
+    "tspan",
+    "use",
+]);
+/**
+ * Whether this markup is SVG content that lost its `<svg>` ancestor.
+ *
+ * A template compiled on its own — `html\`<path/><path/>\``, the body of an
+ * icon helper — is parsed with no parent, and the HTML parser has no
+ * self-closing tag for an unknown element: the second `<path>` becomes a CHILD
+ * of the first, in the XHTML namespace. Nothing throws and nothing is logged;
+ * the icon is simply invisible, because `<path>` in the wrong namespace paints
+ * nothing. Parsing the same markup inside an `<svg>` makes the parser apply
+ * foreign-content rules and produce the two siblings that were written.
+ *
+ * `<svg>` itself is excluded: the parser already handles it when it is the root
+ * of the markup, and wrapping one in another would nest them.
+ */
+function isOrphanedSvgContent(root) {
+    const elements = Array.from(root.content.childNodes).filter((node) => node.nodeType === 1);
+    if (elements.length === 0)
+        return false;
+    return elements.every((el) => {
+        const name = el.localName.toLowerCase();
+        return name !== "svg" && SVG_ONLY.has(name);
+    });
+}
 function compile(strings) {
     const classification = classifySlots(strings);
     const markup = buildMarkup(strings, classification);
-    const tpl = document.createElement("template");
+    let tpl = document.createElement("template");
     tpl.innerHTML = markup;
+    if (isOrphanedSvgContent(tpl)) {
+        // Re-parsed with the ancestor the markup was written for, then lifted
+        // back out: the nodes keep the SVG namespace they were given, and the
+        // slot paths below are collected against the shape that will actually
+        // be cloned.
+        const wrapper = document.createElement("template");
+        wrapper.innerHTML = `<svg>${markup}</svg>`;
+        const svg = wrapper.content.firstElementChild;
+        if (svg !== null) {
+            tpl = document.createElement("template");
+            while (svg.firstChild)
+                tpl.content.appendChild(svg.firstChild);
+        }
+    }
     const slots = collectSlots(tpl, classification);
     return { element: tpl, slots };
 }

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/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

@@ -49,8 +49,8 @@ function stringifyTemplateResult(result) {
     // 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];
+    for (const [i, raw] of strings.entries()) {
+        let segment = raw;
         if (pendingClosingQuote !== undefined) {
             segment =
                 pendingClosingQuote === '"'
@@ -64,18 +64,37 @@ function stringifyTemplateResult(result) {
         // value written into the HTML, and any exception swallowed.
         const directiveMatch = segment.match(/\s([@?.][\w-]+)=("|'|)$/);
         const skipValue = directiveMatch !== null;
+        // Set when the skipped directive is a boolean attribute, which — unlike
+        // the other two — still has markup to emit. See below.
+        let booleanAttrName;
         if (directiveMatch) {
-            segment = segment.slice(0, segment.length - directiveMatch[0].length);
+            const [whole = "", directive = "", quote] = directiveMatch;
+            segment = segment.slice(0, segment.length - whole.length);
+            // `?disabled=${x}` is HTML STATE, not a client-only binding.
+            // `@click` is a listener and `.value` a DOM property: neither
+            // exists until the runtime binds it, so dropping them is right.
+            // A boolean attribute is different — the browser acts on it while
+            // parsing. Skipping it too made the server contradict the very
+            // first client render: a `?hidden` panel arrived visible and
+            // blinked away once hydration caught up.
+            if (directive.startsWith("?"))
+                booleanAttrName = directive.slice(1);
             // Only a quoted directive leaves a closing quote to swallow.
             pendingClosingQuote =
-                directiveMatch[2] === '"'
-                    ? '"'
-                    : directiveMatch[2] === "'"
-                        ? "'"
-                        : undefined;
+                quote === '"' ? '"' : quote === "'" ? "'" : undefined;
         }
         out += segment;
         scanner.consume(segment);
+        if (booleanAttrName !== undefined && i < values.length) {
+            // Present-and-empty when truthy, absent otherwise — byte-for-byte
+            // what applyBooleanAttrSlot writes on the client, so hydration
+            // re-applying the effect is a no-op instead of a correction.
+            if (resolveBooleanValue(values[i])) {
+                const rendered = ` ${booleanAttrName}=""`;
+                out += rendered;
+                scanner.consume(rendered);
+            }
+        }
         if (i < values.length && !skipValue) {
             const value = values[i];
             const inAttr = scanner.insideTag;
@@ -154,6 +173,26 @@ class TagScanner {
         return this.#inTag;
     }
 }
+/**
+ * Read a boolean attribute's value the way the client reads it: a signal or a
+ * reactive expression is called ONCE, then coerced. One level is not an
+ * approximation — `applyBooleanAttrSlot` does exactly the same, so a signal
+ * that returns a signal is truthy on both sides.
+ */
+function resolveBooleanValue(value) {
+    if (isSignal(value) || typeof value === "function") {
+        try {
+            return Boolean(value());
+        }
+        catch {
+            // Same fail-soft as stringifyValue: an expression that throws
+            // server-side leaves the attribute off and lets the client effect
+            // decide once it has a real DOM to read.
+            return false;
+        }
+    }
+    return Boolean(value);
+}
 function stringifyValue(value, inAttribute) {
     if (value === null || value === undefined || value === false)
         return "";

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;