@soulcraft/sdk 2.0.0 → 2.0.2

package/dist/modules/hall/media.js

@@ -0,0 +1,182 @@
+/**
+ * @module modules/hall/media
+ * @description HTTP client for the Hall media pipeline — upload, transcode, retrieve, and delete media.
+ *
+ * Hall provides a media pipeline for processing audio, video, and image files. This module
+ * wraps the HTTP endpoints (not WebSocket) with a typed client. Async notifications for
+ * transcoding completion arrive via the product WebSocket (`mediaReady` / `mediaError` events
+ * on the `HallRoom` handle).
+ *
+ * **Auth model:** All media HTTP requests use `Authorization: Hall <productName>:<secret>`.
+ * This client is server-only — never expose the product secret to browsers. Browser clients
+ * access processed media via the public `GET /media/{mediaId}` endpoint (no auth required
+ * for read access).
+ *
+ * @example
+ * ```typescript
+ * import { createHallMediaClient } from '@soulcraft/sdk/server'
+ *
+ * const media = createHallMediaClient({
+ *   baseUrl: 'https://hall.soulcraft.com',
+ *   productName: 'workshop',
+ *   secret: process.env.HALL_WORKSHOP_SECRET!,
+ * })
+ *
+ * // Upload a file with transcoding
+ * const result = await media.upload(file, { transcode: 'video/mp4' })
+ * console.log(result.mediaId) // listen for 'mediaReady' event on the room
+ *
+ * // Get media info
+ * const info = await media.getInfo(result.mediaId)
+ *
+ * // Delete media
+ * await media.delete(result.mediaId)
+ * ```
+ */
+// ─── HallMediaClient ─────────────────────────────────────────────────────────
+/**
+ * Server-side HTTP client for the Hall media pipeline.
+ *
+ * Handles upload, info retrieval, thumbnail access, and deletion.
+ * All requests are authenticated with the product shared secret.
+ *
+ * Async transcoding notifications arrive via the product WebSocket, not this client.
+ * Listen for `mediaReady` / `mediaError` events on the `HallRoom` handle.
+ */
+export class HallMediaClient {
+    #baseUrl;
+    #productName;
+    #secret;
+    /**
+     * @param options - Hall server URL, product name, and shared secret.
+     */
+    constructor(options) {
+        this.#baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.#productName = options.productName;
+        this.#secret = options.secret;
+    }
+    /**
+     * Upload a media file to Hall for processing.
+     *
+     * @param file - The file to upload. Can be a `Blob`, `File`, or `Buffer`.
+     * @param options - Optional transcode target.
+     * @returns The assigned media ID. Listen for `mediaReady` on the room for completion.
+     *
+     * @example
+     * ```typescript
+     * const file = new Blob([audioBuffer], { type: 'audio/wav' })
+     * const { mediaId } = await media.upload(file, { transcode: 'audio/mp3' })
+     * ```
+     */
+    async upload(file, options = {}) {
+        const form = new FormData();
+        form.append('file', file);
+        if (options.transcode) {
+            form.append('transcode', options.transcode);
+        }
+        const response = await fetch(`${this.#baseUrl}/media/upload`, {
+            method: 'POST',
+            headers: { Authorization: this.#authHeader() },
+            body: form,
+            signal: AbortSignal.timeout(120_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Hall media upload failed (${response.status}): ${await response.text()}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get metadata for a processed media file.
+     *
+     * @param mediaId - The media identifier from the upload result.
+     * @returns Media metadata including MIME type, size, duration, dimensions, and status.
+     */
+    async getInfo(mediaId) {
+        const response = await fetch(`${this.#baseUrl}/media/${encodeURIComponent(mediaId)}/info`, {
+            headers: { Authorization: this.#authHeader() },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Hall media info failed (${response.status}): ${await response.text()}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get the URL for streaming a media file.
+     * Supports HTTP range requests (206 Partial Content).
+     *
+     * @param mediaId - The media identifier.
+     * @returns The full URL to the media file.
+     */
+    getStreamUrl(mediaId) {
+        return `${this.#baseUrl}/media/${encodeURIComponent(mediaId)}`;
+    }
+    /**
+     * Get the URL for an auto-generated thumbnail (WebP).
+     *
+     * @param mediaId - The media identifier.
+     * @returns The full URL to the thumbnail image.
+     */
+    getThumbnailUrl(mediaId) {
+        return `${this.#baseUrl}/media/${encodeURIComponent(mediaId)}/thumbnail`;
+    }
+    /**
+     * Delete a media file. Only the uploading product can delete its own media.
+     *
+     * @param mediaId - The media identifier to delete.
+     */
+    async delete(mediaId) {
+        const response = await fetch(`${this.#baseUrl}/media/${encodeURIComponent(mediaId)}`, {
+            method: 'DELETE',
+            headers: { Authorization: this.#authHeader() },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`Hall media delete failed (${response.status}): ${await response.text()}`);
+        }
+    }
+    /**
+     * Build the WHEP endpoint URL for receive-only WebRTC viewing.
+     * Browser viewers POST an SDP offer to this URL with a session token.
+     *
+     * @param roomId - The room to view.
+     * @returns The WHEP endpoint URL.
+     */
+    getWhepUrl(roomId) {
+        return `${this.#baseUrl}/whep/${encodeURIComponent(roomId)}`;
+    }
+    /**
+     * Build the LL-HLS master playlist URL for scalable HLS viewing.
+     *
+     * @param roomId - The room to view.
+     * @returns The HLS playlist URL.
+     */
+    getHlsUrl(roomId) {
+        return `${this.#baseUrl}/hls/${encodeURIComponent(roomId)}/playlist.m3u8`;
+    }
+    #authHeader() {
+        return `Hall ${this.#productName}:${this.#secret}`;
+    }
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a server-side Hall media client for upload, transcode, and retrieval.
+ *
+ * @param options - Hall server URL, product name, and shared secret.
+ * @returns A `HallMediaClient` instance ready for use.
+ *
+ * @example
+ * ```typescript
+ * import { createHallMediaClient } from '@soulcraft/sdk/server'
+ *
+ * const media = createHallMediaClient({
+ *   baseUrl: 'https://hall.soulcraft.com',
+ *   productName: 'workshop',
+ *   secret: process.env.HALL_WORKSHOP_SECRET!,
+ * })
+ * ```
+ */
+export function createHallMediaClient(options) {
+    return new HallMediaClient(options);
+}
+//# sourceMappingURL=media.js.map

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

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

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

@@ -4,7 +4,8 @@
  *
  * `HallClient` maintains a single authenticated WebSocket connection from the product
  * backend to `hall.soulcraft.com`. All room management (createRoom, closeRoom, session
- * tokens, recording) goes through this connection.
+ * tokens, recording), pub/sub (topics, presence), broadcast control (promote/demote),
+ * and media pipeline notifications go through this connection.
  *
  * This module is **server-only** — it uses WebSocket, reconnect timers, and the
  * product shared secret, none of which should ever reach a browser bundle.
@@ -27,7 +28,7 @@
  * const { token } = await hall.createSessionToken('cohort-123', 'user-456')
  * ```
  */
-import type { HallConnectionOptions, HallModule, HallRoom, HallRoomEvents, RoomOptions } from './types.js';
+import type { HallConnectionOptions, HallModule, HallPubsubEvents, HallRoom, HallRoomEvents, HallPeerRole, RoomOptions, ScreenShareMode } from './types.js';
 type Listener<T> = (event: T) => void;
 /**
  * Concrete implementation of the {@link HallRoom} interface.
@@ -49,8 +50,9 @@ export declare class HallRoomImpl implements HallRoom {
  * Product-backend WebSocket client for the Hall real-time communication server.
  *
  * Create one instance per product process. Maintains a single authenticated control-plane
- * WebSocket to `hall.soulcraft.com`. All room management and event routing goes through
- * this single connection — do not create multiple instances per product.
+ * WebSocket to `hall.soulcraft.com`. All room management, pub/sub, broadcast control,
+ * and event routing goes through this single connection — do not create multiple instances
+ * per product.
  *
  * Auto-reconnects on unexpected disconnect (configurable via `reconnectDelayMs`).
  * In-flight promises are rejected on disconnect; register `onReconnect` to re-create rooms.
@@ -93,7 +95,7 @@ export declare class HallClient implements HallModule {
      * Create a new room on the Hall server.
      *
      * @param roomId - Unique room identifier (e.g. Brainy session entity ID).
-     * @param options - Room configuration: peer limit, transcription, recording, concept list.
+     * @param options - Room configuration: peer limit, transcription, recording, broadcast, concept list.
      * @returns The HallRoom handle — register event listeners on it immediately.
      * @throws {Error} If a room with the same ID already exists or the server returns an error.
      */
@@ -124,9 +126,10 @@ export declare class HallClient implements HallModule {
      * @param roomId - The room the browser peer will join.
      * @param peerId - The peer's unique identifier (e.g. authenticated user ID).
      * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @param role - Optional role hint: `"participant"`, `"viewer"`, or undefined (auto).
      * @returns `{ token, expiresAt }` — send `token` and `this.url` to the browser.
      */
-    createSessionToken(roomId: string, peerId: string, ttlSecs?: number): Promise<{
+    createSessionToken(roomId: string, peerId: string, ttlSecs?: number, role?: HallPeerRole): Promise<{
         token: string;
         expiresAt: number;
     }>;
@@ -144,6 +147,80 @@ export declare class HallClient implements HallModule {
      * @param roomId - The room to stop recording.
      */
     stopRecording(roomId: string): Promise<void>;
+    /**
+     * Subscribe to a pub/sub topic. Topics are product-scoped.
+     *
+     * @param topic - Topic name to subscribe to.
+     * @param metadata - Optional presence metadata visible to other subscribers.
+     */
+    subscribeTopic(topic: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Unsubscribe from a pub/sub topic.
+     *
+     * @param topic - Topic name to unsubscribe from.
+     */
+    unsubscribeTopic(topic: string): void;
+    /**
+     * Broadcast a message to all subscribers of a pub/sub topic.
+     *
+     * @param topic - Topic to broadcast to.
+     * @param payload - Arbitrary JSON payload delivered to all subscribers.
+     */
+    broadcastTopic(topic: string, payload: unknown): void;
+    /**
+     * Request a snapshot of all current subscribers on a topic.
+     *
+     * @param topic - Topic to query presence for.
+     */
+    getPresence(topic: string): void;
+    /**
+     * Register a listener for pub/sub events on the product connection.
+     *
+     * @param event - The pub/sub event name.
+     * @param listener - Callback invoked with the typed event payload.
+     */
+    onPubsub<K extends keyof HallPubsubEvents>(event: K, listener: (data: HallPubsubEvents[K]) => void): void;
+    /**
+     * Issue a browser pub/sub token.
+     *
+     * @param peerId - Peer ID the token is issued for.
+     * @param allowedTopics - Optional topic whitelist.
+     * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @returns `{ token, expiresAt }`.
+     */
+    createPubsubToken(peerId: string, allowedTopics?: string[], ttlSecs?: number): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Promote a viewer to a full bidirectional participant.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to promote.
+     */
+    promotePeer(roomId: string, peerId: string): void;
+    /**
+     * Demote a participant to a receive-only viewer.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to demote.
+     */
+    demotePeer(roomId: string, peerId: string): void;
+    /**
+     * Set the screen share simulcast strategy for a peer.
+     *
+     * @param roomId - Room containing the screensharing peer.
+     * @param peerId - Peer sharing their screen.
+     * @param mode - `"static"` (resolution) or `"motion"` (framerate).
+     */
+    setScreenShareMode(roomId: string, peerId: string, mode: ScreenShareMode): void;
+    /**
+     * Request historical chat messages for a room.
+     *
+     * @param roomId - Room to get chat history for.
+     * @param lastN - Maximum number of recent messages to return.
+     */
+    getChatHistory(roomId: string, lastN?: number): void;
 }
 /**
  * Create a server-mode Hall module that connects to the Hall standalone server.

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,QAAQ,EACR,cAAc,EAEd,WAAW,EAQZ,MAAM,YAAY,CAAA;AAInB,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;AAGrC;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,QAAQ;;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAad,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAK7C,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAKzF,GAAG,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAK1F,iFAAiF;IACjF,SAAS,CAAC,CAAC,SAAS,MAAM,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;CAStF;AAWD;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,UAAU;;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAwBpB;;OAEG;gBACS,OAAO,EAAE,qBAAqB;IAS1C;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAItD;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAMvC;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ5E;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ9B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD;;;;;;;;OAQG;IACH,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAShD;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6N7C;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAE3E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/modules/hall/server.ts"],"names":[],"mappings":"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"}

package/dist/modules/hall/server.js

@@ -4,7 +4,8 @@
  *
  * `HallClient` maintains a single authenticated WebSocket connection from the product
  * backend to `hall.soulcraft.com`. All room management (createRoom, closeRoom, session
- * tokens, recording) goes through this connection.
+ * tokens, recording), pub/sub (topics, presence), broadcast control (promote/demote),
+ * and media pipeline notifications go through this connection.
  *
  * This module is **server-only** — it uses WebSocket, reconnect timers, and the
  * product shared secret, none of which should ever reach a browser bundle.
@@ -45,6 +46,13 @@ export class HallRoomImpl {
         peerJoined: new Set(),
         peerLeft: new Set(),
         recordingManifest: new Set(),
+        peerPromoted: new Set(),
+        peerDemoted: new Set(),
+        viewerCount: new Set(),
+        screenShareThumbnail: new Set(),
+        chatHistory: new Set(),
+        mediaReady: new Set(),
+        mediaError: new Set(),
         closed: new Set(),
     };
     constructor(roomId, sessionId) {
@@ -78,8 +86,9 @@ export class HallRoomImpl {
  * Product-backend WebSocket client for the Hall real-time communication server.
  *
  * Create one instance per product process. Maintains a single authenticated control-plane
- * WebSocket to `hall.soulcraft.com`. All room management and event routing goes through
- * this single connection — do not create multiple instances per product.
+ * WebSocket to `hall.soulcraft.com`. All room management, pub/sub, broadcast control,
+ * and event routing goes through this single connection — do not create multiple instances
+ * per product.
  *
  * Auto-reconnects on unexpected disconnect (configurable via `reconnectDelayMs`).
  * In-flight promises are rejected on disconnect; register `onReconnect` to re-create rooms.
@@ -98,8 +107,16 @@ export class HallClient {
     #pendingCloseRoom = new Map();
     #pendingSessionToken = new Map();
     #pendingRoomList = [];
+    #pendingPubsubToken = [];
     #disconnectListeners = new Set();
     #reconnectListeners = new Set();
+    #pubsubListeners = {
+        topicSubscribed: new Set(),
+        topicUnsubscribed: new Set(),
+        topicMessage: new Set(),
+        presenceUpdate: new Set(),
+        presenceSnapshot: new Set(),
+    };
     /**
      * @param options - Connection options: url, productName, secret, and optional reconnectDelayMs.
      */
@@ -158,7 +175,7 @@ export class HallClient {
      * Create a new room on the Hall server.
      *
      * @param roomId - Unique room identifier (e.g. Brainy session entity ID).
-     * @param options - Room configuration: peer limit, transcription, recording, concept list.
+     * @param options - Room configuration: peer limit, transcription, recording, broadcast, concept list.
      * @returns The HallRoom handle — register event listeners on it immediately.
      * @throws {Error} If a room with the same ID already exists or the server returns an error.
      */
@@ -202,6 +219,7 @@ export class HallClient {
     getRoom(roomId) {
         return this.#rooms.get(roomId);
     }
+    // ── Session tokens ─────────────────────────────────────────────────────────
     /**
      * Mint a short-lived HMAC session token for a browser peer.
      * Pass `{ token, hallUrl }` to the browser — **never** the product secret.
@@ -209,16 +227,18 @@ export class HallClient {
      * @param roomId - The room the browser peer will join.
      * @param peerId - The peer's unique identifier (e.g. authenticated user ID).
      * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @param role - Optional role hint: `"participant"`, `"viewer"`, or undefined (auto).
      * @returns `{ token, expiresAt }` — send `token` and `this.url` to the browser.
      */
-    createSessionToken(roomId, peerId, ttlSecs) {
+    createSessionToken(roomId, peerId, ttlSecs, role) {
         this.#requireConnected();
         const key = `${roomId}:${peerId}`;
         return new Promise((resolve, reject) => {
             this.#pendingSessionToken.set(key, { resolve, reject });
-            this.#send({ t: 'createSessionToken', d: { roomId, peerId, ttlSecs } });
+            this.#send({ t: 'createSessionToken', d: { roomId, peerId, ttlSecs, role } });
         });
     }
+    // ── Recording ──────────────────────────────────────────────────────────────
     /**
      * Start per-track MKV recording for an active room.
      * The room emits `recordingManifest` when `stopRecording` is called.
@@ -228,8 +248,6 @@ export class HallClient {
     startRecording(roomId) {
         this.#requireConnected();
         return new Promise((resolve, _reject) => {
-            // Hall sends `recordingStarted` as an informational ack — errors arrive as
-            // t:'error' messages and are routed to #rejectFirstPending.
             this.#send({ t: 'startRecording', d: { roomId } });
             resolve();
         });
@@ -247,6 +265,114 @@ export class HallClient {
             resolve();
         });
     }
+    // ── Pub/Sub ────────────────────────────────────────────────────────────────
+    /**
+     * Subscribe to a pub/sub topic. Topics are product-scoped.
+     *
+     * @param topic - Topic name to subscribe to.
+     * @param metadata - Optional presence metadata visible to other subscribers.
+     */
+    subscribeTopic(topic, metadata) {
+        this.#requireConnected();
+        this.#send({ t: 'subscribeTopic', d: { topic, metadata } });
+    }
+    /**
+     * Unsubscribe from a pub/sub topic.
+     *
+     * @param topic - Topic name to unsubscribe from.
+     */
+    unsubscribeTopic(topic) {
+        this.#requireConnected();
+        this.#send({ t: 'unsubscribeTopic', d: { topic } });
+    }
+    /**
+     * Broadcast a message to all subscribers of a pub/sub topic.
+     *
+     * @param topic - Topic to broadcast to.
+     * @param payload - Arbitrary JSON payload delivered to all subscribers.
+     */
+    broadcastTopic(topic, payload) {
+        this.#requireConnected();
+        this.#send({ t: 'broadcastTopic', d: { topic, payload } });
+    }
+    /**
+     * Request a snapshot of all current subscribers on a topic.
+     *
+     * @param topic - Topic to query presence for.
+     */
+    getPresence(topic) {
+        this.#requireConnected();
+        this.#send({ t: 'getPresence', d: { topic } });
+    }
+    /**
+     * Register a listener for pub/sub events on the product connection.
+     *
+     * @param event - The pub/sub event name.
+     * @param listener - Callback invoked with the typed event payload.
+     */
+    onPubsub(event, listener) {
+        ;
+        this.#pubsubListeners[event].add(listener);
+    }
+    /**
+     * Issue a browser pub/sub token.
+     *
+     * @param peerId - Peer ID the token is issued for.
+     * @param allowedTopics - Optional topic whitelist.
+     * @param ttlSecs - Token lifetime in seconds (default: 300).
+     * @returns `{ token, expiresAt }`.
+     */
+    createPubsubToken(peerId, allowedTopics, ttlSecs) {
+        this.#requireConnected();
+        return new Promise((resolve, reject) => {
+            this.#pendingPubsubToken.push({ resolve, reject });
+            this.#send({ t: 'createPubsubToken', d: { peerId, allowedTopics, ttlSecs } });
+        });
+    }
+    // ── Broadcast control ──────────────────────────────────────────────────────
+    /**
+     * Promote a viewer to a full bidirectional participant.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to promote.
+     */
+    promotePeer(roomId, peerId) {
+        this.#requireConnected();
+        this.#send({ t: 'promotePeer', d: { roomId, peerId } });
+    }
+    /**
+     * Demote a participant to a receive-only viewer.
+     *
+     * @param roomId - Room containing the peer.
+     * @param peerId - Peer ID to demote.
+     */
+    demotePeer(roomId, peerId) {
+        this.#requireConnected();
+        this.#send({ t: 'demotePeer', d: { roomId, peerId } });
+    }
+    // ── Screen sharing ─────────────────────────────────────────────────────────
+    /**
+     * Set the screen share simulcast strategy for a peer.
+     *
+     * @param roomId - Room containing the screensharing peer.
+     * @param peerId - Peer sharing their screen.
+     * @param mode - `"static"` (resolution) or `"motion"` (framerate).
+     */
+    setScreenShareMode(roomId, peerId, mode) {
+        this.#requireConnected();
+        this.#send({ t: 'setScreenShareMode', d: { roomId, peerId, mode } });
+    }
+    // ── Chat history ───────────────────────────────────────────────────────────
+    /**
+     * Request historical chat messages for a room.
+     *
+     * @param roomId - Room to get chat history for.
+     * @param lastN - Maximum number of recent messages to return.
+     */
+    getChatHistory(roomId, lastN) {
+        this.#requireConnected();
+        this.#send({ t: 'getChatHistory', d: { roomId, lastN } });
+    }
     // ── Private: socket management ─────────────────────────────────────────────
     #openSocket() {
         const ws = new WebSocket(`${this.url}/ws/product`);
@@ -313,6 +439,17 @@ export class HallClient {
             throw new Error('Hall: not authenticated — await hall.connect() first');
         }
     }
+    // ── Private: pub/sub event dispatch ────────────────────────────────────────
+    #dispatchPubsub(event, payload) {
+        for (const listener of this.#pubsubListeners[event]) {
+            try {
+                listener(payload);
+            }
+            catch (e) {
+                console.error(`[Hall] uncaught error in pubsub '${event}' listener:`, e);
+            }
+        }
+    }
     // ── Private: message routing ───────────────────────────────────────────────
     #handleMessage(msg) {
         switch (msg.t) {
@@ -367,6 +504,7 @@ export class HallClient {
                 console.warn(`[Hall] server error ${msg.d.code}: ${msg.d.message}`);
                 this.#rejectFirstPending(new Error(msg.d.message));
                 break;
+            // ── Room events ──────────────────────────────────────────────────────
             case 'transcript':
                 this.#dispatchRoomEvent(msg.d.roomId, 'transcript', msg.d);
                 break;
@@ -388,6 +526,54 @@ export class HallClient {
             case 'recordingManifest':
                 this.#dispatchRoomEvent(msg.d.roomId, 'recordingManifest', msg.d.manifest);
                 break;
+            case 'peerPromoted':
+                this.#dispatchRoomEvent(msg.d.roomId, 'peerPromoted', msg.d);
+                break;
+            case 'peerDemoted':
+                this.#dispatchRoomEvent(msg.d.roomId, 'peerDemoted', msg.d);
+                break;
+            case 'viewerCount':
+                this.#dispatchRoomEvent(msg.d.roomId, 'viewerCount', msg.d);
+                break;
+            case 'screenShareThumbnail':
+                this.#dispatchRoomEvent(msg.d.roomId, 'screenShareThumbnail', msg.d);
+                break;
+            case 'chatHistory':
+                this.#dispatchRoomEvent(msg.d.roomId, 'chatHistory', msg.d);
+                break;
+            case 'mediaReady':
+                // Media events are room-scoped — dispatch to all rooms (media is product-level).
+                // Products typically only have one active room per media upload, so this is fine.
+                for (const room of this.#rooms.values()) {
+                    room._dispatch('mediaReady', msg.d);
+                }
+                break;
+            case 'mediaError':
+                for (const room of this.#rooms.values()) {
+                    room._dispatch('mediaError', msg.d);
+                }
+                break;
+            // ── Pub/Sub events ───────────────────────────────────────────────────
+            case 'topicSubscribed':
+                this.#dispatchPubsub('topicSubscribed', msg.d);
+                break;
+            case 'topicUnsubscribed':
+                this.#dispatchPubsub('topicUnsubscribed', msg.d);
+                break;
+            case 'topicMessage':
+                this.#dispatchPubsub('topicMessage', msg.d);
+                break;
+            case 'presenceUpdate':
+                this.#dispatchPubsub('presenceUpdate', msg.d);
+                break;
+            case 'presenceSnapshot':
+                this.#dispatchPubsub('presenceSnapshot', msg.d);
+                break;
+            case 'pubsubToken': {
+                const pending = this.#pendingPubsubToken.shift();
+                pending?.resolve({ token: msg.d.token, expiresAt: msg.d.expiresAt });
+                break;
+            }
             case 'recordingStarted':
             case 'dataSent':
                 // Informational acks — no pending promise to resolve.
@@ -412,6 +598,8 @@ export class HallClient {
         this.#pendingSessionToken.clear();
         this.#pendingRoomList.forEach((p) => p.reject(err));
         this.#pendingRoomList.length = 0;
+        this.#pendingPubsubToken.forEach((p) => p.reject(err));
+        this.#pendingPubsubToken.length = 0;
     }
     #rejectFirstPending(err) {
         for (const [key, p] of this.#pendingCreateRoom) {
@@ -429,7 +617,16 @@ export class HallClient {
             p.reject(err);
             return;
         }
-        this.#pendingRoomList.shift()?.reject(err);
+        const listPending = this.#pendingRoomList.shift();
+        if (listPending) {
+            listPending.reject(err);
+            return;
+        }
+        const pubsubPending = this.#pendingPubsubToken.shift();
+        if (pubsubPending) {
+            pubsubPending.reject(err);
+            return;
+        }
     }
 }
 // ─── Factory ──────────────────────────────────────────────────────────────────