@modelprofile.com/browser-runtime 5.1.0 → 5.2.0

package/dist_ts/index.d.ts

@@ -8,4 +8,4 @@ export { BrowserRuntimeError } from './errors.js';
 export { createBrowserRuntimeMcpHttpHandler } from './mcp.js';
 export type { TAcquireBrowserRuntimeLeaseOptions, IBrowserRuntimeLeaseRenewalOptions, } from './classes.runtime.js';
 export type { TBrowserRuntimeErrorCode } from './errors.js';
-export type { IAttachTrustedFramedPeerOptions, IApplyBrowserAttachmentBindingRequest, IBrowserAttachmentBinding, IBrowserActionStateResult, IBrowserArtifactMetadata, IBrowserArtifactStoreOptions, IBrowserMcpAuthenticatedBinding, TBrowserCapabilityAuthorizationRequest, TBrowserCapabilityDescriptor, IBrowserClickAction, IBrowserEgressConnectionOptions, IBrowserEgressProxyOptions, IBrowserEgressProxyStats, IBrowserFlexCapabilityBinding, IBrowserFlexSessionId, IBrowserCodexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserRuntimeScreencastOptions, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeViewportResult, IBrowserRuntimeTabState, IBrowserScreenshotAction, IBrowserScreenshotResult, IBrowserSnapshotAction, ICreateBrowserResourceRequest, TIssueBrowserCapabilityRequest, TIssuedBrowserCapability, TQualifiedBrowserSessionId, IRegisterBrowserResourceRequest, IResolvedBrowserFlexCapability, TBrowserActorRole, TBrowserAgentAction, TBrowserAgentActionResult, TBrowserCapabilitySource, TBrowserDnsResolver, TBrowserEgressConnector, TBrowserHarnessId, TBrowserRuntimeEvent, } from './interfaces.js';
+export type { IAttachTrustedFramedPeerOptions, IApplyBrowserAttachmentBindingRequest, IBrowserAttachmentBinding, IBrowserActionStateResult, IBrowserArtifactMetadata, IBrowserArtifactStoreOptions, IBrowserMcpAuthenticatedBinding, TBrowserCapabilityAuthorizationRequest, TBrowserCapabilityDescriptor, IBrowserClickAction, IBrowserEgressConnectionOptions, IBrowserEgressProxyOptions, IBrowserEgressProxyStats, IBrowserFlexCapabilityBinding, IBrowserFlexSessionId, IBrowserCodexSessionId, IBrowserFillAction, IBrowserNavigateAction, IBrowserObservationResult, IBrowserOpenCodeSessionId, IBrowserPressAction, TBrowserRuntimeAuditEvent, TBrowserRuntimeLeaseAuthority, TBrowserRuntimeOperationClassification, TBrowserRuntimeOperationIdentity, IBrowserRuntimeFlexToolProviderOptions, IBrowserRuntimeFrameSubscription, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeMcpOptions, IBrowserRuntimeOperationOptions, IBrowserRuntimeOptions, IBrowserRuntimeScreencastOptions, IBrowserRuntimeEventSubscriptionOptions, TBrowserRuntimeVideoOffer, IBrowserResourceKey, IBrowserResourceRegistration, IBrowserRuntimeState, IBrowserRuntimeViewportResult, IBrowserRuntimeTabState, IBrowserScreenshotAction, IBrowserScreenshotResult, IBrowserSnapshotAction, ICreateBrowserResourceRequest, TIssueBrowserCapabilityRequest, TIssuedBrowserCapability, TQualifiedBrowserSessionId, IRegisterBrowserResourceRequest, IResolvedBrowserFlexCapability, TBrowserActorRole, TBrowserAgentAction, TBrowserAgentActionResult, TBrowserCapabilitySource, TBrowserDnsResolver, TBrowserEgressConnector, TBrowserHarnessId, TBrowserRuntimeEvent, } from './interfaces.js';

package/dist_ts/interfaces.d.ts

@@ -101,7 +101,7 @@ export type TBrowserRuntimeOperationIdentity = TReadonlyBrowserCapabilityAuthori
     readonly classification: TBrowserRuntimeOperationClassification;
     readonly startedAt: number;
 };
-export type TBrowserRuntimeOperationClassification = 'raw-input' | 'frame-stream' | 'viewport' | 'navigation' | 'tab' | 'agent-action';
+export type TBrowserRuntimeOperationClassification = 'raw-input' | 'frame-stream' | 'video-peer' | 'viewport' | 'navigation' | 'tab' | 'agent-action';
 /** The viewport accepted by the shared resource, which may be smaller than one viewer's request. */
 export interface IBrowserRuntimeViewportResult {
     viewport: plugins.smartpuppeteer.ILiveBrowserViewport;
@@ -126,6 +126,11 @@ export interface ILiveBrowserSessionLike {
     getState(): plugins.smartpuppeteer.ILiveBrowserState;
     getProcessState(): plugins.smartpuppeteer.ILiveBrowserProcessState;
     onEvent(listener: plugins.smartpuppeteer.TLiveBrowserEventListener): () => void;
+    setFrameCaptureEnabled(enabled: boolean, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+    openVideoPeer(peerId: string, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveVideoOffer>;
+    answerVideoPeer(peerId: string, negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+    closeVideoPeer(peerId: string): Promise<void>;
+    getVideoStatistics(peerId: string): Promise<plugins.smartpuppeteer.ILiveVideoStatistics>;
     refreshScreencast(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserFrameIdentity>;
     acknowledgeFrame(request: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest): Promise<plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgement>;
     createTab(options?: plugins.smartpuppeteer.ILiveBrowserCreateTabOptions, operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserTabState>;
@@ -193,6 +198,8 @@ export interface IBrowserRuntimeOptions {
     maxOutstandingFrames?: number;
     frameAcknowledgementTimeoutMs?: number;
     screencast?: IBrowserRuntimeScreencastOptions;
+    /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
+    video?: plugins.smartpuppeteer.ILiveVideoOptions;
     egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
     artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }
@@ -206,7 +213,13 @@ export interface IBrowserRuntimeTabState {
     appliedViewportRevision: number;
     streaming: boolean;
 }
+export interface IBrowserRuntimeEventSubscriptionOptions {
+    /** Set false for native video viewers. Defaults to true for image-frame consumers. */
+    includeFrames?: boolean;
+}
+export type TBrowserRuntimeVideoOffer = Omit<plugins.smartpuppeteer.ILiveVideoOffer, 'peerId'>;
 export interface IBrowserRuntimeState {
+    videoAcceleration?: plugins.smartpuppeteer.ILiveVideoAcceleration;
     status: 'stopped' | 'starting' | 'running' | 'stopping';
     activeTabId: string | null;
     viewportRevision: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "5.1.0",
+  "version": "5.2.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,13 +30,13 @@
     "@push.rocks/smartagent": "^6.0.0",
     "@push.rocks/smartipc": "^2.6.0",
     "@push.rocks/smartmcp": "^0.3.0",
-    "@push.rocks/smartpuppeteer": "^2.7.1",
+    "@push.rocks/smartpuppeteer": "^2.8.1",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "4.4.2",
+    "@git.zone/tsbuild": "4.4.3",
     "@git.zone/tsrun": "2.0.6",
-    "@git.zone/tstest": "4.0.0",
+    "@git.zone/tstest": "6.0.0",
     "@types/node": "26.4.1"
   },
   "files": [
@@ -44,7 +44,6 @@
     "dist_ts/**/*",
     ".smartconfig.json",
     "readme.md",
-    "readme.hints.md",
     "changelog.md",
     "license.md"
   ],

package/readme.md

@@ -2,6 +2,14 @@
 
 Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.
 
+## Native video viewers
+
+Human leases expose `openVideoPeer(options?)`, `answerVideoPeer(negotiationId, description, options?)`, `closeVideoPeer(options?)`, and `getVideoStatistics(options?)`. Each operation runs through the resource's bounded, authorized and audited operation queue. Peer IDs are private to the lease; offers expose the negotiation ID and exact tab/generation/viewport source identity. Agent leases cannot open media peers. Releasing or revoking a human lease closes only its peer, preserving other viewers and agent work. Failed peer cleanup remains owned for a subsequent release attempt.
+
+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.
+
+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
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
@@ -132,7 +140,7 @@ All participants enter one strict resource FIFO. `maxQueuedOperationsPerLease` d
 
 `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`, `frame-stream`, `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.
+`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`, `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.
 
 `lease.getAuthority()` returns an immutable process-local lease authority containing the runtime authority ID, exported `authorityGeneration`, incarnation generation, and complete capability binding. Every snapshot also binds the exact `capabilityId` and `leaseId`. `lease.isAuthorityCurrent(authority)` performs an exact synchronous revalidation suitable for a host-owned virtual stream. These values are not durable Controller state and do not replace attachment checks against the Controller database.
 
@@ -142,7 +150,7 @@ Each human participant may have one independent frame subscription with a bounde
 
 An oversized frame is dropped, not fatal. `maxFrameBytes` defaults to 4 MiB and accepts values from 64 KiB through 16 MiB. A frame above the bound is acknowledged toward SmartPuppeteer in the background, never enters the application window, and is reported once on the subscription as `{ type: 'error', error: { code: 'FRAME_TOO_LARGE', fatal: false, tabId } }`. The sequence watermark advances past the dropped frame so later frames remain valid and continue to be delivered.
 
-`screencast` tunes the Chromium screencast that SmartPuppeteer starts for every incarnation. `quality` is the JPEG quality from 0 through 100 and defaults to 70. `maxWidth` and `maxHeight` accept values from 1 through 4,096 each, their product must not exceed 8,294,400 pixels (SmartPuppeteer's ceiling, so 3,840×2,160 is accepted and 4,096×4,096 is rejected with `INVALID_INPUT`), they default to 2,560 and 1,600, and they make Chromium scale captured frames to fit. `everyNthFrame` accepts values from 1 through 60 and defaults to 1. `firstFrameTimeoutMs` accepts values from 1,000 through 60,000 and is left to SmartPuppeteer's default when omitted. Runtime forwards these values together with `maxOutstandingFrames`; the defaults keep frames from device-pixel-ratio 2 viewers well below `maxFrameBytes`.
+`screencast` tunes the Chromium image capture that starts when an image-frame subscriber joins. `quality` is the JPEG quality from 0 through 100 and defaults to 70. `maxWidth` and `maxHeight` accept values from 1 through 4,096 each, their product must not exceed 8,294,400 pixels (SmartPuppeteer's ceiling, so 3,840×2,160 is accepted and 4,096×4,096 is rejected with `INVALID_INPUT`), they default to 2,560 and 1,600, and they make Chromium scale captured frames to fit. `everyNthFrame` accepts values from 1 through 60 and defaults to 1. `firstFrameTimeoutMs` accepts values from 1,000 through 60,000 and is left to SmartPuppeteer's default when omitted. Runtime forwards these values together with `maxOutstandingFrames`; the defaults keep frames from device-pixel-ratio 2 viewers well below `maxFrameBytes`.
 
 Human state and error events retain an optional diagnostic `message` bounded to 2,048 characters. A fatal producer error synchronously invalidates all current participants before their captured subscribers receive the error. Cleanup is coalesced for that exact incarnation and completes before affected operations settle.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '5.1.0',
+  version: '5.2.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

@@ -29,6 +29,8 @@ import type {
   IBrowserResourceRegistration,
   IBrowserRuntimeState,
   IBrowserRuntimeViewportResult,
+  IBrowserRuntimeEventSubscriptionOptions,
+  TBrowserRuntimeVideoOffer,
   IBrowserScreenshotResult,
   ICreateBrowserResourceRequest,
   TQualifiedBrowserSessionId,
@@ -102,6 +104,7 @@ interface INormalizedRuntimeOptions {
   maxOutstandingFrames: number;
   frameAcknowledgementTimeoutMs: number;
   screencast: INormalizedScreencastOptions;
+  video: Required<plugins.smartpuppeteer.ILiveVideoOptions>;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
   ownership?: IBrowserRuntimeTestingOptions['ownership'];
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
@@ -138,6 +141,9 @@ interface ILeaseRecord {
   released: boolean;
   releasePromise?: Promise<void>;
   preferredViewport?: plugins.smartpuppeteer.ILiveBrowserViewport;
+  videoPeerId: string;
+  videoPeerMayExist: boolean;
+  frameCaptureUsed: boolean;
   heldKeys: Map<string, plugins.smartpuppeteer.ILiveBrowserKeyInput>;
   heldButtons: Map<string, plugins.smartpuppeteer.ILiveBrowserMouseInput>;
 }
@@ -175,7 +181,7 @@ interface IQueuedOperationRecord {
   state: 'queued' | 'starting' | 'active' | 'settled';
   onQueuedAbort?: () => void;
   /** Resource-owned cleanup, admitted only for this exact released participant. */
-  participantCleanup?: boolean;
+  participantCleanup?: 'participant' | 'subscription' | false;
 }
 
 interface IOutstandingFrameRecord {
@@ -194,6 +200,10 @@ type TFrameAcknowledgementOutcome =
 interface IFrameSubscriptionRecord {
   lease: ILeaseRecord;
   listener: (event: TBrowserRuntimeEvent) => void;
+  includeFrames: boolean;
+  session: ILiveBrowserSessionLike;
+  closePromise?: Promise<void>;
+  closeComplete?: boolean;
   outstanding: Map<string, IOutstandingFrameRecord>;
   highestSequence: number;
   closed: boolean;
@@ -240,6 +250,7 @@ interface IResourceSlot {
   operationQueue: IQueuedOperationRecord[];
   operationSchedulerRunning: boolean;
   frameSubscriptions: Map<string, IFrameSubscriptionRecord>;
+  frameCaptureEnabled?: boolean;
   highestFrameSequence: number;
   producerAcknowledgements: Set<Promise<TFrameAcknowledgementOutcome>>;
   frameRefresh?: IFrameRefreshRecord;
@@ -558,6 +569,7 @@ export class BrowserRuntime {
         10_000,
       ),
       screencast,
+      video: plugins.smartpuppeteer.normalizeLiveVideoOptions(options.video ?? {}),
       egress: options.egress ?? {},
       ownership: testingOptions?.ownership,
       beforeLeasePublication: testingOptions?.beforeLeasePublication,
@@ -1352,6 +1364,46 @@ export class BrowserRuntime {
       });
   }
 
+  /** @internal */
+  public async leaseOpenVideoPeer(lease: ILeaseRecord, options: IBrowserRuntimeOperationOptions = {}): Promise<TBrowserRuntimeVideoOffer> {
+    this.requireHuman(lease);
+    return this.runOperation(lease, 'openVideoPeer', 'video-peer', options, async (signal, session) => {
+      lease.videoPeerMayExist = true;
+      const { peerId: _peerId, ...offer } = await session.openVideoPeer(lease.videoPeerId, { signal });
+      return offer;
+    });
+  }
+
+  /** @internal */
+  public async leaseAnswerVideoPeer(lease: ILeaseRecord, negotiationId: string,
+    description: plugins.smartpuppeteer.ILiveVideoDescription, options: IBrowserRuntimeOperationOptions = {}): Promise<void> {
+    this.requireHuman(lease);
+    const id = validateBoundedString(negotiationId, 'negotiationId', 1, 128);
+    if (id !== negotiationId) throw new BrowserRuntimeError('INVALID_INPUT');
+    const record = validateExactKeys(description, ['type', 'sdp'], 'video answer');
+    const answer = { type: record.type, sdp: record.sdp } as plugins.smartpuppeteer.ILiveVideoDescription;
+    try { plugins.smartpuppeteer.validateLiveVideoDescription(answer, 'answer'); }
+    catch { throw new BrowserRuntimeError('INVALID_INPUT'); }
+    return this.runOperation(lease, 'answerVideoPeer', 'video-peer', options,
+      async (signal, session) => session.answerVideoPeer(lease.videoPeerId, id, answer, { signal }));
+  }
+
+  /** @internal */
+  public async leaseCloseVideoPeer(lease: ILeaseRecord, options: IBrowserRuntimeOperationOptions = {}): Promise<void> {
+    this.requireHuman(lease);
+    return this.runOperation(lease, 'closeVideoPeer', 'video-peer', options, async (_signal, session) => {
+      await session.closeVideoPeer(lease.videoPeerId);
+      lease.videoPeerMayExist = false;
+    });
+  }
+
+  /** @internal */
+  public async leaseGetVideoStatistics(lease: ILeaseRecord, options: IBrowserRuntimeOperationOptions = {}): Promise<plugins.smartpuppeteer.ILiveVideoStatistics> {
+    this.requireHuman(lease);
+    return this.runOperation(lease, 'getVideoStatistics', 'video-peer', options,
+      async (_signal, session) => session.getVideoStatistics(lease.videoPeerId));
+  }
+
   private validatePreferredViewport(
     value: plugins.smartpuppeteer.ILiveBrowserViewport,
   ): plugins.smartpuppeteer.ILiveBrowserViewport {
@@ -1402,7 +1454,7 @@ export class BrowserRuntime {
     this.requireValidLease(lease);
     const slot = lease.slot;
     const subscription = slot.frameSubscriptions.get(lease.leaseId);
-    if (!subscription || subscription.closed || subscription.lease !== lease) {
+    if (!subscription || subscription.closed || !subscription.includeFrames || subscription.lease !== lease) {
       throw new BrowserRuntimeError('BUSY');
     }
     let refresh: IFrameRefreshRecord | undefined;
@@ -1599,34 +1651,65 @@ export class BrowserRuntime {
   public async subscribeLeaseEvents(
     lease: ILeaseRecord,
     listener: (event: TBrowserRuntimeEvent) => void,
+    options: IBrowserRuntimeEventSubscriptionOptions = {},
   ): Promise<IBrowserRuntimeFrameSubscription> {
     this.requireHuman(lease);
     if (typeof listener !== 'function') throw new BrowserRuntimeError('INVALID_INPUT');
+    const values = validateExactKeys(options, ['includeFrames'], 'event subscription');
+    if (values.includeFrames !== undefined && typeof values.includeFrames !== 'boolean') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
     const slot = lease.slot;
     const release = slot.mutex.tryAcquire();
     if (!release) throw new BrowserRuntimeError('BUSY');
-    let subscription: IFrameSubscriptionRecord;
     try {
       this.requireValidLease(lease);
-      if (slot.frameSubscriptions.has(lease.leaseId)) throw new BrowserRuntimeError('BUSY');
-      subscription = {
-        lease,
-        listener,
-        outstanding: new Map(),
-        highestSequence: 0,
-        closed: false,
-      };
-      slot.frameSubscriptions.set(lease.leaseId, subscription);
-      this.pushToSubscription(subscription, {
-        type: 'state',
-        state: this.resourceState(slot.session!.getState()),
+      if (values.includeFrames === false) {
+        if (slot.frameSubscriptions.has(lease.leaseId)) throw new BrowserRuntimeError('BUSY');
+        const subscription: IFrameSubscriptionRecord = {
+          lease, listener, includeFrames: false, session: slot.session!,
+          outstanding: new Map(), highestSequence: 0, closed: false,
+        };
+        slot.frameSubscriptions.set(lease.leaseId, subscription);
+        this.pushToSubscription(subscription, { type: 'state', state: this.resourceState(slot.session!.getState()) });
+        return { close: () => this.closeFrameSubscription(subscription) };
+      }
+    } finally { release(); }
+    let subscription: IFrameSubscriptionRecord | undefined;
+    try {
+      return await this.runOperation(lease, 'subscribeEvents', 'frame-stream', {}, async (signal, session) => {
+        if (slot.frameSubscriptions.has(lease.leaseId)) throw new BrowserRuntimeError('BUSY');
+        subscription = {
+          lease, listener, includeFrames: values.includeFrames !== false, session,
+          outstanding: new Map(), highestSequence: 0, closed: false,
+        };
+        slot.frameSubscriptions.set(lease.leaseId, subscription);
+        if (subscription.includeFrames) {
+          lease.frameCaptureUsed = true;
+          await this.reconcileFrameCapture(slot, session, signal);
+        }
+        this.pushToSubscription(subscription, { type: 'state', state: this.resourceState(session.getState()) });
+        const ownedSubscription = subscription;
+        return { close: () => this.closeFrameSubscription(ownedSubscription) };
       });
-    } finally {
-      release();
+    } catch (error) {
+      if (subscription) {
+        this.detachFrameSubscription(subscription);
+        await this.revokeCapabilityRecord(lease.capability);
+      }
+      throw error;
     }
-    return {
-      close: async () => this.closeFrameSubscription(subscription),
-    };
+  }
+
+  private async reconcileFrameCapture(slot: IResourceSlot, session: ILiveBrowserSessionLike, signal: AbortSignal): Promise<void> {
+    const enabled = [...slot.frameSubscriptions.values()].some((subscription) => (
+      !subscription.closed && !subscription.lease.released && subscription.includeFrames
+    ));
+    if (slot.frameCaptureEnabled === enabled) return;
+    // A failed/aborted CDP transition may have reached the browser; cleanup must reconcile it.
+    slot.frameCaptureEnabled = undefined;
+    await session.setFrameCaptureEnabled(enabled, { signal });
+    slot.frameCaptureEnabled = enabled;
   }
 
   /** @internal */
@@ -1891,6 +1974,9 @@ export class BrowserRuntime {
       controller: new AbortController(),
       authorityGeneration: slot.authorityGeneration,
       released: false,
+      videoPeerId: randomId(24),
+      videoPeerMayExist: false,
+      frameCaptureUsed: false,
       heldKeys: new Map(),
       heldButtons: new Map(),
     };
@@ -1926,8 +2012,9 @@ export class BrowserRuntime {
         forceNoSandbox: false,
         usePipe: true,
         allowEvaluation: true,
+        video: this.options.video,
         screencast: {
-          maxOutstandingFrames: this.options.maxOutstandingFrames,
+          enabled: false,          maxOutstandingFrames: this.options.maxOutstandingFrames,
           quality: this.options.screencast.quality,
           maxWidth: this.options.screencast.maxWidth,
           maxHeight: this.options.screencast.maxHeight,
@@ -1945,7 +2032,6 @@ export class BrowserRuntime {
             '--disable-quic',
             '--disable-dns-prefetch',
             '--disable-background-networking',
-            '--disable-extensions',
             '--webrtc-ip-handling-policy=disable_non_proxied_udp',
             '--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1',
           ],
@@ -1998,6 +2084,7 @@ export class BrowserRuntime {
       }
       if (probeSignal.aborted) throw probeSignal.reason;
       slot.session = session;
+      slot.frameCaptureEnabled = false;
       slot.proxy = proxy;
       slot.profileDirectory = profileDirectory;
       slot.unsubscribeSession = unsubscribe;
@@ -2059,7 +2146,7 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions,
     execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<T>,
     finalize?: () => Promise<void>,
-    participantCleanup = false,
+    participantCleanup: 'participant' | 'subscription' | false = false,
   ): Promise<T> {
     if (!operationOptions || typeof operationOptions !== 'object') {
       throw new BrowserRuntimeError('INVALID_INPUT');
@@ -2622,6 +2709,7 @@ export class BrowserRuntime {
 
   private resourceState(state: plugins.smartpuppeteer.ILiveBrowserState): IBrowserRuntimeState {
     return {
+      ...(state.videoAcceleration ? { videoAcceleration: { ...state.videoAcceleration } } : {}),
       status: state.status,
       activeTabId: state.activeTabId ? truncateString(state.activeTabId, 128) : null,
       viewportRevision: state.viewportRevision,
@@ -2665,6 +2753,7 @@ export class BrowserRuntime {
       slot.frameRefresh
       || slot.frameSubscriptions.get(lease.leaseId) !== subscription
       || subscription.closed
+      || !subscription.includeFrames
       || subscription.lease !== lease
       || slot.leases.get(lease.leaseId) !== lease
       || slot.session !== session
@@ -2946,6 +3035,7 @@ export class BrowserRuntime {
       if (event.frame.data.byteLength > this.options.maxFrameBytes) {
         if (refresh) this.failFrameRefresh(refresh, 'FRAME_TOO_LARGE');
         for (const subscription of slot.frameSubscriptions.values()) {
+          if (!subscription.includeFrames) continue;
           this.pushToSubscription(subscription, {
             type: 'error',
             error: { code: 'FRAME_TOO_LARGE', fatal: false, tabId: acknowledgement.tabId },
@@ -2964,7 +3054,7 @@ export class BrowserRuntime {
       }
       const key = this.frameAcknowledgementKey(acknowledgement);
       for (const subscription of [...slot.frameSubscriptions.values()]) {
-        if (subscription.closed) continue;
+        if (subscription.closed || !subscription.includeFrames) continue;
         while (subscription.outstanding.size >= this.options.maxOutstandingFrames) {
           const oldestKey = subscription.outstanding.keys().next().value!;
           this.trackCleanup(this.retireOutstandingFrame(subscription, oldestKey).then(() => undefined));
@@ -3027,20 +3117,53 @@ export class BrowserRuntime {
       return true;
     } catch {
       // A failed participant transport cannot revoke another participant or kill the producer.
-      this.trackCleanup(this.closeFrameSubscription(subscription));
+      this.detachFrameSubscription(subscription);
       this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
       return false;
     }
   }
 
   private async closeFrameSubscription(subscription: IFrameSubscriptionRecord): Promise<void> {
-    if (subscription.closed) return;
+    if (subscription.closeComplete) return;
+    if (subscription.closePromise) return subscription.closePromise;
+    this.detachFrameSubscription(subscription, false);
+    const lease = subscription.lease;
+    const slot = lease.slot;
+    const operation = (async () => {
+      if (subscription.includeFrames && slot.session === subscription.session) {
+        if (lease.released) await this.releaseLeaseRecord(lease);
+        else if (this.lifecycleState === 'running' && !slot.permanentlyFenced && !slot.retirementPending
+          && slot.fencingGeneration === undefined && slot.terminationFenceGeneration === undefined) {
+          await this.runOperation(lease, 'unsubscribeFrames', 'frame-stream', {}, async (signal, session) => {
+            await this.reconcileFrameCapture(slot, session, signal);
+            this.detachFrameSubscription(subscription);
+            subscription.closeComplete = true;
+          }, undefined, 'subscription');
+        }
+      }
+      this.detachFrameSubscription(subscription);
+      subscription.closeComplete = true;
+    })();
+    subscription.closePromise = operation;
+    try { await operation; }
+    catch (error) {
+      // Producer failure may supersede a queued unsubscribe. Its exact incarnation's
+      // confirmed termination completes capture cleanup without issuing another toggle.
+      const failure = slot.frameFailure;
+      if (failure?.session === subscription.session) await failure.promise;
+      if (slot.session === subscription.session || !lease.released) throw error;
+      this.detachFrameSubscription(subscription);
+      subscription.closeComplete = true;
+    } finally { subscription.closePromise = undefined; }
+  }
+
+  private detachFrameSubscription(subscription: IFrameSubscriptionRecord, remove = true): void {
     subscription.closed = true;
     const slot = subscription.lease.slot;
     if (slot.frameRefresh?.subscription === subscription) {
       this.abandonFrameRefresh(slot, slot.frameRefresh);
     }
-    if (slot.frameSubscriptions.get(subscription.lease.leaseId) === subscription) {
+    if (remove && slot.frameSubscriptions.get(subscription.lease.leaseId) === subscription) {
       slot.frameSubscriptions.delete(subscription.lease.leaseId);
     }
     for (const frame of subscription.outstanding.values()) {
@@ -3199,10 +3322,10 @@ export class BrowserRuntime {
     this.trackCleanup(operation);
   }
 
-  private requireQueuedLease(lease: ILeaseRecord, participantCleanup = false): void {
+  private requireQueuedLease(lease: ILeaseRecord, participantCleanup: 'participant' | 'subscription' | false = false): void {
     if (!participantCleanup) return this.requireValidLease(lease);
     if (
-      !lease.released || lease.slot.leases.get(lease.leaseId) !== lease
+      (participantCleanup === 'participant' && !lease.released) || lease.slot.leases.get(lease.leaseId) !== lease
       || lease.capability.lease !== lease || !lease.slot.session
     ) throw new BrowserRuntimeError('CAPABILITY_REVOKED');
   }
@@ -3367,14 +3490,20 @@ export class BrowserRuntime {
     if (
       this.lifecycleState === 'running' && slot.session && !slot.permanentlyFenced && !slot.retirementPending
       && slot.fencingGeneration === undefined && slot.terminationFenceGeneration === undefined
-      && (lease.preferredViewport || lease.heldKeys.size || lease.heldButtons.size)
+      && (lease.preferredViewport || lease.heldKeys.size || lease.heldButtons.size
+        || lease.videoPeerMayExist || lease.frameCaptureUsed)
     ) {
       await this.runOperation(lease, 'releaseParticipant', 'viewport', {},
         async (signal, session) => {
+          if (lease.videoPeerMayExist) {
+            await session.closeVideoPeer(lease.videoPeerId);
+            lease.videoPeerMayExist = false;
+          }
+          if (lease.frameCaptureUsed) await this.reconcileFrameCapture(slot, session, signal);
           await this.releaseParticipantInput(lease, session);
           await this.applySharedViewport(slot, session, signal);
           lease.preferredViewport = undefined;
-        }, undefined, true);
+        }, undefined, 'participant');
     }
     if (slot.permanentlyFenced && (slot.session || slot.proxy || slot.profileDirectory)) {
       await this.terminateSlotSession(slot);
@@ -3392,7 +3521,7 @@ export class BrowserRuntime {
 
   private async closeFrameSubscriptionIfLease(lease: ILeaseRecord): Promise<void> {
     const subscription = lease.slot.frameSubscriptions.get(lease.leaseId);
-    if (subscription) await this.closeFrameSubscription(subscription);
+    if (subscription) this.detachFrameSubscription(subscription);
   }
 
   private async quiesceSlot(slot: IResourceSlot): Promise<void> {
@@ -4243,8 +4372,26 @@ export class BrowserRuntimeLease {
 
   public subscribeEvents(
     listener: (event: TBrowserRuntimeEvent) => void,
+    options?: IBrowserRuntimeEventSubscriptionOptions,
   ): Promise<IBrowserRuntimeFrameSubscription> {
-    return this.runtime.subscribeLeaseEvents(this.record, listener);
+    return this.runtime.subscribeLeaseEvents(this.record, listener, options);
+  }
+
+  public openVideoPeer(options?: IBrowserRuntimeOperationOptions): Promise<TBrowserRuntimeVideoOffer> {
+    return this.runtime.leaseOpenVideoPeer(this.record, options);
+  }
+
+  public answerVideoPeer(negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription,
+    options?: IBrowserRuntimeOperationOptions): Promise<void> {
+    return this.runtime.leaseAnswerVideoPeer(this.record, negotiationId, description, options);
+  }
+
+  public closeVideoPeer(options?: IBrowserRuntimeOperationOptions): Promise<void> {
+    return this.runtime.leaseCloseVideoPeer(this.record, options);
+  }
+
+  public getVideoStatistics(options?: IBrowserRuntimeOperationOptions): Promise<plugins.smartpuppeteer.ILiveVideoStatistics> {
+    return this.runtime.leaseGetVideoStatistics(this.record, options);
   }
 
   public acknowledgeFrame(

package/ts/index.ts

@@ -48,6 +48,8 @@ export type {
   IBrowserRuntimeOperationOptions,
   IBrowserRuntimeOptions,
   IBrowserRuntimeScreencastOptions,
+  IBrowserRuntimeEventSubscriptionOptions,
+  TBrowserRuntimeVideoOffer,
   IBrowserResourceKey,
   IBrowserResourceRegistration,
   IBrowserRuntimeState,

package/ts/interfaces.ts

@@ -133,6 +133,7 @@ export type TBrowserRuntimeOperationIdentity = TReadonlyBrowserCapabilityAuthori
 export type TBrowserRuntimeOperationClassification =
   | 'raw-input'
   | 'frame-stream'
+  | 'video-peer'
   | 'viewport'
   | 'navigation'
   | 'tab'
@@ -167,6 +168,12 @@ export interface ILiveBrowserSessionLike {
   getState(): plugins.smartpuppeteer.ILiveBrowserState;
   getProcessState(): plugins.smartpuppeteer.ILiveBrowserProcessState;
   onEvent(listener: plugins.smartpuppeteer.TLiveBrowserEventListener): () => void;
+  setFrameCaptureEnabled(enabled: boolean, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+  openVideoPeer(peerId: string, options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveVideoOffer>;
+  answerVideoPeer(peerId: string, negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription,
+    options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
+  closeVideoPeer(peerId: string): Promise<void>;
+  getVideoStatistics(peerId: string): Promise<plugins.smartpuppeteer.ILiveVideoStatistics>;
   refreshScreencast(
     options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions,
   ): Promise<plugins.smartpuppeteer.ILiveBrowserFrameIdentity>;
@@ -291,6 +298,8 @@ export interface IBrowserRuntimeOptions {
   maxOutstandingFrames?: number;
   frameAcknowledgementTimeoutMs?: number;
   screencast?: IBrowserRuntimeScreencastOptions;
+  /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
+  video?: plugins.smartpuppeteer.ILiveVideoOptions;
   egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
   artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }
@@ -306,7 +315,15 @@ export interface IBrowserRuntimeTabState {
   streaming: boolean;
 }
 
+export interface IBrowserRuntimeEventSubscriptionOptions {
+  /** Set false for native video viewers. Defaults to true for image-frame consumers. */
+  includeFrames?: boolean;
+}
+
+export type TBrowserRuntimeVideoOffer = Omit<plugins.smartpuppeteer.ILiveVideoOffer, 'peerId'>;
+
 export interface IBrowserRuntimeState {
+  videoAcceleration?: plugins.smartpuppeteer.ILiveVideoAcceleration;
   status: 'stopped' | 'starting' | 'running' | 'stopping';
   activeTabId: string | null;
   viewportRevision: number;