@push.rocks/smartbrowser 2.0.10 → 3.0.0

package/ts_web/classes.livebrowsercanvasrenderer.ts

@@ -0,0 +1,1388 @@
+import type {
+  ILiveBrowserFrame,
+  ILiveBrowserInputBase,
+  ILiveBrowserKeyInput,
+  ILiveBrowserModifierState,
+  ILiveBrowserMouseInput,
+  ILiveBrowserState,
+  ILiveBrowserViewport,
+  TLiveBrowserEvent,
+} from '@push.rocks/smartpuppeteer';
+
+import type {
+  ILiveBrowserCanvasError,
+  ILiveBrowserCanvasRendererOptions,
+  TLiveBrowserCanvasErrorCode,
+} from './interfaces.livebrowsercanvas.js';
+
+const maxInputQueueLength = 128;
+const maxPendingAcknowledgements = 16;
+const maxInputReleaseAttempts = 2;
+const coordinateEdgeInset = 0.001;
+const defaultOperationTimeoutMs = 10000;
+
+class LiveBrowserOperationTimeoutError extends Error {}
+
+interface IFrameWork {
+  frame: ILiveBrowserFrame;
+  runEpoch: number;
+  acknowledgementAttempted: boolean;
+}
+
+interface IDisplayedFrame extends ILiveBrowserInputBase {
+  sequence: number;
+  viewport: ILiveBrowserViewport;
+}
+
+type TInputCommandKind = 'key' | 'mouse' | 'mouseMove' | 'text' | 'wheel';
+
+interface IInputCommand {
+  kind: TInputCommandKind;
+  runEpoch: number;
+  execute: () => Promise<void>;
+  onAttempt?: () => void;
+  onSuccess?: () => void;
+  resolve: () => void;
+  reject: (errorArg: unknown) => void;
+}
+
+interface IResizeFence {
+  minimumViewportRevision: number;
+  target: ILiveBrowserViewport;
+}
+
+const viewportEquals = (
+  firstArg: ILiveBrowserViewport,
+  secondArg: ILiveBrowserViewport,
+): boolean => (
+  firstArg.width === secondArg.width
+  && firstArg.height === secondArg.height
+  && firstArg.deviceScaleFactor === secondArg.deviceScaleFactor
+);
+
+const createModifiers = (
+  eventArg: MouseEvent | KeyboardEvent,
+): ILiveBrowserModifierState => ({
+  alt: eventArg.altKey,
+  control: eventArg.ctrlKey,
+  meta: eventArg.metaKey,
+  shift: eventArg.shiftKey,
+});
+
+const createFrameAcknowledgementRequest = (frameArg: ILiveBrowserFrame) => ({
+  tabId: frameArg.tabId,
+  sequence: frameArg.sequence,
+  generation: frameArg.generation,
+  viewportRevision: frameArg.viewportRevision,
+});
+
+const createInputIdentity = (displayedFrameArg: IDisplayedFrame): ILiveBrowserInputBase => ({
+  tabId: displayedFrameArg.tabId,
+  generation: displayedFrameArg.generation,
+  viewportRevision: displayedFrameArg.viewportRevision,
+});
+
+const getErrorMessage = (errorArg: unknown): string => (
+  errorArg instanceof Error ? errorArg.message : String(errorArg)
+);
+
+/**
+ * Renders transport-neutral live browser frames and maps DOM input back to the
+ * currently displayed SmartPuppeteer frame identity.
+ */
+export class LiveBrowserCanvasRenderer {
+  private readonly canvas: HTMLCanvasElement;
+  private readonly canvasContext: CanvasRenderingContext2D;
+  private readonly client: ILiveBrowserCanvasRendererOptions['client'];
+  private readonly focusTarget: HTMLElement;
+  private readonly resizeTarget?: Element;
+  private readonly getDeviceScaleFactor: () => number;
+  private readonly operationTimeoutMs: number;
+  private readonly frameDecodeTimeoutMs: number;
+  private readonly onError?: ILiveBrowserCanvasRendererOptions['onError'];
+  private readonly onFrameRendered?: ILiveBrowserCanvasRendererOptions['onFrameRendered'];
+  private readonly initialCanvasWidth: number;
+  private readonly initialCanvasHeight: number;
+
+  private lifecycleTail: Promise<void> = Promise.resolve();
+  private runEpoch = 0;
+  private running = false;
+  private stopping = false;
+  private stopRequested = false;
+  private terminallyStopped = false;
+  private acceptingFrames = false;
+  private state?: ILiveBrowserState;
+  private unsubscribe?: () => void;
+  private listenerController?: AbortController;
+  private resizeObserver?: ResizeObserver;
+  private focusWasAdjusted = false;
+  private focusHadTabIndex = false;
+  private focusTabIndexValue: string | null = null;
+
+  private displayedFrame?: IDisplayedFrame;
+  private highestFrameSequence = -1;
+  private queuedFrame?: IFrameWork;
+  private frameProcessingPromise?: Promise<void>;
+  private acknowledgementPromises = new Set<Promise<void>>();
+
+  private inputBlocked = true;
+  private inputCommands: IInputCommand[] = [];
+  private inputProcessing = false;
+  private inputIdleResolvers: Array<() => void> = [];
+  private inputResetTail: Promise<void> = Promise.resolve();
+  private inputResetPromise?: Promise<void>;
+  private inputResetCount = 0;
+  private inputOverflowRecoveryPending = false;
+  private pressedKeys = new Map<string, ILiveBrowserKeyInput>();
+  private pressedMouseButtons = new Map<string, ILiveBrowserMouseInput>();
+  private capturedPointerIds = new Set<number>();
+
+  private pendingViewport?: ILiveBrowserViewport;
+  private inFlightViewport?: ILiveBrowserViewport;
+  private viewportProcessing = false;
+  private viewportProcessingPromise?: Promise<void>;
+  private resizeFence?: IResizeFence;
+
+  constructor(optionsArg: ILiveBrowserCanvasRendererOptions) {
+    this.canvas = optionsArg.canvas;
+    this.client = optionsArg.client;
+    this.focusTarget = optionsArg.focusTarget ?? this.canvas;
+    this.resizeTarget = optionsArg.resizeTarget;
+    this.getDeviceScaleFactor = optionsArg.getDeviceScaleFactor
+      ?? (() => window.devicePixelRatio || 1);
+    this.operationTimeoutMs = this.validateTimeout(
+      optionsArg.operationTimeoutMs ?? defaultOperationTimeoutMs,
+      'operationTimeoutMs',
+    );
+    this.frameDecodeTimeoutMs = this.validateTimeout(
+      optionsArg.frameDecodeTimeoutMs ?? this.operationTimeoutMs,
+      'frameDecodeTimeoutMs',
+    );
+    this.onError = optionsArg.onError;
+    this.onFrameRendered = optionsArg.onFrameRendered;
+    this.initialCanvasWidth = this.canvas.width;
+    this.initialCanvasHeight = this.canvas.height;
+
+    const canvasContext = this.canvas.getContext('2d');
+    if (!canvasContext) {
+      throw new Error('LiveBrowserCanvasRenderer requires a 2D canvas context');
+    }
+    this.canvasContext = canvasContext;
+  }
+
+  public get isRunning(): boolean {
+    return this.running;
+  }
+
+  public start(): Promise<void> {
+    return this.enqueueLifecycle(async () => {
+      if (this.terminallyStopped) {
+        throw new Error(
+          'Live browser renderer cannot restart after a terminal operation failure; create a new renderer and client',
+        );
+      }
+      if (this.running) {
+        return;
+      }
+
+      const runEpoch = ++this.runEpoch;
+      this.running = true;
+      this.stopping = false;
+      this.stopRequested = false;
+      this.acceptingFrames = true;
+      this.inputBlocked = true;
+      this.highestFrameSequence = -1;
+
+      try {
+        this.makeFocusTargetFocusable();
+        this.installDomListeners(runEpoch);
+        this.unsubscribe = this.client.onEvent((eventArg) => {
+          this.handleEvent(eventArg, runEpoch);
+        });
+        this.applyState(this.client.getState(), runEpoch);
+        this.installResizeObserver(runEpoch);
+      } catch (error) {
+        await this.stopRun(runEpoch);
+        throw error;
+      }
+    });
+  }
+
+  public stop(): Promise<void> {
+    return this.enqueueLifecycle(async () => {
+      if (!this.running) {
+        return;
+      }
+      await this.stopRun(this.runEpoch);
+    });
+  }
+
+  /**
+   * Sends arbitrary committed text, including text produced by an external IME.
+   */
+  public async insertText(textArg: string): Promise<void> {
+    const displayedFrame = this.requireInputFrame();
+    const inputIdentity = createInputIdentity(displayedFrame);
+    await this.enqueueInputCommand({
+      kind: 'text',
+      runEpoch: this.runEpoch,
+      execute: async () => {
+        await this.client.insertText({
+          ...inputIdentity,
+          text: textArg,
+        });
+      },
+    });
+  }
+
+  /**
+   * Reads the configured stable resize target and requests the corresponding
+   * remote CSS viewport. Intrinsic canvas dimensions are never used here.
+   */
+  public syncViewport(): void {
+    if (!this.running || this.stopping || this.stopRequested || !this.resizeTarget) {
+      return;
+    }
+    const width = Math.floor(this.resizeTarget.clientWidth);
+    const height = Math.floor(this.resizeTarget.clientHeight);
+    this.queueViewport(width, height, this.runEpoch);
+  }
+
+  private enqueueLifecycle(operationArg: () => Promise<void>): Promise<void> {
+    const operation = this.lifecycleTail.then(operationArg, operationArg);
+    this.lifecycleTail = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  private async stopRun(runEpochArg: number): Promise<void> {
+    this.stopping = true;
+    this.acceptingFrames = false;
+    this.inputBlocked = true;
+    this.pendingViewport = undefined;
+    this.releasePointerCaptures();
+
+    try {
+      this.resizeObserver?.disconnect();
+      this.resizeObserver = undefined;
+      this.listenerController?.abort();
+      this.listenerController = undefined;
+      const unsubscribe = this.unsubscribe;
+      this.unsubscribe = undefined;
+      if (unsubscribe) {
+        try {
+          unsubscribe();
+        } catch (error) {
+          this.reportError({
+            code: 'renderer_cleanup_failed',
+            message: `Could not unsubscribe the live browser renderer: ${getErrorMessage(error)}`,
+            cause: error,
+          }, runEpochArg);
+        }
+      }
+
+      if (this.queuedFrame) {
+        const queuedFrame = this.queuedFrame;
+        this.queuedFrame = undefined;
+        await this.acknowledgeFrame(queuedFrame);
+      }
+
+      await this.viewportProcessingPromise;
+      await this.inputResetTail;
+      await this.waitForInputIdle();
+      await this.releasePressedInput(runEpochArg);
+
+      this.running = false;
+      await this.frameProcessingPromise;
+      await Promise.all([...this.acknowledgementPromises]);
+    } finally {
+      this.running = false;
+      this.acceptingFrames = false;
+      this.state = undefined;
+      this.displayedFrame = undefined;
+      this.resizeFence = undefined;
+      this.pendingViewport = undefined;
+      this.inFlightViewport = undefined;
+      this.viewportProcessing = false;
+      this.inputResetPromise = undefined;
+      this.inputBlocked = true;
+      this.pressedKeys.clear();
+      this.pressedMouseButtons.clear();
+      this.releasePointerCaptures();
+      const abandonedCommands = this.inputCommands.splice(0);
+      for (const command of abandonedCommands) {
+        command.reject(new Error('Live browser renderer stopped before dispatching input'));
+      }
+      const inputIdleResolvers = this.inputIdleResolvers;
+      this.inputIdleResolvers = [];
+      for (const resolver of inputIdleResolvers) {
+        resolver();
+      }
+      this.canvas.width = this.initialCanvasWidth;
+      this.canvas.height = this.initialCanvasHeight;
+      this.restoreFocusTarget();
+      this.stopRequested = false;
+      this.stopping = false;
+    }
+  }
+
+  private installDomListeners(runEpochArg: number): void {
+    const listenerController = new AbortController();
+    const signal = listenerController.signal;
+    this.listenerController = listenerController;
+
+    this.canvas.addEventListener('pointerdown', (eventArg) => {
+      this.handlePointerDown(eventArg, runEpochArg);
+    }, { signal });
+    this.canvas.addEventListener('pointermove', (eventArg) => {
+      this.handlePointerMove(eventArg, runEpochArg);
+    }, { signal });
+    this.canvas.addEventListener('pointerup', (eventArg) => {
+      this.handlePointerUp(eventArg, runEpochArg);
+    }, { signal });
+    this.canvas.addEventListener('pointercancel', (eventArg) => {
+      this.releasePointerCapture(eventArg.pointerId);
+      void this.scheduleInputReset(false, runEpochArg);
+    }, { signal });
+    this.canvas.addEventListener('lostpointercapture', (eventArg) => {
+      this.capturedPointerIds.delete(eventArg.pointerId);
+      if (this.pressedMouseButtons.size > 0) {
+        void this.scheduleInputReset(false, runEpochArg);
+      }
+    }, { signal });
+    this.canvas.addEventListener('contextmenu', (eventArg) => {
+      eventArg.preventDefault();
+    }, { signal });
+    this.canvas.addEventListener('wheel', (eventArg) => {
+      this.handleWheel(eventArg, runEpochArg);
+    }, { passive: false, signal });
+
+    this.focusTarget.addEventListener('keydown', (eventArg) => {
+      this.handleKey(eventArg, 'down', runEpochArg);
+    }, { signal });
+    this.focusTarget.addEventListener('keyup', (eventArg) => {
+      this.handleKey(eventArg, 'up', runEpochArg);
+    }, { signal });
+    this.focusTarget.addEventListener('compositionend', (eventArg) => {
+      if (!this.inputBlocked && eventArg.data) {
+        void this.insertText(eventArg.data).catch(() => undefined);
+      }
+    }, { signal });
+
+    window.addEventListener('blur', () => {
+      void this.scheduleInputReset(false, runEpochArg);
+    }, { signal });
+    window.addEventListener('resize', () => {
+      this.syncViewport();
+    }, { signal });
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'hidden') {
+        void this.scheduleInputReset(false, runEpochArg);
+      }
+    }, { signal });
+  }
+
+  private installResizeObserver(runEpochArg: number): void {
+    if (!this.resizeTarget) {
+      return;
+    }
+    this.resizeObserver = new ResizeObserver((entriesArg) => {
+      const matchingEntry = entriesArg.find((entryArg) => entryArg.target === this.resizeTarget);
+      if (!matchingEntry) {
+        return;
+      }
+      this.queueViewport(
+        Math.floor(matchingEntry.contentRect.width),
+        Math.floor(matchingEntry.contentRect.height),
+        runEpochArg,
+      );
+    });
+    this.resizeObserver.observe(this.resizeTarget);
+    this.syncViewport();
+  }
+
+  private handleEvent(eventArg: TLiveBrowserEvent, runEpochArg: number): void {
+    if (eventArg.type === 'frame') {
+      this.queueFrame(eventArg.frame, runEpochArg);
+      return;
+    }
+    if (!this.running || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    if (eventArg.type === 'state') {
+      this.applyState(eventArg.state, runEpochArg);
+      return;
+    }
+    this.reportError({
+      code: 'remote_browser_error',
+      message: `${eventArg.error.code}: ${eventArg.error.message}`,
+      cause: eventArg.error,
+    }, runEpochArg);
+  }
+
+  private applyState(stateArg: ILiveBrowserState, runEpochArg: number): void {
+    if (!this.running || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    this.state = stateArg;
+
+    if (this.displayedFrame && this.isStateAheadOfDisplayedFrame(stateArg, this.displayedFrame)) {
+      this.displayedFrame = undefined;
+      this.clearCanvas();
+      void this.scheduleInputReset(false, runEpochArg);
+      return;
+    }
+    this.updateInputAvailability();
+  }
+
+  private isStateAheadOfDisplayedFrame(
+    stateArg: ILiveBrowserState,
+    displayedFrameArg: IDisplayedFrame,
+  ): boolean {
+    if (stateArg.status !== 'running' || stateArg.activeTabId !== displayedFrameArg.tabId) {
+      return true;
+    }
+    const activeTab = stateArg.tabs.find((tabArg) => tabArg.id === displayedFrameArg.tabId);
+    if (!activeTab || activeTab.status !== 'open') {
+      return true;
+    }
+    return stateArg.viewportRevision > displayedFrameArg.viewportRevision
+      || activeTab.generation > displayedFrameArg.generation;
+  }
+
+  private queueFrame(frameArg: ILiveBrowserFrame, runEpochArg: number): void {
+    const frameWork: IFrameWork = {
+      frame: frameArg,
+      runEpoch: runEpochArg,
+      acknowledgementAttempted: false,
+    };
+
+    if (!this.running || !this.acceptingFrames || runEpochArg !== this.runEpoch) {
+      void this.acknowledgeFrame(frameWork);
+      return;
+    }
+
+    this.highestFrameSequence = Math.max(this.highestFrameSequence, frameArg.sequence);
+    if (this.queuedFrame) {
+      const supersededFrame = this.queuedFrame;
+      this.queuedFrame = undefined;
+      void this.acknowledgeFrame(supersededFrame);
+    }
+    this.queuedFrame = frameWork;
+
+    this.ensureFrameProcessor();
+  }
+
+  private ensureFrameProcessor(): void {
+    if (this.frameProcessingPromise || !this.queuedFrame) {
+      return;
+    }
+    const processingPromise = this.processFrameQueue().finally(() => {
+      if (this.frameProcessingPromise === processingPromise) {
+        this.frameProcessingPromise = undefined;
+        if (this.queuedFrame) {
+          this.ensureFrameProcessor();
+        }
+      }
+    });
+    this.frameProcessingPromise = processingPromise;
+  }
+
+  private async processFrameQueue(): Promise<void> {
+    while (this.queuedFrame) {
+      const frameWork = this.queuedFrame;
+      this.queuedFrame = undefined;
+      await this.processFrame(frameWork);
+    }
+  }
+
+  private async processFrame(frameWorkArg: IFrameWork): Promise<void> {
+    const { frame, runEpoch } = frameWorkArg;
+    let imageBitmap: ImageBitmap | undefined;
+    try {
+      if (!this.canRenderFrame(frame, runEpoch)) {
+        return;
+      }
+
+      const frameBytes = new Uint8Array(frame.data.byteLength);
+      frameBytes.set(frame.data);
+      imageBitmap = await this.decodeFrame(new Blob([frameBytes.buffer], {
+        type: frame.mimeType,
+      }));
+
+      if (!this.canRenderFrame(frame, runEpoch) || frame.sequence !== this.highestFrameSequence) {
+        return;
+      }
+      if (imageBitmap.width !== frame.width || imageBitmap.height !== frame.height) {
+        throw new Error(
+          `decoded frame dimensions ${imageBitmap.width}x${imageBitmap.height} do not match ${frame.width}x${frame.height}`,
+        );
+      }
+
+      this.canvas.width = frame.width;
+      this.canvas.height = frame.height;
+      this.canvasContext.clearRect(0, 0, frame.width, frame.height);
+      this.canvasContext.drawImage(imageBitmap, 0, 0, frame.width, frame.height);
+      this.displayedFrame = {
+        tabId: frame.tabId,
+        sequence: frame.sequence,
+        generation: frame.generation,
+        viewportRevision: frame.viewportRevision,
+        viewport: { ...frame.viewport },
+      };
+
+      if (
+        this.resizeFence
+        && !this.viewportProcessing
+        && frame.viewportRevision >= this.resizeFence.minimumViewportRevision
+        && viewportEquals(frame.viewport, this.resizeFence.target)
+      ) {
+        this.resizeFence = undefined;
+      }
+      this.updateInputAvailability();
+      this.callFrameRendered(frame, runEpoch);
+    } catch (error) {
+      this.reportError({
+        code: 'frame_render_failed',
+        message: `Could not render live browser frame: ${getErrorMessage(error)}`,
+        cause: error,
+        frame,
+      }, runEpoch);
+      if (error instanceof LiveBrowserOperationTimeoutError) {
+        this.requestStop(runEpoch);
+      }
+    } finally {
+      imageBitmap?.close();
+      await this.acknowledgeFrame(frameWorkArg);
+    }
+  }
+
+  private canRenderFrame(frameArg: ILiveBrowserFrame, runEpochArg: number): boolean {
+    if (
+      !this.running
+      || !this.acceptingFrames
+      || runEpochArg !== this.runEpoch
+      || this.viewportProcessing
+    ) {
+      return false;
+    }
+    const state = this.state;
+    if (!state || state.status !== 'running' || state.activeTabId !== frameArg.tabId) {
+      return false;
+    }
+    const activeTab = state.tabs.find((tabArg) => tabArg.id === frameArg.tabId);
+    if (!activeTab || activeTab.status !== 'open') {
+      return false;
+    }
+    if (
+      state.viewportRevision > frameArg.viewportRevision
+      || activeTab.generation > frameArg.generation
+    ) {
+      return false;
+    }
+    if (this.resizeFence) {
+      return frameArg.viewportRevision >= this.resizeFence.minimumViewportRevision
+        && viewportEquals(frameArg.viewport, this.resizeFence.target);
+    }
+    return true;
+  }
+
+  private acknowledgeFrame(frameWorkArg: IFrameWork): Promise<void> {
+    if (frameWorkArg.acknowledgementAttempted) {
+      return Promise.resolve();
+    }
+    frameWorkArg.acknowledgementAttempted = true;
+
+    if (this.acknowledgementPromises.size >= maxPendingAcknowledgements) {
+      this.reportError({
+        code: 'frame_acknowledgement_failed',
+        message: `Live browser frame acknowledgement capacity of ${maxPendingAcknowledgements} was reached`,
+      }, frameWorkArg.runEpoch);
+      this.requestStop(frameWorkArg.runEpoch);
+      return Promise.resolve();
+    }
+
+    const acknowledgement = this.runClientOperation(
+      () => this.client.acknowledgeFrame(createFrameAcknowledgementRequest(frameWorkArg.frame)),
+      'frame acknowledgement',
+    )
+      .then(() => undefined)
+      .catch((error) => {
+        this.reportError({
+          code: 'frame_acknowledgement_failed',
+          message: `Could not acknowledge live browser frame: ${getErrorMessage(error)}`,
+          cause: error,
+          frame: frameWorkArg.frame,
+        }, frameWorkArg.runEpoch);
+        this.requestStop(frameWorkArg.runEpoch);
+      });
+    let trackedAcknowledgement: Promise<void>;
+    trackedAcknowledgement = acknowledgement.finally(() => {
+      this.acknowledgementPromises.delete(trackedAcknowledgement);
+    });
+    this.acknowledgementPromises.add(trackedAcknowledgement);
+    return trackedAcknowledgement;
+  }
+
+  private handlePointerDown(eventArg: PointerEvent, runEpochArg: number): void {
+    if (eventArg.pointerType && eventArg.pointerType !== 'mouse') {
+      return;
+    }
+    const button = this.getMouseButton(eventArg.button);
+    if (!button) {
+      return;
+    }
+    const displayedFrame = this.getInputFrame();
+    if (!displayedFrame || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    eventArg.preventDefault();
+    const coordinates = this.mapCoordinates(eventArg, displayedFrame.viewport);
+    if (!coordinates) {
+      return;
+    }
+    this.focusTarget.focus({ preventScroll: true });
+    try {
+      this.canvas.setPointerCapture(eventArg.pointerId);
+      this.capturedPointerIds.add(eventArg.pointerId);
+    } catch {
+      // Pointer capture may already have been released by the browser.
+    }
+    const input: ILiveBrowserMouseInput = {
+      ...createInputIdentity(displayedFrame),
+      type: 'down',
+      ...coordinates,
+      button,
+      buttons: eventArg.buttons,
+      clickCount: Math.min(3, Math.max(1, eventArg.detail || 1)),
+      modifiers: createModifiers(eventArg),
+    };
+    void this.enqueueInputCommand({
+      kind: 'mouse',
+      runEpoch: runEpochArg,
+      execute: async () => this.client.dispatchMouse(input),
+      onAttempt: () => this.pressedMouseButtons.set(button, input),
+    }).catch(() => undefined);
+  }
+
+  private handlePointerMove(eventArg: PointerEvent, runEpochArg: number): void {
+    if (eventArg.pointerType && eventArg.pointerType !== 'mouse') {
+      return;
+    }
+    const displayedFrame = this.getInputFrame();
+    if (!displayedFrame || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    eventArg.preventDefault();
+    const coordinates = this.mapCoordinates(eventArg, displayedFrame.viewport);
+    if (!coordinates) {
+      this.releasePointerCapture(eventArg.pointerId);
+      void this.scheduleInputReset(false, runEpochArg);
+      return;
+    }
+    const input: ILiveBrowserMouseInput = {
+      ...createInputIdentity(displayedFrame),
+      type: 'move',
+      ...coordinates,
+      button: 'none',
+      buttons: eventArg.buttons,
+      modifiers: createModifiers(eventArg),
+    };
+    void this.enqueueInputCommand({
+      kind: 'mouseMove',
+      runEpoch: runEpochArg,
+      execute: async () => this.client.dispatchMouse(input),
+    }).catch(() => undefined);
+  }
+
+  private handlePointerUp(eventArg: PointerEvent, runEpochArg: number): void {
+    if (eventArg.pointerType && eventArg.pointerType !== 'mouse') {
+      return;
+    }
+    const button = this.getMouseButton(eventArg.button);
+    const displayedFrame = this.getInputFrame();
+    if (!button || !displayedFrame || runEpochArg !== this.runEpoch) {
+      this.releasePointerCapture(eventArg.pointerId);
+      return;
+    }
+    eventArg.preventDefault();
+    const coordinates = this.mapCoordinates(eventArg, displayedFrame.viewport);
+    if (!coordinates) {
+      this.releasePointerCapture(eventArg.pointerId);
+      void this.scheduleInputReset(false, runEpochArg);
+      return;
+    }
+    const input: ILiveBrowserMouseInput = {
+      ...createInputIdentity(displayedFrame),
+      type: 'up',
+      ...coordinates,
+      button,
+      buttons: eventArg.buttons,
+      clickCount: Math.min(3, Math.max(1, eventArg.detail || 1)),
+      modifiers: createModifiers(eventArg),
+    };
+    void this.enqueueInputCommand({
+      kind: 'mouse',
+      runEpoch: runEpochArg,
+      execute: async () => this.client.dispatchMouse(input),
+      onSuccess: () => this.pressedMouseButtons.delete(button),
+    }).catch(() => undefined);
+    this.releasePointerCapture(eventArg.pointerId);
+  }
+
+  private handleWheel(eventArg: WheelEvent, runEpochArg: number): void {
+    const displayedFrame = this.getInputFrame();
+    if (!displayedFrame || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    eventArg.preventDefault();
+    const coordinates = this.mapCoordinates(eventArg, displayedFrame.viewport);
+    if (!coordinates) {
+      return;
+    }
+    const multiplier = eventArg.deltaMode === WheelEvent.DOM_DELTA_LINE
+      ? 16
+      : eventArg.deltaMode === WheelEvent.DOM_DELTA_PAGE
+        ? displayedFrame.viewport.height
+        : 1;
+    const clampDelta = (valueArg: number) => Math.max(-1000000, Math.min(1000000, valueArg));
+    void this.enqueueInputCommand({
+      kind: 'wheel',
+      runEpoch: runEpochArg,
+      execute: async () => this.client.dispatchWheel({
+        ...createInputIdentity(displayedFrame),
+        ...coordinates,
+        deltaX: clampDelta(eventArg.deltaX * multiplier),
+        deltaY: clampDelta(eventArg.deltaY * multiplier),
+        modifiers: createModifiers(eventArg),
+      }),
+    }).catch(() => undefined);
+  }
+
+  private handleKey(
+    eventArg: KeyboardEvent,
+    typeArg: 'down' | 'up',
+    runEpochArg: number,
+  ): void {
+    const displayedFrame = this.getInputFrame();
+    if (
+      !displayedFrame
+      || runEpochArg !== this.runEpoch
+      || eventArg.isComposing
+      || eventArg.key === 'Process'
+    ) {
+      return;
+    }
+    eventArg.preventDefault();
+    const text = typeArg === 'down'
+      && eventArg.key.length === 1
+      && !eventArg.metaKey
+      && (!eventArg.ctrlKey || eventArg.altKey)
+      ? eventArg.key
+      : undefined;
+    const input: ILiveBrowserKeyInput = {
+      ...createInputIdentity(displayedFrame),
+      type: typeArg,
+      key: eventArg.key,
+      code: eventArg.code || undefined,
+      text,
+      windowsVirtualKeyCode: eventArg.keyCode || undefined,
+      autoRepeat: eventArg.repeat,
+      isKeypad: eventArg.location === KeyboardEvent.DOM_KEY_LOCATION_NUMPAD,
+      location: eventArg.location,
+      modifiers: createModifiers(eventArg),
+    };
+    const keyIdentity = eventArg.code || eventArg.key;
+    void this.enqueueInputCommand({
+      kind: 'key',
+      runEpoch: runEpochArg,
+      execute: async () => this.client.dispatchKey(input),
+      onAttempt: typeArg === 'down'
+        ? () => this.pressedKeys.set(keyIdentity, input)
+        : undefined,
+      onSuccess: () => {
+        if (typeArg === 'up') {
+          this.pressedKeys.delete(keyIdentity);
+        }
+      },
+    }).catch(() => undefined);
+  }
+
+  private mapCoordinates(
+    eventArg: MouseEvent,
+    viewportArg: ILiveBrowserViewport,
+  ): { x: number; y: number } | undefined {
+    const canvasBounds = this.canvas.getBoundingClientRect();
+    if (canvasBounds.width <= 0 || canvasBounds.height <= 0) {
+      return undefined;
+    }
+    const x = ((eventArg.clientX - canvasBounds.left) / canvasBounds.width) * viewportArg.width;
+    const y = ((eventArg.clientY - canvasBounds.top) / canvasBounds.height) * viewportArg.height;
+    return {
+      x: Math.max(0, Math.min(viewportArg.width - coordinateEdgeInset, x)),
+      y: Math.max(0, Math.min(viewportArg.height - coordinateEdgeInset, y)),
+    };
+  }
+
+  private getMouseButton(buttonArg: number): ILiveBrowserMouseInput['button'] | undefined {
+    return buttonArg === 0
+      ? 'left'
+      : buttonArg === 1
+        ? 'middle'
+        : buttonArg === 2
+          ? 'right'
+          : buttonArg === 3
+            ? 'back'
+            : buttonArg === 4
+              ? 'forward'
+              : undefined;
+  }
+
+  private getInputFrame(): IDisplayedFrame | undefined {
+    return this.inputBlocked || !this.isDisplayedFrameCurrent()
+      ? undefined
+      : this.displayedFrame;
+  }
+
+  private requireInputFrame(): IDisplayedFrame {
+    const displayedFrame = this.getInputFrame();
+    if (!displayedFrame) {
+      throw new Error('Live browser input is unavailable until a current frame is displayed');
+    }
+    return displayedFrame;
+  }
+
+  private isDisplayedFrameCurrent(): boolean {
+    const state = this.state;
+    const displayedFrame = this.displayedFrame;
+    if (!state || !displayedFrame || state.status !== 'running') {
+      return false;
+    }
+    if (
+      state.activeTabId !== displayedFrame.tabId
+      || state.viewportRevision > displayedFrame.viewportRevision
+    ) {
+      return false;
+    }
+    const activeTab = state.tabs.find((tabArg) => tabArg.id === displayedFrame.tabId);
+    return Boolean(
+      activeTab
+      && activeTab.status === 'open'
+      && activeTab.generation <= displayedFrame.generation,
+    );
+  }
+
+  private enqueueInputCommand(commandArg: Omit<IInputCommand, 'reject' | 'resolve'>): Promise<void> {
+    if (!this.running || this.inputBlocked || commandArg.runEpoch !== this.runEpoch) {
+      return Promise.reject(new Error('Live browser input is currently blocked'));
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const command: IInputCommand = {
+        ...commandArg,
+        resolve,
+        reject,
+      };
+      const lastCommand = this.inputCommands.at(-1);
+      if (command.kind === 'mouseMove' && lastCommand?.kind === 'mouseMove') {
+        lastCommand.resolve();
+        this.inputCommands[this.inputCommands.length - 1] = command;
+      } else if (this.inputCommands.length >= maxInputQueueLength) {
+        if (command.kind === 'mouseMove') {
+          resolve();
+          return;
+        }
+        const error = new Error('Live browser input queue reached its capacity');
+        this.reportError({
+          code: 'input_queue_capacity_exceeded',
+          message: error.message,
+          cause: error,
+        }, command.runEpoch);
+        reject(error);
+        this.recoverFromInputOverflow(command.runEpoch);
+        return;
+      } else {
+        this.inputCommands.push(command);
+      }
+      this.processInputCommands();
+    });
+  }
+
+  private processInputCommands(): void {
+    if (this.inputProcessing) {
+      return;
+    }
+    this.inputProcessing = true;
+    void (async () => {
+      try {
+        while (this.inputCommands.length > 0) {
+          const command = this.inputCommands.shift()!;
+          if (command.runEpoch !== this.runEpoch) {
+            command.resolve();
+            continue;
+          }
+          try {
+            command.onAttempt?.();
+            await this.runClientOperation(command.execute, 'input dispatch');
+            command.onSuccess?.();
+            command.resolve();
+          } catch (error) {
+            this.reportError({
+              code: 'input_dispatch_failed',
+              message: `Could not dispatch live browser input: ${getErrorMessage(error)}`,
+              cause: error,
+            }, command.runEpoch);
+            command.reject(error);
+            const abandonedCommands = this.inputCommands.splice(0);
+            for (const abandonedCommand of abandonedCommands) {
+              abandonedCommand.reject(
+                new Error('Live browser input was abandoned after a dispatch failure'),
+              );
+            }
+            if (!this.stopping) {
+              void this.scheduleInputReset(false, command.runEpoch);
+            }
+            if (error instanceof LiveBrowserOperationTimeoutError) {
+              this.requestStop(command.runEpoch);
+            }
+          }
+        }
+      } finally {
+        this.inputProcessing = false;
+        if (this.inputCommands.length > 0) {
+          this.processInputCommands();
+        } else {
+          const resolvers = this.inputIdleResolvers;
+          this.inputIdleResolvers = [];
+          for (const resolver of resolvers) {
+            resolver();
+          }
+        }
+      }
+    })();
+  }
+
+  private waitForInputIdle(): Promise<void> {
+    if (!this.inputProcessing && this.inputCommands.length === 0) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this.inputIdleResolvers.push(resolve);
+    });
+  }
+
+  private scheduleInputReset(
+    clearDisplayArg: boolean,
+    runEpochArg: number,
+  ): Promise<void> {
+    if (runEpochArg !== this.runEpoch || this.stopping) {
+      return Promise.resolve();
+    }
+    this.inputBlocked = true;
+    this.releasePointerCaptures();
+    if (clearDisplayArg) {
+      this.displayedFrame = undefined;
+      this.clearCanvas();
+    }
+    if (this.inputResetPromise) {
+      return this.inputResetPromise;
+    }
+    this.inputResetCount++;
+    let resetOperation: Promise<void>;
+    resetOperation = this.inputResetTail.then(async () => {
+      await this.waitForInputIdle();
+      await this.releasePressedInput(runEpochArg);
+    }).finally(() => {
+      this.inputResetCount--;
+      if (this.inputResetPromise === resetOperation) {
+        this.inputResetPromise = undefined;
+      }
+      this.updateInputAvailability();
+    });
+    this.inputResetPromise = resetOperation;
+    this.inputResetTail = resetOperation.then(() => undefined, () => undefined);
+    return resetOperation;
+  }
+
+  private recoverFromInputOverflow(runEpochArg: number): void {
+    if (this.inputOverflowRecoveryPending) {
+      return;
+    }
+    this.inputOverflowRecoveryPending = true;
+    this.inputBlocked = true;
+    void this.scheduleInputReset(false, runEpochArg).finally(() => {
+      this.inputOverflowRecoveryPending = false;
+    });
+  }
+
+  private async releasePressedInput(runEpochArg: number): Promise<void> {
+    for (const [keyIdentity, pressedKey] of [...this.pressedKeys.entries()]) {
+      const released = await this.tryInputRelease(
+        () => this.client.dispatchKey({
+          ...pressedKey,
+          type: 'up',
+          text: undefined,
+          autoRepeat: false,
+          modifiers: {},
+        }),
+        runEpochArg,
+      );
+      if (released && this.pressedKeys.get(keyIdentity) === pressedKey) {
+        this.pressedKeys.delete(keyIdentity);
+      }
+    }
+    for (const [button, pressedButton] of [...this.pressedMouseButtons.entries()]) {
+      const released = await this.tryInputRelease(
+        () => this.client.dispatchMouse({
+          ...pressedButton,
+          type: 'up',
+          buttons: 0,
+          clickCount: 1,
+          modifiers: {},
+        }),
+        runEpochArg,
+      );
+      if (released && this.pressedMouseButtons.get(button) === pressedButton) {
+        this.pressedMouseButtons.delete(button);
+      }
+    }
+  }
+
+  private async tryInputRelease(
+    operationArg: () => Promise<void>,
+    runEpochArg: number,
+  ): Promise<boolean> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < maxInputReleaseAttempts; attempt++) {
+      try {
+        await this.runClientOperation(
+          operationArg,
+          'input release',
+        );
+        return true;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    this.reportInputReleaseError(lastError, runEpochArg);
+    this.requestStop(runEpochArg);
+    return false;
+  }
+
+  private reportInputReleaseError(errorArg: unknown, runEpochArg: number): void {
+    this.reportError({
+      code: 'input_dispatch_failed',
+      message: `Could not release live browser input: ${getErrorMessage(errorArg)}`,
+      cause: errorArg,
+    }, runEpochArg);
+  }
+
+  private queueViewport(widthArg: number, heightArg: number, runEpochArg: number): void {
+    if (
+      !this.running
+      || this.stopping
+      || this.stopRequested
+      || runEpochArg !== this.runEpoch
+      || widthArg <= 0
+      || heightArg <= 0
+    ) {
+      return;
+    }
+    const deviceScaleFactor = this.getDeviceScaleFactor();
+    if (!Number.isFinite(deviceScaleFactor) || deviceScaleFactor <= 0) {
+      this.reportError({
+        code: 'viewport_update_failed',
+        message: 'Live browser device scale factor must be a positive finite number',
+      }, runEpochArg);
+      return;
+    }
+    const viewport: ILiveBrowserViewport = {
+      width: widthArg,
+      height: heightArg,
+      deviceScaleFactor,
+    };
+    if (this.pendingViewport && viewportEquals(viewport, this.pendingViewport)) {
+      return;
+    }
+    if (this.inFlightViewport && viewportEquals(viewport, this.inFlightViewport)) {
+      this.pendingViewport = undefined;
+      return;
+    }
+    if (
+      !this.inFlightViewport
+      && this.resizeFence
+      && viewportEquals(viewport, this.resizeFence.target)
+    ) {
+      this.pendingViewport = undefined;
+      return;
+    }
+    if (
+      !this.inFlightViewport
+      && !this.resizeFence
+      && this.state
+      && viewportEquals(viewport, this.state.viewport)
+    ) {
+      this.pendingViewport = undefined;
+      this.updateInputAvailability();
+      return;
+    }
+    this.pendingViewport = viewport;
+    this.inputBlocked = true;
+    this.ensureViewportProcessor(runEpochArg);
+  }
+
+  private ensureViewportProcessor(runEpochArg: number): void {
+    if (this.viewportProcessingPromise || !this.pendingViewport) {
+      return;
+    }
+    const processingPromise = this.processViewportQueue(runEpochArg).finally(() => {
+      if (this.viewportProcessingPromise === processingPromise) {
+        this.viewportProcessingPromise = undefined;
+        if (
+          this.pendingViewport
+          && this.running
+          && !this.stopping
+          && runEpochArg === this.runEpoch
+        ) {
+          this.ensureViewportProcessor(runEpochArg);
+        }
+      }
+    });
+    this.viewportProcessingPromise = processingPromise;
+  }
+
+  private async processViewportQueue(runEpochArg: number): Promise<void> {
+    this.viewportProcessing = true;
+    try {
+      while (
+        this.pendingViewport
+        && this.running
+        && !this.stopping
+        && runEpochArg === this.runEpoch
+      ) {
+        const viewport = this.pendingViewport;
+        this.pendingViewport = undefined;
+        this.inFlightViewport = viewport;
+        if (!this.resizeFence && this.state && viewportEquals(viewport, this.state.viewport)) {
+          this.inFlightViewport = undefined;
+          continue;
+        }
+
+        await this.scheduleInputReset(true, runEpochArg);
+        if (!this.running || this.stopping || runEpochArg !== this.runEpoch) {
+          return;
+        }
+        const currentRevision = this.state?.viewportRevision ?? 0;
+        const previousMinimumRevision = this.resizeFence?.minimumViewportRevision ?? currentRevision;
+        try {
+          await this.runClientOperation(
+            () => this.client.setViewport(viewport),
+            'viewport update',
+          );
+          if (!this.running || this.stopping || runEpochArg !== this.runEpoch) {
+            return;
+          }
+          this.resizeFence = {
+            target: viewport,
+            minimumViewportRevision: Math.max(currentRevision, previousMinimumRevision) + 1,
+          };
+        } catch (error) {
+          if (runEpochArg === this.runEpoch) {
+            this.resizeFence = undefined;
+            this.reportError({
+              code: 'viewport_update_failed',
+              message: `Could not update live browser viewport: ${getErrorMessage(error)}`,
+              cause: error,
+            }, runEpochArg);
+            if (error instanceof LiveBrowserOperationTimeoutError) {
+              this.requestStop(runEpochArg);
+            }
+          }
+        } finally {
+          if (this.inFlightViewport && viewportEquals(this.inFlightViewport, viewport)) {
+            this.inFlightViewport = undefined;
+          }
+        }
+      }
+    } finally {
+      this.viewportProcessing = false;
+      this.updateInputAvailability();
+    }
+  }
+
+  private updateInputAvailability(): void {
+    this.inputBlocked = !(
+      this.running
+      && this.acceptingFrames
+      && !this.viewportProcessing
+      && !this.resizeFence
+      && this.inputResetCount === 0
+      && this.pressedKeys.size === 0
+      && this.pressedMouseButtons.size === 0
+      && this.isDisplayedFrameCurrent()
+    );
+  }
+
+  private makeFocusTargetFocusable(): void {
+    this.focusWasAdjusted = false;
+    if (this.focusTarget.tabIndex >= 0) {
+      return;
+    }
+    this.focusHadTabIndex = this.focusTarget.hasAttribute('tabindex');
+    this.focusTabIndexValue = this.focusTarget.getAttribute('tabindex');
+    this.focusTarget.setAttribute('tabindex', '0');
+    this.focusWasAdjusted = true;
+  }
+
+  private restoreFocusTarget(): void {
+    if (!this.focusWasAdjusted) {
+      return;
+    }
+    if (this.focusHadTabIndex && this.focusTabIndexValue !== null) {
+      this.focusTarget.setAttribute('tabindex', this.focusTabIndexValue);
+    } else {
+      this.focusTarget.removeAttribute('tabindex');
+    }
+    this.focusWasAdjusted = false;
+  }
+
+  private clearCanvas(): void {
+    this.canvasContext.clearRect(0, 0, this.canvas.width, this.canvas.height);
+  }
+
+  private callFrameRendered(frameArg: ILiveBrowserFrame, runEpochArg: number): void {
+    if (!this.onFrameRendered || runEpochArg !== this.runEpoch || !this.running) {
+      return;
+    }
+    try {
+      this.onFrameRendered(frameArg);
+    } catch (error) {
+      this.reportError({
+        code: 'renderer_callback_failed',
+        message: `Live browser frame callback failed: ${getErrorMessage(error)}`,
+        cause: error,
+        frame: frameArg,
+      }, runEpochArg);
+    }
+  }
+
+  private reportError(errorArg: ILiveBrowserCanvasError, runEpochArg: number): void {
+    if (!this.onError || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    try {
+      this.onError(errorArg);
+    } catch {
+      // Consumer error reporting must not break renderer cleanup.
+    }
+  }
+
+  private requestStop(runEpochArg: number): void {
+    if (
+      runEpochArg !== this.runEpoch
+      || (!this.running && !this.stopping)
+    ) {
+      return;
+    }
+    this.terminallyStopped = true;
+    this.acceptingFrames = false;
+    this.inputBlocked = true;
+    this.pendingViewport = undefined;
+    if (this.stopping || this.stopRequested) {
+      return;
+    }
+    this.stopRequested = true;
+    void this.stop();
+  }
+
+  private validateTimeout(timeoutArg: number, nameArg: string): number {
+    if (!Number.isFinite(timeoutArg) || timeoutArg <= 0) {
+      throw new Error(`${nameArg} must be a positive finite number`);
+    }
+    return timeoutArg;
+  }
+
+  private runClientOperation<T>(
+    operationArg: () => Promise<T>,
+    operationNameArg: string,
+  ): Promise<T> {
+    let operation: Promise<T>;
+    try {
+      operation = operationArg();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.withTimeout(operation, this.operationTimeoutMs, operationNameArg);
+  }
+
+  private withTimeout<T>(
+    operationArg: Promise<T>,
+    timeoutMsArg: number,
+    operationNameArg: string,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      let settled = false;
+      const timeout = globalThis.setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          reject(new LiveBrowserOperationTimeoutError(
+            `${operationNameArg} timed out after ${timeoutMsArg}ms`,
+          ));
+        }
+      }, timeoutMsArg);
+      operationArg.then(
+        (valueArg) => {
+          if (!settled) {
+            settled = true;
+            globalThis.clearTimeout(timeout);
+            resolve(valueArg);
+          }
+        },
+        (errorArg) => {
+          if (!settled) {
+            settled = true;
+            globalThis.clearTimeout(timeout);
+            reject(errorArg);
+          }
+        },
+      );
+    });
+  }
+
+  private async decodeFrame(blobArg: Blob): Promise<ImageBitmap> {
+    let decodeOperation: Promise<ImageBitmap>;
+    try {
+      decodeOperation = createImageBitmap(blobArg);
+    } catch (error) {
+      throw error;
+    }
+    try {
+      return await this.withTimeout(
+        decodeOperation,
+        this.frameDecodeTimeoutMs,
+        'frame decode',
+      );
+    } catch (error) {
+      void decodeOperation.then((lateBitmapArg) => lateBitmapArg.close(), () => undefined);
+      throw error;
+    }
+  }
+
+  private releasePointerCapture(pointerIdArg: number): void {
+    this.capturedPointerIds.delete(pointerIdArg);
+    try {
+      if (this.canvas.hasPointerCapture(pointerIdArg)) {
+        this.canvas.releasePointerCapture(pointerIdArg);
+      }
+    } catch {
+      // Pointer capture may already have been released by the browser.
+    }
+  }
+
+  private releasePointerCaptures(): void {
+    const pointerIds = [...this.capturedPointerIds];
+    this.capturedPointerIds.clear();
+    for (const pointerId of pointerIds) {
+      this.releasePointerCapture(pointerId);
+    }
+  }
+}