@c9up/aurora 0.1.10 → 0.1.12

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

@@ -0,0 +1,55 @@
+/**
+ * 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 declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Type guard for {@link RpcError}. */
+export declare function isRpcError(value: unknown): value is 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[]>;
+}
+export declare function createRpcClient(options?: RpcClientOptions): RpcClient;

package/dist/rpc.js

@@ -0,0 +1,97 @@
+/**
+ * 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";
+/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/** Type guard for {@link RpcError}. */
+export function isRpcError(value) {
+    return value instanceof RpcError;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
+function toRpcError(error) {
+    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 = {}) {
+    const http = options.http ?? new HttpClient({ headers: options.headers });
+    const url = options.url ?? "/rpc";
+    let nextId = 0;
+    return {
+        async call(method, params, parse) {
+            const id = ++nextId;
+            const res = await http.post(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;
+        },
+        async batch(calls) {
+            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(url, requests);
+            if (!Array.isArray(res)) {
+                throw new RpcError(-32603, "Malformed JSON-RPC batch response");
+            }
+            const byId = new Map();
+            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 };
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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

@@ -60,6 +60,43 @@ export {
 	isHttpError,
 } from "./http.js";
 export { hydrate } from "./hydrate.js";
+export {
+	type LiveComponentDefinition,
+	type LiveSession,
+	mountLiveSession,
+	type SlotPatch,
+} from "./live.js";
+export {
+	connectPatches,
+	type LiveStore,
+	liveStore,
+	type RelayBroadcaster,
+} from "./liveBroadcast.js";
+export {
+	buildLiveTransport,
+	type LiveClientOptions,
+	type LiveClientTransport,
+	type LiveHttpPoster,
+	liveClient,
+	type RelaySubscribeClient,
+} from "./liveClient.js";
+export {
+	createLiveRegistry,
+	type LiveRegistry,
+	type LiveSessionHandle,
+} from "./liveRegistry.js";
+export {
+	createLiveRouter,
+	type LiveMount,
+	type LiveRouter,
+} from "./liveRouter.js";
+export {
+	DEFAULT_LIVE_EVENT_PATH,
+	type LiveHttpContext,
+	type LiveHttpRouter,
+	type WireLiveEventsOptions,
+	wireLiveEvents,
+} from "./liveServer.js";
 export {
 	batch,
 	effect,
@@ -78,5 +115,14 @@ export {
 	type AuroraRouteConfig,
 	auroraRoute,
 } from "./route.js";
+export {
+	createRpcClient,
+	isRpcError,
+	type RpcCall,
+	type RpcClient,
+	type RpcClientOptions,
+	RpcError,
+	type RpcResult,
+} from "./rpc.js";
 export { renderToString } from "./ssr.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();
+		},
+	};
+}