@c9up/aurora 0.1.10 → 0.1.12

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;
+		},
+	};
+}

package/src/liveRouter.ts

@@ -0,0 +1,70 @@
+/**
+ * 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, 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 function createLiveRouter(
+	registry: LiveRegistry,
+	relay: RelayBroadcaster,
+): LiveRouter {
+	const channelFor = (id: string): string => `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/src/liveServer.ts

@@ -0,0 +1,75 @@
+/**
+ * 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;
+}
+
+interface LiveEventBody {
+	id: string;
+	event: string;
+	payload?: unknown;
+}
+
+/** Structural guard for the POST body — no casts (`in`-narrowing + typeof). */
+function isLiveEventBody(value: unknown): value is LiveEventBody {
+	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: LiveHttpRouter,
+	live: LiveRouter,
+	options: WireLiveEventsOptions = {},
+): void {
+	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/src/relay.ts

@@ -27,12 +27,15 @@ interface RelayState {
 	sse: EventSource | null;
 	uid: string | null;
 	channels: Map<string, Set<(event: unknown) => void>>;
+	/** Channels we've already wired an SSE listener for on the current sse. */
+	attached: Set<string>;
 }
 
 const STATE: RelayState = {
 	sse: null,
 	uid: null,
 	channels: new Map(),
+	attached: new Set(),
 };
 
 export interface RelayOptions {
@@ -85,6 +88,11 @@ const CLIENT: RelayClient = {
 		const adapted = handler as (event: unknown) => void;
 		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,
@@ -110,15 +118,17 @@ const CLIENT: RelayClient = {
 		}
 		STATE.uid = null;
 		STATE.channels.clear();
+		STATE.attached.clear();
 	},
 };
 
 function open(): void {
 	const sse = new EventSource(CONFIG.sseUrl);
 	STATE.sse = sse;
+	STATE.attached = new Set();
 
 	sse.addEventListener("connected", (ev) => {
-		const data = safeJson<{ uid?: string }>((ev as MessageEvent).data);
+		const data = safeJson<{ uid?: string }>(messageData(ev));
 		if (data && typeof data.uid === "string") {
 			STATE.uid = data.uid;
 			// Re-apply EVERY active subscription on each (re)connect. The server
@@ -137,21 +147,40 @@ function open(): void {
 		}
 	});
 
-	sse.onmessage = (ev) => {
-		const data = safeJson<{ channel?: string; [key: string]: unknown }>(
-			ev.data,
-		);
-		if (!data || typeof data.channel !== "string") return;
-		const handlers = STATE.channels.get(data.channel);
+	// 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: EventSource, channel: string): void {
+	if (STATE.attached.has(channel)) return;
+	STATE.attached.add(channel);
+	sse.addEventListener(channel, (ev) => {
+		const payload = safeJson<unknown>(messageData(ev));
+		if (payload === null) return;
+		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: Event): string | null {
+	if ("data" in ev && typeof ev.data === "string") return ev.data;
+	return null;
 }
 
 async function postSubscribe(channel: string): Promise<void> {

package/src/rpc.ts

@@ -0,0 +1,145 @@
+/**
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
+ * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
+ * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
+ * headers, and timeouts.
+ *
+ *   const rpc = createRpcClient()                          // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *
+ * Pairs with aurora's `command()` for reactive calls:
+ *   const validate = command((p) => rpc.call('task.validate', p))
+ */
+import { HttpClient } from "./http.js";
+
+export interface RpcClientOptions {
+	/** Endpoint path. Default `/rpc` (matches RpcProvider's default). */
+	url?: string;
+	/** Reuse an existing HttpClient — its baseURL / headers / auth carry over. */
+	http?: HttpClient;
+	/** Default headers — only used when no `http` client is supplied. */
+	headers?: Record<string, string>;
+}
+
+/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
+export class RpcError extends Error {
+	readonly code: number;
+	readonly data?: unknown;
+	constructor(code: number, message: string, data?: unknown) {
+		super(message);
+		this.name = "RpcError";
+		this.code = code;
+		this.data = data;
+	}
+}
+
+/** Type guard for {@link RpcError}. */
+export function isRpcError(value: unknown): value is RpcError {
+	return value instanceof RpcError;
+}
+
+/** One call in a batch. `parse` optionally validates that call's result (cast-free). */
+export interface RpcCall<T = unknown> {
+	method: string;
+	params?: unknown;
+	parse?: (data: unknown) => T;
+}
+
+/** A settled batch entry — the result, or the JSON-RPC error for that call. */
+export type RpcResult<T = unknown> =
+	| { ok: true; value: T }
+	| { ok: false; error: RpcError };
+
+export interface RpcClient {
+	/**
+	 * Call one method. Returns the result, or throws {@link RpcError} on a
+	 * JSON-RPC error. Pass `parse` to validate the result at runtime (and skip
+	 * the unchecked `T` assertion).
+	 */
+	call<T = unknown>(
+		method: string,
+		params?: unknown,
+		parse?: (data: unknown) => T,
+	): Promise<T>;
+	/** Send a JSON-RPC batch. Returns one settled entry per call, in request order. */
+	batch(calls: RpcCall[]): Promise<RpcResult[]>;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
+function toRpcError(error: unknown): RpcError {
+	if (
+		isObject(error) &&
+		typeof error.code === "number" &&
+		typeof error.message === "string"
+	) {
+		return new RpcError(error.code, error.message, error.data);
+	}
+	return new RpcError(-32603, "Malformed JSON-RPC error envelope", error);
+}
+
+export function createRpcClient(options: RpcClientOptions = {}): RpcClient {
+	const http = options.http ?? new HttpClient({ headers: options.headers });
+	const url = options.url ?? "/rpc";
+	let nextId = 0;
+
+	return {
+		async call<T>(
+			method: string,
+			params?: unknown,
+			parse?: (data: unknown) => T,
+		): Promise<T> {
+			const id = ++nextId;
+			const res = await http.post<unknown>(url, {
+				jsonrpc: "2.0",
+				method,
+				params,
+				id,
+			});
+			if (!isObject(res)) {
+				throw new RpcError(
+					-32603,
+					`Malformed JSON-RPC response for "${method}"`,
+				);
+			}
+			if (res.error !== undefined) throw toRpcError(res.error);
+			// Result boundary — the same unchecked `T` assertion HttpClient uses,
+			// with `parse` as the cast-free, runtime-validated escape hatch.
+			return parse ? parse(res.result) : (res.result as T);
+		},
+
+		async batch(calls: RpcCall[]): Promise<RpcResult[]> {
+			if (calls.length === 0) return [];
+			const requests = calls.map((c, index) => ({
+				jsonrpc: "2.0",
+				method: c.method,
+				params: c.params,
+				id: index, // index = request position; responses are matched back by id
+			}));
+			const res = await http.post<unknown>(url, requests);
+			if (!Array.isArray(res)) {
+				throw new RpcError(-32603, "Malformed JSON-RPC batch response");
+			}
+			const byId = new Map<unknown, Record<string, unknown>>();
+			for (const item of res) if (isObject(item)) byId.set(item.id, item);
+			return calls.map((c, index) => {
+				const envelope = byId.get(index);
+				if (!envelope) {
+					return {
+						ok: false,
+						error: new RpcError(-32603, `No response for "${c.method}"`),
+					};
+				}
+				if (envelope.error !== undefined) {
+					return { ok: false, error: toRpcError(envelope.error) };
+				}
+				const value = c.parse ? c.parse(envelope.result) : envelope.result;
+				return { ok: true, value };
+			});
+		},
+	};
+}