@rapidmx/meet-plugin 0.15.0 → 0.16.0

package/dist/apps/shared/collab/CollabSession.d.ts

@@ -0,0 +1,208 @@
+/**
+ * The call's text chat and shared whiteboard, over the same signaling channel the mesh uses (`../webrtc/types.ts`'s
+ * `chat`, `whiteboard`, `collab-sync-request` and `collab-sync` messages). Like everything else in a call they live
+ * only as long as the call does - there is no server-side copy; each participant's tab holds them.
+ *
+ * ## Chat
+ *
+ * `sendChat()` broadcasts one `chat` message and shows it locally at once (the server never echoes a sender's own
+ * messages). A received one is shown under the name its sender announced in their `hello`. At most
+ * `MAX_CHAT_HISTORY` messages are kept.
+ *
+ * ## Whiteboard
+ *
+ * Every drawing action becomes a `WhiteboardOp`, applied to this tab's own `WhiteboardModel` at once and broadcast. A
+ * stroke being drawn sends its points in batches every `POINT_FLUSH_MS` rather than one message per pointer move, so
+ * the others watch it being drawn without a message per pixel. `undo()` erases this participant's own most recent
+ * element still on the board.
+ *
+ * ## Pointers
+ *
+ * While a participant's pointer is over the board, `moveCursor()` tells everyone where it is and as which tool and
+ * color, at most every `CURSOR_INTERVAL_MS`; `hideCursor()` says it left. While they are drawing a stroke, no pointer
+ * messages are sent at all - everyone else moves their pointer along the stroke's own points instead. Pointers are
+ * never stored or caught up on; one not heard from for `CURSOR_IDLE_MS` is dropped, as is a participant's on `bye`.
+ *
+ * ## Who may draw
+ *
+ * `setDrawPolicy()` limits who may change the board (talking-stick mode: only whoever holds the stick). This
+ * participant's own drawing calls then do nothing unless it is allowed, and a received change from a participant who
+ * isn't is ignored - as cooperative as every other moderation signal in the call (see `../webrtc/types.ts`): each
+ * participant's own tab decides. A change in flight when the stick moves may land on some boards and not others.
+ * Pointers still show for everyone - pointing at something isn't drawing it.
+ *
+ * ## Catching up
+ *
+ * Someone joining a call already under way asks one participant for what they missed: on the first `hello` it hears
+ * within `SYNC_WINDOW_MS` of starting (an existing participant answering its own `hello`), it sends that participant a
+ * `collab-sync-request`; the answer is the chat history and the board as ops, split into `collab-sync` parts that
+ * each fit the server's message limit and paced `SYNC_PACE_MS` apart to stay inside its rate limit. When nothing has
+ * arrived from that participant for `SYNC_TIMEOUT_MS` (first part or next), the next one is asked - as it is when the
+ * whole answer was empty, which is what another newcomer who arrived moments earlier would send. Only the participant
+ * asked is listened to, and a participant answers the same requester at most once per `SYNC_ANSWER_COOLDOWN_MS`. A catch-up is that one participant's account of the call, which this tab cannot check - the chat history it
+ * carries names who said what, and the server stamps only the catch-up's own sender - so it is merged under the same
+ * validation as live messages, and live messages win wherever the two overlap.
+ */
+import { type CursorTool, type PenType, type Stamp, type StencilShape } from "./protocol.js";
+import { WhiteboardModel } from "./WhiteboardModel.js";
+import type { SignalingChannel } from "../webrtc/types.js";
+/** How often the points of a stroke being drawn are sent. */
+export declare const POINT_FLUSH_MS = 60;
+/** How long after starting a `hello` still counts as an existing participant answering ours - see this module's doc. */
+export declare const SYNC_WINDOW_MS = 15000;
+/** How long to wait for a catch-up to start arriving before asking someone else. */
+export declare const SYNC_TIMEOUT_MS = 5000;
+/** The gap between two parts of a catch-up this participant sends. */
+export declare const SYNC_PACE_MS = 250;
+/** Room left in each catch-up part for the message's own envelope. */
+export declare const SYNC_ENVELOPE_BYTES = 1024;
+/** The most stroke points one catch-up op carries, so one op always fits the server's smallest message limit. */
+export declare const SYNC_POINTS_PER_OP = 600;
+/** The least time between two pointer messages this participant sends. */
+export declare const CURSOR_INTERVAL_MS = 80;
+/** How long a participant's pointer stays on the board without news of it. */
+export declare const CURSOR_IDLE_MS = 30000;
+/** How long a participant waits before answering the same requester's catch-up request again. */
+export declare const SYNC_ANSWER_COOLDOWN_MS = 10000;
+/** One chat message as shown. */
+export interface ChatEntry {
+    /** Unique within the call: the sender's peer id and their own message id. */
+    key: string;
+    id: string;
+    peer: string;
+    name: string;
+    text: string;
+    sentAt: number;
+    self: boolean;
+}
+/** Another participant's pointer on the board. */
+export interface RemoteCursor {
+    peer: string;
+    name: string;
+    x: number;
+    y: number;
+    tool: CursorTool;
+    color: string;
+    stamp?: Stamp;
+    /** When it last moved, by this tab's clock. */
+    at: number;
+}
+/** A `chat` event with `history` set is a message from a catch-up - said before this participant arrived; one with
+ * `renamed` set is a message already shown, now under its sender's name. Neither is news. */
+export type CollabEvent = {
+    type: "chat";
+    entry: ChatEntry;
+    history?: boolean;
+    renamed?: boolean;
+} | {
+    type: "board";
+} | {
+    type: "cursors";
+};
+/** What `CollabSession` needs from the signaling channel - `SignalingClient` is one. */
+export interface CollabChannel extends SignalingChannel {
+    /** The server's per-message limit, in bytes - `SignalingClient.maxMessageBytes`. */
+    readonly maxMessageBytes?: number;
+}
+export interface CollabSessionOptions {
+    channel: CollabChannel;
+    /** The authenticated uid every message is sent `from`. */
+    selfUid: string;
+    /** This tab's peer id - the author of its chat messages and the prefix of its board elements' ids. */
+    peerId: string;
+    selfName: string;
+    now?: () => number;
+}
+export declare class CollabSession {
+    private readonly options;
+    readonly board: WhiteboardModel;
+    private chatEntries;
+    /** How many of `chatEntries`, from the front, came from a catch-up - the next part's history goes after them. */
+    private historyCount;
+    private readonly chatKeys;
+    private readonly names;
+    private readonly listeners;
+    private readonly ownIds;
+    private readonly outgoingPoints;
+    private readonly timers;
+    private flushTimer;
+    private syncTimer;
+    private syncTarget;
+    private readonly syncTried;
+    private readonly knownPeers;
+    private unsubscribe;
+    private startedAt;
+    private seq;
+    private stopped;
+    private readonly remoteCursors;
+    private cursorPending;
+    private cursorTimer;
+    private cursorShown;
+    private lastCursorSent;
+    private pruneTimer;
+    /** The stroke this participant is drawing, between `beginStroke()` and `endStroke()`. */
+    private activeStroke;
+    private drawPolicy;
+    private readonly syncAnswered;
+    private syncReceivedAnything;
+    constructor(options: CollabSessionOptions);
+    /** Every chat message, oldest first. */
+    get chat(): readonly ChatEntry[];
+    /** Everyone else's pointers currently on the board. */
+    get cursors(): RemoteCursor[];
+    /** Whether this participant may change the board now - see this module's doc comment on who may draw. */
+    get canDraw(): boolean;
+    /** Limits who may change the board to the peers `policy` accepts; `undefined` lets everyone. */
+    setDrawPolicy(policy: ((peer: string) => boolean) | undefined): void;
+    onEvent(listener: (event: CollabEvent) => void): () => void;
+    start(): void;
+    stop(): void;
+    /** Sends `text` as a chat message. Returns `false`, sending nothing, for blank or overlong text. */
+    sendChat(text: string): boolean;
+    /** Starts a stroke at (`x`, `y`); returns its id, or `undefined` when the board is full. */
+    beginStroke(pen: PenType, color: string, size: number, x: number, y: number): string | undefined;
+    /** Adds a point to this participant's own stroke `id` - sent with the next batch. */
+    extendStroke(id: string, x: number, y: number): void;
+    /** Finishes a stroke: whatever points are still waiting go out now. */
+    endStroke(): void;
+    addShape(shape: StencilShape, color: string, size: number, x1: number, y1: number, x2: number, y2: number): string | undefined;
+    addStamp(stamp: Stamp, size: number, x: number, y: number): string | undefined;
+    /** Erases `ids` - anyone's elements, see `protocol.ts`. */
+    erase(ids: string[]): void;
+    /** Erases this participant's own most recent element still on the board; `false` when there is none. */
+    undo(): boolean;
+    /** Clears the board for everyone. */
+    clear(): void;
+    /** Says this participant's pointer is at (`x`, `y`) on the board, as `tool` in `color` (with `stamp` for the stamp
+     * tool) - sent now, or with the latest position once `CURSOR_INTERVAL_MS` has passed since the last one. */
+    moveCursor(x: number, y: number, tool: CursorTool, color: string, stamp?: Stamp): void;
+    /** Says this participant's pointer has left the board. */
+    hideCursor(): void;
+    private flushCursor;
+    private handleCursor;
+    /** Moves `sender`'s pointer to where their stroke just got to - see this module's doc comment on pointers. */
+    private followStroke;
+    private pruneCursors;
+    private mayDraw;
+    private addElement;
+    private applyAndSend;
+    private flushPoints;
+    private handleMessage;
+    private handleHello;
+    private requestSync;
+    /** Asks the next participant not yet asked, if any - after a silence or an empty answer. */
+    private askNext;
+    private armSyncTimeout;
+    private receiveSync;
+    /** Sends `peer` everything said and drawn so far - see this module's doc comment. */
+    private sendSync;
+    private mergeHistory;
+    private addChat;
+    /** Keeps the latest `MAX_CHAT_HISTORY` of `entries`. */
+    private setChat;
+    private send;
+    private emit;
+    private nextId;
+    private nextElementId;
+    private now;
+}