@modelprofile.com/browser-runtime 5.5.1 → 5.7.0

package/dist_ts/errors.d.ts

@@ -1,4 +1,4 @@
-export type TBrowserRuntimeErrorCode = 'ABORTED' | 'AUTHORIZATION_DENIED' | 'ATTACHMENT_CONFLICT' | 'BUSY' | 'CAPABILITY_EXPIRED' | 'CAPABILITY_INVALID' | 'CAPABILITY_REVOKED' | 'CONFINEMENT_FAILED' | 'EGRESS_DENIED' | 'FENCED' | 'FRAME_STREAM_FAILED' | 'FRAME_TOO_LARGE' | 'DIALOG_PENDING' | 'STALE_INPUT' | 'INVALID_INPUT' | 'LOCKED' | 'NOT_RUNNING' | 'PROTOCOL_ERROR' | 'QUOTA_EXCEEDED' | 'RESOURCE_NOT_FOUND' | 'RESOURCE_RETIRED' | 'TIMEOUT';
+export type TBrowserRuntimeErrorCode = 'ABORTED' | 'AUTHORIZATION_DENIED' | 'ATTACHMENT_CONFLICT' | 'BUSY' | 'CAPABILITY_EXPIRED' | 'CAPABILITY_INVALID' | 'CAPABILITY_REVOKED' | 'CONFINEMENT_FAILED' | 'EGRESS_DENIED' | 'FENCED' | 'FRAME_STREAM_FAILED' | 'FRAME_TOO_LARGE' | 'DIALOG_PENDING' | 'STALE_INPUT' | 'SUPERSEDED' | 'INVALID_INPUT' | 'LOCKED' | 'NOT_RUNNING' | 'PROTOCOL_ERROR' | 'QUOTA_EXCEEDED' | 'RESOURCE_NOT_FOUND' | 'RESOURCE_RETIRED' | 'TIMEOUT';
 export declare class BrowserRuntimeError extends Error {
     readonly code: TBrowserRuntimeErrorCode;
     constructor(code: TBrowserRuntimeErrorCode, internalMessage?: string);

package/dist_ts/errors.js

@@ -13,6 +13,7 @@ const publicMessages = {
     FRAME_TOO_LARGE: 'The browser frame exceeded its limit.',
     DIALOG_PENDING: 'Respond to the website dialog before sending input.',
     STALE_INPUT: 'The input belongs to a previous document or dialog.',
+    SUPERSEDED: 'A newer hover input replaced this queued operation.',
     INVALID_INPUT: 'The request is invalid.',
     LOCKED: 'The browser runtime is already locked.',
     NOT_RUNNING: 'The browser runtime is not running.',
@@ -43,4 +44,4 @@ export const toBrowserRuntimeError = (error) => {
     }
     return new BrowserRuntimeError('ABORTED');
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvZXJyb3JzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXdCQSxNQUFNLGNBQWMsR0FBNkM7SUFDL0QsT0FBTyxFQUFFLDRCQUE0QjtJQUNyQyxvQkFBb0IsRUFBRSxzQ0FBc0M7SUFDNUQsbUJBQW1CLEVBQUUsNkRBQTZEO0lBQ2xGLElBQUksRUFBRSwrQkFBK0I7SUFDckMsa0JBQWtCLEVBQUUsNkJBQTZCO0lBQ2pELGtCQUFrQixFQUFFLDRCQUE0QjtJQUNoRCxrQkFBa0IsRUFBRSxrQ0FBa0M7SUFDdEQsa0JBQWtCLEVBQUUsNkNBQTZDO0lBQ2pFLGFBQWEsRUFBRSwrQkFBK0I7SUFDOUMsTUFBTSxFQUFFLDZDQUE2QztJQUNyRCxtQkFBbUIsRUFBRSxrQ0FBa0M7SUFDdkQsZUFBZSxFQUFFLHVDQUF1QztJQUN4RCxjQUFjLEVBQUUscURBQXFEO0lBQ3JFLFdBQVcsRUFBRSxxREFBcUQ7SUFDbEUsYUFBYSxFQUFFLHlCQUF5QjtJQUN4QyxNQUFNLEVBQUUsd0NBQXdDO0lBQ2hELFdBQVcsRUFBRSxxQ0FBcUM7SUFDbEQsY0FBYyxFQUFFLHlDQUF5QztJQUN6RCxjQUFjLEVBQUUsdUNBQXVDO0lBQ3ZELGtCQUFrQixFQUFFLHlDQUF5QztJQUM3RCxnQkFBZ0IsRUFBRSx3Q0FBd0M7SUFDMUQsT0FBTyxFQUFFLDBCQUEwQjtDQUNwQyxDQUFDO0FBRUYsTUFBTSxPQUFPLG1CQUFvQixTQUFRLEtBQUs7SUFDNUIsSUFBSSxDQUEyQjtJQUUvQyxZQUFZLElBQThCLEVBQUUsZUFBd0I7UUFDbEUsS0FBSyxDQUFDLGVBQWUsSUFBSSxjQUFjLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQztRQUMvQyxJQUFJLENBQUMsSUFBSSxHQUFHLHFCQUFxQixDQUFDO1FBQ2xDLElBQUksQ0FBQyxJQUFJLEdBQUcsSUFBSSxDQUFDO0lBQ25CLENBQUM7SUFFRCxJQUFXLGFBQWE7UUFDdEIsT0FBTyxjQUFjLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFDO0lBQ25DLENBQUM7Q0FDRjtBQUVELE1BQU0sQ0FBQyxNQUFNLHFCQUFxQixHQUFHLENBQUMsS0FBYyxFQUF1QixFQUFFO0lBQzNFLElBQUksS0FBSyxZQUFZLG1CQUFtQixFQUFFLENBQUM7UUFDekMsT0FBTyxLQUFLLENBQUM7SUFDZixDQUFDO0lBQ0QsSUFDRSxLQUFLLFlBQVksS0FBSztXQUNuQixDQUFDLEtBQUssQ0FBQyxJQUFJLEtBQUssWUFBWSxJQUFJLEtBQUssQ0FBQyxJQUFJLEtBQUssY0FBYyxDQUFDLEVBQ2pFLENBQUM7UUFDRCxPQUFPLElBQUksbUJBQW1CLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxjQUFjLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDeEYsQ0FBQztJQUNELE9BQU8sSUFBSSxtQkFBbUIsQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUM1QyxDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvZXJyb3JzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXlCQSxNQUFNLGNBQWMsR0FBNkM7SUFDL0QsT0FBTyxFQUFFLDRCQUE0QjtJQUNyQyxvQkFBb0IsRUFBRSxzQ0FBc0M7SUFDNUQsbUJBQW1CLEVBQUUsNkRBQTZEO0lBQ2xGLElBQUksRUFBRSwrQkFBK0I7SUFDckMsa0JBQWtCLEVBQUUsNkJBQTZCO0lBQ2pELGtCQUFrQixFQUFFLDRCQUE0QjtJQUNoRCxrQkFBa0IsRUFBRSxrQ0FBa0M7SUFDdEQsa0JBQWtCLEVBQUUsNkNBQTZDO0lBQ2pFLGFBQWEsRUFBRSwrQkFBK0I7SUFDOUMsTUFBTSxFQUFFLDZDQUE2QztJQUNyRCxtQkFBbUIsRUFBRSxrQ0FBa0M7SUFDdkQsZUFBZSxFQUFFLHVDQUF1QztJQUN4RCxjQUFjLEVBQUUscURBQXFEO0lBQ3JFLFdBQVcsRUFBRSxxREFBcUQ7SUFDbEUsVUFBVSxFQUFFLHFEQUFxRDtJQUNqRSxhQUFhLEVBQUUseUJBQXlCO0lBQ3hDLE1BQU0sRUFBRSx3Q0FBd0M7SUFDaEQsV0FBVyxFQUFFLHFDQUFxQztJQUNsRCxjQUFjLEVBQUUseUNBQXlDO0lBQ3pELGNBQWMsRUFBRSx1Q0FBdUM7SUFDdkQsa0JBQWtCLEVBQUUseUNBQXlDO0lBQzdELGdCQUFnQixFQUFFLHdDQUF3QztJQUMxRCxPQUFPLEVBQUUsMEJBQTBCO0NBQ3BDLENBQUM7QUFFRixNQUFNLE9BQU8sbUJBQW9CLFNBQVEsS0FBSztJQUM1QixJQUFJLENBQTJCO0lBRS9DLFlBQVksSUFBOEIsRUFBRSxlQUF3QjtRQUNsRSxLQUFLLENBQUMsZUFBZSxJQUFJLGNBQWMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDO1FBQy9DLElBQUksQ0FBQyxJQUFJLEdBQUcscUJBQXFCLENBQUM7UUFDbEMsSUFBSSxDQUFDLElBQUksR0FBRyxJQUFJLENBQUM7SUFDbkIsQ0FBQztJQUVELElBQVcsYUFBYTtRQUN0QixPQUFPLGNBQWMsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLENBQUM7SUFDbkMsQ0FBQztDQUNGO0FBRUQsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsQ0FBQyxLQUFjLEVBQXVCLEVBQUU7SUFDM0UsSUFBSSxLQUFLLFlBQVksbUJBQW1CLEVBQUUsQ0FBQztRQUN6QyxPQUFPLEtBQUssQ0FBQztJQUNmLENBQUM7SUFDRCxJQUNFLEtBQUssWUFBWSxLQUFLO1dBQ25CLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxZQUFZLElBQUksS0FBSyxDQUFDLElBQUksS0FBSyxjQUFjLENBQUMsRUFDakUsQ0FBQztRQUNELE9BQU8sSUFBSSxtQkFBbUIsQ0FBQyxLQUFLLENBQUMsSUFBSSxLQUFLLGNBQWMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQztJQUN4RixDQUFDO0lBQ0QsT0FBTyxJQUFJLG1CQUFtQixDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQzVDLENBQUMsQ0FBQyJ9

package/dist_ts/interfaces.d.ts

@@ -225,6 +225,7 @@ export interface IBrowserRuntimeEventSubscriptionOptions {
 export type TBrowserRuntimeVideoOffer = Omit<plugins.smartpuppeteer.ILiveVideoOffer, 'peerId'>;
 export interface IBrowserRuntimeState {
     videoAcceleration?: plugins.smartpuppeteer.ILiveVideoAcceleration;
+    videoSource?: plugins.smartpuppeteer.ILiveVideoSource;
     status: 'stopped' | 'starting' | 'running' | 'stopping';
     activeTabId: string | null;
     viewportRevision: number;
@@ -336,6 +337,8 @@ export interface IBrowserRuntimeOperationOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
     onOperationStarted?(operationId: string): void;
+    /** Replace an adjacent, unstarted hover from this lease. Superseded calls reject with SUPERSEDED. */
+    coalesceHoverMoves?: boolean;
 }
 export interface IBrowserRuntimeFrameSubscription {
     close(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "5.5.1",
+  "version": "5.7.0",
   "private": false,
   "description": "Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.",
   "main": "dist_ts/index.js",
@@ -30,7 +30,7 @@
     "@push.rocks/smartagent": "^6.0.0",
     "@push.rocks/smartipc": "^2.6.0",
     "@push.rocks/smartmcp": "^0.3.0",
-    "@push.rocks/smartpuppeteer": "^2.12.2",
+    "@push.rocks/smartpuppeteer": "^2.13.0",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {

package/readme.md

@@ -34,6 +34,19 @@ Human leases expose `openVideoPeer(options?)`, `answerVideoPeer(negotiationId, d
 
 Set `video` on `BrowserRuntime` for trusted host limits or ICE configuration. Defaults use direct connections with no external STUN/TURN service and automatic GPU support. The private capture extension is loaded without weakening ordinary page proxy, DNS, permission or WebRTC confinement. `state.videoAcceleration` and peer statistics report actual browser acceleration/encoder support.
 
+`video: { backend: 'native', maxFrameRate: 30 }` selects SmartPuppeteer's Rust/NVIDIA
+capture and NVENC sender. Chromium remains the default backend. Native viewers must
+forward `state.videoSource` unchanged, including its RTP presentation fence and coded
+frame alignment. The native viewport negotiates device scale 1 and fits the configured
+capture limits while preserving the preferred aspect ratio. The returned viewport owns
+input coordinates. Unsupported receiver codec limits fail negotiation explicitly.
+
+Forward DOM pointer `event.timeStamp` as `dispatchMouse().timestampMs` to preserve the
+occurrence spacing of a gesture delivered in a transport burst. Participant changes reset
+the native timing history because viewer clocks have different origins; synthesized
+button releases omit timestamps. Existing operation ordering and held-button ownership
+remain authoritative.
+
 Native viewers should call `lease.subscribeEvents(listener, { includeFrames: false })`. They receive state and errors without generating JPEG traffic. Existing image consumers retain the default `includeFrames: true`; capture starts for the first such subscriber and stops after the last closes. Agent snapshots remain independent of continuous capture. Image subscription cleanup is serialized, coalesced and retryable; a failed disable is retained until cleanup succeeds or its exact browser incarnation terminates.
 
 ## Issue Reporting and Security
@@ -164,6 +177,9 @@ Agent actions are exactly `navigate`, `snapshot`, `screenshot`, `click`, `fill`,
 
 BrowserRuntime alone owns the bounded execution scheduler shared by all participants. Host transports submit operations in order without adding a second execution queue or performing asynchronous authorization ahead of admission. One statistics read may run independently of mutations; its preflight and completion cannot fence input, navigation, or dialog replies. Up to four wheel operations may run concurrently, with authorization and native-send admission kept in order. Other input, viewport, and semantic operations remain barriers behind preceding wheel work. Dialog replies use one interrupt slot so a paused document operation cannot block its own response. `maxQueuedOperationsPerLease` defaults to 128 and accepts 1 through 1,024; each participant has that bound, and the resource queue is bounded by its product with `maxCapabilitiesPerResource`. Overflow fails with `QUOTA_EXCEEDED`. Releasing a participant cancels only its queued and active work. Resource termination and shutdown cancel everyone. Started uncertain work must quiesce or the exact incarnation is terminated before operation settlement.
 
+Interactive hosts can pass `{ coalesceHoverMoves: true }` to `humanLease.dispatchMouse()`. Only an adjacent, unstarted, unpressed move from the same lease, document, viewport and modifier state is replaced. The replaced promise rejects with `BrowserRuntimeError` code `SUPERSEDED`; hosts should report that terminal outcome without treating it as a failed connection. Drag paths, queued or held buttons, other participants, and discrete operations retain their order. The default preserves every submitted operation.
+
+
 `setViewport()` stores the viewer's preferred width, height and device scale factor and returns `IBrowserRuntimeViewportResult` with the effective `viewport` and `viewportRevision`. The effective values are the componentwise minima across active viewers that have supplied a preference. Unchanged effective sizes do not restart the stream. Removing a viewer recomputes the viewport in the resource FIFO. Held keys and buttons are tracked per participant; leaving releases only inputs that no other participant holds. Viewport and tab/navigation transitions clear held input before changing the target. Resource-owned departure cleanup is bounded and audited as `releaseParticipant`; it does not call the external `beforeOperation` gate after the participant has lost access.
 
 `beforeOperation` is an optional awaited fail-closed gate. It receives the complete immutable authority, operation/capability/lease IDs, action, classification, start time, and an `AbortSignal` after dequeue but before the browser side effect starts. Classifications are `raw-input`, `dialog`, `devtools`, `frame-stream`, `video-peer`, `viewport`, `navigation`, `tab`, and `agent-action`. Hosts that require durable attempt-before-side-effect auditing should persist the attempt there. Rejection denies the operation. The default `beforeOperationTimeoutMs` is 10,000 milliseconds and accepts values from 100 through 120,000; timeout fails with `TIMEOUT`. The terminal `audit` callback remains a best-effort `completed`/`failed` notification correlated by the same operation ID and classification and runs after bounded operation cleanup releases or fences the exact reservation.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '5.5.1',
+  version: '5.7.0',
   description: 'Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.'
 }

package/ts/classes.runtime.ts

@@ -172,6 +172,7 @@ export interface IBrowserRuntimeLeaseRenewalOptions {
 }
 
 interface IOperationRecord {
+  hoverKey?: string;
   operationId: string;
   lease: ILeaseRecord;
   controller: AbortController;
@@ -183,6 +184,7 @@ interface IOperationRecord {
 }
 
 interface IQueuedOperationRecord {
+  hoverKey?: string;
   operationId: string;
   lease: ILeaseRecord;
   action: string;
@@ -263,6 +265,7 @@ interface IResourceSlot {
   profileDirectory?: string;
   unsubscribeSession?: () => void;
   leases: Map<string, ILeaseRecord>;
+  lastMouseTimestampLeaseId?: string;
   operations: Set<IOperationRecord>;
   inputCleanup?: { session: ILiveBrowserSessionLike; incarnationGeneration: number; promise: Promise<void> };
   operationScheduler: BrowserOperationScheduler<IQueuedOperationRecord>;
@@ -1595,7 +1598,16 @@ export class BrowserRuntime {
       width: Math.min(...preferences.map((value) => value.width)),
       height: Math.min(...preferences.map((value) => value.height)),
       deviceScaleFactor: Math.min(...preferences.map((value) => value.deviceScaleFactor)),
-    } : current.viewport;
+    } : { ...current.viewport };
+    if (this.options.video.backend === 'native') {
+      // A native desktop has physical pixels. Negotiate the accepted viewport
+      // here so all viewers use the same layout and coordinate space.
+      const scale = Math.min(1, this.options.video.maxWidth / viewport.width,
+        this.options.video.maxHeight / viewport.height);
+      viewport.width = Math.max(1, Math.floor(viewport.width * scale));
+      viewport.height = Math.max(1, Math.floor(viewport.height * scale));
+      viewport.deviceScaleFactor = 1;
+    }
     if (
       viewport.width !== current.viewport.width || viewport.height !== current.viewport.height
       || viewport.deviceScaleFactor !== current.viewport.deviceScaleFactor
@@ -1671,6 +1683,21 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions = {},
   ): Promise<void> {
     this.requireHuman(lease);
+    const mouse = action === 'dispatchMouse' ? input as plugins.smartpuppeteer.ILiveBrowserMouseInput : undefined;
+    if (mouse?.timestampMs !== undefined && (!Number.isFinite(mouse.timestampMs) || mouse.timestampMs < 0)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    // Drag paths and shared held input have observable intermediate positions.
+    // Only explicit hover submissions can replace another pending hover.
+    const hoverKey = operationOptions.coalesceHoverMoves && mouse?.type === 'move'
+      && (mouse.buttons ?? 0) === 0 && (mouse.button ?? 'none') === 'none'
+      && Number.isFinite(mouse.x) && Number.isFinite(mouse.y) && mouse.x >= 0 && mouse.y >= 0
+      && ![...lease.slot.leases.values()].some(participant => participant.heldButtons.size > 0)
+      && !lease.slot.operationScheduler.pending.some(operation => operation.action === 'dispatchMouse' && !operation.hoverKey)
+      && ![...lease.slot.operations].some(operation => operation.action === 'dispatchMouse' && !operation.hoverKey)
+      ? JSON.stringify([mouse.tabId, mouse.generation, mouse.viewportRevision,
+        mouse.modifiers?.alt ?? false, mouse.modifiers?.control ?? false,
+        mouse.modifiers?.meta ?? false, mouse.modifiers?.shift ?? false]) : undefined;
     await this.runOperation(lease, action, 'raw-input', operationOptions, async (_signal, session) => {
       if (action === 'dispatchMouse') {
         const mouse = input as plugins.smartpuppeteer.ILiveBrowserMouseInput;
@@ -1689,11 +1716,16 @@ export class BrowserRuntime {
           throw new BrowserRuntimeError('QUOTA_EXCEEDED');
         }
         if (mouse.type === 'down') lease.heldButtons.set(key, { ...mouse });
+        const previousClock = lease.slot.lastMouseTimestampLeaseId;
+        // Viewer performance clocks have unrelated origins. An untimed event
+        // resets native gesture pacing when another participant takes over.
         await session.dispatchMouse({ ...mouse,
+          timestampMs: previousClock && previousClock !== lease.leaseId ? undefined : mouse.timestampMs,
           buttons: this.sharedMouseButtons(lease.slot, mouse.tabId,
             mouse.type === 'up' ? { lease, key } : undefined),
           modifiers: this.sharedModifiers(lease.slot, mouse.tabId, mouse.modifiers),
         });
+        lease.slot.lastMouseTimestampLeaseId = lease.leaseId;
         if (mouse.type === 'up') lease.heldButtons.delete(key);
       } else if (action === 'dispatchWheel') {
         const wheel = input as plugins.smartpuppeteer.ILiveBrowserWheelInput;
@@ -1726,7 +1758,7 @@ export class BrowserRuntime {
       } else {
         await session.insertText(input as plugins.smartpuppeteer.ILiveBrowserInsertTextInput);
       }
-    });
+    }, undefined, false, hoverKey);
   }
 
   private keyOwnershipKey(input: plugins.smartpuppeteer.ILiveBrowserKeyInput): string {
@@ -2351,6 +2383,7 @@ export class BrowserRuntime {
     execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<T>,
     finalize?: () => Promise<void>,
     participantCleanup: 'participant' | 'subscription' | false = false,
+    hoverKey?: string,
   ): Promise<T> {
     if (!operationOptions || typeof operationOptions !== 'object') {
       throw new BrowserRuntimeError('INVALID_INPUT');
@@ -2364,10 +2397,15 @@ export class BrowserRuntime {
       && typeof operationOptions.onOperationStarted !== 'function'
     ) throw new BrowserRuntimeError('INVALID_INPUT');
     if (operationOptions.signal?.aborted) throw new BrowserRuntimeError('ABORTED');
+    if (operationOptions.coalesceHoverMoves !== undefined
+      && typeof operationOptions.coalesceHoverMoves !== 'boolean') throw new BrowserRuntimeError('INVALID_INPUT');
     const slot = lease.slot;
     this.requireQueuedLease(lease, participantCleanup);
     this.assertSlotAvailable(slot);
-    if (!participantCleanup && (
+    const previousHover = slot.operationScheduler.pending.at(-1);
+    const superseded = hoverKey !== undefined && previousHover?.state === 'queued'
+      && previousHover.lease === lease && previousHover.hoverKey === hoverKey ? previousHover : undefined;
+    if (!participantCleanup && !superseded && (
       slot.operationScheduler.pending.filter((entry) => entry.lease === lease).length
         >= this.options.maxQueuedOperationsPerLease
       || slot.operationScheduler.pending.length >= this.options.maxQueuedOperationsPerLease
@@ -2385,6 +2423,7 @@ export class BrowserRuntime {
     ]);
     return new Promise<T>((resolve, reject) => {
       const queued: IQueuedOperationRecord = {
+        hoverKey,
         operationId: randomId(18),
         lease,
         action,
@@ -2423,6 +2462,14 @@ export class BrowserRuntime {
         onQueuedAbort();
         return;
       }
+      if (superseded) {
+        // Replace atomically before draining; remove() would start the old tail's successor.
+        const index = slot.operationScheduler.pending.indexOf(superseded);
+        if (index >= 0) slot.operationScheduler.pending.splice(index, 1);
+        superseded.state = 'settled';
+        if (superseded.onQueuedAbort) superseded.signal.removeEventListener('abort', superseded.onQueuedAbort);
+        superseded.reject(new BrowserRuntimeError('SUPERSEDED'));
+      }
       slot.operationScheduler.enqueue(queued);
     });
   }
@@ -2471,6 +2518,7 @@ export class BrowserRuntime {
         timeoutController.signal,
       ]);
       operation = {
+        hoverKey: queued.hoverKey,
         operationId: queued.operationId,
         lease,
         controller,
@@ -2890,6 +2938,7 @@ export class BrowserRuntime {
   private resourceState(state: plugins.smartpuppeteer.ILiveBrowserState): IBrowserRuntimeState {
     return {
       ...(state.videoAcceleration ? { videoAcceleration: { ...state.videoAcceleration } } : {}),
+      ...(state.videoSource ? { videoSource: structuredClone(state.videoSource) } : {}),
       status: state.status,
       activeTabId: state.activeTabId ? truncateString(state.activeTabId, 128) : null,
       viewportRevision: state.viewportRevision,

package/ts/errors.ts

@@ -13,6 +13,7 @@ export type TBrowserRuntimeErrorCode =
   | 'FRAME_TOO_LARGE'
   | 'DIALOG_PENDING'
   | 'STALE_INPUT'
+  | 'SUPERSEDED'
   | 'INVALID_INPUT'
   | 'LOCKED'
   | 'NOT_RUNNING'
@@ -37,6 +38,7 @@ const publicMessages: Record<TBrowserRuntimeErrorCode, string> = {
   FRAME_TOO_LARGE: 'The browser frame exceeded its limit.',
   DIALOG_PENDING: 'Respond to the website dialog before sending input.',
   STALE_INPUT: 'The input belongs to a previous document or dialog.',
+  SUPERSEDED: 'A newer hover input replaced this queued operation.',
   INVALID_INPUT: 'The request is invalid.',
   LOCKED: 'The browser runtime is already locked.',
   NOT_RUNNING: 'The browser runtime is not running.',

package/ts/interfaces.ts

@@ -333,6 +333,7 @@ export type TBrowserRuntimeVideoOffer = Omit<plugins.smartpuppeteer.ILiveVideoOf
 
 export interface IBrowserRuntimeState {
   videoAcceleration?: plugins.smartpuppeteer.ILiveVideoAcceleration;
+  videoSource?: plugins.smartpuppeteer.ILiveVideoSource;
   status: 'stopped' | 'starting' | 'running' | 'stopping';
   activeTabId: string | null;
   viewportRevision: number;
@@ -460,6 +461,8 @@ export interface IBrowserRuntimeOperationOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
   onOperationStarted?(operationId: string): void;
+  /** Replace an adjacent, unstarted hover from this lease. Superseded calls reject with SUPERSEDED. */
+  coalesceHoverMoves?: boolean;
 }
 
 export interface IBrowserRuntimeFrameSubscription {