@c9up/aurora 0.1.19 → 0.1.21

package/dist/AuroraManager.d.ts

@@ -33,16 +33,29 @@ 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.
      */
     assetsPrefix?: string;
+    /**
+     * App-level importmap overrides, configured ONCE here (the AdonisJS model:
+     * config lives in `config/aurora.ts`, controllers stay thin and never hand-write
+     * 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
+     * `render(..., { importmap })` still wins over this.
+     *
+     * (Importmaps are aurora's no-bundler particularity — AdonisJS bundles via Vite
+     * and has no importmap; we keep the config-driven shape to stay Adonis-idiomatic.)
+     */
+    importmap?: Record<string, string>;
 }
 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;
@@ -52,22 +65,25 @@ export declare class AuroraManager {
     readonly cometAssetPath: string;
     /** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
     readonly cometDistRoot: string | null;
+    /** App-level importmap overrides from `config/aurora.ts`, merged on render. */
+    readonly importmap: Record<string, string>;
     constructor(config: AuroraManagerConfig);
     /**
-     * SSR + hydrate + ship the document. The importmap default points
-     * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
-     * `options.importmap` still overrides (e.g. to remap to an app-curated
-     * browser entry).
+     * SSR + hydrate + ship the document. The importmap layers, last wins:
+     * aurora's auto defaults (`@c9up/aurora`, `@c9up/aurora/rpc`, `@c9up/comet`)
+     * < the config-level `importmap` (from `config/aurora.ts`) < a per-call
+     * `options.importmap`. So a thin controller calls `render(ctx, name, props)`
+     * with no importmap, and any curation lives once in config.
      */
     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;
@@ -48,12 +48,15 @@ export class AuroraManager {
     cometAssetPath;
     /** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
     cometDistRoot;
+    /** 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`;
         this.cometDistRoot = config.cometDistRoot ?? resolveCometDist();
+        this.importmap = config.importmap ?? {};
         // Pages serve their compiled JS from the same prefix unless the app
         // pins an explicit urlPrefix.
         this.pages = new Pages({
@@ -63,10 +66,11 @@ export class AuroraManager {
         this.auroraDistRoot = config.auroraDistRoot ?? DEFAULT_AURORA_DIST;
     }
     /**
-     * SSR + hydrate + ship the document. The importmap default points
-     * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
-     * `options.importmap` still overrides (e.g. to remap to an app-curated
-     * browser entry).
+     * SSR + hydrate + ship the document. The importmap layers, last wins:
+     * aurora's auto defaults (`@c9up/aurora`, `@c9up/aurora/rpc`, `@c9up/comet`)
+     * < the config-level `importmap` (from `config/aurora.ts`) < a per-call
+     * `options.importmap`. So a thin controller calls `render(ctx, name, props)`
+     * with no importmap, and any curation lives once in config.
      */
     render(ctx, name, props, options) {
         return renderPage(ctx, this.pages, name, props, {
@@ -84,20 +88,23 @@ export class AuroraManager {
                 ...(this.cometDistRoot
                     ? { "@c9up/comet": `${this.cometAssetPath}/index.js` }
                     : {}),
+                // Config-level overrides (config/aurora.ts) — Adonis-style config-driven,
+                // so controllers never hand-write an importmap. A per-call override wins.
+                ...this.importmap,
                 ...options?.importmap,
             },
         });
     }
     /**
      * 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/live.d.ts

@@ -53,3 +53,8 @@ export interface LiveSession {
  * every session then reads the same signal and patches on its change.
  */
 export declare function mountLiveSession(factory: () => LiveComponentDefinition): LiveSession;
+export { connectPatches, type LiveStore, liveStore, type RelayBroadcaster, } from "./liveBroadcast.js";
+export { buildLiveTransport, type LiveClientOptions, type LiveClientTransport, type LiveHttpPoster, liveClient, type RelaySubscribeClient, } from "./liveClient.js";
+export { createLiveRegistry, type LiveRegistry, type LiveSessionHandle, } from "./liveRegistry.js";
+export { createLiveRouter, type LiveMount, type LiveRouter, } from "./liveRouter.js";
+export { DEFAULT_LIVE_EVENT_PATH, type LiveHttpContext, type LiveHttpRouter, type WireLiveEventsOptions, wireLiveEvents, } from "./liveServer.js";

package/dist/live.js

@@ -94,3 +94,15 @@ export function mountLiveSession(factory) {
         },
     };
 }
+// ─── `@c9up/aurora/live` barrel ──────────────────────────────────────
+//
+// The Live stack (broadcast / client / registry / router / server) is
+// re-exported here so the whole niche surface lives behind ONE subpath,
+// `@c9up/aurora/live` — keeping the main `.` barrel lean (it no longer
+// eager-pulls these into every browser graph), consistent with how `./ssr`,
+// `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
+export { connectPatches, liveStore, } from "./liveBroadcast.js";
+export { buildLiveTransport, liveClient, } from "./liveClient.js";
+export { createLiveRegistry, } from "./liveRegistry.js";
+export { createLiveRouter, } from "./liveRouter.js";
+export { DEFAULT_LIVE_EVENT_PATH, wireLiveEvents, } from "./liveServer.js";

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/middleware.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `auroraContext` — binds `ctx.aurora.render(name, props)` onto the request
+ * context, the AdonisJS ctx-service idiom (the `ctx.view` / `ctx.inertia`
+ * analog). Register it globally in your kernel; a thin controller then does:
+ *
+ *   async show({ aurora }: HttpContext) {
+ *     return aurora.render('Dashboard', { user, stats })
+ *   }
+ *
+ * Agnostic: it resolves the AuroraManager from the request container
+ * (`ctx.containerResolver.make('aurora')`) — never imports `@c9up/ream` — and is
+ * a no-op when no manager is registered. The module-level `aurora.render(ctx, …)`
+ * service still works; this is the ctx-bound sugar.
+ */
+import type { RenderHttpContext, RenderPageOptions } from "./server/renderPage.js";
+/** The `ctx.aurora` surface — ctx-bound render (no explicit ctx argument). */
+export interface AuroraRequestRenderer {
+    render(name: string, props?: unknown, options?: RenderPageOptions): Promise<void>;
+}
+/** Request context the middleware needs: render target + optional resolver/slot. */
+interface AuroraMiddlewareContext extends RenderHttpContext {
+    containerResolver?: {
+        make(token: unknown): unknown;
+    };
+    aurora?: AuroraRequestRenderer;
+}
+/**
+ * Middleware: attach `ctx.aurora` for the request. No-op (passes through) when
+ * the AuroraManager isn't registered, so it's safe to mount unconditionally.
+ */
+export declare function auroraContext(ctx: AuroraMiddlewareContext, next: () => Promise<void>): Promise<void>;
+export {};

package/dist/middleware.js

@@ -0,0 +1,43 @@
+/**
+ * `auroraContext` — binds `ctx.aurora.render(name, props)` onto the request
+ * context, the AdonisJS ctx-service idiom (the `ctx.view` / `ctx.inertia`
+ * analog). Register it globally in your kernel; a thin controller then does:
+ *
+ *   async show({ aurora }: HttpContext) {
+ *     return aurora.render('Dashboard', { user, stats })
+ *   }
+ *
+ * Agnostic: it resolves the AuroraManager from the request container
+ * (`ctx.containerResolver.make('aurora')`) — never imports `@c9up/ream` — and is
+ * a no-op when no manager is registered. The module-level `aurora.render(ctx, …)`
+ * service still works; this is the ctx-bound sugar.
+ */
+/** Structural check that a resolved value is render-capable (an AuroraManager). */
+function isManager(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "render" in value &&
+        typeof value.render === "function");
+}
+function resolveManager(resolver) {
+    try {
+        const resolved = resolver?.make("aurora");
+        return isManager(resolved) ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Middleware: attach `ctx.aurora` for the request. No-op (passes through) when
+ * the AuroraManager isn't registered, so it's safe to mount unconditionally.
+ */
+export function auroraContext(ctx, next) {
+    const manager = resolveManager(ctx.containerResolver);
+    if (manager) {
+        ctx.aurora = {
+            render: (name, props, options) => manager.render(ctx, name, props, options),
+        };
+    }
+    return next();
+}

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/dist/server.d.ts

@@ -1,4 +1,5 @@
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
+export { type AuroraRequestRenderer, auroraContext, } from "./middleware.js";
 export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
 export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, } from "./server/renderPage.js";
 export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, packageAssetDir, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";

package/dist/server.js

@@ -5,6 +5,7 @@
 // Node built-ins through the import graph. Server code imports from
 // `@c9up/aurora/server`; the client `.` entry stays node-free.
 export { AuroraManager } from "./AuroraManager.js";
+export { auroraContext, } from "./middleware.js";
 export { Pages } from "./Pages.js";
 export { renderPage, } from "./server/renderPage.js";
 export { packageAssetDir, serveAssets, } from "./server/serveAssets.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "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,11 +45,24 @@ 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.
 	 */
 	assetsPrefix?: string;
+	/**
+	 * App-level importmap overrides, configured ONCE here (the AdonisJS model:
+	 * config lives in `config/aurora.ts`, controllers stay thin and never hand-write
+	 * 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
+	 * `render(..., { importmap })` still wins over this.
+	 *
+	 * (Importmaps are aurora's no-bundler particularity — AdonisJS bundles via Vite
+	 * and has no importmap; we keep the config-driven shape to stay Adonis-idiomatic.)
+	 */
+	importmap?: Record<string, string>;
 }
 
 const DEFAULT_AURORA_DIST = resolvePath(
@@ -79,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;
@@ -89,13 +102,16 @@ export class AuroraManager {
 	readonly cometAssetPath: string;
 	/** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
 	readonly cometDistRoot: string | null;
+	/** App-level importmap overrides from `config/aurora.ts`, merged on render. */
+	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`;
 		this.cometDistRoot = config.cometDistRoot ?? resolveCometDist();
+		this.importmap = config.importmap ?? {};
 		// Pages serve their compiled JS from the same prefix unless the app
 		// pins an explicit urlPrefix.
 		this.pages = new Pages({
@@ -106,10 +122,11 @@ export class AuroraManager {
 	}
 
 	/**
-	 * SSR + hydrate + ship the document. The importmap default points
-	 * `@c9up/aurora` at this manager's `assetsPrefix`; a caller's
-	 * `options.importmap` still overrides (e.g. to remap to an app-curated
-	 * browser entry).
+	 * SSR + hydrate + ship the document. The importmap layers, last wins:
+	 * aurora's auto defaults (`@c9up/aurora`, `@c9up/aurora/rpc`, `@c9up/comet`)
+	 * < the config-level `importmap` (from `config/aurora.ts`) < a per-call
+	 * `options.importmap`. So a thin controller calls `render(ctx, name, props)`
+	 * with no importmap, and any curation lives once in config.
 	 */
 	render(
 		ctx: RenderHttpContext,
@@ -132,6 +149,9 @@ export class AuroraManager {
 				...(this.cometDistRoot
 					? { "@c9up/comet": `${this.cometAssetPath}/index.js` }
 					: {}),
+				// Config-level overrides (config/aurora.ts) — Adonis-style config-driven,
+				// so controllers never hand-write an importmap. A per-call override wins.
+				...this.importmap,
 				...options?.importmap,
 			},
 		});
@@ -139,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 });
@@ -147,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/live.ts

@@ -130,3 +130,42 @@ export function mountLiveSession(
 		},
 	};
 }
+
+// ─── `@c9up/aurora/live` barrel ──────────────────────────────────────
+//
+// The Live stack (broadcast / client / registry / router / server) is
+// re-exported here so the whole niche surface lives behind ONE subpath,
+// `@c9up/aurora/live` — keeping the main `.` barrel lean (it no longer
+// eager-pulls these into every browser graph), consistent with how `./ssr`,
+// `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
+export {
+	connectPatches,
+	type LiveStore,
+	liveStore,
+	type RelayBroadcaster,
+} from "./liveBroadcast.js";
+export {
+	buildLiveTransport,
+	type LiveClientOptions,
+	type LiveClientTransport,
+	type LiveHttpPoster,
+	liveClient,
+	type RelaySubscribeClient,
+} from "./liveClient.js";
+export {
+	createLiveRegistry,
+	type LiveRegistry,
+	type LiveSessionHandle,
+} from "./liveRegistry.js";
+export {
+	createLiveRouter,
+	type LiveMount,
+	type LiveRouter,
+} from "./liveRouter.js";
+export {
+	DEFAULT_LIVE_EVENT_PATH,
+	type LiveHttpContext,
+	type LiveHttpRouter,
+	type WireLiveEventsOptions,
+	wireLiveEvents,
+} from "./liveServer.js";

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/middleware.ts

@@ -0,0 +1,74 @@
+/**
+ * `auroraContext` — binds `ctx.aurora.render(name, props)` onto the request
+ * context, the AdonisJS ctx-service idiom (the `ctx.view` / `ctx.inertia`
+ * analog). Register it globally in your kernel; a thin controller then does:
+ *
+ *   async show({ aurora }: HttpContext) {
+ *     return aurora.render('Dashboard', { user, stats })
+ *   }
+ *
+ * Agnostic: it resolves the AuroraManager from the request container
+ * (`ctx.containerResolver.make('aurora')`) — never imports `@c9up/ream` — and is
+ * a no-op when no manager is registered. The module-level `aurora.render(ctx, …)`
+ * service still works; this is the ctx-bound sugar.
+ */
+
+import type { AuroraManager } from "./AuroraManager.js";
+import type {
+	RenderHttpContext,
+	RenderPageOptions,
+} from "./server/renderPage.js";
+
+/** The `ctx.aurora` surface — ctx-bound render (no explicit ctx argument). */
+export interface AuroraRequestRenderer {
+	render(
+		name: string,
+		props?: unknown,
+		options?: RenderPageOptions,
+	): Promise<void>;
+}
+
+/** Request context the middleware needs: render target + optional resolver/slot. */
+interface AuroraMiddlewareContext extends RenderHttpContext {
+	containerResolver?: { make(token: unknown): unknown };
+	aurora?: AuroraRequestRenderer;
+}
+
+/** Structural check that a resolved value is render-capable (an AuroraManager). */
+function isManager(value: unknown): value is AuroraManager {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"render" in value &&
+		typeof value.render === "function"
+	);
+}
+
+function resolveManager(
+	resolver: { make(token: unknown): unknown } | undefined,
+): AuroraManager | undefined {
+	try {
+		const resolved = resolver?.make("aurora");
+		return isManager(resolved) ? resolved : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Middleware: attach `ctx.aurora` for the request. No-op (passes through) when
+ * the AuroraManager isn't registered, so it's safe to mount unconditionally.
+ */
+export function auroraContext(
+	ctx: AuroraMiddlewareContext,
+	next: () => Promise<void>,
+): Promise<void> {
+	const manager = resolveManager(ctx.containerResolver);
+	if (manager) {
+		ctx.aurora = {
+			render: (name, props, options) =>
+				manager.render(ctx, name, props, options),
+		};
+	}
+	return next();
+}

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

package/src/server.ts

@@ -6,6 +6,10 @@
 // `@c9up/aurora/server`; the client `.` entry stays node-free.
 
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
+export {
+	type AuroraRequestRenderer,
+	auroraContext,
+} from "./middleware.js";
 export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
 export {
 	type RenderHttpContext,