@c9up/aurora 0.1.10 → 0.1.11

package/dist/index.d.ts

@@ -13,4 +13,10 @@ export { batch, effect, isSignal, memo, onCleanup, type ReadSignal, type Signal,
 export { type Disposer, render } from "./render.js";
 export { type AuroraHttpContext, type AuroraResponse, type AuroraRouteConfig, 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/dist/index.js

@@ -9,3 +9,9 @@ export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./re
 export { render } from "./render.js";
 export { auroraRoute, } from "./route.js";
 export { renderToString } from "./ssr.js";
+export { mountLiveSession, } from "./live.js";
+export { createLiveRegistry, } from "./liveRegistry.js";
+export { connectPatches, liveStore, } from "./liveBroadcast.js";
+export { createLiveRouter, } from "./liveRouter.js";
+export { buildLiveTransport, liveClient, } from "./liveClient.js";
+export { DEFAULT_LIVE_EVENT_PATH, wireLiveEvents, } from "./liveServer.js";

package/dist/live.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 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 declare function mountLiveSession(factory: () => LiveComponentDefinition): LiveSession;

package/dist/live.js

@@ -0,0 +1,96 @@
+/**
+ * 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";
+/**
+ * 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) {
+    const { view, handlers = {} } = factory();
+    const listeners = new Set();
+    // 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();
+    const buffer = new Map();
+    let priming = true;
+    let flushScheduled = false;
+    const flush = () => {
+        flushScheduled = false;
+        if (pending.size === 0)
+            return;
+        const patch = [];
+        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 = () => {
+        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());
+            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 = [];
+            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/dist/liveBroadcast.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 } 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 declare function connectPatches(session: LiveSession, relay: RelayBroadcaster, channel: string): () => void;
+/**
+ * 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 declare function liveStore(factory: () => LiveComponentDefinition, relay: RelayBroadcaster, channel: string): LiveStore;

package/dist/liveBroadcast.js

@@ -0,0 +1,44 @@
+/**
+ * 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 { mountLiveSession, } from "./live.js";
+/**
+ * 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, relay, channel) {
+    return session.onPatch((patch) => {
+        relay.broadcast(channel, patch);
+    });
+}
+/**
+ * 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, relay, channel) {
+    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/dist/liveClient.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 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 declare function liveClient(opts: LiveClientOptions): () => void;
+/** 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 declare function buildLiveTransport(relayClient: RelaySubscribeClient, http: LiveHttpPoster, options?: {
+    path?: string;
+}): LiveClientTransport;

package/dist/liveClient.js

@@ -0,0 +1,77 @@
+/**
+ * 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";
+/**
+ * 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) {
+    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(value);
+        }
+    });
+    const onClick = (event) => {
+        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();
+    };
+}
+/**
+ * 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, http, options = {}) {
+    const path = options.path ?? "/_live/event";
+    return {
+        subscribe: (channel, handler) => relayClient.subscribe(channel, handler),
+        post: (id, event, payload) => {
+            void http.post(path, { id, event, payload });
+        },
+    };
+}

package/dist/liveRegistry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 } 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 declare function createLiveRegistry(): LiveRegistry;

package/dist/liveRegistry.js

@@ -0,0 +1,77 @@
+/**
+ * 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 { mountLiveSession, } from "./live.js";
+/** Create an isolated live-session registry (one per app / per relay instance). */
+export function createLiveRegistry() {
+    const defs = new Map();
+    const sessions = new Map();
+    const byOwner = new Map();
+    const dispose = (id) => {
+        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 = {
+                id,
+                ownerId,
+                session: mountLiveSession(factory),
+            };
+            sessions.set(id, handle);
+            const owned = byOwner.get(ownerId) ?? new Set();
+            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/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;