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

package/dist/media/localMediaController.js

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview LOCAL MEDIA CONTROLLER: the user's camera and microphone. It lists devices, starts and stops
+ * each kind, moves a live kind to another device, follows device changes, and reports all of it through
+ * {@link LocalMediaController.State$}.
+ *
+ * - **It never starts on its own.** Every capture begins with an explicit {@link LocalMediaController.Start}.
+ *   Whether frames or audio reach the model is decided where they are sent (the runtime, after the camera
+ *   check), not here.
+ * - **A device switch keeps the stream.** The new track replaces the old one inside the `MediaStream` that
+ *   {@link LocalMediaController.GetStream} handed out, so a `<video>` self-view or a `FrameSampler` keeps
+ *   working. Consumers bound to a track rather than a stream (a Web Audio source node, a WebRTC sender) must
+ *   rebind when `State$` reports the new device; a realtime client does it in `ReplaceMicrophone`. The new
+ *   track keeps the old one's `enabled` flag, so a muted microphone stays muted. The current device is
+ *   released before the new one opens, because mobile browsers open one camera at a time; if the new one
+ *   fails, the previous one is reopened.
+ * - **A lost device falls back to the default.** When the device in use goes away (unplugged, Bluetooth
+ *   dropped), the kind restarts on the system default device. Only when none is left does it report `failed`.
+ * - **Capture runs at the device's native frame rate**; pace what the model receives with a `FrameSampler`.
+ *
+ * Screen sharing is `RequestDisplayCapture`'s job, not this controller's.
+ *
+ * @module @memberjunction/ai-realtime-client/media
+ */
+import { BehaviorSubject } from 'rxjs';
+const DEFAULT_CAMERA_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 } };
+const DEFAULT_MICROPHONE_CONSTRAINTS = { echoCancellation: true, noiseSuppression: true, autoGainControl: true };
+const OFF = { Status: 'off' };
+/** The camera and microphone of one browser session. */
+export class LocalMediaController {
+    constructor(options = {}) {
+        this.options = options;
+        this.state = new BehaviorSubject({ Camera: OFF, Microphone: OFF, Devices: [] });
+        this.live = { camera: null, microphone: null };
+        this.pending = { camera: null, microphone: null };
+        /** Bumped by every Stop, so a start that resolves after it knows it was cancelled. */
+        this.generation = { camera: 0, microphone: 0 };
+        this.onDeviceChange = () => void this.RefreshDevices();
+        this.disposed = false;
+        mediaDevices()?.addEventListener('devicechange', this.onDeviceChange);
+    }
+    /** The current state. */
+    get State() {
+        return this.state.value;
+    }
+    /** The state, now and on every change. Completes on {@link Dispose}. */
+    get State$() {
+        return this.state.asObservable();
+    }
+    /** The live stream of a kind, or `null` while it is off. The same object across device switches. */
+    GetStream(kind) {
+        return this.live[kind]?.Stream ?? null;
+    }
+    /**
+     * Lists the input devices. Labels stay empty until the user has allowed this site that kind of device. If
+     * the browser cannot list them, the last list is kept.
+     */
+    async RefreshDevices() {
+        const devices = mediaDevices();
+        if (!devices?.enumerateDevices) {
+            return this.State.Devices;
+        }
+        try {
+            const listed = await devices.enumerateDevices();
+            const inputs = listed.flatMap((info) => {
+                const kind = localKindOf(info.kind);
+                return kind ? [{ DeviceID: info.deviceId, Kind: kind, Label: info.label, GroupID: info.groupId }] : [];
+            });
+            this.publish({ Devices: inputs });
+            return inputs;
+        }
+        catch (err) {
+            console.warn('[LocalMediaController] Could not list devices:', err);
+            return this.State.Devices;
+        }
+    }
+    /**
+     * Starts capturing a kind: on `deviceId` when it is available, otherwise on the system default. If the
+     * kind is already on, returns its stream.
+     */
+    Start(kind, deviceId) {
+        const current = this.live[kind];
+        if (current) {
+            return Promise.resolve({ Status: 'started', Stream: current.Stream });
+        }
+        let pending = this.pending[kind];
+        if (!pending) {
+            pending = this.startCapture(kind, deviceId).finally(() => {
+                this.pending[kind] = null;
+            });
+            this.pending[kind] = pending;
+        }
+        return pending;
+    }
+    /**
+     * Moves a live kind to another device, keeping the same stream. The current device is released first; if
+     * the new device fails, the previous one is reopened. A kind that is off is started on that device instead.
+     */
+    async SwitchDevice(kind, deviceId) {
+        const current = this.live[kind];
+        if (!current) {
+            return this.Start(kind, deviceId);
+        }
+        const previous = current.Track.getSettings().deviceId;
+        const generation = this.beginChange(kind, current);
+        const switched = await this.acquire(kind, { exact: deviceId });
+        if (!this.isLatest(kind, generation, switched)) {
+            return { Status: 'failed', Reason: 'error', Message: 'Stopped or changed again before the switch finished.' };
+        }
+        if (switched.Status === 'started') {
+            this.insertTrack(kind, current, switched.Track);
+            return { Status: 'started', Stream: current.Stream };
+        }
+        await this.reopenOrFail(kind, current, previous ? { exact: previous } : undefined, generation);
+        return switched;
+    }
+    /** Stops a kind and releases its device. */
+    Stop(kind) {
+        this.generation[kind]++;
+        const current = this.live[kind];
+        this.live[kind] = null;
+        if (current) {
+            current.Unwatch();
+            current.Stream.getTracks().forEach((track) => track.stop());
+        }
+        this.publishTrack(kind, OFF);
+    }
+    /** Stops both kinds, stops following device changes, and completes {@link State$}. */
+    Dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.Stop('camera');
+        this.Stop('microphone');
+        mediaDevices()?.removeEventListener('devicechange', this.onDeviceChange);
+        this.disposed = true;
+        this.state.complete();
+    }
+    async startCapture(kind, deviceId) {
+        const generation = this.generation[kind];
+        this.publishTrack(kind, { Status: 'starting' });
+        const acquired = await this.acquire(kind, deviceId ? { ideal: deviceId } : undefined);
+        if (!this.isLatest(kind, generation, acquired)) {
+            return { Status: 'failed', Reason: 'error', Message: 'Stopped before the device started.' };
+        }
+        if (acquired.Status === 'failed') {
+            this.publishTrack(kind, { Status: 'failed', Failure: acquired.Reason, Message: acquired.Message });
+            return acquired;
+        }
+        const stream = acquired.Stream;
+        this.live[kind] = { Stream: stream, Track: acquired.Track, Unwatch: this.watch(kind, acquired.Track) };
+        this.publishTrack(kind, onState(acquired.Track));
+        // Labels appear once the user has allowed the device.
+        void this.RefreshDevices();
+        return { Status: 'started', Stream: stream };
+    }
+    /** Asks the browser for one track of a kind. */
+    async acquire(kind, deviceId) {
+        const devices = mediaDevices();
+        if (!devices?.getUserMedia) {
+            return { Status: 'failed', Reason: 'unsupported', Message: 'This browser cannot capture a camera or microphone.' };
+        }
+        const constraints = { ...this.constraintsFor(kind), ...(deviceId ? { deviceId } : {}) };
+        try {
+            const stream = await devices.getUserMedia(kind === 'camera' ? { video: constraints } : { audio: constraints });
+            const track = (kind === 'camera' ? stream.getVideoTracks() : stream.getAudioTracks())[0];
+            if (!track) {
+                stream.getTracks().forEach((t) => t.stop());
+                return { Status: 'failed', Reason: 'error', Message: `The browser returned no ${kind} track.` };
+            }
+            return { Status: 'started', Stream: stream, Track: track };
+        }
+        catch (err) {
+            return { Status: 'failed', Reason: failureOf(err), Message: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    constraintsFor(kind) {
+        return kind === 'camera'
+            ? (this.options.CameraConstraints ?? DEFAULT_CAMERA_CONSTRAINTS)
+            : (this.options.MicrophoneConstraints ?? DEFAULT_MICROPHONE_CONSTRAINTS);
+    }
+    /**
+     * Releases a live capture's device ahead of opening another one, and reports the kind as starting.
+     *
+     * @returns The change's generation: a later change, or a Stop, makes it stale.
+     */
+    beginChange(kind, current) {
+        current.Unwatch();
+        current.Stream.removeTrack(current.Track);
+        current.Track.stop();
+        this.publishTrack(kind, { Status: 'starting' });
+        return ++this.generation[kind];
+    }
+    /** Whether a change is still the latest for its kind. If not, the device it opened is released. */
+    isLatest(kind, generation, acquired) {
+        if (generation === this.generation[kind]) {
+            return true;
+        }
+        if (acquired.Status === 'started') {
+            acquired.Track.stop();
+        }
+        return false;
+    }
+    /**
+     * Puts a track in the stream of the capture it replaces and reports its device. The track takes over the
+     * old one's `enabled` flag, so a muted microphone stays muted on the new device.
+     */
+    insertTrack(kind, replacing, track) {
+        track.enabled = replacing.Track.enabled;
+        replacing.Stream.addTrack(track);
+        this.live[kind] = { Stream: replacing.Stream, Track: track, Unwatch: this.watch(kind, track) };
+        this.publishTrack(kind, onState(track));
+    }
+    /** Opens a device in place of a released capture; if that fails, stops the kind and reports why. */
+    async reopenOrFail(kind, replacing, deviceId, generation) {
+        const reopened = await this.acquire(kind, deviceId);
+        if (!this.isLatest(kind, generation, reopened)) {
+            return;
+        }
+        if (reopened.Status === 'started') {
+            this.insertTrack(kind, replacing, reopened.Track);
+            return;
+        }
+        this.Stop(kind);
+        this.publishTrack(kind, { Status: 'failed', Failure: reopened.Reason, Message: reopened.Message });
+    }
+    /** Follows a live track: when it ends without being stopped here, its device went away. */
+    watch(kind, track) {
+        const onEnded = () => void this.recoverFromLostDevice(kind, track);
+        track.addEventListener('ended', onEnded);
+        return () => track.removeEventListener('ended', onEnded);
+    }
+    /** Restarts a kind whose device went away on the system default, or reports that none is left. */
+    async recoverFromLostDevice(kind, lost) {
+        const current = this.live[kind];
+        if (!current || current.Track !== lost) {
+            return;
+        }
+        const generation = this.beginChange(kind, current);
+        await this.reopenOrFail(kind, current, undefined, generation);
+    }
+    publishTrack(kind, track) {
+        this.publish(kind === 'camera' ? { Camera: track } : { Microphone: track });
+    }
+    publish(change) {
+        if (!this.disposed) {
+            this.state.next({ ...this.state.value, ...change });
+        }
+    }
+}
+/** The browser's media devices, or `undefined` where there are none (Node, some embedded views). */
+function mediaDevices() {
+    return typeof navigator === 'undefined' ? undefined : navigator.mediaDevices;
+}
+/** The local kind of a browser device kind; `null` for outputs. */
+function localKindOf(kind) {
+    if (kind === 'videoinput') {
+        return 'camera';
+    }
+    return kind === 'audioinput' ? 'microphone' : null;
+}
+/** The `on` state for a live track: its device and name. */
+function onState(track) {
+    return { Status: 'on', DeviceID: track.getSettings().deviceId, Label: track.label };
+}
+/** Maps a `getUserMedia` rejection to a failure reason. */
+function failureOf(err) {
+    switch (err instanceof Error ? err.name : '') {
+        case 'NotAllowedError':
+        case 'SecurityError':
+            return 'denied';
+        case 'NotFoundError':
+        case 'OverconstrainedError':
+            return 'not-found';
+        case 'NotReadableError':
+        case 'AbortError':
+            return 'in-use';
+        default:
+            return 'error';
+    }
+}
+//# sourceMappingURL=localMediaController.js.map

package/dist/media/localMediaController.js.map

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

package/dist/media/mediaLayout.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview MEDIA LAYOUT: the user's layout of a media stage as a host keeps and saves it.
+ * - **Moves.** One move per surface, oldest first: the list `LayoutMediaStage` and `ResolveSurfacePlacements` read.
+ *   {@link RecordPlacementMove} keeps it that way, and {@link WithoutStageMoves} hands the stage back to its default.
+ * - **Boxes.** Where the user put each picture-in-picture box, by surface key, as fractions of the stage.
+ * - **Self-view.** Whether the user hid their own tile, for a host that lets them (the meeting room).
+ *
+ * The realtime call keeps its channels' layout this way and the meeting room its participants' tiles, so both save the
+ * same form ({@link SerializePlacementMoves}, {@link SerializePipRects}, {@link SerializeSelfViewHidden}) and read it
+ * back tolerantly, through {@link MediaLayoutPrefs} under each host's own keys.
+ *
+ * @module @memberjunction/ai-realtime-client/media
+ */
+import { type MediaPipRect, type MediaPlacementMove } from './model.js';
+/** Adds a move at the end, dropping the surface's earlier move, so the list keeps one move per surface in order. */
+export declare function RecordPlacementMove(moves: readonly MediaPlacementMove[], move: MediaPlacementMove): MediaPlacementMove[];
+/**
+ * The moves without any move to the stage: whatever the user put there goes back to its default. The stage goes to the
+ * newest move there, so a host whose "unpin" should hand the stage back to its default, not to an earlier move, drops
+ * the stage moves before recording the next one.
+ */
+export declare function WithoutStageMoves(moves: readonly MediaPlacementMove[]): MediaPlacementMove[];
+/** Reads saved moves. Tolerant: a value that is not a list reads as no moves, and a malformed entry is skipped. */
+export declare function ParsePlacementMoves(raw: string | null | undefined): MediaPlacementMove[];
+/** The saved form of a list of moves. */
+export declare function SerializePlacementMoves(moves: readonly MediaPlacementMove[]): string;
+/** Adds a box at the end, dropping the surface's earlier box, so the boxes the user moved most recently come last. */
+export declare function RecordPipRect(rects: ReadonlyMap<string, MediaPipRect>, key: string, rect: MediaPipRect): Map<string, MediaPipRect>;
+/**
+ * Reads saved picture-in-picture boxes, by surface key. Tolerant: a value that is not an object reads as none, and a box
+ * that is not four fractions with a size is skipped.
+ */
+export declare function ParsePipRects(raw: string | null | undefined): Map<string, MediaPipRect>;
+/** The saved form of picture-in-picture boxes, by surface key. */
+export declare function SerializePipRects(rects: ReadonlyMap<string, MediaPipRect>): string;
+/**
+ * Reads whether the user hid their self-view. Tolerant: only a saved `true` hides it; nothing saved, `false` or anything
+ * else shows it.
+ */
+export declare function ParseSelfViewHidden(raw: string | null | undefined): boolean;
+/** The saved form of whether the user hid their self-view: JSON `true` or `false`. */
+export declare function SerializeSelfViewHidden(hidden: boolean): string;
+/** A per-user settings store: MJ's `UserInfoEngine` is one, or anything with the same two methods. */
+export interface MediaLayoutSettings {
+    /** The text saved under a key, or `undefined` when there is none. */
+    GetSetting(key: string): string | undefined;
+    /** Saves text under a key; the store may wait for a burst of changes to end. */
+    SetSettingDebounced(key: string, value: string): void;
+}
+/** The keys a host saves its layout under, so two hosts never overwrite each other's. */
+export interface MediaLayoutKeys {
+    /** Where the moves go. */
+    Moves: string;
+    /** Where the picture-in-picture boxes go. */
+    PipRects: string;
+    /** Where whether the user hid their self-view goes. A host with no Hide on the user's own tile leaves it out. */
+    SelfViewHidden?: string;
+}
+/** How many moves, and how many boxes, a saved layout keeps: the newest. The oldest go first. */
+export declare const MEDIA_LAYOUT_SAVED_LIMIT = 50;
+/**
+ * A host's saved layout: its moves, its picture-in-picture boxes and whether the user hid their self-view, in a per-user
+ * settings store under the host's own keys. Reading treats a store that is not ready (it throws) as nothing saved;
+ * writing skips one, or one that fails to save, so the layout then lasts for this session only. Writing keeps the newest
+ * {@link MEDIA_LAYOUT_SAVED_LIMIT} moves and boxes.
+ */
+export declare class MediaLayoutPrefs {
+    private readonly store;
+    private readonly keys;
+    /**
+     * @param store The settings store, looked up each time it is used, since a host's store may be ready only later.
+     * @param keys Where this host's layout goes.
+     */
+    constructor(store: () => MediaLayoutSettings, keys: MediaLayoutKeys);
+    /** The saved moves, oldest first; none when nothing is saved or the store is not ready. */
+    LoadMoves(): MediaPlacementMove[];
+    /** The saved boxes, by surface key; none when nothing is saved or the store is not ready. */
+    LoadPipRects(): Map<string, MediaPipRect>;
+    /** Saves the moves, the newest {@link MEDIA_LAYOUT_SAVED_LIMIT} of them. */
+    SaveMoves(moves: readonly MediaPlacementMove[]): void;
+    /** Saves the boxes, the newest {@link MEDIA_LAYOUT_SAVED_LIMIT} of them (the last in the map's order). */
+    SavePipRects(rects: ReadonlyMap<string, MediaPipRect>): void;
+    /**
+     * Whether the user hid their self-view: shown when nothing usable is saved, the store is not ready, or the host keeps
+     * no self-view setting (it named no key for it).
+     */
+    LoadSelfViewHidden(): boolean;
+    /** Saves whether the user hid their self-view; nothing, for a host that keeps no self-view setting. */
+    SaveSelfViewHidden(hidden: boolean): void;
+    private read;
+    private write;
+}
+//# sourceMappingURL=mediaLayout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mediaLayout.d.ts","sourceRoot":"","sources":["../../src/media/mediaLayout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAoB,KAAK,YAAY,EAAuB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE5G,oHAAoH;AACpH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,EAAE,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAExH;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAE5F;AAED,mHAAmH;AACnH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,EAAE,CAaxF;AAED,yCAAyC;AACzC,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAEpF;AAED,sHAAsH;AACtH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAKlI;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAmBvF;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE3E;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAE/D;AAED,sGAAsG;AACtG,MAAM,WAAW,mBAAmB;IAChC,qEAAqE;IACrE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACzD;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC5B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,iHAAiH;IACjH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iGAAiG;AACjG,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;GAKG;AACH,qBAAa,gBAAgB;IAMrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANzB;;;OAGG;gBAEkB,KAAK,EAAE,MAAM,mBAAmB,EAChC,IAAI,EAAE,eAAe;IAG1C,2FAA2F;IACpF,SAAS,IAAI,kBAAkB,EAAE;IAIxC,6FAA6F;IACtF,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC;IAIhD,4EAA4E;IACrE,SAAS,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI;IAI5D,0GAA0G;IACnG,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI;IAInE;;;OAGG;IACI,kBAAkB,IAAI,OAAO;IAKpC,uGAAuG;IAChG,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAOhD,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,KAAK;CAOhB"}

package/dist/media/mediaLayout.js

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview MEDIA LAYOUT: the user's layout of a media stage as a host keeps and saves it.
+ * - **Moves.** One move per surface, oldest first: the list `LayoutMediaStage` and `ResolveSurfacePlacements` read.
+ *   {@link RecordPlacementMove} keeps it that way, and {@link WithoutStageMoves} hands the stage back to its default.
+ * - **Boxes.** Where the user put each picture-in-picture box, by surface key, as fractions of the stage.
+ * - **Self-view.** Whether the user hid their own tile, for a host that lets them (the meeting room).
+ *
+ * The realtime call keeps its channels' layout this way and the meeting room its participants' tiles, so both save the
+ * same form ({@link SerializePlacementMoves}, {@link SerializePipRects}, {@link SerializeSelfViewHidden}) and read it
+ * back tolerantly, through {@link MediaLayoutPrefs} under each host's own keys.
+ *
+ * @module @memberjunction/ai-realtime-client/media
+ */
+import { MEDIA_PLACEMENTS } from './model.js';
+/** Adds a move at the end, dropping the surface's earlier move, so the list keeps one move per surface in order. */
+export function RecordPlacementMove(moves, move) {
+    return [...moves.filter((existing) => existing.SurfaceKey !== move.SurfaceKey), move];
+}
+/**
+ * The moves without any move to the stage: whatever the user put there goes back to its default. The stage goes to the
+ * newest move there, so a host whose "unpin" should hand the stage back to its default, not to an earlier move, drops
+ * the stage moves before recording the next one.
+ */
+export function WithoutStageMoves(moves) {
+    return moves.filter((move) => move.Placement !== 'stage');
+}
+/** Reads saved moves. Tolerant: a value that is not a list reads as no moves, and a malformed entry is skipped. */
+export function ParsePlacementMoves(raw) {
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter(isMove).map((move) => ({ SurfaceKey: move.SurfaceKey, Placement: move.Placement }));
+    }
+    catch {
+        return [];
+    }
+}
+/** The saved form of a list of moves. */
+export function SerializePlacementMoves(moves) {
+    return JSON.stringify(moves.map((move) => ({ SurfaceKey: move.SurfaceKey, Placement: move.Placement })));
+}
+/** Adds a box at the end, dropping the surface's earlier box, so the boxes the user moved most recently come last. */
+export function RecordPipRect(rects, key, rect) {
+    const next = new Map(rects);
+    next.delete(key);
+    next.set(key, rect);
+    return next;
+}
+/**
+ * Reads saved picture-in-picture boxes, by surface key. Tolerant: a value that is not an object reads as none, and a box
+ * that is not four fractions with a size is skipped.
+ */
+export function ParsePipRects(raw) {
+    const rects = new Map();
+    if (!raw) {
+        return rects;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return rects;
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (isPipRect(value)) {
+                rects.set(key, { X: value.X, Y: value.Y, W: value.W, H: value.H });
+            }
+        }
+        return rects;
+    }
+    catch {
+        return rects;
+    }
+}
+/** The saved form of picture-in-picture boxes, by surface key. */
+export function SerializePipRects(rects) {
+    return JSON.stringify(Object.fromEntries([...rects].map(([key, rect]) => [key, { X: rect.X, Y: rect.Y, W: rect.W, H: rect.H }])));
+}
+/**
+ * Reads whether the user hid their self-view. Tolerant: only a saved `true` hides it; nothing saved, `false` or anything
+ * else shows it.
+ */
+export function ParseSelfViewHidden(raw) {
+    return raw === SerializeSelfViewHidden(true);
+}
+/** The saved form of whether the user hid their self-view: JSON `true` or `false`. */
+export function SerializeSelfViewHidden(hidden) {
+    return JSON.stringify(hidden);
+}
+/** How many moves, and how many boxes, a saved layout keeps: the newest. The oldest go first. */
+export const MEDIA_LAYOUT_SAVED_LIMIT = 50;
+/**
+ * A host's saved layout: its moves, its picture-in-picture boxes and whether the user hid their self-view, in a per-user
+ * settings store under the host's own keys. Reading treats a store that is not ready (it throws) as nothing saved;
+ * writing skips one, or one that fails to save, so the layout then lasts for this session only. Writing keeps the newest
+ * {@link MEDIA_LAYOUT_SAVED_LIMIT} moves and boxes.
+ */
+export class MediaLayoutPrefs {
+    /**
+     * @param store The settings store, looked up each time it is used, since a host's store may be ready only later.
+     * @param keys Where this host's layout goes.
+     */
+    constructor(store, keys) {
+        this.store = store;
+        this.keys = keys;
+    }
+    /** The saved moves, oldest first; none when nothing is saved or the store is not ready. */
+    LoadMoves() {
+        return ParsePlacementMoves(this.read(this.keys.Moves));
+    }
+    /** The saved boxes, by surface key; none when nothing is saved or the store is not ready. */
+    LoadPipRects() {
+        return ParsePipRects(this.read(this.keys.PipRects));
+    }
+    /** Saves the moves, the newest {@link MEDIA_LAYOUT_SAVED_LIMIT} of them. */
+    SaveMoves(moves) {
+        this.write(this.keys.Moves, SerializePlacementMoves(moves.slice(-MEDIA_LAYOUT_SAVED_LIMIT)));
+    }
+    /** Saves the boxes, the newest {@link MEDIA_LAYOUT_SAVED_LIMIT} of them (the last in the map's order). */
+    SavePipRects(rects) {
+        this.write(this.keys.PipRects, SerializePipRects(new Map([...rects].slice(-MEDIA_LAYOUT_SAVED_LIMIT))));
+    }
+    /**
+     * Whether the user hid their self-view: shown when nothing usable is saved, the store is not ready, or the host keeps
+     * no self-view setting (it named no key for it).
+     */
+    LoadSelfViewHidden() {
+        const key = this.keys.SelfViewHidden;
+        return key !== undefined && ParseSelfViewHidden(this.read(key));
+    }
+    /** Saves whether the user hid their self-view; nothing, for a host that keeps no self-view setting. */
+    SaveSelfViewHidden(hidden) {
+        const key = this.keys.SelfViewHidden;
+        if (key !== undefined) {
+            this.write(key, SerializeSelfViewHidden(hidden));
+        }
+    }
+    read(key) {
+        try {
+            return this.store().GetSetting(key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    write(key, value) {
+        try {
+            this.store().SetSettingDebounced(key, value);
+        }
+        catch {
+            // The store is not ready, or failed to save: the layout lasts for this session only.
+        }
+    }
+}
+function isMove(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'SurfaceKey' in value &&
+        typeof value.SurfaceKey === 'string' &&
+        'Placement' in value &&
+        isPlacement(value.Placement));
+}
+function isPlacement(value) {
+    return typeof value === 'string' && MEDIA_PLACEMENTS.includes(value);
+}
+function isPipRect(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'X' in value &&
+        'Y' in value &&
+        'W' in value &&
+        'H' in value &&
+        isFraction(value.X) &&
+        isFraction(value.Y) &&
+        isFraction(value.W) &&
+        isFraction(value.H) &&
+        value.W > 0 &&
+        value.H > 0);
+}
+function isFraction(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+//# sourceMappingURL=mediaLayout.js.map

package/dist/media/mediaLayout.js.map

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