@modelprofile.com/browser-runtime 3.0.0 → 3.1.0

package/ts/classes.runtime.ts

@@ -146,6 +146,7 @@ interface IQueuedOperationRecord {
   onOperationStarted?: (operationId: string) => void;
   signal: AbortSignal;
   execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<unknown>;
+  finalize?: () => Promise<void>;
   resolve(value: unknown): void;
   reject(error: unknown): void;
   state: 'queued' | 'starting' | 'active' | 'settled';
@@ -154,7 +155,7 @@ interface IQueuedOperationRecord {
 
 interface IOutstandingFrameRecord {
   acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
-  timer: ReturnType<typeof setTimeout>;
+  timer?: ReturnType<typeof setTimeout>;
   session: ILiveBrowserSessionLike;
   incarnationGeneration: number;
 }
@@ -172,6 +173,23 @@ interface IFrameSubscriptionRecord {
   closed: boolean;
 }
 
+interface IFrameRefreshRecord {
+  lease: ILeaseRecord;
+  subscription: IFrameSubscriptionRecord;
+  session: ILiveBrowserSessionLike;
+  incarnationGeneration: number;
+  initialTabId: string;
+  initialGeneration: number;
+  initialViewportRevision: number;
+  startingHighestSequence: number;
+  pendingAcknowledgements: Set<Promise<TFrameAcknowledgementOutcome>>;
+  refreshStarted: boolean;
+  admissionClosed: boolean;
+  abandoned: boolean;
+  boundaryCandidate?: plugins.smartpuppeteer.ILiveBrowserFrameIdentity;
+  failure?: BrowserRuntimeError;
+}
+
 interface IResourceSlot {
   projectId: string;
   browserResourceId: string;
@@ -195,6 +213,7 @@ interface IResourceSlot {
   operationQueue: IQueuedOperationRecord[];
   operationSchedulerRunning: boolean;
   frameSubscription?: IFrameSubscriptionRecord;
+  frameRefresh?: IFrameRefreshRecord;
   idleTimer?: ReturnType<typeof setTimeout>;
   lifecycleTail: Promise<void>;
   lifecycleOperationCount: number;
@@ -1153,6 +1172,39 @@ export class BrowserRuntime {
     );
   }
 
+  /** @internal */
+  public async leaseRefreshFrameStream(
+    lease: ILeaseRecord,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<void> {
+    this.requireHuman(lease);
+    this.requireValidLease(lease);
+    const slot = lease.slot;
+    const subscription = slot.frameSubscription;
+    if (!subscription || subscription.closed || subscription.lease !== lease) {
+      throw new BrowserRuntimeError('BUSY');
+    }
+    let refresh: IFrameRefreshRecord | undefined;
+    return this.runOperation(
+      lease,
+      'refreshFrameStream',
+      'frame-stream',
+      operationOptions,
+      async (signal, session) => {
+        refresh = this.beginFrameRefresh(
+          slot,
+          lease,
+          subscription,
+          session,
+        );
+        await this.executeFrameRefresh(refresh, signal);
+      },
+      async () => {
+        if (refresh) await this.finalizeFrameRefresh(slot, refresh);
+      },
+    );
+  }
+
   /** @internal */
   public async leaseDispatchRawInput(
     lease: ILeaseRecord,
@@ -1186,11 +1238,12 @@ export class BrowserRuntime {
     this.requireHuman(lease);
     if (typeof listener !== 'function') throw new BrowserRuntimeError('INVALID_INPUT');
     const slot = lease.slot;
-    const release = await slot.mutex.acquire();
+    const release = slot.mutex.tryAcquire();
+    if (!release) throw new BrowserRuntimeError('BUSY');
     let subscription: IFrameSubscriptionRecord;
     try {
       this.requireValidLease(lease);
-      if (slot.frameSubscription) throw new BrowserRuntimeError('BUSY');
+      if (slot.frameSubscription || slot.frameRefresh) throw new BrowserRuntimeError('BUSY');
       subscription = {
         lease,
         listener,
@@ -1225,14 +1278,34 @@ export class BrowserRuntime {
     if (!subscription || subscription.lease !== lease) return false;
     const outstanding = subscription.outstanding.get(key);
     if (!outstanding) return false;
-    subscription.outstanding.delete(key);
-    clearTimeout(outstanding.timer);
     const { session, incarnationGeneration } = outstanding;
-    const outcome = await this.waitForFrameAcknowledgement(
+    const refresh = this.matchingFrameRefresh(
+      slot,
+      subscription,
+      session,
+      incarnationGeneration,
+    );
+    if (refresh?.admissionClosed) {
+      subscription.outstanding.delete(key);
+      if (outstanding.timer) clearTimeout(outstanding.timer);
+      outstanding.timer = undefined;
+      return false;
+    }
+    subscription.outstanding.delete(key);
+    if (outstanding.timer) clearTimeout(outstanding.timer);
+    outstanding.timer = undefined;
+    const refreshOwned = Boolean(refresh && !refresh.abandoned);
+    const outcome = await this.beginFrameAcknowledgement(
       session,
       outstanding.acknowledgement,
+      refreshOwned ? refresh : undefined,
     );
     if (outcome.status === 'fulfilled') return outcome.accepted;
+    if (refreshOwned) return false;
+    if (refresh && slot.frameRefresh === refresh) {
+      this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      return false;
+    }
     await this.options.beforeFrameFailureTermination?.();
     await this.handleFrameFailure(slot, session, incarnationGeneration, subscription.lease);
     return false;
@@ -1640,6 +1713,7 @@ export class BrowserRuntime {
     classification: TBrowserRuntimeOperationClassification,
     operationOptions: IBrowserRuntimeOperationOptions,
     execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<T>,
+    finalize?: () => Promise<void>,
   ): Promise<T> {
     if (!operationOptions || typeof operationOptions !== 'object') {
       throw new BrowserRuntimeError('INVALID_INPUT');
@@ -1678,6 +1752,7 @@ export class BrowserRuntime {
         onOperationStarted: operationOptions.onOperationStarted,
         signal,
         execute: execute as IQueuedOperationRecord['execute'],
+        finalize,
         resolve: (value) => resolve(value as T),
         reject,
         state: 'queued',
@@ -1813,6 +1888,7 @@ export class BrowserRuntime {
     let failed = false;
     let failure: unknown;
     let executionStarted = false;
+    let executionSettled = false;
     try {
       await this.runBeforeOperation(operationIdentity, combinedSignal);
       const executionRelease = await slot.mutex.acquire();
@@ -1829,7 +1905,9 @@ export class BrowserRuntime {
         ) throw new BrowserRuntimeError('ABORTED');
         executionStarted = true;
         executionPromise = queued.execute(combinedSignal, session);
-        operation.promise = executionPromise.then(() => undefined, () => undefined);
+        operation.promise = executionPromise.then(() => undefined, () => undefined).finally(() => {
+          executionSettled = true;
+        });
       } finally {
         executionRelease();
       }
@@ -1875,6 +1953,18 @@ export class BrowserRuntime {
       } else {
         await cleanupSlot();
       }
+      if (
+        queued.finalize
+        && (!executionStarted || executionSettled)
+        && slot.operation !== operation
+      ) {
+        try {
+          await queued.finalize();
+        } catch (error) {
+          failed = true;
+          failure = error;
+        }
+      }
       const errorCode = failed ? this.operationErrorCode(failure) : undefined;
       await this.emitAudit(Object.freeze({
         ...operationIdentity,
@@ -2193,6 +2283,271 @@ export class BrowserRuntime {
     };
   }
 
+  private beginFrameRefresh(
+    slot: IResourceSlot,
+    lease: ILeaseRecord,
+    subscription: IFrameSubscriptionRecord,
+    session: ILiveBrowserSessionLike,
+  ): IFrameRefreshRecord {
+    if (
+      slot.frameRefresh
+      || slot.frameSubscription !== subscription
+      || subscription.closed
+      || subscription.lease !== lease
+      || slot.lease !== lease
+      || slot.session !== session
+    ) throw new BrowserRuntimeError('BUSY');
+    const state = session.getState();
+    const activeTab = state.tabs.find((tab) => tab.id === state.activeTabId);
+    if (
+      !activeTab
+      || !activeTab.active
+      || activeTab.status !== 'open'
+      || !activeTab.streaming
+    ) throw new BrowserRuntimeError('BUSY');
+    const refresh: IFrameRefreshRecord = {
+      lease,
+      subscription,
+      session,
+      incarnationGeneration: slot.incarnationGeneration,
+      initialTabId: activeTab.id,
+      initialGeneration: activeTab.generation,
+      initialViewportRevision: state.viewportRevision,
+      startingHighestSequence: subscription.highestSequence,
+      pendingAcknowledgements: new Set(),
+      refreshStarted: false,
+      admissionClosed: false,
+      abandoned: false,
+    };
+    slot.frameRefresh = refresh;
+    return refresh;
+  }
+
+  private async executeFrameRefresh(
+    refresh: IFrameRefreshRecord,
+    signal: AbortSignal,
+  ): Promise<void> {
+    let operationError: unknown;
+    try {
+      await this.drainFrameRefreshOutstanding(refresh);
+      if (refresh.failure) throw refresh.failure;
+      signal.throwIfAborted();
+      refresh.refreshStarted = true;
+      const identity = this.validateFrameAcknowledgement(
+        await refresh.session.refreshScreencast({ signal }),
+        true,
+      );
+      this.validateFrameRefreshBoundary(refresh, identity);
+      await this.reconcileFrameRefreshOutstanding(refresh, identity);
+      if (refresh.failure) throw refresh.failure;
+    } catch (error) {
+      operationError = error;
+      if (signal.aborted && refresh.refreshStarted) {
+        try {
+          const candidate = refresh.boundaryCandidate;
+          if (!candidate) throw new BrowserRuntimeError('FRAME_STREAM_FAILED');
+          this.validateFrameRefreshBoundary(refresh, candidate);
+          await this.reconcileFrameRefreshOutstanding(refresh, candidate);
+        } catch {
+          this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+        }
+      } else if (!signal.aborted && !refresh.failure) {
+        this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      }
+    } finally {
+      refresh.admissionClosed = true;
+      await Promise.allSettled([...refresh.pendingAcknowledgements]);
+    }
+    if (refresh.failure) throw refresh.failure;
+    if (operationError !== undefined) throw operationError;
+  }
+
+  private async drainFrameRefreshOutstanding(refresh: IFrameRefreshRecord): Promise<void> {
+    const outstanding = [...refresh.subscription.outstanding.values()];
+    refresh.subscription.outstanding.clear();
+    for (const frame of outstanding) {
+      if (frame.timer) clearTimeout(frame.timer);
+      frame.timer = undefined;
+    }
+    await Promise.all(outstanding.map((frame) => this.beginFrameAcknowledgement(
+      frame.session,
+      frame.acknowledgement,
+      refresh,
+    )));
+  }
+
+  private validateFrameRefreshBoundary(
+    refresh: IFrameRefreshRecord,
+    identity: plugins.smartpuppeteer.ILiveBrowserFrameIdentity,
+  ): void {
+    const candidate = refresh.boundaryCandidate;
+    const state = refresh.session.getState();
+    const activeTab = state.tabs.find((tab) => tab.id === state.activeTabId);
+    if (
+      !candidate
+      || this.frameAcknowledgementKey(candidate) !== this.frameAcknowledgementKey(identity)
+      || identity.tabId !== refresh.initialTabId
+      || identity.sequence <= refresh.startingHighestSequence
+      || identity.generation <= refresh.initialGeneration
+      || identity.viewportRevision !== refresh.initialViewportRevision
+      || state.activeTabId !== refresh.initialTabId
+      || state.viewportRevision !== refresh.initialViewportRevision
+      || !activeTab
+      || !activeTab.active
+      || activeTab.status !== 'open'
+      || !activeTab.streaming
+      || activeTab.generation !== identity.generation
+      || activeTab.appliedViewportRevision !== identity.viewportRevision
+    ) throw new BrowserRuntimeError('FRAME_STREAM_FAILED');
+  }
+
+  private async reconcileFrameRefreshOutstanding(
+    refresh: IFrameRefreshRecord,
+    identity: plugins.smartpuppeteer.ILiveBrowserFrameIdentity,
+  ): Promise<void> {
+    const retirements: Array<Promise<TFrameAcknowledgementOutcome>> = [];
+    for (const [key, frame] of refresh.subscription.outstanding) {
+      const acknowledgement = frame.acknowledgement;
+      if (
+        acknowledgement.tabId === identity.tabId
+        && acknowledgement.generation === identity.generation
+        && acknowledgement.viewportRevision === identity.viewportRevision
+        && acknowledgement.sequence >= identity.sequence
+      ) continue;
+      refresh.subscription.outstanding.delete(key);
+      if (frame.timer) clearTimeout(frame.timer);
+      frame.timer = undefined;
+      retirements.push(this.beginFrameAcknowledgement(
+        frame.session,
+        acknowledgement,
+        refresh,
+      ));
+    }
+    await Promise.all(retirements);
+  }
+
+  private beginFrameAcknowledgement(
+    session: ILiveBrowserSessionLike,
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+    refresh?: IFrameRefreshRecord,
+  ): Promise<TFrameAcknowledgementOutcome> {
+    const operation = this.waitForFrameAcknowledgement(session, acknowledgement);
+    if (!refresh || refresh.admissionClosed || refresh.abandoned) return operation;
+    const tracked = operation.then((outcome) => {
+      if (outcome.status !== 'fulfilled') this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      return outcome;
+    });
+    refresh.pendingAcknowledgements.add(tracked);
+    void tracked.then(
+      () => refresh.pendingAcknowledgements.delete(tracked),
+      () => refresh.pendingAcknowledgements.delete(tracked),
+    );
+    return tracked;
+  }
+
+  private failFrameRefresh(
+    refresh: IFrameRefreshRecord,
+    code: 'FRAME_STREAM_FAILED' | 'FRAME_TOO_LARGE',
+  ): void {
+    refresh.failure ??= new BrowserRuntimeError(code);
+  }
+
+  private async finalizeFrameRefresh(
+    slot: IResourceSlot,
+    refresh: IFrameRefreshRecord,
+  ): Promise<void> {
+    if (refresh.failure) {
+      await this.options.beforeFrameFailureTermination?.();
+      const claimed = await this.handleFrameFailure(
+        slot,
+        refresh.session,
+        refresh.incarnationGeneration,
+        refresh.lease,
+        refresh,
+      );
+      if (!claimed) {
+        this.abandonFrameRefresh(slot, refresh);
+        throw new BrowserRuntimeError('ABORTED');
+      }
+      throw refresh.failure;
+    }
+
+    let current = false;
+    const release = await slot.mutex.acquire();
+    try {
+      try {
+        this.requireValidLease(refresh.lease);
+        current = slot.frameRefresh === refresh
+          && !refresh.abandoned
+          && slot.frameSubscription === refresh.subscription
+          && !refresh.subscription.closed
+          && slot.session === refresh.session
+          && slot.incarnationGeneration === refresh.incarnationGeneration;
+      } catch {
+        current = false;
+      }
+      if (current) {
+        slot.frameRefresh = undefined;
+        for (const [key, frame] of refresh.subscription.outstanding) {
+          if (!frame.timer) this.armFrameAcknowledgementTimer(refresh.subscription, key, frame);
+        }
+      } else {
+        this.abandonFrameRefresh(slot, refresh);
+      }
+    } finally {
+      release();
+    }
+    if (!current) throw new BrowserRuntimeError('ABORTED');
+  }
+
+  private abandonFrameRefresh(slot: IResourceSlot, expected?: IFrameRefreshRecord): void {
+    const refresh = slot.frameRefresh;
+    if (!refresh || (expected && refresh !== expected)) return;
+    refresh.admissionClosed = true;
+    refresh.abandoned = true;
+    slot.frameRefresh = undefined;
+    if (
+      slot.frameSubscription === refresh.subscription
+      && !refresh.subscription.closed
+      && slot.session === refresh.session
+      && slot.incarnationGeneration === refresh.incarnationGeneration
+    ) {
+      for (const [key, frame] of refresh.subscription.outstanding) {
+        if (!frame.timer) this.armFrameAcknowledgementTimer(refresh.subscription, key, frame);
+      }
+    }
+  }
+
+  private armFrameAcknowledgementTimer(
+    subscription: IFrameSubscriptionRecord,
+    key: string,
+    frame: IOutstandingFrameRecord,
+  ): void {
+    if (frame.timer || subscription.closed || !subscription.outstanding.has(key)) return;
+    const timer = setTimeout(() => {
+      this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
+    }, this.options.frameAcknowledgementTimeoutMs);
+    timer.unref();
+    frame.timer = timer;
+  }
+
+  private matchingFrameRefresh(
+    slot: IResourceSlot,
+    subscription: IFrameSubscriptionRecord,
+    session: ILiveBrowserSessionLike,
+    incarnationGeneration: number,
+  ): IFrameRefreshRecord | undefined {
+    const refresh = slot.frameRefresh;
+    return refresh
+      && !refresh.abandoned
+      && refresh.subscription === subscription
+      && refresh.lease === subscription.lease
+      && refresh.session === session
+      && refresh.incarnationGeneration === incarnationGeneration
+      ? refresh
+      : undefined;
+  }
+
   private handleSessionEvent(
     slot: IResourceSlot,
     session: ILiveBrowserSessionLike,
@@ -2210,6 +2565,12 @@ export class BrowserRuntime {
       return;
     }
     const subscription = slot.frameSubscription;
+    const refreshForSession = slot.frameRefresh
+      && !slot.frameRefresh.abandoned
+      && slot.frameRefresh.session === session
+      && slot.frameRefresh.incarnationGeneration === slot.incarnationGeneration
+      ? slot.frameRefresh
+      : undefined;
     if (event.type === 'frame') {
       let acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
       try {
@@ -2218,38 +2579,72 @@ export class BrowserRuntime {
         }
         acknowledgement = this.validateFrameAcknowledgement(event.frame);
       } catch {
+        if (refreshForSession) {
+          this.failFrameRefresh(refreshForSession, 'FRAME_STREAM_FAILED');
+          return;
+        }
         const failedLease = slot.session === session ? (slot.lease ?? null) : null;
         this.trackCleanup(this.handleFrameFailure(
           slot,
           session,
           slot.incarnationGeneration,
           failedLease,
-        ));
+        ).then(() => undefined));
         return;
       }
       if (!subscription || subscription.closed) {
+        if (refreshForSession) {
+          this.failFrameRefresh(refreshForSession, 'FRAME_STREAM_FAILED');
+          return;
+        }
         this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
         return;
       }
+      const refresh = this.matchingFrameRefresh(
+        slot,
+        subscription,
+        session,
+        slot.incarnationGeneration,
+      );
+      if (refreshForSession && refreshForSession !== refresh) {
+        this.failFrameRefresh(refreshForSession, 'FRAME_STREAM_FAILED');
+        return;
+      }
       try {
         this.requireValidLease(subscription.lease);
       } catch {
+        if (refresh) {
+          this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+          return;
+        }
         this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
         this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
         return;
       }
       const key = this.frameAcknowledgementKey(acknowledgement);
       if (acknowledgement.sequence <= subscription.highestSequence) {
+        if (refresh) {
+          this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+          return;
+        }
         this.trackCleanup(this.handleFrameFailure(
           slot,
           session,
           slot.incarnationGeneration,
           subscription.lease,
-        ));
+        ).then(() => undefined));
         return;
       }
       subscription.highestSequence = acknowledgement.sequence;
       if (event.frame.data.byteLength > this.options.maxFrameBytes) {
+        if (refresh) {
+          this.failFrameRefresh(refresh, 'FRAME_TOO_LARGE');
+          this.pushToSubscription(subscription, {
+            type: 'error',
+            error: { code: 'FRAME_TOO_LARGE', fatal: true, tabId: event.frame.tabId },
+          });
+          return;
+        }
         this.trackCleanup(this.acknowledgeFrameInBackground(
           slot,
           session,
@@ -2262,28 +2657,64 @@ export class BrowserRuntime {
         });
         return;
       }
-      while (subscription.outstanding.size >= this.options.maxOutstandingFrames) {
-        const oldestKey = subscription.outstanding.keys().next().value as string | undefined;
-        if (!oldestKey) break;
-        this.trackCleanup(
-          this.retireOutstandingFrame(subscription, oldestKey, false).then(() => undefined),
-        );
+      if (refresh?.admissionClosed) return;
+      const refreshAdmission = refresh && !refresh.admissionClosed && !refresh.abandoned
+        ? refresh
+        : undefined;
+      if (refreshAdmission) {
+        if (refreshAdmission.failure) return;
+        if (
+          subscription.outstanding.size + refreshAdmission.pendingAcknowledgements.size
+          >= this.options.maxOutstandingFrames
+        ) {
+          this.failFrameRefresh(refreshAdmission, 'FRAME_STREAM_FAILED');
+          return;
+        }
+      } else {
+        if (refresh && subscription.outstanding.size >= this.options.maxOutstandingFrames) {
+          this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+        }
+        while (subscription.outstanding.size >= this.options.maxOutstandingFrames) {
+          const oldestKey = subscription.outstanding.keys().next().value as string | undefined;
+          if (!oldestKey) break;
+          this.trackCleanup(
+            this.retireOutstandingFrame(subscription, oldestKey, false).then(() => undefined),
+          );
+        }
       }
-      const timer = setTimeout(() => {
-        this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
-      }, this.options.frameAcknowledgementTimeoutMs);
-      timer.unref();
-      subscription.outstanding.set(key, {
+      const outstanding: IOutstandingFrameRecord = {
         acknowledgement,
-        timer,
         session,
         incarnationGeneration: slot.incarnationGeneration,
-      });
-      this.pushToSubscription(subscription, { type: 'frame', frame: event.frame });
+      };
+      subscription.outstanding.set(key, outstanding);
+      if (!refreshAdmission) this.armFrameAcknowledgementTimer(subscription, key, outstanding);
+      const delivered = this.pushToSubscription(subscription, { type: 'frame', frame: event.frame });
+      if (
+        delivered
+        && refreshAdmission
+        && refreshAdmission.refreshStarted
+        && !refreshAdmission.boundaryCandidate
+      ) {
+        if (
+          acknowledgement.tabId === refreshAdmission.initialTabId
+          && acknowledgement.sequence > refreshAdmission.startingHighestSequence
+          && acknowledgement.generation > refreshAdmission.initialGeneration
+          && acknowledgement.viewportRevision === refreshAdmission.initialViewportRevision
+        ) {
+          refreshAdmission.boundaryCandidate = { ...acknowledgement };
+        } else {
+          this.failFrameRefresh(refreshAdmission, 'FRAME_STREAM_FAILED');
+        }
+      }
       return;
     }
     if (event.type === 'error' && event.error.fatal && slot.lease) {
-      this.trackCleanup(this.revokeCapabilityRecord(slot.lease.capability));
+      if (refreshForSession) {
+        this.failFrameRefresh(refreshForSession, 'FRAME_STREAM_FAILED');
+      } else {
+        this.trackCleanup(this.revokeCapabilityRecord(slot.lease.capability));
+      }
     }
     if (!subscription || subscription.closed) return;
     if (event.type === 'state') {
@@ -2303,22 +2734,30 @@ export class BrowserRuntime {
   private pushToSubscription(
     subscription: IFrameSubscriptionRecord,
     event: TBrowserRuntimeEvent,
-  ): void {
+  ): boolean {
     try {
       this.requireValidLease(subscription.lease);
       subscription.listener(event);
+      return true;
     } catch {
       const slot = subscription.lease.slot;
       const session = slot.session;
       const incarnationGeneration = slot.incarnationGeneration;
+      const refresh = session
+        ? this.matchingFrameRefresh(slot, subscription, session, incarnationGeneration)
+        : undefined;
       if (event.type === 'frame') {
         const key = this.frameAcknowledgementKey(this.validateFrameAcknowledgement(event.frame));
         this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
-        return;
+        return false;
+      }
+      if (refresh) {
+        this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+        return false;
       }
       if (!session) {
         this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
-        return;
+        return false;
       }
       this.trackCleanup((async () => {
         await this.options.beforeFrameFailureTermination?.();
@@ -2329,6 +2768,7 @@ export class BrowserRuntime {
           subscription.lease,
         );
       })());
+      return false;
     }
   }
 
@@ -2336,6 +2776,10 @@ export class BrowserRuntime {
     if (subscription.closed) return;
     subscription.closed = true;
     const slot = subscription.lease.slot;
+    const refresh = slot.frameRefresh;
+    if (refresh?.subscription === subscription && !refresh.abandoned) {
+      this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+    }
     if (slot.frameSubscription === subscription) slot.frameSubscription = undefined;
     for (const key of [...subscription.outstanding.keys()]) {
       await this.retireOutstandingFrame(subscription, key, false);
@@ -2350,15 +2794,37 @@ export class BrowserRuntime {
     const outstanding = subscription.outstanding.get(key);
     if (!outstanding) return false;
     subscription.outstanding.delete(key);
-    clearTimeout(outstanding.timer);
-    const outcome = await this.waitForFrameAcknowledgement(
+    if (outstanding.timer) clearTimeout(outstanding.timer);
+    outstanding.timer = undefined;
+    const slot = subscription.lease.slot;
+    const refresh = this.matchingFrameRefresh(
+      slot,
+      subscription,
+      outstanding.session,
+      outstanding.incarnationGeneration,
+    );
+    if (refresh?.admissionClosed) {
+      this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      return false;
+    }
+    if (refresh && failLease) this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+    const refreshOwned = Boolean(refresh && !refresh.abandoned);
+    const outcome = await this.beginFrameAcknowledgement(
       outstanding.session,
       outstanding.acknowledgement,
+      refreshOwned ? refresh : undefined,
     );
     if (outcome.status === 'fulfilled' && !failLease) return outcome.accepted;
+    if (refreshOwned) return outcome.status === 'fulfilled' ? outcome.accepted : false;
+    if (refresh && slot.frameRefresh === refresh) {
+      if (outcome.status !== 'fulfilled') {
+        this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      }
+      return outcome.status === 'fulfilled' ? outcome.accepted : false;
+    }
     await this.options.beforeFrameFailureTermination?.();
     await this.handleFrameFailure(
-      subscription.lease.slot,
+      slot,
       outstanding.session,
       outstanding.incarnationGeneration,
       subscription.lease,
@@ -2433,8 +2899,25 @@ export class BrowserRuntime {
   ): Promise<void> {
     const failedLease = slot.session === session ? (slot.lease ?? null) : null;
     const incarnationGeneration = slot.incarnationGeneration;
-    const outcome = await this.waitForFrameAcknowledgement(session, acknowledgement);
+    const subscription = slot.frameSubscription;
+    const refresh = subscription
+      ? this.matchingFrameRefresh(slot, subscription, session, incarnationGeneration)
+      : undefined;
+    if (refresh && failLease) this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+    const refreshOwned = Boolean(refresh && !refresh.admissionClosed && !refresh.abandoned);
+    const outcome = await this.beginFrameAcknowledgement(
+      session,
+      acknowledgement,
+      refreshOwned ? refresh : undefined,
+    );
     if (outcome.status === 'fulfilled' && !failLease) return;
+    if (refreshOwned) return;
+    if (refresh && slot.frameRefresh === refresh) {
+      if (outcome.status !== 'fulfilled') {
+        this.failFrameRefresh(refresh, 'FRAME_STREAM_FAILED');
+      }
+      return;
+    }
     await this.options.beforeFrameFailureTermination?.();
     await this.handleFrameFailure(slot, session, incarnationGeneration, failedLease);
   }
@@ -2444,7 +2927,8 @@ export class BrowserRuntime {
     session: ILiveBrowserSessionLike,
     incarnationGeneration: number,
     expectedLease: ILeaseRecord | null,
-  ): Promise<void> {
+    expectedRefresh?: IFrameRefreshRecord,
+  ): Promise<boolean> {
     let transitionGeneration = 0;
     let ownsTransitionFence = false;
     const lease = expectedLease ?? undefined;
@@ -2477,8 +2961,14 @@ export class BrowserRuntime {
         || slot.attachmentRetryBinding
         || !exactLeaseIsCurrent
         || !leaseAttachmentIsCurrent
+        || (expectedRefresh !== undefined && slot.frameRefresh !== expectedRefresh)
         || (slot.fencingGeneration !== undefined && !borrowsLeaseReleaseFence)
-      ) return;
+      ) return false;
+      if (expectedRefresh) {
+        expectedRefresh.admissionClosed = true;
+        expectedRefresh.abandoned = true;
+        slot.frameRefresh = undefined;
+      }
       if (lease) this.invalidateCapabilityRecord(lease.capability);
       if (borrowsLeaseReleaseFence) {
         transitionGeneration = slot.fencingGeneration!;
@@ -2525,6 +3015,7 @@ export class BrowserRuntime {
     if (errors.length > 1) {
       throw new AggregateError(errors, 'Frame acknowledgement cleanup is incomplete');
     }
+    return true;
   }
 
   private trackFrameCapabilityRevocation(lease: ILeaseRecord): void {
@@ -2695,6 +3186,9 @@ export class BrowserRuntime {
     }
     await this.closeFrameSubscriptionIfLease(lease);
     await this.quiesceSlot(slot);
+    if (slot.frameRefresh?.lease === lease) {
+      this.abandonFrameRefresh(slot, slot.frameRefresh);
+    }
     if (
       slot.permanentlyFenced
       && (slot.session || slot.proxy || slot.profileDirectory)
@@ -2779,6 +3273,9 @@ export class BrowserRuntime {
     }
     const session = slot.session;
     if (expectedSession && session !== expectedSession) return;
+    if (slot.frameRefresh && (!session || slot.frameRefresh.session === session)) {
+      this.abandonFrameRefresh(slot, slot.frameRefresh);
+    }
     if (session) {
       let termination: plugins.smartpuppeteer.ILiveBrowserTerminationResult;
       try {
@@ -3577,6 +4074,12 @@ export class BrowserRuntimeLease {
     return this.runtime.acknowledgeLeaseFrame(this.record, acknowledgement);
   }
 
+  public refreshFrameStream(
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseRefreshFrameStream(this.record, operationOptions);
+  }
+
   public readArtifact(artifactId: string): Promise<Uint8Array> {
     return this.runtime.readLeaseArtifact(this.record, artifactId);
   }