@soulcraft/sdk 1.1.0 → 1.3.0

package/dist/modules/billing/portal-provider.js

@@ -0,0 +1,204 @@
+/**
+ * @module billing/portal-provider
+ * @description Portal-backed billing provider for unified cross-product credit tracking.
+ *
+ * Delegates all credit checks and usage recording to the Portal credit API at
+ * `https://portal.soulcraft.com/api/credits/*`. This ensures that a user's
+ * 1,000 monthly credits are shared across Workshop, Venue, and Academy — not siloed
+ * per product.
+ *
+ * Activated when `PORTAL_CREDIT_SECRET` is set in the environment. Takes precedence
+ * over the Firestore provider.
+ *
+ * **Endpoint summary:**
+ * ```
+ * POST /api/credits/check   — pre-flight before an AI call
+ * POST /api/credits/consume — deduct usage after a single AI response
+ * POST /api/credits/batch   — flush buffered usage at end of session
+ * ```
+ *
+ * All requests carry `X-Portal-Credit-Secret: <PORTAL_CREDIT_SECRET>`.
+ *
+ * Subscription data, top-up balances, and usage history are not surfaced via
+ * this API — those are managed by Portal directly. Methods that require them
+ * (`getUsageStatus`, `getSubscription`, `addTopUp`) return safe defaults.
+ * Products that need rich billing UI should call Portal's management API directly.
+ *
+ * @example
+ * ```typescript
+ * // Automatically selected when PORTAL_CREDIT_SECRET is set:
+ * const billing = createBillingModule()
+ *
+ * // Explicit override (e.g. for testing):
+ * const billing = createBillingModule({
+ *   provider: new PortalBillingProvider('https://portal.soulcraft.com', secret, 'workshop'),
+ * })
+ * ```
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Period helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function _currentPeriod() {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+function _thirtyDaysFromNow() {
+    return new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Portal-backed billing provider.
+ *
+ * Calls the Portal credit API for all gate checks and usage recording.
+ * All requests are authenticated with the `X-Portal-Credit-Secret` header.
+ *
+ * The `userId` parameter on all methods must be the user's **email address** —
+ * the same identifier Portal uses to look up the license document.
+ */
+export class PortalBillingProvider {
+    baseUrl;
+    secret;
+    product;
+    /**
+     * @param baseUrl - Portal base URL (e.g. `"https://portal.soulcraft.com"`).
+     * @param secret - The value of `PORTAL_CREDIT_SECRET`.
+     * @param product - The product name sent with consume/batch calls (`'workshop'`, `'venue'`, `'academy'`).
+     */
+    constructor(baseUrl, secret, product) {
+        this.baseUrl = baseUrl;
+        this.secret = secret;
+        this.product = product;
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    _headers() {
+        return {
+            'Content-Type': 'application/json',
+            'X-Portal-Credit-Secret': this.secret,
+        };
+    }
+    async _post(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Portal credit API error (${response.status}) at ${path}`);
+        }
+        return response.json();
+    }
+    // ── BillingProvider interface ─────────────────────────────────────────────
+    async checkLimit(userId, hasPersonalKey) {
+        if (hasPersonalKey) {
+            return { ok: true, remaining: Infinity, topUpBalance: 0, totalAvailable: Infinity, useTopUp: false };
+        }
+        try {
+            const result = await this._post('/api/credits/check', { userEmail: userId, product: this.product });
+            return {
+                ok: result.ok,
+                remaining: result.remaining ?? 0,
+                topUpBalance: result.topUpBalance ?? 0,
+                totalAvailable: result.totalAvailable ?? 0,
+                useTopUp: !result.ok ? false : (result.remaining ?? 1) <= 0,
+                ...(!result.ok && result.reason ? { reason: result.reason === 'no_subscription' ? 'no_subscription' : 'limit_reached' } : {}),
+            };
+        }
+        catch {
+            // Network failure — fail open to avoid blocking AI calls due to Portal downtime.
+            return { ok: true, remaining: 1, topUpBalance: 0, totalAvailable: 1, useTopUp: false };
+        }
+    }
+    async getUsage(userId) {
+        // Portal does not expose per-product usage history via the credit API.
+        // Return a minimal placeholder — products that need full usage dashboards
+        // should call Portal's management API directly.
+        void userId;
+        return {
+            currentPeriod: _currentPeriod(),
+            periodEnd: _thirtyDaysFromNow(),
+            messagesUsed: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            byModel: {},
+            lastUpdated: new Date().toISOString(),
+        };
+    }
+    async getUsageStatus(userId, hasPersonalKey) {
+        const check = await this.checkLimit(userId, hasPersonalKey);
+        const usage = await this.getUsage(userId);
+        if (hasPersonalKey) {
+            return {
+                mode: 'byok',
+                usage,
+                limit: null,
+                remaining: null,
+                topUpBalance: 0,
+                totalAvailable: null,
+                percentUsed: null,
+                resetsAt: usage.periodEnd,
+                estimatedCostUSD: 0,
+            };
+        }
+        return {
+            mode: check.ok ? 'included' : 'free',
+            usage,
+            limit: null, // Portal doesn't expose the plan limit via this API
+            remaining: check.remaining === Infinity ? null : check.remaining,
+            topUpBalance: check.topUpBalance,
+            totalAvailable: check.totalAvailable === Infinity ? null : check.totalAvailable,
+            percentUsed: null,
+            resetsAt: usage.periodEnd,
+            estimatedCostUSD: 0,
+            isFreeUser: !check.ok,
+        };
+    }
+    async incrementUsage(userId, inputTokens, outputTokens, model, _useTopUp) {
+        try {
+            await this._post('/api/credits/consume', {
+                userEmail: userId,
+                product: this.product,
+                inputTokens,
+                outputTokens,
+                model,
+            });
+        }
+        catch {
+            // Fire-and-forget — a consume failure does not block the caller.
+            console.error('[SDK/billing] Portal consume failed — usage may be under-counted');
+        }
+    }
+    async batchIncrementUsage(userId, batch) {
+        try {
+            await this._post('/api/credits/batch', {
+                userEmail: userId,
+                product: this.product,
+                messageCount: batch.messageCount,
+                inputTokens: batch.inputTokens,
+                outputTokens: batch.outputTokens,
+                byModel: batch.byModel,
+            });
+        }
+        catch {
+            console.error('[SDK/billing] Portal batch flush failed — usage may be under-counted');
+        }
+    }
+    async getSubscription(_userId) {
+        // Subscription data is not exposed via the credit API.
+        return undefined;
+    }
+    async hasActiveSubscription(userId) {
+        const check = await this.checkLimit(userId, false);
+        return check.ok;
+    }
+    async getTopUpBalance(userId) {
+        const check = await this.checkLimit(userId, false);
+        return check.topUpBalance;
+    }
+    async canAccessPaidFeature(userId) {
+        return this.hasActiveSubscription(userId);
+    }
+}
+//# sourceMappingURL=portal-provider.js.map

package/dist/modules/billing/portal-provider.js.map

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

package/dist/modules/billing/types.d.ts

@@ -10,9 +10,10 @@
  * - **Top-up credits**: purchase additional credits beyond the monthly allowance
  * - **Provider abstraction**: local file storage (dev) or Firestore (production)
  *
- * The billing provider is selected automatically based on environment variables:
- * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
- * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ * The billing provider is selected automatically (priority order):
+ * 1. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 2. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 3. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
  *
  * @example Checking limits before an AI call
  * ```typescript

package/dist/modules/billing/types.d.ts.map

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

package/dist/modules/billing/types.js

@@ -10,9 +10,10 @@
  * - **Top-up credits**: purchase additional credits beyond the monthly allowance
  * - **Provider abstraction**: local file storage (dev) or Firestore (production)
  *
- * The billing provider is selected automatically based on environment variables:
- * - `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (production)
- * - Not set → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
+ * The billing provider is selected automatically (priority order):
+ * 1. `PORTAL_CREDIT_SECRET` set → `PortalBillingProvider` (cross-product unified credits)
+ * 2. `FIREBASE_SERVICE_ACCOUNT_KEY` set → `FirestoreBillingProvider` (per-product production)
+ * 3. Neither → `LocalBillingProvider` (dev, stores state in `.soulcraft/billing/`)
  *
  * @example Checking limits before an AI call
  * ```typescript

package/dist/modules/billing/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/modules/billing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/modules/hall/browser.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @module modules/hall/browser
+ * @description Browser-side Hall room client — joins a WebRTC room via a session token.
+ *
+ * `joinHallRoom` is the browser entry point for Hall real-time communication.
+ * It opens a WebSocket to the Hall signaling endpoint, negotiates a WebRTC peer
+ * connection via offer/answer/ICE, and returns a `HallRoomHandle` with typed events
+ * for tracks, transcripts, concept mentions, and room lifecycle.
+ *
+ * **Auth model:** The browser never sees the product's shared secret. The product
+ * backend mints a short-lived HMAC session token (via `sdk.hall.createSessionToken`)
+ * and passes it to the browser. The browser passes the token to `joinHallRoom` — that
+ * is the only browser credential.
+ *
+ * This module has no server-only dependencies and is safe to bundle for the browser.
+ * It does require `RTCPeerConnection` and `WebSocket` to be available (standard in
+ * all modern browsers; not available in Node.js without polyfills).
+ *
+ * @example
+ * ```typescript
+ * import { joinHallRoom } from '@soulcraft/sdk/client'
+ *
+ * // 1. Get token from product backend:
+ * const { token, hallUrl } = await fetch('/api/session/join').then(r => r.json())
+ *
+ * // 2. Get camera + mic:
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
+ *
+ * // 3. Join room:
+ * const room = await joinHallRoom({ token, hallUrl })
+ * room.addStream(stream)
+ *
+ * // 4. Handle events:
+ * room.on('trackAdded', ({ peerId, streams }) => {
+ *   document.getElementById(`video-${peerId}`).srcObject = streams[0]
+ * })
+ * room.on('transcript', ({ peerId, text, isFinal }) => {
+ *   if (isFinal) appendCaption(peerId, text)
+ * })
+ * room.on('conceptMention', ({ nodeId, confidence }) => pulseGraphNode(nodeId, confidence))
+ *
+ * // 5. On leave:
+ * room.close()
+ * ```
+ */
+import type { HallRoomHandle } from './types.js';
+/**
+ * Options for {@link joinHallRoom}.
+ */
+export interface JoinHallRoomOptions {
+    /**
+     * The session token issued by the product backend via `sdk.hall.createSessionToken()`.
+     * Embedded in the Hall WebSocket URL — never sent as a header or query param separately.
+     */
+    token: string;
+    /**
+     * The Hall server WebSocket base URL (e.g. `"wss://hall.soulcraft.com"`).
+     * Provided by the product backend alongside the token.
+     */
+    hallUrl: string;
+    /**
+     * Optional RTCConfiguration overrides (e.g. additional STUN/TURN servers).
+     * Hall's in-process TURN server is always included automatically via the signaling handshake.
+     * Pass additional servers here if you have a separate STUN/TURN setup.
+     */
+    iceServers?: RTCIceServer[];
+}
+/**
+ * Join a Hall room from the browser using a session token.
+ *
+ * Opens a WebSocket to `{hallUrl}/ws/session/{token}`, creates an `RTCPeerConnection`,
+ * performs the offer/answer/ICE exchange, and resolves once the peer connection reaches
+ * `connected` state. Returns a {@link HallRoomHandle} with typed events.
+ *
+ * @param options - Token, Hall URL, and optional ICE server overrides.
+ * @returns A connected `HallRoomHandle`.
+ * @throws {Error} If the signaling handshake fails or the connection times out.
+ *
+ * @example
+ * ```typescript
+ * const room = await joinHallRoom({ token, hallUrl: 'wss://hall.soulcraft.com' })
+ * room.addStream(localStream)
+ * room.on('trackAdded', ({ peerId, streams }) => renderVideo(peerId, streams[0]))
+ * room.on('transcript', ({ text, isFinal }) => { if (isFinal) showCaption(text) })
+ * ```
+ */
+export declare function joinHallRoom(options: JoinHallRoomOptions): Promise<HallRoomHandle>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/modules/hall/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,cAAc,EAQf,MAAM,YAAY,CAAA;AAoBnB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAA;CAC5B;AAgFD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgIxF"}

package/dist/modules/hall/browser.js

@@ -0,0 +1,265 @@
+/**
+ * @module modules/hall/browser
+ * @description Browser-side Hall room client — joins a WebRTC room via a session token.
+ *
+ * `joinHallRoom` is the browser entry point for Hall real-time communication.
+ * It opens a WebSocket to the Hall signaling endpoint, negotiates a WebRTC peer
+ * connection via offer/answer/ICE, and returns a `HallRoomHandle` with typed events
+ * for tracks, transcripts, concept mentions, and room lifecycle.
+ *
+ * **Auth model:** The browser never sees the product's shared secret. The product
+ * backend mints a short-lived HMAC session token (via `sdk.hall.createSessionToken`)
+ * and passes it to the browser. The browser passes the token to `joinHallRoom` — that
+ * is the only browser credential.
+ *
+ * This module has no server-only dependencies and is safe to bundle for the browser.
+ * It does require `RTCPeerConnection` and `WebSocket` to be available (standard in
+ * all modern browsers; not available in Node.js without polyfills).
+ *
+ * @example
+ * ```typescript
+ * import { joinHallRoom } from '@soulcraft/sdk/client'
+ *
+ * // 1. Get token from product backend:
+ * const { token, hallUrl } = await fetch('/api/session/join').then(r => r.json())
+ *
+ * // 2. Get camera + mic:
+ * const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
+ *
+ * // 3. Join room:
+ * const room = await joinHallRoom({ token, hallUrl })
+ * room.addStream(stream)
+ *
+ * // 4. Handle events:
+ * room.on('trackAdded', ({ peerId, streams }) => {
+ *   document.getElementById(`video-${peerId}`).srcObject = streams[0]
+ * })
+ * room.on('transcript', ({ peerId, text, isFinal }) => {
+ *   if (isFinal) appendCaption(peerId, text)
+ * })
+ * room.on('conceptMention', ({ nodeId, confidence }) => pulseGraphNode(nodeId, confidence))
+ *
+ * // 5. On leave:
+ * room.close()
+ * ```
+ */
+class HallRoomHandleImpl {
+    roomId;
+    peerId;
+    #listeners = {
+        transcript: new Set(),
+        conceptMention: new Set(),
+        relationProposed: new Set(),
+        speakerChanged: new Set(),
+        peerJoined: new Set(),
+        peerLeft: new Set(),
+        trackAdded: new Set(),
+        trackRemoved: new Set(),
+        closed: new Set(),
+        error: new Set(),
+    };
+    #pc;
+    #ws;
+    constructor(roomId, peerId, pc, ws) {
+        this.roomId = roomId;
+        this.peerId = peerId;
+        this.#pc = pc;
+        this.#ws = ws;
+    }
+    on(event, listener) {
+        ;
+        this.#listeners[event].add(listener);
+        return this;
+    }
+    off(event, listener) {
+        ;
+        this.#listeners[event].delete(listener);
+        return this;
+    }
+    addStream(stream) {
+        for (const track of stream.getTracks()) {
+            this.#pc.addTrack(track, stream);
+        }
+    }
+    close() {
+        this.#ws.close(1000, 'peer leaving');
+        this.#pc.close();
+    }
+    /** @internal */
+    _dispatch(event, payload) {
+        for (const listener of this.#listeners[event]) {
+            try {
+                listener(payload);
+            }
+            catch (e) {
+                console.error(`[Hall] uncaught error in room '${this.roomId}' ${event} listener:`, e);
+            }
+        }
+    }
+}
+// ─── joinHallRoom ─────────────────────────────────────────────────────────────
+/**
+ * Join a Hall room from the browser using a session token.
+ *
+ * Opens a WebSocket to `{hallUrl}/ws/session/{token}`, creates an `RTCPeerConnection`,
+ * performs the offer/answer/ICE exchange, and resolves once the peer connection reaches
+ * `connected` state. Returns a {@link HallRoomHandle} with typed events.
+ *
+ * @param options - Token, Hall URL, and optional ICE server overrides.
+ * @returns A connected `HallRoomHandle`.
+ * @throws {Error} If the signaling handshake fails or the connection times out.
+ *
+ * @example
+ * ```typescript
+ * const room = await joinHallRoom({ token, hallUrl: 'wss://hall.soulcraft.com' })
+ * room.addStream(localStream)
+ * room.on('trackAdded', ({ peerId, streams }) => renderVideo(peerId, streams[0]))
+ * room.on('transcript', ({ text, isFinal }) => { if (isFinal) showCaption(text) })
+ * ```
+ */
+export async function joinHallRoom(options) {
+    const { token, hallUrl, iceServers = [] } = options;
+    const signalingUrl = `${hallUrl}/ws/session/${encodeURIComponent(token)}`;
+    // The Hall server sends TURN credentials in the first message after the WebSocket opens.
+    // We resolve ICE servers from that before creating the RTCPeerConnection.
+    const ws = new WebSocket(signalingUrl);
+    const handle = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error('Hall: signaling connection timed out after 30s'));
+        }, 30_000);
+        ws.onerror = () => {
+            clearTimeout(timeout);
+            reject(new Error('Hall: WebSocket error during signaling'));
+        };
+        ws.onopen = async () => {
+            // Create the peer connection. Hall's TURN server handles NAT traversal —
+            // the signaling 'answer' message from Hall includes ICE candidates.
+            const pc = new RTCPeerConnection({
+                iceServers: [
+                    // Hall's in-process TURN is always available.
+                    // The session token encodes the TURN credentials — Hall provides them via the ws.
+                    { urls: `${hallUrl.replace('wss://', 'turn:').replace('ws://', 'turn:')}:3478` },
+                    ...iceServers,
+                ],
+            });
+            // Send ICE candidates to Hall as they are gathered.
+            pc.onicecandidate = (ev) => {
+                if (ev.candidate) {
+                    ws.send(JSON.stringify({ type: 'ice', candidate: JSON.stringify(ev.candidate) }));
+                }
+            };
+            // Create and send SDP offer.
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+            ws.send(JSON.stringify({ type: 'offer', sdp: offer.sdp }));
+            ws.onmessage = async (ev) => {
+                let msg;
+                try {
+                    msg = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === 'answer') {
+                    await pc.setRemoteDescription({ type: 'answer', sdp: msg.sdp });
+                    return;
+                }
+                if (msg.type === 'ice') {
+                    try {
+                        await pc.addIceCandidate(JSON.parse(msg.candidate));
+                    }
+                    catch {
+                        // Stale ICE candidates are harmless to ignore.
+                    }
+                    return;
+                }
+                if (msg.type === 'error') {
+                    clearTimeout(timeout);
+                    ws.close();
+                    pc.close();
+                    reject(new Error(`Hall signaling error: ${msg.message}`));
+                    return;
+                }
+                // The peer connection is considered "ready" once we have a remote description.
+                // Resolve the handle at this point so event listeners can be attached.
+                // We defer the roomId/peerId extraction to after the connection resolves.
+                // Hall sends peerJoined as the first room event after ICE completes.
+                if (!roomHandleRef)
+                    return;
+                routeSignalingEvent(roomHandleRef, msg);
+            };
+            // Resolve once connected. Track events before connection is established are
+            // buffered by the browser's RTCPeerConnection — addTrack after setRemoteDescription.
+            pc.onconnectionstatechange = () => {
+                if (pc.connectionState === 'connected' && !roomHandleRef) {
+                    // roomId and peerId are decoded from the token by Hall and sent in peerJoined.
+                    // We use placeholders here; they are filled in by the first peerJoined event.
+                    const h = new HallRoomHandleImpl('', '', pc, ws);
+                    roomHandleRef = h;
+                    clearTimeout(timeout);
+                    resolve(h);
+                }
+                if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
+                    if (!roomHandleRef) {
+                        clearTimeout(timeout);
+                        reject(new Error(`Hall: WebRTC connection ${pc.connectionState}`));
+                    }
+                }
+            };
+            // Wire track events.
+            pc.ontrack = (ev) => {
+                if (!roomHandleRef)
+                    return;
+                roomHandleRef._dispatch('trackAdded', {
+                    peerId: 'remote', // refined by peerJoined
+                    track: ev.track,
+                    streams: ev.streams,
+                });
+                ev.track.onended = () => {
+                    roomHandleRef?._dispatch('trackRemoved', { peerId: 'remote', track: ev.track });
+                };
+            };
+        };
+        let roomHandleRef = null;
+        ws.onclose = (ev) => {
+            if (roomHandleRef) {
+                if (ev.code !== 1000) {
+                    roomHandleRef._dispatch('error', { message: `Hall WebSocket closed: ${ev.reason || ev.code}` });
+                }
+                roomHandleRef._dispatch('closed', { roomId: roomHandleRef.roomId });
+            }
+        };
+    });
+    return handle;
+}
+// ─── Signaling event router ───────────────────────────────────────────────────
+function routeSignalingEvent(handle, msg) {
+    switch (msg.type) {
+        case 'transcript':
+            handle._dispatch('transcript', msg);
+            break;
+        case 'conceptMention':
+            handle._dispatch('conceptMention', msg);
+            break;
+        case 'relationProposed':
+            handle._dispatch('relationProposed', msg);
+            break;
+        case 'speaker_changed':
+            handle._dispatch('speakerChanged', { roomId: msg.roomId, peerId: msg.speakerId });
+            break;
+        case 'peerJoined':
+            handle._dispatch('peerJoined', msg);
+            break;
+        case 'peerLeft':
+            handle._dispatch('peerLeft', msg);
+            break;
+        case 'roomClosed':
+            handle._dispatch('closed', { roomId: msg.roomId });
+            break;
+        case 'error':
+            handle._dispatch('error', { message: msg.message });
+            break;
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/modules/hall/browser.js.map

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