@c9up/aurora 0.1.10 → 0.1.11

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.10",
+  "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/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();
+		},
+	};
+}

package/src/liveClient.ts

@@ -0,0 +1,115 @@
+/**
+ * Live client runtime (Stage 5) — the thin browser side of live components.
+ *
+ * It HYDRATES the server-rendered HTML with mirror signals (aurora's real
+ * `hydrate`), then:
+ *   - applies inbound patches by SETTING the mirror signal at the patched slot
+ *     → aurora's fine-grained binding updates the exact DOM node (no bespoke
+ *     DOM patcher; the isomorphic renderer IS the applier);
+ *   - forwards interactions declared with `data-live-click="<event>"` to the
+ *     server via the injected transport.
+ *
+ * Transport-agnostic: `subscribe` (relay SSE) and `post` (HTTP up) are injected,
+ * so aurora never imports `@c9up/relay` or an HTTP client here. In an app, wire
+ * `subscribe` to `@c9up/aurora/relay`'s `relay().subscribe` and `post` to an
+ * `HttpClient`. Browser-only (uses the DOM) — part of the client barrel.
+ */
+
+import { hydrate } from "./hydrate.js";
+import { isSignal } from "./reactive.js";
+import type { SlotPatch } from "./live.js";
+import type { TemplateResult } from "./types.js";
+
+/** The transport the live client needs: a patch subscription + an event POST. */
+export interface LiveClientTransport {
+	/** Subscribe to a channel's patches (relay SSE). Returns an unsubscribe. */
+	subscribe(channel: string, handler: (patch: SlotPatch[]) => void): () => void;
+	/** Send a client event to the server (HTTP POST up). */
+	post(id: string, event: string, payload?: unknown): void;
+}
+
+export interface LiveClientOptions {
+	/** The element holding the server-rendered HTML to adopt. */
+	container: Element;
+	/** The client view (same template as the server; its signals are mirrors). */
+	factory: () => TemplateResult;
+	/** Ids from the server's mount response. */
+	mount: { id: string; channel: string };
+	transport: LiveClientTransport;
+}
+
+/**
+ * Start the live client for one mounted component. Returns a disposer that
+ * unsubscribes, removes the event listener, and tears down the hydration.
+ *
+ * Patches set writable signal slots; derived slots recompute locally from the
+ * base signals they read (aurora re-evaluates them) — so the server's
+ * base-signal patch is enough. (Derived-only slots with no mirrored base are an
+ * étape-6 refinement.)
+ *
+ * Authoring rule (aurora hydration): a reactive text slot must be the SOLE
+ * content of its element — write `Count: <span>${count}</span>`, not
+ * `Count: ${count}`. SSR merges adjacent static+dynamic text into one node,
+ * which hydration cannot re-split; isolating the slot keeps adopt + patch exact.
+ */
+export function liveClient(opts: LiveClientOptions): () => void {
+	const view = opts.factory();
+	const disposeHydrate = hydrate(opts.container, () => view);
+
+	const off = opts.transport.subscribe(opts.mount.channel, (patch) => {
+		for (const { slot, value } of patch) {
+			const sig = view.values[slot];
+			if (isSignal(sig)) (sig as (v: string) => void)(value);
+		}
+	});
+
+	const onClick = (event: Event): void => {
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		const el = target.closest("[data-live-click]");
+		if (el) opts.transport.post(opts.mount.id, el.getAttribute("data-live-click") ?? "");
+	};
+	opts.container.addEventListener("click", onClick);
+
+	return () => {
+		off();
+		opts.container.removeEventListener("click", onClick);
+		disposeHydrate();
+	};
+}
+
+/** The relay client slice the transport needs (`@c9up/aurora/relay` satisfies it). */
+export interface RelaySubscribeClient {
+	subscribe<E>(channel: string, handler: (event: E) => void): () => void;
+}
+
+/** The HTTP client slice the transport needs (aurora's `HttpClient` satisfies it). */
+export interface LiveHttpPoster {
+	post(url: string, body: unknown): unknown;
+}
+
+/**
+ * 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.
+ *
+ * @example
+ *   import { relay } from '@c9up/aurora/relay'
+ *   import { HttpClient, buildLiveTransport, liveClient } from '@c9up/aurora'
+ *   const transport = buildLiveTransport(relay(), new HttpClient())
+ *   liveClient({ container, factory, mount, transport })
+ */
+export function buildLiveTransport(
+	relayClient: RelaySubscribeClient,
+	http: LiveHttpPoster,
+	options: { path?: string } = {},
+): LiveClientTransport {
+	const path = options.path ?? "/_live/event";
+	return {
+		subscribe: (channel, handler) =>
+			relayClient.subscribe<SlotPatch[]>(channel, handler),
+		post: (id, event, payload) => {
+			void http.post(path, { id, event, payload });
+		},
+	};
+}

package/src/liveRegistry.ts

@@ -0,0 +1,112 @@
+/**
+ * Live session registry (Stage 2) — the lifecycle layer for live components.
+ *
+ * Holds component DEFINITIONS by name (like the Pages registry), mounts a fresh
+ * {@link LiveSession} per connected client, tracks ownership so every session a
+ * client opened can be torn down at once on disconnect, and exposes lookup so
+ * an inbound event reaches the right session.
+ *
+ * The transport stage drives it: connect → `mount(name, uid)`; event →
+ * `get(id)?.dispatch(...)`; disconnect → `disposeOwner(uid)`. Transport-agnostic
+ * and node-free (only `mountLiveSession` + `crypto.randomUUID`, both isomorphic).
+ */
+
+import {
+	type LiveComponentDefinition,
+	type LiveSession,
+	mountLiveSession,
+} from "./live.js";
+
+/** A mounted instance: its id, the owner (e.g. relay uid), and the session. */
+export interface LiveSessionHandle {
+	id: string;
+	ownerId: string;
+	session: LiveSession;
+}
+
+export interface LiveRegistry {
+	/** Register a live component definition under `name` (the "live class"). */
+	define(name: string, factory: () => LiveComponentDefinition): void;
+	/** True if `name` is registered. */
+	has(name: string): boolean;
+	/**
+	 * Mount a fresh session of `name` owned by `ownerId`. Each call gets its own
+	 * per-session signals. Throws if `name` is unknown — an unmountable component
+	 * must fail loudly, never silently serve nothing.
+	 */
+	mount(name: string, ownerId: string): LiveSessionHandle;
+	/** Look up a live session by instance id. */
+	get(id: string): LiveSession | undefined;
+	/** Dispose one session instance (frees its effects). */
+	dispose(id: string): void;
+	/** Dispose EVERY session a given owner opened — call on disconnect. */
+	disposeOwner(ownerId: string): void;
+	/** Dispose all sessions (shutdown). */
+	disposeAll(): void;
+	/** Number of live sessions currently mounted (diagnostics / tests). */
+	size(): number;
+}
+
+/** Create an isolated live-session registry (one per app / per relay instance). */
+export function createLiveRegistry(): LiveRegistry {
+	const defs = new Map<string, () => LiveComponentDefinition>();
+	const sessions = new Map<string, LiveSessionHandle>();
+	const byOwner = new Map<string, Set<string>>();
+
+	const dispose = (id: string): void => {
+		const handle = sessions.get(id);
+		if (!handle) return;
+		handle.session.dispose();
+		sessions.delete(id);
+		const owned = byOwner.get(handle.ownerId);
+		if (owned) {
+			owned.delete(id);
+			if (owned.size === 0) byOwner.delete(handle.ownerId);
+		}
+	};
+
+	return {
+		define(name, factory) {
+			defs.set(name, factory);
+		},
+		has(name) {
+			return defs.has(name);
+		},
+		mount(name, ownerId) {
+			const factory = defs.get(name);
+			if (!factory) {
+				throw new Error(
+					`[aurora:live] unknown live component "${name}" — register it with registry.define("${name}", …) before mounting.`,
+				);
+			}
+			const id = crypto.randomUUID();
+			const handle: LiveSessionHandle = {
+				id,
+				ownerId,
+				session: mountLiveSession(factory),
+			};
+			sessions.set(id, handle);
+			const owned = byOwner.get(ownerId) ?? new Set<string>();
+			owned.add(id);
+			byOwner.set(ownerId, owned);
+			return handle;
+		},
+		get(id) {
+			return sessions.get(id)?.session;
+		},
+		dispose,
+		disposeOwner(ownerId) {
+			const owned = byOwner.get(ownerId);
+			if (!owned) return;
+			// Copy ids first — `dispose` mutates the same set as it goes.
+			for (const id of [...owned]) dispose(id);
+			byOwner.delete(ownerId);
+		},
+		disposeAll() {
+			for (const id of [...sessions.keys()]) dispose(id);
+		},
+		size() {
+			return sessions.size;
+		},
+	};
+}