@antcdn/live-signaling 0.1.0 → 0.1.1

package/dist/client.d.ts

@@ -38,6 +38,17 @@ export interface LiveRoomEvents {
         connected: boolean;
         reconnecting: boolean;
     };
+    /**
+     * A cued question arrived and is being held until the video reports its cue.
+     *
+     * Emitted so that waiting is visible. A question held forever because no cue ever
+     * came looks exactly like a question that was never asked, and that is the single
+     * hardest state to diagnose from outside.
+     */
+    pending: {
+        question: LiveQuestion;
+        cueTimeoutMs: number;
+    };
 }
 type Listener<K extends keyof LiveRoomEvents> = (payload: LiveRoomEvents[K]) => void;
 export interface LiveRoomOptions {
@@ -54,6 +65,18 @@ export interface LiveRoomOptions {
      * reintroduces exactly the early-reveal problem cues exist to prevent.
      */
     revealImmediately?: boolean;
+    /**
+     * How long to wait for a question's in-band cue before revealing it anyway, in
+     * milliseconds. Zero waits forever.
+     *
+     * The cue is what makes a question appear at the moment it was asked, so waiting is
+     * the whole point. But some players never surface in-band metadata at all, and there
+     * the choice is between a question that arrives slightly early and one that never
+     * arrives. Late and visible beats perfectly timed and invisible.
+     *
+     * Defaults to 30 seconds, which is beyond any plausible live delay.
+     */
+    cueTimeoutMs?: number;
     /** Injectable for tests and non-browser runtimes. */
     webSocketFactory?: (url: string) => WebSocket;
 }
@@ -68,6 +91,8 @@ export declare class LiveRoom {
     private earlyCues;
     /** Revealed already, so a duplicate cue cannot fire the event twice. */
     private revealed;
+    /** Fallback reveals for held questions, cancelled when the real cue arrives. */
+    private cueTimers;
     private closedByCaller;
     private reconnectAttempts;
     private reconnectTimer;

package/dist/client.js

@@ -1,6 +1,8 @@
 import { PROTOCOL_VERSION, } from './protocol.js';
 import { resolveSessionId } from './session.js';
 const RECONNECT_BASE_MS = 500;
+/** See LiveRoomOptions.cueTimeoutMs. */
+const DEFAULT_CUE_TIMEOUT_MS = 30_000;
 const RECONNECT_MAX_MS = 15000;
 export class LiveRoom {
     options;
@@ -13,6 +15,8 @@ export class LiveRoom {
     earlyCues = new Set();
     /** Revealed already, so a duplicate cue cannot fire the event twice. */
     revealed = new Set();
+    /** Fallback reveals for held questions, cancelled when the real cue arrives. */
+    cueTimers = new Map();
     closedByCaller = false;
     reconnectAttempts = 0;
     reconnectTimer = null;
@@ -76,6 +80,9 @@ export class LiveRoom {
     }
     close() {
         this.closedByCaller = true;
+        for (const timer of this.cueTimers.values())
+            clearTimeout(timer);
+        this.cueTimers.clear();
         if (this.reconnectTimer)
             clearTimeout(this.reconnectTimer);
         this.reconnectTimer = null;
@@ -205,9 +212,32 @@ export class LiveRoom {
             return;
         }
         this.pending.set(question.id, question);
+        const timeout = this.options.cueTimeoutMs ?? DEFAULT_CUE_TIMEOUT_MS;
+        this.emit('pending', { question, cueTimeoutMs: timeout });
+        if (timeout > 0) {
+            const timer = setTimeout(() => {
+                this.cueTimers.delete(question.id);
+                // Still held, so no cue ever arrived for it.
+                if (!this.pending.has(question.id))
+                    return;
+                this.pending.delete(question.id);
+                this.emit('error', {
+                    code: 'cue_timeout',
+                    message: `No in-band cue arrived for ${question.id} within ${timeout}ms, so it is ` +
+                        'being shown now. It will be slightly ahead of the moment it was asked.',
+                });
+                this.reveal(question);
+            }, timeout);
+            this.cueTimers.set(question.id, timer);
+        }
     }
     reveal(question) {
         this.revealed.add(question.id);
+        const timer = this.cueTimers.get(question.id);
+        if (timer) {
+            clearTimeout(timer);
+            this.cueTimers.delete(question.id);
+        }
         this.emit('question', question);
     }
     emit(event, payload) {

package/dist/protocol.d.ts

@@ -42,7 +42,7 @@ export interface LiveTally {
      */
     textCount?: number;
 }
-export type ServerErrorCode = 'bad_message' | 'no_active_question' | 'already_voted' | 'unknown_option' | 'text_not_allowed' | 'text_too_long';
+export type ServerErrorCode = 'bad_message' | 'no_active_question' | 'already_voted' | 'unknown_option' | 'text_not_allowed' | 'text_too_long' | 'cue_timeout';
 export interface WelcomeMessage {
     v: number;
     type: 'welcome';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antcdn/live-signaling",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactivity for AntCDN live streams and recordings: viewer count, questions, and voting, independent of any video player.",
   "type": "module",
   "main": "./dist/index.js",