ai-remote 0.1.0

package/src/protocols/rdp/display.ts

@@ -0,0 +1,750 @@
+// Canvas rendering and input capture for an RDP session.
+//
+// The host sends rectangles of pixels and a cursor shape; this module paints
+// them, maps browser events back into desktop coordinates, and turns key events
+// into the scancodes RDP expects.
+
+import { decodeBitmapRect } from './rle';
+import { TOGGLE_FLAG } from './pdu';
+
+/**
+ * On a Mac the editing shortcuts live on Command, and Windows expects them on
+ * Control. Sending Command through as the Windows key -- which is what its
+ * scancode means -- would make copy and paste unreachable, so it is translated
+ * instead. The Special Keys panel still sends a real Windows key.
+ */
+const IS_MAC = /Mac|iPod|iPhone|iPad/.test(
+  globalThis.navigator?.platform || globalThis.navigator?.userAgent || ''
+);
+
+const COMMAND_TO_CONTROL = {
+  MetaLeft: 'ControlLeft',
+  MetaRight: 'ControlRight',
+};
+
+// Trackpads emit many small wheel events. Waiting for roughly one line of
+// accumulated motion prevents each tiny event from becoming a full RDP notch.
+const WHEEL_STEP_PIXELS = 60;
+const WHEEL_LINE_PIXELS = 16;
+
+/** Two fingers dragged this far, per notch, count as one wheel click. */
+const TOUCH_SCROLL_STEP = 20;
+
+/**
+ * How far past "the whole desktop is visible" a pinch may go. Eight is well
+ * past readable on any phone; the floor of 1 is the fitted view, because
+ * zooming out beyond the window only adds letterboxing.
+ */
+const MAX_ZOOM = 8;
+const MIN_ZOOM = 1;
+
+
+export class RdpDisplay {
+  constructor(container) {
+    this.container = container;
+    this.canvas = document.createElement('canvas');
+    this.canvas.tabIndex = 0;
+    this.canvas.style.display = 'block';
+    this.canvas.style.position = 'absolute';
+    this.canvas.style.outline = 'none';
+    this.canvas.style.imageRendering = 'auto';
+    this.canvas.style.boxShadow = 'none';
+    this.context = this.canvas.getContext('2d', { alpha: false });
+
+    // The canvas is always the whole remote desktop, and this element decides
+    // how much of it is on screen. A full-desktop session shows all of it; a
+    // RemoteApp session shows only the application's own window, because
+    // RemoteApp paints nothing around it.
+    this.viewportElement = document.createElement('div');
+    this.viewportElement.style.position = 'relative';
+    this.viewportElement.style.overflow = 'hidden';
+    this.viewportElement.style.margin = 'auto';
+    this.viewportElement.style.background = '#000';
+    this.viewportElement.style.boxShadow = '0 10px 30px rgba(0, 0, 0, 0.8)';
+    this.viewportElement.appendChild(this.canvas);
+
+    container.replaceChildren(this.viewportElement);
+
+    // The element that actually scrolls when the desktop is larger than the
+    // window. `container` grows with its contents, so it is the wrong thing to
+    // measure the available space against.
+    this.scrollHost = container.parentElement || container;
+
+    this.width = 0;
+    this.height = 0;
+    this.viewport = { x: 0, y: 0, width: 0, height: 0 };
+    this.scale = 1;
+    this.scaleViewport = true;
+    // A multiplier on top of the fitted scale. 1 shows the whole desktop.
+    this.zoom = 1;
+    // Once the user has pinched, their zoom is theirs to keep: rotating the
+    // phone should not silently throw it away.
+    this.userZoomed = false;
+    this.viewOnly = false;
+    this.client = null;
+    this.palette = null;
+    this.cursorCache = new Map();
+    this.heldKeys = new Set();
+    this.keyboardSynced = false;
+
+    // Turning the phone changes which axis is the tight one; applyScale picks
+    // the opening zoom up again unless the user has since chosen their own.
+    this.onWindowResize = () => this.applyScale();
+    window.addEventListener('resize', this.onWindowResize);
+
+    // The workspace also changes width without the window changing at all --
+    // the SSH panel docking beside it, for one -- and no `resize` is fired for
+    // that, so the desktop would keep the scale it had before the panel opened.
+    this.resizeObserver = typeof ResizeObserver === 'function'
+      ? new ResizeObserver(() => this.applyScale())
+      : null;
+    this.resizeObserver?.observe(this.scrollHost);
+  }
+
+  resize(width: number, height: number) {
+    this.width = width;
+    this.height = height;
+    this.canvas.width = width;
+    this.canvas.height = height;
+
+    this.context.fillStyle = '#000';
+    this.context.fillRect(0, 0, width, height);
+    this.setViewport({ x: 0, y: 0, width, height });
+  }
+
+  /**
+   * Choose the part of the desktop that is on screen. Everything else about
+   * the session -- painting, input coordinates, the remote pointer -- keeps
+   * working in desktop coordinates, so only the framing changes here.
+   */
+  setViewport({ x = 0, y = 0, width, height } = {}) {
+    if (!this.width || !this.height) return;
+
+    const left = Math.max(0, Math.min(this.width - 1, Math.floor(x)));
+    const top = Math.max(0, Math.min(this.height - 1, Math.floor(y)));
+    this.viewport = {
+      x: left,
+      y: top,
+      width: Math.max(1, Math.min(this.width - left, Math.floor(width || this.width))),
+      height: Math.max(1, Math.min(this.height - top, Math.floor(height || this.height))),
+    };
+
+    // The toolbar reads the resolution off the canvas, and a screenshot of a
+    // RemoteApp session should be the window rather than the desktop it sits on.
+    this.canvas.dataset.viewport = [
+      this.viewport.x, this.viewport.y, this.viewport.width, this.viewport.height,
+    ].join(',');
+    this.applyScale();
+  }
+
+  /** The space a fitted desktop has to fit into: the window, not the content. */
+  #available() {
+    const host = this.scrollHost;
+    return {
+      width: host.clientWidth || this.container.clientWidth || 1,
+      height: host.clientHeight || this.container.clientHeight || 1,
+    };
+  }
+
+  /** The scale at which the whole desktop is on screen, letterboxed. */
+  #fitScale(available = this.#available()) {
+    const fitted = Math.min(
+      available.width / this.viewport.width,
+      available.height / this.viewport.height
+    );
+    return Number.isFinite(fitted) && fitted > 0 ? fitted : 1;
+  }
+
+  /**
+   * The zoom to open a session at.
+   *
+   * On a laptop the fitted view is the right one: the whole desktop is on
+   * screen and readable, and that is where this stays. On a phone it is not --
+   * a 1024x768 desktop fitted to a 375pt-wide window lands at about a third of
+   * full size, a band of unreadable pixels across the middle of a tall black
+   * screen. When fitting would land under LEGIBLE_SCALE the desktop is scaled
+   * to fill the window instead: the short edge matches exactly and the long one
+   * is panned. Everything is still reachable, and a pinch still gets back to
+   * the whole desktop. Legible first and complete second is the right way round
+   * on a screen this size.
+   */
+  #defaultZoom() {
+    return 1;
+  }
+
+  applyScale() {
+    if (!this.width || !this.height) return;
+    const viewport = this.viewport;
+
+    // Measured once and shared, so the zoom and the scale it multiplies can
+    // never come from two different layouts. Turning the phone fires `resize`
+    // while the new size is still settling, and reading it twice there is how
+    // the desktop ends up fitted on one axis and filled on the other.
+    const available = this.#available();
+    const fitted = this.#fitScale(available);
+    if (!this.userZoomed) this.zoom = this.#defaultZoom();
+
+    const scale = (this.scaleViewport ? fitted : 1) * this.zoom;
+    this.scale = scale;
+
+    // Sized in exact fractions of a pixel rather than whole ones: rounding the
+    // two axes apart is what makes a scaled desktop very slightly the wrong
+    // shape, which is visible as soon as the scale factor is small -- a phone
+    // fitting a 1024x768 desktop into 375 points, for instance.
+    this.viewportElement.style.width = `${viewport.width * scale}px`;
+    this.viewportElement.style.height = `${viewport.height * scale}px`;
+    this.canvas.style.width = `${this.width * scale}px`;
+    this.canvas.style.height = `${this.height * scale}px`;
+    this.canvas.style.left = `${-viewport.x * scale}px`;
+    this.canvas.style.top = `${-viewport.y * scale}px`;
+  }
+
+  /**
+   * Zoom about a point, keeping whatever is under it in place. `focal` is in
+   * client coordinates -- the midpoint between two fingers, usually.
+   */
+  setZoom(next, focal = null) {
+    const clamped = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, next));
+    if (!Number.isFinite(clamped) || clamped === this.zoom) return;
+
+    const host = this.scrollHost;
+    const before = this.scale;
+    const bounds = host.getBoundingClientRect();
+    const anchorX = focal ? focal.x - bounds.left : bounds.width / 2;
+    const anchorY = focal ? focal.y - bounds.top : bounds.height / 2;
+    const contentX = host.scrollLeft + anchorX;
+    const contentY = host.scrollTop + anchorY;
+
+    this.zoom = clamped;
+    this.applyScale();
+
+    const ratio = before > 0 ? this.scale / before : 1;
+    host.scrollLeft = contentX * ratio - anchorX;
+    host.scrollTop = contentY * ratio - anchorY;
+  }
+
+  /** Move the visible window over the desktop. Returns what it actually used. */
+  panBy(dx, dy) {
+    const host = this.scrollHost;
+    const beforeX = host.scrollLeft;
+    const beforeY = host.scrollTop;
+    host.scrollLeft = beforeX - dx;
+    host.scrollTop = beforeY - dy;
+    return {
+      x: beforeX - host.scrollLeft,
+      y: beforeY - host.scrollTop,
+    };
+  }
+
+  /** True when the desktop is larger than the window on either axis. */
+  canPan() {
+    if (this.zoom <= 1.05) return false;
+    const host = this.scrollHost;
+    return host.scrollWidth > host.clientWidth + 2 || host.scrollHeight > host.clientHeight + 2;
+  }
+
+  setScaleViewport(enabled: boolean) {
+    this.scaleViewport = enabled;
+    if (!enabled) this.userZoomed = false;
+    this.applyScale();
+  }
+
+  /** Back to the opening view: whole desktop fitted on screen. */
+  resetZoom() {
+    this.userZoomed = false;
+    this.zoom = 1;
+    this.applyScale();
+    const host = this.scrollHost;
+    host.scrollLeft = 0;
+    host.scrollTop = 0;
+  }
+
+  drawRects(rects, palette) {
+    if (palette) this.palette = palette;
+
+    for (const rect of rects) {
+      if (rect.width === 0 || rect.height === 0) continue;
+      try {
+        const rgba = decodeBitmapRect(rect, this.palette);
+        const image = new ImageData(rgba, rect.width, rect.height);
+        this.context.putImageData(image, rect.left, rect.top);
+      } catch (error) {
+        // One malformed rectangle must not kill the session; the next full
+        // update repaints the area anyway.
+        console.warn('[RDP] Dropped an undecodable bitmap rectangle', {
+          geometry: `${rect.width}x${rect.height}+${rect.left}+${rect.top}`,
+          bitsPerPixel: rect.bitsPerPixel,
+          compressed: rect.compressed,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+
+  // --- cursor ---------------------------------------------------------------
+
+  /**
+   * Turn an RDP pointer bitmap into a CSS cursor. RDP stores both masks
+   * bottom-up with rows padded to an even number of bytes, and a set AND-mask
+   * bit means "leave this pixel alone", which becomes transparency here.
+   */
+  #cursorFromPointer(pointer) {
+    const { width, height, xorBpp, xorMask, andMask, hotSpotX, hotSpotY } = pointer;
+    if (!width || !height) return null;
+
+    const xorBytesPerRow = Math.ceil((width * xorBpp) / 8 / 2) * 2;
+    const andBytesPerRow = Math.ceil(width / 8 / 2) * 2;
+    const rgba = new Uint8ClampedArray(width * height * 4);
+
+    for (let y = 0; y < height; y++) {
+      const sourceRow = height - 1 - y; // bottom-up
+      for (let x = 0; x < width; x++) {
+        const andByte = andMask[sourceRow * andBytesPerRow + (x >> 3)];
+        const transparent = andByte !== undefined && (andByte & (0x80 >> (x & 7))) !== 0;
+
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        let a = transparent ? 0 : 255;
+
+        if (xorBpp === 1) {
+          const bit = xorMask[sourceRow * xorBytesPerRow + (x >> 3)] & (0x80 >> (x & 7));
+          r = g = b = bit ? 255 : 0;
+        } else {
+          const bytesPerPixel = xorBpp / 8;
+          const offset = sourceRow * xorBytesPerRow + x * bytesPerPixel;
+          if (xorBpp === 16) {
+            const value = xorMask[offset] | (xorMask[offset + 1] << 8);
+            r = ((value >> 11) & 0x1f) * 255 / 31;
+            g = ((value >> 5) & 0x3f) * 255 / 63;
+            b = (value & 0x1f) * 255 / 31;
+          } else {
+            b = xorMask[offset] || 0;
+            g = xorMask[offset + 1] || 0;
+            r = xorMask[offset + 2] || 0;
+            if (xorBpp === 32 && xorMask[offset + 3] !== undefined && andMask.length === 0) {
+              a = xorMask[offset + 3];
+            }
+          }
+        }
+
+        const target = (y * width + x) * 4;
+        rgba[target] = r;
+        rgba[target + 1] = g;
+        rgba[target + 2] = b;
+        rgba[target + 3] = a;
+      }
+    }
+
+    const cursorCanvas = document.createElement('canvas');
+    cursorCanvas.width = width;
+    cursorCanvas.height = height;
+    cursorCanvas.getContext('2d').putImageData(new ImageData(rgba, width, height), 0, 0);
+
+    const hotX = Math.min(hotSpotX || 0, width - 1);
+    const hotY = Math.min(hotSpotY || 0, height - 1);
+    return `url(${cursorCanvas.toDataURL('image/png')}) ${hotX} ${hotY}, default`;
+  }
+
+  applyPointer(pointer) {
+    if (pointer.kind === 'system') {
+      this.canvas.style.cursor = pointer.hidden ? 'none' : 'default';
+      return;
+    }
+
+    if (pointer.kind === 'position') {
+      // Host-driven pointer warps cannot move the real mouse; ignore them and
+      // let the local pointer stay where the user put it.
+      return;
+    }
+
+    if (pointer.kind === 'cached') {
+      const cached = this.cursorCache.get(pointer.cacheIndex);
+      if (cached) this.canvas.style.cursor = cached;
+      return;
+    }
+
+    if (pointer.kind === 'bitmap') {
+      try {
+        const cursor = this.#cursorFromPointer(pointer);
+        if (!cursor) return;
+        this.cursorCache.set(pointer.cacheIndex, cursor);
+        this.canvas.style.cursor = cursor;
+      } catch (error) {
+        console.warn('[RDP] Could not build a cursor from the host pointer update', error);
+      }
+    }
+  }
+
+  // --- input ----------------------------------------------------------------
+
+  #toRemote(event) {
+    const bounds = this.canvas.getBoundingClientRect();
+    const scaleX = this.width / (bounds.width || 1);
+    const scaleY = this.height / (bounds.height || 1);
+    return {
+      x: Math.max(0, Math.min(this.width - 1, (event.clientX - bounds.left) * scaleX)),
+      y: Math.max(0, Math.min(this.height - 1, (event.clientY - bounds.top) * scaleY)),
+    };
+  }
+
+  #syncKeyboardOnce(event) {
+    if (this.keyboardSynced || !this.client) return;
+    this.keyboardSynced = true;
+
+    let flags = 0;
+    if (event.getModifierState?.('CapsLock')) flags |= TOGGLE_FLAG.CAPS_LOCK;
+    if (event.getModifierState?.('NumLock')) flags |= TOGGLE_FLAG.NUM_LOCK;
+    if (event.getModifierState?.('ScrollLock')) flags |= TOGGLE_FLAG.SCROLL_LOCK;
+    this.client.sendKeyboardSync(flags);
+  }
+
+  attachInput(client) {
+    this.client = client;
+    this.keyboardSynced = false;
+
+    const canSend = () => this.client && this.client.connected && !this.viewOnly;
+
+    let pendingMove = null;
+    let moveScheduled = false;
+    let pendingWheelDelta = 0;
+    let touchIsDown = false;
+    let lastTouchX = 0;
+    let lastTouchY = 0;
+    let lastTouchScrollY = 0;
+    let lastTouchScrollX = 0;
+    let gestureStartMid = { x: 0, y: 0 };
+    let gestureStartDistance = 0;
+    let lastPinchDistance = 0;
+    let pendingTouchWheelDelta = 0;
+    let touchMode = null;
+
+    const touchMidpoint = (touches) => ({
+      x: (touches[0].clientX + touches[1].clientX) / 2,
+      y: (touches[0].clientY + touches[1].clientY) / 2,
+    });
+
+    const touchDistance = (touches) => Math.hypot(
+      touches[0].clientX - touches[1].clientX,
+      touches[0].clientY - touches[1].clientY
+    );
+    const flushMove = () => {
+      moveScheduled = false;
+      if (pendingMove && canSend()) this.client.sendMouseMove(pendingMove.x, pendingMove.y);
+      pendingMove = null;
+    };
+
+    this.handlers = {
+      mousemove: (event) => {
+        if (!canSend()) return;
+        pendingMove = this.#toRemote(event);
+        if (!moveScheduled) {
+          moveScheduled = true;
+          requestAnimationFrame(flushMove);
+        }
+      },
+      mousedown: (event) => {
+        this.canvas.focus();
+        if (!canSend()) return;
+        event.preventDefault();
+        const { x, y } = this.#toRemote(event);
+        this.client.sendMouseButton(event.button, true, x, y);
+      },
+      mouseup: (event) => {
+        if (!canSend()) return;
+        event.preventDefault();
+        const { x, y } = this.#toRemote(event);
+        this.client.sendMouseButton(event.button, false, x, y);
+      },
+      contextmenu: (event) => event.preventDefault(),
+      wheel: (event) => {
+        if (!canSend()) return;
+        event.preventDefault();
+
+        let delta = event.deltaY;
+        if (event.deltaMode === WheelEvent.DOM_DELTA_LINE) delta *= WHEEL_LINE_PIXELS;
+        if (event.deltaMode === WheelEvent.DOM_DELTA_PAGE) {
+          delta *= Math.max(1, this.canvas.clientHeight || this.height);
+        }
+        if (!delta) return;
+
+        // Do not let a partial gesture in one direction accelerate the next
+        // gesture in the opposite direction.
+        if (pendingWheelDelta && Math.sign(pendingWheelDelta) !== Math.sign(delta)) {
+          pendingWheelDelta = 0;
+        }
+        pendingWheelDelta += delta;
+        if (Math.abs(pendingWheelDelta) < WHEEL_STEP_PIXELS) return;
+
+        const direction = Math.sign(pendingWheelDelta);
+        pendingWheelDelta -= direction * WHEEL_STEP_PIXELS;
+        const { x, y } = this.#toRemote(event);
+        this.client.sendWheel(direction, x, y);
+      },
+      touchstart: (event) => {
+        this.canvas.focus();
+        if (!canSend()) return;
+        event.preventDefault();
+
+        if (event.touches.length === 1) {
+          touchMode = 'tap';
+          const touch = event.touches[0];
+          lastTouchX = touch.clientX;
+          lastTouchY = touch.clientY;
+          const { x, y } = this.#toRemote(touch);
+          this.client.sendMouseMove(x, y);
+          this.client.sendMouseButton(0, true, x, y);
+          touchIsDown = true;
+        } else if (event.touches.length === 2) {
+          touchMode = 'undecided';
+          if (touchIsDown) {
+            const { x, y } = this.#toRemote({ clientX: lastTouchX, clientY: lastTouchY });
+            this.client.sendMouseButton(0, false, x, y);
+            touchIsDown = false;
+          }
+          const mid = touchMidpoint(event.touches);
+          const dist = touchDistance(event.touches);
+          gestureStartMid = { x: mid.x, y: mid.y };
+          gestureStartDistance = dist;
+          lastTouchScrollY = mid.y;
+          lastTouchScrollX = mid.x;
+          lastPinchDistance = dist;
+          pendingTouchWheelDelta = 0;
+        }
+      },
+      touchmove: (event) => {
+        if (!canSend()) return;
+        event.preventDefault();
+
+        if (event.touches.length === 1 && touchMode === 'tap') {
+          const touch = event.touches[0];
+          lastTouchX = touch.clientX;
+          lastTouchY = touch.clientY;
+          const { x, y } = this.#toRemote(touch);
+          this.client.sendMouseMove(x, y);
+        } else if (event.touches.length === 2) {
+          const mid = touchMidpoint(event.touches);
+          const currX = mid.x;
+          const currY = mid.y;
+          const distance = touchDistance(event.touches);
+          const deltaY = lastTouchScrollY - currY;
+          const deltaX = lastTouchScrollX - currX;
+          lastTouchScrollY = currY;
+          lastTouchScrollX = currX;
+
+          const totalMove = Math.hypot(currX - gestureStartMid.x, currY - gestureStartMid.y);
+          const pinchDelta = Math.abs(distance - gestureStartDistance);
+          const pinchRatio = gestureStartDistance > 0 ? distance / gestureStartDistance : 1;
+
+          if (touchMode === 'undecided' || touchMode === 'gesture') {
+            // Disambiguate between pinch-to-zoom and two-finger scroll
+            if (pinchDelta > 20 && Math.abs(pinchRatio - 1) > 0.15 && pinchDelta > totalMove * 0.8) {
+              touchMode = 'pinch';
+            } else if (totalMove > 8) {
+              touchMode = 'scroll';
+            }
+          }
+
+          if (touchMode === 'pinch') {
+            if (lastPinchDistance > 0 && Math.abs(distance - lastPinchDistance) > 1) {
+              this.userZoomed = true;
+              this.setZoom(this.zoom * (distance / lastPinchDistance), { x: currX, y: currY });
+            }
+            lastPinchDistance = distance;
+          } else if (touchMode === 'scroll') {
+            lastPinchDistance = distance;
+
+            // A zoomed-in desktop pans; a fitted desktop turns the remote mouse wheel.
+            if (this.canPan()) {
+              this.panBy(deltaX * -1, deltaY * -1);
+              pendingTouchWheelDelta = 0;
+              return;
+            }
+
+            if (deltaY && pendingTouchWheelDelta
+              && Math.sign(pendingTouchWheelDelta) !== Math.sign(deltaY)) {
+              pendingTouchWheelDelta = 0;
+            }
+            pendingTouchWheelDelta += deltaY;
+
+            while (Math.abs(pendingTouchWheelDelta) >= TOUCH_SCROLL_STEP) {
+              const direction = Math.sign(pendingTouchWheelDelta);
+              pendingTouchWheelDelta -= direction * TOUCH_SCROLL_STEP;
+              const { x, y } = this.#toRemote({ clientX: currX, clientY: currY });
+              this.client.sendWheel(direction, x, y);
+            }
+          }
+        }
+      },
+      touchend: (event) => {
+        if (!canSend()) return;
+        event.preventDefault();
+
+        if (event.touches.length === 0) {
+          if (touchIsDown) {
+            const { x, y } = this.#toRemote({ clientX: lastTouchX, clientY: lastTouchY });
+            this.client.sendMouseButton(0, false, x, y);
+            touchIsDown = false;
+          }
+          if (touchMode === 'pinch' && this.zoom <= 1.05) {
+            this.resetZoom();
+          }
+          touchMode = null;
+          pendingTouchWheelDelta = 0;
+          lastPinchDistance = 0;
+        } else if (event.touches.length === 1) {
+          // A finger lifted mid-gesture leaves one behind that was never a tap;
+          // letting it fall through would press the mouse where it happens to
+          // rest. The gesture ends here and the stray finger is ignored.
+          if (touchMode === 'gesture' || touchMode === 'pinch' || touchMode === 'scroll' || touchMode === 'undecided') {
+            if (touchMode === 'pinch' && this.zoom <= 1.05) {
+              this.resetZoom();
+            }
+            touchMode = null;
+            lastPinchDistance = 0;
+            pendingTouchWheelDelta = 0;
+          }
+        }
+      },
+      touchcancel: (event) => {
+        if (!canSend()) return;
+        if (touchIsDown) {
+          const { x, y } = this.#toRemote({ clientX: lastTouchX, clientY: lastTouchY });
+          this.client.sendMouseButton(0, false, x, y);
+          touchIsDown = false;
+        }
+        if (touchMode === 'pinch' && this.zoom <= 1.05) {
+          this.resetZoom();
+        }
+        touchMode = null;
+        pendingTouchWheelDelta = 0;
+        lastPinchDistance = 0;
+      },
+      keydown: (event) => {
+        if (!canSend()) return;
+        this.#syncKeyboardOnce(event);
+
+        // Paste is the browser's to deliver: preventing the default here would
+        // stop the paste event that carries the text the host is about to ask
+        // for. The keystroke is sent from the paste handler instead.
+        if (this.#isPasteShortcut(event)) return;
+
+        const code = this.#translateCode(event.code);
+        if (!this.client.sendKeyByCode(code, true)) return;
+        event.preventDefault();
+
+        // macOS withholds keyup while Command is held, which would leave the
+        // key stuck down on the host. Releasing it at once is the only way to
+        // keep the shortcut from repeating forever.
+        if (IS_MAC && event.metaKey && !COMMAND_TO_CONTROL[event.code]) {
+          this.client.sendKeyByCode(code, false);
+          return;
+        }
+
+        this.heldKeys.add(code);
+      },
+      keyup: (event) => {
+        if (!canSend()) return;
+        if (this.#isPasteShortcut(event)) return;
+
+        const code = this.#translateCode(event.code);
+        if (this.client.sendKeyByCode(code, false)) {
+          this.heldKeys.delete(code);
+          event.preventDefault();
+        }
+      },
+      paste: (event) => {
+        if (!canSend()) return;
+
+        /**
+         * Only when the screen is what is being pasted into.
+         *
+         * This listener is on the document because a canvas cannot receive a
+         * paste event of its own -- which means *every* paste in the page
+         * arrives here, including one typed into the assistant's message box or
+         * a password field. Without this guard the text went two places at
+         * once: into the box the user was looking at, and into whatever window
+         * happened to be open on the far machine.
+         *
+         * Focus is the test. The remote screen holds it when the remote screen
+         * is what you are working in, and nothing else does at the same time.
+         * (The terminal never had this problem because xterm stops the event
+         * from propagating; a text field cannot be relied on to do that.)
+         */
+        const target = event.target;
+        const onTheScreen = target instanceof Node && this.container.contains(target);
+        if (document.activeElement !== this.canvas && !onTheScreen) return;
+
+        event.preventDefault();
+        const text = event.clipboardData?.getData('text/plain') || '';
+        if (text) this.client.pasteToHost(text);
+      },
+      blur: () => this.releaseAllKeys(),
+    };
+
+    this.canvas.addEventListener('mousemove', this.handlers.mousemove);
+    this.canvas.addEventListener('mousedown', this.handlers.mousedown);
+    this.canvas.addEventListener('mouseup', this.handlers.mouseup);
+    this.canvas.addEventListener('contextmenu', this.handlers.contextmenu);
+    this.canvas.addEventListener('wheel', this.handlers.wheel, { passive: false });
+    this.canvas.addEventListener('touchstart', this.handlers.touchstart, { passive: false });
+    this.canvas.addEventListener('touchmove', this.handlers.touchmove, { passive: false });
+    this.canvas.addEventListener('touchend', this.handlers.touchend, { passive: false });
+    this.canvas.addEventListener('touchcancel', this.handlers.touchcancel, { passive: false });
+    this.canvas.addEventListener('keydown', this.handlers.keydown);
+    this.canvas.addEventListener('keyup', this.handlers.keyup);
+    this.canvas.addEventListener('blur', this.handlers.blur);
+    // A canvas is not editable, so the paste event lands on the document. The
+    // handler checks that the canvas has focus before treating it as its own.
+    document.addEventListener('paste', this.handlers.paste);
+  }
+
+  /** Command on a Mac stands in for Control everywhere the host is concerned. */
+  #translateCode(code: number) {
+    return IS_MAC ? COMMAND_TO_CONTROL[code] || code : code;
+  }
+
+  #isPasteShortcut(event) {
+    if (event.code !== 'KeyV') return false;
+    return IS_MAC ? event.metaKey : event.ctrlKey;
+  }
+
+  /** A key held while focus moves away would otherwise stay down on the host. */
+  releaseAllKeys() {
+    if (!this.client) return;
+    for (const code of this.heldKeys) this.client.sendKeyByCode(code, false);
+    this.heldKeys.clear();
+  }
+
+  focus() {
+    this.canvas.focus();
+  }
+
+  blur() {
+    this.canvas.blur();
+  }
+
+  destroy() {
+    this.releaseAllKeys();
+    window.removeEventListener('resize', this.onWindowResize);
+    this.resizeObserver?.disconnect();
+
+    if (this.handlers) {
+      this.canvas.removeEventListener('mousemove', this.handlers.mousemove);
+      this.canvas.removeEventListener('mousedown', this.handlers.mousedown);
+      this.canvas.removeEventListener('mouseup', this.handlers.mouseup);
+      this.canvas.removeEventListener('contextmenu', this.handlers.contextmenu);
+      this.canvas.removeEventListener('wheel', this.handlers.wheel);
+      this.canvas.removeEventListener('touchstart', this.handlers.touchstart);
+      this.canvas.removeEventListener('touchmove', this.handlers.touchmove);
+      this.canvas.removeEventListener('touchend', this.handlers.touchend);
+      this.canvas.removeEventListener('touchcancel', this.handlers.touchcancel);
+      this.canvas.removeEventListener('keydown', this.handlers.keydown);
+      this.canvas.removeEventListener('keyup', this.handlers.keyup);
+      this.canvas.removeEventListener('blur', this.handlers.blur);
+      document.removeEventListener('paste', this.handlers.paste);
+    }
+
+    this.client = null;
+  }
+}