@c9up/aurora 0.1.20 → 0.1.22

package/dist/AuroraManager.d.ts

@@ -33,7 +33,7 @@ export interface AuroraManagerConfig {
      * URL prefix the asset routes mount under. The aurora runtime is served
      * from `<assetsPrefix>/aurora/*` and the app's pages from
      * `<assetsPrefix>/pages/*`, and the SSR importmap + page URLs derive from
-     * it. Default `/_assets` (the leading underscore namespaces framework
+     * it. Default `/__assets` (the leading underscore namespaces framework
      * assets away from app routes, Next.js `/_next` style). Set e.g. `/assets`
      * for an underscore-free scheme. An explicit `pages.urlPrefix` still wins.
      */
@@ -44,7 +44,7 @@ export interface AuroraManagerConfig {
      * importmaps). Merged over aurora's auto defaults (`@c9up/aurora`,
      * `@c9up/aurora/rpc`, `@c9up/comet`) on every `render()`. Use to point a bare
      * specifier at a curated browser entry, e.g.
-     * `{ '@c9up/aurora': '/_assets/pages/browser/aurora.js' }`. A per-call
+     * `{ '@c9up/aurora': '/__assets/pages/browser/aurora.js' }`. A per-call
      * `render(..., { importmap })` still wins over this.
      *
      * (Importmaps are aurora's no-bundler particularity — AdonisJS bundles via Vite
@@ -55,7 +55,7 @@ export interface AuroraManagerConfig {
 export declare class AuroraManager {
     readonly pages: Pages;
     readonly auroraDistRoot: string;
-    /** Resolved asset prefix (default `/_assets`). */
+    /** Resolved asset prefix (default `/__assets`). */
     readonly assetsPrefix: string;
     /** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
     readonly auroraAssetPath: string;
@@ -78,12 +78,12 @@ export declare class AuroraManager {
     render(ctx: RenderHttpContext, name: string, props: unknown, options?: RenderPageOptions): Promise<void>;
     /**
      * Handler for aurora's pre-built ESM runtime. Mount on
-     * `GET /_assets/aurora/*`.
+     * `GET /__assets/aurora/*`.
      */
     auroraAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void>;
     /**
      * Handler for the app's pages directory. Mount on
-     * `GET /_assets/pages/*`.
+     * `GET /__assets/pages/*`.
      */
     pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void>;
     /**

package/dist/AuroraManager.js

@@ -38,7 +38,7 @@ function normalizePrefix(prefix) {
 export class AuroraManager {
     pages;
     auroraDistRoot;
-    /** Resolved asset prefix (default `/_assets`). */
+    /** Resolved asset prefix (default `/__assets`). */
     assetsPrefix;
     /** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
     auroraAssetPath;
@@ -51,7 +51,7 @@ export class AuroraManager {
     /** App-level importmap overrides from `config/aurora.ts`, merged on render. */
     importmap;
     constructor(config) {
-        this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
+        this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/__assets");
         this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
         this.pageAssetPath = `${this.assetsPrefix}/pages`;
         this.cometAssetPath = `${this.assetsPrefix}/comet`;
@@ -97,14 +97,14 @@ export class AuroraManager {
     }
     /**
      * Handler for aurora's pre-built ESM runtime. Mount on
-     * `GET /_assets/aurora/*`.
+     * `GET /__assets/aurora/*`.
      */
     auroraAssetsHandler() {
         return serveAssets({ root: this.auroraDistRoot });
     }
     /**
      * Handler for the app's pages directory. Mount on
-     * `GET /_assets/pages/*`.
+     * `GET /__assets/pages/*`.
      */
     pageAssetsHandler() {
         return serveAssets({ root: this.pages.root });

package/dist/AuroraProvider.d.ts

@@ -2,8 +2,8 @@
  * AuroraProvider — registers the AuroraManager singleton and auto-mounts
  * the two asset routes the browser needs:
  *
- *   GET /_assets/aurora/*  → packages/@c9up/aurora/dist/*
- *   GET /_assets/pages/*   → resources/pages/*
+ *   GET /__assets/aurora/*  → packages/@c9up/aurora/dist/*
+ *   GET /__assets/pages/*   → resources/pages/*
  *
  * Config (in `config/aurora.ts`):
  *

package/dist/AuroraProvider.js

@@ -2,8 +2,8 @@
  * AuroraProvider — registers the AuroraManager singleton and auto-mounts
  * the two asset routes the browser needs:
  *
- *   GET /_assets/aurora/*  → packages/@c9up/aurora/dist/*
- *   GET /_assets/pages/*   → resources/pages/*
+ *   GET /__assets/aurora/*  → packages/@c9up/aurora/dist/*
+ *   GET /__assets/pages/*   → resources/pages/*
  *
  * Config (in `config/aurora.ts`):
  *
@@ -64,7 +64,7 @@ export default class AuroraProvider {
         const router = this.app.container.resolve("router");
         const manager = this.app.container.resolve(AuroraManager);
         // Mount paths derive from the configured `assetsPrefix` (default
-        // `/_assets`) — set `config.aurora.assetsPrefix` to change the scheme.
+        // `/__assets`) — set `config.aurora.assetsPrefix` to change the scheme.
         router.get(`${manager.auroraAssetPath}/*`, adaptHandler(manager.auroraAssetsHandler()));
         router.get(`${manager.pageAssetPath}/*`, adaptHandler(manager.pageAssetsHandler()));
         // Serve @c9up/comet's runtime so the RPC client's bare `import

package/dist/Pages.d.ts

@@ -25,7 +25,7 @@ export interface PagesConfig {
     root: string;
     /**
      * URL prefix the browser uses to fetch a page's compiled JS.
-     * Defaults to `/_assets/pages`. A name `"Foo"` maps to
+     * Defaults to `/__assets/pages`. A name `"Foo"` maps to
      * `${urlPrefix}/Foo.js`.
      */
     urlPrefix?: string;

package/dist/Pages.js

@@ -29,7 +29,7 @@ export class Pages {
     registry = new Map();
     constructor(config) {
         this.root = config.root;
-        this.urlPrefix = (config.urlPrefix ?? "/_assets/pages").replace(/\/$/, "");
+        this.urlPrefix = (config.urlPrefix ?? "/__assets/pages").replace(/\/$/, "");
         this.extension = config.extension ?? ".js";
     }
     /**

package/dist/browser.d.ts

@@ -31,10 +31,14 @@ export interface WebStorageOptions {
     area?: StorageArea;
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -45,13 +49,31 @@ export declare class WebStorage {
     constructor(options?: WebStorageOptions);
     /** The on-disk key for `key`, namespaced by the configured prefix. */
     fullKey(key: string): string;
-    get<T>(key: string): T | null;
-    set(key: string, value: unknown): void;
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
+    get(key: string): string | null;
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
+    set(key: string, value: string): void;
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON<T>(key: string): T | null;
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key: string, value: unknown): void;
     /** Whether `key` is present (and not the server). */
     has(key: string): boolean;
     remove(key: string): void;
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-    getOrSet<T>(key: string, factory: () => T): T;
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+    getOrSet(key: string, factory: () => string): string;
     /** Keys in this store, prefix stripped. Empty array during SSR. */
     keys(): string[];
     /** Remove this store's keys. With no prefix this clears the whole area. */

package/dist/browser.js

@@ -29,10 +29,14 @@ export function reload() {
     }
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -56,31 +60,53 @@ export class WebStorage {
     fullKey(key) {
         return this.#prefix + key;
     }
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
     get(key) {
         const backend = this.#backend();
         if (!backend)
             return null;
-        const raw = backend.getItem(this.fullKey(key));
-        if (raw === null)
-            return null;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
+        return backend.getItem(this.fullKey(key));
     }
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
     set(key, value) {
         const backend = this.#backend();
         if (!backend)
             return;
         try {
-            backend.setItem(this.fullKey(key), JSON.stringify(value));
+            backend.setItem(this.fullKey(key), value);
         }
         catch {
             // QuotaExceededError / Safari private mode — best-effort write.
         }
     }
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON(key) {
+        const raw = this.get(key);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key, value) {
+        this.set(key, JSON.stringify(value));
+    }
     /** Whether `key` is present (and not the server). */
     has(key) {
         const backend = this.#backend();
@@ -91,7 +117,7 @@ export class WebStorage {
     remove(key) {
         this.#backend()?.removeItem(this.fullKey(key));
     }
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
     getOrSet(key, factory) {
         const existing = this.get(key);
         if (existing !== null)
@@ -148,11 +174,12 @@ export const session = new WebStorage({ area: "session" });
  */
 export function persistedSignal(key, initial, options = {}) {
     const store = new WebStorage(options);
-    const stored = store.get(key);
+    const stored = store.getJSON(key);
     const sig = signal(stored !== null ? stored : initial);
     // Mirror every change back to storage; runs once immediately, then on change.
+    // JSON so any T (object, number, boolean, string) round-trips.
     effect(() => {
-        store.set(key, sig());
+        store.setJSON(key, sig());
     });
     if ((options.crossTab ?? true) &&
         (options.area ?? "local") === "local" &&

package/dist/liveClient.d.ts

@@ -61,7 +61,7 @@ export interface LiveHttpPoster {
 /**
  * Build a {@link LiveClientTransport} from a relay client (SSE down) + an HTTP
  * client (events up). `path` must match the server's `wireLiveEvents` route
- * (default `/_live/event`). Keeps `liveClient` itself transport-agnostic.
+ * (default `/__live/event`). Keeps `liveClient` itself transport-agnostic.
  *
  * @example
  *   import { relay } from '@c9up/aurora/relay'

package/dist/liveClient.js

@@ -58,7 +58,7 @@ export function liveClient(opts) {
 /**
  * Build a {@link LiveClientTransport} from a relay client (SSE down) + an HTTP
  * client (events up). `path` must match the server's `wireLiveEvents` route
- * (default `/_live/event`). Keeps `liveClient` itself transport-agnostic.
+ * (default `/__live/event`). Keeps `liveClient` itself transport-agnostic.
  *
  * @example
  *   import { relay } from '@c9up/aurora/relay'
@@ -67,7 +67,7 @@ export function liveClient(opts) {
  *   liveClient({ container, factory, mount, transport })
  */
 export function buildLiveTransport(relayClient, http, options = {}) {
-    const path = options.path ?? "/_live/event";
+    const path = options.path ?? "/__live/event";
     return {
         subscribe: (channel, handler) => relayClient.subscribe(channel, handler),
         post: (id, event, payload) => {

package/dist/liveServer.d.ts

@@ -29,7 +29,7 @@ export interface WireLiveEventsOptions {
     path?: string;
 }
 /** Default inbound-event route — keep the client transport's `path` in sync. */
-export declare const DEFAULT_LIVE_EVENT_PATH = "/_live/event";
+export declare const DEFAULT_LIVE_EVENT_PATH = "/__live/event";
 /**
  * Register the inbound live-event route on the host router. Call once at boot
  * (e.g. from a provider that resolved the router + relay from the container).

package/dist/liveServer.js

@@ -18,7 +18,7 @@ function isLiveEventBody(value) {
     return typeof value.id === "string" && typeof value.event === "string";
 }
 /** Default inbound-event route — keep the client transport's `path` in sync. */
-export const DEFAULT_LIVE_EVENT_PATH = "/_live/event";
+export const DEFAULT_LIVE_EVENT_PATH = "/__live/event";
 /**
  * Register the inbound live-event route on the host router. Call once at boot
  * (e.g. from a provider that resolved the router + relay from the container).

package/dist/rpc.d.ts

@@ -8,9 +8,23 @@ export interface RpcClientOptions {
     http?: HttpClient;
     /** Default headers — only used when no `http` client is supplied. */
     headers?: Record<string, string>;
+    /**
+     * Auto CSRF: read the `XSRF-TOKEN` cookie and echo it as `X-XSRF-TOKEN` on
+     * every call (Axios/Angular convention), so RPC POSTs pass blackhole's
+     * signed double-submit check when the route is cookie/session-authed. No-op
+     * outside the browser and when the cookie is absent. Default `true`.
+     * `/rpc` under a bearer (JWT) guard is CSRF-exempt, so the missing-cookie
+     * no-op is exactly right there too.
+     */
+    xsrf?: boolean;
+    /** Cookie to read the CSRF token from. Default `XSRF-TOKEN`. */
+    xsrfCookieName?: string;
+    /** Header to echo the CSRF token in. Default `X-XSRF-TOKEN`. */
+    xsrfHeaderName?: string;
 }
 /**
  * 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.
+ * 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 declare function createRpcClient(options?: RpcClientOptions): RpcClient;

package/dist/rpc.js

@@ -16,14 +16,43 @@
 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.
+ * 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";
     return createCometRpcClient({
         url: options.url,
-        transport: (url, body, { signal }) => http.post(url, body, { signal }),
+        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 });
+        },
     });
 }

package/dist/server/renderPage.d.ts

@@ -8,7 +8,7 @@
  *   <head>
  *     ...
  *     <script type="importmap">
- *       { "imports": { "@c9up/aurora": "/_assets/aurora/index.js" } }
+ *       { "imports": { "@c9up/aurora": "/__assets/aurora/index.js" } }
  *     </script>
  *   </head>
  *   <body>
@@ -16,7 +16,7 @@
  *     <script id="aurora-page-data" type="application/json">{…}</script>
  *     <script type="module">
  *       import { hydrate } from '@c9up/aurora'
- *       import Page from '/_assets/pages/ProjectPage.js'
+ *       import Page from '/__assets/pages/ProjectPage.js'
  *       const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
  *       hydrate(document.getElementById('aurora-root'), () => Page(data.props))
  *     </script>
@@ -39,7 +39,7 @@ export interface RenderHttpContext {
 export interface RenderPageOptions {
     /**
      * Importmap entries injected into `<head>`. Defaults to mapping
-     * `@c9up/aurora` to `/_assets/aurora/index.js`. Override to point
+     * `@c9up/aurora` to `/__assets/aurora/index.js`. Override to point
      * at a different mount or to add app-side aliases.
      */
     importmap?: Record<string, string>;

package/dist/server/renderPage.js

@@ -8,7 +8,7 @@
  *   <head>
  *     ...
  *     <script type="importmap">
- *       { "imports": { "@c9up/aurora": "/_assets/aurora/index.js" } }
+ *       { "imports": { "@c9up/aurora": "/__assets/aurora/index.js" } }
  *     </script>
  *   </head>
  *   <body>
@@ -16,7 +16,7 @@
  *     <script id="aurora-page-data" type="application/json">{…}</script>
  *     <script type="module">
  *       import { hydrate } from '@c9up/aurora'
- *       import Page from '/_assets/pages/ProjectPage.js'
+ *       import Page from '/__assets/pages/ProjectPage.js'
  *       const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
  *       hydrate(document.getElementById('aurora-root'), () => Page(data.props))
  *     </script>
@@ -58,7 +58,7 @@ export async function renderPage(ctx, pages, name, props, options = {}) {
     const tree = await factory(props);
     const body = renderToString(tree);
     const importmap = {
-        "@c9up/aurora": "/_assets/aurora/index.js",
+        "@c9up/aurora": "/__assets/aurora/index.js",
         ...options.importmap,
     };
     const rootId = options.rootId ?? "aurora-root";

package/dist/server/serveAssets.d.ts

@@ -2,8 +2,8 @@
  * `serveAssets` — generic static-file handler exposed by aurora so an
  * app can mount the runtime + the pages dist with a couple of routes:
  *
- *   router.get('/_assets/aurora/*', serveAssets({ root: auroraDistPath }))
- *   router.get('/_assets/pages/*',  serveAssets({ root: pagesPath }))
+ *   router.get('/__assets/aurora/*', serveAssets({ root: auroraDistPath }))
+ *   router.get('/__assets/pages/*',  serveAssets({ root: pagesPath }))
  *
  * The handler is framework-agnostic: it reads `ctx.request.param('*')`
  * and writes to `ctx.response`. Any context that satisfies

package/dist/server/serveAssets.js

@@ -2,8 +2,8 @@
  * `serveAssets` — generic static-file handler exposed by aurora so an
  * app can mount the runtime + the pages dist with a couple of routes:
  *
- *   router.get('/_assets/aurora/*', serveAssets({ root: auroraDistPath }))
- *   router.get('/_assets/pages/*',  serveAssets({ root: pagesPath }))
+ *   router.get('/__assets/aurora/*', serveAssets({ root: auroraDistPath }))
+ *   router.get('/__assets/pages/*',  serveAssets({ root: pagesPath }))
  *
  * The handler is framework-agnostic: it reads `ctx.request.param('*')`
  * and writes to `ctx.response`. Any context that satisfies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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",

package/src/AuroraManager.ts

@@ -45,7 +45,7 @@ export interface AuroraManagerConfig {
 	 * URL prefix the asset routes mount under. The aurora runtime is served
 	 * from `<assetsPrefix>/aurora/*` and the app's pages from
 	 * `<assetsPrefix>/pages/*`, and the SSR importmap + page URLs derive from
-	 * it. Default `/_assets` (the leading underscore namespaces framework
+	 * it. Default `/__assets` (the leading underscore namespaces framework
 	 * assets away from app routes, Next.js `/_next` style). Set e.g. `/assets`
 	 * for an underscore-free scheme. An explicit `pages.urlPrefix` still wins.
 	 */
@@ -56,7 +56,7 @@ export interface AuroraManagerConfig {
 	 * importmaps). Merged over aurora's auto defaults (`@c9up/aurora`,
 	 * `@c9up/aurora/rpc`, `@c9up/comet`) on every `render()`. Use to point a bare
 	 * specifier at a curated browser entry, e.g.
-	 * `{ '@c9up/aurora': '/_assets/pages/browser/aurora.js' }`. A per-call
+	 * `{ '@c9up/aurora': '/__assets/pages/browser/aurora.js' }`. A per-call
 	 * `render(..., { importmap })` still wins over this.
 	 *
 	 * (Importmaps are aurora's no-bundler particularity — AdonisJS bundles via Vite
@@ -92,7 +92,7 @@ function normalizePrefix(prefix: string): string {
 export class AuroraManager {
 	readonly pages: Pages;
 	readonly auroraDistRoot: string;
-	/** Resolved asset prefix (default `/_assets`). */
+	/** Resolved asset prefix (default `/__assets`). */
 	readonly assetsPrefix: string;
 	/** Mount path for the aurora runtime — `<assetsPrefix>/aurora`. */
 	readonly auroraAssetPath: string;
@@ -106,7 +106,7 @@ export class AuroraManager {
 	readonly importmap: Record<string, string>;
 
 	constructor(config: AuroraManagerConfig) {
-		this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
+		this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/__assets");
 		this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
 		this.pageAssetPath = `${this.assetsPrefix}/pages`;
 		this.cometAssetPath = `${this.assetsPrefix}/comet`;
@@ -159,7 +159,7 @@ export class AuroraManager {
 
 	/**
 	 * Handler for aurora's pre-built ESM runtime. Mount on
-	 * `GET /_assets/aurora/*`.
+	 * `GET /__assets/aurora/*`.
 	 */
 	auroraAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
 		return serveAssets({ root: this.auroraDistRoot });
@@ -167,7 +167,7 @@ export class AuroraManager {
 
 	/**
 	 * Handler for the app's pages directory. Mount on
-	 * `GET /_assets/pages/*`.
+	 * `GET /__assets/pages/*`.
 	 */
 	pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
 		return serveAssets({ root: this.pages.root });

package/src/AuroraProvider.ts

@@ -2,8 +2,8 @@
  * AuroraProvider — registers the AuroraManager singleton and auto-mounts
  * the two asset routes the browser needs:
  *
- *   GET /_assets/aurora/*  → packages/@c9up/aurora/dist/*
- *   GET /_assets/pages/*   → resources/pages/*
+ *   GET /__assets/aurora/*  → packages/@c9up/aurora/dist/*
+ *   GET /__assets/pages/*   → resources/pages/*
  *
  * Config (in `config/aurora.ts`):
  *
@@ -92,7 +92,7 @@ export default class AuroraProvider {
 		const router = this.app.container.resolve<ReamRouter>("router");
 		const manager = this.app.container.resolve<AuroraManager>(AuroraManager);
 		// Mount paths derive from the configured `assetsPrefix` (default
-		// `/_assets`) — set `config.aurora.assetsPrefix` to change the scheme.
+		// `/__assets`) — set `config.aurora.assetsPrefix` to change the scheme.
 		router.get(
 			`${manager.auroraAssetPath}/*`,
 			adaptHandler(manager.auroraAssetsHandler()),

package/src/Pages.ts

@@ -33,7 +33,7 @@ export interface PagesConfig {
 
 	/**
 	 * URL prefix the browser uses to fetch a page's compiled JS.
-	 * Defaults to `/_assets/pages`. A name `"Foo"` maps to
+	 * Defaults to `/__assets/pages`. A name `"Foo"` maps to
 	 * `${urlPrefix}/Foo.js`.
 	 */
 	urlPrefix?: string;
@@ -63,7 +63,7 @@ export class Pages {
 
 	constructor(config: PagesConfig) {
 		this.root = config.root;
-		this.urlPrefix = (config.urlPrefix ?? "/_assets/pages").replace(/\/$/, "");
+		this.urlPrefix = (config.urlPrefix ?? "/__assets/pages").replace(/\/$/, "");
 		this.extension = config.extension ?? ".js";
 	}
 

package/src/browser.ts

@@ -50,10 +50,14 @@ export interface WebStorageOptions {
 }
 
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -80,28 +84,52 @@ export class WebStorage {
 		return this.#prefix + key;
 	}
 
-	get<T>(key: string): T | null {
+	/**
+	 * Read the raw string at `key` — a thin, SSR-safe pass-through over
+	 * `localStorage.getItem` (returns `null` on the server or a missing key).
+	 * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+	 * structured values.
+	 */
+	get(key: string): string | null {
 		const backend = this.#backend();
 		if (!backend) return null;
-		const raw = backend.getItem(this.fullKey(key));
-		if (raw === null) return null;
-		try {
-			return JSON.parse(raw) as T;
-		} catch {
-			return null;
-		}
+		return backend.getItem(this.fullKey(key));
 	}
 
-	set(key: string, value: unknown): void {
+	/**
+	 * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+	 * errors are swallowed — best-effort). No encoding, like
+	 * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+	 */
+	set(key: string, value: string): void {
 		const backend = this.#backend();
 		if (!backend) return;
 		try {
-			backend.setItem(this.fullKey(key), JSON.stringify(value));
+			backend.setItem(this.fullKey(key), value);
 		} catch {
 			// QuotaExceededError / Safari private mode — best-effort write.
 		}
 	}
 
+	/**
+	 * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+	 * missing key, or malformed JSON. Pair with {@link setJSON}.
+	 */
+	getJSON<T>(key: string): T | null {
+		const raw = this.get(key);
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+	setJSON(key: string, value: unknown): void {
+		this.set(key, JSON.stringify(value));
+	}
+
 	/** Whether `key` is present (and not the server). */
 	has(key: string): boolean {
 		const backend = this.#backend();
@@ -113,9 +141,9 @@ export class WebStorage {
 		this.#backend()?.removeItem(this.fullKey(key));
 	}
 
-	/** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-	getOrSet<T>(key: string, factory: () => T): T {
-		const existing = this.get<T>(key);
+	/** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+	getOrSet(key: string, factory: () => string): string {
+		const existing = this.get(key);
 		if (existing !== null) return existing;
 		const value = factory();
 		this.set(key, value);
@@ -183,12 +211,13 @@ export function persistedSignal<T>(
 	options: PersistedSignalOptions = {},
 ): Signal<T> {
 	const store = new WebStorage(options);
-	const stored = store.get<T>(key);
+	const stored = store.getJSON<T>(key);
 	const sig = signal<T>(stored !== null ? stored : initial);
 
 	// Mirror every change back to storage; runs once immediately, then on change.
+	// JSON so any T (object, number, boolean, string) round-trips.
 	effect(() => {
-		store.set(key, sig());
+		store.setJSON(key, sig());
 	});
 
 	if (

package/src/liveClient.ts

@@ -91,7 +91,7 @@ export interface LiveHttpPoster {
 /**
  * Build a {@link LiveClientTransport} from a relay client (SSE down) + an HTTP
  * client (events up). `path` must match the server's `wireLiveEvents` route
- * (default `/_live/event`). Keeps `liveClient` itself transport-agnostic.
+ * (default `/__live/event`). Keeps `liveClient` itself transport-agnostic.
  *
  * @example
  *   import { relay } from '@c9up/aurora/relay'
@@ -104,7 +104,7 @@ export function buildLiveTransport(
 	http: LiveHttpPoster,
 	options: { path?: string } = {},
 ): LiveClientTransport {
-	const path = options.path ?? "/_live/event";
+	const path = options.path ?? "/__live/event";
 	return {
 		subscribe: (channel, handler) =>
 			relayClient.subscribe<SlotPatch[]>(channel, handler),

package/src/liveServer.ts

@@ -45,7 +45,7 @@ function isLiveEventBody(value: unknown): value is LiveEventBody {
 }
 
 /** Default inbound-event route — keep the client transport's `path` in sync. */
-export const DEFAULT_LIVE_EVENT_PATH = "/_live/event";
+export const DEFAULT_LIVE_EVENT_PATH = "/__live/event";
 
 /**
  * Register the inbound live-event route on the host router. Call once at boot

package/src/rpc.ts

@@ -34,17 +34,56 @@ export interface RpcClientOptions {
 	http?: HttpClient;
 	/** Default headers — only used when no `http` client is supplied. */
 	headers?: Record<string, string>;
+	/**
+	 * Auto CSRF: read the `XSRF-TOKEN` cookie and echo it as `X-XSRF-TOKEN` on
+	 * every call (Axios/Angular convention), so RPC POSTs pass blackhole's
+	 * signed double-submit check when the route is cookie/session-authed. No-op
+	 * outside the browser and when the cookie is absent. Default `true`.
+	 * `/rpc` under a bearer (JWT) guard is CSRF-exempt, so the missing-cookie
+	 * no-op is exactly right there too.
+	 */
+	xsrf?: boolean;
+	/** Cookie to read the CSRF token from. Default `XSRF-TOKEN`. */
+	xsrfCookieName?: string;
+	/** Header to echo the CSRF token in. Default `X-XSRF-TOKEN`. */
+	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.
+ * 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";
 	return createCometRpcClient({
 		url: options.url,
-		transport: (url, body, { signal }) =>
-			http.post<unknown>(url, body, { signal }),
+		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 });
+		},
 	});
 }

package/src/server/renderPage.ts

@@ -8,7 +8,7 @@
  *   <head>
  *     ...
  *     <script type="importmap">
- *       { "imports": { "@c9up/aurora": "/_assets/aurora/index.js" } }
+ *       { "imports": { "@c9up/aurora": "/__assets/aurora/index.js" } }
  *     </script>
  *   </head>
  *   <body>
@@ -16,7 +16,7 @@
  *     <script id="aurora-page-data" type="application/json">{…}</script>
  *     <script type="module">
  *       import { hydrate } from '@c9up/aurora'
- *       import Page from '/_assets/pages/ProjectPage.js'
+ *       import Page from '/__assets/pages/ProjectPage.js'
  *       const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
  *       hydrate(document.getElementById('aurora-root'), () => Page(data.props))
  *     </script>
@@ -45,7 +45,7 @@ export interface RenderHttpContext {
 export interface RenderPageOptions {
 	/**
 	 * Importmap entries injected into `<head>`. Defaults to mapping
-	 * `@c9up/aurora` to `/_assets/aurora/index.js`. Override to point
+	 * `@c9up/aurora` to `/__assets/aurora/index.js`. Override to point
 	 * at a different mount or to add app-side aliases.
 	 */
 	importmap?: Record<string, string>;
@@ -139,7 +139,7 @@ export async function renderPage<P>(
 	const body = renderToString(tree);
 
 	const importmap = {
-		"@c9up/aurora": "/_assets/aurora/index.js",
+		"@c9up/aurora": "/__assets/aurora/index.js",
 		...options.importmap,
 	};
 	const rootId = options.rootId ?? "aurora-root";

package/src/server/serveAssets.ts

@@ -2,8 +2,8 @@
  * `serveAssets` — generic static-file handler exposed by aurora so an
  * app can mount the runtime + the pages dist with a couple of routes:
  *
- *   router.get('/_assets/aurora/*', serveAssets({ root: auroraDistPath }))
- *   router.get('/_assets/pages/*',  serveAssets({ root: pagesPath }))
+ *   router.get('/__assets/aurora/*', serveAssets({ root: auroraDistPath }))
+ *   router.get('/__assets/pages/*',  serveAssets({ root: pagesPath }))
  *
  * The handler is framework-agnostic: it reads `ctx.request.param('*')`
  * and writes to `ctx.response`. Any context that satisfies