@push.rocks/smartbrowser 3.0.0 → 4.0.1

package/ts_web/classes.livebrowsercanvasrenderer.ts

@@ -11,17 +11,27 @@ import type {
 
 import type {
   ILiveBrowserCanvasError,
+  ILiveBrowserCanvasOperationOptions,
   ILiveBrowserCanvasRendererOptions,
-  TLiveBrowserCanvasErrorCode,
 } from './interfaces.livebrowsercanvas.js';
 
 const maxInputQueueLength = 128;
 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;
@@ -39,7 +49,7 @@ type TInputCommandKind = 'key' | 'mouse' | 'mouseMove' | 'text' | 'wheel';
 interface IInputCommand {
   kind: TInputCommandKind;
   runEpoch: number;
-  execute: () => Promise<void>;
+  execute: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<void>;
   onAttempt?: () => void;
   onSuccess?: () => void;
   resolve: () => void;
@@ -107,9 +117,11 @@ export class LiveBrowserCanvasRenderer {
   private lifecycleTail: Promise<void> = Promise.resolve();
   private runEpoch = 0;
   private running = false;
+  private suspended = false;
   private stopping = false;
-  private stopRequested = false;
-  private terminallyStopped = false;
+  private interruptionRequested = false;
+  private runController?: AbortController;
+  private operationControllers = new Set<AbortController>();
   private acceptingFrames = false;
   private state?: ILiveBrowserState;
   private unsubscribe?: () => void;
@@ -124,6 +136,7 @@ export class LiveBrowserCanvasRenderer {
   private queuedFrame?: IFrameWork;
   private frameProcessingPromise?: Promise<void>;
   private acknowledgementPromises = new Set<Promise<void>>();
+  private rawDecodeSettlementPromises = new Set<Promise<void>>();
 
   private inputBlocked = true;
   private inputCommands: IInputCommand[] = [];
@@ -174,46 +187,66 @@ export class LiveBrowserCanvasRenderer {
     return this.running;
   }
 
+  public get isSuspended(): boolean {
+    return this.suspended;
+  }
+
   public start(): Promise<void> {
     return this.enqueueLifecycle(async () => {
-      if (this.terminallyStopped) {
-        throw new Error(
-          'Live browser renderer cannot restart after a terminal operation failure; create a new renderer and client',
-        );
-      }
       if (this.running) {
         return;
       }
+      if (this.suspended) {
+        throw new Error('Live browser renderer is suspended; call resume() to start a fresh run');
+      }
+      await this.startRun(false);
+    });
+  }
 
-      const runEpoch = ++this.runEpoch;
-      this.running = true;
-      this.stopping = false;
-      this.stopRequested = false;
-      this.acceptingFrames = true;
-      this.inputBlocked = true;
-      this.highestFrameSequence = -1;
+  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();
+    });
+  }
 
-      try {
-        this.makeFocusTargetFocusable();
-        this.installDomListeners(runEpoch);
-        this.unsubscribe = this.client.onEvent((eventArg) => {
-          this.handleEvent(eventArg, runEpoch);
-        });
-        this.applyState(this.client.getState(), runEpoch);
-        this.installResizeObserver(runEpoch);
-      } catch (error) {
-        await this.stopRun(runEpoch);
-        throw error;
+  /**
+   * 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);
     });
   }
 
-  public stop(): Promise<void> {
+  /**
+   * Starts a new transport generation that requires new state and a new frame.
+   */
+  public resume(): Promise<void> {
     return this.enqueueLifecycle(async () => {
-      if (!this.running) {
+      if (this.running) {
         return;
       }
-      await this.stopRun(this.runEpoch);
+      if (!this.suspended) {
+        throw new Error('Live browser renderer is not suspended');
+      }
+      await this.startRun(true);
     });
   }
 
@@ -226,11 +259,11 @@ export class LiveBrowserCanvasRenderer {
     await this.enqueueInputCommand({
       kind: 'text',
       runEpoch: this.runEpoch,
-      execute: async () => {
+      execute: async (optionsArg) => {
         await this.client.insertText({
           ...inputIdentity,
           text: textArg,
-        });
+        }, optionsArg);
       },
     });
   }
@@ -240,12 +273,14 @@ export class LiveBrowserCanvasRenderer {
    * remote CSS viewport. Intrinsic canvas dimensions are never used here.
    */
   public syncViewport(): void {
-    if (!this.running || this.stopping || this.stopRequested || !this.resizeTarget) {
+    if (!this.running || this.stopping || this.interruptionRequested || !this.resizeTarget) {
       return;
     }
-    const width = Math.floor(this.resizeTarget.clientWidth);
-    const height = Math.floor(this.resizeTarget.clientHeight);
-    this.queueViewport(width, height, this.runEpoch);
+    this.queueViewport(
+      this.resizeTarget.clientWidth,
+      this.resizeTarget.clientHeight,
+      this.runEpoch,
+    );
   }
 
   private enqueueLifecycle(operationArg: () => Promise<void>): Promise<void> {
@@ -254,12 +289,76 @@ export class LiveBrowserCanvasRenderer {
     return operation;
   }
 
-  private async stopRun(runEpochArg: number): Promise<void> {
+  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.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.releasePointerCaptures();
+    this.clearCanvas();
+
+    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();
+    this.inputOverflowRecoveryPending = false;
+  }
+
+  private async finishRun(runEpochArg: number, suspendArg: boolean): Promise<void> {
+    if (runEpochArg !== this.runEpoch) {
+      return;
+    }
 
     try {
       this.resizeObserver?.disconnect();
@@ -280,30 +379,38 @@ export class LiveBrowserCanvasRenderer {
         }
       }
 
-      if (this.queuedFrame) {
-        const queuedFrame = this.queuedFrame;
-        this.queuedFrame = undefined;
-        await this.acknowledgeFrame(queuedFrame);
-      }
-
-      await this.viewportProcessingPromise;
-      await this.inputResetTail;
-      await this.waitForInputIdle();
-      await this.releasePressedInput(runEpochArg);
-
-      this.running = false;
-      await this.frameProcessingPromise;
-      await Promise.all([...this.acknowledgementPromises]);
+      await Promise.allSettled([
+        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.acknowledgementPromises.clear();
       this.resizeFence = 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();
@@ -317,14 +424,18 @@ export class LiveBrowserCanvasRenderer {
       for (const resolver of inputIdleResolvers) {
         resolver();
       }
-      this.canvas.width = this.initialCanvasWidth;
-      this.canvas.height = this.initialCanvasHeight;
-      this.restoreFocusTarget();
-      this.stopRequested = false;
+      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;
@@ -391,8 +502,8 @@ export class LiveBrowserCanvasRenderer {
         return;
       }
       this.queueViewport(
-        Math.floor(matchingEntry.contentRect.width),
-        Math.floor(matchingEntry.contentRect.height),
+        matchingEntry.contentRect.width,
+        matchingEntry.contentRect.height,
         runEpochArg,
       );
     });
@@ -450,18 +561,34 @@ export class LiveBrowserCanvasRenderer {
   }
 
   private queueFrame(frameArg: ILiveBrowserFrame, runEpochArg: number): void {
+    if (!this.running || !this.acceptingFrames || runEpochArg !== this.runEpoch) {
+      return;
+    }
+
+    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.running || !this.acceptingFrames || runEpochArg !== this.runEpoch) {
-      void this.acknowledgeFrame(frameWork);
-      return;
-    }
-
-    this.highestFrameSequence = Math.max(this.highestFrameSequence, frameArg.sequence);
     if (this.queuedFrame) {
       const supersededFrame = this.queuedFrame;
       this.queuedFrame = undefined;
@@ -498,6 +625,8 @@ export class LiveBrowserCanvasRenderer {
   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;
@@ -507,16 +636,16 @@ export class LiveBrowserCanvasRenderer {
       frameBytes.set(frame.data);
       imageBitmap = await this.decodeFrame(new Blob([frameBytes.buffer], {
         type: frame.mimeType,
-      }));
+      }), runEpoch);
 
-      if (!this.canRenderFrame(frame, runEpoch) || frame.sequence !== this.highestFrameSequence) {
-        return;
-      }
       if (imageBitmap.width !== frame.width || imageBitmap.height !== frame.height) {
-        throw new Error(
+        throw new LiveBrowserFrameIntegrityError(
           `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) {
+        return;
+      }
 
       this.canvas.width = frame.width;
       this.canvas.height = frame.height;
@@ -541,18 +670,23 @@ export class LiveBrowserCanvasRenderer {
       this.updateInputAvailability();
       this.callFrameRendered(frame, runEpoch);
     } catch (error) {
-      this.reportError({
-        code: 'frame_render_failed',
-        message: `Could not render live browser frame: ${getErrorMessage(error)}`,
-        cause: error,
-        frame,
-      }, runEpoch);
-      if (error instanceof LiveBrowserOperationTimeoutError) {
-        this.requestStop(runEpoch);
+      if (error instanceof LiveBrowserRunAbortedError) {
+        return;
       }
+      terminalFailure = true;
+      terminalError = error;
     } finally {
       imageBitmap?.close();
       await this.acknowledgeFrame(frameWorkArg);
+      if (terminalFailure) {
+        this.requestSuspend(runEpoch);
+        this.reportError({
+          code: 'frame_render_failed',
+          message: `Could not render live browser frame: ${getErrorMessage(terminalError)}`,
+          cause: terminalError,
+          frame,
+        }, runEpoch);
+      }
     }
   }
 
@@ -592,28 +726,39 @@ export class LiveBrowserCanvasRenderer {
     }
     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);
-      this.requestStop(frameWorkArg.runEpoch);
       return Promise.resolve();
     }
 
     const acknowledgement = this.runClientOperation(
-      () => this.client.acknowledgeFrame(createFrameAcknowledgementRequest(frameWorkArg.frame)),
+      (optionsArg) => 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);
-        this.requestStop(frameWorkArg.runEpoch);
       });
     let trackedAcknowledgement: Promise<void>;
     trackedAcknowledgement = acknowledgement.finally(() => {
@@ -659,7 +804,7 @@ export class LiveBrowserCanvasRenderer {
     void this.enqueueInputCommand({
       kind: 'mouse',
       runEpoch: runEpochArg,
-      execute: async () => this.client.dispatchMouse(input),
+      execute: async (optionsArg) => this.client.dispatchMouse(input, optionsArg),
       onAttempt: () => this.pressedMouseButtons.set(button, input),
     }).catch(() => undefined);
   }
@@ -690,7 +835,7 @@ export class LiveBrowserCanvasRenderer {
     void this.enqueueInputCommand({
       kind: 'mouseMove',
       runEpoch: runEpochArg,
-      execute: async () => this.client.dispatchMouse(input),
+      execute: async (optionsArg) => this.client.dispatchMouse(input, optionsArg),
     }).catch(() => undefined);
   }
 
@@ -723,7 +868,7 @@ export class LiveBrowserCanvasRenderer {
     void this.enqueueInputCommand({
       kind: 'mouse',
       runEpoch: runEpochArg,
-      execute: async () => this.client.dispatchMouse(input),
+      execute: async (optionsArg) => this.client.dispatchMouse(input, optionsArg),
       onSuccess: () => this.pressedMouseButtons.delete(button),
     }).catch(() => undefined);
     this.releasePointerCapture(eventArg.pointerId);
@@ -748,13 +893,13 @@ export class LiveBrowserCanvasRenderer {
     void this.enqueueInputCommand({
       kind: 'wheel',
       runEpoch: runEpochArg,
-      execute: async () => this.client.dispatchWheel({
+      execute: async (optionsArg) => this.client.dispatchWheel({
         ...createInputIdentity(displayedFrame),
         ...coordinates,
         deltaX: clampDelta(eventArg.deltaX * multiplier),
         deltaY: clampDelta(eventArg.deltaY * multiplier),
         modifiers: createModifiers(eventArg),
-      }),
+      }, optionsArg),
     }).catch(() => undefined);
   }
 
@@ -795,7 +940,7 @@ export class LiveBrowserCanvasRenderer {
     void this.enqueueInputCommand({
       kind: 'key',
       runEpoch: runEpochArg,
-      execute: async () => this.client.dispatchKey(input),
+      execute: async (optionsArg) => this.client.dispatchKey(input, optionsArg),
       onAttempt: typeArg === 'down'
         ? () => this.pressedKeys.set(keyIdentity, input)
         : undefined,
@@ -916,34 +1061,44 @@ export class LiveBrowserCanvasRenderer {
       try {
         while (this.inputCommands.length > 0) {
           const command = this.inputCommands.shift()!;
-          if (command.runEpoch !== this.runEpoch) {
-            command.resolve();
+          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');
+            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);
-            command.reject(error);
             const abandonedCommands = this.inputCommands.splice(0);
             for (const abandonedCommand of abandonedCommands) {
               abandonedCommand.reject(
                 new Error('Live browser input was abandoned after a dispatch failure'),
               );
             }
-            if (!this.stopping) {
+            if (!(error instanceof LiveBrowserOperationTimeoutError) && !this.stopping) {
               void this.scheduleInputReset(false, command.runEpoch);
             }
-            if (error instanceof LiveBrowserOperationTimeoutError) {
-              this.requestStop(command.runEpoch);
-            }
           }
         }
       } finally {
@@ -1017,13 +1172,13 @@ export class LiveBrowserCanvasRenderer {
   private async releasePressedInput(runEpochArg: number): Promise<void> {
     for (const [keyIdentity, pressedKey] of [...this.pressedKeys.entries()]) {
       const released = await this.tryInputRelease(
-        () => this.client.dispatchKey({
+        (optionsArg) => this.client.dispatchKey({
           ...pressedKey,
           type: 'up',
           text: undefined,
           autoRepeat: false,
           modifiers: {},
-        }),
+        }, optionsArg),
         runEpochArg,
       );
       if (released && this.pressedKeys.get(keyIdentity) === pressedKey) {
@@ -1032,13 +1187,13 @@ export class LiveBrowserCanvasRenderer {
     }
     for (const [button, pressedButton] of [...this.pressedMouseButtons.entries()]) {
       const released = await this.tryInputRelease(
-        () => this.client.dispatchMouse({
+        (optionsArg) => this.client.dispatchMouse({
           ...pressedButton,
           type: 'up',
           buttons: 0,
           clickCount: 1,
           modifiers: {},
-        }),
+        }, optionsArg),
         runEpochArg,
       );
       if (released && this.pressedMouseButtons.get(button) === pressedButton) {
@@ -1048,7 +1203,7 @@ export class LiveBrowserCanvasRenderer {
   }
 
   private async tryInputRelease(
-    operationArg: () => Promise<void>,
+    operationArg: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<void>,
     runEpochArg: number,
   ): Promise<boolean> {
     let lastError: unknown;
@@ -1057,14 +1212,18 @@ export class LiveBrowserCanvasRenderer {
         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);
-    this.requestStop(runEpochArg);
     return false;
   }
 
@@ -1080,26 +1239,13 @@ export class LiveBrowserCanvasRenderer {
     if (
       !this.running
       || this.stopping
-      || this.stopRequested
+      || this.interruptionRequested
       || runEpochArg !== this.runEpoch
-      || widthArg <= 0
-      || heightArg <= 0
     ) {
       return;
     }
-    const deviceScaleFactor = this.getDeviceScaleFactor();
-    if (!Number.isFinite(deviceScaleFactor) || deviceScaleFactor <= 0) {
-      this.reportError({
-        code: 'viewport_update_failed',
-        message: 'Live browser device scale factor must be a positive finite number',
-      }, runEpochArg);
-      return;
-    }
-    const viewport: ILiveBrowserViewport = {
-      width: widthArg,
-      height: heightArg,
-      deviceScaleFactor,
-    };
+    const viewport = this.normalizeGeneratedViewport(widthArg, heightArg, runEpochArg);
+    if (!viewport) return;
     if (this.pendingViewport && viewportEquals(viewport, this.pendingViewport)) {
       return;
     }
@@ -1130,6 +1276,61 @@ export class LiveBrowserCanvasRenderer {
     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;
@@ -1175,8 +1376,9 @@ export class LiveBrowserCanvasRenderer {
         const previousMinimumRevision = this.resizeFence?.minimumViewportRevision ?? currentRevision;
         try {
           await this.runClientOperation(
-            () => this.client.setViewport(viewport),
+            (optionsArg) => this.client.setViewport(viewport, optionsArg),
             'viewport update',
+            runEpochArg,
           );
           if (!this.running || this.stopping || runEpochArg !== this.runEpoch) {
             return;
@@ -1186,16 +1388,16 @@ export class LiveBrowserCanvasRenderer {
             minimumViewportRevision: Math.max(currentRevision, previousMinimumRevision) + 1,
           };
         } catch (error) {
-          if (runEpochArg === this.runEpoch) {
+          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);
-            if (error instanceof LiveBrowserOperationTimeoutError) {
-              this.requestStop(runEpochArg);
-            }
           }
         } finally {
           if (this.inFlightViewport && viewportEquals(this.inFlightViewport, viewport)) {
@@ -1216,8 +1418,6 @@ export class LiveBrowserCanvasRenderer {
       && !this.viewportProcessing
       && !this.resizeFence
       && this.inputResetCount === 0
-      && this.pressedKeys.size === 0
-      && this.pressedMouseButtons.size === 0
       && this.isDisplayedFrameCurrent()
     );
   }
@@ -1276,22 +1476,12 @@ export class LiveBrowserCanvasRenderer {
     }
   }
 
-  private requestStop(runEpochArg: number): void {
-    if (
-      runEpochArg !== this.runEpoch
-      || (!this.running && !this.stopping)
-    ) {
+  private requestSuspend(runEpochArg: number): void {
+    if (!this.isRunActive(runEpochArg) || this.interruptionRequested) {
       return;
     }
-    this.terminallyStopped = true;
-    this.acceptingFrames = false;
-    this.inputBlocked = true;
-    this.pendingViewport = undefined;
-    if (this.stopping || this.stopRequested) {
-      return;
-    }
-    this.stopRequested = true;
-    void this.stop();
+    this.interruptRun(runEpochArg);
+    void this.suspend();
   }
 
   private validateTimeout(timeoutArg: number, nameArg: string): number {
@@ -1302,68 +1492,257 @@ export class LiveBrowserCanvasRenderer {
   }
 
   private runClientOperation<T>(
-    operationArg: () => Promise<T>,
+    operationArg: (optionsArg: ILiveBrowserCanvasOperationOptions) => Promise<T>,
     operationNameArg: string,
+    runEpochArg: number,
   ): Promise<T> {
-    let operation: Promise<T>;
-    try {
-      operation = operationArg();
-    } catch (error) {
-      return Promise.reject(error);
-    }
-    return this.withTimeout(operation, this.operationTimeoutMs, operationNameArg);
+    return this.runAbortableOperation(
+      (signalArg) => operationArg({ signal: signalArg }),
+      this.operationTimeoutMs,
+      operationNameArg,
+      runEpochArg,
+    );
   }
 
-  private withTimeout<T>(
-    operationArg: Promise<T>,
+  private runAbortableOperation<T>(
+    operationArg: (signalArg: AbortSignal) => Promise<T>,
     timeoutMsArg: number,
     operationNameArg: string,
+    runEpochArg: number,
   ): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
+    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 timeout = globalThis.setTimeout(() => {
+      const settle = (callbackArg: () => void) => {
         if (!settled) {
           settled = true;
-          reject(new LiveBrowserOperationTimeoutError(
-            `${operationNameArg} timed out after ${timeoutMsArg}ms`,
-          ));
+          callbackArg();
         }
-      }, timeoutMsArg);
-      operationArg.then(
+      };
+      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) => {
-          if (!settled) {
-            settled = true;
-            globalThis.clearTimeout(timeout);
-            resolve(valueArg);
-          }
+          settle(() => resolve(valueArg));
         },
         (errorArg) => {
-          if (!settled) {
-            settled = true;
-            globalThis.clearTimeout(timeout);
-            reject(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): Promise<ImageBitmap> {
+  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.withTimeout(
-        decodeOperation,
+      return await this.runAbortableOperation(
+        async () => decodeOperation,
         this.frameDecodeTimeoutMs,
         'frame decode',
+        runEpochArg,
       );
     } catch (error) {
-      void decodeOperation.then((lateBitmapArg) => lateBitmapArg.close(), () => undefined);
-      throw 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`,
+      );
     }
   }