@c9up/aurora 0.1.9 → 0.1.11

package/dist/liveRouter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Live router (Stage 4) — the server-side orchestration that ties the session
+ * registry to the relay transport, transport-agnostically.
+ *
+ *   - `mount(name, ownerId)` → mounts a session, wires its patches to a
+ *     per-session channel, returns `{ id, channel, html }` for the HTTP
+ *     response (the client renders `html` and subscribes to `channel`).
+ *   - `event(id, event, payload)` → routes an inbound client event (a relay
+ *     POST) to the session; its patches auto-broadcast on the channel.
+ *   - `disconnect(ownerId)` → disposes every session that owner opened.
+ *
+ * Pure orchestration over the duck-typed registry + relay — node-free, no
+ * `@c9up/ream` / `@c9up/relay` import. The thin HTTP/relay wiring (register the
+ * POST route, hook relay's disconnect) is the provider/app's job and feeds
+ * these three methods.
+ */
+import { type RelayBroadcaster } from "./liveBroadcast.js";
+import type { LiveRegistry } from "./liveRegistry.js";
+/** What a client needs after mounting: render this `html`, subscribe to `channel`. */
+export interface LiveMount {
+    id: string;
+    channel: string;
+    html: string;
+}
+export interface LiveRouter {
+    /** Mount a session, wire its channel, return the initial render + ids. */
+    mount(name: string, ownerId: string): LiveMount;
+    /** Route a client event to its session. Returns false if the id is unknown. */
+    event(id: string, event: string, payload?: unknown): boolean;
+    /** Tear down every session an owner opened (call on relay disconnect). */
+    disconnect(ownerId: string): void;
+    /** The relay channel a session id broadcasts on. */
+    channelFor(id: string): string;
+}
+/**
+ * Create the live router over a session registry + a relay broadcaster. One per
+ * app. The per-session channel is `live/<id>`; gate subscription with
+ * `relay.authorize("live/*", …)` if the components carry sensitive state.
+ */
+export declare function createLiveRouter(registry: LiveRegistry, relay: RelayBroadcaster): LiveRouter;

package/dist/liveRouter.js

@@ -0,0 +1,46 @@
+/**
+ * Live router (Stage 4) — the server-side orchestration that ties the session
+ * registry to the relay transport, transport-agnostically.
+ *
+ *   - `mount(name, ownerId)` → mounts a session, wires its patches to a
+ *     per-session channel, returns `{ id, channel, html }` for the HTTP
+ *     response (the client renders `html` and subscribes to `channel`).
+ *   - `event(id, event, payload)` → routes an inbound client event (a relay
+ *     POST) to the session; its patches auto-broadcast on the channel.
+ *   - `disconnect(ownerId)` → disposes every session that owner opened.
+ *
+ * Pure orchestration over the duck-typed registry + relay — node-free, no
+ * `@c9up/ream` / `@c9up/relay` import. The thin HTTP/relay wiring (register the
+ * POST route, hook relay's disconnect) is the provider/app's job and feeds
+ * these three methods.
+ */
+import { connectPatches } from "./liveBroadcast.js";
+/**
+ * Create the live router over a session registry + a relay broadcaster. One per
+ * app. The per-session channel is `live/<id>`; gate subscription with
+ * `relay.authorize("live/*", …)` if the components carry sensitive state.
+ */
+export function createLiveRouter(registry, relay) {
+    const channelFor = (id) => `live/${id}`;
+    return {
+        mount(name, ownerId) {
+            const { id, session } = registry.mount(name, ownerId);
+            const channel = channelFor(id);
+            // Patches flow to the channel; `disconnect` → registry disposes the
+            // session, which clears its patch listener (stops broadcasting).
+            connectPatches(session, relay, channel);
+            return { id, channel, html: session.renderToString() };
+        },
+        event(id, event, payload) {
+            const session = registry.get(id);
+            if (!session)
+                return false;
+            session.dispatch(event, payload);
+            return true;
+        },
+        disconnect(ownerId) {
+            registry.disposeOwner(ownerId);
+        },
+        channelFor,
+    };
+}

package/dist/liveServer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Live server wiring (Stage 6) — register the inbound-event HTTP route that
+ * feeds the {@link LiveRouter}. The client POSTs `{ id, event, payload }` here;
+ * the route dispatches it to the session, whose patches broadcast over relay.
+ *
+ * Agnostic: the host HTTP router + context are DUCK-TYPED (a `post(path,
+ * handler)` router; a `ctx.request.body()` / `ctx.response` context) — no
+ * `@c9up/ream` import. Mirrors how warden/blackhole middleware read the ctx.
+ * Mount (render + ids) is done by the page handler via `liveRouter.mount`;
+ * disconnect is wired by the app: relay's disconnect → `liveRouter.disconnect`.
+ */
+import type { LiveRouter } from "./liveRouter.js";
+/** The slice of the host HTTP router this needs. */
+export interface LiveHttpRouter {
+    post(path: string, handler: (ctx: LiveHttpContext) => unknown): unknown;
+}
+/** The slice of the host HTTP context this needs (Ream's HttpContext satisfies it). */
+export interface LiveHttpContext {
+    request: {
+        body(): unknown;
+    };
+    response: {
+        status(code: number): unknown;
+        json(data: unknown): void;
+    };
+}
+export interface WireLiveEventsOptions {
+    /** Route path for inbound events (must match the client transport). */
+    path?: string;
+}
+/** Default inbound-event route — keep the client transport's `path` in sync. */
+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).
+ */
+export declare function wireLiveEvents(router: LiveHttpRouter, live: LiveRouter, options?: WireLiveEventsOptions): void;

package/dist/liveServer.js

@@ -0,0 +1,43 @@
+/**
+ * Live server wiring (Stage 6) — register the inbound-event HTTP route that
+ * feeds the {@link LiveRouter}. The client POSTs `{ id, event, payload }` here;
+ * the route dispatches it to the session, whose patches broadcast over relay.
+ *
+ * Agnostic: the host HTTP router + context are DUCK-TYPED (a `post(path,
+ * handler)` router; a `ctx.request.body()` / `ctx.response` context) — no
+ * `@c9up/ream` import. Mirrors how warden/blackhole middleware read the ctx.
+ * Mount (render + ids) is done by the page handler via `liveRouter.mount`;
+ * disconnect is wired by the app: relay's disconnect → `liveRouter.disconnect`.
+ */
+/** Structural guard for the POST body — no casts (`in`-narrowing + typeof). */
+function isLiveEventBody(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("id" in value) || !("event" in value))
+        return false;
+    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";
+/**
+ * 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).
+ */
+export function wireLiveEvents(router, live, options = {}) {
+    const path = options.path ?? DEFAULT_LIVE_EVENT_PATH;
+    router.post(path, (ctx) => {
+        const body = ctx.request.body();
+        if (!isLiveEventBody(body)) {
+            ctx.response.status(400);
+            ctx.response.json({ error: "live event requires { id, event }" });
+            return;
+        }
+        const handled = live.event(body.id, body.event, body.payload);
+        if (!handled) {
+            ctx.response.status(404);
+            ctx.response.json({ error: "unknown live session" });
+            return;
+        }
+        ctx.response.json({ ok: true });
+    });
+}

package/dist/relay.js

@@ -21,6 +21,7 @@ const STATE = {
     sse: null,
     uid: null,
     channels: new Map(),
+    attached: new Set(),
 };
 let CONFIG = {
     sseUrl: "/__relay/events",
@@ -59,6 +60,11 @@ const CLIENT = {
         }
         const adapted = handler;
         handlers.add(adapted);
+        // Wire the SSE listener for this channel's NAMED events — the relay
+        // broadcasts `event: <channel>`, so a per-channel addEventListener (not
+        // the default `onmessage`) is what actually receives the payload.
+        if (STATE.sse)
+            attachChannel(STATE.sse, channel);
         // Subscribe over POST as soon as we have a uid. Before the first uid (or
         // during an auto-reconnect) the channel already lives in STATE.channels
         // and is (re-)subscribed by the `connected` handler — so the server,
@@ -82,13 +88,15 @@ const CLIENT = {
         }
         STATE.uid = null;
         STATE.channels.clear();
+        STATE.attached.clear();
     },
 };
 function open() {
     const sse = new EventSource(CONFIG.sseUrl);
     STATE.sse = sse;
+    STATE.attached = new Set();
     sse.addEventListener("connected", (ev) => {
-        const data = safeJson(ev.data);
+        const data = safeJson(messageData(ev));
         if (data && typeof data.uid === "string") {
             STATE.uid = data.uid;
             // Re-apply EVERY active subscription on each (re)connect. The server
@@ -103,22 +111,44 @@ function open() {
             }
         }
     });
-    sse.onmessage = (ev) => {
-        const data = safeJson(ev.data);
-        if (!data || typeof data.channel !== "string")
+    // 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);
+}
+/**
+ * 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
+ * event — `onmessage` (default/unnamed only) never sees them. The handler
+ * receives the broadcast payload verbatim (the value passed to
+ * `relay.broadcast(channel, payload)`).
+ */
+function attachChannel(sse, channel) {
+    if (STATE.attached.has(channel))
+        return;
+    STATE.attached.add(channel);
+    sse.addEventListener(channel, (ev) => {
+        const payload = safeJson(messageData(ev));
+        if (payload === null)
             return;
-        const handlers = STATE.channels.get(data.channel);
+        const handlers = STATE.channels.get(channel);
         if (!handlers)
             return;
         for (const handler of handlers) {
             try {
-                handler(data);
+                handler(payload);
             }
             catch (err) {
-                console.warn(`[aurora/relay] listener for ${data.channel} threw:`, err);
+                console.warn(`[aurora/relay] listener for ${channel} threw:`, err);
             }
         }
-    };
+    });
+}
+/** Read an SSE event's string `data` without an unsafe DOM cast. */
+function messageData(ev) {
+    if ("data" in ev && typeof ev.data === "string")
+        return ev.data;
+    return null;
 }
 async function postSubscribe(channel) {
     const headers = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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/AuroraProvider.ts

@@ -31,6 +31,7 @@ import { renderToString } from "./ssr.js";
 interface AuroraContainer {
 	singleton(token: unknown, factory: () => unknown): void;
 	resolve<T = unknown>(token: unknown): T;
+	has(token: unknown): boolean;
 }
 interface AuroraConfigStore {
 	get<T = unknown>(key: string): T | undefined;
@@ -76,40 +77,22 @@ export default class AuroraProvider {
 	}
 
 	async start(): Promise<void> {
-		// Asset routes are registered in `start()` — after preloads —
-		// so apps can swap aurora's pages root in a preload if they
-		// wanted to. Non-Ream hosts (no `@c9up/ream/services/router`)
-		// AND pre-`setRouter` boots (router proxy uninit) both
-		// silent-return; ANY other error (slug collision, AuroraManager
-		// crash, factory bug) propagates so real regressions surface
-		// with a stack instead of "the asset routes just stopped
-		// mounting".
-		// Variable specifier so tsc does not statically resolve the optional
-		// `@c9up/ream` peer at build time (keeps aurora agnostic /
-		// standalone-buildable). Resolved to the host router only at runtime
-		// when aurora actually runs inside Ream.
-		const routerSpecifier = "@c9up/ream/services/router";
-		let routerMod: { default: ReamRouter };
-		try {
-			routerMod = await import(routerSpecifier);
-		} catch (err) {
-			if (isModuleNotFound(err)) return;
-			throw err;
-		}
+		// Asset routes are registered in `start()` — after preloads — so apps can
+		// swap aurora's pages root in a preload if they wanted to.
+		//
+		// Resolve the host router from the container, where Ream registers it as
+		// `'router'` (Ignitor). Reading it from the container — instead of
+		// importing `@c9up/ream/services/router` — keeps aurora runtime-agnostic:
+		// a non-Ream host simply never registers `'router'`, so aurora silently
+		// skips its asset routes. The container yields the real Router instance
+		// (registered before any provider's `start()`), so route-registration
+		// 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);
-		try {
-			routerMod.default.get(
-				"/_assets/aurora/*",
-				adaptHandler(manager.auroraAssetsHandler()),
-			);
-			routerMod.default.get(
-				"/_assets/pages/*",
-				adaptHandler(manager.pageAssetsHandler()),
-			);
-		} catch (err) {
-			if (isRouterProxyUninit(err)) return;
-			throw err;
-		}
+		router.get("/_assets/aurora/*", adaptHandler(manager.auroraAssetsHandler()));
+		router.get("/_assets/pages/*", adaptHandler(manager.pageAssetsHandler()));
 	}
 
 	async ready(): Promise<void> {}
@@ -170,18 +153,3 @@ function adaptHandler(
 }) => Promise<void> {
 	return (ctx) => handler(ctx);
 }
-
-/** Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`. */
-function isModuleNotFound(err: unknown): boolean {
-	if (err === null || typeof err !== "object" || !("code" in err)) return false;
-	const { code } = err;
-	return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
-}
-
-/** Ream's router proxy throws this exact string before Ignitor wires it. */
-function isRouterProxyUninit(err: unknown): boolean {
-	return (
-		err instanceof Error &&
-		err.message.includes("Router accessed before initialization")
-	);
-}

package/src/index.ts

@@ -79,4 +79,41 @@ export {
 	auroraRoute,
 } from "./route.js";
 export { renderToString } from "./ssr.js";
+export {
+	type LiveComponentDefinition,
+	type LiveSession,
+	mountLiveSession,
+	type SlotPatch,
+} from "./live.js";
+export {
+	createLiveRegistry,
+	type LiveRegistry,
+	type LiveSessionHandle,
+} from "./liveRegistry.js";
+export {
+	connectPatches,
+	type LiveStore,
+	liveStore,
+	type RelayBroadcaster,
+} from "./liveBroadcast.js";
+export {
+	createLiveRouter,
+	type LiveMount,
+	type LiveRouter,
+} from "./liveRouter.js";
+export {
+	buildLiveTransport,
+	liveClient,
+	type LiveClientOptions,
+	type LiveClientTransport,
+	type LiveHttpPoster,
+	type RelaySubscribeClient,
+} from "./liveClient.js";
+export {
+	DEFAULT_LIVE_EVENT_PATH,
+	type LiveHttpContext,
+	type LiveHttpRouter,
+	wireLiveEvents,
+	type WireLiveEventsOptions,
+} from "./liveServer.js";
 export type { TemplateResult } from "./types.js";

package/src/live.ts

@@ -0,0 +1,132 @@
+/**
+ * Live components — server-resident reactive UI. The state lives on the server
+ * as ordinary aurora signals; this module turns a fine-grained signal change
+ * into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering the
+ * whole component. That precision — each signal already knows which template
+ * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ *
+ * This is the transport-agnostic CORE (Stage 1): mount a session, render its
+ * initial HTML, dispatch events that mutate signals, and drain / subscribe to
+ * the patches produced. Wiring patches over `@c9up/relay` (SSE down, POST up)
+ * and the thin client applier live in later stages.
+ *
+ * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`, so it
+ * sits in the main barrel alongside the rest of aurora's runtime.
+ */
+
+import { effect, isSignal } from "./reactive.js";
+import { renderToString } from "./ssr.js";
+import type { TemplateResult } from "./types.js";
+
+/** A precise per-slot update: slot index (positional in the template) + value. */
+export interface SlotPatch {
+	slot: number;
+	value: string;
+}
+
+/** A live component: its reactive view + named event handlers that mutate it. */
+export interface LiveComponentDefinition {
+	/** The reactive view. Slots reading signals become live-patchable. */
+	view: TemplateResult;
+	/**
+	 * Event handlers, by name. A client interaction (`@click="increment"`)
+	 * dispatches one of these; it mutates the component's signals, which the
+	 * patch tracker turns into a `{slot, value}` patch.
+	 */
+	handlers?: Record<string, (payload?: unknown) => void>;
+}
+
+/** A mounted live component instance — one per connected client session. */
+export interface LiveSession {
+	/** Initial server-side render (the first full-HTML response). */
+	renderToString(): string;
+	/** Run a named handler (mutates signals); emits a patch for the batch. */
+	dispatch(event: string, payload?: unknown): void;
+	/** Collect + clear the patches accumulated since the last drain (pull model). */
+	drainPatches(): SlotPatch[];
+	/**
+	 * Subscribe to patches as they are produced (push model — what the relay
+	 * transport hooks into). Use `onPatch` OR `drainPatches`, not both.
+	 */
+	onPatch(listener: (patch: SlotPatch[]) => void): () => void;
+	/** Stop every effect — call on client disconnect to free the session. */
+	dispose(): void;
+}
+
+/**
+ * Mount a live session from a definition factory. Call once per connected
+ * client: the factory's signals become that session's private state. To SHARE
+ * state across sessions, close the factory over a signal created OUTSIDE it —
+ * every session then reads the same signal and patches on its change.
+ */
+export function mountLiveSession(
+	factory: () => LiveComponentDefinition,
+): LiveSession {
+	const { view, handlers = {} } = factory();
+	const listeners = new Set<(patch: SlotPatch[]) => void>();
+	// slot → latest value. `pending` = current (un-flushed) batch; `buffer` =
+	// accumulated for pull consumers. Both keyed by slot so repeated writes in
+	// one batch collapse to the last value.
+	const pending = new Map<number, string>();
+	const buffer = new Map<number, string>();
+	let priming = true;
+	let flushScheduled = false;
+
+	const flush = (): void => {
+		flushScheduled = false;
+		if (pending.size === 0) return;
+		const patch: SlotPatch[] = [];
+		for (const [slot, value] of pending) {
+			patch.push({ slot, value });
+			buffer.set(slot, value);
+		}
+		pending.clear();
+		for (const listener of listeners) listener(patch);
+	};
+
+	const scheduleFlush = (): void => {
+		if (flushScheduled) return;
+		flushScheduled = true;
+		queueMicrotask(flush);
+	};
+
+	// One fine-grained effect per reactive slot. The priming run only
+	// subscribes; later runs (a signal changed) record the slot's new value.
+	const stops = view.values.map((value, slot) => {
+		if (!isSignal(value) && typeof value !== "function") return () => {};
+		return effect(() => {
+			const next = String((value as () => unknown)());
+			if (priming) return;
+			pending.set(slot, next);
+			scheduleFlush();
+		});
+	});
+	priming = false;
+
+	return {
+		renderToString: () => renderToString(view),
+		dispatch(event, payload) {
+			const handler = handlers[event];
+			if (!handler) return;
+			handler(payload);
+			flush(); // synchronous — one patch per dispatch (batches the handler's writes)
+		},
+		drainPatches() {
+			flush();
+			const patch: SlotPatch[] = [];
+			for (const [slot, value] of buffer) patch.push({ slot, value });
+			buffer.clear();
+			return patch;
+		},
+		onPatch(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		dispose() {
+			for (const stop of stops) stop();
+			listeners.clear();
+			pending.clear();
+			buffer.clear();
+		},
+	};
+}

package/src/liveBroadcast.ts

@@ -0,0 +1,85 @@
+/**
+ * Live broadcast (Stage 3) — pipe live-component patches onto a relay channel,
+ * and the SHARED-store primitive that makes live components multiplayer.
+ *
+ * aurora stays framework-agnostic: it DUCK-TYPES a {@link RelayBroadcaster}
+ * (just `broadcast(channel, data)`) and never imports `@c9up/relay`. The app
+ * passes its relay instance. Channel authorization (who may subscribe) is the
+ * relay's job — configure it with `relay.authorize(channel, …)`; aurora only
+ * pushes patches.
+ *
+ * Per-session use: `connectPatches(session, relay, "live/<id>")`.
+ * Shared/multiplayer use: `liveStore(factory, relay, "room/<id>")` — ONE
+ * server-side instance whose state is shared by every client on the channel;
+ * one mutation → one patch computed once → relay fans it out to all subscribers
+ * (O(1) compute, O(N) network).
+ */
+
+import {
+	type LiveComponentDefinition,
+	type LiveSession,
+	mountLiveSession,
+	type SlotPatch,
+} from "./live.js";
+
+/**
+ * Minimal relay surface aurora needs. The real `@c9up/relay` `Relay` satisfies
+ * it (`broadcast(channel, data) → recipient count`); aurora never imports it.
+ */
+export interface RelayBroadcaster {
+	broadcast(channel: string, data: unknown): number;
+}
+
+/**
+ * Pipe a session's patches onto a relay channel as they are produced. Returns
+ * an unsubscribe. Each patch becomes one `broadcast(channel, patch)`.
+ */
+export function connectPatches(
+	session: LiveSession,
+	relay: RelayBroadcaster,
+	channel: string,
+): () => void {
+	return session.onPatch((patch: SlotPatch[]) => {
+		relay.broadcast(channel, patch);
+	});
+}
+
+/**
+ * A shared, broadcast-backed live store — the multiplayer primitive. One
+ * server-side instance; every client on `channel` renders its initial HTML and
+ * subscribes for patches. A `dispatch` mutates the shared signals ONCE; the
+ * resulting patch is broadcast to the whole channel.
+ */
+export interface LiveStore {
+	/** The relay channel this store broadcasts on. */
+	readonly channel: string;
+	/** Current shared-state HTML — served to each client that joins. */
+	renderToString(): string;
+	/** Run a handler that mutates the shared state → one broadcast patch. */
+	dispatch(event: string, payload?: unknown): void;
+	/** Stop broadcasting + free the underlying session. */
+	dispose(): void;
+}
+
+/**
+ * Create a shared live store. Signals declared inside `factory` are the SHARED
+ * state (one instance, not per-client). Pair with `relay.authorize(channel, …)`
+ * to gate who may subscribe.
+ */
+export function liveStore(
+	factory: () => LiveComponentDefinition,
+	relay: RelayBroadcaster,
+	channel: string,
+): LiveStore {
+	const session = mountLiveSession(factory);
+	const off = connectPatches(session, relay, channel);
+	return {
+		channel,
+		renderToString: () => session.renderToString(),
+		dispatch: (event, payload) => session.dispatch(event, payload),
+		dispose: () => {
+			off();
+			session.dispose();
+		},
+	};
+}