@antcdn/live-signaling 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AntCDN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @antcdn/live-signaling
+
+Interactivity for AntCDN live streams and their recordings: viewer presence, host-driven questions, and voting. It is independent of any video player.
+
+Works with player-ant, hls.js, Shaka Player, a native app shell, or a page with no video at all. It opens a WebSocket and emits events; it never touches a video element.
+
+## Install
+
+```
+pnpm add @antcdn/live-signaling
+```
+
+## Live
+
+```ts
+import { connectLiveRoom } from '@antcdn/live-signaling';
+
+const room = connectLiveRoom({
+  streamId: 'ls_2VQDR4DO8RTVADPQ21X95U',
+  // Optional. Prefer the id from your playback session; otherwise one is
+  // generated and persisted in localStorage.
+  sessionId: playbackSession?.sessionId,
+});
+
+room.on('count', ({ viewerCount }) => renderViewerCount(viewerCount));
+room.on('question', (q) => showQuestion(q));      // fires at reveal time
+room.on('tally', (t) => renderResults(t.counts));
+room.on('closed', (t) => renderFinal(t.counts));
+room.on('error', ({ code }) => { if (code === 'already_voted') markAnswered(); });
+
+// When the viewer answers
+room.vote(questionId, optionIndex);
+```
+
+### Reveal timing, the part that matters
+
+A question asked *inside the video* must appear when the viewer **hears it asked**, not when the socket delivered it. A viewer eight seconds behind the live edge would otherwise get a prompt about something that has not happened yet.
+
+So questions marked `cued` are **held** until you report the matching in-band cue:
+
+```ts
+// Shaka Player
+player.addEventListener('metadata', (e) => {
+  const questionId = readQuestionId(e);   // from the ID3/emsg payload
+  if (questionId) room.cue(questionId);
+});
+```
+
+Order does not matter. A cue arriving before its question is remembered, and the question reveals the moment it lands.
+
+Hosts and moderators are not on delay and need to see a question the instant it opens:
+
+```ts
+connectLiveRoom({ streamId, revealImmediately: true });
+```
+
+Never set that for ordinary viewers; it reintroduces exactly the early-reveal problem cues exist to prevent.
+
+## Recorded
+
+The same events, driven by playback position instead of a socket:
+
+```ts
+import { replayLiveRoom } from '@antcdn/live-signaling';
+
+const replay = replayLiveRoom({ questions });   // from the recording's question timeline
+
+replay.on('question', (q) => showQuestion(q));
+replay.on('tally', (t) => renderResults(t.counts));   // what the live audience answered
+
+video.addEventListener('timeupdate', () => replay.update(video.currentTime));
+```
+
+Seeking behaves the way a viewer expects: scrubbing backwards re-arms questions so a rewatch works, and scrubbing far forward does **not** fire a backlog. Only a question within `revealWindowSeconds` (default 30) of where you landed is shown.
+
+Because the event shape is identical, one set of handlers serves both live and recorded playback.
+
+## Identity and voting
+
+Votes are deduplicated by session id, one vote per session per question. A second vote returns `error` with code `already_voted`.
+
+Supplying your own `sessionId`, ideally the one AntCDN's secure-playback handshake issues, makes that meaningful. The generated fallback is deliberately weak: clearing site data earns another vote. That matches the bar the feature sets; do not build anything on it that needs a verified identity.
+
+## Protocol
+
+The SDK is a convenience over a plain JSON-over-WebSocket protocol. Implement it directly on any platform.
+
+```
+GET  wss://worker.antcdn.net/v1/{streamId}/live-room?sessionId={sessionId}
+GET  https://worker.antcdn.net/v1/{streamId}/live-room/count
+```
+
+**Server → client**
+
+| `type` | Payload |
+|---|---|
+| `welcome` | `streamId`, `viewerCount`, `activeQuestion?`, `hasVoted?`, `tally?` |
+| `count` | `viewerCount` |
+| `question` | `question: { id, prompt, options, cued? }` |
+| `tally` | `tally: { questionId, counts[], total }` |
+| `closed` | `tally`, final |
+| `error` | `code`, `message` |
+
+**Client → server**
+
+| `type` | Payload |
+|---|---|
+| `vote` | `questionId`, `optionIndex` |
+
+Every message carries `v`, the protocol version. The client warns on a mismatch rather than failing. Unknown fields are ignored, so additive server changes are safe.
+
+`welcome` is sent on every connect, including reconnects, and carries enough state to resume: the open question, whether this session already answered it, and the tally so far. Reconnection is automatic with jittered backoff.

package/dist/client.d.ts

@@ -0,0 +1,119 @@
+import { type LiveQuestion, type LiveTally, type ServerErrorCode } from './protocol.js';
+/**
+ * The live-room client.
+ *
+ * Player-agnostic by design: it opens a WebSocket and emits events. It never touches a
+ * video element, so it works with player-ant, hls.js, Shaka, a native app shell, or a
+ * page with no video at all (a host dashboard, say).
+ *
+ * Its one piece of real logic is **reveal timing**. A question tied to an in-band cue is
+ * held on arrival and released when the player reports the matching cue, so viewers at
+ * different buffer depths all see it at the same moment in the video. Everything else
+ * is transport.
+ */
+export interface LiveRoomEvents {
+    /** Connected, with whatever state the room already had. */
+    welcome: {
+        streamId: string;
+        viewerCount: number;
+        hasVoted: boolean;
+    };
+    /** Current viewer count. Coalesced server-side, so this is not chatty. */
+    count: {
+        viewerCount: number;
+    };
+    /** A question, at reveal time — held ones fire when their cue arrives, not on receipt. */
+    question: LiveQuestion;
+    /** Running results. */
+    tally: LiveTally;
+    /** The host closed the question; these are the final numbers. */
+    closed: LiveTally;
+    /** The server rejected something. `already_voted` is the common, benign one. */
+    error: {
+        code: ServerErrorCode;
+        message: string;
+    };
+    /** Transport state, so a UI can show a reconnecting indicator. */
+    status: {
+        connected: boolean;
+        reconnecting: boolean;
+    };
+}
+type Listener<K extends keyof LiveRoomEvents> = (payload: LiveRoomEvents[K]) => void;
+export interface LiveRoomOptions {
+    streamId: string;
+    /** Defaults to AntCDN's worker. Override for self-hosted or local development. */
+    baseUrl?: string;
+    /** Prefer the id from your playback session; one is generated and persisted if omitted. */
+    sessionId?: string;
+    /**
+     * Reveal cued questions immediately instead of waiting for `cue()`.
+     *
+     * For hosts and moderators, who are not watching on delay and need to see the
+     * question the moment it opens. Never set this for ordinary viewers — it
+     * reintroduces exactly the early-reveal problem cues exist to prevent.
+     */
+    revealImmediately?: boolean;
+    /** Injectable for tests and non-browser runtimes. */
+    webSocketFactory?: (url: string) => WebSocket;
+}
+export declare class LiveRoom {
+    private readonly options;
+    private readonly sessionId;
+    private socket;
+    private listeners;
+    /** Cued questions waiting for their cue, keyed by question id. */
+    private pending;
+    /** Cues that arrived before their question did — a race worth surviving. */
+    private earlyCues;
+    /** Revealed already, so a duplicate cue cannot fire the event twice. */
+    private revealed;
+    private closedByCaller;
+    private reconnectAttempts;
+    private reconnectTimer;
+    constructor(options: LiveRoomOptions);
+    on<K extends keyof LiveRoomEvents>(event: K, listener: Listener<K>): () => void;
+    connect(): void;
+    /**
+     * Report an in-band cue from the video.
+     *
+     * Call this from whatever surfaces timed metadata — Shaka's `metadata` event, hls.js
+     * fragment metadata, a native player's callback.
+     *
+     * Pass the question the cue carried, and it is revealed there and then: no round
+     * trip at the one moment that has to be instant, and it works even if this room's
+     * connection is down. AntCDN's own pipeline always puts the whole question in the
+     * media, for exactly that reason.
+     *
+     * Passing only an id is still supported, for encoders that carry no more than that.
+     * Then the question has to arrive over the socket before it can be shown, and the
+     * cue is remembered until it does.
+     */
+    cue(cue: LiveQuestion | string): void;
+    /**
+     * Answer a question by choosing an option, writing a reply, or both.
+     *
+     * Pass FREE_TEXT_ONLY as the option index to answer in writing without choosing.
+     */
+    vote(questionId: string, optionIndex: number, text?: string): void;
+    close(): void;
+    private url;
+    private open;
+    /**
+     * Exponential backoff with jitter.
+     *
+     * Jitter matters more than usual here: when a stream ends or a Worker redeploys,
+     * every viewer disconnects at once, and un-jittered backoff would have them all
+     * retry in lockstep.
+     */
+    private scheduleReconnect;
+    private send;
+    private receive;
+    /** Reveal now, or hold until the cue says the video has reached the question. */
+    private acceptQuestion;
+    private reveal;
+    private emit;
+}
+/** Convenience: construct and connect in one call. */
+export declare function connectLiveRoom(options: LiveRoomOptions): LiveRoom;
+export {};

package/dist/client.js

@@ -0,0 +1,230 @@
+import { PROTOCOL_VERSION, } from './protocol.js';
+import { resolveSessionId } from './session.js';
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 15000;
+export class LiveRoom {
+    options;
+    sessionId;
+    socket = null;
+    listeners = new Map();
+    /** Cued questions waiting for their cue, keyed by question id. */
+    pending = new Map();
+    /** Cues that arrived before their question did — a race worth surviving. */
+    earlyCues = new Set();
+    /** Revealed already, so a duplicate cue cannot fire the event twice. */
+    revealed = new Set();
+    closedByCaller = false;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    constructor(options) {
+        this.options = options;
+        this.sessionId = resolveSessionId(options.sessionId);
+    }
+    // ─── public surface ───────────────────────────────────────────────────────
+    on(event, listener) {
+        const set = this.listeners.get(event) ?? new Set();
+        set.add(listener);
+        this.listeners.set(event, set);
+        return () => set.delete(listener);
+    }
+    connect() {
+        this.closedByCaller = false;
+        this.open();
+    }
+    /**
+     * Report an in-band cue from the video.
+     *
+     * Call this from whatever surfaces timed metadata — Shaka's `metadata` event, hls.js
+     * fragment metadata, a native player's callback.
+     *
+     * Pass the question the cue carried, and it is revealed there and then: no round
+     * trip at the one moment that has to be instant, and it works even if this room's
+     * connection is down. AntCDN's own pipeline always puts the whole question in the
+     * media, for exactly that reason.
+     *
+     * Passing only an id is still supported, for encoders that carry no more than that.
+     * Then the question has to arrive over the socket before it can be shown, and the
+     * cue is remembered until it does.
+     */
+    cue(cue) {
+        if (typeof cue === 'string') {
+            if (this.revealed.has(cue))
+                return;
+            const question = this.pending.get(cue);
+            if (question) {
+                this.pending.delete(cue);
+                this.reveal(question);
+                return;
+            }
+            this.earlyCues.add(cue);
+            return;
+        }
+        if (this.revealed.has(cue.id))
+            return;
+        // Nothing to wait for — the cue brought the question with it.
+        this.pending.delete(cue.id);
+        this.earlyCues.delete(cue.id);
+        this.reveal(cue);
+    }
+    /**
+     * Answer a question by choosing an option, writing a reply, or both.
+     *
+     * Pass FREE_TEXT_ONLY as the option index to answer in writing without choosing.
+     */
+    vote(questionId, optionIndex, text) {
+        this.send({ v: PROTOCOL_VERSION, type: 'vote', questionId, optionIndex, ...(text ? { text } : {}) });
+    }
+    close() {
+        this.closedByCaller = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.socket?.close();
+        this.socket = null;
+    }
+    // ─── transport ────────────────────────────────────────────────────────────
+    url() {
+        const base = this.options.baseUrl ?? 'https://worker.antcdn.net';
+        const u = new URL(`${base.replace(/\/$/, '')}/v1/${this.options.streamId}/live-room`);
+        u.protocol = u.protocol === 'http:' ? 'ws:' : 'wss:';
+        u.searchParams.set('sessionId', this.sessionId);
+        return u.toString();
+    }
+    open() {
+        const factory = this.options.webSocketFactory ?? ((url) => new WebSocket(url));
+        let socket;
+        try {
+            socket = factory(this.url());
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = () => {
+            this.reconnectAttempts = 0;
+            this.emit('status', { connected: true, reconnecting: false });
+        };
+        socket.onmessage = (event) => this.receive(event.data);
+        socket.onclose = () => {
+            this.emit('status', { connected: false, reconnecting: !this.closedByCaller });
+            this.scheduleReconnect();
+        };
+        socket.onerror = () => {
+            // onclose always follows, and that is where reconnection is handled.
+        };
+    }
+    /**
+     * Exponential backoff with jitter.
+     *
+     * Jitter matters more than usual here: when a stream ends or a Worker redeploys,
+     * every viewer disconnects at once, and un-jittered backoff would have them all
+     * retry in lockstep.
+     */
+    scheduleReconnect() {
+        if (this.closedByCaller || this.reconnectTimer)
+            return;
+        const backoff = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempts, RECONNECT_MAX_MS);
+        const delay = backoff * (0.5 + Math.random() / 2);
+        this.reconnectAttempts += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (!this.closedByCaller)
+                this.open();
+        }, delay);
+    }
+    send(message) {
+        if (this.socket?.readyState !== 1 /* OPEN */)
+            return;
+        try {
+            this.socket.send(JSON.stringify(message));
+        }
+        catch {
+            // Dropped in flight; the reconnect path will re-establish state.
+        }
+    }
+    // ─── message handling ─────────────────────────────────────────────────────
+    receive(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.v === 'number' && msg.v !== PROTOCOL_VERSION) {
+            // Forward-compatible: unknown fields are ignored rather than fatal, but a
+            // mismatch is worth surfacing once rather than debugging blind.
+            console.warn(`[live-signaling] server protocol v${msg.v}, client v${PROTOCOL_VERSION} — update @antcdn/live-signaling`);
+        }
+        switch (msg.type) {
+            case 'welcome':
+                this.emit('welcome', {
+                    streamId: msg.streamId,
+                    viewerCount: msg.viewerCount,
+                    hasVoted: Boolean(msg.hasVoted),
+                });
+                this.emit('count', { viewerCount: msg.viewerCount });
+                // A question already open when we joined. Same reveal rules apply, so a
+                // late joiner behind the live edge still sees it at the right moment.
+                if (msg.activeQuestion)
+                    this.acceptQuestion(msg.activeQuestion);
+                if (msg.tally)
+                    this.emit('tally', msg.tally);
+                return;
+            case 'count':
+                this.emit('count', { viewerCount: msg.viewerCount });
+                return;
+            case 'question':
+                this.acceptQuestion(msg.question);
+                return;
+            case 'tally':
+                this.emit('tally', msg.tally);
+                return;
+            case 'closed':
+                this.pending.delete(msg.tally.questionId);
+                this.emit('closed', msg.tally);
+                return;
+            case 'error':
+                this.emit('error', { code: msg.code, message: msg.message });
+                return;
+        }
+    }
+    /** Reveal now, or hold until the cue says the video has reached the question. */
+    acceptQuestion(question) {
+        if (this.revealed.has(question.id))
+            return;
+        const waitForCue = question.cued && !this.options.revealImmediately;
+        if (!waitForCue) {
+            this.reveal(question);
+            return;
+        }
+        if (this.earlyCues.has(question.id)) {
+            this.earlyCues.delete(question.id);
+            this.reveal(question);
+            return;
+        }
+        this.pending.set(question.id, question);
+    }
+    reveal(question) {
+        this.revealed.add(question.id);
+        this.emit('question', question);
+    }
+    emit(event, payload) {
+        for (const listener of this.listeners.get(event) ?? []) {
+            try {
+                listener(payload);
+            }
+            catch (err) {
+                // One bad listener must not stop the others, or break the socket loop.
+                console.error(`[live-signaling] listener for "${event}" threw`, err);
+            }
+        }
+    }
+}
+/** Convenience: construct and connect in one call. */
+export function connectLiveRoom(options) {
+    const room = new LiveRoom(options);
+    room.connect();
+    return room;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @antcdn/live-signaling
+ *
+ * Interactivity for AntCDN live streams and their recordings: viewer presence,
+ * host-driven questions, and voting. It is independent of any video player.
+ *
+ * Two sources, one set of events:
+ *
+ *   connectLiveRoom()  live, over a WebSocket
+ *   replayLiveRoom()   recorded, from a timeline of offsets
+ *
+ * Integrate once, and a customer's own UI works for both.
+ */
+export { LiveRoom, connectLiveRoom } from './client.js';
+export type { LiveRoomOptions, LiveRoomEvents } from './client.js';
+export { LiveRoomReplay, replayLiveRoom } from './replay.js';
+export type { ReplayOptions, ReplayEvents } from './replay.js';
+export { resolveSessionId } from './session.js';
+export { PROTOCOL_VERSION, FREE_TEXT_ONLY, MAX_FREE_TEXT_LENGTH } from './protocol.js';
+export type { LiveQuestion, LiveTally, RecordedQuestion, ServerMessage, ClientMessage, ServerErrorCode, } from './protocol.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @antcdn/live-signaling
+ *
+ * Interactivity for AntCDN live streams and their recordings: viewer presence,
+ * host-driven questions, and voting. It is independent of any video player.
+ *
+ * Two sources, one set of events:
+ *
+ *   connectLiveRoom()  live, over a WebSocket
+ *   replayLiveRoom()   recorded, from a timeline of offsets
+ *
+ * Integrate once, and a customer's own UI works for both.
+ */
+export { LiveRoom, connectLiveRoom } from './client.js';
+export { LiveRoomReplay, replayLiveRoom } from './replay.js';
+export { resolveSessionId } from './session.js';
+export { PROTOCOL_VERSION, FREE_TEXT_ONLY, MAX_FREE_TEXT_LENGTH } from './protocol.js';

package/dist/protocol.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The live-room wire protocol.
+ *
+ * A deliberate copy of the Worker's `live_room_protocol.ts`, not an import: this package
+ * ships and versions independently of the Worker, and a customer implementing the raw
+ * protocol in another language has only this file as the contract.
+ *
+ * The two copies must agree. `PROTOCOL_VERSION` is what makes a disagreement visible
+ * rather than silent — the client warns when a server message carries a version it was
+ * not built against.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export interface LiveQuestion {
+    id: string;
+    prompt: string;
+    options: string[];
+    /**
+     * True when the question is tied to an in-band cue in the video.
+     *
+     * The client holds these until the player reports the matching cue, so the question
+     * appears when the streamer actually asked it rather than when the socket delivered
+     * it. Without this, a viewer eight seconds behind the live edge would see a question
+     * eight seconds before hearing it — a prompt about something that has not happened.
+     */
+    cued?: boolean;
+    /**
+     * When set, viewers may answer in writing as well as, or instead of, picking an
+     * option. Written answers are counted but never folded into the option counts —
+     * they are not comparable, and merging them would misreport both.
+     */
+    allowFreeText?: boolean;
+}
+export interface LiveTally {
+    questionId: string;
+    /** Index-aligned with the question's options. */
+    counts: number[];
+    total: number;
+    /**
+     * Written answers received, when the question allows them. Deliberately separate
+     * from `counts`: a written answer is not a choice between the options, so adding it
+     * to any of them — or to `total` — would misstate the result.
+     */
+    textCount?: number;
+}
+export type ServerErrorCode = 'bad_message' | 'no_active_question' | 'already_voted' | 'unknown_option' | 'text_not_allowed' | 'text_too_long';
+export interface WelcomeMessage {
+    v: number;
+    type: 'welcome';
+    streamId: string;
+    viewerCount: number;
+    activeQuestion?: LiveQuestion;
+    hasVoted?: boolean;
+    tally?: LiveTally;
+}
+export interface CountMessage {
+    v: number;
+    type: 'count';
+    viewerCount: number;
+}
+export interface QuestionMessage {
+    v: number;
+    type: 'question';
+    question: LiveQuestion;
+}
+export interface TallyMessage {
+    v: number;
+    type: 'tally';
+    tally: LiveTally;
+}
+export interface ClosedMessage {
+    v: number;
+    type: 'closed';
+    tally: LiveTally;
+}
+export interface ErrorMessage {
+    v: number;
+    type: 'error';
+    code: ServerErrorCode;
+    message: string;
+}
+export type ServerMessage = WelcomeMessage | CountMessage | QuestionMessage | TallyMessage | ClosedMessage | ErrorMessage;
+export interface VoteMessage {
+    v: number;
+    type: 'vote';
+    questionId: string;
+    /** The chosen option, or FREE_TEXT_ONLY when the viewer is answering in writing. */
+    optionIndex: number;
+    /** A written answer. Rejected when the question does not allow one. */
+    text?: string;
+}
+/**
+ * `optionIndex` for a written answer with no option chosen.
+ *
+ * A sentinel rather than an omitted field so that every vote has an option index and
+ * the server never has to distinguish "absent" from "index 0" — a distinction JSON and
+ * JavaScript both make easy to get wrong.
+ */
+export declare const FREE_TEXT_ONLY = -1;
+/**
+ * Longest written answer accepted, in characters.
+ *
+ * Enforced server-side. This is audience input arriving at broadcast rates, so the
+ * bound is on the server, where it protects storage, and not only in the UI.
+ */
+export declare const MAX_FREE_TEXT_LENGTH = 280;
+export type ClientMessage = VoteMessage;
+/** One question as recorded, for replaying interactivity over a VOD asset. */
+export interface RecordedQuestion {
+    id: string;
+    prompt: string;
+    options: string[];
+    /** Seconds from the start of the stream — the same instant the live cue fired. */
+    offsetSeconds: number;
+    /**
+     * Whether the question took written answers.
+     *
+     * Carried into the recording because a replay shows the question as it was asked:
+     * without this a viewer would be offered a narrower question than the live audience
+     * got, and the text they wanted to write would have nowhere to go.
+     */
+    allowFreeText?: boolean;
+    /** Final live tally, when the caller wants to show what the live audience answered. */
+    tally?: LiveTally;
+}

package/dist/protocol.js

@@ -0,0 +1,27 @@
+/**
+ * The live-room wire protocol.
+ *
+ * A deliberate copy of the Worker's `live_room_protocol.ts`, not an import: this package
+ * ships and versions independently of the Worker, and a customer implementing the raw
+ * protocol in another language has only this file as the contract.
+ *
+ * The two copies must agree. `PROTOCOL_VERSION` is what makes a disagreement visible
+ * rather than silent — the client warns when a server message carries a version it was
+ * not built against.
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * `optionIndex` for a written answer with no option chosen.
+ *
+ * A sentinel rather than an omitted field so that every vote has an option index and
+ * the server never has to distinguish "absent" from "index 0" — a distinction JSON and
+ * JavaScript both make easy to get wrong.
+ */
+export const FREE_TEXT_ONLY = -1;
+/**
+ * Longest written answer accepted, in characters.
+ *
+ * Enforced server-side. This is audience input arriving at broadcast rates, so the
+ * bound is on the server, where it protects storage, and not only in the UI.
+ */
+export const MAX_FREE_TEXT_LENGTH = 280;

package/dist/replay.d.ts

@@ -0,0 +1,79 @@
+import { type LiveQuestion, type LiveTally, type RecordedQuestion } from './protocol.js';
+/**
+ * Interactivity over a recorded stream.
+ *
+ * A live stream that was recorded keeps its questions as a timeline of offsets from the
+ * start of the broadcast. Replaying them against `currentTime` gives a VOD viewer the
+ * same experience the live audience had, in the same order, at the same points — the
+ * mechanism YouTube cards and Twitch's VOD chat replay use.
+ *
+ * Deliberately the same event names as the live client, so an integrator writes one set
+ * of handlers and switches source rather than writing the feature twice.
+ *
+ * Seeking is handled properly: jumping backwards re-arms questions so they fire again,
+ * and jumping forwards past several does not fire a burst of stale prompts — only the
+ * most recent one is presented, because that is what a viewer scrubbing into the middle
+ * of a talk would expect to be looking at.
+ */
+export interface ReplayEvents {
+    question: LiveQuestion;
+    tally: LiveTally;
+}
+export interface ReplayOptions {
+    questions: RecordedQuestion[];
+    /**
+     * The stream this recording came from. Required to submit answers; omit it and the
+     * replay is read-only.
+     */
+    streamId?: string;
+    /** Defaults to AntCDN's worker. Override for self-hosted or local development. */
+    baseUrl?: string;
+    /** Prefer the id from your playback session; one is generated and persisted if omitted. */
+    sessionId?: string;
+    /** Injectable for tests and non-browser runtimes. */
+    fetchImpl?: typeof fetch;
+    /**
+     * How far past a question's offset it may still be revealed, in seconds.
+     *
+     * Without a bound, seeking to the end of a two-hour recording would reveal the
+     * question from minute three. With one, a scrub lands you in the state a viewer at
+     * that point would actually be in.
+     */
+    revealWindowSeconds?: number;
+}
+export declare class LiveRoomReplay {
+    private readonly questions;
+    private readonly revealWindow;
+    private listeners;
+    private revealed;
+    private lastTime;
+    private readonly options;
+    private readonly sessionId;
+    /** Answered in this session, so the UI need not wait on a round trip to know. */
+    private answered;
+    constructor(options: ReplayOptions);
+    /**
+     * Answer a question while watching the recording.
+     *
+     * Recorded against the recording, never against the broadcast. What the live
+     * audience said is a record of a moment that has passed; a recording collects
+     * answers for as long as anyone watches it, and merging the two would let the live
+     * result drift for years after the stream ended.
+     *
+     * Resolves true when the answer was stored, false when this viewer had already
+     * answered — which is not an error, and is what a retried submission should report.
+     */
+    answer(questionId: string, optionIndex: number, text?: string): Promise<boolean>;
+    /** Whether this viewer has answered the question during this session. */
+    hasAnswered(questionId: string): boolean;
+    on<K extends keyof ReplayEvents>(event: K, listener: (payload: ReplayEvents[K]) => void): () => void;
+    /**
+     * Drive from playback position. Call on `timeupdate` — a few times a second is
+     * plenty, since question offsets are seconds apart at best.
+     */
+    update(currentTimeSeconds: number): void;
+    /** Questions after this point become eligible again, so a rewatch behaves like a first watch. */
+    private rearmAfter;
+    private emit;
+}
+export declare function replayLiveRoom(options: ReplayOptions): LiveRoomReplay;

package/dist/replay.js

@@ -0,0 +1,122 @@
+import { FREE_TEXT_ONLY, MAX_FREE_TEXT_LENGTH } from './protocol.js';
+import { resolveSessionId } from './session.js';
+const DEFAULT_BASE_URL = 'https://worker.antcdn.net';
+const DEFAULT_REVEAL_WINDOW_SECONDS = 30;
+export class LiveRoomReplay {
+    questions;
+    revealWindow;
+    listeners = new Map();
+    revealed = new Set();
+    lastTime = 0;
+    options;
+    sessionId;
+    /** Answered in this session, so the UI need not wait on a round trip to know. */
+    answered = new Set();
+    constructor(options) {
+        // Sorted once so `update` is a scan from a known order rather than a search.
+        this.questions = [...options.questions].sort((a, b) => a.offsetSeconds - b.offsetSeconds);
+        this.revealWindow = options.revealWindowSeconds ?? DEFAULT_REVEAL_WINDOW_SECONDS;
+        this.options = options;
+        this.sessionId = resolveSessionId(options.sessionId);
+    }
+    /**
+     * Answer a question while watching the recording.
+     *
+     * Recorded against the recording, never against the broadcast. What the live
+     * audience said is a record of a moment that has passed; a recording collects
+     * answers for as long as anyone watches it, and merging the two would let the live
+     * result drift for years after the stream ended.
+     *
+     * Resolves true when the answer was stored, false when this viewer had already
+     * answered — which is not an error, and is what a retried submission should report.
+     */
+    async answer(questionId, optionIndex, text) {
+        if (!this.options.streamId) {
+            throw new Error('replayLiveRoom needs a streamId to submit answers');
+        }
+        if (text && text.length > MAX_FREE_TEXT_LENGTH) {
+            throw new Error(`Answers are limited to ${MAX_FREE_TEXT_LENGTH} characters.`);
+        }
+        if (optionIndex === FREE_TEXT_ONLY && !text?.trim()) {
+            throw new Error('An answer must pick an option, write a reply, or both.');
+        }
+        const base = (this.options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        const url = `${base}/v1/${encodeURIComponent(this.options.streamId)}/questions/${encodeURIComponent(questionId)}/replay-answer`;
+        const doFetch = this.options.fetchImpl ?? globalThis.fetch;
+        const res = await doFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                sessionId: this.sessionId,
+                optionIndex,
+                ...(text ? { text } : {}),
+            }),
+        });
+        if (!res.ok) {
+            throw new Error(`Could not record answer (HTTP ${res.status})`);
+        }
+        this.answered.add(questionId);
+        const body = (await res.json().catch(() => null));
+        return body?.recorded ?? true;
+    }
+    /** Whether this viewer has answered the question during this session. */
+    hasAnswered(questionId) {
+        return this.answered.has(questionId);
+    }
+    on(event, listener) {
+        const set = this.listeners.get(event) ?? new Set();
+        set.add(listener);
+        this.listeners.set(event, set);
+        return () => set.delete(listener);
+    }
+    /**
+     * Drive from playback position. Call on `timeupdate` — a few times a second is
+     * plenty, since question offsets are seconds apart at best.
+     */
+    update(currentTimeSeconds) {
+        const seekedBackwards = currentTimeSeconds < this.lastTime - 1;
+        if (seekedBackwards)
+            this.rearmAfter(currentTimeSeconds);
+        this.lastTime = currentTimeSeconds;
+        // The most recent question whose moment has passed and is still within the
+        // window. Only that one is revealed, so a forward seek does not dump a backlog.
+        let candidate = null;
+        for (const q of this.questions) {
+            if (q.offsetSeconds > currentTimeSeconds)
+                break;
+            if (currentTimeSeconds - q.offsetSeconds > this.revealWindow)
+                continue;
+            candidate = q;
+        }
+        if (!candidate || this.revealed.has(candidate.id))
+            return;
+        this.revealed.add(candidate.id);
+        this.emit('question', {
+            id: candidate.id,
+            prompt: candidate.prompt,
+            options: candidate.options,
+        });
+        if (candidate.tally)
+            this.emit('tally', candidate.tally);
+    }
+    /** Questions after this point become eligible again, so a rewatch behaves like a first watch. */
+    rearmAfter(seconds) {
+        for (const q of this.questions) {
+            if (q.offsetSeconds >= seconds)
+                this.revealed.delete(q.id);
+        }
+    }
+    emit(event, payload) {
+        for (const listener of this.listeners.get(event) ?? []) {
+            try {
+                listener(payload);
+            }
+            catch (err) {
+                console.error(`[live-signaling] replay listener for "${event}" threw`, err);
+            }
+        }
+    }
+}
+export function replayLiveRoom(options) {
+    return new LiveRoomReplay(options);
+}

package/dist/session.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Viewer identity.
+ *
+ * The room deduplicates votes by session id, so every connection needs one. There are
+ * two sources, in order of preference:
+ *
+ *   1. A session id the host application already has — most usefully the one AntCDN's
+ *      secure-playback handshake mints, which is server-issued and therefore not
+ *      trivially reset by the viewer.
+ *   2. One this module generates and persists, for public streams where no handshake
+ *      happens at all.
+ *
+ * The generated form is deliberately weak: clearing site data earns another vote. That
+ * matches the bar the feature actually sets — one vote per session, not per verified
+ * identity — and pretending otherwise would invite someone to rely on it.
+ */
+/**
+ * Returns a stable session id, persisting a generated one when possible.
+ *
+ * Every storage access is guarded: private-mode browsers and embedded webviews throw on
+ * localStorage rather than returning null, and an identity failure must not stop a
+ * viewer from watching.
+ */
+export declare function resolveSessionId(provided?: string): string;

package/dist/session.js

@@ -0,0 +1,57 @@
+/**
+ * Viewer identity.
+ *
+ * The room deduplicates votes by session id, so every connection needs one. There are
+ * two sources, in order of preference:
+ *
+ *   1. A session id the host application already has — most usefully the one AntCDN's
+ *      secure-playback handshake mints, which is server-issued and therefore not
+ *      trivially reset by the viewer.
+ *   2. One this module generates and persists, for public streams where no handshake
+ *      happens at all.
+ *
+ * The generated form is deliberately weak: clearing site data earns another vote. That
+ * matches the bar the feature actually sets — one vote per session, not per verified
+ * identity — and pretending otherwise would invite someone to rely on it.
+ */
+const STORAGE_KEY = 'antcdn.live-signaling.session';
+/** Crypto-random where available, falling back so this never throws in odd runtimes. */
+function randomId() {
+    const g = globalThis;
+    if (g.crypto?.randomUUID)
+        return g.crypto.randomUUID();
+    if (g.crypto?.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        g.crypto.getRandomValues(bytes);
+        return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+}
+/**
+ * Returns a stable session id, persisting a generated one when possible.
+ *
+ * Every storage access is guarded: private-mode browsers and embedded webviews throw on
+ * localStorage rather than returning null, and an identity failure must not stop a
+ * viewer from watching.
+ */
+export function resolveSessionId(provided) {
+    if (provided)
+        return provided;
+    try {
+        const existing = globalThis.localStorage?.getItem(STORAGE_KEY);
+        if (existing)
+            return existing;
+    }
+    catch {
+        // Storage unavailable — fall through to an ephemeral id.
+    }
+    const generated = randomId();
+    try {
+        globalThis.localStorage?.setItem(STORAGE_KEY, generated);
+    }
+    catch {
+        // Not persistable. The id still works for this page's lifetime, which means
+        // the viewer can vote once here and once again after a reload.
+    }
+    return generated;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@antcdn/live-signaling",
+  "version": "0.1.0",
+  "description": "Interactivity for AntCDN live streams and recordings: viewer count, questions, and voting, independent of any video player.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "tsc": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run tsc && npm run test && npm run build"
+  },
+  "keywords": [
+    "antcdn",
+    "live",
+    "streaming",
+    "interactive",
+    "polls",
+    "websocket"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavidQuartz/antcdn.git",
+    "directory": "typescript_root/live-signaling-sdk"
+  },
+  "homepage": "https://antcdn.net/interactive-live",
+  "bugs": {
+    "url": "https://github.com/DavidQuartz/antcdn/issues"
+  }
+}