hci-atrium 0.1.0 → 0.3.0

package/dist/player/runtime.d.ts

@@ -0,0 +1,105 @@
+import { LayerEngine, type LayerState } from "./audio-layers.js";
+import { type SendSignalOpts } from "./layer-signals.js";
+/** A room frame as it reaches the runtime — the transport layer parses the wire envelope and hands
+ * this shape to `handleSignal`. */
+export interface PlayerSignal {
+    type?: string;
+    payload?: unknown;
+    /** The sender's connection id (server-stamped) — the reply target for a `layer.query`. */
+    from?: string;
+    /** A request's correlation id, echoed back as `reply_to` on the answer. */
+    ack_id?: string;
+}
+export interface PlayerRuntimeOptions {
+    /** A live AudioContext (created by the host on its Start gesture — autoplay policy). */
+    context: AudioContext;
+    /** Where the master chain's output routes. Defaults to `context.destination`. The runtime always
+     * builds its own master gain → limiter and exposes `masterGain` regardless. */
+    destination?: AudioNode;
+    /** Asset-resolution root for the `asset_id`-only play shape. `""` (default) = same-origin. */
+    baseUrl?: string;
+    /** Outbound-signal sink — the host POSTs it into the room. Used for `layer.query` replies and
+     * `layer.state` broadcasts; the runtime never builds the wire envelope itself. */
+    send: (type: string, payload: unknown, opts?: SendSignalOpts) => void;
+    /** Human-readable engine/dispatch breadcrumbs (the durable record of a room is its session). */
+    onLog?: (text: string) => void;
+    /** Called on every engine change with the fresh snapshot — the host reflects it into its UI. */
+    onSnapshot?: (layers: Record<string, LayerState>) => void;
+    /** Called when a `play` resolves a bytes track, so the host can seed a visualizer with the sound's
+     * name + (when known) tempo — the runtime is framework-agnostic and can't reach the analyzer. Fires
+     * for a legacy flat play's one-shot AND the unified path's first bytes track (queue or oneshot);
+     * `bpm` is only present on the flat path (a resolved LayerTrack carries no tempo). */
+    onTrack?: (track: {
+        name: string;
+        bpm?: number;
+    }) => void;
+    /** Escape hatch for intents the runtime can't play (Spotify, "open link") and any message type it
+     * doesn't recognize. Return true when the host consumed it; false logs-and-skips. The frame it
+     * receives always carries `layer`/`from`/`ack_id` when present: a flat play forwards the original
+     * frame verbatim; a unified play's Spotify track is re-synthesized with the resolved `layer` and the
+     * original frame's `from`/`ack_id`, so the host has the same routing context on both paths. */
+    unhandled?: (msg: PlayerSignal) => boolean;
+    /** Loudness-normalize tracks carrying a measured LUFS (default true — passed to the engine). */
+    normalize?: boolean;
+    /** Subscriber set (`layer.subscribe`rs, by connection id) to adopt BY REFERENCE — host and runtime
+     * mutate the same Set, so a host can carry over subscribers it tracked before the runtime existed
+     * (the pre-Start window). The runtime never replaces or clears it; the host owns its lifecycle. The
+     * representation is intentionally a bare `Set<string>`, not a wrapper — both sides just add/delete. */
+    subscribers?: Set<string>;
+    /** Decoded-buffer cache (keyed by content URL) to adopt BY REFERENCE, like `subscribers` — lets a
+     * host keep the warm cache across runtime rebuilds (e.g. a Stop→Start), so replayed sounds don't
+     * re-fetch/re-decode. Defaults to a fresh per-runtime Map. */
+    buffers?: Map<string, AudioBuffer>;
+}
+/**
+ * The headless Player: feed it room frames via {@link handleSignal}, give it a `send` sink, and it
+ * plays the `play` / `layer.*` dialect over WebAudio. Owns the master chain + {@link LayerEngine};
+ * the host owns transport, UI, and any Spotify/link glue (reached through `unhandled`).
+ */
+export declare class PlayerRuntime {
+    /** The master gain every layer routes through — the analyzer's tap point (pre-limiter). */
+    readonly masterGain: GainNode;
+    /** The layered-audio engine. Exposed so the host can drive listener-side controls (per-layer /
+     * master volume, normalization, device-change resume) and read snapshots for its own ticker. */
+    readonly engine: LayerEngine;
+    private readonly opts;
+    private readonly ctx;
+    private readonly limiter;
+    private readonly engineUnsub;
+    private readonly subscribers;
+    private readonly buffers;
+    private playChain;
+    private broadcastTimer;
+    private heartbeatTimer;
+    private disposed;
+    constructor(opts: PlayerRuntimeOptions);
+    /**
+     * Dispatch a single room frame. The full `play` / `layer.*` dialect; `room.code_rotated` and other
+     * transport-terminal frames stay with the host (they never reach here). An unrecognized type falls
+     * through to the `unhandled` hook.
+     */
+    handleSignal(msg: PlayerSignal): void;
+    /** Tear down the engine + the runtime's own timers. Leaves the AudioContext (the host created it)
+     * but disconnects the master chain this runtime built. Does not clear a shared subscriber set. */
+    dispose(): void;
+    private disconnect;
+    private loadBuffer;
+    private fetchAsset;
+    private resolveWireTracks;
+    private playBytesOneshot;
+    private handleFlatPlay;
+    private onPlaySignal;
+    private onLayerConfigure;
+    private onLayerClear;
+    private onLayerEffects;
+    private onLayerPosition;
+    private onLayerQuery;
+    private broadcastState;
+    private scheduleBroadcast;
+    private addSubscriber;
+    private removeSubscriber;
+    private updateHeartbeat;
+    private onEngineChange;
+    private log;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/player/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/player/runtime.ts"],"names":[],"mappings":"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"}

package/dist/player/runtime.js

@@ -0,0 +1,402 @@
+// The Player's dialect brain, lifted out of the hosted tool's page (tools/src/pages/player/main.tsx)
+// so a host app (e.g. SoundMuse) can embed the same behavior. Framework-agnostic and
+// transport-agnostic: it owns the WebAudio graph (master → limiter, the LayerEngine) and the full
+// `play` / `layer.*` dispatch, but never opens a socket, touches the DOM, or imports React. The host
+// wires transport by handing frames to `handleSignal` and supplying `send` (an outbound-signal sink);
+// page-specific intents it can't play itself (Spotify, an "open link") route back out through the
+// `unhandled` hook, so the runtime carries ZERO Spotify code.
+//
+// Design record: docs/plans/audio-layers.md ("The layer.* dialect") + docs/plans/streaming-assets.md
+// ("Playback as a typed intent over rooms"). Pure signal parsing / track resolution lives in the
+// sibling layer-signals.ts / play-command.ts / play-intent.ts modules.
+import { fetchAssetMeta } from "../asset-meta.js";
+import { httpFetch } from "../http.js";
+import { LayerEngine, } from "./audio-layers.js";
+import { carryTrackFields, fetchedLoudness, resolveWireTrack, validateTransition, wireTrackFetchId, } from "./layer-signals.js";
+import { contentUrlFor, needsAssetFetch, resolvePlayback, } from "./play-command.js";
+import { routePlayIntent } from "./play-intent.js";
+/** How often a playing layer's elapsed/remaining clock is re-broadcast to subscribers (ms). */
+const HEARTBEAT_MS = 1000;
+/** Debounce window coalescing a burst of engine changes into one subscriber broadcast (ms). */
+const BROADCAST_DEBOUNCE_MS = 200;
+/**
+ * The headless Player: feed it room frames via {@link handleSignal}, give it a `send` sink, and it
+ * plays the `play` / `layer.*` dialect over WebAudio. Owns the master chain + {@link LayerEngine};
+ * the host owns transport, UI, and any Spotify/link glue (reached through `unhandled`).
+ */
+export class PlayerRuntime {
+    /** The master gain every layer routes through — the analyzer's tap point (pre-limiter). */
+    masterGain;
+    /** The layered-audio engine. Exposed so the host can drive listener-side controls (per-layer /
+     * master volume, normalization, device-change resume) and read snapshots for its own ticker. */
+    engine;
+    opts;
+    ctx;
+    limiter;
+    engineUnsub;
+    subscribers;
+    // Decoded-buffer cache, keyed by content URL — shared by the engine's one-shot + queue playback.
+    buffers;
+    // Unified `play` signals apply strictly in arrival order: resolution may await asset fetches, and
+    // unordered engine.enqueue calls would scramble queue semantics.
+    playChain = Promise.resolve();
+    broadcastTimer = null;
+    heartbeatTimer = null;
+    // Set by dispose(); every await-then-touch-the-engine path re-checks it so a frame in flight when
+    // the host tears the runtime down can't resurrect the disposed engine.
+    disposed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.ctx = opts.context;
+        // Both adopted by reference (see the option docs): the runtime mutates these in place and never
+        // replaces or clears them, so a host's pre-Start subscribers / warm buffer cache survive intact.
+        this.subscribers = opts.subscribers ?? new Set();
+        this.buffers = opts.buffers ?? new Map();
+        // A single master node every sound routes through, so the analyzer can tap the summed playback.
+        // A brick-wall-ish limiter on the master output is a clipping safety net for normalization boosts
+        // and stacked one-shots. The analyzer taps `master` (pre-limiter), so shared analysis still
+        // reflects the intended mix.
+        const master = this.ctx.createGain();
+        const limiter = this.ctx.createDynamicsCompressor();
+        limiter.threshold.value = -3;
+        limiter.knee.value = 0;
+        limiter.ratio.value = 20;
+        limiter.attack.value = 0.003;
+        limiter.release.value = 0.25;
+        master.connect(limiter);
+        limiter.connect(opts.destination ?? this.ctx.destination);
+        this.masterGain = master;
+        this.limiter = limiter;
+        this.engine = new LayerEngine({
+            context: this.ctx,
+            destination: master,
+            loadBuffer: this.loadBuffer,
+            onLog: opts.onLog,
+            normalize: opts.normalize,
+        });
+        this.engineUnsub = this.engine.onChange(() => this.onEngineChange());
+    }
+    /**
+     * Dispatch a single room frame. The full `play` / `layer.*` dialect; `room.code_rotated` and other
+     * transport-terminal frames stay with the host (they never reach here). An unrecognized type falls
+     * through to the `unhandled` hook.
+     */
+    handleSignal(msg) {
+        switch (msg.type) {
+            case "play": {
+                const p = (msg.payload ?? {});
+                if (Array.isArray(p.tracks)) {
+                    // Unified play (layer/mode/tracks) — serialize so a queue lands in wire order.
+                    this.playChain = this.playChain
+                        .then(() => this.onPlaySignal(p, msg))
+                        .catch(() => this.log("· play failed"));
+                }
+                else {
+                    // Legacy flat play: a single one-shot (or spotify/link) on the layer.
+                    void this.handleFlatPlay(p, typeof p.layer === "string" ? p.layer : "default", msg);
+                }
+                return;
+            }
+            case "layer.configure":
+                this.onLayerConfigure(msg.payload);
+                return;
+            case "layer.clear":
+                this.onLayerClear(msg.payload);
+                return;
+            case "layer.effects":
+                this.onLayerEffects(msg.payload);
+                return;
+            case "layer.position":
+                this.onLayerPosition(msg.payload);
+                return;
+            case "layer.query":
+                this.onLayerQuery(msg.from, msg.ack_id);
+                return;
+            case "layer.subscribe":
+                this.addSubscriber(msg.from);
+                return;
+            case "layer.unsubscribe":
+                this.removeSubscriber(msg.from);
+                return;
+            case "presence.leave":
+                this.removeSubscriber(msg.payload?.connection_id);
+                return;
+            default:
+                // Not part of the dialect — hand it to the host (its own message types), else log-and-skip
+                // (mirrors handleFlatPlay's unrecognized-intent breadcrumb).
+                if (!this.opts.unhandled?.(msg))
+                    this.log(`· ignored: ${msg.type}`);
+                return;
+        }
+    }
+    /** Tear down the engine + the runtime's own timers. Leaves the AudioContext (the host created it)
+     * but disconnects the master chain this runtime built. Does not clear a shared subscriber set. */
+    dispose() {
+        this.disposed = true;
+        this.engineUnsub();
+        if (this.broadcastTimer != null)
+            clearTimeout(this.broadcastTimer);
+        if (this.heartbeatTimer != null)
+            clearInterval(this.heartbeatTimer);
+        this.engine.dispose();
+        this.disconnect(this.masterGain);
+        this.disconnect(this.limiter);
+    }
+    disconnect(node) {
+        try {
+            node.disconnect();
+        }
+        catch {
+            // already disconnected
+        }
+    }
+    // ── Track resolution ────────────────────────────────────────────────────────────────────────────
+    // Decoded-buffer loader, cached by content URL — both the one-shot `play` path and the engine's
+    // queue playback share this one cache.
+    loadBuffer = async (url) => {
+        const cached = this.buffers.get(url);
+        if (cached)
+            return cached;
+        const res = await httpFetch(url);
+        if (!res.ok)
+            throw new Error(String(res.status));
+        const buf = await this.ctx.decodeAudioData(await res.arrayBuffer());
+        this.buffers.set(url, buf);
+        return buf;
+    };
+    // Single-asset metadata is public (content-by-id capability); used only for the asset_id-only play
+    // shape to recover a name label + facts (bpm / loudness). Content bytes stream from the derived URL
+    // regardless. Adapts the public `AssetPublicRead` shape (`title`/`filename`, no `content_url`) that
+    // `fetchAssetMeta` returns onto the `AssetLike` the play resolver reads — so an asset_id-only play
+    // keeps its title as the now-playing label (the server never sends `name`/`content_url`).
+    async fetchAsset(assetId) {
+        const meta = await fetchAssetMeta(this.opts.baseUrl ?? "", assetId);
+        if (!meta)
+            return null;
+        return {
+            id: assetId,
+            content_url: contentUrlFor(assetId),
+            name: meta.title ?? meta.filename,
+            facts: meta.facts,
+        };
+    }
+    // Resolve a batch of wire tracks to playable LayerTracks concurrently (the asset_id-only shape needs
+    // a metadata fetch); order is preserved so a queue lands in wire order.
+    async resolveWireTracks(wireTracks) {
+        const results = await Promise.all(wireTracks.map(async (wt) => {
+            const fetchId = wireTrackFetchId(wt);
+            const fetched = fetchId ? await this.fetchAsset(fetchId) : null;
+            return resolveWireTrack(wt, fetched);
+        }));
+        return results.filter((t) => t !== null);
+    }
+    // ── play ────────────────────────────────────────────────────────────────────────────────────────
+    // Resolve a bytes PlayCommand to a track and fire it as a one-shot on `layerId` via the engine
+    // (the single one-shot pipeline — delay/max-duration/fades/spatial all live in the engine).
+    async playBytesOneshot(cmd, layerId) {
+        const fetched = needsAssetFetch(cmd) && cmd.asset_id ? await this.fetchAsset(cmd.asset_id) : null;
+        if (this.disposed)
+            return; // torn down mid-fetch — don't touch the disposed engine
+        const resolved = resolvePlayback(cmd, fetched);
+        if (!resolved) {
+            this.log("· nothing to play (no content_url / asset)");
+            return;
+        }
+        // carryTrackFields is the one source of truth for the per-sound fields (a PlayCommand is a
+        // WireTrack-compatible shape) — so a new field is a single edit, not two hand-lists.
+        this.engine.playOneshots(layerId, [
+            {
+                ...fetchedLoudness(fetched),
+                ...carryTrackFields(cmd),
+                url: resolved.url,
+                name: resolved.label,
+            },
+        ]);
+        // Seed a host visualizer with the sound's name + (when known) tempo, so its bpm prior and
+        // now-playing label reflect it.
+        this.opts.onTrack?.(resolved.bpm != null ? { name: resolved.label, bpm: resolved.bpm } : { name: resolved.label });
+        this.log(`▶ [${layerId}] ${resolved.label}${cmd.delay_seconds ? `  +${cmd.delay_seconds}s` : ""}`);
+    }
+    // A legacy flat `play` payload (a single sound, no `tracks`): a one-shot on the layer, or a
+    // spotify/link intent handed to the host. Kept for existing hosts (e.g. the HA bridge).
+    async handleFlatPlay(cmd, layerId, original) {
+        const route = routePlayIntent(cmd);
+        if (route.kind === "bytes")
+            return this.playBytesOneshot(route.cmd, layerId);
+        // Non-bytes (spotify / link / none) live outside the runtime — hand the frame to the host.
+        if (this.opts.unhandled?.(original))
+            return;
+        this.log("· nothing to play (unrecognized play signal)");
+    }
+    // The unified `play` signal: `{ layer?, mode?, tracks[], transition? }`. `mode:"queue"` drives the
+    // layer's single-track queue; `mode:"oneshot"` (default) fires overlapping one-shots. A spotify
+    // track routes to the host in oneshot mode; in queue mode the engine stubs it (reserved).
+    async onPlaySignal(payload, original) {
+        const layerId = typeof payload.layer === "string" ? payload.layer : "default";
+        const resolved = await this.resolveWireTracks(Array.isArray(payload.tracks) ? payload.tracks : []);
+        if (this.disposed)
+            return; // torn down mid-resolution — don't touch the disposed engine
+        if (resolved.length === 0) {
+            this.log("· nothing to play (no playable tracks)");
+            return;
+        }
+        if (payload.mode === "queue") {
+            // Queue mode doesn't support spotify (reserved/stubbed) — the engine drops those, so only the
+            // bytes tracks actually queue. Log what really queued, not the raw batch.
+            const queued = resolved.filter((t) => !t.spotify_ref);
+            const transition = validateTransition(payload.transition ?? "now");
+            const mode = { repeat: payload.repeat === true, shuffle: payload.shuffle === true };
+            this.engine.enqueue(layerId, resolved, transition, mode);
+            const first = queued[0];
+            if (first) {
+                const name = first.name ?? first.url ?? "track";
+                this.opts.onTrack?.({ name });
+                const modes = [mode.shuffle && "shuffle", mode.repeat && "repeat"].filter(Boolean);
+                this.log(`▶ [${layerId}] ${name} (queue: ${transition}${modes.length ? `, ${modes.join("+")}` : ""})`);
+            }
+            return;
+        }
+        // oneshot: bytes overlap on the layer; spotify tracks fire through the host.
+        const bytes = resolved.filter((t) => !t.spotify_ref);
+        const firstByte = bytes[0];
+        if (firstByte) {
+            this.engine.playOneshots(layerId, bytes);
+            const name = firstByte.name ?? firstByte.url ?? "sound";
+            this.opts.onTrack?.({ name });
+            this.log(`▶ [${layerId}] ${name}${bytes.length > 1 ? ` +${bytes.length - 1}` : ""}`);
+        }
+        for (const t of resolved) {
+            if (!t.spotify_ref)
+                continue;
+            // Re-synthesize the flat-play `unhandled` contract: carry the resolved `layer` and the original
+            // frame's `from`/`ack_id` so the host has the same routing context it gets on the flat path.
+            const consumed = this.opts.unhandled?.({
+                type: "play",
+                payload: {
+                    layer: layerId,
+                    playback: { source: "spotify", ref: t.spotify_ref, mode: t.spotify_mode },
+                },
+                from: original.from,
+                ack_id: original.ack_id,
+            });
+            if (!consumed)
+                this.log(`· spotify track in layer not yet supported: ${t.name ?? t.spotify_ref}`);
+        }
+    }
+    // ── layer.* dialect ─────────────────────────────────────────────────────────────────────────────
+    onLayerConfigure(payload) {
+        const raw = Array.isArray(payload?.layers) ? payload.layers : [];
+        // Be tolerant at the wire boundary: a `null` / scalar / array entry (or one with no id) would
+        // throw inside `engine.configure` — and this runs from a socket handler, where a throw takes the
+        // whole dispatch down. Drop what can't be a layer, and coerce a non-string id (mirrors how the
+        // rest of the runtime decodes hand-rolled payloads).
+        const layers = raw
+            .filter((spec) => typeof spec === "object" && spec !== null && !Array.isArray(spec) && spec.id != null)
+            .map((spec) => ({ ...spec, id: String(spec.id) }));
+        this.engine.configure(layers);
+    }
+    onLayerClear(payload) {
+        const layerId = typeof payload?.layer === "string" ? payload.layer : "default";
+        const fade = typeof payload?.fade_out_ms === "number" ? payload.fade_out_ms : undefined;
+        // "*" clears every layer at once (a "stop all audio"); otherwise just the named layer.
+        if (layerId === "*") {
+            this.engine.clearAll(fade);
+            this.log("· cleared all layers");
+            return;
+        }
+        this.engine.clear(layerId, fade);
+        this.log(`· cleared [${layerId}]`);
+    }
+    onLayerEffects(payload) {
+        const layerId = typeof payload?.layer === "string" ? payload.layer : "default";
+        const effects = payload?.effects ?? {};
+        const fade = typeof payload?.fade_ms === "number" ? payload.fade_ms : undefined;
+        // "*" applies to every EXISTING layer at once (mirrors layer.clear "*"); no auto-vivify.
+        if (layerId === "*") {
+            this.engine.setEffectsAll(effects, fade);
+            return;
+        }
+        this.engine.setEffects(layerId, effects, fade);
+    }
+    // Ramped whole-layer HRTF positioning. The panner is created lazily on first use (an unpositioned
+    // layer keeps today's graph); `distance`, when given, opts into distance attenuation. No "*".
+    onLayerPosition(payload) {
+        const layerId = typeof payload?.layer === "string" ? payload.layer : "default";
+        if (layerId === "*") {
+            this.log(`· layer.position has no "*" wildcard — ignored`);
+            return;
+        }
+        const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+        this.engine.setPosition(layerId, num(payload?.x), num(payload?.y), num(payload?.z), typeof payload?.fade_ms === "number" ? payload.fade_ms : undefined, payload?.distance);
+    }
+    // Pull: reply the exact snapshot straight back to the requester (`to=from`, `reply_to=ack_id`).
+    onLayerQuery(from, ackId) {
+        if (!from)
+            return;
+        const layers = this.engine.snapshot();
+        this.opts.send("layer.query", { layers }, { to: from, replyTo: ackId, ephemeral: true });
+    }
+    // ── Subscriber fan-out ──────────────────────────────────────────────────────────────────────────
+    // Push the current snapshot to every subscriber (one broadcast, server fans it out). Accepts a
+    // pre-computed snapshot so the heartbeat doesn't have to snapshot twice.
+    broadcastState(layers) {
+        if (this.subscribers.size === 0)
+            return;
+        const snap = layers ?? this.engine.snapshot();
+        this.opts.send("layer.state", { layers: snap }, { ephemeral: true });
+    }
+    // Coalesce a burst of engine changes into one broadcast — the on-change half of the subscribe
+    // contract; the heartbeat below covers a playing layer's elapsed/remaining drift.
+    scheduleBroadcast() {
+        if (this.subscribers.size === 0)
+            return;
+        if (this.broadcastTimer != null)
+            return;
+        this.broadcastTimer = setTimeout(() => {
+            this.broadcastTimer = null;
+            this.broadcastState();
+        }, BROADCAST_DEBOUNCE_MS);
+    }
+    addSubscriber(from) {
+        if (!from)
+            return;
+        this.subscribers.add(from);
+        this.broadcastState(); // immediate first push so a fresh subscriber isn't blind until the next change
+        // A subscriber joining mid-playback starts the heartbeat (it was gated off with no subscribers).
+        this.updateHeartbeat(this.engine.snapshot());
+    }
+    removeSubscriber(from) {
+        if (!from)
+            return;
+        this.subscribers.delete(from);
+        // The last subscriber leaving stops the heartbeat (nothing left to broadcast to).
+        this.updateHeartbeat(this.engine.snapshot());
+    }
+    // The engine only notifies on discrete changes, so a playing layer's elapsed/remaining clock would
+    // freeze between them — while anything plays AND someone's subscribed, re-broadcast once a second.
+    // Gated on subscribers too so an unwatched Player doesn't run a pointless timer; addSubscriber /
+    // removeSubscriber re-evaluate it so joining/leaving mid-playback starts/stops it.
+    updateHeartbeat(snap) {
+        const playing = this.subscribers.size > 0 && Object.values(snap).some((l) => l.playing);
+        if (playing && this.heartbeatTimer == null) {
+            this.heartbeatTimer = setInterval(() => {
+                this.broadcastState();
+            }, HEARTBEAT_MS);
+        }
+        else if (!playing && this.heartbeatTimer != null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    onEngineChange() {
+        // One snapshot feeds every consumer of this change (heartbeat gate + the host's onSnapshot).
+        const snap = this.engine.snapshot();
+        this.scheduleBroadcast();
+        this.updateHeartbeat(snap);
+        this.opts.onSnapshot?.(snap);
+    }
+    log(text) {
+        this.opts.onLog?.(text);
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/player/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/player/runtime.ts"],"names":[],"mappings":"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"}

package/dist/react/index.d.ts

@@ -10,6 +10,7 @@
 import { type ReactNode } from "react";
 import type { Atrium } from "../atrium.js";
 import type { User } from "../types.js";
+export { type RoomConnection, type RoomStatus, type UseRoomConnectionOptions, useRoomConnection, } from "./use-room-connection.js";
 export interface AtriumProviderProps {
     atrium: Atrium;
     children: ReactNode;

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAmC,MAAM,OAAO,CAAA;AACtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAUvC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,mBAAmB,GAAG,SAAS,CAoCnF;AAUD,uDAAuD;AACvD,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,oGAAoG;AACpG,wBAAgB,OAAO,IAAI,IAAI,GAAG,IAAI,GAAG,SAAS,CAEjD;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,IAAI,KAAK,GAAG,IAAI,CAE3C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,SAAS,CAAA;IACnB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAUnF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAmC,MAAM,OAAO,CAAA;AACtF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,wBAAwB,EAC7B,iBAAiB,GAClB,MAAM,0BAA0B,CAAA;AAUjC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,mBAAmB,GAAG,SAAS,CAoCnF;AAUD,uDAAuD;AACvD,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,oGAAoG;AACpG,wBAAgB,OAAO,IAAI,IAAI,GAAG,IAAI,GAAG,SAAS,CAEjD;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,IAAI,KAAK,GAAG,IAAI,CAE3C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,SAAS,CAAA;IACnB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,kBAAkB,GAAG,SAAS,CAUnF"}

package/dist/react/index.js

@@ -9,6 +9,7 @@ import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
  * flight, ``null`` when signed out, and a ``User`` when signed in.
  */
 import { createContext, useContext, useEffect, useState } from "react";
+export { useRoomConnection, } from "./use-room-connection.js";
 const AtriumContext = createContext(null);
 /** Provides the ``Atrium`` client and the live user to the ``useAtrium`` / ``useUser`` hooks. */
 export function AtriumProvider({ atrium, children }) {

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"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"}

package/dist/react/use-room-connection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ``useRoomConnection`` — the connect/reconnect skeleton shared by the browser tools that consume a
+ * room by connect code (Dashboard, Viewer).
+ *
+ * It owns exactly the transport lifecycle: ``joinRoom(code)`` → classify a join failure
+ * (``APIError`` 4xx = a bad code, anything else = unreachable) → register a terminal ``onEnd``
+ * (the typed reason becomes the status) → ``await room.connect()`` (a non-terminal failure =
+ * unreachable) → remount-safe cleanup (a ``cancelled`` flag guards every late setState, and
+ * ``room.close()`` tears the handle down). App-specific signal handling stays outside: pass
+ * ``onRoom`` to register handlers on the room the moment it exists — **before** ``connect()`` runs,
+ * so a durable-signal replay isn't missed — and return an optional cleanup from it.
+ */
+import { type Room, type RoomEndReason } from "../rooms/index.js";
+/**
+ * The transport-level status, independent of anything the app puts on the wire. ``"connecting"``
+ * until the room is joined and connected; ``"connected"`` once in; ``"unreachable"`` for a join or
+ * connect failure with no typed end; the ``RoomEndReason`` variants (``"bad-code"`` |
+ * ``"code-rotated"`` | ``"room-gone"``) for a typed terminal end (a bad code at join maps to
+ * ``"bad-code"`` too). Callers map this onto their own richer view model.
+ */
+export type RoomStatus = "connecting" | "connected" | "unreachable" | RoomEndReason;
+export interface UseRoomConnectionOptions {
+    /** Presence identity for the join (e.g. ``"viewer:web"``). */
+    identity: string;
+    /** Room resolution root. Defaults to ``location.origin``. */
+    baseUrl?: string;
+    /**
+     * Called once the room handle exists, **before** ``connect()`` runs — the point to register
+     * signal handlers (``room.on`` / ``room.onAny``) so a replayed durable signal isn't missed. May
+     * return a cleanup, run on unmount / reconnect before the handle is closed.
+     */
+    onRoom?: (room: Room) => void | (() => void);
+}
+export interface RoomConnection {
+    status: RoomStatus;
+    /** The joined room, or ``null`` before it exists / after teardown. */
+    room: Room | null;
+}
+export declare function useRoomConnection(code: string, opts: UseRoomConnectionOptions): RoomConnection;
+//# sourceMappingURL=use-room-connection.d.ts.map

package/dist/react/use-room-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-room-connection.d.ts","sourceRoot":"","sources":["../../src/react/use-room-connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAY,KAAK,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAA;AAEnF,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IAEH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAA;IAClB,sEAAsE;IACtE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,GAAG,cAAc,CAoE9F"}