cmux 0.3.6 → 0.4.0

package/dist/src/client.js

@@ -0,0 +1,799 @@
+import { decodeBase64, encodeBase64 } from "./base64.js";
+import { CmuxCommandError, CmuxConnectionError, CmuxError, CmuxProtocolError, CmuxTimeoutError, } from "./errors.js";
+export const DEFAULT_MAX_BUFFERED_EVENTS = 256;
+export const DEFAULT_MAX_ATTACH_ENCODED_CHARS = 16 * 1024 * 1024;
+export const TERMINAL_KEY_TEXT_MAX_BYTES = 4 * 1024;
+function validateViewportPaneWidth(width) {
+    if (typeof width !== "number"
+        || !Number.isFinite(width)
+        || width < 0.1
+        || width > 1.0) {
+        throw new CmuxProtocolError("viewport pane width must be between 0.1 and 1.0");
+    }
+}
+function layoutUndoUint(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new CmuxProtocolError(`layout undo ${field} is not a nonnegative integer`);
+    }
+    return value;
+}
+function decodeLayoutUndoResult(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new CmuxProtocolError("layout undo result is not an object");
+    }
+    const result = value;
+    const screen = layoutUndoUint(result.screen, "screen");
+    const revision = layoutUndoUint(result.revision, "revision");
+    if (result.undone === true
+        && (result.confirmation_required === undefined
+            || result.confirmation_required === false)) {
+        return { undone: true, screen, revision };
+    }
+    if (result.undone === false && result.confirmation_required === true) {
+        if (!Array.isArray(result.closes_panes)) {
+            throw new CmuxProtocolError("layout undo closes_panes is not an array");
+        }
+        return {
+            undone: false,
+            confirmation_required: true,
+            screen,
+            revision,
+            closes_panes: result.closes_panes.map((pane) => layoutUndoUint(pane, "pane ID")),
+        };
+    }
+    throw new CmuxProtocolError("layout undo result does not contain exactly one valid outcome");
+}
+function decodeResponseData(command, value) {
+    if (command === "undo-layout")
+        return decodeLayoutUndoResult(value);
+    return value;
+}
+function workspaceMutationResult(result) {
+    if ("workspace" in result
+        && "key" in result
+        && "workspace_revision" in result
+        && typeof result.workspace === "number"
+        && typeof result.key === "string"
+        && typeof result.workspace_revision === "number") {
+        return {
+            workspace: result.workspace,
+            key: result.key,
+            workspace_revision: result.workspace_revision,
+        };
+    }
+    throw new CmuxProtocolError("server returned an invalid workspace registry mutation");
+}
+function normalizeClientSizing(clients) {
+    return clients.map((client) => {
+        const fallback = client.size_participating ?? true;
+        if (client.sizes.every((size) => size.size_participating !== undefined))
+            return client;
+        return {
+            ...client,
+            sizes: client.sizes.map((size) => (size.size_participating === undefined
+                ? { ...size, size_participating: fallback }
+                : size)),
+        };
+    });
+}
+class MessageRouter {
+    transport;
+    pending = new Map();
+    eventHandlers = new Set();
+    terminalHandlers = new Set();
+    terminalError = null;
+    constructor(transport) {
+        this.transport = transport;
+        transport.onMessage((json) => this.receive(json));
+        transport.onError((error) => this.terminate(this.connectionError(error)));
+        transport.onClose(() => this.terminate(new CmuxConnectionError("session transport closed")));
+    }
+    send(request, timeoutMs) {
+        const key = this.idKey(request.id);
+        if (this.terminalError)
+            return Promise.reject(this.terminalError);
+        if (this.pending.has(key))
+            return Promise.reject(new CmuxProtocolError(`duplicate request id ${key}`));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(key);
+                reject(new CmuxTimeoutError("session did not respond"));
+            }, timeoutMs);
+            this.pending.set(key, { resolve, reject, timer });
+            try {
+                this.transport.send(JSON.stringify(request));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(key);
+                reject(this.connectionError(error));
+            }
+        });
+    }
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    onTerminal(handler) {
+        this.terminalHandlers.add(handler);
+        if (this.terminalError)
+            queueMicrotask(() => handler(this.terminalError));
+        return () => this.terminalHandlers.delete(handler);
+    }
+    receive(json) {
+        let value;
+        try {
+            value = JSON.parse(json);
+        }
+        catch (error) {
+            this.terminate(new CmuxProtocolError(`bad JSON from server: ${error.message}`));
+            return;
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            this.terminate(new CmuxProtocolError("server sent non-object JSON message"));
+            return;
+        }
+        const object = value;
+        if (typeof object.event === "string") {
+            for (const handler of this.eventHandlers)
+                handler(object);
+            return;
+        }
+        const key = object.id === undefined ? this.pending.keys().next().value : this.idKey(object.id);
+        if (key === undefined)
+            return;
+        const pending = this.pending.get(key);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pending.delete(key);
+        pending.resolve(object);
+    }
+    terminate(error) {
+        if (this.terminalError)
+            return;
+        this.terminalError = error;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        for (const handler of this.terminalHandlers)
+            handler(error);
+    }
+    idKey(id) {
+        return id === undefined ? "undefined" : JSON.stringify(id);
+    }
+    connectionError(error) {
+        if (error instanceof CmuxError)
+            return error;
+        return new CmuxConnectionError(error instanceof Error ? error.message : String(error));
+    }
+}
+/** A closeable async event stream with optional per-read timeouts. */
+export class CmuxStream {
+    timeoutMs;
+    cleanup;
+    maxBufferedEvents;
+    maxBufferedBytes;
+    retainedBytes;
+    buffered = [];
+    bufferedBytes = 0;
+    waiters = [];
+    closed = false;
+    endsAfterDrain = false;
+    terminalError = null;
+    constructor(timeoutMs, cleanup, maxBufferedEvents = DEFAULT_MAX_BUFFERED_EVENTS, maxBufferedBytes = Number.POSITIVE_INFINITY, retainedBytes = () => 0) {
+        this.timeoutMs = timeoutMs;
+        this.cleanup = cleanup;
+        this.maxBufferedEvents = maxBufferedEvents;
+        this.maxBufferedBytes = maxBufferedBytes;
+        this.retainedBytes = retainedBytes;
+    }
+    async next(timeoutMs = this.timeoutMs) {
+        if (this.buffered.length > 0) {
+            const event = this.buffered.shift();
+            this.bufferedBytes = Math.max(0, this.bufferedBytes - this.retainedBytes(event));
+            if (this.endsAfterDrain && this.buffered.length === 0)
+                this.finish();
+            return event;
+        }
+        if (this.terminalError)
+            throw this.terminalError;
+        if (this.closed)
+            throw new CmuxConnectionError("stream is closed");
+        const waiter = {
+            active: true,
+            resolve: () => undefined,
+            reject: () => undefined,
+        };
+        const event = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                waiter.active = false;
+                const index = this.waiters.indexOf(waiter);
+                if (index >= 0)
+                    this.waiters.splice(index, 1);
+                reject(new CmuxTimeoutError("stream did not produce an event"));
+            }, timeoutMs);
+            waiter.resolve = (value) => {
+                clearTimeout(timer);
+                resolve(value);
+            };
+            waiter.reject = (error) => {
+                clearTimeout(timer);
+                reject(error);
+            };
+            this.waiters.push(waiter);
+        });
+        if (this.endsAfterDrain && this.buffered.length === 0)
+            this.finish();
+        return event;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.buffered.length = 0;
+        this.bufferedBytes = 0;
+        this.finish();
+        this.rejectWaiters(new CmuxConnectionError("stream is closed"));
+    }
+    push(event, terminal = false) {
+        if (this.closed)
+            return;
+        let delivered = false;
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            if (!waiter.active)
+                continue;
+            waiter.resolve(event);
+            delivered = true;
+            break;
+        }
+        if (!delivered) {
+            if (this.buffered.length >= this.maxBufferedEvents) {
+                this.fail(new CmuxProtocolError("stream event buffer overflow"));
+                return;
+            }
+            const retainedBytes = this.retainedBytes(event);
+            if (retainedBytes > this.maxBufferedBytes - this.bufferedBytes) {
+                this.fail(new CmuxProtocolError(`stream buffered data exceeds ${this.maxBufferedBytes} bytes`));
+                return;
+            }
+            this.buffered.push(event);
+            this.bufferedBytes += retainedBytes;
+        }
+        if (terminal)
+            this.endsAfterDrain = true;
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        this.terminalError = error;
+        this.buffered.length = 0;
+        this.bufferedBytes = 0;
+        this.finish();
+        this.rejectWaiters(error);
+    }
+    get error() {
+        return this.terminalError;
+    }
+    async *[Symbol.asyncIterator]() {
+        try {
+            while (true) {
+                if (this.terminalError)
+                    throw this.terminalError;
+                if (this.closed)
+                    return;
+                yield await this.next();
+            }
+        }
+        finally {
+            this.close();
+        }
+    }
+    finish() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.cleanup();
+    }
+    rejectWaiters(error) {
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            if (waiter.active)
+                waiter.reject(error);
+        }
+    }
+}
+/** Promise-based typed client for any cmux JSON transport. */
+export class CmuxClient {
+    timeoutMs;
+    allowProtocolV6Attach;
+    maxBufferedEvents;
+    maxAttachEncodedChars;
+    transport;
+    router;
+    streamTransportFactory;
+    nextRequestId = 1;
+    identifiedProtocol = null;
+    identifiedCapabilities = new Set();
+    sharedSubscriptionActive = false;
+    constructor(options) {
+        this.transport = options.transport;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.allowProtocolV6Attach = options.allowProtocolV6Attach ?? true;
+        this.maxBufferedEvents = this.securityLimit("maxBufferedEvents", options.maxBufferedEvents, DEFAULT_MAX_BUFFERED_EVENTS);
+        this.maxAttachEncodedChars = this.securityLimit("maxAttachEncodedChars", options.maxAttachEncodedChars, DEFAULT_MAX_ATTACH_ENCODED_CHARS);
+        this.streamTransportFactory = options.streamTransportFactory;
+        this.router = new MessageRouter(this.transport);
+    }
+    async close() {
+        this.transport.close();
+    }
+    async sendRaw(obj) {
+        const payload = this.dropUndefined({ ...obj });
+        if (!("id" in payload))
+            payload.id = this.nextId();
+        return this.router.send(payload, this.timeoutMs);
+    }
+    async request(requestOrCommand, params) {
+        const request = typeof requestOrCommand === "string"
+            ? { cmd: requestOrCommand, ...(params ?? {}) }
+            : requestOrCommand;
+        const response = await this.sendRaw(request);
+        if (response.ok) {
+            return decodeResponseData(request.cmd, response.data);
+        }
+        throw new CmuxCommandError(response.error || "unknown error", response.id, response, response.error_code, response.error_delivery);
+    }
+    async identify() {
+        const result = await this.request("identify");
+        this.identifiedProtocol = result.protocol;
+        this.identifiedCapabilities = new Set(result.capabilities ?? []);
+        return result;
+    }
+    /** The protocol reported by the latest `identify()`, or null before identification. */
+    get protocol() { return this.identifiedProtocol; }
+    ping() { return this.request("ping"); }
+    setClientInfo(name, kind) {
+        return this.request("set-client-info", { name, kind });
+    }
+    async listClients() {
+        return normalizeClientSizing(await this.request("list-clients"));
+    }
+    detachClient(client) { return this.request("detach-client", { client }); }
+    async setClientSizing(surface, client, enabled) {
+        await this.requireProtocol(10, "set-client-sizing");
+        return this.request("set-client-sizing", { surface, client, enabled });
+    }
+    async useOnlyClientSizing(surface, client) {
+        await this.requireProtocol(10, "set-client-sizing");
+        return this.request("set-client-sizing", { surface, client, enabled: true, exclusive: true });
+    }
+    async useAllClientSizing(surface) {
+        await this.requireProtocol(10, "set-client-sizing");
+        return this.request("set-client-sizing", { surface, enabled: true });
+    }
+    reloadConfig() { return this.request("reload-config"); }
+    setWindowTitle(title) { return this.request("set-window-title", { title }); }
+    clearWindowTitle() { return this.request("clear-window-title"); }
+    listWorkspaces() { return this.request("list-workspaces"); }
+    listTerminals() { return this.request("list-terminals"); }
+    terminalEvents(afterRevision = 0) {
+        return this.request("terminal-events", { after_revision: afterRevision });
+    }
+    exportLayout(screen) { return this.request("export-layout", { screen }); }
+    applyLayout(layout, options = {}) {
+        return this.request("apply-layout", { ...options, layout });
+    }
+    async send(surface, options = {}) {
+        const legacyBytes = options.bytes instanceof Uint8Array ? encodeBase64(options.bytes) : options.bytes;
+        const bytes = "base64" in options ? options.base64 : legacyBytes;
+        return this.request("send", { surface, text: options.text, bytes, paste: options.paste });
+    }
+    async clearHistory(surface, fallbackKey) {
+        await this.requireCapability("clear-history-v1", "clear-history");
+        if (fallbackKey !== undefined) {
+            await this.requireCapability("clear-history-key-v1", "clear-history key fallback");
+            if (new TextEncoder().encode(fallbackKey.utf8).byteLength > TERMINAL_KEY_TEXT_MAX_BYTES) {
+                throw new TypeError("terminal key text exceeds the 4 KiB protocol limit");
+            }
+        }
+        return this.request("clear-history", { surface, fallback_key: fallbackKey });
+    }
+    readScreen(surface) { return this.request("read-screen", { surface }); }
+    readScrollback(surface, start, count) {
+        return this.request("read-scrollback", { surface, start, count });
+    }
+    sidebarPlugin(cols, rows, relaunch) {
+        return this.request("sidebar-plugin", { cols, rows, relaunch });
+    }
+    vtState(surface) { return this.request("vt-state", { surface }); }
+    resolveTerminal(terminalId) {
+        return this.request("resolve-terminal", { terminal_id: terminalId });
+    }
+    closeTerminal(terminalId, terminalIncarnation, options = {}) {
+        return this.request("close-terminal", {
+            ...options,
+            terminal_id: terminalId,
+            terminal_incarnation: terminalIncarnation,
+        });
+    }
+    newTab(options = {}) { return this.request("new-tab", options); }
+    newBrowserTab(url, options = {}) {
+        return this.request("new-browser-tab", { url, ...options });
+    }
+    newWorkspace(options = {}) { return this.request("new-workspace", options); }
+    async createWorkspace(options = {}) {
+        await this.requireCapability("workspace-registry-v1", "workspace registry");
+        return this.request("create-workspace", options);
+    }
+    async createTerminal(options) {
+        await this.requireCapability("workspace-registry-v1", "workspace registry");
+        return this.request("create-terminal", options);
+    }
+    moveTerminal(terminalId, workspaceKey, options = {}) {
+        return this.request("move-terminal", {
+            ...options,
+            terminal_id: terminalId,
+            workspace_key: workspaceKey,
+        });
+    }
+    newScreen(options = {}) { return this.request("new-screen", options); }
+    async newPane(pane, options = {}) {
+        await this.requireProtocol(9, "new-pane");
+        return this.request("new-pane", { pane, ...options });
+    }
+    async newPaneRight(pane, options = {}) {
+        if (options.width !== undefined && options.width !== null) {
+            validateViewportPaneWidth(options.width);
+        }
+        await this.requireCapability("viewport-splits-v1", "viewport panes");
+        return this.request("new-pane-right", { pane, ...options });
+    }
+    split(pane, dir, options = {}) {
+        return this.request("split", { pane, dir, ...options });
+    }
+    setRatio(pane, dir, ratio) {
+        return this.request("set-ratio", { pane, dir, ratio });
+    }
+    async setSplitRatio(split, ratio, options = {}) {
+        await this.requireProtocol(8, "set-split-ratio");
+        return this.request("set-split-ratio", { split, ratio, ...options });
+    }
+    async setViewportPaneWidth(pane, width, options = {}) {
+        validateViewportPaneWidth(width);
+        await this.requireCapability("viewport-column-resize-v1", "viewport pane resizing");
+        return this.request("set-viewport-pane-width", { pane, width, ...options });
+    }
+    async undoLayout(pane, confirmationRevision) {
+        await this.requireCapability("layout-undo-v1", "layout undo");
+        if (confirmationRevision === undefined) {
+            return this.request("undo-layout", { pane });
+        }
+        return this.request("undo-layout", {
+            pane,
+            revision: confirmationRevision,
+            confirm_close: true,
+        });
+    }
+    paneNeighbor(pane, dir) {
+        return this.request("pane-neighbor", { pane, dir });
+    }
+    focusDirection(dir, pane) {
+        return this.request("focus-direction", { pane, dir });
+    }
+    swapPane(params) { return this.request("swap-pane", params); }
+    zoomPane(params = {}) { return this.request("zoom-pane", params); }
+    processInfo(surface) { return this.request("process-info", { surface }); }
+    setDefaultColors(fg, bg) {
+        return this.request("set-default-colors", { fg, bg });
+    }
+    closeSurface(surface) { return this.request("close-surface", { surface }); }
+    closePane(pane) { return this.request("close-pane", { pane }); }
+    closeScreen(screen) { return this.request("close-screen", { screen }); }
+    async closeWorkspace(workspace) {
+        await this.request("close-workspace", { workspace });
+        return {};
+    }
+    async closeWorkspaceRegistry(options) {
+        await this.requireCapability("workspace-registry-v1", "workspace registry");
+        return workspaceMutationResult(await this.request("close-workspace", options));
+    }
+    renamePane(pane, name) { return this.request("rename-pane", { pane, name }); }
+    renameSurface(surface, name) { return this.request("rename-surface", { surface, name }); }
+    renameScreen(screen, name) { return this.request("rename-screen", { screen, name }); }
+    async renameWorkspace(workspace, name) {
+        await this.request("rename-workspace", { workspace, name });
+        return {};
+    }
+    async renameWorkspaceRegistry(options) {
+        await this.requireCapability("workspace-registry-v1", "workspace registry");
+        return workspaceMutationResult(await this.request("rename-workspace", options));
+    }
+    async resizeSurface(surface, cols, rows) {
+        const result = await this.request("resize-surface", { surface, cols, rows });
+        return { ...result, accepted: result.accepted ?? true };
+    }
+    releaseSurfaceSize(surface) {
+        return this.request("release-surface-size", { surface });
+    }
+    focusPane(pane) { return this.request("focus-pane", { pane }); }
+    selectTab(options = {}) { return this.request("select-tab", options); }
+    selectScreen(options = {}) { return this.request("select-screen", options); }
+    selectWorkspace(options = {}) { return this.request("select-workspace", options); }
+    moveTab(surface, pane, index) { return this.request("move-tab", { surface, pane, index }); }
+    async moveWorkspace(workspace, index) {
+        await this.request("move-workspace", { workspace, index });
+        return {};
+    }
+    async moveWorkspaceRegistry(options) {
+        await this.requireCapability("workspace-registry-v1", "workspace registry");
+        return workspaceMutationResult(await this.request("move-workspace", options));
+    }
+    scrollSurface(surface, delta) { return this.request("scroll-surface", { surface, delta }); }
+    async subscribe(options = {}) {
+        return this.openStream({ cmd: "subscribe", tree_events: options.treeEvents }, (event) => event, (event, dedicated) => dedicated
+            || (!this.attachOnlyEvent(event.event) && !this.isSurfaceOverflow(event)), (event) => event.event === "overflow" && !this.isSurfaceOverflow(event), true);
+    }
+    async attachSurface(surface, options = {}) {
+        if ((options.cols === undefined) !== (options.rows === undefined)) {
+            throw new CmuxProtocolError("attach-surface cols and rows must be supplied together");
+        }
+        const mode = options.mode ?? "bytes";
+        const protocol = this.identifiedProtocol ?? (await this.identify()).protocol;
+        if (mode === "render" && protocol < 7) {
+            throw new CmuxProtocolError(`render attach requires protocol 7 or newer; server reported protocol ${protocol}`);
+        }
+        if (mode === "bytes" && protocol > 5 && !this.allowProtocolV6Attach) {
+            throw new CmuxProtocolError(`byte attach for protocol ${protocol} is disabled`);
+        }
+        if ((options.cols !== undefined || options.rows !== undefined)
+            && !this.identifiedCapabilities.has("attach-initial-size")) {
+            throw new CmuxProtocolError("initial attach sizing is not supported by this server");
+        }
+        const request = {
+            cmd: "attach-surface",
+            surface,
+            ...(options.mode === undefined ? {} : { mode }),
+            ...(options.cols === undefined ? {} : { cols: options.cols }),
+            ...(options.rows === undefined ? {} : { rows: options.rows }),
+        };
+        if (mode === "render") {
+            return this.openStream(request, (event) => event, (event, dedicated) => dedicated || this.matchesAttachEvent(event, surface, mode), (event) => event.event === "detached" || this.isSurfaceOverflow(event, surface));
+        }
+        return this.openStream(request, (event) => this.decodeAttachEvent(event), (event, dedicated) => dedicated || this.matchesAttachEvent(event, surface, mode), (event) => event.event === "detached" || this.isSurfaceOverflow(event, surface), false, {
+            maxBytes: this.maxAttachEncodedChars,
+            retainedBytes: (event) => this.attachEventRetainedBytes(event),
+        });
+    }
+    async requireCapability(capability, feature) {
+        if (this.identifiedProtocol === null) {
+            await this.identify();
+        }
+        if (!this.identifiedCapabilities.has(capability)) {
+            throw new CmuxProtocolError(`${feature} is not supported by this server`);
+        }
+    }
+    async requireProtocol(minimum, feature) {
+        const protocol = this.protocol ?? (await this.identify()).protocol;
+        if (protocol < minimum) {
+            throw new CmuxProtocolError(`${feature} requires protocol ${minimum}; server uses protocol ${protocol}`);
+        }
+    }
+    waitFor(surface, pattern, timeoutMs) {
+        return this.request("wait-for", { surface, pattern, timeout_ms: timeoutMs });
+    }
+    run(options) { return this.request("run", options); }
+    sendKey(surface, keys) { return this.request("send-key", { surface, keys }); }
+    copy(surface, mode) { return this.request("copy", { surface, mode }); }
+    ids(kind) { return this.request("ids", { kind }); }
+    notify(title, body, options = {}) {
+        return this.request("notify", { title, body, ...options });
+    }
+    listAgents(options = {}) {
+        return this.request("list-agents", options);
+    }
+    reportAgent(surface, state, source, session) {
+        return this.request("report-agent", { surface, state, source, session });
+    }
+    async openStream(request, map, accept, terminal = () => false, exclusiveSharedSubscription = false, buffering) {
+        const dedicated = this.streamTransportFactory !== undefined;
+        if (exclusiveSharedSubscription && !dedicated) {
+            if (this.sharedSubscriptionActive) {
+                throw new CmuxProtocolError("concurrent subscriptions require streamTransportFactory");
+            }
+            this.sharedSubscriptionActive = true;
+        }
+        const transport = this.streamTransportFactory?.() ?? this.transport;
+        const router = dedicated ? new MessageRouter(transport) : this.router;
+        let eventSubscription = () => undefined;
+        let terminalSubscription = () => undefined;
+        let streamError = null;
+        const stream = new CmuxStream(this.timeoutMs, () => {
+            eventSubscription();
+            terminalSubscription();
+            if (exclusiveSharedSubscription && !dedicated) {
+                this.sharedSubscriptionActive = false;
+            }
+            if (dedicated)
+                transport.close();
+        }, this.maxBufferedEvents, buffering?.maxBytes, buffering?.retainedBytes);
+        eventSubscription = router.onEvent((event) => {
+            if (!accept(event, dedicated))
+                return;
+            try {
+                const mapped = map(event);
+                stream.push(mapped, terminal(mapped));
+                streamError ??= stream.error;
+            }
+            catch (error) {
+                streamError = error instanceof CmuxProtocolError
+                    ? error
+                    : new CmuxProtocolError(`invalid stream event: ${error.message}`);
+                stream.fail(streamError);
+            }
+        });
+        terminalSubscription = router.onTerminal((error) => stream.fail(error));
+        const payload = this.dropUndefined({ id: this.nextId(), ...request });
+        const response = await router.send(payload, this.timeoutMs).catch((error) => {
+            stream.fail(error);
+            throw streamError ?? error;
+        });
+        if (!response.ok) {
+            stream.close();
+            throw new CmuxCommandError(response.error || "unknown error", response.id, response, response.error_code, response.error_delivery);
+        }
+        const terminalError = streamError ?? stream.error;
+        if (terminalError)
+            throw terminalError;
+        return stream;
+    }
+    decodeAttachEvent(event) {
+        switch (event.event) {
+            case "vt-state": {
+                return { ...event, data: this.decodeAttachData(event.data, "vt-state") };
+            }
+            case "output": {
+                return { ...event, data: this.decodeAttachData(event.data, "output") };
+            }
+            case "resized": {
+                const encoded = typeof event.data === "string" ? event.data : event.replay;
+                const data = this.decodeAttachData(encoded, "resized");
+                return { ...event, data, replay: data };
+            }
+            case "frame": {
+                return {
+                    ...event,
+                    ...this.decodeBrowserFrame(event, "frame"),
+                };
+            }
+            case "browser-state": {
+                const frame = event.frame;
+                if (frame !== undefined && frame !== null) {
+                    return {
+                        ...event,
+                        frame: this.decodeBrowserFrame(frame, "browser-state frame"),
+                    };
+                }
+                return event;
+            }
+            default: return event;
+        }
+    }
+    decodeAttachData(value, eventName) {
+        return decodeBase64(this.validateAttachEncodedData(value, eventName));
+    }
+    decodeBrowserFrame(value, eventName) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            throw new CmuxProtocolError(`${eventName} is not an object`);
+        }
+        const frame = value;
+        const seq = this.validateFrameSequence(frame.seq, eventName);
+        const width = this.validateFrameCssDimension(frame.width, eventName, "width");
+        const height = this.validateFrameCssDimension(frame.height, eventName, "height");
+        const imageWidth = frame.image_width === undefined
+            ? width
+            : this.validateFrameDimension(frame.image_width, eventName, "image_width");
+        const imageHeight = frame.image_height === undefined
+            ? height
+            : this.validateFrameDimension(frame.image_height, eventName, "image_height");
+        const data = this.validateAttachEncodedData(frame.data, eventName);
+        return {
+            ...frame,
+            seq,
+            width,
+            height,
+            image_width: imageWidth,
+            image_height: imageHeight,
+            data,
+        };
+    }
+    validateFrameSequence(value, eventName) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+            throw new CmuxProtocolError(`${eventName} seq is not a nonnegative integer`);
+        }
+        return value;
+    }
+    validateFrameCssDimension(value, eventName, field) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+            throw new CmuxProtocolError(`${eventName} ${field} is not a nonnegative integer`);
+        }
+        return value;
+    }
+    validateFrameDimension(value, eventName, field) {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+            throw new CmuxProtocolError(`${eventName} ${field} is not a positive integer`);
+        }
+        return value;
+    }
+    validateAttachEncodedData(value, eventName) {
+        if (typeof value !== "string") {
+            throw new CmuxProtocolError(`${eventName} data is not base64 text`);
+        }
+        if (value.length > this.maxAttachEncodedChars) {
+            throw new CmuxProtocolError(`${eventName} data exceeds ${this.maxAttachEncodedChars} encoded characters`);
+        }
+        return value;
+    }
+    attachEventRetainedBytes(event) {
+        switch (event.event) {
+            case "vt-state":
+            case "output":
+            case "resized":
+                return event.data instanceof Uint8Array ? event.data.byteLength : 0;
+            case "frame":
+                return typeof event.data === "string" ? event.data.length : 0;
+            case "browser-state":
+                return new TextEncoder().encode(JSON.stringify(event)).byteLength;
+            default:
+                return 0;
+        }
+    }
+    matchesAttachEvent(event, surface, mode) {
+        // colors-changed is scoped by its attach connection and intentionally has
+        // no surface field in protocol v6. Protocol v7 includes the surface id.
+        if (event.event === "colors-changed") {
+            return mode === "bytes" && (!("surface" in event) || event.surface === surface);
+        }
+        if (!("surface" in event) || event.surface !== surface)
+            return false;
+        if (event.event === "detached" || event.event === "scroll-changed"
+            || this.isSurfaceOverflow(event, surface))
+            return true;
+        return mode === "render"
+            ? event.event === "render-state" || event.event === "render-delta"
+            : event.event === "vt-state" || event.event === "output" || event.event === "resized"
+                || event.event === "frame" || event.event === "browser-state";
+    }
+    isSurfaceOverflow(event, surface) {
+        return event.event === "overflow"
+            && event.scope === "surface"
+            && "surface" in event
+            && (surface === undefined || event.surface === surface);
+    }
+    attachOnlyEvent(event) {
+        return event === "vt-state"
+            || event === "output"
+            || event === "resized"
+            || event === "frame"
+            || event === "browser-state"
+            || event === "colors-changed"
+            || event === "render-state"
+            || event === "render-delta"
+            || event === "detached";
+    }
+    dropUndefined(value) {
+        return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+    }
+    securityLimit(name, value, maximum) {
+        const limit = value ?? maximum;
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > maximum) {
+            throw new RangeError(`${name} must be an integer from 1 through ${maximum}`);
+        }
+        return limit;
+    }
+    nextId() {
+        return this.nextRequestId++;
+    }
+}