hci-atrium 0.1.0

package/dist/rooms/offer-transcription.js

@@ -0,0 +1,231 @@
+/**
+ * The transcription standing service behind {@link ./room.Room.offerTranscription} — armed by a
+ * ``transcription.start`` request, wound down by ``transcription.stop`` or the room's close. The
+ * TypeScript port of Python's ``_AsyncOfferedTranscription`` + ``_publish_room_transcription`` (aio.py).
+ *
+ * Engage is **sender-scoped** (see {@link ./armed-set.ArmedSet}): only armed sources are transcribed
+ * — an unarmed source's frames are dropped at the demux (no engine spawns). While engaged it
+ * subscribes the room's ``audio.snippet`` stream, demuxes frames per source, and runs one
+ * transcription engine per source (the same engine as {@link ./room.Room.transcribe}), stamping each
+ * ``transcript.*`` signal's payload with the source's connection id and roster-resolved
+ * ``source_name``. Up to ``maxSources`` sources; a departed source's engine is reaped promptly.
+ */
+import { asError } from "../http.js";
+import { decodeAudioSnippetFrame } from "./snippet.js";
+import { OFFER_CLIP_QUEUE_MAX, OFFER_MAX_SOURCES, StandingSource, } from "./standing-source.js";
+import { publishRoomTranscripts, TRANSCRIBER_SOURCE } from "./transcriber.js";
+/** A bounded per-source clip queue — drops the **oldest** queued clip when full (live captions favour
+ * recency over completeness). A ``null`` end-sentinel always lands, ending the async iterator so the
+ * engine flushes and returns. The port of Python's ``asyncio.Queue`` + ``_put_newest`` + ``_queue_bytes``. */
+class ClipQueue {
+    max;
+    items = [];
+    wake = null;
+    constructor(max) {
+        this.max = max;
+    }
+    /** Put an item, first dropping the oldest queued item if the queue is full. Returns whether a drop
+     * happened (never throws — so the ``null`` sentinel always lands too). */
+    putNewest(item) {
+        let dropped = false;
+        if (this.items.length >= this.max) {
+            this.items.shift();
+            dropped = true;
+        }
+        this.items.push(item);
+        this.wake?.();
+        this.wake = null;
+        return dropped;
+    }
+    /** Discard every buffered clip (a per-source stop/leave drops what hasn't been transcribed — no
+     * captions past the disarm boundary). A subsequent {@link putNewest}(null) still ends the iterator. */
+    clear() {
+        this.items.length = 0;
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            while (this.items.length > 0) {
+                const item = this.items.shift();
+                if (item === null)
+                    return;
+                yield item;
+            }
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+    }
+}
+export class OfferedTranscription extends StandingSource {
+    signal = "transcription.available";
+    logName = "transcription offer";
+    identityPrefix = "transcription-offer";
+    engineFn;
+    model;
+    language;
+    queues = new Map();
+    engines = new Map();
+    // Per-source abort — a single source's stop/leave cancels *its* engine immediately (the streaming
+    // path's events read unblocks at once), so no captions publish past that source's disarm boundary.
+    aborts = new Map();
+    reaped = [];
+    stalled = new Set();
+    constructor(deps, opts = {}) {
+        super(deps, opts.maxSources ?? OFFER_MAX_SOURCES);
+        this.engineFn = deps.engine;
+        this.model = opts.model;
+        this.language = opts.language;
+    }
+    /** A v1 (id-less) source being transcribed under an all-arm surfaces as a null-source entry. */
+    activeExtra() {
+        return this.engines.has(null) ? [{ source: null, name: null }] : [];
+    }
+    async run() {
+        const ws = await this.openWs();
+        let failed = false;
+        try {
+            for await (const raw of this.frames()) {
+                const snippet = decodeAudioSnippetFrame(raw);
+                if (!snippet)
+                    continue; // a foreign / DSP binary frame — not ours
+                this.admit(snippet.source, snippet.data);
+            }
+        }
+        catch (err) {
+            failed = true;
+            this.err = asError(err);
+            console.error(`Atrium transcription offer for room ${this.deps.roomId} died:`, err);
+        }
+        if (!failed && this.codeRotated) {
+            this.stoppedReason = "code-rotated";
+            console.info(`Atrium transcription offer for room ${this.deps.roomId}: room code rotated`);
+        }
+        this.stopSweeper();
+        for (const queue of this.queues.values())
+            queue.putNewest(null); // drain each engine
+        await Promise.allSettled([...this.engines.values(), ...this.reaped]);
+        this.queues.clear();
+        this.engines.clear();
+        this.aborts.clear();
+        this.reaped = [];
+        await Promise.allSettled(this.bg);
+        this.bg.length = 0;
+        ws.close();
+    }
+    /** Route one clip to its source's engine — dropping it if the source is unarmed or past the cap,
+     * and spawning the engine on a source's first clip. */
+    admit(source, data) {
+        if (!this.armed.isArmed(source))
+            return; // unarmed source — dropped at the demux
+        let queue = this.queues.get(source);
+        if (!queue) {
+            if (this.engines.size >= this.maxSources) {
+                this.warnCapped(source);
+                return;
+            }
+            queue = new ClipQueue(OFFER_CLIP_QUEUE_MAX);
+            this.queues.set(source, queue);
+            const ac = new AbortController();
+            this.aborts.set(source, ac);
+            const sourceName = source !== null ? this.nameFor(source) : null;
+            this.engines.set(source, this.spawnEngine(source, sourceName, queue, ac.signal));
+            this.spawnBroadcast(); // a new source is now active (v1 surfaces the null entry)
+        }
+        this.enqueue(source, queue, data);
+    }
+    spawnEngine(source, sourceName, queue, signal) {
+        return this.publishTranscription(source, sourceName, queue, signal).catch((err) => {
+            // An engine error (an auth reject, a mid-stream drop) is swallowed like Python's suppressed
+            // engine-task exceptions — the demux loop, not the engine, owns the offer's terminal error.
+            console.debug(`Atrium transcription offer engine for ${JSON.stringify(source)} ended:`, err);
+        });
+    }
+    /** Run the engine over one source's clip queue and publish each result — the shared
+     * {@link publishRoomTranscripts} with per-source attribution, published over the REST ``/signal``
+     * POST (so the ephemeral partial hint survives) as ``source: "transcriber"``. */
+    publishTranscription(source, sourceName, queue, signal) {
+        return publishRoomTranscripts({
+            clips: queue,
+            engine: this.engineFn,
+            publish: (type, payload, o) => this.deps.publishSignal(type, payload, {
+                source: TRANSCRIBER_SOURCE,
+                ephemeral: o.ephemeral,
+            }),
+            model: this.model,
+            language: this.language,
+            signal,
+            attribution: { source, source_name: sourceName },
+        });
+    }
+    /** Hand one clip to a source's engine, dropping the oldest queued clip if the engine has stalled.
+     * Warns once per source per stall episode. */
+    enqueue(source, queue, data) {
+        if (queue.putNewest(data)) {
+            if (!this.stalled.has(source)) {
+                this.stalled.add(source);
+                console.warn(`Atrium transcription offer for room ${this.deps.roomId}: source ${JSON.stringify(source)} ` +
+                    "is backing up (engine stalled) — dropping oldest clips");
+            }
+        }
+        else {
+            this.stalled.delete(source);
+        }
+    }
+    /** On leave, cancel that source's engine immediately (mirror of Python's ``engine.cancel()``):
+     * abort its signal and drop its buffered clips, so no captions publish for a source that has left
+     * (consent-relevant). The reaped engine is awaited at teardown (the base handles the rest). */
+    onPresenceSource(event, cid) {
+        if (event !== "leave")
+            return;
+        const queue = this.queues.get(cid);
+        const engine = this.engines.get(cid);
+        this.aborts.get(cid)?.abort(); // cancel now — the streaming events read unblocks at once
+        this.queues.delete(cid);
+        this.engines.delete(cid);
+        this.aborts.delete(cid);
+        if (queue) {
+            queue.clear(); // drop buffered clips — nothing transcribes past the leave
+            queue.putNewest(null); // …then end the iterator (batch path exits its for-await)
+        }
+        if (engine)
+            this.reaped.push(engine);
+        this.stalled.delete(cid);
+    }
+    // Serialize the per-source stop with the other state transitions (start / stop) under the lock —
+    // it mutates the queue/engine/armed maps the frame loop reads. Cancel-immediately, like Python:
+    // abort the engine, drop its buffered clips, ack promptly (no captions after the disarm boundary).
+    async stopSource(source) {
+        await this.lock.run(async () => {
+            this.armed.disarm(source);
+            const queue = this.queues.get(source);
+            const engine = this.engines.get(source);
+            this.aborts.get(source)?.abort(); // cancel now — the streaming path stops publishing at once
+            this.queues.delete(source);
+            this.engines.delete(source);
+            this.aborts.delete(source);
+            if (queue) {
+                queue.clear(); // drop buffered clips — no captions past disarm
+                queue.putNewest(null); // …then end the iterator so the batch path exits and the engine settles
+            }
+            if (engine)
+                await engine.catch(() => { });
+            this.stalled.delete(source);
+            this.cappedWarned.delete(source);
+        });
+        await this.broadcast();
+    }
+    async stop() {
+        this.armed.clear();
+        for (const ac of this.aborts.values())
+            ac.abort(); // cancel every source's engine
+        this.ws?.close();
+        for (const queue of this.queues.values())
+            queue.putNewest(null);
+        const running = this.runPromise;
+        this.runPromise = null;
+        if (running)
+            await running.catch(() => { });
+        this.clearLastBroadcast();
+    }
+}
+//# sourceMappingURL=offer-transcription.js.map

package/dist/rooms/offer-transcription.js.map

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

package/dist/rooms/participant.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The typed presence-roster participant behind ``room.participants()`` / ``room.has()`` — the
+ * camelCase port of the Python SDK's ``models.Participant`` (``_wrap`` / ``_merge_roles`` /
+ * ``_participant_matches``). Distinct from the transport-level {@link ./transport.RosterEntry} (the
+ * raw live-roster item ``room.presence`` yields): this is the parsed, query-friendly view.
+ */
+/** One member of a room's presence roster (from ``room.participants()``, behind ``room.has()``). */
+export interface Participant {
+    connectionId: string;
+    identity: string | null;
+    /** The announced display name (``announce.name``), or ``null``. */
+    name: string | null;
+    /** The announce's ``role`` (singular) and ``roles`` (list) merged, deduped, order-preserving. */
+    roles: string[];
+    /** When this connection joined — a fresh joiner vs. a long-standing tab (rooms are always open). */
+    connectedAt: Date | null;
+    /** The original server roster dict — the escape hatch for fields this type doesn't surface. */
+    raw: Record<string, unknown>;
+}
+/** A ``has()`` predicate: the given filters are ANDed (each omitted filter passes). */
+export interface ParticipantPredicate {
+    role?: string;
+    name?: string;
+    identityPrefix?: string;
+}
+/** Merge an announce's ``role`` (string) and ``roles`` (list) into one deduped, order-preserving list.
+ * Both shapes exist in the wild — a consumer reading only one would silently miss the other. */
+export declare function mergeRoles(announce: Record<string, unknown>): string[];
+/** Parse one server roster entry into a typed {@link Participant} (mirror of Python's ``_wrap``). */
+export declare function parseParticipant(data: Record<string, unknown>): Participant;
+/** The shared ``has()`` predicate: the given filters ANDed (each omitted filter passes). A hosted
+ * Player announces no role but identity ``player:web``, so ``{ identityPrefix: "player:" }`` is how
+ * the old ``hasPlayer()`` guard is spelled now (mirror of Python's ``_participant_matches``). */
+export declare function participantMatches(p: Participant, pred: ParticipantPredicate): boolean;
+//# sourceMappingURL=participant.d.ts.map

package/dist/rooms/participant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.d.ts","sourceRoot":"","sources":["../../src/rooms/participant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oGAAoG;AACpG,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,mEAAmE;IACnE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,iGAAiG;IACjG,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,oGAAoG;IACpG,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,+FAA+F;IAC/F,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC7B;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;gGACgG;AAChG,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAWtE;AAQD,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAa3E;AAED;;iGAEiG;AACjG,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAItF"}

package/dist/rooms/participant.js

@@ -0,0 +1,53 @@
+/**
+ * The typed presence-roster participant behind ``room.participants()`` / ``room.has()`` — the
+ * camelCase port of the Python SDK's ``models.Participant`` (``_wrap`` / ``_merge_roles`` /
+ * ``_participant_matches``). Distinct from the transport-level {@link ./transport.RosterEntry} (the
+ * raw live-roster item ``room.presence`` yields): this is the parsed, query-friendly view.
+ */
+/** Merge an announce's ``role`` (string) and ``roles`` (list) into one deduped, order-preserving list.
+ * Both shapes exist in the wild — a consumer reading only one would silently miss the other. */
+export function mergeRoles(announce) {
+    const out = [];
+    const single = announce.role;
+    if (typeof single === "string" && single && !out.includes(single))
+        out.push(single);
+    const many = announce.roles;
+    if (Array.isArray(many)) {
+        for (const role of many) {
+            if (typeof role === "string" && role && !out.includes(role))
+                out.push(role);
+        }
+    }
+    return out;
+}
+function parseIso(value) {
+    if (typeof value !== "string" || !value)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** Parse one server roster entry into a typed {@link Participant} (mirror of Python's ``_wrap``). */
+export function parseParticipant(data) {
+    const announce = data.announce && typeof data.announce === "object"
+        ? data.announce
+        : {};
+    return {
+        connectionId: String(data.connection_id ?? ""),
+        identity: typeof data.identity === "string" ? data.identity : null,
+        name: typeof announce.name === "string" ? announce.name : null,
+        roles: mergeRoles(announce),
+        connectedAt: parseIso(data.connected_at),
+        raw: data,
+    };
+}
+/** The shared ``has()`` predicate: the given filters ANDed (each omitted filter passes). A hosted
+ * Player announces no role but identity ``player:web``, so ``{ identityPrefix: "player:" }`` is how
+ * the old ``hasPlayer()`` guard is spelled now (mirror of Python's ``_participant_matches``). */
+export function participantMatches(p, pred) {
+    if (pred.role !== undefined && !p.roles.includes(pred.role))
+        return false;
+    if (pred.name !== undefined && p.name !== pred.name)
+        return false;
+    return pred.identityPrefix === undefined || Boolean(p.identity?.startsWith(pred.identityPrefix));
+}
+//# sourceMappingURL=participant.js.map

package/dist/rooms/participant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"participant.js","sourceRoot":"","sources":["../../src/rooms/participant.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;gGACgG;AAChG,MAAM,UAAU,UAAU,CAAC,QAAiC;IAC1D,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAA;IAC5B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACnF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAA;IAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5B,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACnD,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAAC,IAA6B;IAC5D,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;QAChD,CAAC,CAAE,IAAI,CAAC,QAAoC;QAC5C,CAAC,CAAC,EAAE,CAAA;IACR,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;QAC9C,QAAQ,EAAE,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;QAClE,IAAI,EAAE,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC9D,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC;QAC3B,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC;QACxC,GAAG,EAAE,IAAI;KACV,CAAA;AACH,CAAC;AAED;;iGAEiG;AACjG,MAAM,UAAU,kBAAkB,CAAC,CAAc,EAAE,IAA0B;IAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IACzE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IACjE,OAAO,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAA;AAClG,CAAC"}

package/dist/rooms/recorder.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The room→session recorder — the single durable binding between a live room (pure transport,
+ * nothing stored) and a session (an append-only durable log). Started by {@link ./room.Room.record};
+ * a line-for-line port of the Python SDK's ``_AsyncRecorder`` (aio.py).
+ *
+ * It rides an **observe** SSE stream ({@link ./sse.RoomEventStream} in observe mode — no presence
+ * connection, so the recorder is invisible in the roster) and bridges every durable-worthy signal
+ * into ``session.event(...)``, stamping provenance (``via``). The skip rules mirror Python exactly:
+ * a ``ready`` frame, a ``presence.*`` signal, and anything marked ``ephemeral`` (beats, cursors, live
+ * captions, relayed vectors) are **not** recorded — only real, durable signals are.
+ *
+ * Lifecycle: a dropped stream reconnects with backoff (the gap is lost — rooms have no replay), so a
+ * blip never ends capture. Only a **terminal** end stops it, cleanly, with a {@link RecorderStopReason}:
+ * a connect-code rotation (``code-rotated`` — the consent boundary between studies) or the room being
+ * gone / its code rejected. An explicit {@link Recorder.stop} is the ``stopped`` reason. It never
+ * throws to the caller; check {@link Recorder.error} for a server refusal.
+ */
+import type { Session } from "../models.js";
+import type { ShapedRequest } from "../shaping/index.js";
+import type { FetchImpl } from "./sse.js";
+/** Why a {@link Recorder} stopped for good — no reconnect recovers. ``stopped`` is an explicit
+ * {@link Recorder.stop}; the rest mirror the transport's terminal {@link RoomEndReason}. */
+export type RecorderStopReason = "stopped" | "code-rotated" | "room-gone" | "bad-code";
+/** The REST caller a recorder needs to append session events (the authenticated host transport). */
+export type RecorderRest = (req: ShapedRequest) => Promise<unknown>;
+/** Everything a {@link Recorder} is built from — the room's connection facts plus the seam callback. */
+export interface RecorderDeps {
+    roomId: string;
+    /** The room's connect code — the observe stream's ``?code=`` auth. */
+    code: string;
+    /** The room's display name — stamped into each event's ``via`` provenance. */
+    roomName: string | null;
+    baseUrl: string;
+    /** Authenticated caller for the session-event POST (a host handle; absent for a participant). */
+    rest: RecorderRest;
+    reconnect?: boolean;
+    /** Injected ``fetch`` for the observe SSE stream — the test seam. */
+    fetchImpl?: FetchImpl;
+    /** Fired when this recorder starts and when it stops — the room's ``notifyRecordersChanged`` seam
+     * (so a wave-4 capture offer can re-derive availability off the active-recorder set). */
+    onChange: () => void;
+}
+export declare class Recorder {
+    private readonly deps;
+    private readonly session;
+    private stream;
+    private started;
+    private ended;
+    private reason;
+    private failure;
+    constructor(deps: RecorderDeps, into: Session);
+    /** The session this recorder writes into — the durable binding a wave-4 capture offer engages
+     * under. */
+    get into(): Session;
+    /** True while the capture loop runs (streaming or reconnecting) and has not begun winding down —
+     * a recorder in its terminal wind-down already counts as gone (mirror of Python's ``alive``). */
+    get alive(): boolean;
+    /** Why the recorder stopped, or ``null`` while alive. */
+    get stoppedReason(): RecorderStopReason | null;
+    /** The error that ended the capture for good — a server refusal (the room gone, or a rejected
+     * code). ``null`` while alive, after a clean rotation, or after an explicit {@link stop}. */
+    get error(): Error | null;
+    /** Begin capturing (idempotent). Starts immediately in the background — the returned handle is
+     * live at once, like Python's ``room.record`` side effect. */
+    start(): void;
+    private record;
+    private onEnd;
+    /** Stop capturing (idempotent). Also fires the room's recorder-changed seam so a wave-4 capture
+     * offer engaged under this recorder disengages. */
+    stop(): void;
+    [Symbol.dispose]: () => void;
+    [Symbol.asyncDispose]: () => Promise<void>;
+}
+//# sourceMappingURL=recorder.d.ts.map

package/dist/rooms/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/rooms/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAIzC;4FAC4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,UAAU,CAAA;AAEtF,oGAAoG;AACpG,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAEnE,wGAAwG;AACxG,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,iGAAiG;IACjG,IAAI,EAAE,YAAY,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;6FACyF;IACzF,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,OAAO,CAAqB;gBAExB,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO;IAK7C;gBACY;IACZ,IAAI,IAAI,IAAI,OAAO,CAElB;IAED;qGACiG;IACjG,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,yDAAyD;IACzD,IAAI,aAAa,IAAI,kBAAkB,GAAG,IAAI,CAE7C;IAED;iGAC6F;IAC7F,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED;kEAC8D;IAC9D,KAAK,IAAI,IAAI;YAyBC,MAAM;IA4CpB,OAAO,CAAC,KAAK;IAWb;uDACmD;IACnD,IAAI,IAAI,IAAI;IAUJ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD"}

package/dist/rooms/recorder.js

@@ -0,0 +1,157 @@
+/**
+ * The room→session recorder — the single durable binding between a live room (pure transport,
+ * nothing stored) and a session (an append-only durable log). Started by {@link ./room.Room.record};
+ * a line-for-line port of the Python SDK's ``_AsyncRecorder`` (aio.py).
+ *
+ * It rides an **observe** SSE stream ({@link ./sse.RoomEventStream} in observe mode — no presence
+ * connection, so the recorder is invisible in the roster) and bridges every durable-worthy signal
+ * into ``session.event(...)``, stamping provenance (``via``). The skip rules mirror Python exactly:
+ * a ``ready`` frame, a ``presence.*`` signal, and anything marked ``ephemeral`` (beats, cursors, live
+ * captions, relayed vectors) are **not** recorded — only real, durable signals are.
+ *
+ * Lifecycle: a dropped stream reconnects with backoff (the gap is lost — rooms have no replay), so a
+ * blip never ends capture. Only a **terminal** end stops it, cleanly, with a {@link RecorderStopReason}:
+ * a connect-code rotation (``code-rotated`` — the consent boundary between studies) or the room being
+ * gone / its code rejected. An explicit {@link Recorder.stop} is the ``stopped`` reason. It never
+ * throws to the caller; check {@link Recorder.error} for a server refusal.
+ */
+import { APIError } from "../errors.js";
+import { buildSessionEvent } from "../shaping/rooms.js";
+import { RoomEventStream } from "./sse.js";
+export class Recorder {
+    deps;
+    session;
+    stream = null;
+    started = false;
+    ended = false;
+    reason = null;
+    failure = null;
+    constructor(deps, into) {
+        this.deps = deps;
+        this.session = into;
+    }
+    /** The session this recorder writes into — the durable binding a wave-4 capture offer engages
+     * under. */
+    get into() {
+        return this.session;
+    }
+    /** True while the capture loop runs (streaming or reconnecting) and has not begun winding down —
+     * a recorder in its terminal wind-down already counts as gone (mirror of Python's ``alive``). */
+    get alive() {
+        return this.started && !this.ended;
+    }
+    /** Why the recorder stopped, or ``null`` while alive. */
+    get stoppedReason() {
+        return this.reason;
+    }
+    /** The error that ended the capture for good — a server refusal (the room gone, or a rejected
+     * code). ``null`` while alive, after a clean rotation, or after an explicit {@link stop}. */
+    get error() {
+        return this.failure;
+    }
+    /** Begin capturing (idempotent). Starts immediately in the background — the returned handle is
+     * live at once, like Python's ``room.record`` side effect. */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        // Announce the fresh recorder before the stream opens, so a capture offer can engage against it.
+        this.deps.onChange();
+        const stream = new RoomEventStream({
+            roomId: this.deps.roomId,
+            code: this.deps.code,
+            baseUrl: this.deps.baseUrl,
+            observe: true,
+            reconnect: this.deps.reconnect,
+            fetchImpl: this.deps.fetchImpl,
+            onSignal: (sig) => this.record(sig),
+            onEnd: (r) => this.onEnd(r),
+        });
+        this.stream = stream;
+        // Terminal ends arrive via onEnd; a pre-ready reject (reconnect off) is swallowed the same way.
+        void stream.connect().catch(() => { });
+    }
+    // Bridge one live signal into the session, applying the durable-worthy skip rules. Awaited by the
+    // observe stream's read loop (onSignal), so the write is **inline**: the next frame isn't read
+    // until this settles — Python's backpressure, no unbounded queue of in-flight POSTs. The observe
+    // stream only delivers ``event: signal`` frames here (a ``ready`` never reaches onSignal), so the
+    // filter mirrors Python's ``event.ephemeral or event.is_presence`` on top of the kind check.
+    async record(sig) {
+        if (this.ended)
+            return;
+        const type = sig.type ?? "";
+        // Skip the rotation advance-signal by name (Python checks it before the ephemeral skip; the
+        // transport also winds the recorder down via onEnd), then presence + ephemeral noise.
+        if (type === "room.code_rotated")
+            return;
+        if (sig.ephemeral || type.startsWith("presence."))
+            return;
+        const via = {
+            room_id: this.deps.roomId,
+            room_name: this.deps.roomName,
+            from: sig.from ?? null,
+            to: sig.to || "all",
+        };
+        const req = buildSessionEvent(this.session.id, {
+            type,
+            payload: sig.payload ?? {},
+            source: sig.source ?? undefined,
+            via,
+        });
+        try {
+            await this.deps.rest(req);
+        }
+        catch (err) {
+            if (this.ended)
+                return;
+            // Mirror Python's recorder: a session-write refusal with status < 500 (and ≠ 429) is TERMINAL
+            // — the server rejected us and no retry heals a 4xx, so stop for good (``.error`` set, seam
+            // fires so a bound capture offer disengages). A transient failure (5xx / 429 / network) is
+            // rethrown so the observe stream drops and reconnects with backoff (the gap is lost — rooms
+            // have no replay — but capture continues), exactly as Python backs off on a transient write.
+            if (err instanceof APIError && err.status < 500 && err.status !== 429) {
+                this.failure = err;
+                this.ended = true;
+                this.stream?.close();
+                this.stream = null;
+                console.error(`Atrium recorder: session event '${type}' refused (${err.status}); stopping:`, err);
+                this.deps.onChange();
+                return;
+            }
+            throw err;
+        }
+    }
+    onEnd(reason) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.reason = reason;
+        // A rotation is a clean wind-down (the consent boundary); a gone room / bad code is a refusal.
+        if (reason !== "code-rotated") {
+            this.failure = new Error(`recorder stopped: room ${reason}`);
+        }
+        this.deps.onChange();
+    }
+    /** Stop capturing (idempotent). Also fires the room's recorder-changed seam so a wave-4 capture
+     * offer engaged under this recorder disengages. */
+    stop() {
+        if (!this.ended) {
+            this.ended = true;
+            this.reason = "stopped";
+        }
+        this.stream?.close();
+        this.stream = null;
+        this.deps.onChange();
+    }
+}
+if (typeof Symbol.dispose === "symbol") {
+    Recorder.prototype[Symbol.dispose] = function () {
+        this.stop();
+    };
+}
+if (typeof Symbol.asyncDispose === "symbol") {
+    Recorder.prototype[Symbol.asyncDispose] = async function () {
+        this.stop();
+    };
+}
+//# sourceMappingURL=recorder.js.map

package/dist/rooms/recorder.js.map

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