@push.rocks/smartbrowser 4.0.2 → 4.1.0

package/ts_web/classes.livebrowsercanvasrenderer.ts

@@ -6,6 +6,7 @@ import type {
   ILiveBrowserMouseInput,
   ILiveBrowserState,
   ILiveBrowserViewport,
+  ILiveBrowserWheelInput,
   TLiveBrowserEvent,
 } from '@push.rocks/smartpuppeteer';
 
@@ -13,9 +14,15 @@ import type {
   ILiveBrowserCanvasError,
   ILiveBrowserCanvasOperationOptions,
   ILiveBrowserCanvasRendererOptions,
+  ILiveBrowserCanvasRendererStatistics,
 } from './interfaces.livebrowsercanvas.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;
@@ -45,17 +52,63 @@ interface IDisplayedFrame extends ILiveBrowserInputBase {
 }
 
 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;
@@ -102,7 +155,8 @@ const getErrorMessage = (errorArg: unknown): string => (
  */
 export class LiveBrowserCanvasRenderer {
   private readonly canvas: HTMLCanvasElement;
-  private readonly canvasContext: CanvasRenderingContext2D;
+  private readonly canvasContext?: CanvasRenderingContext2D;
+  private readonly bitmapContext?: ImageBitmapRenderingContext;
   private readonly client: ILiveBrowserCanvasRendererOptions['client'];
   private readonly focusTarget: HTMLElement;
   private readonly resizeTarget?: Element;
@@ -135,17 +189,22 @@ export class LiveBrowserCanvasRenderer {
   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 inputProcessing = false;
+  private inFlightInputCommands = 0;
+  private inFlightWheelCommands = 0;
   private inputIdleResolvers: Array<() => void> = [];
   private inputResetTail: Promise<void> = Promise.resolve();
   private inputResetPromise?: Promise<void>;
   private inputResetCount = 0;
-  private inputOverflowRecoveryPending = false;
+  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>();
@@ -155,6 +214,17 @@ export class LiveBrowserCanvasRenderer {
   private viewportProcessing = false;
   private viewportProcessingPromise?: Promise<void>;
   private resizeFence?: IResizeFence;
+  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) {
     this.canvas = optionsArg.canvas;
@@ -176,11 +246,17 @@ export class LiveBrowserCanvasRenderer {
     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');
+    const bitmapContext = this.canvas.getContext('bitmaprenderer');
+    if (bitmapContext) {
+      this.bitmapContext = bitmapContext;
+    } else {
+      // A canvas that already owns a 2D context keeps the 2D drawing path.
+      const canvasContext = this.canvas.getContext('2d');
+      if (!canvasContext) {
+        throw new Error('LiveBrowserCanvasRenderer requires a bitmaprenderer or 2D canvas context');
+      }
+      this.canvasContext = canvasContext;
     }
-    this.canvasContext = canvasContext;
   }
 
   public get isRunning(): boolean {
@@ -191,6 +267,16 @@ export class LiveBrowserCanvasRenderer {
     return this.suspended;
   }
 
+  /**
+   * Cumulative frame and input counters for this renderer instance across runs.
+   */
+  public getStatistics(): ILiveBrowserCanvasRendererStatistics {
+    return {
+      ...this.statistics,
+      inputCommandsInFlight: this.inFlightInputCommands,
+    };
+  }
+
   public start(): Promise<void> {
     return this.enqueueLifecycle(async () => {
       if (this.running) {
@@ -299,6 +385,7 @@ export class LiveBrowserCanvasRenderer {
     this.interruptionRequested = false;
     this.acceptingFrames = true;
     this.inputBlocked = true;
+    this.wheelFrameElapsed = true;
     this.state = undefined;
     this.displayedFrame = undefined;
     this.highestFrameSequence = -1;
@@ -335,6 +422,8 @@ export class LiveBrowserCanvasRenderer {
     this.queuedFrame = undefined;
     this.displayedFrame = undefined;
     this.resizeFence = undefined;
+    this.discardPendingDraw();
+    this.discardPendingWheel();
     this.releasePointerCaptures();
     this.clearCanvas();
 
@@ -352,7 +441,6 @@ export class LiveBrowserCanvasRenderer {
     }
     this.pressedKeys.clear();
     this.pressedMouseButtons.clear();
-    this.inputOverflowRecoveryPending = false;
   }
 
   private async finishRun(runEpochArg: number, suspendArg: boolean): Promise<void> {
@@ -363,6 +451,7 @@ export class LiveBrowserCanvasRenderer {
     try {
       this.resizeObserver?.disconnect();
       this.resizeObserver = undefined;
+      this.clearResizeDebounce();
       this.listenerController?.abort();
       this.listenerController = undefined;
       const unsubscribe = this.unsubscribe;
@@ -402,6 +491,9 @@ export class LiveBrowserCanvasRenderer {
       this.highestFrameSequence = -1;
       this.queuedFrame = undefined;
       this.frameProcessingPromise = undefined;
+      this.discardPendingDraw();
+      this.discardPendingWheel();
+      this.clearResizeDebounce();
       this.acknowledgementPromises.clear();
       this.resizeFence = undefined;
       this.pendingViewport = undefined;
@@ -498,19 +590,37 @@ export class LiveBrowserCanvasRenderer {
     }
     this.resizeObserver = new ResizeObserver((entriesArg) => {
       const matchingEntry = entriesArg.find((entryArg) => entryArg.target === this.resizeTarget);
-      if (!matchingEntry) {
+      if (!matchingEntry || runEpochArg !== this.runEpoch) {
         return;
       }
-      this.queueViewport(
-        matchingEntry.contentRect.width,
-        matchingEntry.contentRect.height,
-        runEpochArg,
-      );
+      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') {
       this.queueFrame(eventArg.frame, runEpochArg);
@@ -564,6 +674,7 @@ export class LiveBrowserCanvasRenderer {
     if (!this.running || !this.acceptingFrames || runEpochArg !== this.runEpoch) {
       return;
     }
+    this.statistics.framesReceived++;
 
     try {
       this.validateFrame(frameArg);
@@ -590,11 +701,12 @@ export class LiveBrowserCanvasRenderer {
       acknowledgementAttempted: false,
     };
     if (this.queuedFrame) {
-      const supersededFrame = this.queuedFrame;
+      // The superseded frame was already acknowledged at receipt.
       this.queuedFrame = undefined;
-      void this.acknowledgeFrame(supersededFrame);
+      this.statistics.framesSkipped++;
     }
     this.queuedFrame = frameWork;
+    void this.acknowledgeFrame(frameWork);
 
     this.ensureFrameProcessor();
   }
@@ -643,32 +755,14 @@ export class LiveBrowserCanvasRenderer {
           `decoded frame dimensions ${imageBitmap.width}x${imageBitmap.height} do not match ${frame.width}x${frame.height}`,
         );
       }
-      if (!this.canRenderFrame(frame, runEpoch) || frame.sequence !== this.highestFrameSequence) {
+      this.statistics.framesDecoded++;
+      if (!this.canRenderFrame(frame, runEpoch)) {
+        this.statistics.framesSkipped++;
         return;
       }
 
-      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);
+      this.setPendingDraw({ bitmap: imageBitmap, frame, runEpoch });
+      imageBitmap = undefined;
     } catch (error) {
       if (error instanceof LiveBrowserRunAbortedError) {
         return;
@@ -677,7 +771,6 @@ export class LiveBrowserCanvasRenderer {
       terminalError = error;
     } finally {
       imageBitmap?.close();
-      await this.acknowledgeFrame(frameWorkArg);
       if (terminalFailure) {
         this.requestSuspend(runEpoch);
         this.reportError({
@@ -690,6 +783,104 @@ export class LiveBrowserCanvasRenderer {
     }
   }
 
+  /**
+   * 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
@@ -889,20 +1080,110 @@ export class LiveBrowserCanvasRenderer {
       : eventArg.deltaMode === WheelEvent.DOM_DELTA_PAGE
         ? displayedFrame.viewport.height
         : 1;
-    const clampDelta = (valueArg: number) => Math.max(-1000000, Math.min(1000000, valueArg));
+    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: runEpochArg,
+      runEpoch,
+      wheelInput,
       execute: async (optionsArg) => this.client.dispatchWheel({
-        ...createInputIdentity(displayedFrame),
-        ...coordinates,
-        deltaX: clampDelta(eventArg.deltaX * multiplier),
-        deltaY: clampDelta(eventArg.deltaY * multiplier),
-        modifiers: createModifiers(eventArg),
+        ...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',
@@ -1028,97 +1309,175 @@ export class LiveBrowserCanvasRenderer {
         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();
+      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;
         }
-        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 {
+        // Accumulated wheel input precedes this command in event order.
+        this.flushPendingWheel();
+        this.statistics.inputCommandsEnqueued++;
         this.inputCommands.push(command);
       }
       this.processInputCommands();
     });
   }
 
-  private processInputCommands(): void {
-    if (this.inputProcessing) {
+  /**
+   * 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;
     }
-    this.inputProcessing = true;
-    void (async () => {
-      try {
-        while (this.inputCommands.length > 0) {
-          const command = this.inputCommands.shift()!;
-          if (!this.isRunActive(command.runEpoch)) {
-            command.reject(new LiveBrowserRunAbortedError(
-              `Live browser input belongs to inactive run ${command.runEpoch}`,
-            ));
-            continue;
-          }
-          try {
-            command.onAttempt?.();
-            await this.runClientOperation(command.execute, 'input dispatch', command.runEpoch);
-            if (!this.isRunActive(command.runEpoch)) {
-              throw new LiveBrowserRunAbortedError(
-                `Live browser input belongs to inactive run ${command.runEpoch}`,
-              );
-            }
-            command.onSuccess?.();
-            command.resolve();
-          } catch (error) {
-            command.reject(error);
-            if (error instanceof LiveBrowserRunAbortedError) {
-              continue;
-            }
-            if (error instanceof LiveBrowserOperationTimeoutError) {
-              this.requestSuspend(command.runEpoch);
-            }
-            this.reportError({
-              code: 'input_dispatch_failed',
-              message: `Could not dispatch live browser input: ${getErrorMessage(error)}`,
-              cause: error,
-            }, command.runEpoch);
-            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 (!(error instanceof LiveBrowserOperationTimeoutError) && !this.stopping) {
-              void this.scheduleInputReset(true, 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();
-          }
+    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.inputProcessing && this.inputCommands.length === 0) {
+    if (this.inFlightInputCommands === 0 && this.inputCommands.length === 0) {
       return Promise.resolve();
     }
     return new Promise<void>((resolve) => {
@@ -1159,17 +1518,6 @@ export class LiveBrowserCanvasRenderer {
     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(
@@ -1447,7 +1795,46 @@ export class LiveBrowserCanvasRenderer {
   }
 
   private clearCanvas(): void {
-    this.canvasContext.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    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 {