@trycua/cua 0.2.0

package/dist/spaces/host.js

@@ -0,0 +1,154 @@
+/**
+ * `@trycua/cua/spaces/host` — the host presentation adapter. **Explicitly unstable.**
+ *
+ * This is the one thing the SDK itself cannot do: put a Space on
+ * the *operator's own Mac desktop* — pinned as picture-in-picture, opened in a
+ * viewer window, or a single Space window streamed back bidirectionally over
+ * rcdp.
+ *
+ * It talks to the loopback control server inside the Cua Spaces desktop app,
+ * discovered through `$CUA_HOME/spaces-control.json` (default `~/.cua`; `{port, token}`). That means
+ * all of the following, and you should assume all of it will change:
+ *
+ *  - it only works on the machine where the app is running, as the user who
+ *    owns that home directory;
+ *  - the port is ephemeral and the token is regenerated on every app launch;
+ *  - a Local Space's rcdp token rotates on every rcdpd restart, so a token read
+ *    once and cached will start failing — `streamWindow` takes a fresh one;
+ *  - the control server resolves `local:<vm>` ids only. `pin` and `openViewer`
+ *    with any other id are rejected by the app with HTTP 400, and this adapter
+ *    says so rather than reporting success.
+ *
+ * Every method throws `host_unavailable` when the app is not running. None of
+ * them degrades to a silent no-op — a `forget_rcdp_token` with zero callers is
+ * exactly the kind of thing this codebase has shipped before.
+ */
+import { SpacesError, excerpt } from './errors.js';
+/** `$CUA_HOME` when set and non-empty, else `~/.cua` (the Rust core's rule). */
+export function cuaHome(home, env = globalThis.process?.env ?? {}) {
+    const set = env.CUA_HOME;
+    return set ? set : `${home.replace(/[\\/]+$/, '')}/.cua`;
+}
+/** Read `{port, token}` from the app's control file. */
+export async function readControlEndpoint(controlFile) {
+    const { readFile } = await import('node:fs/promises');
+    const { homedir } = await import('node:os');
+    const { join } = await import('node:path');
+    const path = controlFile ?? join(cuaHome(homedir()), 'spaces-control.json');
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (cause) {
+        throw new SpacesError('host_unavailable', `the Cua Spaces app does not appear to be running: cannot read ${path}. ` +
+            `Host presentation (PiP, viewer, window stream) needs the desktop app on this machine.`, { cause });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw SpacesError.protocol(`${path} is not valid JSON`, { cause, detail: excerpt(raw, 120) });
+    }
+    const record = parsed;
+    if (typeof record.port !== 'number' || typeof record.token !== 'string' || !record.token) {
+        throw SpacesError.protocol(`${path} does not contain a usable {port, token}`);
+    }
+    return { port: record.port, token: record.token };
+}
+export class HostPresentation {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Pin a Local Space as picture-in-picture on this Mac's desktop. */
+    async pin(spaceId) {
+        this.assertLocal(spaceId, 'pin');
+        await this.post('/pip/pin', { space_id: spaceId });
+    }
+    async unpin(spaceId) {
+        await this.post('/pip/unpin', { space_id: spaceId });
+    }
+    /** Open the full viewer window for a Local Space. */
+    async openViewer(spaceId) {
+        this.assertLocal(spaceId, 'openViewer');
+        await this.post('/viewer/open', { space_id: spaceId });
+    }
+    /**
+     * Stream one window of a Local Space back to a bidirectional window here.
+     *
+     * `rcdpToken` must be read fresh: a Local Space's rcdp token rotates on every
+     * rcdpd restart, so a cached one silently stops working.
+     *
+     * `replica: true` opens an *additional* stream for the same target rather
+     * than focusing the existing one. Note the real limit: only one page per app
+     * can hardware-decode H.264, so a second concurrent stream falls back to an
+     * uncompressed codec and is visibly heavier.
+     */
+    async streamWindow(input) {
+        this.assertLocal(input.spaceId, 'streamWindow');
+        if (!input.windowId)
+            throw SpacesError.usage('streamWindow requires a windowId');
+        if (!input.rcdpToken) {
+            throw SpacesError.usage('streamWindow requires a fresh rcdpToken; the token rotates on every rcdpd restart');
+        }
+        await this.post('/window/stream', {
+            space_id: input.spaceId,
+            window_id: input.windowId,
+            rcdp_token: input.rcdpToken,
+            app_name: input.appName ?? '',
+            title: input.title ?? '',
+            replica: input.replica ?? false,
+        });
+    }
+    /** Is the desktop app reachable right now? */
+    async available() {
+        try {
+            await readControlEndpoint(this.options.controlFile);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    assertLocal(spaceId, method) {
+        if (!spaceId.startsWith('local:') && !spaceId.startsWith('space://local/')) {
+            throw SpacesError.usage(`${method} accepts a Local Space id (local:<vm>, or legacy space://local/<vm>) only — ` +
+                `the app's control server rejects other ids with HTTP 400. Stream any Space with ` +
+                `space.openStream() / space.attachStream() instead.`);
+        }
+    }
+    async post(path, body) {
+        const endpoint = await readControlEndpoint(this.options.controlFile);
+        const doFetch = this.options.fetch ?? globalThis.fetch;
+        const url = `http://127.0.0.1:${endpoint.port}${path}`;
+        let response;
+        try {
+            response = await doFetch(url, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${endpoint.token}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (cause) {
+            throw new SpacesError('host_unavailable', `the Cua Spaces control server at 127.0.0.1:${endpoint.port} did not answer; the app may ` +
+                `have restarted, which also invalidates the token in the control file`, { cause });
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            throw new SpacesError('http', `POST ${path} -> HTTP ${response.status}`, {
+                status: response.status,
+                target: path,
+                detail: excerpt(text, 200),
+            });
+        }
+        // The control server answers `{"ok":true}`. Anything else means the route
+        // did not do what we asked, and reporting success would be a lie.
+        if (!text.includes('"ok"') && !text.includes('"active"')) {
+            throw SpacesError.protocol(`POST ${path} returned HTTP 200 without an ok acknowledgement, so the effect is unproven`, { detail: excerpt(text, 200) });
+        }
+    }
+}

package/dist/spaces/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@trycua/cua/spaces`: Cua Spaces for Node, on the native cua SDK.
+ *
+ * ```ts
+ * import { embedded } from "@trycua/cua"
+ * import { approve, startThread, SpaceSendFileOptions } from "@trycua/cua/spaces"
+ *
+ * const spaces = embedded().spaces()               // or connect().spaces() (cua daemon)
+ * const info = await spaces.add("http://10.0.0.5:3211", token, "dev")
+ * const space = await spaces.space(info.id)
+ * console.log((await space.bash("uname -a", undefined)).stdout)
+ * await space.sendFile("./report.pdf", SpaceSendFileOptions.create({}))
+ * await space.teleport("firefox", undefined, approve((manifest) => ({
+ *   include: undefined, acknowledgeSensitive: true,       // after asking a human
+ * })))
+ * const bot = await startThread(spaces, {
+ *   agent: "claude-code", prompt: "summarise the open PRs",
+ *   placement: { kind: "shared", space, acknowledgeNoIsolation: true },
+ * })
+ * for await (const e of bot.events({ maxPolls: 60 })) if (e.kind === "text") console.log(e.text)
+ * ```
+ *
+ * Every call is the Rust `cua-spaces` implementation (embedded, or in
+ * `cua daemon` through `SpaceService`); `spaces.create({ on })` makes a
+ * Space locally or in the cloud. Webviews and browsers, which cannot
+ * load the native binding, use `@trycua/cua/spaces/transport` (MCP over the
+ * daemon's `/mcp` or a Tauri `invoke`) instead.
+ */
+import { type TeleportApprover, type TeleportDecision, type TeleportManifest } from "../native/index.js";
+export { AgentActionReport, AgentRunStatus, AgentStartReport, PresenceCursor, PresenceIdentity, Space, SpaceCreateOptions, SpaceCreateResult, SpacePresence, SpaceSendFileOptions, SpaceStreamOptions, SpaceStreamSession, Spaces, TeleportDecision, spacesToolMethods, } from "../native/index.js";
+export type { AudioPacket, AudioSink, FrameSink, MediaEvent, MediaSessionLike, MediaStats, PresenceEvent, PresenceMember, PresenceParticipant, SpaceBashResult, SpaceHotspotStatus, SpaceInfo, SpaceLike, SpacePresenceLike, SpaceSendFileReport, SpaceSentFile, SpaceStreamSessionLike, SpaceStreamStats, SpaceStreamTicket, SpaceToolInfo, SpaceToolResult, SpaceTransferReport, SpaceWindow, SpaceWriteReport, SpacesLike, SpacesToolMethod, TeleportApprover, TeleportItem, TeleportManifest, TeleportReceipt, VideoFrame, } from "../native/index.js";
+export { SpacesError, isSpacesError, excerpt, toSpacesError, wrapErrors } from "./errors.js";
+export type { SpacesErrorCode, SpacesErrorOptions } from "./errors.js";
+export { TranscriptAdapter, detectApproval } from "./events.js";
+export type { AgentStatus, ApprovalRequestEvent, ErrorEvent, FileEvent, ImageEvent, LinkEvent, StateEvent, TextEvent, ThreadEvent, ThreadEventKind, ThreadStatus, } from "./events.js";
+export { AGENT_IDS, SETTLED, SpaceTurnLock, Thread, adoptThread, lockFor, startThread, validatePlacement, } from "./thread.js";
+export type { AgentId, EventOptions, StartThreadOptions, ThreadPlacement, Turn } from "./thread.js";
+export { CURSOR_ART, CURSOR_SHAPES, CursorSmoother, DATAGRAM_DELAY_MS, PRESENCE_FALLBACK_COLOR, PRESENCE_PALETTE, PresenceRoster, PresenceView, STREAM_DELAY_MS, cursorArt, cursorArtSvg, idleAlpha, isCursorShape, agentIdentity, presenceColor, presenceTextColor, waitForPresence, } from "./presence.js";
+export type { CursorArtShape, CursorShapeName, PresenceDrawable, PresenceEntry } from "./presence.js";
+export * from "./routines.js";
+export * from "./groups.js";
+/**
+ * A {@link TeleportApprover} from a function. The function sees exactly what
+ * would leave this machine and returns the human's decision, or `undefined`
+ * to cancel (the teleport then fails with `TeleportRefused`). It runs on a
+ * worker thread of the SDK and must be synchronous.
+ */
+export declare function approve(decide: (manifest: TeleportManifest) => TeleportDecision | undefined): TeleportApprover;

package/dist/spaces/index.js

@@ -0,0 +1,44 @@
+/**
+ * `@trycua/cua/spaces`: Cua Spaces for Node, on the native cua SDK.
+ *
+ * ```ts
+ * import { embedded } from "@trycua/cua"
+ * import { approve, startThread, SpaceSendFileOptions } from "@trycua/cua/spaces"
+ *
+ * const spaces = embedded().spaces()               // or connect().spaces() (cua daemon)
+ * const info = await spaces.add("http://10.0.0.5:3211", token, "dev")
+ * const space = await spaces.space(info.id)
+ * console.log((await space.bash("uname -a", undefined)).stdout)
+ * await space.sendFile("./report.pdf", SpaceSendFileOptions.create({}))
+ * await space.teleport("firefox", undefined, approve((manifest) => ({
+ *   include: undefined, acknowledgeSensitive: true,       // after asking a human
+ * })))
+ * const bot = await startThread(spaces, {
+ *   agent: "claude-code", prompt: "summarise the open PRs",
+ *   placement: { kind: "shared", space, acknowledgeNoIsolation: true },
+ * })
+ * for await (const e of bot.events({ maxPolls: 60 })) if (e.kind === "text") console.log(e.text)
+ * ```
+ *
+ * Every call is the Rust `cua-spaces` implementation (embedded, or in
+ * `cua daemon` through `SpaceService`); `spaces.create({ on })` makes a
+ * Space locally or in the cloud. Webviews and browsers, which cannot
+ * load the native binding, use `@trycua/cua/spaces/transport` (MCP over the
+ * daemon's `/mcp` or a Tauri `invoke`) instead.
+ */
+export { AgentActionReport, AgentRunStatus, AgentStartReport, PresenceCursor, PresenceIdentity, Space, SpaceCreateOptions, SpaceCreateResult, SpacePresence, SpaceSendFileOptions, SpaceStreamOptions, SpaceStreamSession, Spaces, TeleportDecision, spacesToolMethods, } from "../native/index.js";
+export { SpacesError, isSpacesError, excerpt, toSpacesError, wrapErrors } from "./errors.js";
+export { TranscriptAdapter, detectApproval } from "./events.js";
+export { AGENT_IDS, SETTLED, SpaceTurnLock, Thread, adoptThread, lockFor, startThread, validatePlacement, } from "./thread.js";
+export { CURSOR_ART, CURSOR_SHAPES, CursorSmoother, DATAGRAM_DELAY_MS, PRESENCE_FALLBACK_COLOR, PRESENCE_PALETTE, PresenceRoster, PresenceView, STREAM_DELAY_MS, cursorArt, cursorArtSvg, idleAlpha, isCursorShape, agentIdentity, presenceColor, presenceTextColor, waitForPresence, } from "./presence.js";
+export * from "./routines.js";
+export * from "./groups.js";
+/**
+ * A {@link TeleportApprover} from a function. The function sees exactly what
+ * would leave this machine and returns the human's decision, or `undefined`
+ * to cancel (the teleport then fails with `TeleportRefused`). It runs on a
+ * worker thread of the SDK and must be synchronous.
+ */
+export function approve(decide) {
+    return { approve: decide };
+}

package/dist/spaces/pip.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `@trycua/cua/spaces/pip`: picture-in-picture of a Space, for browsers and
+ * webviews. No native library, no Node imports.
+ *
+ * A PiP shows one {@link PipSource}: the whole desktop, or a single window
+ * from the Space's window list (`space.windows()`, streamed with
+ * `SpaceStreamOptions.windowId`). The stream itself is the caller's: whatever
+ * paints a canvas (WebCodecs over the media socket) is what the PiP shows.
+ *
+ * - In a browser, {@link PictureInPicture} opens the Document
+ *   Picture-in-Picture API when it exists (an always-on-top window holding a
+ *   live `<video>` of the canvas) and falls back to video picture-in-picture.
+ *   Browsers allow one PiP window at a time, so opening another source
+ *   replaces the current one.
+ * - In a desktop shell (Tauri and the like), open a small always-on-top
+ *   window per source: {@link pipWindowLabel} names it, {@link encodePipRoute}
+ *   tells its page what to stream and {@link parsePipRoute} reads that back.
+ *
+ * ```ts
+ * import { PictureInPicture, desktopSource, windowSource } from "@trycua/cua/spaces/pip"
+ *
+ * const pip = new PictureInPicture()
+ * button.onclick = () => pip.toggle(desktopSource, canvas, { title: "dev" })
+ * row.onclick = () => pip.open(windowSource(w), windowCanvas, { title: pipLabel(windowSource(w)) })
+ * ```
+ */
+/** What a PiP shows: the whole desktop or one window of the Space. */
+export type PipSource = {
+    kind: "desktop";
+} | {
+    kind: "window";
+    windowId: string;
+    app: string;
+    title: string;
+};
+export declare const desktopSource: PipSource;
+/** A window source from a window-list row (`SpaceWindow` or the core's JSON). */
+export declare function windowSource(w: {
+    windowId?: string;
+    window_id?: string;
+    appName?: string;
+    app_name?: string;
+    app?: string;
+    title?: string;
+}): PipSource;
+/** A stable key: `desktop`, or `window:<id>`. */
+export declare function pipKey(source: PipSource): string;
+/** One line for a title bar or a list row. */
+export declare function pipLabel(source: PipSource, spaceName?: string): string;
+/**
+ * A window label every shell accepts (`[A-Za-z0-9_-]`, bounded): `pip-desktop`,
+ * or `pip-w-` plus the window id with anything else replaced. Distinct ids
+ * that collide after replacement get a short hash suffix.
+ */
+export declare function pipWindowLabel(source: PipSource): string;
+/** The PiP page's route: `pip=desktop`, or `pip=window&id=…&app=…&title=…`. */
+export declare function encodePipRoute(source: PipSource): string;
+/** Reads {@link encodePipRoute} from a hash or query (`#…`/`?…` allowed); null when absent. */
+export declare function parsePipRoute(route: string): PipSource | null;
+/** Fits a `width`×`height` picture into a PiP whose long edge is `longEdge`. */
+export declare function pipSize(width: number, height: number, longEdge?: number): {
+    width: number;
+    height: number;
+};
+/** `document`: Document Picture-in-Picture; `video`: video PiP; `none`: neither. */
+export type PipMode = "document" | "video" | "none";
+interface DocumentPipApi {
+    requestWindow(options?: {
+        width?: number;
+        height?: number;
+    }): Promise<Window>;
+    window?: Window | null;
+}
+/** The window-like object {@link PictureInPicture} needs (a real `window` in a page). */
+export interface PipHostWindow {
+    document: Document;
+    documentPictureInPicture?: DocumentPipApi;
+}
+/** Which PiP this page can open. */
+export declare function pipSupport(win?: PipHostWindow | undefined): PipMode;
+export interface PipOpenOptions {
+    /** The PiP's title (Document PiP only; video PiP has none). */
+    title?: string;
+    /** Initial size; defaults to the canvas fitted by {@link pipSize}. */
+    width?: number;
+    height?: number;
+}
+/** An open PiP. */
+export interface PipHandle {
+    readonly mode: Exclude<PipMode, "none">;
+    readonly source: PipSource;
+    /** The Document PiP window, when that is the mode. */
+    readonly window: Window | null;
+    /** Resolves once the PiP is closed, by {@link close} or by the user. */
+    readonly closed: Promise<void>;
+    close(): void;
+}
+export interface PictureInPictureOptions {
+    /** The page's window (default: `globalThis`). */
+    window?: PipHostWindow;
+    /** Frames per second of the canvas capture (default 30). */
+    fps?: number;
+}
+/**
+ * One PiP at a time, of the desktop or of a window. The canvas keeps being
+ * painted by its stream; the PiP shows a live capture of it, so nothing moves
+ * out of the page and closing the PiP never stops the stream.
+ */
+export declare class PictureInPicture {
+    #private;
+    constructor(options?: PictureInPictureOptions);
+    get mode(): PipMode;
+    /** What is in the PiP now, or null. */
+    get current(): PipSource | null;
+    /** Whether `source` is what the PiP shows. */
+    isOpen(source: PipSource): boolean;
+    /** Called with the new source (or null) on every open and close. */
+    subscribe(fn: (source: PipSource | null) => void): () => void;
+    /**
+     * Opens `source` from `canvas`, replacing any open PiP. Call it from the
+     * click handler: browsers only open a PiP on a user gesture.
+     */
+    open(source: PipSource, canvas: HTMLCanvasElement, options?: PipOpenOptions): Promise<PipHandle>;
+    /** Opens `source`, or closes it when it is what the PiP shows. */
+    toggle(source: PipSource, canvas: HTMLCanvasElement, options?: PipOpenOptions): Promise<PipHandle | null>;
+    close(): void;
+}
+export {};

package/dist/spaces/pip.js

@@ -0,0 +1,250 @@
+/**
+ * `@trycua/cua/spaces/pip`: picture-in-picture of a Space, for browsers and
+ * webviews. No native library, no Node imports.
+ *
+ * A PiP shows one {@link PipSource}: the whole desktop, or a single window
+ * from the Space's window list (`space.windows()`, streamed with
+ * `SpaceStreamOptions.windowId`). The stream itself is the caller's: whatever
+ * paints a canvas (WebCodecs over the media socket) is what the PiP shows.
+ *
+ * - In a browser, {@link PictureInPicture} opens the Document
+ *   Picture-in-Picture API when it exists (an always-on-top window holding a
+ *   live `<video>` of the canvas) and falls back to video picture-in-picture.
+ *   Browsers allow one PiP window at a time, so opening another source
+ *   replaces the current one.
+ * - In a desktop shell (Tauri and the like), open a small always-on-top
+ *   window per source: {@link pipWindowLabel} names it, {@link encodePipRoute}
+ *   tells its page what to stream and {@link parsePipRoute} reads that back.
+ *
+ * ```ts
+ * import { PictureInPicture, desktopSource, windowSource } from "@trycua/cua/spaces/pip"
+ *
+ * const pip = new PictureInPicture()
+ * button.onclick = () => pip.toggle(desktopSource, canvas, { title: "dev" })
+ * row.onclick = () => pip.open(windowSource(w), windowCanvas, { title: pipLabel(windowSource(w)) })
+ * ```
+ */
+export const desktopSource = Object.freeze({ kind: "desktop" });
+/** A window source from a window-list row (`SpaceWindow` or the core's JSON). */
+export function windowSource(w) {
+    return {
+        kind: "window",
+        windowId: String(w.windowId ?? w.window_id ?? ""),
+        app: String(w.appName ?? w.app_name ?? w.app ?? ""),
+        title: String(w.title ?? ""),
+    };
+}
+/** A stable key: `desktop`, or `window:<id>`. */
+export function pipKey(source) {
+    return source.kind === "desktop" ? "desktop" : `window:${source.windowId}`;
+}
+/** One line for a title bar or a list row. */
+export function pipLabel(source, spaceName = "") {
+    if (source.kind === "desktop")
+        return spaceName || "Desktop";
+    if (!source.title)
+        return source.app || "Window";
+    if (!source.app || source.title.includes(source.app))
+        return source.title;
+    return `${source.app} · ${source.title}`;
+}
+/**
+ * A window label every shell accepts (`[A-Za-z0-9_-]`, bounded): `pip-desktop`,
+ * or `pip-w-` plus the window id with anything else replaced. Distinct ids
+ * that collide after replacement get a short hash suffix.
+ */
+export function pipWindowLabel(source) {
+    if (source.kind === "desktop")
+        return "pip-desktop";
+    const clean = source.windowId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 48);
+    const suffix = clean === source.windowId ? "" : `-${hash(source.windowId)}`;
+    return `pip-w-${clean}${suffix}`;
+}
+function hash(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/** The PiP page's route: `pip=desktop`, or `pip=window&id=…&app=…&title=…`. */
+export function encodePipRoute(source) {
+    const p = new URLSearchParams();
+    if (source.kind === "desktop")
+        p.set("pip", "desktop");
+    else {
+        p.set("pip", "window");
+        p.set("id", source.windowId);
+        if (source.app)
+            p.set("app", source.app);
+        if (source.title)
+            p.set("title", source.title);
+    }
+    return p.toString();
+}
+/** Reads {@link encodePipRoute} from a hash or query (`#…`/`?…` allowed); null when absent. */
+export function parsePipRoute(route) {
+    const p = new URLSearchParams(route.replace(/^[#?]/, ""));
+    switch (p.get("pip")) {
+        case "desktop":
+            return desktopSource;
+        case "window": {
+            const id = p.get("id");
+            return id ? { kind: "window", windowId: id, app: p.get("app") ?? "", title: p.get("title") ?? "" } : null;
+        }
+        default:
+            return null;
+    }
+}
+/** Fits a `width`×`height` picture into a PiP whose long edge is `longEdge`. */
+export function pipSize(width, height, longEdge = 480) {
+    const w = width > 0 ? width : 16;
+    const h = height > 0 ? height : 9;
+    const scale = longEdge / Math.max(w, h);
+    return { width: Math.max(1, Math.round(w * scale)), height: Math.max(1, Math.round(h * scale)) };
+}
+/** Which PiP this page can open. */
+export function pipSupport(win = globalThis) {
+    if (!win?.document)
+        return "none";
+    if (win.documentPictureInPicture && typeof win.documentPictureInPicture.requestWindow === "function")
+        return "document";
+    return win.document.pictureInPictureEnabled ? "video" : "none";
+}
+/**
+ * One PiP at a time, of the desktop or of a window. The canvas keeps being
+ * painted by its stream; the PiP shows a live capture of it, so nothing moves
+ * out of the page and closing the PiP never stops the stream.
+ */
+export class PictureInPicture {
+    #win;
+    #fps;
+    #current = null;
+    #listeners = new Set();
+    constructor(options = {}) {
+        this.#win = options.window ?? globalThis;
+        this.#fps = options.fps ?? 30;
+    }
+    get mode() {
+        return pipSupport(this.#win);
+    }
+    /** What is in the PiP now, or null. */
+    get current() {
+        return this.#current?.source ?? null;
+    }
+    /** Whether `source` is what the PiP shows. */
+    isOpen(source) {
+        return this.#current !== null && pipKey(this.#current.source) === pipKey(source);
+    }
+    /** Called with the new source (or null) on every open and close. */
+    subscribe(fn) {
+        this.#listeners.add(fn);
+        return () => this.#listeners.delete(fn);
+    }
+    /**
+     * Opens `source` from `canvas`, replacing any open PiP. Call it from the
+     * click handler: browsers only open a PiP on a user gesture.
+     */
+    async open(source, canvas, options = {}) {
+        const win = this.#win;
+        const mode = pipSupport(win);
+        if (!win || mode === "none")
+            throw new Error("this browser has no picture-in-picture");
+        const size = options.width && options.height ? { width: options.width, height: options.height } : pipSize(canvas.width, canvas.height);
+        // The PiP being replaced closes quietly: listeners see the new source,
+        // not a null in between.
+        const previous = this.#current;
+        this.#current = null;
+        let pipWindow = null;
+        try {
+            // Document PiP first, before any other await: it needs the gesture.
+            if (mode === "document")
+                pipWindow = await win.documentPictureInPicture.requestWindow(size);
+        }
+        catch (e) {
+            this.#current = previous;
+            throw e;
+        }
+        previous?.close();
+        const stream = canvas.captureStream(this.#fps);
+        const doc = pipWindow?.document ?? win.document;
+        const video = doc.createElement("video");
+        video.muted = true;
+        video.autoplay = true;
+        video.playsInline = true;
+        video.srcObject = stream;
+        let resolveClosed = () => { };
+        const closed = new Promise((r) => (resolveClosed = r));
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            for (const t of stream.getTracks())
+                t.stop();
+            video.srcObject = null;
+            if (this.#current === handle) {
+                this.#current = null;
+                this.#emit(null);
+            }
+            resolveClosed();
+        };
+        const handle = {
+            mode: mode,
+            source,
+            window: pipWindow,
+            closed,
+            close: () => {
+                if (done)
+                    return;
+                if (pipWindow)
+                    pipWindow.close();
+                else if (win.document.pictureInPictureElement === video)
+                    void win.document.exitPictureInPicture?.().catch(() => { });
+                finish();
+            },
+        };
+        if (pipWindow) {
+            pipWindow.document.title = options.title ?? pipLabel(source);
+            const style = pipWindow.document.createElement("style");
+            style.textContent =
+                "html,body{margin:0;height:100%;background:#000;overflow:hidden}video{display:block;width:100%;height:100%;object-fit:contain}";
+            pipWindow.document.head.append(style);
+            pipWindow.document.body.append(video);
+            pipWindow.addEventListener("pagehide", finish, { once: true });
+            await video.play().catch(() => { });
+        }
+        else {
+            video.addEventListener("leavepictureinpicture", finish, { once: true });
+            try {
+                await video.play();
+                await video.requestPictureInPicture();
+            }
+            catch (e) {
+                finish();
+                if (previous)
+                    this.#emit(null);
+                throw e;
+            }
+        }
+        this.#current = handle;
+        this.#emit(source);
+        return handle;
+    }
+    /** Opens `source`, or closes it when it is what the PiP shows. */
+    async toggle(source, canvas, options = {}) {
+        if (this.isOpen(source)) {
+            this.close();
+            return null;
+        }
+        return this.open(source, canvas, options);
+    }
+    close() {
+        this.#current?.close();
+    }
+    #emit(source) {
+        for (const fn of this.#listeners)
+            fn(source);
+    }
+}