ai-remote 0.1.0

package/src/protocols/rdp/client.ts

@@ -0,0 +1,1363 @@
+// 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',
+      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;
+
+    this.socket = 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,
+    }));
+  }
+}