hci-atrium 0.1.0

package/dist/react/index.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * React bindings for ``hci-atrium`` — ``hci-atrium/react``.
+ *
+ * ``<AtriumProvider>`` subscribes to auth changes and exposes the client + user via context;
+ * ``useAtrium`` / ``useUser`` read it; ``<RequireSignIn>`` gates a subtree behind sign-in.
+ *
+ * ``useUser()`` distinguishes three states: ``undefined`` while the initial auth check is still in
+ * flight, ``null`` when signed out, and a ``User`` when signed in.
+ */
+import { createContext, useContext, useEffect, useState } from "react";
+const AtriumContext = createContext(null);
+/** Provides the ``Atrium`` client and the live user to the ``useAtrium`` / ``useUser`` hooks. */
+export function AtriumProvider({ atrium, children }) {
+    const [user, setUser] = useState(undefined);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let active = true;
+        const unsubscribe = atrium.auth.onChange((next) => {
+            if (active) {
+                setUser(next);
+                // A successful sign-in clears any prior error; a sign-out leaves the last error in place
+                // so the surface (e.g. a state-mismatch) is still readable.
+                if (next) {
+                    setError(null);
+                }
+            }
+        });
+        const unsubscribeError = atrium.auth.onError((err) => {
+            if (active) {
+                setError(err);
+            }
+        });
+        // Once initial auth settles, adopt the resolved state (null or a user) + any surfaced error.
+        atrium.ready().then(() => {
+            if (active) {
+                setUser(atrium.auth.user);
+                setError(atrium.auth.error);
+            }
+        });
+        return () => {
+            active = false;
+            unsubscribe();
+            unsubscribeError();
+        };
+    }, [atrium]);
+    return _jsx(AtriumContext.Provider, { value: { atrium, user, error }, children: children });
+}
+function useAtriumContext() {
+    const ctx = useContext(AtriumContext);
+    if (!ctx) {
+        throw new Error("Atrium React hooks must be used within an <AtriumProvider>");
+    }
+    return ctx;
+}
+/** The ``Atrium`` client from the nearest provider. */
+export function useAtrium() {
+    return useAtriumContext().atrium;
+}
+/** The signed-in user: ``undefined`` while loading, ``null`` when signed out, else the ``User``. */
+export function useUser() {
+    return useAtriumContext().user;
+}
+/** The most recent auth error (state mismatch, exchange or refresh failure), or ``null``. */
+export function useAuthError() {
+    return useAtriumContext().error;
+}
+/**
+ * Render ``children`` only once signed in; otherwise render ``fallback`` (or a default sign-in
+ * button). Renders nothing while the initial auth check is still in flight.
+ *
+ * This is a UX guard, not a security boundary — see the README caveat.
+ */
+export function RequireSignIn({ children, fallback }) {
+    const { atrium, user } = useAtriumContext();
+    if (user === undefined) {
+        return null;
+    }
+    if (user === null) {
+        return fallback !== undefined ? fallback : _jsx(DefaultSignIn, { atrium: atrium });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+function DefaultSignIn({ atrium }) {
+    return (_jsx("button", { type: "button", onClick: () => {
+            void atrium.auth.signIn();
+        }, children: "Sign in with Atrium" }));
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

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

package/dist/rooms/armed-set.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The armed-set state machine shared by both standing offers (multi-mic scoping,
+ * docs/reference/rooms-sessions-protocol.md) — the TypeScript port of Python's ``_ArmedSet``
+ * (aio.py). Sources are **connection ids** (the ``from`` the server stamps on a ``*.start`` /
+ * ``*.stop`` request, never a client-supplied field).
+ *
+ * Membership = explicit per-source arms ∪ (an all-arm minus the per-source stops issued *since*
+ * that all-arm). A fresh all-arm resets those exclusions (every device shows ON again); an all-stop
+ * clears everything. A ``null`` source — a v1 (single implicit source) frame that carries no id — is
+ * armed **only under an all-arm** (the v1 compatibility rule, since an unscoped ``start`` arms all):
+ * a scoped per-source arm deliberately excludes id-less v1 audio so it can't bleed into a scoped
+ * session.
+ */
+export declare class ArmedSet {
+    private all;
+    private readonly explicitSet;
+    private readonly excludedSet;
+    arm(source: string): void;
+    armAll(): void;
+    disarm(source: string): void;
+    /** Move an explicit arm from a departed connection id to its same-name reconnect (a new id), so a
+     * per-source-armed device that drops and returns within grace stays admitted (its consent — they
+     * pressed ON — survives a wifi blip). No-op unless ``old`` was explicitly armed. */
+    migrate(oldId: string, newId: string): void;
+    clear(): void;
+    isArmed(source: string | null): boolean;
+    /** The explicitly per-source-armed connection ids (drives the arm-time source cap). */
+    get explicit(): Set<string>;
+    /** True while a standing all-arm is in effect (drives the roster-enumerated active set). */
+    get allArmed(): boolean;
+    get any(): boolean;
+}
+//# sourceMappingURL=armed-set.d.ts.map

package/dist/rooms/armed-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"armed-set.d.ts","sourceRoot":"","sources":["../../src/rooms/armed-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKzB,MAAM,IAAI,IAAI;IAKd,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B;;wFAEoF;IACpF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQ3C,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAMvC,uFAAuF;IACvF,IAAI,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,CAE1B;IAED,4FAA4F;IAC5F,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,GAAG,IAAI,OAAO,CAEjB;CACF"}

package/dist/rooms/armed-set.js

@@ -0,0 +1,65 @@
+/**
+ * The armed-set state machine shared by both standing offers (multi-mic scoping,
+ * docs/reference/rooms-sessions-protocol.md) — the TypeScript port of Python's ``_ArmedSet``
+ * (aio.py). Sources are **connection ids** (the ``from`` the server stamps on a ``*.start`` /
+ * ``*.stop`` request, never a client-supplied field).
+ *
+ * Membership = explicit per-source arms ∪ (an all-arm minus the per-source stops issued *since*
+ * that all-arm). A fresh all-arm resets those exclusions (every device shows ON again); an all-stop
+ * clears everything. A ``null`` source — a v1 (single implicit source) frame that carries no id — is
+ * armed **only under an all-arm** (the v1 compatibility rule, since an unscoped ``start`` arms all):
+ * a scoped per-source arm deliberately excludes id-less v1 audio so it can't bleed into a scoped
+ * session.
+ */
+export class ArmedSet {
+    all = false;
+    explicitSet = new Set();
+    excludedSet = new Set();
+    arm(source) {
+        this.explicitSet.add(source);
+        this.excludedSet.delete(source);
+    }
+    armAll() {
+        this.all = true;
+        this.excludedSet.clear(); // a fresh all-arm forgets prior per-source stops
+    }
+    disarm(source) {
+        this.explicitSet.delete(source);
+        if (this.all)
+            this.excludedSet.add(source); // excluded from the standing all-arm
+    }
+    /** Move an explicit arm from a departed connection id to its same-name reconnect (a new id), so a
+     * per-source-armed device that drops and returns within grace stays admitted (its consent — they
+     * pressed ON — survives a wifi blip). No-op unless ``old`` was explicitly armed. */
+    migrate(oldId, newId) {
+        if (this.explicitSet.has(oldId)) {
+            this.explicitSet.delete(oldId);
+            this.explicitSet.add(newId);
+            this.excludedSet.delete(newId);
+        }
+    }
+    clear() {
+        this.all = false;
+        this.explicitSet.clear();
+        this.excludedSet.clear();
+    }
+    isArmed(source) {
+        if (source === null)
+            return this.all; // a v1 id-less frame rides ONLY on an all-arm (the v1 rule)
+        if (this.explicitSet.has(source))
+            return true;
+        return this.all && !this.excludedSet.has(source);
+    }
+    /** The explicitly per-source-armed connection ids (drives the arm-time source cap). */
+    get explicit() {
+        return this.explicitSet;
+    }
+    /** True while a standing all-arm is in effect (drives the roster-enumerated active set). */
+    get allArmed() {
+        return this.all;
+    }
+    get any() {
+        return this.all || this.explicitSet.size > 0;
+    }
+}
+//# sourceMappingURL=armed-set.js.map

package/dist/rooms/armed-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"armed-set.js","sourceRoot":"","sources":["../../src/rooms/armed-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,QAAQ;IACX,GAAG,GAAG,KAAK,CAAA;IACF,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IAEhD,GAAG,CAAC,MAAc;QAChB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,GAAG,GAAG,IAAI,CAAA;QACf,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA,CAAC,iDAAiD;IAC5E,CAAC;IAED,MAAM,CAAC,MAAc;QACnB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC/B,IAAI,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA,CAAC,qCAAqC;IAClF,CAAC;IAED;;wFAEoF;IACpF,OAAO,CAAC,KAAa,EAAE,KAAa;QAClC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAC9B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YAC3B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,GAAG,KAAK,CAAA;QAChB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;QACxB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;IAC1B,CAAC;IAED,OAAO,CAAC,MAAqB;QAC3B,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,GAAG,CAAA,CAAC,4DAA4D;QACjG,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAA;QAC7C,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClD,CAAC;IAED,uFAAuF;IACvF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;IAED,4FAA4F;IAC5F,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,GAAG,CAAA;IACjB,CAAC;IAED,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,CAAA;IAC9C,CAAC;CACF"}

package/dist/rooms/brokers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure request-shaping for a {@link ./room.Room}'s capability brokers (``offerEmbeds`` /
+ * ``offerChat``, docs/reference/rooms-sessions-protocol.md) plus the standing-offer roles — the
+ * TypeScript port of Python's ``_brokers.py``. Validation only, no I/O, so it's cheaply unit-testable
+ * independent of a transport.
+ */
+import { AtriumError } from "../errors.js";
+/** Discoverable presence roles for the capability brokers — merged into ``announce.roles`` so a
+ * code-joined peer can find a broker in the presence roster. */
+export declare const EMBED_BROKER_ROLE = "embed-broker";
+export declare const CHAT_BROKER_ROLE = "chat-broker";
+/** Standing-service offer roles (the third broker kind — peer-toggleable via ``<service>.start`` /
+ * ``<service>.stop`` requests; see ``offerTranscription`` / ``offerAudioCapture``). */
+export declare const TRANSCRIPTION_OFFER_ROLE = "transcription-offer";
+export declare const CAPTURE_OFFER_ROLE = "capture-offer";
+/** ``offerEmbeds``'s default anchor-count cap on one ``embed.resolve`` request. */
+export declare const DEFAULT_MAX_ANCHORS = 64;
+/** ``offerChat``'s default ``maxTokens`` cap on one ``chat.generate`` reply. */
+export declare const DEFAULT_CHAT_MAX_TOKENS = 512;
+/** A sane request-payload cap for ``chat.generate`` — independent of ``maxTokens`` (which caps the
+ * *reply*, not the incoming prompt). */
+export declare const CHAT_MAX_MESSAGES = 50;
+export declare const CHAT_MAX_PAYLOAD_CHARS = 20000;
+/** One anchor, or a whole ``chat.generate`` request, failed to validate/resolve — the message is
+ * safe to send back verbatim in an error reply. Under {@link AtriumError} so one ``catch`` covers the
+ * whole SDK surface (errors.ts: everything derives from ``AtriumError``). */
+export declare class BrokerError extends AtriumError {
+}
+/** A validated ``embed.resolve`` anchor descriptor — one of text / concept / vector / asset. */
+export type AnchorDescriptor = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "concept";
+    concept: string;
+    collection: string | null;
+} | {
+    kind: "vector";
+    vector: number[];
+} | {
+    kind: "asset";
+    asset: string;
+    matchBy: string | null;
+};
+/**
+ * Validate one ``embed.resolve`` anchor descriptor (the compare operand JSON shapes) and return its
+ * parsed form. Throws {@link BrokerError} on anything malformed. An ``asset`` descriptor resolves
+ * through the per-asset vectors endpoint (the broker looks up the asset's stored vector in the
+ * request's space).
+ */
+export declare function parseAnchorDescriptor(desc: unknown): AnchorDescriptor;
+/** One validated ``chat.generate`` message. */
+export interface ChatMessage {
+    role: string;
+    content: string;
+}
+/**
+ * Validate a ``chat.generate`` request's ``messages`` — a non-empty list of ``{ role, content }``
+ * (both strings), under the payload cap. Throws {@link BrokerError} otherwise.
+ */
+export declare function validateChatMessages(messages: unknown): ChatMessage[];
+//# sourceMappingURL=brokers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brokers.d.ts","sourceRoot":"","sources":["../../src/rooms/brokers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C;gEACgE;AAChE,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAC/C,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAE7C;uFACuF;AACvF,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAC7D,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C;wCACwC;AACxC,eAAO,MAAM,iBAAiB,KAAK,CAAA;AACnC,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAE5C;;6EAE6E;AAC7E,qBAAa,WAAY,SAAQ,WAAW;CAAG;AAE/C,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAM5D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CA4CrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,WAAW,EAAE,CAuBrE"}

package/dist/rooms/brokers.js

@@ -0,0 +1,109 @@
+/**
+ * Pure request-shaping for a {@link ./room.Room}'s capability brokers (``offerEmbeds`` /
+ * ``offerChat``, docs/reference/rooms-sessions-protocol.md) plus the standing-offer roles — the
+ * TypeScript port of Python's ``_brokers.py``. Validation only, no I/O, so it's cheaply unit-testable
+ * independent of a transport.
+ */
+import { AtriumError } from "../errors.js";
+/** Discoverable presence roles for the capability brokers — merged into ``announce.roles`` so a
+ * code-joined peer can find a broker in the presence roster. */
+export const EMBED_BROKER_ROLE = "embed-broker";
+export const CHAT_BROKER_ROLE = "chat-broker";
+/** Standing-service offer roles (the third broker kind — peer-toggleable via ``<service>.start`` /
+ * ``<service>.stop`` requests; see ``offerTranscription`` / ``offerAudioCapture``). */
+export const TRANSCRIPTION_OFFER_ROLE = "transcription-offer";
+export const CAPTURE_OFFER_ROLE = "capture-offer";
+/** ``offerEmbeds``'s default anchor-count cap on one ``embed.resolve`` request. */
+export const DEFAULT_MAX_ANCHORS = 64;
+/** ``offerChat``'s default ``maxTokens`` cap on one ``chat.generate`` reply. */
+export const DEFAULT_CHAT_MAX_TOKENS = 512;
+/** A sane request-payload cap for ``chat.generate`` — independent of ``maxTokens`` (which caps the
+ * *reply*, not the incoming prompt). */
+export const CHAT_MAX_MESSAGES = 50;
+export const CHAT_MAX_PAYLOAD_CHARS = 20_000;
+/** One anchor, or a whole ``chat.generate`` request, failed to validate/resolve — the message is
+ * safe to send back verbatim in an error reply. Under {@link AtriumError} so one ``catch`` covers the
+ * whole SDK surface (errors.ts: everything derives from ``AtriumError``). */
+export class BrokerError extends AtriumError {
+}
+function isNumber(x) {
+    return typeof x === "number" && !Number.isNaN(x);
+}
+/**
+ * Validate one ``embed.resolve`` anchor descriptor (the compare operand JSON shapes) and return its
+ * parsed form. Throws {@link BrokerError} on anything malformed. An ``asset`` descriptor resolves
+ * through the per-asset vectors endpoint (the broker looks up the asset's stored vector in the
+ * request's space).
+ */
+export function parseAnchorDescriptor(desc) {
+    if (typeof desc !== "object" || desc === null || Array.isArray(desc)) {
+        throw new BrokerError("anchor descriptor must be a JSON object");
+    }
+    const obj = desc;
+    const present = ["text", "concept", "vector", "asset"].filter((k) => k in obj);
+    if (present.length !== 1) {
+        throw new BrokerError("anchor descriptor needs exactly one of text/concept/vector/asset");
+    }
+    const kind = present[0];
+    if (kind === "asset") {
+        const asset = obj.asset;
+        if (typeof asset !== "string" || asset.trim() === "") {
+            throw new BrokerError("asset must be a non-empty id string");
+        }
+        const matchBy = obj.match_by;
+        if (matchBy !== undefined && matchBy !== null && typeof matchBy !== "string") {
+            throw new BrokerError("match_by must be a string");
+        }
+        return { kind: "asset", asset, matchBy: matchBy ?? null };
+    }
+    if (kind === "vector") {
+        const vec = obj.vector;
+        if (!Array.isArray(vec) || vec.length === 0 || !vec.every(isNumber)) {
+            throw new BrokerError("vector must be a non-empty list of numbers");
+        }
+        return { kind: "vector", vector: vec.map(Number) };
+    }
+    if (kind === "text") {
+        const text = obj.text;
+        if (typeof text !== "string" || text.trim() === "") {
+            throw new BrokerError("text must be a non-empty string");
+        }
+        return { kind: "text", text };
+    }
+    const concept = obj.concept;
+    if (typeof concept !== "string" || concept.trim() === "") {
+        throw new BrokerError("concept must be a non-empty string");
+    }
+    const collection = obj.collection;
+    if (collection !== undefined && collection !== null && typeof collection !== "string") {
+        throw new BrokerError("collection must be a string");
+    }
+    return { kind: "concept", concept, collection: collection ?? null };
+}
+/**
+ * Validate a ``chat.generate`` request's ``messages`` — a non-empty list of ``{ role, content }``
+ * (both strings), under the payload cap. Throws {@link BrokerError} otherwise.
+ */
+export function validateChatMessages(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) {
+        throw new BrokerError("messages must be a non-empty list");
+    }
+    if (messages.length > CHAT_MAX_MESSAGES) {
+        throw new BrokerError(`too many messages (${messages.length} > ${CHAT_MAX_MESSAGES})`);
+    }
+    let totalChars = 0;
+    for (const message of messages) {
+        if (typeof message !== "object" ||
+            message === null ||
+            typeof message.role !== "string" ||
+            typeof message.content !== "string") {
+            throw new BrokerError("each message needs a string role and content");
+        }
+        totalChars += message.content.length;
+    }
+    if (totalChars > CHAT_MAX_PAYLOAD_CHARS) {
+        throw new BrokerError(`messages exceed ${CHAT_MAX_PAYLOAD_CHARS} characters`);
+    }
+    return messages;
+}
+//# sourceMappingURL=brokers.js.map

package/dist/rooms/brokers.js.map

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

package/dist/rooms/codec.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Audio-signal wire protocol — extracted verbatim from the Player/tools implementation
+ * (``tools/src/lib/audio-frame.ts`` + ``audio-protocol.ts``) so the SDK decodes exactly what a
+ * hosted Player produces.
+ *
+ * Two channels ride a room (see ``docs/plans/audio-signal-streaming.md``):
+ *   • the continuous per-frame analysis stream → **raw binary** frames (this file's
+ *     {@link decodeAudioFrame}), quantized to bytes; visualization doesn't need float precision.
+ *   • everything else (track context, discrete beats, producer discovery) → **text signals**, whose
+ *     type names and payload shapes are pinned by {@link AUDIO_SIGNAL} / the interfaces below.
+ */
+export declare const AUDIO_FRAME_MAGIC = 161;
+export declare const AUDIO_FRAME_VERSION = 1;
+/** One analysis frame in normalized units — every scalar 0..1 except ``bpm`` (BPM) and ``onsetRate``. */
+export interface AudioFrame {
+    level: number;
+    peak: number;
+    centroid: number;
+    flatness: number;
+    rolloff: number;
+    beatPhase: number;
+    energyTrend: number;
+    onsetRate: number;
+    bpm: number;
+    bands: number[];
+}
+/** Pack a frame into a compact binary buffer. Bands are capped at 255. */
+export declare function encodeAudioFrame(f: AudioFrame): ArrayBuffer;
+/** Decode a binary frame, or ``null`` if it isn't a recognized audio frame (foreign/short/bad magic). */
+export declare function decodeAudioFrame(data: ArrayBuffer): AudioFrame | null;
+/** True if a binary frame looks like an audio frame (cheap magic check before a full decode). */
+export declare function isAudioFrame(data: ArrayBuffer): boolean;
+export declare const AUDIO_SIGNAL: {
+    /** Producer → room: structural track context (bpm/key/beat grid). Low-rate, re-emitted to joiners. */
+    readonly track: "audio.track";
+    /** Producer → room: an instantaneous beat event. */
+    readonly beat: "audio.beat";
+    /** Consumer → room: "who can provide audio analysis?" (carries an ack_id). */
+    readonly discover: "audio.discover";
+    /** Producer → consumer: availability announcement (reply_to a discover, or a proactive broadcast). */
+    readonly announce: "audio.announce";
+};
+/**
+ * Presence roles announced on room join (in ``announce.role``). Producers and consumers advertise
+ * themselves so a producer can tell whether a consumer is present (demand) and which producer is
+ * elected to broadcast (lowest connection_id among producers).
+ */
+export declare const AUDIO_ROLE: {
+    readonly producer: "audio-analysis";
+    readonly consumer: "audio-consumer";
+};
+export type AudioInputKind = "playback" | "mic";
+export interface AudioTrack {
+    /** Producer identity (e.g. ``analyzer:studio``). */
+    source: string;
+    input: AudioInputKind;
+    name?: string;
+    assetId?: string;
+    bpm?: number | null;
+    key?: string;
+    mode?: string;
+    durationS?: number;
+    /** Precomputed beat times in seconds (playback input only). */
+    beatGrid?: number[];
+    sections?: {
+        t: number;
+        label?: string;
+    }[];
+}
+export interface AudioBeatEvent {
+    /** Producer clock (ms). */
+    t: number;
+    strength: number;
+    kind?: "beat" | "onset" | "downbeat";
+}
+export interface AudioAnnounce {
+    identity: string;
+    input: AudioInputKind;
+    name?: string;
+}
+/**
+ * A decoded audio-signal event, as delivered to a {@link "./room".Room.audioSignals} subscriber.
+ * Discriminated by ``kind`` so a consumer switches on it: continuous ``frame``s carry the
+ * loudness/spectrum stream, ``beat``s the discrete onsets, ``track`` the structural context, and
+ * ``announce`` a producer's availability.
+ */
+export type AudioSignal = {
+    kind: "frame";
+    frame: AudioFrame;
+} | {
+    kind: "beat";
+    beat: AudioBeatEvent;
+} | {
+    kind: "track";
+    track: AudioTrack;
+} | {
+    kind: "announce";
+    announce: AudioAnnounce;
+};
+//# sourceMappingURL=codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/rooms/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,eAAO,MAAM,iBAAiB,MAAO,CAAA;AACrC,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAGpC,yGAAyG;AACzG,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAUD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,WAAW,CAsB3D;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAuBrE;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEvD;AAID,eAAO,MAAM,YAAY;IACvB,sGAAsG;;IAEtG,oDAAoD;;IAEpD,8EAA8E;;IAE9E,sGAAsG;;CAE9F,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;CAGb,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,KAAK,CAAA;AAE/C,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,cAAc,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAA;IACT,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAA;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,cAAc,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,CAAA"}

package/dist/rooms/codec.js

@@ -0,0 +1,101 @@
+/**
+ * Audio-signal wire protocol — extracted verbatim from the Player/tools implementation
+ * (``tools/src/lib/audio-frame.ts`` + ``audio-protocol.ts``) so the SDK decodes exactly what a
+ * hosted Player produces.
+ *
+ * Two channels ride a room (see ``docs/plans/audio-signal-streaming.md``):
+ *   • the continuous per-frame analysis stream → **raw binary** frames (this file's
+ *     {@link decodeAudioFrame}), quantized to bytes; visualization doesn't need float precision.
+ *   • everything else (track context, discrete beats, producer discovery) → **text signals**, whose
+ *     type names and payload shapes are pinned by {@link AUDIO_SIGNAL} / the interfaces below.
+ */
+// --- binary frame codec (the "hot" channel) ----------------------------------------------------
+export const AUDIO_FRAME_MAGIC = 0xa1;
+export const AUDIO_FRAME_VERSION = 1;
+const HEADER_BYTES = 13; // magic, version, nBands, 8 scalar u8s, bpm u16
+const clamp01 = (x) => (x <= 0 ? 0 : x >= 1 ? 1 : x);
+const q8 = (x) => Math.round(clamp01(x) * 255); // 0..1 → byte
+const dq8 = (b) => b / 255; // byte → 0..1
+// onsetRate spans ~0..25 /s; store at 0.1 resolution in a byte (0..25.5).
+const qOnset = (x) => Math.round(Math.min(Math.max(x, 0), 25.5) * 10);
+const dqOnset = (b) => b / 10;
+/** Pack a frame into a compact binary buffer. Bands are capped at 255. */
+export function encodeAudioFrame(f) {
+    const n = Math.min(f.bands.length, 255);
+    const buf = new ArrayBuffer(HEADER_BYTES + n);
+    const view = new DataView(buf);
+    view.setUint8(0, AUDIO_FRAME_MAGIC);
+    view.setUint8(1, AUDIO_FRAME_VERSION);
+    view.setUint8(2, n);
+    view.setUint8(3, q8(f.level));
+    view.setUint8(4, q8(f.peak));
+    view.setUint8(5, q8(f.centroid));
+    view.setUint8(6, q8(f.flatness));
+    view.setUint8(7, q8(f.rolloff));
+    view.setUint8(8, q8(f.beatPhase));
+    view.setUint8(9, q8(f.energyTrend));
+    view.setUint8(10, qOnset(f.onsetRate));
+    view.setUint16(11, Math.min(Math.round(Math.max(f.bpm, 0)), 65535), true);
+    const bytes = new Uint8Array(buf);
+    // The `?? 0` here and in `decodeAudioFrame` are the only deliberate divergences from the source
+    // `tools/src/lib/audio-frame.ts` (which indexes `f.bands[i]` bare) — the SDK's stricter
+    // `noUncheckedIndexedAccess` needs the guard. tools/ migrates onto this module later (plan step 3).
+    for (let i = 0; i < n; i++)
+        bytes[HEADER_BYTES + i] = q8(f.bands[i] ?? 0);
+    return buf;
+}
+/** Decode a binary frame, or ``null`` if it isn't a recognized audio frame (foreign/short/bad magic). */
+export function decodeAudioFrame(data) {
+    if (data.byteLength < HEADER_BYTES)
+        return null;
+    const view = new DataView(data);
+    if (view.getUint8(0) !== AUDIO_FRAME_MAGIC)
+        return null;
+    if (view.getUint8(1) !== AUDIO_FRAME_VERSION)
+        return null;
+    const n = view.getUint8(2);
+    if (data.byteLength < HEADER_BYTES + n)
+        return null;
+    const bytes = new Uint8Array(data);
+    const bands = new Array(n);
+    // `?? 0`: see the note in `encodeAudioFrame` — a `noUncheckedIndexedAccess` guard, not in tools/.
+    for (let i = 0; i < n; i++)
+        bands[i] = dq8(bytes[HEADER_BYTES + i] ?? 0);
+    return {
+        level: dq8(view.getUint8(3)),
+        peak: dq8(view.getUint8(4)),
+        centroid: dq8(view.getUint8(5)),
+        flatness: dq8(view.getUint8(6)),
+        rolloff: dq8(view.getUint8(7)),
+        beatPhase: dq8(view.getUint8(8)),
+        energyTrend: dq8(view.getUint8(9)),
+        onsetRate: dqOnset(view.getUint8(10)),
+        bpm: view.getUint16(11, true),
+        bands,
+    };
+}
+/** True if a binary frame looks like an audio frame (cheap magic check before a full decode). */
+export function isAudioFrame(data) {
+    return data.byteLength >= 2 && new Uint8Array(data)[0] === AUDIO_FRAME_MAGIC;
+}
+// --- text-signal names + payload shapes (the reliable channel) ---------------------------------
+export const AUDIO_SIGNAL = {
+    /** Producer → room: structural track context (bpm/key/beat grid). Low-rate, re-emitted to joiners. */
+    track: "audio.track",
+    /** Producer → room: an instantaneous beat event. */
+    beat: "audio.beat",
+    /** Consumer → room: "who can provide audio analysis?" (carries an ack_id). */
+    discover: "audio.discover",
+    /** Producer → consumer: availability announcement (reply_to a discover, or a proactive broadcast). */
+    announce: "audio.announce",
+};
+/**
+ * Presence roles announced on room join (in ``announce.role``). Producers and consumers advertise
+ * themselves so a producer can tell whether a consumer is present (demand) and which producer is
+ * elected to broadcast (lowest connection_id among producers).
+ */
+export const AUDIO_ROLE = {
+    producer: "audio-analysis",
+    consumer: "audio-consumer",
+};
+//# sourceMappingURL=codec.js.map

package/dist/rooms/codec.js.map

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

package/dist/rooms/index.d.ts

@@ -0,0 +1,40 @@
+/** The live rooms surface — the {@link Room} handle, its audio codec, and the loginless
+ * {@link joinRoom} entry (no client needed, just a connect code). */
+import { Room, type RoomTransportMode } from "./room.js";
+import type { FetchImpl } from "./sse.js";
+import type { WebSocketCtor } from "./transport.js";
+export { ArmedSet } from "./armed-set.js";
+export { type AnchorDescriptor, BrokerError, CAPTURE_OFFER_ROLE, CHAT_BROKER_ROLE, DEFAULT_CHAT_MAX_TOKENS, DEFAULT_MAX_ANCHORS, EMBED_BROKER_ROLE, parseAnchorDescriptor, TRANSCRIPTION_OFFER_ROLE, validateChatMessages, } from "./brokers.js";
+export { AUDIO_ROLE, AUDIO_SIGNAL, type AudioAnnounce, type AudioBeatEvent, type AudioFrame, type AudioInputKind, type AudioSignal, type AudioTrack, decodeAudioFrame, encodeAudioFrame, isAudioFrame, } from "./codec.js";
+export { type CaptureOfferDeps, type CaptureRecorder, OfferedCapture } from "./offer-capture.js";
+export { OfferedTranscription, type TranscriptionOfferDeps } from "./offer-transcription.js";
+export { mergeRoles, type Participant, type ParticipantPredicate, parseParticipant, participantMatches, } from "./participant.js";
+export { Recorder, type RecorderStopReason } from "./recorder.js";
+export { type AudioClip, type AudioVector, type Handler, Room, type RoomAudioClient, type RoomDeps, type RoomEvent, type RoomTransportMode, type ScoredAudio, } from "./room.js";
+export { AUDIO_SNIPPET_CONSUMER_ROLE, AUDIO_SNIPPET_MAGIC, AUDIO_SNIPPET_SOURCE_ROLE, AUDIO_SNIPPET_VERSION, AUDIO_SNIPPET_VERSION_2, type AudioSnippetFrame, CAPTURE_SOURCE_ROLE, decodeAudioSnippetFrame, isAudioSnippetFrame, } from "./snippet.js";
+export { type FetchImpl, RoomEventStream, readObserveRoster } from "./sse.js";
+export { type ActiveSource, OFFER_MAX_SOURCES, type OfferDeps, StandingSource, } from "./standing-source.js";
+export { TRANSCRIBER_SOURCE, Transcriber, type TranscriberDeps } from "./transcriber.js";
+export type { RoomEndReason, RoomSignal, RoomTransport, RosterEntry, WebSocketCtor, WebSocketLike, } from "./transport.js";
+/** Options for the loginless {@link joinRoom} (a subset of {@link RoomDeps} — no account). */
+export interface JoinRoomOptions {
+    /** The instance base URL. Falls back to ``ATRIUM_BASE_URL``. */
+    baseUrl?: string;
+    identity?: string;
+    announce?: Record<string, unknown>;
+    requestTimeout?: number;
+    reconnect?: boolean;
+    /** Signal transport preference (default ``"auto"`` — WS, falling back to SSE behind a proxy). */
+    transport?: RoomTransportMode;
+    WebSocketCtor?: WebSocketCtor;
+    /** Injected ``fetch`` for the SSE transport / roster reads — the test seam. */
+    fetchImpl?: FetchImpl;
+    signal?: AbortSignal;
+}
+/**
+ * Join a room by its connect code — **no account, no client**. Resolves the code to a room, then
+ * returns a live {@link Room} handle that can ``send`` / ``on`` / ``request`` / play / consume audio
+ * signals (but not manage the room — that needs the owner). Mirrors the Python SDK's ``join_room``.
+ */
+export declare function joinRoom(code: string, opts?: JoinRoomOptions): Promise<Room>;
+//# sourceMappingURL=index.d.ts.map