@c9up/aurora 0.1.23 → 0.1.25

package/dist/AuroraProvider.d.ts

@@ -17,7 +17,7 @@
  */
 interface AuroraContainer {
     singleton(token: unknown, factory: () => unknown): void;
-    resolve<T = unknown>(token: unknown): T;
+    resolve<T = unknown>(token: unknown): Promise<T>;
     has(token: unknown): boolean;
 }
 interface AuroraConfigStore {

package/dist/AuroraProvider.js

@@ -27,9 +27,9 @@ export default class AuroraProvider {
         this.app = app;
     }
     register() {
-        this.app.container.singleton(AuroraManager, () => {
+        this.app.container.singleton(AuroraManager, async () => {
             const raw = this.app.config.get("aurora");
-            const config = this.resolveConfig(raw);
+            const config = await this.resolveConfig(raw);
             const manager = new AuroraManager(config);
             setAurora(manager);
             return manager;
@@ -44,7 +44,7 @@ export default class AuroraProvider {
     async boot() {
         // Force-resolve so `setAurora` runs even if the app never
         // touches the singleton from a preload.
-        const manager = this.app.container.resolve(AuroraManager);
+        const manager = await this.app.container.resolve(AuroraManager);
         setAurora(manager);
     }
     async start() {
@@ -61,8 +61,8 @@ export default class AuroraProvider {
         // instead of being misread as "the asset routes just stopped mounting".
         if (!this.app.container.has("router"))
             return;
-        const router = this.app.container.resolve("router");
-        const manager = this.app.container.resolve(AuroraManager);
+        const router = await this.app.container.resolve("router");
+        const manager = await this.app.container.resolve(AuroraManager);
         // Mount paths derive from the configured `assetsPrefix` (default
         // `/__assets`) — set `config.aurora.assetsPrefix` to change the scheme.
         router.get(`${manager.auroraAssetPath}/*`, adaptHandler(manager.auroraAssetsHandler()));
@@ -89,8 +89,8 @@ export default class AuroraProvider {
      * one (Ream does, since v0.x — see Ignitor); other hosts get the
      * `process.cwd()` fallback.
      */
-    resolveConfig(raw) {
-        const appRoot = this.readAppRoot();
+    async resolveConfig(raw) {
+        const appRoot = await this.readAppRoot();
         const userRoot = raw?.pages?.root;
         const root = typeof userRoot === "string" && userRoot.length > 0
             ? isAbsolute(userRoot)
@@ -102,9 +102,9 @@ export default class AuroraProvider {
             pages: { ...(raw?.pages ?? {}), root },
         };
     }
-    readAppRoot() {
+    async readAppRoot() {
         try {
-            const raw = this.app.container.resolve("appRoot");
+            const raw = await this.app.container.resolve("appRoot");
             if (raw instanceof URL)
                 return fileURLToPath(raw);
             if (typeof raw === "string")

package/dist/Pages.js

@@ -28,7 +28,11 @@ export class Pages {
     extension;
     registry = new Map();
     constructor(config) {
-        this.root = config.root;
+        // Normalize the root ONCE so the `startsWith(root + sep)` containment
+        // check below compares like-for-like against the resolved page path.
+        // A raw root with a trailing slash, a relative segment, or `..` would
+        // otherwise never match the resolved absolute path → spurious 403s.
+        this.root = resolvePath(config.root);
         this.urlPrefix = (config.urlPrefix ?? "/__assets/pages").replace(/\/$/, "");
         this.extension = config.extension ?? ".js";
     }

package/dist/browser.js

@@ -6,7 +6,7 @@
  * without `typeof window` guards at every call site. Node-free — part of the
  * client barrel.
  */
-import { effect, signal } from "./reactive.js";
+import { effect, onCleanup, signal } from "./reactive.js";
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export function redirect(url) {
     if (typeof window !== "undefined") {
@@ -185,7 +185,7 @@ export function persistedSignal(key, initial, options = {}) {
         (options.area ?? "local") === "local" &&
         typeof window !== "undefined") {
         const fullKey = store.fullKey(key);
-        window.addEventListener("storage", (event) => {
+        const onStorage = (event) => {
             if (event.key !== fullKey || event.newValue === null)
                 return;
             try {
@@ -194,7 +194,14 @@ export function persistedSignal(key, initial, options = {}) {
             catch {
                 // Ignore a malformed cross-tab write.
             }
-        });
+        };
+        window.addEventListener("storage", onStorage);
+        // Tie the listener to the owning reactive scope so a persistedSignal
+        // created in a component's setup removes it on dispose (matching the
+        // mirror effect above — the JSDoc promises disposal-with-the-component).
+        // At module scope onCleanup is a no-op, so the listener lives for the
+        // page lifetime, as intended for a shared module-level signal.
+        onCleanup(() => window.removeEventListener("storage", onStorage));
     }
     return sig;
 }

package/dist/middleware.d.ts

@@ -20,7 +20,7 @@ export interface AuroraRequestRenderer {
 /** Request context the middleware needs: render target + optional resolver/slot. */
 interface AuroraMiddlewareContext extends RenderHttpContext {
     containerResolver?: {
-        make(token: unknown): unknown;
+        make(token: unknown): Promise<unknown>;
     };
     aurora?: AuroraRequestRenderer;
 }

package/dist/middleware.js

@@ -19,9 +19,9 @@ function isManager(value) {
         "render" in value &&
         typeof value.render === "function");
 }
-function resolveManager(resolver) {
+async function resolveManager(resolver) {
     try {
-        const resolved = resolver?.make("aurora");
+        const resolved = await resolver?.make("aurora");
         return isManager(resolved) ? resolved : undefined;
     }
     catch {
@@ -32,8 +32,8 @@ function resolveManager(resolver) {
  * 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);
+export async function auroraContext(ctx, next) {
+    const manager = await resolveManager(ctx.containerResolver);
     if (manager) {
         ctx.aurora = {
             render: (name, props, options) => manager.render(ctx, name, props, options),

package/dist/relay.d.ts

@@ -17,8 +17,19 @@
  * `@c9up/aurora`. Node-side code that pulls it will trip on
  * `EventSource` being undefined.
  */
+/**
+ * Connection lifecycle status. Mirrors `@adonisjs/transmit-client`'s
+ * `TransmitStatus` (minus `initializing`, which the singleton never
+ * exposes — the first `relay()` call opens straight into `connecting`).
+ */
+export type RelayStatus = "connecting" | "connected" | "disconnected" | "reconnecting";
 export interface RelayClient {
     subscribe<E>(channel: string, handler: (event: E) => void): () => void;
+    /**
+     * Register a connection-status listener. Returns a detacher. Mirrors
+     * `transmit.on('connected' | 'disconnected' | ...)`.
+     */
+    on(status: RelayStatus, callback: (status: RelayStatus) => void): () => void;
     close(): void;
 }
 export interface RelayOptions {
@@ -26,13 +37,25 @@ export interface RelayOptions {
     sseUrl?: string;
     /** Subscribe POST endpoint. Defaults to `/__relay/subscribe`. */
     subscribeUrl?: string;
+    /** Unsubscribe POST endpoint. Defaults to `/__relay/unsubscribe`. */
+    unsubscribeUrl?: string;
     /** Optional bearer token (for guarded relay routes). */
     bearer?: string;
+    /**
+     * Give up after this many consecutive reconnect attempts. Default 5
+     * (Transmit parity). `0` disables the cap — the browser's native
+     * EventSource keeps retrying forever.
+     */
+    maxReconnectAttempts?: number;
+    /** Fired before each reconnect attempt with the 1-based attempt count. */
+    onReconnectAttempt?: (attempt: number) => void;
+    /** Fired once when `maxReconnectAttempts` is exhausted and we give up. */
+    onReconnectFailed?: () => void;
 }
 /**
- * Configure the relay endpoints + bearer. Call once at boot if you
- * need to override the defaults. Multiple calls overwrite — last call
- * wins.
+ * Configure the relay endpoints + bearer + reconnect policy. Call once
+ * at boot if you need to override the defaults. Multiple calls overwrite
+ * — last call wins.
  */
 export declare function configureRelay(options: RelayOptions): void;
 /**

package/dist/relay.js

@@ -22,22 +22,31 @@ const STATE = {
     uid: null,
     channels: new Map(),
     attached: new Set(),
+    status: "connecting",
+    statusListeners: new Map(),
+    reconnectAttempts: 0,
 };
 let CONFIG = {
     sseUrl: "/__relay/events",
     subscribeUrl: "/__relay/subscribe",
+    unsubscribeUrl: "/__relay/unsubscribe",
     bearer: "",
+    maxReconnectAttempts: 5,
 };
 /**
- * Configure the relay endpoints + bearer. Call once at boot if you
- * need to override the defaults. Multiple calls overwrite — last call
- * wins.
+ * Configure the relay endpoints + bearer + reconnect policy. Call once
+ * at boot if you need to override the defaults. Multiple calls overwrite
+ * — last call wins.
  */
 export function configureRelay(options) {
     CONFIG = {
         sseUrl: options.sseUrl ?? CONFIG.sseUrl,
         subscribeUrl: options.subscribeUrl ?? CONFIG.subscribeUrl,
+        unsubscribeUrl: options.unsubscribeUrl ?? CONFIG.unsubscribeUrl,
         bearer: options.bearer ?? CONFIG.bearer,
+        maxReconnectAttempts: options.maxReconnectAttempts ?? CONFIG.maxReconnectAttempts,
+        onReconnectAttempt: options.onReconnectAttempt ?? CONFIG.onReconnectAttempt,
+        onReconnectFailed: options.onReconnectFailed ?? CONFIG.onReconnectFailed,
     };
 }
 /**
@@ -74,11 +83,32 @@ const CLIENT = {
                 console.warn(`[aurora/relay] subscribe to ${channel} failed:`, err);
             });
         }
-        // Detacher — only removes the local listener. The server-side
-        // subscription stays open; closing it would interrupt other
-        // listeners on the same channel.
+        // Detacher — removes the local listener. When it was the LAST handler
+        // on the channel, the server-side subscription is dropped too (POST
+        // /__relay/unsubscribe), so the server stops streaming a channel
+        // nobody's listening to. Other channels / other listeners are
+        // untouched.
         return () => {
             handlers?.delete(adapted);
+            if (handlers && handlers.size === 0) {
+                STATE.channels.delete(channel);
+                if (STATE.uid) {
+                    postUnsubscribe(channel).catch((err) => {
+                        console.warn(`[aurora/relay] unsubscribe from ${channel} failed:`, err);
+                    });
+                }
+            }
+        };
+    },
+    on(status, callback) {
+        let set = STATE.statusListeners.get(status);
+        if (!set) {
+            set = new Set();
+            STATE.statusListeners.set(status, set);
+        }
+        set.add(callback);
+        return () => {
+            set?.delete(callback);
         };
     },
     close() {
@@ -89,16 +119,22 @@ const CLIENT = {
         STATE.uid = null;
         STATE.channels.clear();
         STATE.attached.clear();
+        STATE.reconnectAttempts = 0;
     },
 };
 function open() {
     const sse = new EventSource(CONFIG.sseUrl);
     STATE.sse = sse;
     STATE.attached = new Set();
+    changeStatus("connecting");
     sse.addEventListener("connected", (ev) => {
         const data = safeJson(messageData(ev));
         if (data && typeof data.uid === "string") {
             STATE.uid = data.uid;
+            // A successful (re)connect clears the failure counter and flips the
+            // status back to `connected`.
+            STATE.reconnectAttempts = 0;
+            changeStatus("connected");
             // Re-apply EVERY active subscription on each (re)connect. The server
             // assigns a fresh uid per connection and has no memory of prior
             // subscriptions, so both the first connect AND browser auto-reconnects
@@ -111,11 +147,46 @@ function open() {
             }
         }
     });
+    // The native EventSource auto-reconnects on a dropped connection, firing
+    // `error` each time. Mirror Transmit's reconnect bookkeeping: surface a
+    // `disconnected` → `reconnecting` transition, count attempts, and once the
+    // cap is reached close the stream (stopping the native retry loop) and fire
+    // `onReconnectFailed`.
+    sse.addEventListener("error", () => {
+        if (STATE.status !== "reconnecting")
+            changeStatus("disconnected");
+        changeStatus("reconnecting");
+        CONFIG.onReconnectAttempt?.(STATE.reconnectAttempts + 1);
+        if (CONFIG.maxReconnectAttempts > 0 &&
+            STATE.reconnectAttempts >= CONFIG.maxReconnectAttempts) {
+            sse.close();
+            if (STATE.sse === sse)
+                STATE.sse = null;
+            CONFIG.onReconnectFailed?.();
+            return;
+        }
+        STATE.reconnectAttempts++;
+    });
     // Re-attach channel listeners — a close()+reopen builds a fresh EventSource
     // that has lost the listeners wired by earlier subscribe() calls.
     for (const channel of STATE.channels.keys())
         attachChannel(sse, channel);
 }
+/** Update the status and notify every listener registered for it. */
+function changeStatus(status) {
+    STATE.status = status;
+    const set = STATE.statusListeners.get(status);
+    if (!set)
+        return;
+    for (const cb of set) {
+        try {
+            cb(status);
+        }
+        catch (err) {
+            console.warn(`[aurora/relay] status listener for ${status} threw:`, err);
+        }
+    }
+}
 /**
  * Wire one SSE listener for a channel's named broadcast events. The relay sends
  * `event: <channel>\ndata: <JSON payload>`, so each channel is its own named
@@ -150,21 +221,50 @@ function messageData(ev) {
         return ev.data;
     return null;
 }
-async function postSubscribe(channel) {
+function postSubscribe(channel) {
+    return postHandshake(CONFIG.subscribeUrl, channel);
+}
+function postUnsubscribe(channel) {
+    return postHandshake(CONFIG.unsubscribeUrl, 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
+ * itself rides along. Without both, the POST is rejected by the signed
+ * double-submit guard. Mirrors `HttpClient.#retrieveXsrfToken` /
+ * `createRequest` in `@adonisjs/transmit-client`.
+ */
+async function postHandshake(url, channel) {
     const headers = {
         "content-type": "application/json",
     };
     if (CONFIG.bearer)
         headers.authorization = `Bearer ${CONFIG.bearer}`;
-    const res = await fetch(CONFIG.subscribeUrl, {
+    const xsrf = retrieveXsrfToken();
+    if (xsrf !== null)
+        headers["x-xsrf-token"] = xsrf;
+    const res = await fetch(url, {
         method: "POST",
         headers,
         body: JSON.stringify({ uid: STATE.uid, channel }),
+        credentials: "include",
     });
     if (!res.ok) {
         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=([^;]*)/);
+    return match ? decodeURIComponent(match[1]) : null;
+}
 function safeJson(raw) {
     if (typeof raw !== "string")
         return null;

package/dist/server/renderPage.d.ts

@@ -46,6 +46,12 @@ export interface RenderPageOptions {
     /**
      * Extra markup spliced into `<head>` after the importmap. Use to
      * inject `<title>`, meta tags, stylesheets.
+     *
+     * ⚠️ Injected RAW / unescaped — it IS `<head>` markup, so it cannot be
+     * HTML-escaped. Pass ONLY trusted, server-authored strings; NEVER
+     * interpolate request/user input into it (that is an HTML-injection
+     * sink). Build any dynamic head content through an escaping helper
+     * upstream before handing it here.
      */
     headExtra?: string;
     /**

package/dist/server/serveAssets.js

@@ -33,7 +33,10 @@ const CONTENT_TYPES = {
     ".json": "application/json; charset=utf-8",
 };
 export function serveAssets(options) {
-    const root = options.root;
+    // Normalize the root ONCE so the lexical containment gate below compares
+    // like-for-like: a raw root with a trailing slash or a non-normalized
+    // segment would never match the resolved request path → spurious 403s.
+    const root = resolvePath(options.root);
     const cacheControl = options.cacheControl ?? "public, max-age=60";
     // Canonicalize the root ONCE at handler creation. The realpath check
     // below compares against this canonical form so a symlinked root

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "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",
@@ -53,14 +53,15 @@
     }
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
     "@c9up/comet": "^0.1.0",
     "@types/node": "^22.19.15",
-    "@vitest/browser": "4.1.6",
-    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/browser": "4.1.9",
+    "@vitest/browser-playwright": "4.1.9",
     "happy-dom": "^15.11.7",
     "playwright": "^1.61.1",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "vitest": "4.1.9"
   },
   "files": [
     "LICENSE",

package/src/AuroraProvider.ts

@@ -30,7 +30,7 @@ import { renderToString } from "./ssr.js";
 
 interface AuroraContainer {
 	singleton(token: unknown, factory: () => unknown): void;
-	resolve<T = unknown>(token: unknown): T;
+	resolve<T = unknown>(token: unknown): Promise<T>;
 	has(token: unknown): boolean;
 }
 interface AuroraConfigStore {
@@ -52,9 +52,9 @@ export default class AuroraProvider {
 	constructor(protected app: AuroraAppContext) {}
 
 	register(): void {
-		this.app.container.singleton(AuroraManager, () => {
+		this.app.container.singleton(AuroraManager, async () => {
 			const raw = this.app.config.get<AuroraManagerConfig>("aurora");
-			const config = this.resolveConfig(raw);
+			const config = await this.resolveConfig(raw);
 			const manager = new AuroraManager(config);
 			setAurora(manager);
 			return manager;
@@ -72,7 +72,8 @@ export default class AuroraProvider {
 	async boot(): Promise<void> {
 		// Force-resolve so `setAurora` runs even if the app never
 		// touches the singleton from a preload.
-		const manager = this.app.container.resolve<AuroraManager>(AuroraManager);
+		const manager =
+			await this.app.container.resolve<AuroraManager>(AuroraManager);
 		setAurora(manager);
 	}
 
@@ -89,8 +90,9 @@ export default class AuroraProvider {
 		// failures (slug collision, AuroraManager crash) propagate with a stack
 		// instead of being misread as "the asset routes just stopped mounting".
 		if (!this.app.container.has("router")) return;
-		const router = this.app.container.resolve<ReamRouter>("router");
-		const manager = this.app.container.resolve<AuroraManager>(AuroraManager);
+		const router = await this.app.container.resolve<ReamRouter>("router");
+		const manager =
+			await this.app.container.resolve<AuroraManager>(AuroraManager);
 		// Mount paths derive from the configured `assetsPrefix` (default
 		// `/__assets`) — set `config.aurora.assetsPrefix` to change the scheme.
 		router.get(
@@ -125,10 +127,10 @@ export default class AuroraProvider {
 	 * one (Ream does, since v0.x — see Ignitor); other hosts get the
 	 * `process.cwd()` fallback.
 	 */
-	private resolveConfig(
+	private async resolveConfig(
 		raw: AuroraManagerConfig | undefined,
-	): AuroraManagerConfig {
-		const appRoot = this.readAppRoot();
+	): Promise<AuroraManagerConfig> {
+		const appRoot = await this.readAppRoot();
 		const userRoot = raw?.pages?.root;
 		const root =
 			typeof userRoot === "string" && userRoot.length > 0
@@ -142,9 +144,9 @@ export default class AuroraProvider {
 		};
 	}
 
-	private readAppRoot(): string {
+	private async readAppRoot(): Promise<string> {
 		try {
-			const raw = this.app.container.resolve<unknown>("appRoot");
+			const raw = await this.app.container.resolve<unknown>("appRoot");
 			if (raw instanceof URL) return fileURLToPath(raw);
 			if (typeof raw === "string") return raw;
 		} catch {

package/src/Pages.ts

@@ -62,7 +62,11 @@ export class Pages {
 	private readonly registry = new Map<string, PageFactory>();
 
 	constructor(config: PagesConfig) {
-		this.root = config.root;
+		// Normalize the root ONCE so the `startsWith(root + sep)` containment
+		// check below compares like-for-like against the resolved page path.
+		// A raw root with a trailing slash, a relative segment, or `..` would
+		// otherwise never match the resolved absolute path → spurious 403s.
+		this.root = resolvePath(config.root);
 		this.urlPrefix = (config.urlPrefix ?? "/__assets/pages").replace(/\/$/, "");
 		this.extension = config.extension ?? ".js";
 	}

package/src/browser.ts

@@ -7,7 +7,7 @@
  * client barrel.
  */
 
-import { effect, type Signal, signal } from "./reactive.js";
+import { effect, onCleanup, type Signal, signal } from "./reactive.js";
 
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export function redirect(url: string): void {
@@ -226,14 +226,21 @@ export function persistedSignal<T>(
 		typeof window !== "undefined"
 	) {
 		const fullKey = store.fullKey(key);
-		window.addEventListener("storage", (event) => {
+		const onStorage = (event: StorageEvent) => {
 			if (event.key !== fullKey || event.newValue === null) return;
 			try {
 				sig(JSON.parse(event.newValue) as T);
 			} catch {
 				// Ignore a malformed cross-tab write.
 			}
-		});
+		};
+		window.addEventListener("storage", onStorage);
+		// Tie the listener to the owning reactive scope so a persistedSignal
+		// created in a component's setup removes it on dispose (matching the
+		// mirror effect above — the JSDoc promises disposal-with-the-component).
+		// At module scope onCleanup is a no-op, so the listener lives for the
+		// page lifetime, as intended for a shared module-level signal.
+		onCleanup(() => window.removeEventListener("storage", onStorage));
 	}
 
 	return sig;

package/src/middleware.ts

@@ -30,7 +30,7 @@ export interface AuroraRequestRenderer {
 
 /** Request context the middleware needs: render target + optional resolver/slot. */
 interface AuroraMiddlewareContext extends RenderHttpContext {
-	containerResolver?: { make(token: unknown): unknown };
+	containerResolver?: { make(token: unknown): Promise<unknown> };
 	aurora?: AuroraRequestRenderer;
 }
 
@@ -44,11 +44,11 @@ function isManager(value: unknown): value is AuroraManager {
 	);
 }
 
-function resolveManager(
-	resolver: { make(token: unknown): unknown } | undefined,
-): AuroraManager | undefined {
+async function resolveManager(
+	resolver: { make(token: unknown): Promise<unknown> } | undefined,
+): Promise<AuroraManager | undefined> {
 	try {
-		const resolved = resolver?.make("aurora");
+		const resolved = await resolver?.make("aurora");
 		return isManager(resolved) ? resolved : undefined;
 	} catch {
 		return undefined;
@@ -59,11 +59,11 @@ function resolveManager(
  * 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(
+export async function auroraContext(
 	ctx: AuroraMiddlewareContext,
 	next: () => Promise<void>,
 ): Promise<void> {
-	const manager = resolveManager(ctx.containerResolver);
+	const manager = await resolveManager(ctx.containerResolver);
 	if (manager) {
 		ctx.aurora = {
 			render: (name, props, options) =>

package/src/relay.ts

@@ -18,8 +18,24 @@
  * `EventSource` being undefined.
  */
 
+/**
+ * Connection lifecycle status. Mirrors `@adonisjs/transmit-client`'s
+ * `TransmitStatus` (minus `initializing`, which the singleton never
+ * exposes — the first `relay()` call opens straight into `connecting`).
+ */
+export type RelayStatus =
+	| "connecting"
+	| "connected"
+	| "disconnected"
+	| "reconnecting";
+
 export interface RelayClient {
 	subscribe<E>(channel: string, handler: (event: E) => void): () => void;
+	/**
+	 * Register a connection-status listener. Returns a detacher. Mirrors
+	 * `transmit.on('connected' | 'disconnected' | ...)`.
+	 */
+	on(status: RelayStatus, callback: (status: RelayStatus) => void): () => void;
 	close(): void;
 }
 
@@ -29,6 +45,12 @@ interface RelayState {
 	channels: Map<string, Set<(event: unknown) => void>>;
 	/** Channels we've already wired an SSE listener for on the current sse. */
 	attached: Set<string>;
+	/** Current connection status. */
+	status: RelayStatus;
+	/** Status listeners, keyed by the status they fire on. */
+	statusListeners: Map<RelayStatus, Set<(status: RelayStatus) => void>>;
+	/** Consecutive failed-connection count, reset on every `connected` frame. */
+	reconnectAttempts: number;
 }
 
 const STATE: RelayState = {
@@ -36,6 +58,9 @@ const STATE: RelayState = {
 	uid: null,
 	channels: new Map(),
 	attached: new Set(),
+	status: "connecting",
+	statusListeners: new Map(),
+	reconnectAttempts: 0,
 };
 
 export interface RelayOptions {
@@ -43,26 +68,55 @@ export interface RelayOptions {
 	sseUrl?: string;
 	/** Subscribe POST endpoint. Defaults to `/__relay/subscribe`. */
 	subscribeUrl?: string;
+	/** Unsubscribe POST endpoint. Defaults to `/__relay/unsubscribe`. */
+	unsubscribeUrl?: string;
 	/** Optional bearer token (for guarded relay routes). */
 	bearer?: string;
+	/**
+	 * Give up after this many consecutive reconnect attempts. Default 5
+	 * (Transmit parity). `0` disables the cap — the browser's native
+	 * EventSource keeps retrying forever.
+	 */
+	maxReconnectAttempts?: number;
+	/** Fired before each reconnect attempt with the 1-based attempt count. */
+	onReconnectAttempt?: (attempt: number) => void;
+	/** Fired once when `maxReconnectAttempts` is exhausted and we give up. */
+	onReconnectFailed?: () => void;
 }
 
-let CONFIG: Required<RelayOptions> = {
+interface RelayConfigResolved {
+	sseUrl: string;
+	subscribeUrl: string;
+	unsubscribeUrl: string;
+	bearer: string;
+	maxReconnectAttempts: number;
+	onReconnectAttempt?: (attempt: number) => void;
+	onReconnectFailed?: () => void;
+}
+
+let CONFIG: RelayConfigResolved = {
 	sseUrl: "/__relay/events",
 	subscribeUrl: "/__relay/subscribe",
+	unsubscribeUrl: "/__relay/unsubscribe",
 	bearer: "",
+	maxReconnectAttempts: 5,
 };
 
 /**
- * Configure the relay endpoints + bearer. Call once at boot if you
- * need to override the defaults. Multiple calls overwrite — last call
- * wins.
+ * Configure the relay endpoints + bearer + reconnect policy. Call once
+ * at boot if you need to override the defaults. Multiple calls overwrite
+ * — last call wins.
  */
 export function configureRelay(options: RelayOptions): void {
 	CONFIG = {
 		sseUrl: options.sseUrl ?? CONFIG.sseUrl,
 		subscribeUrl: options.subscribeUrl ?? CONFIG.subscribeUrl,
+		unsubscribeUrl: options.unsubscribeUrl ?? CONFIG.unsubscribeUrl,
 		bearer: options.bearer ?? CONFIG.bearer,
+		maxReconnectAttempts:
+			options.maxReconnectAttempts ?? CONFIG.maxReconnectAttempts,
+		onReconnectAttempt: options.onReconnectAttempt ?? CONFIG.onReconnectAttempt,
+		onReconnectFailed: options.onReconnectFailed ?? CONFIG.onReconnectFailed,
 	};
 }
 
@@ -103,11 +157,36 @@ const CLIENT: RelayClient = {
 			});
 		}
 
-		// Detacher — only removes the local listener. The server-side
-		// subscription stays open; closing it would interrupt other
-		// listeners on the same channel.
+		// Detacher — removes the local listener. When it was the LAST handler
+		// on the channel, the server-side subscription is dropped too (POST
+		// /__relay/unsubscribe), so the server stops streaming a channel
+		// nobody's listening to. Other channels / other listeners are
+		// untouched.
 		return () => {
 			handlers?.delete(adapted);
+			if (handlers && handlers.size === 0) {
+				STATE.channels.delete(channel);
+				if (STATE.uid) {
+					postUnsubscribe(channel).catch((err: unknown) => {
+						console.warn(
+							`[aurora/relay] unsubscribe from ${channel} failed:`,
+							err,
+						);
+					});
+				}
+			}
+		};
+	},
+
+	on(status, callback) {
+		let set = STATE.statusListeners.get(status);
+		if (!set) {
+			set = new Set();
+			STATE.statusListeners.set(status, set);
+		}
+		set.add(callback);
+		return () => {
+			set?.delete(callback);
 		};
 	},
 
@@ -119,6 +198,7 @@ const CLIENT: RelayClient = {
 		STATE.uid = null;
 		STATE.channels.clear();
 		STATE.attached.clear();
+		STATE.reconnectAttempts = 0;
 	},
 };
 
@@ -126,11 +206,16 @@ function open(): void {
 	const sse = new EventSource(CONFIG.sseUrl);
 	STATE.sse = sse;
 	STATE.attached = new Set();
+	changeStatus("connecting");
 
 	sse.addEventListener("connected", (ev) => {
 		const data = safeJson<{ uid?: string }>(messageData(ev));
 		if (data && typeof data.uid === "string") {
 			STATE.uid = data.uid;
+			// A successful (re)connect clears the failure counter and flips the
+			// status back to `connected`.
+			STATE.reconnectAttempts = 0;
+			changeStatus("connected");
 			// Re-apply EVERY active subscription on each (re)connect. The server
 			// assigns a fresh uid per connection and has no memory of prior
 			// subscriptions, so both the first connect AND browser auto-reconnects
@@ -147,11 +232,46 @@ function open(): void {
 		}
 	});
 
+	// The native EventSource auto-reconnects on a dropped connection, firing
+	// `error` each time. Mirror Transmit's reconnect bookkeeping: surface a
+	// `disconnected` → `reconnecting` transition, count attempts, and once the
+	// cap is reached close the stream (stopping the native retry loop) and fire
+	// `onReconnectFailed`.
+	sse.addEventListener("error", () => {
+		if (STATE.status !== "reconnecting") changeStatus("disconnected");
+		changeStatus("reconnecting");
+		CONFIG.onReconnectAttempt?.(STATE.reconnectAttempts + 1);
+		if (
+			CONFIG.maxReconnectAttempts > 0 &&
+			STATE.reconnectAttempts >= CONFIG.maxReconnectAttempts
+		) {
+			sse.close();
+			if (STATE.sse === sse) STATE.sse = null;
+			CONFIG.onReconnectFailed?.();
+			return;
+		}
+		STATE.reconnectAttempts++;
+	});
+
 	// Re-attach channel listeners — a close()+reopen builds a fresh EventSource
 	// that has lost the listeners wired by earlier subscribe() calls.
 	for (const channel of STATE.channels.keys()) attachChannel(sse, channel);
 }
 
+/** Update the status and notify every listener registered for it. */
+function changeStatus(status: RelayStatus): void {
+	STATE.status = status;
+	const set = STATE.statusListeners.get(status);
+	if (!set) return;
+	for (const cb of set) {
+		try {
+			cb(status);
+		} catch (err) {
+			console.warn(`[aurora/relay] status listener for ${status} threw:`, err);
+		}
+	}
+}
+
 /**
  * Wire one SSE listener for a channel's named broadcast events. The relay sends
  * `event: <channel>\ndata: <JSON payload>`, so each channel is its own named
@@ -183,21 +303,51 @@ function messageData(ev: Event): string | null {
 	return null;
 }
 
-async function postSubscribe(channel: string): Promise<void> {
+function postSubscribe(channel: string): Promise<void> {
+	return postHandshake(CONFIG.subscribeUrl, channel);
+}
+
+function postUnsubscribe(channel: string): Promise<void> {
+	return postHandshake(CONFIG.unsubscribeUrl, 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
+ * itself rides along. Without both, the POST is rejected by the signed
+ * double-submit guard. Mirrors `HttpClient.#retrieveXsrfToken` /
+ * `createRequest` in `@adonisjs/transmit-client`.
+ */
+async function postHandshake(url: string, channel: string): Promise<void> {
 	const headers: Record<string, string> = {
 		"content-type": "application/json",
 	};
 	if (CONFIG.bearer) headers.authorization = `Bearer ${CONFIG.bearer}`;
-	const res = await fetch(CONFIG.subscribeUrl, {
+	const xsrf = retrieveXsrfToken();
+	if (xsrf !== null) headers["x-xsrf-token"] = xsrf;
+	const res = await fetch(url, {
 		method: "POST",
 		headers,
 		body: JSON.stringify({ uid: STATE.uid, channel }),
+		credentials: "include",
 	});
 	if (!res.ok) {
 		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(): string | null {
+	if (typeof document === "undefined") return null;
+	const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
+	return match ? decodeURIComponent(match[1]) : null;
+}
+
 function safeJson<T>(raw: unknown): T | null {
 	if (typeof raw !== "string") return null;
 	try {

package/src/server/renderPage.ts

@@ -52,6 +52,12 @@ export interface RenderPageOptions {
 	/**
 	 * Extra markup spliced into `<head>` after the importmap. Use to
 	 * inject `<title>`, meta tags, stylesheets.
+	 *
+	 * ⚠️ Injected RAW / unescaped — it IS `<head>` markup, so it cannot be
+	 * HTML-escaped. Pass ONLY trusted, server-authored strings; NEVER
+	 * interpolate request/user input into it (that is an HTML-injection
+	 * sink). Build any dynamic head content through an escaping helper
+	 * upstream before handing it here.
 	 */
 	headExtra?: string;
 	/**

package/src/server/serveAssets.ts

@@ -72,7 +72,10 @@ export interface ServeAssetsOptions {
 export function serveAssets(
 	options: ServeAssetsOptions,
 ): (ctx: AssetsHttpContext) => Promise<void> {
-	const root = options.root;
+	// Normalize the root ONCE so the lexical containment gate below compares
+	// like-for-like: a raw root with a trailing slash or a non-normalized
+	// segment would never match the resolved request path → spurious 403s.
+	const root = resolvePath(options.root);
 	const cacheControl = options.cacheControl ?? "public, max-age=60";
 	// Canonicalize the root ONCE at handler creation. The realpath check
 	// below compares against this canonical form so a symlinked root