@memberjunction/ai-realtime-client 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/media/videoSourceArbiter.d.ts

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview The VIDEO SOURCE ARBITER: the single writer of a session's inbound video.
+ *
+ * A realtime session can have many things worth showing the model at once: a shared screen, the camera,
+ * a whiteboard, a remote browser. Today's video models accept ONE inbound stream. Before this existed,
+ * every source wrote to that one stream directly: whichever happened to send last "won", and the model
+ * was never told what it was looking at. The arbiter owns the decision:
+ *
+ * - **Sources register** (`RegisterSource`) with an id, a label and a kind, and push frames to the
+ *   arbiter (`PushFrame`) rather than to the client.
+ * - **The arbiter maps N live sources onto the model's `MaxInboundVideoStreams`.** With enough streams
+ *   for every enabled source (a future multi-stream model) frames pass through untouched, each tagged
+ *   with its source id. Otherwise it ranks the sources by a POLICY (data, overridable) and forwards only
+ *   the top N.
+ * - **The model is told when the choice changes** (`[You can now see: Camera]`), because a model
+ *   that silently starts seeing something else will describe the old thing.
+ * - **The user can switch a source off.** A disabled source is not a candidate, sends nothing, and the
+ *   model is told it was turned off (`[You can no longer see: Camera (the user turned it off)]`).
+ * - **The rate comes only from the negotiated track.** Pacing is read from the sink
+ *   (`InboundVideoRate`), never a constant here.
+ *
+ * The notes' wording comes from `@memberjunction/ai` ({@link VideoSourceSeenNote}, {@link VideoSourceTurnedOffNote},
+ * {@link VideoSourceTurnedOnNote}), where a meeting's bridge engine gets its notes too, so the model reads one style of
+ * note in a call and in a meeting.
+ *
+ * It deliberately depends only on the narrow {@link IVideoFrameSink} interface (which
+ * `BaseRealtimeClient` satisfies) and imports nothing from `generic/` or the drivers, so the media code
+ * can be split into its own subpath without untangling it.
+ *
+ * The default policy and the rationale for its ordering are on {@link DEFAULT_VIDEO_SOURCE_POLICY}.
+ *
+ * @module @memberjunction/ai-realtime-client
+ */
+import { type RealtimeTrackDirection } from '@memberjunction/ai';
+/**
+ * The slice of a realtime client the arbiter writes to. `BaseRealtimeClient` satisfies it structurally,
+ * and tests satisfy it with a plain object.
+ */
+export interface IVideoFrameSink {
+    /**
+     * How many concurrent inbound video streams the model accepts. `0` when none is live (no video track
+     * negotiated), `1` for every model shipped so far.
+     */
+    readonly MaxInboundVideoStreams: number;
+    /** The negotiated inbound video rate in frames per second, or `undefined` when none was negotiated. */
+    readonly InboundVideoRate: number | undefined;
+    /** Whether a track of the given modality and direction is established and live. */
+    IsTrackEstablished(modality: string, direction: RealtimeTrackDirection): boolean;
+    /**
+     * Streams one frame to the model, tagged with the source that produced it. Optional because most
+     * drivers have no video; a sink without it makes the arbiter inert.
+     *
+     * @returns `true` if the frame was sent.
+     */
+    SendVideoFrame?(base64Image: string, mimeType?: string, sourceId?: string): boolean;
+    /** Injects a context note into the conversation without triggering a reply. */
+    SendContextNote(text: string): void;
+}
+/**
+ * What kind of source this is. Open vocabulary: `'camera'` and `'screen'` are CAPTURES (the user chose to
+ * share them), `'surface'` is a channel surface (a whiteboard, a remote browser); anything else is treated
+ * as a surface unless the policy says otherwise.
+ */
+export type VideoSourceKind = 'camera' | 'screen' | 'surface' | (string & {});
+/** Whether a source kind is a capture (as opposed to a channel surface). */
+export declare function IsVideoCaptureKind(kind: VideoSourceKind | undefined): boolean;
+/** What a source registers itself as. */
+export interface VideoSourceDescriptor {
+    /** Stable id of the source within the session. Registering an existing id updates it in place. */
+    SourceID: string;
+    /** Human-readable name, used in the notes sent to the model and in the UI's "agent can see" list. */
+    Label: string;
+    /** What kind of source this is. Defaults to `'surface'`. */
+    Kind?: VideoSourceKind;
+    /**
+     * The channel this source belongs to, when it comes from one. The UI maps a source to the user's
+     * persisted per-channel visual-perception choice by this key.
+     */
+    ChannelKey?: string;
+    /**
+     * Whether a newly registered source starts enabled. Default `true`. A source the agent may not see yet registers
+     * disabled, so the model is never told it is looking at it. Ignored for an id that is already registered; use
+     * {@link VideoSourceArbiter.SetSourceEnabled} for that.
+     */
+    Enabled?: boolean;
+}
+/** A source as the arbiter currently sees it. */
+export interface VideoSourceState extends VideoSourceDescriptor {
+    /** `false` when the user (or exposure policy) turned the source off: it is not a candidate and sends nothing. */
+    Enabled: boolean;
+    /** Whether the arbiter is currently forwarding this source's frames to the model. */
+    Active: boolean;
+    /** Frames forwarded to the model so far. */
+    FramesSent: number;
+    /** Epoch ms of the last forwarded frame; `undefined` before the first. */
+    LastFrameAt?: number;
+    /**
+     * `true` while it is the user's pick ({@link VideoSourceArbiter.SelectSource}), which beats every other rule. Absent
+     * otherwise, and while nothing is picked the policy decides.
+     */
+    Picked?: boolean;
+}
+/**
+ * One rule of the source-selection policy. Rules apply in order and each contributes the sources it
+ * prefers; the arbiter forwards the first `MaxInboundVideoStreams` of the combined ranking.
+ *
+ * - `'user-pick'`: the source the user explicitly chose ({@link VideoSourceArbiter.SelectSource}).
+ * - `'recent-capture'`: captures (camera, screen), the most recently started first.
+ * - `'focused'`: the source belonging to the surface the user is looking at
+ *   ({@link VideoSourceArbiter.SetFocusedSource}).
+ * - `'recent'`: any source at all, the most recently started first. The catch-all, so a session whose
+ *   only source is a surface with no focus still shows it.
+ */
+export type VideoSourcePolicyRule = 'user-pick' | 'recent-capture' | 'focused' | 'recent';
+/**
+ * The default selection policy, as DATA so an agent or host can reorder or trim it.
+ *
+ * Order: an explicit user pick beats everything (the user is the authority on what the agent sees);
+ * then the most recently started CAPTURE, because starting a camera or share is a deliberate "look at
+ * this" and a surface is always there to come back to; then the focused surface; then simply the newest
+ * source, so a lone unfocused surface is never invisible.
+ *
+ * "Most recently started" is applied to captures rather than to every source. Applied to everything it
+ * would always produce a winner and the focused-surface rule could never be reached.
+ */
+export declare const DEFAULT_VIDEO_SOURCE_POLICY: readonly VideoSourcePolicyRule[];
+/** Options for a {@link VideoSourceArbiter}. */
+export interface VideoSourceArbiterOptions {
+    /** The selection policy. Defaults to {@link DEFAULT_VIDEO_SOURCE_POLICY}. */
+    Policy?: readonly VideoSourcePolicyRule[];
+    /**
+     * The note sent when the set of sources the model sees changes while sources are being arbitrated.
+     * Receives the labels now in view. Return `null` to send nothing. Default: {@link VideoSourceSeenNote}
+     * with every label in view.
+     */
+    FormatSwitchNote?: (labels: readonly string[]) => string | null;
+    /** The note sent when a source is turned off. Return `null` to send nothing. Default: {@link VideoSourceTurnedOffNote}. */
+    FormatDisabledNote?: (label: string) => string | null;
+    /** The note sent when a source is turned back on. Return `null` to send nothing. Default: {@link VideoSourceTurnedOnNote}. */
+    FormatEnabledNote?: (label: string) => string | null;
+    /** Reports a problem (a throwing sink). Defaults to `console.error`; the arbiter never throws into a caller's timer. */
+    OnError?: (context: string, error: unknown) => void;
+    /** Clock, injectable for tests. Defaults to `Date.now`. */
+    Now?: () => number;
+}
+/** A sink or a way to find the current one (the client changes across a reconnect). */
+export type VideoFrameSinkSource = IVideoFrameSink | (() => IVideoFrameSink | null | undefined) | null | undefined;
+/**
+ * The per-session arbiter. Obtain the one for a client with {@link VideoSourceArbiter.ForSink} so every
+ * writer shares it; constructing a second one for the same client would make two writers again.
+ */
+export declare class VideoSourceArbiter {
+    private readonly sinkSource;
+    private readonly options;
+    private static readonly bySink;
+    /**
+     * The arbiter for a sink, created on first use. One arbiter per sink is the whole point (a single
+     * writer), so every bridge and channel that gets its arbiter this way shares it.
+     *
+     * @param sink The client (anything satisfying {@link IVideoFrameSink}).
+     * @param options Options applied only when the arbiter is created.
+     */
+    static ForSink(sink: IVideoFrameSink, options?: VideoSourceArbiterOptions): VideoSourceArbiter;
+    private readonly sources;
+    private readonly policy;
+    private readonly handlers;
+    private nextSeq;
+    private userPick;
+    private focused;
+    private focusedChannel;
+    /** The ids forwarded as of the last reconcile — the baseline a change is detected against. */
+    private lastActive;
+    /** Whether the previous reconcile had more enabled sources than streams (arbitration in effect). */
+    private lastArbitrating;
+    constructor(sinkSource: VideoFrameSinkSource, options?: VideoSourceArbiterOptions);
+    private get sink();
+    /**
+     * Registers a source, or updates its label/kind if the id is already registered (its recency, enabled
+     * state and counters are kept). A newly registered source counts as the most recently STARTED.
+     */
+    RegisterSource(descriptor: VideoSourceDescriptor): void;
+    /** Removes a source. Its explicit pick or focus, if it held one, is cleared. */
+    UnregisterSource(sourceId: string): void;
+    /** Whether a source id is registered. */
+    HasSource(sourceId: string): boolean;
+    /**
+     * The user explicitly picks the source the agent sees (`null` clears the pick). A pick beats every
+     * other rule. Returns `false` for an unknown or disabled source (nothing changes).
+     */
+    SelectSource(sourceId: string | null): boolean;
+    /**
+     * Marks the CHANNEL whose surface the user is looking at (`null` clears it): every source registered for that
+     * channel counts as focused, including one that registers after this call (a surface the user is already on
+     * before its first frame). Used by the `'focused'` rule alongside {@link SetFocusedSource}.
+     */
+    SetFocusedChannel(channelKey: string | null): void;
+    /** Marks the source whose surface the user is looking at (`null` clears it). Used by the `'focused'` rule. */
+    SetFocusedSource(sourceId: string | null): void;
+    /**
+     * Turns a source on or off. A disabled source is not a candidate and forwards nothing.
+     *
+     * @param sourceId The source.
+     * @param enabled The new state.
+     * @param notify Whether to tell the model. Default `true`. A caller that sends its own note about the
+     *   same change (a channel lowering its exposure) passes `false` so the model is told once.
+     * @returns `false` for an unknown source; `true` otherwise (including "already in that state").
+     */
+    SetSourceEnabled(sourceId: string, enabled: boolean, notify?: boolean): boolean;
+    /** A snapshot of every registered source and whether it is being forwarded, in registration order. */
+    GetSources(): VideoSourceState[];
+    /** The ids the arbiter would forward right now, best first. */
+    GetActiveSourceIDs(): string[];
+    /**
+     * Subscribes to structural changes (a source registered, removed, enabled, disabled, picked, focused,
+     * or the forwarded set changing). Not called per frame.
+     *
+     * @returns An unsubscribe function.
+     */
+    OnChange(handler: () => void): () => void;
+    /**
+     * A source offers a frame. It is forwarded to the model only if the source is enabled, among the
+     * sources the model should see, and not inside the negotiated pacing interval.
+     *
+     * @param sourceId The producing source (it must be registered).
+     * @param base64Image The frame, base64-encoded.
+     * @param mimeType Image MIME type. Defaults to `'image/jpeg'`.
+     * @returns `true` if the frame was sent to the model.
+     */
+    PushFrame(sourceId: string, base64Image: string, mimeType?: string): boolean;
+    /** Drops every source and subscription. The arbiter stays usable (it simply has no sources). */
+    Dispose(): void;
+    /** The enabled sources, ranked by policy, best first. */
+    private rank;
+    /** The ids to forward: the top N of the ranking, N being the model's inbound video stream count. */
+    private computeActive;
+    /**
+     * Re-derives the forwarded set and, when it changed while sources are being arbitrated, tells the model.
+     *
+     * @param quiet Update the baseline without sending a switch note (the caller sends its own).
+     */
+    private reconcile;
+    private formatDisabledNote;
+    private formatEnabledNote;
+    private now;
+    private send;
+    private sendNote;
+    private emitChange;
+    private reportError;
+}
+//# sourceMappingURL=videoSourceArbiter.d.ts.map

package/dist/media/videoSourceArbiter.d.ts.map

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

package/dist/media/videoSourceArbiter.js

@@ -0,0 +1,423 @@
+/**
+ * @fileoverview The VIDEO SOURCE ARBITER: the single writer of a session's inbound video.
+ *
+ * A realtime session can have many things worth showing the model at once: a shared screen, the camera,
+ * a whiteboard, a remote browser. Today's video models accept ONE inbound stream. Before this existed,
+ * every source wrote to that one stream directly: whichever happened to send last "won", and the model
+ * was never told what it was looking at. The arbiter owns the decision:
+ *
+ * - **Sources register** (`RegisterSource`) with an id, a label and a kind, and push frames to the
+ *   arbiter (`PushFrame`) rather than to the client.
+ * - **The arbiter maps N live sources onto the model's `MaxInboundVideoStreams`.** With enough streams
+ *   for every enabled source (a future multi-stream model) frames pass through untouched, each tagged
+ *   with its source id. Otherwise it ranks the sources by a POLICY (data, overridable) and forwards only
+ *   the top N.
+ * - **The model is told when the choice changes** (`[You can now see: Camera]`), because a model
+ *   that silently starts seeing something else will describe the old thing.
+ * - **The user can switch a source off.** A disabled source is not a candidate, sends nothing, and the
+ *   model is told it was turned off (`[You can no longer see: Camera (the user turned it off)]`).
+ * - **The rate comes only from the negotiated track.** Pacing is read from the sink
+ *   (`InboundVideoRate`), never a constant here.
+ *
+ * The notes' wording comes from `@memberjunction/ai` ({@link VideoSourceSeenNote}, {@link VideoSourceTurnedOffNote},
+ * {@link VideoSourceTurnedOnNote}), where a meeting's bridge engine gets its notes too, so the model reads one style of
+ * note in a call and in a meeting.
+ *
+ * It deliberately depends only on the narrow {@link IVideoFrameSink} interface (which
+ * `BaseRealtimeClient` satisfies) and imports nothing from `generic/` or the drivers, so the media code
+ * can be split into its own subpath without untangling it.
+ *
+ * The default policy and the rationale for its ordering are on {@link DEFAULT_VIDEO_SOURCE_POLICY}.
+ *
+ * @module @memberjunction/ai-realtime-client
+ */
+import { VideoSourceSeenNote, VideoSourceTurnedOffNote, VideoSourceTurnedOnNote } from '@memberjunction/ai';
+import { MinVideoFrameSpacingMs } from './videoPacing.js';
+/** Source kinds the default ranking treats as captures: things a person started sharing on purpose. */
+const CAPTURE_KINDS = new Set(['camera', 'screen']);
+/** Whether a source kind is a capture (as opposed to a channel surface). */
+export function IsVideoCaptureKind(kind) {
+    return kind !== undefined && CAPTURE_KINDS.has(kind);
+}
+/**
+ * The default selection policy, as DATA so an agent or host can reorder or trim it.
+ *
+ * Order: an explicit user pick beats everything (the user is the authority on what the agent sees);
+ * then the most recently started CAPTURE, because starting a camera or share is a deliberate "look at
+ * this" and a surface is always there to come back to; then the focused surface; then simply the newest
+ * source, so a lone unfocused surface is never invisible.
+ *
+ * "Most recently started" is applied to captures rather than to every source. Applied to everything it
+ * would always produce a winner and the focused-surface rule could never be reached.
+ */
+export const DEFAULT_VIDEO_SOURCE_POLICY = Object.freeze([
+    'user-pick',
+    'recent-capture',
+    'focused',
+    'recent',
+]);
+/**
+ * How many streams a sink can take right now. A sink that predates `MaxInboundVideoStreams` (a custom
+ * client, a test double) is read the way every model was until the field existed: one stream while an
+ * inbound video track is live, none otherwise.
+ */
+function streamCapacity(sink) {
+    if (!sink) {
+        return 0;
+    }
+    if (typeof sink.MaxInboundVideoStreams === 'number') {
+        return sink.MaxInboundVideoStreams;
+    }
+    return sink.IsTrackEstablished('video', 'inbound') ? 1 : 0;
+}
+/**
+ * The per-session arbiter. Obtain the one for a client with {@link VideoSourceArbiter.ForSink} so every
+ * writer shares it; constructing a second one for the same client would make two writers again.
+ */
+export class VideoSourceArbiter {
+    static { this.bySink = new WeakMap(); }
+    /**
+     * The arbiter for a sink, created on first use. One arbiter per sink is the whole point (a single
+     * writer), so every bridge and channel that gets its arbiter this way shares it.
+     *
+     * @param sink The client (anything satisfying {@link IVideoFrameSink}).
+     * @param options Options applied only when the arbiter is created.
+     */
+    static ForSink(sink, options) {
+        let arbiter = VideoSourceArbiter.bySink.get(sink);
+        if (!arbiter) {
+            arbiter = new VideoSourceArbiter(sink, options);
+            VideoSourceArbiter.bySink.set(sink, arbiter);
+        }
+        return arbiter;
+    }
+    constructor(sinkSource, options = {}) {
+        this.sinkSource = sinkSource;
+        this.options = options;
+        this.sources = new Map();
+        this.handlers = new Set();
+        this.nextSeq = 1;
+        this.userPick = null;
+        this.focused = null;
+        this.focusedChannel = null;
+        /** The ids forwarded as of the last reconcile — the baseline a change is detected against. */
+        this.lastActive = [];
+        /** Whether the previous reconcile had more enabled sources than streams (arbitration in effect). */
+        this.lastArbitrating = false;
+        this.policy = options.Policy ?? DEFAULT_VIDEO_SOURCE_POLICY;
+    }
+    get sink() {
+        const resolved = typeof this.sinkSource === 'function' ? this.sinkSource() : this.sinkSource;
+        return resolved ?? null;
+    }
+    /**
+     * Registers a source, or updates its label/kind if the id is already registered (its recency, enabled
+     * state and counters are kept). A newly registered source counts as the most recently STARTED.
+     */
+    RegisterSource(descriptor) {
+        if (!descriptor.SourceID) {
+            throw new Error('VideoSourceArbiter.RegisterSource requires a SourceID.');
+        }
+        const existing = this.sources.get(descriptor.SourceID);
+        if (existing) {
+            existing.Label = descriptor.Label;
+            existing.Kind = descriptor.Kind ?? existing.Kind;
+            existing.ChannelKey = descriptor.ChannelKey ?? existing.ChannelKey;
+        }
+        else {
+            this.sources.set(descriptor.SourceID, {
+                ...descriptor,
+                Kind: descriptor.Kind ?? 'surface',
+                Enabled: descriptor.Enabled ?? true,
+                Seq: this.nextSeq++,
+                FramesSent: 0,
+                LastSentAt: 0,
+            });
+        }
+        this.reconcile();
+        this.emitChange();
+    }
+    /** Removes a source. Its explicit pick or focus, if it held one, is cleared. */
+    UnregisterSource(sourceId) {
+        if (!this.sources.delete(sourceId)) {
+            return;
+        }
+        if (this.userPick === sourceId) {
+            this.userPick = null;
+        }
+        if (this.focused === sourceId) {
+            this.focused = null;
+        }
+        this.reconcile();
+        this.emitChange();
+    }
+    /** Whether a source id is registered. */
+    HasSource(sourceId) {
+        return this.sources.has(sourceId);
+    }
+    /**
+     * The user explicitly picks the source the agent sees (`null` clears the pick). A pick beats every
+     * other rule. Returns `false` for an unknown or disabled source (nothing changes).
+     */
+    SelectSource(sourceId) {
+        if (sourceId !== null) {
+            const source = this.sources.get(sourceId);
+            if (!source || !source.Enabled) {
+                return false;
+            }
+        }
+        this.userPick = sourceId;
+        this.reconcile();
+        this.emitChange();
+        return true;
+    }
+    /**
+     * Marks the CHANNEL whose surface the user is looking at (`null` clears it): every source registered for that
+     * channel counts as focused, including one that registers after this call (a surface the user is already on
+     * before its first frame). Used by the `'focused'` rule alongside {@link SetFocusedSource}.
+     */
+    SetFocusedChannel(channelKey) {
+        if (this.focusedChannel === channelKey) {
+            return;
+        }
+        this.focusedChannel = channelKey;
+        this.reconcile();
+        this.emitChange();
+    }
+    /** Marks the source whose surface the user is looking at (`null` clears it). Used by the `'focused'` rule. */
+    SetFocusedSource(sourceId) {
+        this.focused = sourceId !== null && this.sources.has(sourceId) ? sourceId : null;
+        this.reconcile();
+        this.emitChange();
+    }
+    /**
+     * Turns a source on or off. A disabled source is not a candidate and forwards nothing.
+     *
+     * @param sourceId The source.
+     * @param enabled The new state.
+     * @param notify Whether to tell the model. Default `true`. A caller that sends its own note about the
+     *   same change (a channel lowering its exposure) passes `false` so the model is told once.
+     * @returns `false` for an unknown source; `true` otherwise (including "already in that state").
+     */
+    SetSourceEnabled(sourceId, enabled, notify = true) {
+        const source = this.sources.get(sourceId);
+        if (!source) {
+            return false;
+        }
+        if (source.Enabled === enabled) {
+            return true;
+        }
+        source.Enabled = enabled;
+        if (!enabled && this.userPick === sourceId) {
+            this.userPick = null;
+        }
+        // Reconcile FIRST and quietly: the toggle has its own note, so a switch note on top of it
+        // would tell the model the same thing twice.
+        this.reconcile(true);
+        if (notify) {
+            this.sendNote(enabled ? this.formatEnabledNote(source.Label) : this.formatDisabledNote(source.Label));
+        }
+        this.emitChange();
+        return true;
+    }
+    /** A snapshot of every registered source and whether it is being forwarded, in registration order. */
+    GetSources() {
+        const active = new Set(this.computeActive());
+        return [...this.sources.values()]
+            .sort((a, b) => a.Seq - b.Seq)
+            .map((s) => ({
+            SourceID: s.SourceID,
+            Label: s.Label,
+            Kind: s.Kind,
+            ChannelKey: s.ChannelKey,
+            Enabled: s.Enabled,
+            Active: active.has(s.SourceID),
+            FramesSent: s.FramesSent,
+            LastFrameAt: s.LastFrameAt,
+            ...(this.userPick === s.SourceID ? { Picked: true } : {}),
+        }));
+    }
+    /** The ids the arbiter would forward right now, best first. */
+    GetActiveSourceIDs() {
+        return this.computeActive();
+    }
+    /**
+     * Subscribes to structural changes (a source registered, removed, enabled, disabled, picked, focused,
+     * or the forwarded set changing). Not called per frame.
+     *
+     * @returns An unsubscribe function.
+     */
+    OnChange(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    /**
+     * A source offers a frame. It is forwarded to the model only if the source is enabled, among the
+     * sources the model should see, and not inside the negotiated pacing interval.
+     *
+     * @param sourceId The producing source (it must be registered).
+     * @param base64Image The frame, base64-encoded.
+     * @param mimeType Image MIME type. Defaults to `'image/jpeg'`.
+     * @returns `true` if the frame was sent to the model.
+     */
+    PushFrame(sourceId, base64Image, mimeType = 'image/jpeg') {
+        const source = this.sources.get(sourceId);
+        const sink = this.sink;
+        if (!source || !source.Enabled || !sink || typeof sink.SendVideoFrame !== 'function') {
+            return false;
+        }
+        if (!sink.IsTrackEstablished('video', 'inbound')) {
+            return false;
+        }
+        // The stream count can change once the track is negotiated, so the active set is re-derived
+        // here rather than trusted from the last registration.
+        this.reconcile();
+        if (!this.computeActive().includes(sourceId)) {
+            return false;
+        }
+        const now = this.now();
+        if (source.LastSentAt > 0 && now - source.LastSentAt < MinVideoFrameSpacingMs(sink.InboundVideoRate)) {
+            return false;
+        }
+        const sent = this.send(sink, base64Image, mimeType, sourceId);
+        if (sent) {
+            source.LastSentAt = now;
+            source.LastFrameAt = now;
+            source.FramesSent++;
+        }
+        return sent;
+    }
+    /** Drops every source and subscription. The arbiter stays usable (it simply has no sources). */
+    Dispose() {
+        this.sources.clear();
+        this.userPick = null;
+        this.focused = null;
+        this.focusedChannel = null;
+        this.lastActive = [];
+        this.lastArbitrating = false;
+        this.handlers.clear();
+    }
+    // ── selection ───────────────────────────────────────────────────────────
+    /** The enabled sources, ranked by policy, best first. */
+    rank() {
+        const enabled = [...this.sources.values()].filter((s) => s.Enabled);
+        const newestFirst = (list) => [...list].sort((a, b) => b.Seq - a.Seq);
+        const ranked = [];
+        const add = (list) => {
+            for (const s of list) {
+                if (!ranked.includes(s)) {
+                    ranked.push(s);
+                }
+            }
+        };
+        for (const rule of this.policy) {
+            switch (rule) {
+                case 'user-pick':
+                    add(enabled.filter((s) => s.SourceID === this.userPick));
+                    break;
+                case 'recent-capture':
+                    add(newestFirst(enabled.filter((s) => IsVideoCaptureKind(s.Kind))));
+                    break;
+                case 'focused':
+                    add(enabled.filter((s) => s.SourceID === this.focused || (this.focusedChannel !== null && s.ChannelKey === this.focusedChannel)));
+                    break;
+                case 'recent':
+                    add(newestFirst(enabled));
+                    break;
+            }
+        }
+        // A policy without the catch-all must still be total over the enabled sources' ORDER, but it is
+        // allowed to leave some out: that is what trimming the policy means.
+        return ranked;
+    }
+    /** The ids to forward: the top N of the ranking, N being the model's inbound video stream count. */
+    computeActive() {
+        const streams = streamCapacity(this.sink);
+        if (streams <= 0) {
+            return [];
+        }
+        return this.rank().slice(0, streams).map((s) => s.SourceID);
+    }
+    /**
+     * Re-derives the forwarded set and, when it changed while sources are being arbitrated, tells the model.
+     *
+     * @param quiet Update the baseline without sending a switch note (the caller sends its own).
+     */
+    reconcile(quiet = false) {
+        const sink = this.sink;
+        const streams = streamCapacity(sink);
+        const enabledCount = [...this.sources.values()].filter((s) => s.Enabled).length;
+        const arbitrating = streams > 0 && enabledCount > streams;
+        const active = this.computeActive();
+        const changed = active.length !== this.lastActive.length || active.some((id, i) => id !== this.lastActive[i]);
+        const wasArbitrating = this.lastArbitrating;
+        this.lastActive = active;
+        this.lastArbitrating = arbitrating;
+        if (!changed || quiet || !sink) {
+            return;
+        }
+        // Notes only matter when the model could be confused about what it sees: more sources than
+        // streams now, or just before. A lone source appearing or leaving is not a "switch".
+        if (!arbitrating && !wasArbitrating) {
+            return;
+        }
+        if (active.length === 0) {
+            // Nothing left to switch TO. A source the user turned off has its own note, and a session whose
+            // last source stopped has nothing the model could be confused about.
+            return;
+        }
+        const labels = active.map((id) => this.sources.get(id)?.Label ?? id);
+        this.sendNote(this.options.FormatSwitchNote ? this.options.FormatSwitchNote(labels) : VideoSourceSeenNote(labels));
+    }
+    // ── plumbing ────────────────────────────────────────────────────────────
+    formatDisabledNote(label) {
+        return this.options.FormatDisabledNote ? this.options.FormatDisabledNote(label) : VideoSourceTurnedOffNote(label);
+    }
+    formatEnabledNote(label) {
+        return this.options.FormatEnabledNote ? this.options.FormatEnabledNote(label) : VideoSourceTurnedOnNote(label);
+    }
+    now() {
+        return this.options.Now ? this.options.Now() : Date.now();
+    }
+    send(sink, base64Image, mimeType, sourceId) {
+        try {
+            return Boolean(sink.SendVideoFrame?.(base64Image, mimeType, sourceId));
+        }
+        catch (error) {
+            this.reportError('sending a video frame', error);
+            return false;
+        }
+    }
+    sendNote(note) {
+        const sink = this.sink;
+        if (!note || !sink) {
+            return;
+        }
+        try {
+            sink.SendContextNote(note);
+        }
+        catch (error) {
+            this.reportError('sending a source note', error);
+        }
+    }
+    emitChange() {
+        for (const handler of [...this.handlers]) {
+            try {
+                handler();
+            }
+            catch (error) {
+                this.reportError('notifying a change handler', error);
+            }
+        }
+    }
+    reportError(context, error) {
+        if (this.options.OnError) {
+            this.options.OnError(context, error);
+            return;
+        }
+        console.error(`[VideoSourceArbiter] Error ${context}:`, error);
+    }
+}
+//# sourceMappingURL=videoSourceArbiter.js.map