ai-remote 0.4.0 → 0.4.2

package/src/protocols/rdp/client.ts

@@ -1,1371 +0,0 @@
-// The RDP client connection state machine (MS-RDPBCGR 1.3.1.1).
-//
-// It runs in the browser and talks to the gateway's /rdp-ws relay, which moves
-// bytes to and from TCP port 3389 and performs the TLS upgrade when X.224
-// negotiation asks for one. Everything above the transport -- MCS, the security
-// layer, capability exchange, updates and input -- happens here.
-
-import { Reader, concatBytes } from './buffer';
-import { rsaEncrypt } from './crypto';
-import { NEG_FAILURE, NEG_PROTOCOL, connectionRequest, parseConnectionConfirm, splitFrames } from './x224';
-import { Tls12Client } from './tls';
-import { CredSspClient } from './credssp';
-import {
-  MCS_BASE_CHANNEL_ID,
-  attachUserRequest,
-  channelJoinRequest,
-  connectInitial,
-  erectDomainRequest,
-  parseAttachUserConfirm,
-  parseChannelJoinConfirm,
-  parseConnectResponse,
-  parseDomainPdu,
-  sendDataRequest,
-} from './mcs';
-import { ENCRYPTION_LEVEL, clientData, parseServerData } from './gcc';
-import { ClipboardChannel } from './cliprdr';
-import { RailChannel, SHOW_STATE, SYS_COMMAND, isPrimaryWindow, parseRemoteAppWindowOrders } from './rail';
-import {
-  CHANNEL_FLAG_SHOW_PROTOCOL,
-  CHANNEL_OPTION,
-  ChannelReassembler,
-  CHANNEL_CHUNK_LENGTH,
-  chunkChannelData,
-} from './vchannel';
-import { SEC_FLAG, SecurityLayer } from './sec';
-import { buildClientCapabilities, parseServerCapabilities } from './caps';
-import {
-  CONTROL_ACTION,
-  PDU_TYPE,
-  PDU_TYPE2,
-  POINTER_FLAG,
-  UPDATE_TYPE,
-  clientInfoPdu,
-  confirmActivePdu,
-  controlPdu,
-  errorInfoMessage,
-  extendedMouseEvent,
-  fontListPdu,
-  inputEventsPdu,
-  mouseEvent,
-  parseBitmapUpdate,
-  parseDemandActive,
-  parsePaletteUpdate,
-  parsePointerUpdate,
-  pointerWheelFlags,
-  parseShareControlHeader,
-  parseShareDataHeader,
-  refreshRectPdu,
-  scancodeEvent,
-  shareControlPdu,
-  shareDataPdu,
-  suppressOutputPdu,
-  syncEvent,
-  synchronizePdu,
-  unicodeEvent,
-} from './pdu';
-import { CTRL_ALT_DEL, lookupScancode } from './keymap';
-import {
-  GATEWAY_KEEPALIVE_SIGNAL,
-  GATEWAY_READY_SIGNAL,
-  KEEPALIVE_INTERVAL_MS,
-} from '../../shared/signals';
-
-
-const STATE = {
-  IDLE: 'idle',
-  NEGOTIATING: 'negotiating',
-  TLS_HANDSHAKE: 'tls-handshake',
-  CREDSSP: 'credssp',
-  MCS_CONNECT: 'mcs-connect',
-  ATTACH_USER: 'attach-user',
-  JOIN_CHANNELS: 'join-channels',
-  SECURE: 'secure-exchange',
-  LICENSING: 'licensing',
-  CAPABILITIES: 'capabilities',
-  CONNECTED: 'connected',
-  CLOSED: 'closed',
-};
-
-const LICENSE_ERROR_ALERT = 0xff;
-
-/**
- * The clipboard channel. ENCRYPT_RDP only matters under the RDP security layer,
- * where the host would otherwise send this channel in the clear.
- *
- * SHOW_PROTOCOL is not optional, and it has to be matched by
- * CHANNEL_FLAG_SHOW_PROTOCOL on every chunk the client sends. Windows silently
- * discards clipboard data that arrives without the pair: the channel opens, the
- * host announces itself, and then nothing the client sends is ever answered.
- *
- * Compression is absent because this client advertises no decompressor.
- */
-const CLIPBOARD_CHANNEL = {
-  name: 'cliprdr',
-  options: CHANNEL_OPTION.INITIALIZED | CHANNEL_OPTION.ENCRYPT_RDP | CHANNEL_OPTION.SHOW_PROTOCOL,
-};
-
-const RAIL_CHANNEL = {
-  name: 'rail',
-  options: CHANNEL_OPTION.INITIALIZED | CHANNEL_OPTION.ENCRYPT_RDP | CHANNEL_OPTION.SHOW_PROTOCOL,
-};
-
-const PERF_DISABLE_WALLPAPER = 0x00000001;
-const PERF_DISABLE_FULLWINDOWDRAG = 0x00000002;
-const PERF_DISABLE_MENUANIMATIONS = 0x00000004;
-const REMOTE_APP_CLOSE_GRACE_MS = 1200;
-
-// A window that has just been restored from maximized is not movable until the
-// host has finished the restore, so the move that fits it is sent one beat
-// later. A repeated fit is coalesced over the same delay.
-const REMOTE_APP_FIT_DELAY_MS = 120;
-
-// How far the host may place the window from what was asked for before the
-// client asks again, and how many times it is worth asking.
-const FIT_TOLERANCE_PIXELS = 2;
-const REMOTE_APP_FIT_ATTEMPTS = 4;
-const REMOTE_APP_FIT_MOVES = 12;
-const MIN_REMOTE_APP_SIZE = 320;
-
-/**
- * A single RDP connection. Emits:
- *   'ready'    { width, height }      -- the desktop size is known
- *   'bitmap'   { rects }              -- decoded rectangles to paint
- *   'palette'  Uint8Array             -- 8bpp palette update
- *   'pointer'  pointer update         -- shape, position or visibility
- *   'error'    { message }            -- fatal, always followed by 'close'
- *   'close'    { clean, message }
- */
-export class RdpClient extends EventTarget {
-  constructor(url: string, options = {}) {
-    super();
-
-    this.url = url;
-    this.options = {
-      width: 1024,
-      height: 768,
-      username: '',
-      password: '',
-      domain: '',
-      keyboardLayout: 0x409,
-      clientName: 'cf-gateway',
-      security: 'auto',
-      /** Returns a WebSocket-shaped transport for `url`; default is a real one. */
-      openTransport: null,
-      clipboard: true,
-      remoteApp: null,
-      performance: PERF_DISABLE_WALLPAPER | PERF_DISABLE_FULLWINDOWDRAG | PERF_DISABLE_MENUANIMATIONS,
-      ...options,
-    };
-
-    this.state = STATE.IDLE;
-    this.legacyRetryUsed = false;
-    this.desktopWidth = this.options.width;
-    this.desktopHeight = this.options.height;
-    this.palette = null;
-
-    this.userId = MCS_BASE_CHANNEL_ID;
-    this.ioChannelId = 1003;
-    this.serverChannelId = 0x03ea;
-    this.shareId = 0;
-    this.channelsToJoin = [];
-    this.requestedChannels = [];
-    /** Server-assigned virtual channel ids, keyed by the name we asked for. */
-    this.channelNamesById = new Map();
-    this.channelReassemblers = new Map();
-    this.clipboard = null;
-    this.rail = null;
-    /** Live RemoteApp windows and their last reported geometry, by window id. */
-    this.remoteAppWindows = new Map();
-    this.remoteAppHadWindow = false;
-    this.remoteAppCloseTimer = null;
-    this.remoteAppFit = null;
-    this.remoteAppFitTimer = null;
-    this.clientRandom = null;
-    this.serverData = null;
-    this.fastPathFragments = [];
-
-    this.receiveBuffer = new Uint8Array(0);
-    this.keepaliveTimer = null;
-    this.closeReported = false;
-
-    // TLS and CredSSP run here rather than at the edge: the gateway's runtime
-    // hides the host certificate that CredSSP must bind to, and validates it
-    // against public CAs, which no self-signed RDP host can satisfy.
-    this.tls = null;
-    this.credssp = null;
-    this.inboundQueue = Promise.resolve();
-
-    // "auto" offers both modern layers and lets the host choose, which is what
-    // the X.224 negotiation is for. HYBRID_EX is left out on purpose: a host
-    // offered it will pick it, and it needs a round trip this client does not
-    // implement.
-    this.requestedProtocol = {
-      auto: NEG_PROTOCOL.SSL | NEG_PROTOCOL.HYBRID,
-      nla: NEG_PROTOCOL.SSL | NEG_PROTOCOL.HYBRID,
-      tls: NEG_PROTOCOL.SSL,
-      rdp: NEG_PROTOCOL.RDP,
-    }[this.options.security] ?? (NEG_PROTOCOL.SSL | NEG_PROTOCOL.HYBRID);
-
-    this.#openTransport();
-  }
-
-  /**
-   * Open the transport and reset everything that belongs to one connection.
-   * Falling back to another security layer needs a second socket, because a
-   * host that refuses the negotiation closes the first.
-   */
-  #openTransport() {
-    this.receiveBuffer = new Uint8Array(0);
-    this.inboundQueue = Promise.resolve();
-    this.tls = null;
-    this.credssp = null;
-    this.security = new SecurityLayer();
-    this.replacingTransport = false;
-    this.channelNamesById = new Map();
-    this.channelReassemblers = new Map();
-    this.clipboard = null;
-    this.rail = null;
-    this.remoteAppWindows.clear();
-    this.remoteAppHadWindow = false;
-    clearTimeout(this.remoteAppCloseTimer);
-    clearTimeout(this.remoteAppFitTimer);
-    this.remoteAppFitTimer = null;
-    this.remoteAppCloseTimer = null;
-
-    // The transport is injected so this client can run anywhere. In a browser
-    // it is a WebSocket to the gateway's relay; in the CLI it is a TCP socket
-    // straight at the host. Everything above it -- X.224, TLS, CredSSP, MCS --
-    // is the same either way, which is the whole reason it is a seam.
-    this.socket = this.options.openTransport
-      ? this.options.openTransport(this.url)
-      : new WebSocket(this.url);
-    this.socket.binaryType = 'arraybuffer';
-    this.socket.addEventListener('open', () => this.#onOpen());
-    this.socket.addEventListener('message', (event) => this.#onMessage(event));
-    this.socket.addEventListener('close', (event) => this.#onSocketClose(event));
-    this.socket.addEventListener('error', () => {
-      // The browser never exposes the underlying error; the close event that
-      // follows carries the gateway's reason.
-      console.warn('[RDP] WebSocket transport error', { target: this.url });
-    });
-  }
-
-  /** Reconnect asking for the only security layer this host will accept. */
-  #retryWithSecurityLayer(security) {
-    console.info('[RDP] Reconnecting with a different security layer', { security });
-    this.legacyRetryUsed = true;
-    this.options.security = security;
-    this.requestedProtocol = security === 'rdp' ? NEG_PROTOCOL.RDP : NEG_PROTOCOL.SSL;
-    this.state = STATE.IDLE;
-
-    // The old socket's close must not be reported as the session ending.
-    this.replacingTransport = true;
-    clearInterval(this.keepaliveTimer);
-    try { this.socket.close(1000, 'Retrying with another security layer'); } catch {}
-
-    this.#openTransport();
-  }
-
-  // --- transport ------------------------------------------------------------
-
-  #onOpen() {
-    // The relay holds off reading the host until the browser says it is ready,
-    // so the negotiation response cannot be lost.
-    this.socket.send(GATEWAY_READY_SIGNAL);
-
-    this.state = STATE.NEGOTIATING;
-    this.#send(connectionRequest(this.requestedProtocol));
-
-    this.keepaliveTimer = setInterval(() => {
-      if (this.socket.readyState !== WebSocket.OPEN) return;
-
-      // Keeps the browser-to-gateway WebSocket from idling out at the edge.
-      // The gateway absorbs this frame; it never reaches the host.
-      this.socket.send(GATEWAY_KEEPALIVE_SIGNAL);
-
-      // Which is why the session also needs traffic of its own. A desktop
-      // nobody is touching sends nothing for minutes at a time, and the TCP
-      // connection carrying it -- through the tunnel, through the VPC binding
-      // -- is dropped as idle long before the user has finished reading the
-      // screen. A sync event is what mstsc sends for the same reason: it
-      // restates the toggle-key state, changes nothing, and is traffic.
-      if (this.state === STATE.CONNECTED) {
-        try {
-          this.#sendInput([syncEvent(this.toggleFlags || 0)]);
-        } catch {
-          // A keepalive is not worth breaking a working session over.
-        }
-      }
-    }, KEEPALIVE_INTERVAL_MS);
-  }
-
-  /** RDP-level send: once a secure channel exists everything rides inside it. */
-  #send(bytes: Uint8Array) {
-    if (this.tls && this.tls.established) {
-      this.tls.write(bytes);
-      return;
-    }
-    this.#sendRaw(bytes);
-  }
-
-  #sendRaw(bytes: Uint8Array) {
-    if (this.socket.readyState !== WebSocket.OPEN) return;
-    this.socket.send(bytes);
-  }
-
-  #onSocketClose(event) {
-    clearInterval(this.keepaliveTimer);
-    clearTimeout(this.remoteAppCloseTimer);
-    clearTimeout(this.remoteAppFitTimer);
-    this.remoteAppFitTimer = null;
-    if (this.replacingTransport) return;
-    if (this.state === STATE.CLOSED && this.closeReported) return;
-
-    const wasConnected = this.state === STATE.CONNECTED;
-    this.state = STATE.CLOSED;
-    this.closeReported = true;
-
-    this.dispatchEvent(new CustomEvent('close', {
-      detail: {
-        clean: event.wasClean && wasConnected,
-        code: event.code,
-        message: event.reason || '',
-        phase: wasConnected ? 'session' : 'handshake',
-      },
-    }));
-  }
-
-  #fail(error: unknown) {
-    if (this.state === STATE.CLOSED) return;
-    const message = error instanceof Error ? error.message : String(error);
-    console.error('[RDP] Protocol failure', { state: this.state, message });
-
-    this.dispatchEvent(new CustomEvent('error', { detail: { message, phase: this.state } }));
-    this.state = STATE.CLOSED;
-    this.closeReported = true;
-    clearInterval(this.keepaliveTimer);
-    clearTimeout(this.remoteAppCloseTimer);
-    clearTimeout(this.remoteAppFitTimer);
-    this.remoteAppFitTimer = null;
-
-    try { this.socket.close(4000, message.slice(0, 100)); } catch {}
-    this.dispatchEvent(new CustomEvent('close', {
-      detail: { clean: false, code: 4000, message, phase: 'protocol' },
-    }));
-  }
-
-  disconnect() {
-    if (this.state === STATE.CLOSED) return;
-    this.state = STATE.CLOSED;
-    this.closeReported = true;
-    clearInterval(this.keepaliveTimer);
-    clearTimeout(this.remoteAppCloseTimer);
-    clearTimeout(this.remoteAppFitTimer);
-    this.remoteAppFitTimer = null;
-    try { this.socket.close(1000, 'Client disconnected'); } catch {}
-  }
-
-  /**
-   * Transport bytes are processed strictly in order. Nothing awaited in here
-   * may itself wait for a later message, or the pipeline would deadlock -- the
-   * TLS and CredSSP startup is therefore detached and driven by callbacks.
-   */
-  #onMessage(event) {
-    if (this.state === STATE.CLOSED) return;
-
-    this.inboundQueue = this.inboundQueue
-      .then(async () => {
-        if (this.state === STATE.CLOSED) return;
-
-        const chunk = typeof event.data === 'string'
-          ? new TextEncoder().encode(event.data)
-          : new Uint8Array(event.data);
-
-        // Before the secure channel exists these are RDP frames; afterwards
-        // they are TLS records carrying them.
-        if (this.tls) await this.tls.receive(chunk);
-        else await this.#ingest(chunk);
-      })
-      .catch((error: unknown) => this.#fail(error));
-  }
-
-  /** Plaintext coming out of the secure channel. */
-  #onSecureData(bytes: Uint8Array) {
-    if (this.state === STATE.CREDSSP && this.credssp) {
-      this.credssp.receive(bytes);
-      return;
-    }
-    return this.#ingest(bytes);
-  }
-
-  async #ingest(chunk: Uint8Array) {
-    this.receiveBuffer = this.receiveBuffer.length === 0
-      ? chunk
-      : concatBytes(this.receiveBuffer, chunk);
-
-    const { frames, rest } = splitFrames(this.receiveBuffer);
-    this.receiveBuffer = rest.length === this.receiveBuffer.length ? this.receiveBuffer : rest.slice();
-
-    for (const { fastPath, frame } of frames) {
-      if (this.state === STATE.CLOSED) return;
-      if (fastPath) this.#handleFastPath(frame);
-      else await this.#handleX224(frame);
-    }
-  }
-
-  // --- connection sequence --------------------------------------------------
-
-  async #handleX224(frame: Uint8Array) {
-    if (this.state === STATE.NEGOTIATING) {
-      let selectedProtocol;
-      try {
-        ({ selectedProtocol } = parseConnectionConfirm(frame));
-      } catch (error) {
-        // A host offering only the legacy RDP security layer refuses TLS
-        // outright. Negotiating automatically, that is an answer rather than a
-        // failure: reconnect asking for the layer it does have.
-        if (
-          this.options.security === 'auto' &&
-          !this.legacyRetryUsed &&
-          error.negotiationFailure === NEG_FAILURE.SSL_NOT_ALLOWED
-        ) {
-          this.#retryWithSecurityLayer('rdp');
-          return;
-        }
-        throw error;
-      }
-
-      this.selectedProtocol = selectedProtocol;
-      console.info('[RDP] X.224 negotiation complete', {
-        requested: this.requestedProtocol,
-        selected: selectedProtocol,
-        layer: selectedProtocol & NEG_PROTOCOL.HYBRID
-          ? 'NLA / CredSSP'
-          : selectedProtocol & NEG_PROTOCOL.SSL ? 'TLS' : 'RDP standard',
-      });
-
-      if (selectedProtocol & NEG_PROTOCOL.HYBRID_EX) {
-        // CredSSP-with-early-user-auth adds a round trip this client does not
-        // implement; asking for HYBRID alone avoids it.
-        throw new Error('This host selected CredSSP with early user authorization, which this client does not implement.');
-      }
-
-      // A host that chose TLS or NLA gets its own TLS session, established
-      // here so the certificate is visible and self-signed is acceptable.
-      if (selectedProtocol & (NEG_PROTOCOL.SSL | NEG_PROTOCOL.HYBRID)) {
-        void this.#startSecureChannel(selectedProtocol);
-        return;
-      }
-
-      this.#startMcsConnect(selectedProtocol);
-      return;
-    }
-
-    if (this.state === STATE.MCS_CONNECT) {
-      this.serverData = parseServerData(parseConnectResponse(frame));
-      console.info('[RDP] MCS connect response', {
-        encryptionMethod: this.serverData.encryptionMethod,
-        encryptionLevel: this.serverData.encryptionLevel,
-        ioChannelId: this.serverData.ioChannelId,
-        certificate: this.serverData.publicKey?.source || 'none',
-        virtualChannels: this.serverData.channelIds,
-      });
-
-      this.ioChannelId = this.serverData.ioChannelId;
-
-      // The host answers with one id per requested channel, in the order asked.
-      this.channelNamesById = new Map();
-      this.requestedChannels.forEach((channel, index) => {
-        const channelId = this.serverData.channelIds[index];
-        if (channelId !== undefined) this.channelNamesById.set(channelId, channel.name);
-      });
-
-      this.security.configure(
-        this.serverData.encryptionMethod,
-        this.serverData.encryptionLevel,
-        // The client random is only needed when the RDP security layer is live.
-        this.serverData.encryptionMethod ? this.#makeClientRandom() : new Uint8Array(32),
-        this.serverData.serverRandom || new Uint8Array(32)
-      );
-
-      this.state = STATE.ATTACH_USER;
-      this.#send(erectDomainRequest());
-      this.#send(attachUserRequest());
-      return;
-    }
-
-    if (this.state === STATE.ATTACH_USER) {
-      ({ userId: this.userId } = parseAttachUserConfirm(frame));
-      this.channelsToJoin = [this.userId, this.ioChannelId, ...this.serverData.channelIds];
-      this.joinedChannels = 0;
-      this.state = STATE.JOIN_CHANNELS;
-      this.#send(channelJoinRequest(this.userId, this.channelsToJoin[0]));
-      return;
-    }
-
-    if (this.state === STATE.JOIN_CHANNELS) {
-      parseChannelJoinConfirm(frame);
-      this.joinedChannels += 1;
-
-      if (this.joinedChannels < this.channelsToJoin.length) {
-        this.#send(channelJoinRequest(this.userId, this.channelsToJoin[this.joinedChannels]));
-        return;
-      }
-
-      this.#startSecureSession();
-      return;
-    }
-
-    // Past the connect sequence everything arrives as a send-data indication.
-    const pdu = parseDomainPdu(frame);
-    if (pdu.type === 'disconnect') {
-      this.#fail(new Error(pdu.message));
-      return;
-    }
-    if (pdu.type !== 'send-data') return;
-
-    // Virtual channels are routed by id, before the security header heuristic
-    // below: a channel PDU's own length field can look exactly like one.
-    const channelName = this.channelNamesById.get(pdu.channelId);
-    if (channelName) {
-      const body = this.security.headerPresent
-        ? this.security.unwrap(pdu.payload).payload
-        : pdu.payload;
-      this.#handleChannelData(channelName, body);
-      return;
-    }
-
-    const { flags, payload } = this.#unwrapSecurity(pdu.payload);
-    if (payload.length === 0) return;
-
-    if (flags & SEC_FLAG.LICENSE_PKT) {
-      this.#handleLicensing(payload);
-      return;
-    }
-
-    this.#handleSharePdu(payload);
-  }
-
-  /**
-   * Basic security headers are mandatory on licensing PDUs even when the host
-   * reported no RDP-level encryption, so during that phase the header has to be
-   * recognised rather than assumed. A share control PDU never has a zero pduType,
-   * which is what tells the two apart.
-   */
-  #unwrapSecurity(bytes: Uint8Array) {
-    if (this.security.headerPresent) return this.security.unwrap(bytes);
-
-    const KNOWN_FLAGS =
-      SEC_FLAG.EXCHANGE_PKT | SEC_FLAG.ENCRYPT | SEC_FLAG.INFO_PKT | SEC_FLAG.LICENSE_PKT |
-      SEC_FLAG.LICENSE_ENCRYPT_CS | SEC_FLAG.REDIRECTION_PKT | SEC_FLAG.AUTODETECT_REQ |
-      SEC_FLAG.HEARTBEAT;
-
-    if (bytes.length >= 4) {
-      const flags = bytes[0] | (bytes[1] << 8);
-      const flagsHi = bytes[2] | (bytes[3] << 8);
-      if (flagsHi === 0 && (flags & KNOWN_FLAGS) !== 0) {
-        return this.security.unwrap(bytes, true);
-      }
-    }
-
-    return { flags: 0, payload: bytes };
-  }
-
-  /**
-   * Establish TLS and, when the host asked for NLA, authenticate with CredSSP
-   * before the RDP connection sequence starts. Detached from the inbound
-   * pipeline on purpose: it waits for messages that the pipeline delivers.
-   */
-  async #startSecureChannel(selectedProtocol: number) {
-    try {
-      this.state = STATE.TLS_HANDSHAKE;
-      this.tls = new Tls12Client({
-        send: (bytes: Uint8Array) => this.#sendRaw(bytes),
-        onData: (bytes: Uint8Array) => this.#onSecureData(bytes),
-        onError: (error: unknown) => this.#fail(error),
-      });
-
-      const session = await this.tls.start();
-      console.info('[RDP] TLS established', {
-        cipherSuite: session.cipherSuite,
-        certificates: session.certificates.length,
-        modulusBits: session.publicKey.modulus.length * 8,
-      });
-
-      if (selectedProtocol & NEG_PROTOCOL.HYBRID) {
-        this.state = STATE.CREDSSP;
-        this.credssp = new CredSspClient({
-          username: this.options.username,
-          domain: this.options.domain,
-          password: this.options.password,
-          serverPublicKey: session.publicKey.subjectPublicKey,
-          send: (bytes: Uint8Array) => this.tls.write(bytes),
-          log: (step: number, detail) => console.info(`[RDP] ${step}`, detail),
-        });
-
-        if (!this.options.password) {
-          throw new Error('This host authenticates before the desktop appears (NLA), so it needs a username and password.');
-        }
-
-        const outcome = await this.credssp.authenticate();
-        console.info('[RDP] Network Level Authentication succeeded', outcome);
-        this.credssp = null;
-      }
-
-      this.#startMcsConnect(selectedProtocol);
-    } catch (error) {
-      this.#fail(error);
-    }
-  }
-
-  #startMcsConnect(selectedProtocol: number) {
-    this.state = STATE.MCS_CONNECT;
-    this.requestedChannels = [];
-    if (this.options.clipboard) this.requestedChannels.push(CLIPBOARD_CHANNEL);
-    if (this.options.remoteApp?.program) this.requestedChannels.push(RAIL_CHANNEL);
-    this.#send(connectInitial(clientData({
-      width: this.options.width,
-      height: this.options.height,
-      clientName: this.options.clientName,
-      keyboardLayout: this.options.keyboardLayout,
-      selectedProtocol,
-      // Only the bare RDP security layer needs RDP's own encryption; with TLS
-      // underneath, the host reports no encryption method at all.
-      encryptionMethods: selectedProtocol === NEG_PROTOCOL.RDP ? 0x0000000b : 0,
-      channels: this.requestedChannels,
-    })));
-  }
-
-  #makeClientRandom() {
-    this.clientRandom = new Uint8Array(32);
-    crypto.getRandomValues(this.clientRandom);
-    return this.clientRandom;
-  }
-
-  /**
-   * Send the security exchange (when the RDP security layer is in use) followed
-   * by the client info PDU that carries the credentials.
-   */
-  #startSecureSession() {
-    if (this.security.encryptionEnabled) {
-      const key = this.serverData.publicKey;
-      if (!key) throw new Error('RDP: the host asked for encryption but sent no public key');
-
-      const encryptedRandom = rsaEncrypt(this.clientRandom, key.modulus, key.exponent);
-      this.#sendOnIoChannel(SecurityLayer.securityExchange(encryptedRandom));
-    }
-
-    const info = clientInfoPdu({
-      domain: this.options.domain,
-      username: this.options.username,
-      password: this.options.password,
-      performanceFlags: this.options.performance,
-      autoLogon: Boolean(this.options.password),
-      remoteApp: Boolean(this.options.remoteApp?.program),
-    });
-
-    this.state = STATE.LICENSING;
-    this.#sendOnIoChannel(this.security.wrap(info, SEC_FLAG.INFO_PKT));
-  }
-
-  #sendOnIoChannel(payload: Uint8Array) {
-    this.#send(sendDataRequest(this.userId, this.ioChannelId, payload));
-  }
-
-  #handleLicensing(payload: Uint8Array) {
-    if (payload.length < 4) return;
-    const messageType = payload[0];
-
-    if (messageType === LICENSE_ERROR_ALERT) {
-      // The expected answer for a host that needs no per-device licence.
-      console.info('[RDP] Licensing finished with an error alert (the normal path)');
-      this.state = STATE.CAPABILITIES;
-      return;
-    }
-
-    throw new Error(
-      'This host requires Remote Desktop licensing negotiation (per-device CAL), which this client does not implement.'
-    );
-  }
-
-  // --- share layer ----------------------------------------------------------
-
-  #handleSharePdu(payload: Uint8Array) {
-    const control = parseShareControlHeader(payload);
-    if (control.pduSource) this.serverChannelId = control.pduSource;
-
-    if (control.pduType === PDU_TYPE.DEMAND_ACTIVE) {
-      this.#handleDemandActive(control.payload);
-      return;
-    }
-
-    if (control.pduType === PDU_TYPE.DEACTIVATE_ALL) {
-      // The host is about to re-run capability exchange, typically because the
-      // desktop was resized or the session was reconnected.
-      console.info('[RDP] Host deactivated the share; waiting for a new demand active');
-      this.state = STATE.CAPABILITIES;
-      return;
-    }
-
-    if (control.pduType === PDU_TYPE.SERVER_REDIRECT) {
-      throw new Error('This host redirected the session to another server, which this client cannot follow.');
-    }
-
-    if (control.pduType !== PDU_TYPE.DATA) return;
-
-    const data = parseShareDataHeader(control.payload);
-    if (data.compressedType & 0x20) {
-      throw new Error('RDP: the host compressed a PDU although this client advertised no compression support');
-    }
-
-    this.#handleDataPdu(data);
-  }
-
-  #handleDemandActive(payload: Uint8Array) {
-    const { shareId, capabilities } = parseDemandActive(payload);
-    this.shareId = shareId;
-
-    const serverCaps = parseServerCapabilities(capabilities);
-    if (this.options.remoteApp?.program && (!(serverCaps.railSupportLevel & 1) || !serverCaps.windowSupportLevel)) {
-      throw new Error('This RDP host did not accept RemoteApp mode. Publish the application on the host or connect without a RemoteApp program.');
-    }
-    if (serverCaps.desktopWidth && serverCaps.desktopHeight) {
-      const resized = this.state === STATE.CONNECTED &&
-        (serverCaps.desktopWidth !== this.desktopWidth || serverCaps.desktopHeight !== this.desktopHeight);
-      this.desktopWidth = serverCaps.desktopWidth;
-      this.desktopHeight = serverCaps.desktopHeight;
-
-      // A host may re-run capability exchange with a different desktop size.
-      // The canvas has to follow it, or every later update lands at the wrong
-      // coordinates on a framebuffer of the old size.
-      if (resized) {
-        console.info('[RDP] Host resized the desktop', {
-          desktop: `${this.desktopWidth}x${this.desktopHeight}`,
-        });
-        this.dispatchEvent(new CustomEvent('resize', {
-          detail: { width: this.desktopWidth, height: this.desktopHeight },
-        }));
-      }
-    }
-    this.refreshRectSupported = serverCaps.refreshRectSupport;
-
-    console.info('[RDP] Demand active', {
-      shareId,
-      desktop: `${this.desktopWidth}x${this.desktopHeight}`,
-      bitsPerPixel: serverCaps.preferredBitsPerPixel,
-      refreshRectSupport: serverCaps.refreshRectSupport,
-      remoteApp: Boolean(this.options.remoteApp?.program),
-    });
-
-    const { bytes, count } = buildClientCapabilities({
-      width: this.desktopWidth,
-      height: this.desktopHeight,
-      keyboardLayout: this.options.keyboardLayout,
-      remoteApp: Boolean(this.options.remoteApp?.program),
-      remoteAppCaps: serverCaps,
-    });
-
-    this.#sendShareControl(
-      PDU_TYPE.CONFIRM_ACTIVE,
-      confirmActivePdu(this.shareId, bytes, count)
-    );
-
-    // The host expects this exact sequence before it will send any output.
-    this.#sendShareData(PDU_TYPE2.SYNCHRONIZE, synchronizePdu(this.serverChannelId));
-    this.#sendShareData(PDU_TYPE2.CONTROL, controlPdu(CONTROL_ACTION.COOPERATE));
-    this.#sendShareData(PDU_TYPE2.CONTROL, controlPdu(CONTROL_ACTION.REQUEST_CONTROL));
-    this.#sendShareData(PDU_TYPE2.FONT_LIST, fontListPdu());
-  }
-
-  #handleDataPdu(data: Uint8Array) {
-    switch (data.pduType2) {
-      case PDU_TYPE2.UPDATE:
-        this.#handleUpdate(new Reader(data.payload));
-        return;
-
-      case PDU_TYPE2.POINTER:
-        this.dispatchEvent(new CustomEvent('pointer', { detail: parsePointerUpdate(new Reader(data.payload)) }));
-        return;
-
-      case PDU_TYPE2.FONT_MAP:
-        this.#markConnected();
-        return;
-
-      case PDU_TYPE2.SET_ERROR_INFO: {
-        const errorInfo = new Reader(data.payload).u32le();
-        if (errorInfo === 0) return;
-        this.#fail(new Error(errorInfoMessage(errorInfo)));
-        return;
-      }
-
-      case PDU_TYPE2.SAVE_SESSION_INFO:
-        console.info('[RDP] Host reported a completed sign-in');
-        return;
-
-      case PDU_TYPE2.SHUTDOWN_DENIED:
-        console.info('[RDP] Host denied the shutdown request');
-        return;
-
-      case PDU_TYPE2.CONTROL:
-      case PDU_TYPE2.SYNCHRONIZE:
-      case PDU_TYPE2.PLAY_SOUND:
-      case PDU_TYPE2.MONITOR_LAYOUT:
-        return;
-
-      default:
-        return;
-    }
-  }
-
-  #handleUpdate(reader: Reader) {
-    const updateType = reader.u16le();
-
-    if (!this.firstUpdateLogged) {
-      this.firstUpdateLogged = true;
-      console.info('[RDP] First host update received', { updateType });
-    }
-
-    if (updateType === UPDATE_TYPE.BITMAP) {
-      const rects = parseBitmapUpdate(reader);
-      if (rects.length > 0) {
-        this.dispatchEvent(new CustomEvent('bitmap', { detail: { rects, palette: this.palette } }));
-      }
-      return;
-    }
-
-    if (updateType === UPDATE_TYPE.PALETTE) {
-      this.palette = parsePaletteUpdate(reader);
-      this.dispatchEvent(new CustomEvent('palette', { detail: this.palette }));
-      return;
-    }
-
-    if (updateType === UPDATE_TYPE.ORDERS) {
-      if (this.options.remoteApp?.program) {
-        this.#handleRemoteAppWindowEvents(parseRemoteAppWindowOrders(reader));
-      } else {
-        // No primary order support was advertised. Windowing Alternate
-        // Secondary orders are the only exception, and only in RemoteApp mode.
-        console.warn('[RDP] Ignoring a drawing-order update the client did not advertise');
-      }
-      return;
-    }
-  }
-
-  #handleRemoteAppWindowEvents(events) {
-    for (const event of events) {
-      if (event.type === 'deleted') {
-        this.remoteAppWindows.delete(event.windowId);
-        this.dispatchEvent(new CustomEvent('remoteappwindow', {
-          detail: { ...event, count: this.remoteAppWindows.size },
-        }));
-        continue;
-      }
-
-      if (event.type === 'new') {
-        clearTimeout(this.remoteAppCloseTimer);
-        this.remoteAppCloseTimer = null;
-        this.remoteAppHadWindow = true;
-      } else if (!this.remoteAppWindows.has(event.windowId)) {
-        // An update for a window whose creation order was never seen. Tracking
-        // it anyway keeps the session alive and the geometry usable.
-        this.remoteAppHadWindow = true;
-      }
-
-      // Only the changed fields are present in an update, so each one is
-      // folded into what the window was already known to be.
-      const known = this.remoteAppWindows.get(event.windowId) || { windowId: event.windowId };
-      const tracked = { ...known, ...event, type: undefined };
-      this.remoteAppWindows.set(event.windowId, tracked);
-
-      this.dispatchEvent(new CustomEvent('remoteappwindow', {
-        detail: { ...event, window: tracked, count: this.remoteAppWindows.size },
-      }));
-
-      // The host may place a new window anywhere, and a user-driven maximize
-      // sizes it to the work area rather than to the browser. Either way the
-      // pending fit is what the browser window currently is, so re-apply it.
-      if (this.remoteAppFit && this.#isFittedWindow(tracked) && !this.#matchesFit(tracked)) {
-        this.#scheduleRemoteAppFit();
-      }
-    }
-
-    this.#publishRemoteAppViewport();
-
-    if (!this.remoteAppHadWindow || this.remoteAppWindows.size > 0 || this.remoteAppCloseTimer) return;
-
-    // Chrome and Electron apps can replace a splash/initial window during
-    // startup. Give a replacement window a short chance to arrive, then end
-    // the otherwise blank RDP connection when the final window stays gone.
-    this.remoteAppCloseTimer = setTimeout(() => {
-      this.remoteAppCloseTimer = null;
-      if (this.state !== STATE.CONNECTED || this.remoteAppWindows.size > 0) return;
-      console.info('[RDP] Last RemoteApp window closed; ending the session');
-      this.dispatchEvent(new CustomEvent('remoteappclosed', {
-        detail: { application: this.options.remoteApp },
-      }));
-    }, REMOTE_APP_CLOSE_GRACE_MS);
-  }
-
-  /**
-   * The window the session exists to show: the largest top-level application
-   * window. Menus, tooltips and drag images are RAIL windows too, and fitting
-   * one of those to the browser instead of the application would be worse than
-   * doing nothing.
-   */
-  get remoteAppPrimaryWindow() {
-    let best = null;
-    let bestArea = -1;
-    for (const candidate of this.remoteAppWindows.values()) {
-      if (!isPrimaryWindow(candidate)) continue;
-      if (candidate.showState === SHOW_STATE.HIDDEN) continue;
-      const area = (candidate.width || 0) * (candidate.height || 0);
-      if (area > bestArea) {
-        best = candidate;
-        bestArea = area;
-      }
-    }
-    return best;
-  }
-
-  #isFittedWindow(candidate) {
-    const target = this.remoteAppPrimaryWindow;
-    return Boolean(target) && target.windowId === candidate.windowId;
-  }
-
-  /** The fit always asks for the desktop's top-left corner. */
-  #matchesFit(candidate) {
-    const fit = this.remoteAppFit;
-    if (!fit) return true;
-    return Math.abs(candidate.x || 0) <= FIT_TOLERANCE_PIXELS &&
-      Math.abs(candidate.y || 0) <= FIT_TOLERANCE_PIXELS &&
-      Math.abs((candidate.width || 0) - fit.width) <= FIT_TOLERANCE_PIXELS &&
-      Math.abs((candidate.height || 0) - fit.height) <= FIT_TOLERANCE_PIXELS;
-  }
-
-  #scheduleRemoteAppFit() {
-    if (this.remoteAppFitTimer) return;
-    this.remoteAppFitTimer = setTimeout(() => {
-      this.remoteAppFitTimer = null;
-      this.#applyRemoteAppFit();
-    }, REMOTE_APP_FIT_DELAY_MS);
-  }
-
-  #applyRemoteAppFit() {
-    const fit = this.remoteAppFit;
-    if (!fit || !this.rail || this.state !== STATE.CONNECTED) return;
-
-    // Maximize, whether the user asks for it or the application does at
-    // startup, resizes into the work area, so it has to follow the browser
-    // window even when there is no window to move yet.
-    this.rail.setWorkArea(fit.width, fit.height);
-
-    const target = this.remoteAppPrimaryWindow;
-    if (!target || target.showState === SHOW_STATE.MINIMIZED) return;
-
-    // A host that will not honour the move must not be asked forever: every
-    // later window order would otherwise start the exchange again. A move that
-    // did change the window is not counted, because a host that is responding
-    // -- an application enforcing a minimum size, a restore still settling --
-    // deserves the next attempt.
-    const geometry = `${target.width || 0}x${target.height || 0}+${target.x || 0}+${target.y || 0}`;
-    if (geometry !== fit.lastGeometry) fit.attempts = 0;
-    fit.lastGeometry = geometry;
-    if (fit.attempts >= REMOTE_APP_FIT_ATTEMPTS || fit.moves >= REMOTE_APP_FIT_MOVES) return;
-    fit.attempts += 1;
-    fit.moves += 1;
-
-    if (target.showState === SHOW_STATE.MAXIMIZED) {
-      // Windows ignores a move applied to a maximized window. Restoring it
-      // first produces a window order, which schedules this fit again.
-      console.info('[RDP] Restoring the maximized RemoteApp window before fitting it');
-      this.rail.sysCommand(target.windowId, SYS_COMMAND.RESTORE);
-      return;
-    }
-
-    console.info('[RDP] Fitting the RemoteApp window to the browser', {
-      windowId: target.windowId,
-      from: `${target.width || 0}x${target.height || 0}+${target.x || 0}+${target.y || 0}`,
-      to: `${fit.width}x${fit.height}+0+0`,
-      attempt: fit.attempts,
-    });
-    this.rail.activate(target.windowId);
-    this.rail.moveWindow(target.windowId, {
-      left: 0,
-      top: 0,
-      right: fit.width,
-      bottom: fit.height,
-    });
-  }
-
-  /**
-   * Show only the primary window's own rectangle. RemoteApp paints nothing
-   * outside its windows, so without this the canvas is the whole negotiated
-   * desktop with the application somewhere inside it.
-   */
-  #publishRemoteAppViewport() {
-    const target = this.remoteAppPrimaryWindow;
-    if (!target || !target.width || !target.height) return;
-    if (target.showState === SHOW_STATE.MINIMIZED || target.showState === SHOW_STATE.HIDDEN) return;
-
-    const x = Math.max(0, Math.min(this.desktopWidth - 1, target.x || 0));
-    const y = Math.max(0, Math.min(this.desktopHeight - 1, target.y || 0));
-    const viewport = {
-      x,
-      y,
-      width: Math.max(1, Math.min(this.desktopWidth - x, target.width)),
-      height: Math.max(1, Math.min(this.desktopHeight - y, target.height)),
-    };
-
-    const previous = this.remoteAppViewport;
-    if (previous && previous.x === viewport.x && previous.y === viewport.y &&
-      previous.width === viewport.width && previous.height === viewport.height) {
-      return;
-    }
-    this.remoteAppViewport = viewport;
-    this.dispatchEvent(new CustomEvent('remoteappviewport', { detail: viewport }));
-  }
-
-  /**
-   * Size the remote application's window to the room the browser has for it.
-   *
-   * The RDP desktop is fixed for the life of a connection -- resizing it needs
-   * the dynamic virtual channel this client does not speak -- so the desktop is
-   * negotiated large at connect time and the application window is moved and
-   * resized inside it instead. The canvas then shows only that window.
-   */
-  fitRemoteApp(width: number, height: number) {
-    if (!this.options.remoteApp?.program) return false;
-    if (!Number.isFinite(width) || !Number.isFinite(height)) return false;
-
-    const fit = {
-      width: Math.max(MIN_REMOTE_APP_SIZE, Math.min(this.desktopWidth, Math.floor(width))),
-      height: Math.max(MIN_REMOTE_APP_SIZE, Math.min(this.desktopHeight, Math.floor(height))),
-      attempts: 0,
-      moves: 0,
-      lastGeometry: '',
-    };
-    this.remoteAppFit = fit;
-    this.#scheduleRemoteAppFit();
-    return true;
-  }
-
-  #markConnected() {
-    if (this.state === STATE.CONNECTED) return;
-    this.state = STATE.CONNECTED;
-
-    console.info('[RDP] Session established', {
-      desktop: `${this.desktopWidth}x${this.desktopHeight}`,
-      encryption: this.security.encryptionEnabled ? `RC4 ${this.security.keys.keyLength * 8}-bit` : 'TLS transport',
-    });
-
-    this.dispatchEvent(new CustomEvent('ready', {
-      detail: { width: this.desktopWidth, height: this.desktopHeight },
-    }));
-
-    // Nothing has been painted yet: the host only sends what changed, and the
-    // session's first frame is a change the client has to ask for. Enabling
-    // output first covers a host that starts the share suppressed.
-    this.setOutputEnabled(true);
-    this.refresh();
-  }
-
-  // --- fast-path output (defensive) ----------------------------------------
-
-  /**
-   * This client does not advertise fast-path output, so a well-behaved host
-   * never uses it. Some do anyway, and dropping those frames would leave a
-   * blank screen with no explanation.
-   */
-  #handleFastPath(frame: Uint8Array) {
-    const encryptionFlags = (frame[0] >> 6) & 0x03;
-    const lengthBytes = frame[1] & 0x80 ? 2 : 1;
-
-    let payload = frame.subarray(1 + lengthBytes);
-    if (encryptionFlags & 0x02) payload = this.security.decryptFastPath(payload);
-
-    const reader = new Reader(payload);
-    while (reader.remaining >= 3) {
-      const header = reader.u8();
-      const updateCode = header & 0x0f;
-      const fragmentation = (header >> 4) & 0x03;
-      const compression = (header >> 6) & 0x03;
-
-      if (compression & 0x02) reader.u8(); // compressionFlags
-      const size = reader.u16le();
-      let updateData = reader.raw(Math.min(size, reader.remaining));
-
-      // 0 single, 1 last, 2 first, 3 next
-      if (fragmentation !== 0) {
-        if (fragmentation === 2) this.fastPathFragments = [];
-        this.fastPathFragments.push(updateData.slice());
-        if (fragmentation !== 1) continue;
-        updateData = concatBytes(...this.fastPathFragments);
-        this.fastPathFragments = [];
-      }
-
-      this.#handleFastPathUpdate(updateCode, updateData);
-    }
-  }
-
-  #handleFastPathUpdate(updateCode, updateData) {
-    const reader = new Reader(updateData);
-
-    switch (updateCode) {
-      case 1: { // FASTPATH_UPDATETYPE_BITMAP
-        reader.u16le(); // updateType, repeated inside the update
-        const rects = parseBitmapUpdate(reader);
-        if (rects.length > 0) {
-          this.dispatchEvent(new CustomEvent('bitmap', { detail: { rects, palette: this.palette } }));
-        }
-        return;
-      }
-      case 2: // FASTPATH_UPDATETYPE_PALETTE
-        this.palette = parsePaletteUpdate(reader);
-        this.dispatchEvent(new CustomEvent('palette', { detail: this.palette }));
-        return;
-      case 5: // FASTPATH_UPDATETYPE_PTR_NULL
-        this.dispatchEvent(new CustomEvent('pointer', { detail: { kind: 'system', hidden: true } }));
-        return;
-      case 6: // FASTPATH_UPDATETYPE_PTR_DEFAULT
-        this.dispatchEvent(new CustomEvent('pointer', { detail: { kind: 'system', hidden: false } }));
-        return;
-      case 8: // FASTPATH_UPDATETYPE_PTR_POSITION
-        this.dispatchEvent(new CustomEvent('pointer', {
-          detail: { kind: 'position', x: reader.u16le(), y: reader.u16le() },
-        }));
-        return;
-      case 9:    // FASTPATH_UPDATETYPE_COLOR
-      case 0x0a: // FASTPATH_UPDATETYPE_CACHED
-      case 0x0b: { // FASTPATH_UPDATETYPE_POINTER
-        // The slow-path parser expects the message type these updates imply.
-        const messageType = { 9: 0x06, 0x0a: 0x07, 0x0b: 0x08 }[updateCode];
-        const header = new Uint8Array([messageType, 0x00, 0x00, 0x00]);
-        this.dispatchEvent(new CustomEvent('pointer', {
-          detail: parsePointerUpdate(new Reader(concatBytes(header, updateData))),
-        }));
-        return;
-      }
-      default:
-        return;
-    }
-  }
-
-  // --- virtual channels -----------------------------------------------------
-
-  #handleChannelData(name: string, bytes: Uint8Array) {
-    let reassembler = this.channelReassemblers.get(name);
-    if (!reassembler) {
-      reassembler = new ChannelReassembler();
-      this.channelReassemblers.set(name, reassembler);
-    }
-
-    const message = reassembler.push(bytes);
-    if (!message) return;
-
-    if (name === CLIPBOARD_CHANNEL.name) {
-      this.#clipboardChannel().receive(message);
-      return;
-    }
-
-    if (name === RAIL_CHANNEL.name) {
-      this.#railChannel().receive(message);
-    }
-  }
-
-  #sendVirtualChannel(name: string, bytes: Uint8Array) {
-    const channelId = [...this.channelNamesById].find(([, channelName]) => channelName === name)?.[0];
-    if (channelId === undefined) return false;
-
-    for (const chunk of chunkChannelData(bytes, CHANNEL_CHUNK_LENGTH, CHANNEL_FLAG_SHOW_PROTOCOL)) {
-      this.#send(sendDataRequest(this.userId, channelId, this.security.wrap(chunk)));
-    }
-    return true;
-  }
-
-  #railChannel() {
-    if (this.rail) return this.rail;
-
-    this.rail = new RailChannel({
-      application: this.options.remoteApp,
-      // The work area is what the host maximizes into, so it is the browser's
-      // room for the window rather than the whole negotiated desktop. A fit
-      // requested before the channel opened is already known here.
-      width: this.remoteAppFit?.width || this.desktopWidth,
-      height: this.remoteAppFit?.height || this.desktopHeight,
-      send: (bytes: Uint8Array) => this.#sendVirtualChannel(RAIL_CHANNEL.name, bytes),
-      onReady: ({ buildNumber, extended, flags }) => {
-        console.info('[RDP] RemoteApp channel ready', { buildNumber, extended: Boolean(extended), flags: flags || 0 });
-        this.dispatchEvent(new CustomEvent('remoteappready', {
-          detail: { application: this.options.remoteApp },
-        }));
-      },
-      onResult: (result) => {
-        const detail = { ...result, application: this.options.remoteApp };
-        this.dispatchEvent(new CustomEvent('remoteappresult', { detail }));
-        if (!result.ok) this.#fail(new Error(result.message));
-        else console.info('[RDP] Remote application launched', detail);
-      },
-    });
-
-    return this.rail;
-  }
-
-  /** Created on first use, so a host without the channel costs nothing. */
-  #clipboardChannel() {
-    if (this.clipboard) return this.clipboard;
-
-    this.clipboard = new ClipboardChannel({
-      send: (bytes: Uint8Array) => this.#sendVirtualChannel(CLIPBOARD_CHANNEL.name, bytes),
-      log: (step: number, detail) => console.info(`[RDP] ${step}`, detail),
-    });
-
-    this.clipboard.addEventListener('text', (event) => {
-      this.dispatchEvent(new CustomEvent('clipboard', { detail: event.detail }));
-    });
-
-    return this.clipboard;
-  }
-
-  /**
-   * Hand the host our clipboard text. Resolves once the host has acknowledged
-   * owning it, which is what makes it safe to send a paste keystroke next.
-   */
-  setClipboardText(text: string) {
-    if (!this.connected || !this.channelNamesById.size) return Promise.resolve(false);
-    return this.#clipboardChannel().setLocalText(text || '');
-  }
-
-  get clipboardShared() {
-    return Boolean(this.clipboard?.ready);
-  }
-
-  /**
-   * Deliver text into the session the way a person would: put it on the host's
-   * clipboard, wait for the host to acknowledge owning it, then press the paste
-   * shortcut. Waiting is what stops the keystroke from pasting the previous
-   * contents. A host with no clipboard channel gets the text typed instead.
-   */
-  pasteToHost(text: string) {
-    if (!text || !this.connected) return Promise.resolve(false);
-
-    const pressPaste = () => {
-      if (!this.connected) return;
-      this.sendKeyByCode('ControlLeft', true);
-      this.sendKeyByCode('KeyV', true);
-      this.sendKeyByCode('KeyV', false);
-      this.sendKeyByCode('ControlLeft', false);
-    };
-
-    return this.setClipboardText(text).then((acknowledged: boolean) => {
-      if (acknowledged) pressPaste();
-      else this.sendUnicode(text);
-      return true;
-    });
-  }
-
-  // --- outbound share PDUs --------------------------------------------------
-
-  #sendShareControl(pduType, payload: Uint8Array) {
-    this.#sendOnIoChannel(this.security.wrap(shareControlPdu(pduType, this.userId, payload)));
-  }
-
-  #sendShareData(pduType2, payload: Uint8Array) {
-    this.#sendOnIoChannel(
-      this.security.wrap(shareDataPdu(this.shareId, this.userId, pduType2, payload))
-    );
-  }
-
-  // --- input ----------------------------------------------------------------
-
-  get connected() {
-    return this.state === STATE.CONNECTED;
-  }
-
-  #sendInput(events) {
-    if (!this.connected || events.length === 0) return;
-    this.#sendShareData(PDU_TYPE2.INPUT, inputEventsPdu(events));
-  }
-
-  sendKeyByCode(code: number, pressed: boolean) {
-    const mapped = lookupScancode(code);
-    if (!mapped) return false;
-    this.#sendInput([scancodeEvent(mapped.scancode, pressed, mapped.extended)]);
-    return true;
-  }
-
-  sendUnicode(text: string) {
-    const events = [];
-    for (const character of text) {
-      for (let i = 0; i < character.length; i++) {
-        const unit = character.charCodeAt(i);
-        events.push(unicodeEvent(unit, true));
-        events.push(unicodeEvent(unit, false));
-      }
-    }
-    // Long pastes are split so no single PDU grows past the MCS limit.
-    for (let i = 0; i < events.length; i += 40) this.#sendInput(events.slice(i, i + 40));
-  }
-
-  sendCtrlAltDel() {
-    const events = CTRL_ALT_DEL.map(({ code, pressed }) => {
-      const mapped = lookupScancode(code);
-      return scancodeEvent(mapped.scancode, pressed, mapped.extended);
-    });
-    this.#sendInput(events);
-  }
-
-  sendMouseMove(x: number, y: number) {
-    this.#sendInput([mouseEvent(POINTER_FLAG.MOVE, x, y)]);
-  }
-
-  sendMouseButton(button: number, pressed: boolean, x: number, y: number) {
-    const buttonFlag = {
-      0: POINTER_FLAG.BUTTON1,
-      1: POINTER_FLAG.BUTTON3, // middle
-      2: POINTER_FLAG.BUTTON2, // right
-    }[button];
-
-    if (buttonFlag === undefined) {
-      // Buttons 4 and 5 (back / forward) travel as extended mouse events.
-      const extendedFlag = button === 3 ? 0x0001 : 0x0002;
-      this.#sendInput([extendedMouseEvent(extendedFlag | (pressed ? POINTER_FLAG.DOWN : 0), x, y)]);
-      return;
-    }
-
-    this.#sendInput([mouseEvent(buttonFlag | (pressed ? POINTER_FLAG.DOWN : 0), x, y)]);
-  }
-
-  sendWheel(delta: number, x: number, y: number, horizontal = false) {
-    const flags = pointerWheelFlags(delta, horizontal);
-    if (!flags) return;
-    this.#sendInput([mouseEvent(flags, x, y)]);
-  }
-
-  /** Tell the host which lock keys are already on, so they do not drift. */
-  sendKeyboardSync(toggleFlags: number) {
-    // Remembered so the idle keepalive restates the real state rather than
-    // quietly telling the host every lock key is off.
-    this.toggleFlags = toggleFlags >>> 0;
-    this.#sendInput([syncEvent(this.toggleFlags)]);
-  }
-
-  /** Ask the host to resend a region, used after the canvas is re-created. */
-  refresh(rect) {
-    if (!this.connected || !this.refreshRectSupported) return;
-    this.#sendShareData(PDU_TYPE2.REFRESH_RECT, refreshRectPdu([
-      rect || { left: 0, top: 0, right: this.desktopWidth - 1, bottom: this.desktopHeight - 1 },
-    ]));
-  }
-
-  /** Pause or resume host output, e.g. while the tab is hidden. */
-  setOutputEnabled(enabled: boolean) {
-    if (!this.connected) return;
-    this.#sendShareData(PDU_TYPE2.SUPPRESS_OUTPUT, suppressOutputPdu(enabled, {
-      left: 0,
-      top: 0,
-      right: this.desktopWidth - 1,
-      bottom: this.desktopHeight - 1,
-    }));
-  }
-}