@push.rocks/smartbrowser 4.1.0 → 4.3.0

package/ts_web/classes.livebrowserrenderer.ts

@@ -0,0 +1,2232 @@
+import type {
+  ILiveBrowserFrame,
+  ILiveBrowserInputBase,
+  ILiveBrowserKeyInput,
+  ILiveBrowserModifierState,
+  ILiveBrowserMouseInput,
+  ILiveBrowserState,
+  ILiveBrowserViewport,
+  ILiveBrowserWheelInput,
+  ILiveVideoSource,
+  TLiveBrowserEvent,
+} from '@push.rocks/smartpuppeteer';
+
+import type {
+  ILiveBrowserCanvasError,
+  ILiveBrowserCanvasOperationOptions,
+  ILiveBrowserCanvasRendererOptions,
+  ILiveBrowserCanvasRendererStatistics,
+} from './interfaces.livebrowsercanvas.js';
+
+import { LiveBrowserVideoReceiver } from './classes.livebrowservideoreceiver.js';
+import type { ILiveBrowserVideoRendererOptions, ILiveBrowserVideoRendererStatistics } from './interfaces.livebrowservideo.js';
+
+const maxInputQueueLength = 128;
+const maxInFlightInputCommands = 4;
+const maxQueuedCoalescableCommands = 32;
+const maxWheelDelta = 1000000;
+const animationFrameFallbackMs = 16;
+const resizeDebounceMs = 100;
+const maxPendingAcknowledgements = 16;
+const maxInputReleaseAttempts = 2;
+const maxFrameDimension = 12288;
+const maxFramePixelArea = 8294400;
+const maxFrameByteLength = (maxFramePixelArea * 4) + 1048576;
+const maxViewportWidth = 4096;
+const maxViewportHeight = 4096;
+const minDeviceScaleFactor = 0.25;
+const maxDeviceScaleFactor = 3;
+const coordinateEdgeInset = 0.001;
+const defaultOperationTimeoutMs = 10000;
+
+class LiveBrowserOperationTimeoutError extends Error {}
+class LiveBrowserRunAbortedError extends Error {}
+class LiveBrowserFrameProtocolError extends Error {}
+class LiveBrowserFrameIntegrityError 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';
+type TCoalescableInputCommandKind = 'mouseMove' | 'wheel';
+
+interface IInputCommand {
+  kind: TInputCommandKind;
+  runEpoch: number;
+  execute: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<void>;
+  /** Mutable merged wheel payload that execute() reads at dispatch time. */
+  wheelInput?: ILiveBrowserWheelInput;
+  onAttempt?: () => void;
+  onSuccess?: () => void;
+  resolve: () => void;
+  reject: (errorArg: unknown) => void;
+}
+
+interface IPendingWheel extends ILiveBrowserWheelInput {
+  runEpoch: number;
+}
+
+interface IPendingDraw {
+  bitmap: ImageBitmap;
+  frame: ILiveBrowserFrame;
+  runEpoch: number;
+}
+
+interface IScheduledFrame {
+  animationFrameId?: number;
+  timeoutId?: ReturnType<typeof setTimeout>;
+}
+
+const isCoalescableInputCommand = (
+  kindArg: TInputCommandKind,
+): kindArg is TCoalescableInputCommandKind => kindArg === 'mouseMove' || kindArg === 'wheel';
+
+const clampWheelDelta = (valueArg: number): number => (
+  Math.max(-maxWheelDelta, Math.min(maxWheelDelta, valueArg))
+);
+
+const mergeWheelInput = (
+  targetArg: ILiveBrowserWheelInput,
+  sourceArg: ILiveBrowserWheelInput,
+): void => {
+  targetArg.x = sourceArg.x;
+  targetArg.y = sourceArg.y;
+  targetArg.deltaX = clampWheelDelta(targetArg.deltaX + sourceArg.deltaX);
+  targetArg.deltaY = clampWheelDelta(targetArg.deltaY + sourceArg.deltaY);
+  targetArg.modifiers = sourceArg.modifiers;
+};
+
+const inputIdentityEquals = (
+  firstArg: ILiveBrowserInputBase,
+  secondArg: ILiveBrowserInputBase,
+): boolean => (
+  firstArg.tabId === secondArg.tabId
+  && firstArg.generation === secondArg.generation
+  && firstArg.viewportRevision === secondArg.viewportRevision
+);
+
+interface IResizeFence {
+  minimumViewportRevision: number;
+  target: ILiveBrowserViewport;
+  negotiated?: boolean;
+}
+
+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 LiveBrowserRenderer {
+  private readonly canvas: HTMLElement & { width: number; height: number };
+  private readonly videoReceiver?: LiveBrowserVideoReceiver;
+  private readonly canvasContext?: CanvasRenderingContext2D;
+  private readonly bitmapContext?: ImageBitmapRenderingContext;
+  private readonly client: ILiveBrowserCanvasRendererOptions['client'] | ILiveBrowserVideoRendererOptions['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 suspended = false;
+  private stopping = false;
+  private interruptionRequested = false;
+  private runController?: AbortController;
+  private operationControllers = new Set<AbortController>();
+  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 pendingDraw?: IPendingDraw;
+  private drawSchedule?: IScheduledFrame;
+  private acknowledgementPromises = new Set<Promise<void>>();
+  private rawDecodeSettlementPromises = new Set<Promise<void>>();
+
+  private inputBlocked = true;
+  private inputCommands: IInputCommand[] = [];
+  private inFlightInputCommands = 0;
+  private inFlightWheelCommands = 0;
+  private inputIdleResolvers: Array<() => void> = [];
+  private inputResetTail: Promise<void> = Promise.resolve();
+  private inputResetPromise?: Promise<void>;
+  private inputResetCount = 0;
+  private pendingWheel?: IPendingWheel;
+  private wheelFlushSchedule?: IScheduledFrame;
+  private wheelFrameElapsed = true;
+  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;
+  private lastRequestedViewport?: ILiveBrowserViewport;
+  private resizeDebounceTimer?: ReturnType<typeof setTimeout>;
+  private pendingResizeSize?: { width: number; height: number };
+
+  private readonly statistics: Omit<ILiveBrowserCanvasRendererStatistics, 'inputCommandsInFlight'> = {
+    framesReceived: 0,
+    framesDecoded: 0,
+    framesSkipped: 0,
+    inputCommandsEnqueued: 0,
+    inputCommandsCoalesced: 0,
+    lastInputRoundTripMs: 0,
+  };
+
+  constructor(optionsArg: ILiveBrowserCanvasRendererOptions | ILiveBrowserVideoRendererOptions) {
+    this.canvas = 'video' in optionsArg ? optionsArg.video : 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(
+      ('frameDecodeTimeoutMs' in optionsArg ? optionsArg.frameDecodeTimeoutMs : undefined) ?? this.operationTimeoutMs,
+      'frameDecodeTimeoutMs',
+    );
+    this.onError = optionsArg.onError;
+    this.onFrameRendered = 'onFrameRendered' in optionsArg ? optionsArg.onFrameRendered : undefined;
+    this.initialCanvasWidth = this.canvas.width;
+    this.initialCanvasHeight = this.canvas.height;
+
+    if ('video' in optionsArg) {
+      this.videoReceiver = new LiveBrowserVideoReceiver({
+        video: optionsArg.video, client: optionsArg.client, operationTimeoutMs: this.operationTimeoutMs,
+        onUnavailable: () => {
+          this.displayedFrame = undefined;
+          this.inputBlocked = true;
+          if (this.running) void this.scheduleInputReset(false, this.runEpoch);
+        },
+        onPresented: (sourceArg) => this.presentVideo(sourceArg),
+        onError: (errorArg) => this.reportError(errorArg, this.runEpoch),
+      });
+      return;
+    }
+    const bitmapContext = optionsArg.canvas.getContext('bitmaprenderer');
+    if (bitmapContext) {
+      this.bitmapContext = bitmapContext;
+    } else {
+      // A canvas that already owns a 2D context keeps the 2D drawing path.
+      const canvasContext = optionsArg.canvas.getContext('2d');
+      if (!canvasContext) {
+        throw new Error('LiveBrowserCanvasRenderer requires a bitmaprenderer or 2D canvas context');
+      }
+      this.canvasContext = canvasContext;
+    }
+  }
+
+  public get isRunning(): boolean {
+    return this.running;
+  }
+
+  public get isSuspended(): boolean {
+    return this.suspended;
+  }
+
+  /**
+   * Cumulative frame and input counters for this renderer instance across runs.
+   */
+  public getStatistics(): ILiveBrowserVideoRendererStatistics {
+    return {
+      ...this.statistics,
+      ...this.videoReceiver?.getCounters(),
+      ...(this.videoReceiver ? { video: this.videoReceiver.getStatistics() } : {}),
+      inputCommandsInFlight: this.inFlightInputCommands,
+    };
+  }
+
+  public start(): Promise<void> {
+    return this.enqueueLifecycle(async () => {
+      if (this.running) {
+        return;
+      }
+      if (this.suspended) {
+        throw new Error('Live browser renderer is suspended; call resume() to start a fresh run');
+      }
+      await this.startRun(false);
+    });
+  }
+
+  public stop(): Promise<void> {
+    this.interruptRun(this.runEpoch);
+    return this.enqueueLifecycle(async () => {
+      const runEpoch = this.runEpoch;
+      this.interruptRun(runEpoch);
+      if (this.stopping) {
+        await this.finishRun(runEpoch, false);
+        return;
+      }
+      if (!this.suspended) {
+        return;
+      }
+      this.suspended = false;
+      this.restoreCanvasAndFocus();
+    });
+  }
+
+  /**
+   * Aborts the current transport generation without replaying input recovery.
+   */
+  public suspend(): Promise<void> {
+    this.interruptRun(this.runEpoch);
+    return this.enqueueLifecycle(async () => {
+      const runEpoch = this.runEpoch;
+      this.interruptRun(runEpoch);
+      if (!this.stopping) {
+        return;
+      }
+      await this.finishRun(runEpoch, true);
+    });
+  }
+
+  /**
+   * Starts a new transport generation that requires new state and a new frame.
+   */
+  public resume(): Promise<void> {
+    return this.enqueueLifecycle(async () => {
+      if (this.running) {
+        return;
+      }
+      if (!this.suspended) {
+        throw new Error('Live browser renderer is not suspended');
+      }
+      await this.startRun(true);
+    });
+  }
+
+  /**
+   * 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 (optionsArg) => {
+        await this.client.insertText({
+          ...inputIdentity,
+          text: textArg,
+        }, optionsArg);
+      },
+    });
+  }
+
+  /**
+   * 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.interruptionRequested || !this.resizeTarget) {
+      return;
+    }
+    this.queueViewport(
+      this.resizeTarget.clientWidth,
+      this.resizeTarget.clientHeight,
+      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 startRun(resumingArg: boolean): Promise<void> {
+    await Promise.all([...this.rawDecodeSettlementPromises]);
+    const runEpoch = ++this.runEpoch;
+    this.runController = new AbortController();
+    this.running = true;
+    this.suspended = false;
+    this.stopping = false;
+    this.interruptionRequested = false;
+    this.acceptingFrames = true;
+    this.inputBlocked = true;
+    this.wheelFrameElapsed = true;
+    this.state = undefined;
+    this.displayedFrame = undefined;
+    this.highestFrameSequence = -1;
+    this.clearCanvas();
+
+    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) {
+      this.interruptRun(runEpoch);
+      await this.finishRun(runEpoch, resumingArg);
+      throw error;
+    }
+  }
+
+  private interruptRun(runEpochArg: number): void {
+    if (
+      runEpochArg !== this.runEpoch
+      || (!this.running && !this.stopping)
+    ) {
+      return;
+    }
+    this.running = false;
+    this.stopping = true;
+    this.interruptionRequested = true;
+    this.acceptingFrames = false;
+    this.inputBlocked = true;
+    this.pendingViewport = undefined;
+    this.queuedFrame = undefined;
+    this.displayedFrame = undefined;
+    this.resizeFence = undefined;
+    this.discardPendingDraw();
+    this.discardPendingWheel();
+    this.releasePointerCaptures();
+    this.clearCanvas();
+    this.videoReceiver?.interrupt();
+
+    const interruptionError = new LiveBrowserRunAbortedError(
+      `Live browser renderer run ${runEpochArg} was interrupted`,
+    );
+    this.runController?.abort(interruptionError);
+    for (const controller of this.operationControllers) {
+      controller.abort(interruptionError);
+    }
+
+    const abandonedCommands = this.inputCommands.splice(0);
+    for (const command of abandonedCommands) {
+      command.reject(interruptionError);
+    }
+    this.pressedKeys.clear();
+    this.pressedMouseButtons.clear();
+  }
+
+  private async finishRun(runEpochArg: number, suspendArg: boolean): Promise<void> {
+    if (runEpochArg !== this.runEpoch) {
+      return;
+    }
+
+    try {
+      this.resizeObserver?.disconnect();
+      this.resizeObserver = undefined;
+      this.clearResizeDebounce();
+      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);
+        }
+      }
+
+      await Promise.allSettled([
+        this.videoReceiver?.stop(),
+        this.viewportProcessingPromise,
+        this.inputResetTail,
+        this.waitForInputIdle(),
+        this.frameProcessingPromise,
+        ...this.acknowledgementPromises,
+      ]);
+    } finally {
+      for (const controller of this.operationControllers) {
+        controller.abort(new LiveBrowserRunAbortedError(
+          `Live browser renderer run ${runEpochArg} finished`,
+        ));
+      }
+      this.operationControllers.clear();
+      this.runController = undefined;
+      this.running = false;
+      this.suspended = suspendArg;
+      this.acceptingFrames = false;
+      this.state = undefined;
+      this.displayedFrame = undefined;
+      this.highestFrameSequence = -1;
+      this.queuedFrame = undefined;
+      this.frameProcessingPromise = undefined;
+      this.discardPendingDraw();
+      this.discardPendingWheel();
+      this.clearResizeDebounce();
+      this.acknowledgementPromises.clear();
+      this.resizeFence = undefined;
+      this.lastRequestedViewport = undefined;
+      this.pendingViewport = undefined;
+      this.inFlightViewport = undefined;
+      this.viewportProcessing = false;
+      this.viewportProcessingPromise = undefined;
+      this.inputResetPromise = undefined;
+      this.inputResetTail = Promise.resolve();
+      this.inputResetCount = 0;
+      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.restoreCanvasAndFocus();
+      this.interruptionRequested = false;
+      this.stopping = false;
+    }
+  }
+
+  private restoreCanvasAndFocus(): void {
+    this.canvas.width = this.initialCanvasWidth;
+    this.canvas.height = this.initialCanvasHeight;
+    this.restoreFocusTarget();
+  }
+
+  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 (this.state && this.running) this.videoReceiver?.update(this.state);
+      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 || runEpochArg !== this.runEpoch) {
+        return;
+      }
+      this.pendingResizeSize = {
+        width: matchingEntry.contentRect.width,
+        height: matchingEntry.contentRect.height,
+      };
+      if (this.resizeDebounceTimer !== undefined) {
+        globalThis.clearTimeout(this.resizeDebounceTimer);
+      }
+      this.resizeDebounceTimer = globalThis.setTimeout(() => {
+        this.resizeDebounceTimer = undefined;
+        const pendingResizeSize = this.pendingResizeSize;
+        this.pendingResizeSize = undefined;
+        if (pendingResizeSize) {
+          this.queueViewport(pendingResizeSize.width, pendingResizeSize.height, runEpochArg);
+        }
+      }, resizeDebounceMs);
+    });
+    this.resizeObserver.observe(this.resizeTarget);
+    this.syncViewport();
+  }
+
+  private clearResizeDebounce(): void {
+    if (this.resizeDebounceTimer !== undefined) {
+      globalThis.clearTimeout(this.resizeDebounceTimer);
+      this.resizeDebounceTimer = undefined;
+    }
+    this.pendingResizeSize = undefined;
+  }
+
+  private handleEvent(eventArg: TLiveBrowserEvent, runEpochArg: number): void {
+    if (eventArg.type === 'frame') {
+      if (this.videoReceiver) return;
+      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;
+    this.followNegotiatedViewport();
+    this.videoReceiver?.update(stateArg);
+
+    if (this.displayedFrame && this.isStateAheadOfDisplayedFrame(stateArg, this.displayedFrame)) {
+      this.displayedFrame = undefined;
+      this.clearCanvas();
+      void this.scheduleInputReset(false, runEpochArg);
+      return;
+    }
+    this.updateInputAvailability();
+  }
+
+  private presentVideo(sourceArg: ILiveVideoSource): void {
+    if (!this.running || !this.state) return;
+    const tab = this.state.tabs.find((tabArg) => tabArg.id === sourceArg.tabId);
+    if (this.state.status !== 'running' || this.state.activeTabId !== sourceArg.tabId
+      || this.state.viewportRevision !== sourceArg.viewportRevision || !tab?.streaming
+      || tab.status !== 'open' || tab.generation !== sourceArg.generation) return;
+    this.displayedFrame = { ...sourceArg, viewport: { ...sourceArg.viewport }, sequence: 0 };
+    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' || !activeTab.streaming) {
+      return true;
+    }
+    return stateArg.viewportRevision > displayedFrameArg.viewportRevision
+      || activeTab.generation > displayedFrameArg.generation;
+  }
+
+  private queueFrame(frameArg: ILiveBrowserFrame, runEpochArg: number): void {
+    if (!this.running || !this.acceptingFrames || runEpochArg !== this.runEpoch) {
+      return;
+    }
+    this.statistics.framesReceived++;
+
+    try {
+      this.validateFrame(frameArg);
+      if (frameArg.sequence <= this.highestFrameSequence) {
+        throw new LiveBrowserFrameProtocolError(
+          `frame.sequence ${frameArg.sequence} must be strictly greater than current run high-water ${this.highestFrameSequence}`,
+        );
+      }
+    } catch (error) {
+      this.requestSuspend(runEpochArg);
+      this.reportError({
+        code: 'frame_render_failed',
+        message: `Rejected invalid live browser frame: ${getErrorMessage(error)}`,
+        cause: error,
+        frame: frameArg,
+      }, runEpochArg);
+      return;
+    }
+
+    this.highestFrameSequence = frameArg.sequence;
+    const frameWork: IFrameWork = {
+      frame: frameArg,
+      runEpoch: runEpochArg,
+      acknowledgementAttempted: false,
+    };
+    if (this.queuedFrame) {
+      // The superseded frame was already acknowledged at receipt.
+      this.queuedFrame = undefined;
+      this.statistics.framesSkipped++;
+    }
+    this.queuedFrame = frameWork;
+    void this.acknowledgeFrame(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;
+    let terminalFailure = false;
+    let terminalError: unknown;
+    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,
+      }), runEpoch);
+
+      if (imageBitmap.width !== frame.width || imageBitmap.height !== frame.height) {
+        throw new LiveBrowserFrameIntegrityError(
+          `decoded frame dimensions ${imageBitmap.width}x${imageBitmap.height} do not match ${frame.width}x${frame.height}`,
+        );
+      }
+      this.statistics.framesDecoded++;
+      if (!this.canRenderFrame(frame, runEpoch)) {
+        this.statistics.framesSkipped++;
+        return;
+      }
+
+      this.setPendingDraw({ bitmap: imageBitmap, frame, runEpoch });
+      imageBitmap = undefined;
+    } catch (error) {
+      if (error instanceof LiveBrowserRunAbortedError) {
+        return;
+      }
+      terminalFailure = true;
+      terminalError = error;
+    } finally {
+      imageBitmap?.close();
+      if (terminalFailure) {
+        this.requestSuspend(runEpoch);
+        this.reportError({
+          code: 'frame_render_failed',
+          message: `Could not render live browser frame: ${getErrorMessage(terminalError)}`,
+          cause: terminalError,
+          frame,
+        }, runEpoch);
+      }
+    }
+  }
+
+  /**
+   * Keeps only the newest decoded bitmap and presents it on the next animation frame.
+   */
+  private setPendingDraw(pendingDrawArg: IPendingDraw): void {
+    if (this.pendingDraw) {
+      this.pendingDraw.bitmap.close();
+      this.statistics.framesSkipped++;
+    }
+    this.pendingDraw = pendingDrawArg;
+    if (!this.drawSchedule) {
+      this.drawSchedule = this.scheduleAnimationFrame(() => {
+        this.drawSchedule = undefined;
+        this.drawPendingFrame();
+      });
+    }
+  }
+
+  private discardPendingDraw(): void {
+    if (this.drawSchedule) {
+      this.cancelScheduledFrame(this.drawSchedule);
+      this.drawSchedule = undefined;
+    }
+    const pendingDraw = this.pendingDraw;
+    this.pendingDraw = undefined;
+    if (pendingDraw) {
+      pendingDraw.bitmap.close();
+      this.statistics.framesSkipped++;
+    }
+  }
+
+  private drawPendingFrame(): void {
+    const pendingDraw = this.pendingDraw;
+    this.pendingDraw = undefined;
+    if (!pendingDraw) {
+      return;
+    }
+    const { bitmap, frame, runEpoch } = pendingDraw;
+    if (!this.canRenderFrame(frame, runEpoch)) {
+      bitmap.close();
+      this.statistics.framesSkipped++;
+      return;
+    }
+    try {
+      this.paintBitmap(bitmap, frame.width, frame.height);
+    } catch (error) {
+      bitmap.close();
+      this.requestSuspend(runEpoch);
+      this.reportError({
+        code: 'frame_render_failed',
+        message: `Could not render live browser frame: ${getErrorMessage(error)}`,
+        cause: error,
+        frame,
+      }, runEpoch);
+      return;
+    }
+    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);
+  }
+
+  /**
+   * Presents one decoded bitmap. The canvas backing store is reallocated only
+   * when the frame dimensions differ from the current intrinsic dimensions.
+   */
+  private paintBitmap(bitmapArg: ImageBitmap, widthArg: number, heightArg: number): void {
+    if (this.canvas.width !== widthArg) {
+      this.canvas.width = widthArg;
+    }
+    if (this.canvas.height !== heightArg) {
+      this.canvas.height = heightArg;
+    }
+    if (this.bitmapContext) {
+      this.bitmapContext.transferFromImageBitmap(bitmapArg);
+      return;
+    }
+    if (!this.canvasContext) {
+      throw new Error('LiveBrowserCanvasRenderer has no rendering context');
+    }
+    this.canvasContext.clearRect(0, 0, widthArg, heightArg);
+    this.canvasContext.drawImage(bitmapArg, 0, 0, widthArg, heightArg);
+    bitmapArg.close();
+  }
+
+  private canRenderFrame(frameArg: ILiveBrowserFrame, runEpochArg: number): boolean {
+    if (
+      !this.running
+      || !this.acceptingFrames
+      || runEpochArg !== this.runEpoch
+    ) {
+      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' || !activeTab.streaming) {
+      return false;
+    }
+    if (
+      state.viewportRevision > frameArg.viewportRevision
+      || activeTab.generation > frameArg.generation
+    ) {
+      return false;
+    }
+    if (this.resizeFence && !this.viewportProcessing) {
+      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.isRunActive(frameWorkArg.runEpoch)) {
+      return Promise.resolve();
+    }
+
+    if (this.acknowledgementPromises.size >= maxPendingAcknowledgements) {
+      this.requestSuspend(frameWorkArg.runEpoch);
+      this.reportError({
+        code: 'frame_acknowledgement_failed',
+        message: `Live browser frame acknowledgement capacity of ${maxPendingAcknowledgements} was reached`,
+      }, frameWorkArg.runEpoch);
+      return Promise.resolve();
+    }
+
+    const acknowledgement = this.runClientOperation(
+      (optionsArg) => {
+        if (!('acknowledgeFrame' in this.client)) throw new Error('Video clients do not acknowledge image frames');
+        return this.client.acknowledgeFrame(
+          createFrameAcknowledgementRequest(frameWorkArg.frame),
+          optionsArg,
+        );
+      },
+      'frame acknowledgement',
+      frameWorkArg.runEpoch,
+    )
+      .then(() => undefined)
+      .catch((error) => {
+        if (error instanceof LiveBrowserRunAbortedError) {
+          return;
+        }
+        this.requestSuspend(frameWorkArg.runEpoch);
+        this.reportError({
+          code: 'frame_acknowledgement_failed',
+          message: `Could not acknowledge live browser frame: ${getErrorMessage(error)}`,
+          cause: error,
+          frame: frameWorkArg.frame,
+        }, 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 (optionsArg) => this.client.dispatchMouse(input, optionsArg),
+      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 (optionsArg) => this.client.dispatchMouse(input, optionsArg),
+    }).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 (optionsArg) => this.client.dispatchMouse(input, optionsArg),
+      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 inputIdentity = createInputIdentity(displayedFrame);
+    const modifiers = createModifiers(eventArg);
+    this.statistics.inputCommandsEnqueued++;
+    const pendingWheel = this.pendingWheel;
+    if (
+      pendingWheel
+      && pendingWheel.runEpoch === runEpochArg
+      && inputIdentityEquals(pendingWheel, inputIdentity)
+    ) {
+      mergeWheelInput(pendingWheel, {
+        ...inputIdentity,
+        ...coordinates,
+        deltaX: eventArg.deltaX * multiplier,
+        deltaY: eventArg.deltaY * multiplier,
+        modifiers,
+      });
+      this.statistics.inputCommandsCoalesced++;
+    } else {
+      if (pendingWheel) {
+        this.flushPendingWheel();
+      }
+      this.pendingWheel = {
+        ...inputIdentity,
+        ...coordinates,
+        deltaX: clampWheelDelta(eventArg.deltaX * multiplier),
+        deltaY: clampWheelDelta(eventArg.deltaY * multiplier),
+        modifiers,
+        runEpoch: runEpochArg,
+      };
+    }
+    this.tryFlushPendingWheel();
+  }
+
+  /**
+   * Flushes accumulated wheel input at most once per animation frame and only
+   * while no wheel dispatch is in flight; the settling dispatch flushes the rest.
+   */
+  private tryFlushPendingWheel(): void {
+    if (!this.pendingWheel) {
+      return;
+    }
+    if (!this.wheelFrameElapsed) {
+      this.scheduleWheelFlush();
+      return;
+    }
+    if (this.inFlightWheelCommands > 0) {
+      return;
+    }
+    this.flushPendingWheel();
+  }
+
+  private scheduleWheelFlush(): void {
+    if (this.wheelFlushSchedule) {
+      return;
+    }
+    this.wheelFlushSchedule = this.scheduleAnimationFrame(() => {
+      this.wheelFlushSchedule = undefined;
+      this.wheelFrameElapsed = true;
+      this.tryFlushPendingWheel();
+    });
+  }
+
+  /**
+   * Moves the accumulated wheel input into the command queue regardless of the
+   * frame gate so that later discrete commands stay behind it.
+   */
+  private flushPendingWheel(): void {
+    const pendingWheel = this.pendingWheel;
+    if (!pendingWheel) {
+      return;
+    }
+    this.pendingWheel = undefined;
+    this.wheelFrameElapsed = false;
+    this.scheduleWheelFlush();
+    const displayedFrame = this.getInputFrame();
+    if (
+      !displayedFrame
+      || pendingWheel.runEpoch !== this.runEpoch
+      || !inputIdentityEquals(pendingWheel, createInputIdentity(displayedFrame))
+    ) {
+      return;
+    }
+    const { runEpoch, ...wheelInput } = pendingWheel;
+    void this.enqueueInputCommand({
+      kind: 'wheel',
+      runEpoch,
+      wheelInput,
+      execute: async (optionsArg) => this.client.dispatchWheel({
+        ...wheelInput,
+        deltaX: clampWheelDelta(wheelInput.deltaX),
+        deltaY: clampWheelDelta(wheelInput.deltaY),
+      }, optionsArg),
+    }).catch(() => undefined);
+  }
+
+  private discardPendingWheel(): void {
+    this.pendingWheel = undefined;
+    if (this.wheelFlushSchedule) {
+      this.cancelScheduledFrame(this.wheelFlushSchedule);
+      this.wheelFlushSchedule = undefined;
+    }
+    this.wheelFrameElapsed = true;
+  }
+
+  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 (optionsArg) => this.client.dispatchKey(input, optionsArg),
+      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 bounds = this.canvas.getBoundingClientRect();
+    let canvasBounds = { left: bounds.left, top: bounds.top, width: bounds.width, height: bounds.height };
+    if (this.videoReceiver && bounds.width > 0 && bounds.height > 0) {
+      const scale = Math.min(bounds.width / viewportArg.width, bounds.height / viewportArg.height);
+      canvasBounds = {
+        left: bounds.left + (bounds.width - viewportArg.width * scale) / 2,
+        top: bounds.top + (bounds.height - viewportArg.height * scale) / 2,
+        width: viewportArg.width * scale, height: viewportArg.height * scale,
+      };
+      if (this.pressedMouseButtons.size === 0 && (eventArg.clientX < canvasBounds.left
+        || eventArg.clientX >= canvasBounds.left + canvasBounds.width
+        || eventArg.clientY < canvasBounds.top || eventArg.clientY >= canvasBounds.top + canvasBounds.height)) return undefined;
+    }
+    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.streaming
+      && 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,
+      };
+      if (isCoalescableInputCommand(command.kind)) {
+        this.enqueueCoalescableCommand(command);
+      } else {
+        const queuedDiscreteCommands = this.inputCommands.filter((queuedCommand) => (
+          !isCoalescableInputCommand(queuedCommand.kind)
+        )).length;
+        if (queuedDiscreteCommands >= maxInputQueueLength) {
+          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);
+          return;
+        }
+        // Accumulated wheel input precedes this command in event order.
+        this.flushPendingWheel();
+        this.statistics.inputCommandsEnqueued++;
+        this.inputCommands.push(command);
+      }
+      this.processInputCommands();
+    });
+  }
+
+  /**
+   * Coalescable commands never exhaust capacity: they merge into a same-kind
+   * queue tail or evict the oldest queued coalescable command under pressure.
+   */
+  private enqueueCoalescableCommand(commandArg: IInputCommand): void {
+    // Wheel submissions are counted per DOM event before accumulation.
+    if (commandArg.kind === 'mouseMove') {
+      this.statistics.inputCommandsEnqueued++;
+    }
+    const lastCommand = this.inputCommands.at(-1);
+    if (lastCommand && lastCommand.kind === commandArg.kind) {
+      this.statistics.inputCommandsCoalesced++;
+      if (commandArg.kind === 'wheel' && lastCommand.wheelInput && commandArg.wheelInput) {
+        mergeWheelInput(lastCommand.wheelInput, commandArg.wheelInput);
+        commandArg.resolve();
+      } else {
+        lastCommand.resolve();
+        this.inputCommands[this.inputCommands.length - 1] = commandArg;
+      }
+      return;
+    }
+    const queuedCoalescableCommands = this.inputCommands.filter((queuedCommand) => (
+      isCoalescableInputCommand(queuedCommand.kind)
+    ));
+    if (queuedCoalescableCommands.length >= maxQueuedCoalescableCommands) {
+      this.dropOldestCoalescableCommand(queuedCoalescableCommands[0]);
+    }
+    this.inputCommands.push(commandArg);
+  }
+
+  private dropOldestCoalescableCommand(oldestCommandArg: IInputCommand): void {
+    const index = this.inputCommands.indexOf(oldestCommandArg);
+    if (index < 0) {
+      return;
+    }
+    this.inputCommands.splice(index, 1);
+    this.statistics.inputCommandsCoalesced++;
+    if (oldestCommandArg.kind === 'wheel' && oldestCommandArg.wheelInput) {
+      const nextWheelCommand = this.inputCommands.find((queuedCommand) => (
+        queuedCommand.kind === 'wheel' && queuedCommand.wheelInput
+      ));
+      if (nextWheelCommand?.wheelInput) {
+        const nextWheelInput = nextWheelCommand.wheelInput;
+        nextWheelInput.deltaX = clampWheelDelta(
+          nextWheelInput.deltaX + oldestCommandArg.wheelInput.deltaX,
+        );
+        nextWheelInput.deltaY = clampWheelDelta(
+          nextWheelInput.deltaY + oldestCommandArg.wheelInput.deltaY,
+        );
+      }
+    }
+    oldestCommandArg.resolve();
+  }
+
+  /**
+   * Dispatches queued commands in order with a bounded number in flight. The
+   * remote session processes operations sequentially, so order is preserved.
+   */
+  private processInputCommands(): void {
+    while (
+      this.inputCommands.length > 0
+      && this.inFlightInputCommands < maxInFlightInputCommands
+    ) {
+      const command = this.inputCommands.shift()!;
+      if (!this.isRunActive(command.runEpoch)) {
+        command.reject(new LiveBrowserRunAbortedError(
+          `Live browser input belongs to inactive run ${command.runEpoch}`,
+        ));
+        continue;
+      }
+      this.dispatchInputCommand(command);
+    }
+    if (this.inputCommands.length === 0 && this.inFlightInputCommands === 0) {
+      const resolvers = this.inputIdleResolvers;
+      this.inputIdleResolvers = [];
+      for (const resolver of resolvers) {
+        resolver();
+      }
+    }
+  }
+
+  private dispatchInputCommand(commandArg: IInputCommand): void {
+    this.inFlightInputCommands++;
+    if (commandArg.kind === 'wheel') {
+      this.inFlightWheelCommands++;
+    }
+    const startedAt = performance.now();
+    let dispatch: Promise<void>;
+    try {
+      commandArg.onAttempt?.();
+      dispatch = this.runClientOperation(commandArg.execute, 'input dispatch', commandArg.runEpoch);
+    } catch (error) {
+      dispatch = Promise.reject(error);
+    }
+    void dispatch.then(() => {
+      if (!this.isRunActive(commandArg.runEpoch)) {
+        throw new LiveBrowserRunAbortedError(
+          `Live browser input belongs to inactive run ${commandArg.runEpoch}`,
+        );
+      }
+      this.statistics.lastInputRoundTripMs = performance.now() - startedAt;
+      commandArg.onSuccess?.();
+      commandArg.resolve();
+    }).catch((error) => {
+      commandArg.reject(error);
+      this.handleInputDispatchFailure(error, commandArg.runEpoch);
+    }).finally(() => {
+      this.inFlightInputCommands--;
+      if (commandArg.kind === 'wheel') {
+        this.inFlightWheelCommands--;
+        if (this.inFlightWheelCommands === 0) {
+          this.tryFlushPendingWheel();
+        }
+      }
+      this.processInputCommands();
+    });
+  }
+
+  private handleInputDispatchFailure(errorArg: unknown, runEpochArg: number): void {
+    if (errorArg instanceof LiveBrowserRunAbortedError) {
+      return;
+    }
+    if (errorArg instanceof LiveBrowserOperationTimeoutError) {
+      this.requestSuspend(runEpochArg);
+    }
+    this.reportError({
+      code: 'input_dispatch_failed',
+      message: `Could not dispatch live browser input: ${getErrorMessage(errorArg)}`,
+      cause: errorArg,
+    }, runEpochArg);
+    this.discardPendingWheel();
+    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 (!(errorArg instanceof LiveBrowserOperationTimeoutError) && !this.stopping) {
+      void this.scheduleInputReset(true, runEpochArg);
+    }
+  }
+
+  private waitForInputIdle(): Promise<void> {
+    if (this.inFlightInputCommands === 0 && 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 async releasePressedInput(runEpochArg: number): Promise<void> {
+    for (const [keyIdentity, pressedKey] of [...this.pressedKeys.entries()]) {
+      const released = await this.tryInputRelease(
+        (optionsArg) => this.client.dispatchKey({
+          ...pressedKey,
+          type: 'up',
+          text: undefined,
+          autoRepeat: false,
+          modifiers: {},
+        }, optionsArg),
+        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(
+        (optionsArg) => this.client.dispatchMouse({
+          ...pressedButton,
+          type: 'up',
+          buttons: 0,
+          clickCount: 1,
+          modifiers: {},
+        }, optionsArg),
+        runEpochArg,
+      );
+      if (released && this.pressedMouseButtons.get(button) === pressedButton) {
+        this.pressedMouseButtons.delete(button);
+      }
+    }
+  }
+
+  private async tryInputRelease(
+    operationArg: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<void>,
+    runEpochArg: number,
+  ): Promise<boolean> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < maxInputReleaseAttempts; attempt++) {
+      try {
+        await this.runClientOperation(
+          operationArg,
+          'input release',
+          runEpochArg,
+        );
+        return true;
+      } catch (error) {
+        if (error instanceof LiveBrowserRunAbortedError) {
+          return false;
+        }
+        lastError = error;
+      }
+    }
+    this.requestSuspend(runEpochArg);
+    this.reportInputReleaseError(lastError, 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.interruptionRequested
+      || runEpochArg !== this.runEpoch
+    ) {
+      return;
+    }
+    const viewport = this.normalizeGeneratedViewport(widthArg, heightArg, runEpochArg);
+    if (!viewport) return;
+    if (this.pendingViewport && viewportEquals(viewport, this.pendingViewport)) {
+      return;
+    }
+    if (this.inFlightViewport && viewportEquals(viewport, this.inFlightViewport)) {
+      this.pendingViewport = undefined;
+      return;
+    }
+    if (!this.inFlightViewport && this.lastRequestedViewport && viewportEquals(viewport, this.lastRequestedViewport)) {
+      this.pendingViewport = undefined;
+      return;
+    }
+    if (
+      !this.inFlightViewport
+      && this.resizeFence
+      && !this.resizeFence.negotiated
+      && viewportEquals(viewport, this.resizeFence.target)
+    ) {
+      this.pendingViewport = undefined;
+      return;
+    }
+    if (
+      !this.inFlightViewport
+      && !this.resizeFence
+      && !this.lastRequestedViewport
+      && this.state
+      && viewportEquals(viewport, this.state.viewport)
+    ) {
+      this.pendingViewport = undefined;
+      this.lastRequestedViewport = { ...viewport };
+      this.updateInputAvailability();
+      return;
+    }
+    this.pendingViewport = viewport;
+    this.inputBlocked = true;
+    this.ensureViewportProcessor(runEpochArg);
+  }
+
+  private normalizeGeneratedViewport(
+    widthArg: number,
+    heightArg: number,
+    runEpochArg: number,
+  ): ILiveBrowserViewport | undefined {
+    if (
+      !Number.isFinite(widthArg)
+      || !Number.isFinite(heightArg)
+      || widthArg <= 0
+      || heightArg <= 0
+    ) {
+      this.reportError({
+        code: 'viewport_update_failed',
+        message: 'Live browser viewport dimensions must be positive finite numbers',
+      }, runEpochArg);
+      return undefined;
+    }
+    const measuredWidth = Math.max(1, Math.floor(widthArg));
+    const measuredHeight = Math.max(1, Math.floor(heightArg));
+    const reductionFactor = Math.min(
+      1,
+      maxViewportWidth / measuredWidth,
+      maxViewportHeight / measuredHeight,
+    );
+    const width = Math.max(1, Math.floor(measuredWidth * reductionFactor));
+    const height = Math.max(1, Math.floor(measuredHeight * reductionFactor));
+    const providedScale = this.getDeviceScaleFactor();
+    if (!Number.isFinite(providedScale) || providedScale <= 0) {
+      this.reportError({
+        code: 'viewport_update_failed',
+        message: 'Live browser device scale factor must be a positive finite number',
+      }, runEpochArg);
+      return undefined;
+    }
+    const desiredScale = Math.min(
+      maxDeviceScaleFactor,
+      Math.max(minDeviceScaleFactor, providedScale),
+    );
+    const physicalAreaIsValid = (scaleArg: number): boolean => (
+      Math.ceil(width * scaleArg) * Math.ceil(height * scaleArg) <= maxFramePixelArea
+    );
+    let deviceScaleFactor = desiredScale;
+    if (!physicalAreaIsValid(deviceScaleFactor)) {
+      let lower = minDeviceScaleFactor;
+      let upper = desiredScale;
+      for (let iteration = 0; iteration < 40; iteration += 1) {
+        const candidate = (lower + upper) / 2;
+        if (physicalAreaIsValid(candidate)) lower = candidate;
+        else upper = candidate;
+      }
+      deviceScaleFactor = lower;
+    }
+    return { width, height, deviceScaleFactor };
+  }
+
+  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.lastRequestedViewport && this.state && viewportEquals(viewport, this.state.viewport)) {
+          this.inFlightViewport = undefined;
+          this.lastRequestedViewport = { ...viewport };
+          continue;
+        }
+
+        await this.scheduleInputReset(false, runEpochArg);
+        if (!this.running || this.stopping || runEpochArg !== this.runEpoch) {
+          return;
+        }
+        const currentRevision = this.state?.viewportRevision ?? 0;
+        const previousMinimumRevision = this.resizeFence?.minimumViewportRevision ?? currentRevision;
+        try {
+          const result = await this.runClientOperation(
+            (optionsArg) => this.client.setViewport(viewport, optionsArg),
+            'viewport update',
+            runEpochArg,
+          );
+          if (!this.running || this.stopping || runEpochArg !== this.runEpoch) {
+            return;
+          }
+          if (result !== undefined) {
+            this.validateViewport(result.viewport, 'viewport result');
+            this.validateProtocolInteger(result.viewportRevision, 'viewport result revision', Math.max(1, currentRevision));
+            this.resizeFence = { target: { ...result.viewport }, minimumViewportRevision: result.viewportRevision, negotiated: true };
+            this.followNegotiatedViewport();
+          } else {
+            this.resizeFence = { target: viewport, minimumViewportRevision: Math.max(currentRevision, previousMinimumRevision) + 1 };
+          }
+          this.lastRequestedViewport = { ...viewport };
+        } catch (error) {
+          if (runEpochArg === this.runEpoch && !(error instanceof LiveBrowserRunAbortedError)) {
+            this.resizeFence = undefined;
+            if (error instanceof LiveBrowserOperationTimeoutError) {
+              this.requestSuspend(runEpochArg);
+            }
+            this.reportError({
+              code: 'viewport_update_failed',
+              message: `Could not update live browser viewport: ${getErrorMessage(error)}`,
+              cause: error,
+            }, runEpochArg);
+          }
+        } finally {
+          if (this.inFlightViewport && viewportEquals(this.inFlightViewport, viewport)) {
+            this.inFlightViewport = undefined;
+          }
+        }
+      }
+    } finally {
+      this.viewportProcessing = false;
+      this.updateInputAvailability();
+    }
+  }
+
+  private updateInputAvailability(): void {
+    if (this.resizeFence && !this.viewportProcessing && this.displayedFrame && this.isDisplayedFrameCurrent()
+      && this.displayedFrame.viewportRevision >= this.resizeFence.minimumViewportRevision
+      && viewportEquals(this.displayedFrame.viewport, this.resizeFence.target)) {
+      this.resizeFence = undefined;
+    }
+    this.inputBlocked = !(
+      this.running
+      && this.acceptingFrames
+      && !this.viewportProcessing
+      && !this.resizeFence
+      && this.inputResetCount === 0
+      && this.isDisplayedFrameCurrent()
+    );
+  }
+
+  private followNegotiatedViewport(): void {
+    if (this.resizeFence?.negotiated && this.state && this.state.viewportRevision > this.resizeFence.minimumViewportRevision) {
+      this.resizeFence = { target: { ...this.state.viewport }, minimumViewportRevision: this.state.viewportRevision, negotiated: true };
+    }
+  }
+
+  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 {
+    if (this.bitmapContext) {
+      this.bitmapContext.transferFromImageBitmap(null);
+      return;
+    }
+    this.canvasContext?.clearRect(0, 0, this.canvas.width, this.canvas.height);
+  }
+
+  /**
+   * Runs work on the next animation frame, or after one nominal frame period
+   * when the document is not visible and animation frames would not fire.
+   */
+  private scheduleAnimationFrame(callbackArg: () => void): IScheduledFrame {
+    const schedule: IScheduledFrame = {};
+    if (
+      typeof document !== 'undefined'
+      && document.visibilityState === 'visible'
+      && typeof globalThis.requestAnimationFrame === 'function'
+    ) {
+      schedule.animationFrameId = globalThis.requestAnimationFrame(() => {
+        schedule.animationFrameId = undefined;
+        callbackArg();
+      });
+    } else {
+      schedule.timeoutId = globalThis.setTimeout(() => {
+        schedule.timeoutId = undefined;
+        callbackArg();
+      }, animationFrameFallbackMs);
+    }
+    return schedule;
+  }
+
+  private cancelScheduledFrame(scheduleArg: IScheduledFrame): void {
+    if (scheduleArg.animationFrameId !== undefined) {
+      globalThis.cancelAnimationFrame(scheduleArg.animationFrameId);
+      scheduleArg.animationFrameId = undefined;
+    }
+    if (scheduleArg.timeoutId !== undefined) {
+      globalThis.clearTimeout(scheduleArg.timeoutId);
+      scheduleArg.timeoutId = undefined;
+    }
+  }
+
+  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 requestSuspend(runEpochArg: number): void {
+    if (!this.isRunActive(runEpochArg) || this.interruptionRequested) {
+      return;
+    }
+    this.interruptRun(runEpochArg);
+    void this.suspend();
+  }
+
+  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: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<T>,
+    operationNameArg: string,
+    runEpochArg: number,
+  ): Promise<T> {
+    return this.runAbortableOperation(
+      (signalArg) => operationArg({ signal: signalArg }),
+      this.operationTimeoutMs,
+      operationNameArg,
+      runEpochArg,
+    );
+  }
+
+  private runAbortableOperation<T>(
+    operationArg: (signalArg: AbortSignal) => Promise<T>,
+    timeoutMsArg: number,
+    operationNameArg: string,
+    runEpochArg: number,
+  ): Promise<T> {
+    const runController = this.runController;
+    if (
+      !runController
+      || !this.isRunActive(runEpochArg)
+      || runController.signal.aborted
+    ) {
+      return Promise.reject(new LiveBrowserRunAbortedError(
+        `Cannot start ${operationNameArg} for inactive run ${runEpochArg}`,
+      ));
+    }
+
+    const operationController = new AbortController();
+    this.operationControllers.add(operationController);
+    const abortFromRun = () => {
+      const reason = runController.signal.reason instanceof Error
+        ? runController.signal.reason
+        : new LiveBrowserRunAbortedError(
+            `Live browser renderer run ${runEpochArg} was interrupted`,
+          );
+      operationController.abort(reason);
+    };
+    runController.signal.addEventListener('abort', abortFromRun, { once: true });
+    const timeout = globalThis.setTimeout(() => {
+      operationController.abort(new LiveBrowserOperationTimeoutError(
+        `${operationNameArg} timed out after ${timeoutMsArg}ms`,
+      ));
+    }, timeoutMsArg);
+
+    let abortOperation = () => undefined;
+    const operation = new Promise<T>((resolve, reject) => {
+      let settled = false;
+      const settle = (callbackArg: () => void) => {
+        if (!settled) {
+          settled = true;
+          callbackArg();
+        }
+      };
+      abortOperation = () => {
+        const reason = operationController.signal.reason instanceof Error
+          ? operationController.signal.reason
+          : new LiveBrowserRunAbortedError(`${operationNameArg} was aborted`);
+        settle(() => reject(reason));
+      };
+      operationController.signal.addEventListener('abort', abortOperation, { once: true });
+
+      let operationResult: Promise<T>;
+      try {
+        operationResult = operationArg(operationController.signal);
+      } catch (error) {
+        settle(() => reject(error));
+        return;
+      }
+      operationResult.then(
+        (valueArg) => {
+          settle(() => resolve(valueArg));
+        },
+        (errorArg) => {
+          settle(() => reject(errorArg));
+        },
+      );
+    }).finally(() => {
+      globalThis.clearTimeout(timeout);
+      runController.signal.removeEventListener('abort', abortFromRun);
+      operationController.signal.removeEventListener('abort', abortOperation);
+      this.operationControllers.delete(operationController);
+    });
+    return operation;
+  }
+
+  private async decodeFrame(blobArg: Blob, runEpochArg: number): Promise<ImageBitmap> {
+    let decodeOperation: Promise<ImageBitmap>;
+    try {
+      decodeOperation = createImageBitmap(blobArg);
+    } catch (error) {
+      throw error;
+    }
+    let rawDecodeSettlementPromise: Promise<void>;
+    rawDecodeSettlementPromise = decodeOperation.then(
+      () => undefined,
+      () => undefined,
+    ).finally(() => {
+      this.rawDecodeSettlementPromises.delete(rawDecodeSettlementPromise);
+    });
+    this.rawDecodeSettlementPromises.add(rawDecodeSettlementPromise);
+    try {
+      return await this.runAbortableOperation(
+        async () => decodeOperation,
+        this.frameDecodeTimeoutMs,
+        'frame decode',
+        runEpochArg,
+      );
+    } catch (error) {
+      if (
+        error instanceof LiveBrowserOperationTimeoutError
+        || error instanceof LiveBrowserRunAbortedError
+      ) {
+        void decodeOperation.then((lateBitmapArg) => lateBitmapArg.close(), () => undefined);
+        throw error;
+      }
+      throw new LiveBrowserFrameIntegrityError(
+        `frame bytes could not be decoded: ${getErrorMessage(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
+  private isRunActive(runEpochArg: number): boolean {
+    return Boolean(
+      this.running
+      && !this.stopping
+      && runEpochArg === this.runEpoch
+      && this.runController
+      && !this.runController.signal.aborted,
+    );
+  }
+
+  private validateFrame(frameArg: ILiveBrowserFrame): void {
+    if (!frameArg || typeof frameArg !== 'object') {
+      throw new LiveBrowserFrameProtocolError('frame must be an object');
+    }
+    if (
+      typeof frameArg.tabId !== 'string'
+      || frameArg.tabId.length === 0
+      || frameArg.tabId.length > 4096
+    ) {
+      throw new LiveBrowserFrameProtocolError('frame.tabId must be a non-empty bounded string');
+    }
+    this.validateProtocolInteger(frameArg.sequence, 'frame.sequence', 1);
+    this.validateProtocolInteger(frameArg.generation, 'frame.generation', 1);
+    this.validateProtocolInteger(frameArg.viewportRevision, 'frame.viewportRevision', 1);
+    this.validateViewport(frameArg.viewport, 'frame.viewport');
+    if (frameArg.format !== 'jpeg' && frameArg.format !== 'png') {
+      throw new LiveBrowserFrameProtocolError('frame.format must be jpeg or png');
+    }
+    const expectedMimeType = frameArg.format === 'jpeg' ? 'image/jpeg' : 'image/png';
+    if (frameArg.mimeType !== expectedMimeType) {
+      throw new LiveBrowserFrameProtocolError(
+        `frame.mimeType must be ${expectedMimeType} for ${frameArg.format}`,
+      );
+    }
+    this.validateProtocolInteger(frameArg.width, 'frame.width', 1, maxFrameDimension);
+    this.validateProtocolInteger(frameArg.height, 'frame.height', 1, maxFrameDimension);
+    if (frameArg.width * frameArg.height > maxFramePixelArea) {
+      throw new LiveBrowserFrameProtocolError(
+        `frame pixel area must not exceed ${maxFramePixelArea}`,
+      );
+    }
+    if (!(frameArg.data instanceof Uint8Array)) {
+      throw new LiveBrowserFrameProtocolError('frame.data must be a Uint8Array');
+    }
+    if (frameArg.data.byteLength === 0 || frameArg.data.byteLength > maxFrameByteLength) {
+      throw new LiveBrowserFrameProtocolError(
+        `frame.data byte length must be between 1 and ${maxFrameByteLength}`,
+      );
+    }
+
+    const metadata = frameArg.metadata;
+    if (!metadata || typeof metadata !== 'object') {
+      throw new LiveBrowserFrameProtocolError('frame.metadata must be an object');
+    }
+    this.validateProtocolNumber(metadata.offsetTop, 'frame.metadata.offsetTop');
+    this.validateProtocolNumber(
+      metadata.pageScaleFactor,
+      'frame.metadata.pageScaleFactor',
+      true,
+    );
+    this.validateProtocolNumber(metadata.deviceWidth, 'frame.metadata.deviceWidth', true);
+    this.validateProtocolNumber(metadata.deviceHeight, 'frame.metadata.deviceHeight', true);
+    if (
+      metadata.deviceWidth > maxFrameDimension
+      || metadata.deviceHeight > maxFrameDimension
+      || metadata.deviceWidth * metadata.deviceHeight > maxFramePixelArea
+    ) {
+      throw new LiveBrowserFrameProtocolError(
+        `frame metadata dimensions must fit within ${maxFramePixelArea} pixels`,
+      );
+    }
+    this.validateProtocolNumber(metadata.scrollOffsetX, 'frame.metadata.scrollOffsetX');
+    this.validateProtocolNumber(metadata.scrollOffsetY, 'frame.metadata.scrollOffsetY');
+    if (metadata.timestamp !== undefined) {
+      this.validateProtocolNumber(metadata.timestamp, 'frame.metadata.timestamp');
+    }
+  }
+
+  private validateViewport(viewportArg: ILiveBrowserViewport, nameArg: string): void {
+    if (!viewportArg || typeof viewportArg !== 'object') {
+      throw new LiveBrowserFrameProtocolError(`${nameArg} must be an object`);
+    }
+    this.validateProtocolInteger(viewportArg.width, `${nameArg}.width`, 1, maxViewportWidth);
+    this.validateProtocolInteger(viewportArg.height, `${nameArg}.height`, 1, maxViewportHeight);
+    this.validateProtocolNumber(viewportArg.deviceScaleFactor, `${nameArg}.deviceScaleFactor`, true);
+    if (viewportArg.deviceScaleFactor > maxDeviceScaleFactor) {
+      throw new LiveBrowserFrameProtocolError(
+        `${nameArg}.deviceScaleFactor must not exceed ${maxDeviceScaleFactor}`,
+      );
+    }
+    const physicalArea = viewportArg.width
+      * viewportArg.height
+      * viewportArg.deviceScaleFactor
+      * viewportArg.deviceScaleFactor;
+    if (physicalArea > maxFramePixelArea) {
+      throw new LiveBrowserFrameProtocolError(
+        `${nameArg} physical pixel area must not exceed ${maxFramePixelArea}`,
+      );
+    }
+  }
+
+  private validateProtocolInteger(
+    valueArg: number,
+    nameArg: string,
+    minimumArg: number,
+    maximumArg = Number.MAX_SAFE_INTEGER,
+  ): void {
+    if (
+      !Number.isSafeInteger(valueArg)
+      || valueArg < minimumArg
+      || valueArg > maximumArg
+    ) {
+      throw new LiveBrowserFrameProtocolError(
+        `${nameArg} must be an integer between ${minimumArg} and ${maximumArg}`,
+      );
+    }
+  }
+
+  private validateProtocolNumber(
+    valueArg: number,
+    nameArg: string,
+    positiveArg = false,
+  ): void {
+    if (!Number.isFinite(valueArg) || (positiveArg && valueArg <= 0)) {
+      throw new LiveBrowserFrameProtocolError(
+        `${nameArg} must be a ${positiveArg ? 'positive ' : ''}finite number`,
+      );
+    }
+  }
+
+  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);
+    }
+  }
+}