@raydiant/playlist-window-manager 0.29.1 → 0.30.0

package/src/PresentationWindow.ts

@@ -26,6 +26,11 @@ import {
   Terminal,
   InterruptLock,
 } from './types';
+import SurfaceBroker, {
+  DEFAULT_SURFACE_SWAP_DELAY_MS,
+  SurfaceRefusal,
+} from './SurfaceBroker';
+import { Rect, VideoEvent, VideoRefusalReason, VideoSurface } from './surfaces';
 
 export interface PresentationWindowOptions {
   windowManager?: PlaylistWindowManager;
@@ -60,10 +65,73 @@ export interface PresentationWindowOptions {
   ) => void;
   getTerminal?: () => Terminal | null;
   getOnlineStatus?: () => boolean;
+  // Set only on a top-level window of a manager given a surface host. The
+  // window then offers its app a video surface.
+  surfaceBroker?: SurfaceBroker;
+  // How long showing a surface may wait for the host's show() and then for
+  // the app to open its hole, together.
+  surfaceShowDeadlineMs?: number;
 }
 
 // TODO: Automatically inject latest version when building in CI.
-const defaultAppRendererUrl = 'https://apps.raydiant.com/3.1.0/index.html';
+const defaultAppRendererUrl = 'https://apps.raydiant.com/3.1.1/index.html';
+
+// The urls a window may open a surface for besides its content url: the
+// Videos app probes for these renditions beside the original.
+const RENDITION_SUFFIXES = ['_4K', '_720p', '_480p'];
+
+// A video surface one window holds. A window holds at most one.
+interface WindowSurface {
+  // Null while the host is still opening it.
+  handle: VideoSurface | null;
+  // The app asked for sound.
+  wantsSound: boolean;
+  firstFrame: boolean;
+  // The bounds the app sent after the first frame.
+  bounds: Rect | null;
+  holeOpen: boolean;
+  // The app opened its hole while the window was hidden.
+  isHolePreopened: boolean;
+  // A swap started the surface before its reveal; the held play then only
+  // tells the app.
+  isPlayingAhead: boolean;
+  // Plays sent to the surface, so a replay seeks to the start.
+  plays: number;
+}
+
+const isValidRect = (value: any): value is Rect =>
+  value &&
+  typeof value === 'object' &&
+  isFiniteNumber(value.x) &&
+  isFiniteNumber(value.y) &&
+  isFiniteNumber(value.width) &&
+  isFiniteNumber(value.height);
+
+const isFiniteNumber = (value: any) =>
+  typeof value === 'number' && isFinite(value);
+
+const roundRect = (rect: Rect): Rect => ({
+  x: Math.round(rect.x),
+  y: Math.round(rect.y),
+  width: Math.round(rect.width),
+  height: Math.round(rect.height),
+});
+
+// Every string held under a `url` key, at any depth.
+const collectUrls = (value: any, urls: string[] = []): string[] => {
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectUrls(item, urls));
+  } else if (value && typeof value === 'object') {
+    Object.keys(value).forEach((key) => {
+      if (key === 'url' && typeof value[key] === 'string') {
+        urls.push(value[key]);
+      } else {
+        collectUrls(value[key], urls);
+      }
+    });
+  }
+  return urls;
+};
 
 const isValidNumber = (value: any) =>
   typeof value === 'number' && !isNaN(value);
@@ -130,6 +198,8 @@ export default class PresentationWindow {
     null;
   private chargeRequestCallback: ((request: ChargeRequest) => void) | null =
     null;
+  private didPaintSinceLastPlay = false;
+  private firstPaintResolvers: Array<() => void> = [];
 
   private builderState: BuilderState | undefined;
   private presentation: Presentation;
@@ -155,6 +225,18 @@ export default class PresentationWindow {
   private interruptLocks: Record<string, InterruptLock> = {};
   private previouslyLocked = false;
 
+  private surface: WindowSurface | null = null;
+  // Once a window has been shown without a ready surface, or has given one
+  // up, it is offered none from then on and its app keeps <video>.
+  private surfaceWithdrawn = false;
+  private surfaceShow: Promise<void> | null = null;
+  private wakeSurfaceShow: Array<() => void> = [];
+  private holeOpenWaiter: (() => void) | null = null;
+  private playingWaiter: (() => void) | null = null;
+  private isPlayHeld = false;
+  private isRemoved = false;
+  private frameBackground = '#000000';
+
   constructor(private options: PresentationWindowOptions) {
     this.builderState = options.builderState;
     this.presentation = options.presentation;
@@ -172,7 +254,51 @@ export default class PresentationWindow {
     return this.loadLegacyApp();
   }
 
-  public show(isFocused: boolean = true): void {
+  // Shows the window. A window holding a surface with its first frame and
+  // bounds shows the surface first and reveals its frame only once the app
+  // has opened its hole; onReveal then runs in the reveal's task. Given
+  // showAfterRevealMs by a swap, a surface whose app opened its hole while
+  // hidden is played, then revealed, then shown instead. The promise
+  // resolves once the frame is revealed and any such show has settled, or
+  // the window is removed.
+  public show(
+    isFocused: boolean = true,
+    onReveal?: () => void,
+    showAfterRevealMs?: number
+  ): Promise<void> {
+    if (this.surfaceShow) {
+      return this.surfaceShow;
+    }
+
+    const surface = this.surface;
+    if (surface && surface.holeOpen) {
+      this.showFrame(isFocused);
+      return Promise.resolve();
+    }
+
+    if (surface && this.isSurfaceReady(surface)) {
+      const showing =
+        showAfterRevealMs !== undefined && surface.isHolePreopened
+          ? this.showSurfaceAfterReveal(
+              surface,
+              isFocused,
+              showAfterRevealMs,
+              onReveal
+            )
+          : this.showSurface(surface, isFocused, onReveal);
+      this.surfaceShow = showing.then(() => {
+        this.surfaceShow = null;
+      });
+      return this.surfaceShow;
+    }
+
+    // Shown before its surface was ready: the app keeps <video>.
+    this.withdrawSurface();
+    this.showFrame(isFocused);
+    return Promise.resolve();
+  }
+
+  private showFrame(isFocused: boolean) {
     const { windowId, renderer } = this.options;
 
     // Show the main window and focus it before any child windows. Showing a child
@@ -241,11 +367,35 @@ export default class PresentationWindow {
       this.configurableDurationTimeout = null;
     }
 
+    // Release anything waiting on a paint signal so callers never hang on a
+    // window that is going away.
+    this.resolveFirstPaintWaiters();
+
+    // Release a surface show in progress; a removed window is never revealed.
+    this.isRemoved = true;
+    this.isPlayHeld = false;
+    this.wakeSurfaceShowWaiters();
+
     // Remove any child window managers.
     Object.values(this.windowManagers).forEach((wm) => {
       wm.destroy();
     });
 
+    // The app paints over its hole, then the surface closes, then the hole
+    // is reported closed, all before the frame goes.
+    const surface = this.surface;
+    const { surfaceBroker } = this.options;
+    if (surface && surfaceBroker) {
+      this.surface = null;
+      if (surface.handle) {
+        this.sendVideoMessage('video_closing');
+      }
+      await surfaceBroker.close(windowId);
+      if (surface.holeOpen) {
+        surfaceBroker.onHole(false);
+      }
+    }
+
     // Remove the main window after removing all the child window managers.
     try {
       await renderer.removeWindow(windowId);
@@ -269,6 +419,19 @@ export default class PresentationWindow {
   public play(): void {
     const { applicationVersion, presentation } = this.options;
 
+    // A window holding a surface plays only once its frame is revealed over
+    // an open hole, so its first paint follows the hole opening.
+    const surface = this.surface;
+    if (surface && !surface.holeOpen) {
+      this.isPlayHeld = true;
+      return;
+    }
+    this.isPlayHeld = false;
+
+    // Each play starts a new paint cycle; 'first_painted' arrives once the
+    // window has presented a frame after this play.
+    this.didPaintSinceLastPlay = false;
+
     if (applicationVersion.configurableDuration) {
       const durationMs = Math.max(presentation.duration * 1000, 5000);
       if (this.configurableDurationTimeout) {
@@ -284,6 +447,20 @@ export default class PresentationWindow {
     if (!this.isEmbeddedApp()) {
       this.sendMessageString('play');
 
+      // A replay seeks to the start rather than reopening, which would cost
+      // a new first frame with nothing in the hole meanwhile.
+      if (surface && surface.handle) {
+        if (surface.isPlayingAhead) {
+          surface.isPlayingAhead = false;
+        } else {
+          if (surface.plays > 0) {
+            surface.handle.seek(0);
+          }
+          surface.handle.play();
+          surface.plays += 1;
+        }
+      }
+
       // Play any child window managers.
       Object.values(this.windowManagers).forEach((wm) => {
         // We only want to trigger play on child windows the first play of the main window or if
@@ -314,6 +491,79 @@ export default class PresentationWindow {
     this.didReceiveComplete = false;
   }
 
+  // Resolves when the window reports its first painted frame after the most
+  // recent play, or after timeoutMs, whichever comes first. Only app-renderer
+  // windows emit the paint signal; anything else exits via the timeout.
+  public waitForFirstPaint(timeoutMs: number): Promise<void> {
+    if (this.didPaintSinceLastPlay) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        const index = this.firstPaintResolvers.indexOf(settle);
+        if (index !== -1) {
+          this.firstPaintResolvers.splice(index, 1);
+        }
+        resolve();
+      };
+      const timer = setTimeout(settle, timeoutMs);
+      this.firstPaintResolvers.push(settle);
+    });
+  }
+
+  // Stop delivering this window's events (complete, error, analytics, charge,
+  // interrupt locks) to the window manager. Used when the outgoing window is
+  // kept on screen only as a visual backdrop during a swap overlap — a late
+  // event from it must not be attributed to the incoming window.
+  public detachCallbacks(): void {
+    this.readyCallback = null;
+    this.completeCallback = null;
+    this.errorCallback = null;
+    this.enableInterruptLockCallback = null;
+    this.disableInterruptLockCallback = null;
+    this.analyticsEventCallback = null;
+    this.chargeRequestCallback = null;
+  }
+
+  // Mute the window's audio channel. On the IFrameRenderer this is best-effort
+  // (iframes expose no mute API); BrowserWindow renderers mute for real.
+  public mute(): void {
+    const { windowId, renderer } = this.options;
+    renderer.muteWindow(windowId);
+  }
+
+  public wasRemoved(): boolean {
+    return this.isRemoved;
+  }
+
+  // The window holds a video surface, opened or still opening.
+  public holdsSurface(): boolean {
+    return this.surface !== null;
+  }
+
+  // A swap is taking this window off screen: mute its surface and tell the
+  // broker its close follows, or mute the window as today when it has none.
+  public muteSurfaceOrFrame(): void {
+    const { windowId, surfaceBroker } = this.options;
+    const surface = this.surface;
+    if (surface && surface.handle && surfaceBroker) {
+      surface.handle.setMuted(true);
+      surfaceBroker.leaving(windowId);
+    } else {
+      this.mute();
+    }
+  }
+
+  private resolveFirstPaintWaiters() {
+    const resolvers = this.firstPaintResolvers;
+    this.firstPaintResolvers = [];
+    resolvers.forEach((resolve) => resolve());
+  }
+
   public onComplete(callback: (() => void) | null) {
     this.completeCallback = callback;
   }
@@ -345,6 +595,12 @@ export default class PresentationWindow {
     if (this.isEmbeddedApp()) {
       return this.didEmbeddedAppLoad;
     }
+    // A window holding a surface is ready only once its first frame has
+    // arrived and the app has sized its hole from it.
+    const surface = this.surface;
+    if (surface && !this.isSurfaceReady(surface)) {
+      return false;
+    }
     return this.didReceiveReady && this.allChildWindowManagersReady();
   }
 
@@ -636,13 +892,14 @@ export default class PresentationWindow {
 
     this.logInfo(`Create window '${windowId}'`);
 
+    this.frameBackground = backgroundColor || '#000000'; // Default to black bg for Raydiant apps
     await this.createAndLoadWindow(
       this.getFullAppRendererUrl({
         appRendererUrl,
         windowId,
         appRendererOfflineSupport,
       }),
-      backgroundColor || '#000000', // Default to black bg for Raydiant apps
+      this.frameBackground,
       this.handleLegacyMessage
     );
 
@@ -766,7 +1023,11 @@ export default class PresentationWindow {
   }
 
   private sendRenderMessage() {
-    const { applicationVersion, isPreview, device } = this.options;
+    const { applicationVersion, isPreview, device, surfaceBroker } =
+      this.options;
+    // The offer of a video surface; app renderer 3.2.0 gives the app its
+    // miraVideo prop only when this is set.
+    const surfaceOffer = surfaceBroker ? { nativeVideo: true } : {};
     // IFrames do not have a mute/unmute API so we are overriding any mute properties
     // to support muting MZ zones when using the IFrameRenderer (SecondScreen).
     if (this.forceMute) {
@@ -786,6 +1047,7 @@ export default class PresentationWindow {
         applicationVersion,
         device,
         isPreview,
+        ...surfaceOffer,
       });
     } else {
       this.sendMessageString('render', {
@@ -795,6 +1057,7 @@ export default class PresentationWindow {
         applicationVersion,
         device,
         isPreview,
+        ...surfaceOffer,
       });
     }
   }
@@ -1274,6 +1537,12 @@ export default class PresentationWindow {
         break;
       }
 
+      case 'open_video': {
+        // An embedded app is never offered a video surface.
+        this.refuseVideo('not_offered');
+        break;
+      }
+
       default: {
         this.logWarning(`Received unknown embedded message type: ${type}`);
       }
@@ -1300,6 +1569,12 @@ export default class PresentationWindow {
       this.handleComplete();
     }
 
+    if (type === 'first_painted') {
+      this.logDebug(`Received 'first_painted' from window '${windowId}'`);
+      this.didPaintSinceLastPlay = true;
+      this.resolveFirstPaintWaiters();
+    }
+
     if (type === 'enable_interrupt_lock') {
       this.logInfo(
         `Received 'enable_interrupt_lock' from window '${windowId}'`
@@ -1339,6 +1614,38 @@ export default class PresentationWindow {
       }
     }
 
+    if (type === 'open_video') {
+      this.handleOpenVideo(payload);
+    }
+
+    if (type === 'video_bounds') {
+      this.handleVideoBounds(payload);
+    }
+
+    if (type === 'video_hole_open') {
+      this.logInfo(`Received 'video_hole_open' from window '${windowId}'`);
+      const surface = this.surface;
+      if (this.holeOpenWaiter) {
+        this.holeOpenWaiter();
+      } else if (
+        surface &&
+        surface.firstFrame &&
+        !surface.holeOpen &&
+        !this.surfaceShow
+      ) {
+        // Opened before the window is shown, so a swap may play and reveal
+        // it before showing its surface.
+        surface.isHolePreopened = true;
+      }
+    }
+
+    if (type === 'close_video') {
+      this.logInfo(`Received 'close_video' from window '${windowId}'`);
+      if (this.surface) {
+        this.dropSurface(this.surface);
+      }
+    }
+
     if (type === 'close_child_window') {
       // TODO: Validate close_child_window message payload.
       this.logInfo(
@@ -1381,6 +1688,407 @@ export default class PresentationWindow {
     }
   };
 
+  private handleOpenVideo(payload?: any) {
+    const { windowId, surfaceBroker, presentation } = this.options;
+
+    this.logInfo(
+      `Received 'open_video' from window '${windowId}', url=${
+        payload && payload.url
+      }`
+    );
+
+    if (!surfaceBroker || this.surfaceWithdrawn || this.isEmbeddedApp()) {
+      this.refuseVideo('not_offered');
+      return;
+    }
+
+    if (this.surface) {
+      this.logWarning(
+        `Ignoring 'open_video' from window '${windowId}', it already holds a surface`
+      );
+      return;
+    }
+
+    if (
+      !payload ||
+      typeof payload !== 'object' ||
+      typeof payload.url !== 'string' ||
+      !isValidRect(payload.bounds) ||
+      !this.isOfferedVideoUrl(payload.url)
+    ) {
+      this.refuseVideo('not_offered');
+      return;
+    }
+
+    const surface: WindowSurface = {
+      handle: null,
+      wantsSound: payload.muted === false,
+      firstFrame: false,
+      bounds: null,
+      holeOpen: false,
+      isHolePreopened: false,
+      isPlayingAhead: false,
+      plays: 0,
+    };
+    this.surface = surface;
+
+    surfaceBroker
+      .open(
+        windowId,
+        {
+          url: payload.url,
+          bounds: roundRect(payload.bounds),
+          // Always opened muted; sound waits for the show.
+          muted: true,
+          label: presentation.id,
+        },
+        (event) => this.handleSurfaceEvent(surface, event),
+        (reason) => {
+          if (this.surface !== surface) return;
+          this.sendVideoMessage('video_refused', { reason });
+          this.dropSurface(surface);
+        }
+      )
+      .then(
+        (handle) => {
+          if (this.surface !== surface) return;
+          surface.handle = handle;
+          this.sendVideoMessage('video_opened');
+        },
+        (err: unknown) => {
+          if (this.surface !== surface) return;
+          const reason =
+            err instanceof SurfaceRefusal ? err.reason : 'unsupported';
+          // The broker has logged its refusal.
+          if (reason !== 'closed') {
+            this.sendVideoMessage('video_refused', { reason });
+          }
+          this.dropSurface(surface);
+        }
+      );
+  }
+
+  private handleVideoBounds(payload?: any) {
+    const surface = this.surface;
+    if (!surface || !surface.handle) return;
+
+    if (!payload || !isValidRect(payload.bounds)) {
+      this.logWarning(`Invalid payload received for 'video_bounds', ignoring`);
+      return;
+    }
+
+    const bounds = roundRect(payload.bounds);
+    surface.handle.setBounds(bounds);
+
+    if (surface.firstFrame) {
+      const wasSized = surface.bounds !== null;
+      surface.bounds = bounds;
+      if (!wasSized) {
+        this.checkIsReadyCallback();
+      }
+    }
+  }
+
+  private handleSurfaceEvent(surface: WindowSurface, event: VideoEvent) {
+    if (this.surface !== surface) return;
+    // A stall is the host's to ride out, but it reaches the app: an app that
+    // times its own complete holds that timer until the next 'playing'.
+
+    if (event.type === 'first_frame') {
+      surface.firstFrame = true;
+    }
+
+    this.sendVideoMessage('video_event', event);
+
+    if (event.type === 'playing' && this.playingWaiter) {
+      this.playingWaiter();
+    }
+
+    if (event.type === 'error') {
+      this.dropSurface(surface);
+    }
+  }
+
+  private isSurfaceReady(surface: WindowSurface) {
+    return !!surface.handle && surface.firstFrame && surface.bounds !== null;
+  }
+
+  // Only an http(s) url the presentation holds, or one of its renditions,
+  // opens a surface: it is the url the app would give <video>.
+  private isOfferedVideoUrl(url: string) {
+    if (!/^https?:\/\//i.test(url)) return false;
+    return collectUrls(this.presentation.applicationVariables).some(
+      (offered) =>
+        url === offered ||
+        RENDITION_SUFFIXES.some((suffix) => url === `${offered}${suffix}`)
+    );
+  }
+
+  // Shows a ready surface: the host's show() is awaited, the app is told to
+  // open its hole, and the frame is revealed once it has. One deadline covers
+  // both waits; past it the app keeps <video> and the frame shows as today.
+  private async showSurface(
+    surface: WindowSurface,
+    isFocused: boolean,
+    onReveal?: () => void
+  ) {
+    const { surfaceShowDeadlineMs = DEFAULT_SURFACE_SWAP_DELAY_MS } =
+      this.options;
+    const handle = surface.handle as VideoSurface;
+
+    let passDeadline: (value: 'deadline') => void = () => undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      passDeadline = resolve;
+    });
+    const timer = setTimeout(
+      () => passDeadline('deadline'),
+      surfaceShowDeadlineMs
+    );
+    // Resolves when the window is removed or gives its surface up.
+    let wake: () => void = () => undefined;
+    const woken = new Promise<'woken'>((resolve) => {
+      wake = () => resolve('woken');
+    });
+    this.wakeSurfaceShow.push(wake);
+    const holeOpen = new Promise<'hole_open'>((resolve) => {
+      this.holeOpenWaiter = () => resolve('hole_open');
+    });
+    const finish = () => {
+      clearTimeout(timer);
+      this.holeOpenWaiter = null;
+      this.wakeSurfaceShow = this.wakeSurfaceShow.filter((w) => w !== wake);
+    };
+
+    let outcome: 'shown' | 'hole_open' | 'deadline' | 'woken' | 'failed' =
+      await Promise.race([
+        handle.show().then(
+          () => 'shown' as const,
+          () => 'failed' as const
+        ),
+        deadline,
+        woken,
+      ]);
+
+    if (outcome === 'shown' && this.surface === surface && !this.isRemoved) {
+      if (surface.wantsSound && !this.forceMute) {
+        handle.setMuted(false);
+      }
+      this.sendVideoMessage('video_shown');
+      outcome = await Promise.race([holeOpen, deadline, woken]);
+    }
+    finish();
+
+    if (this.isRemoved) {
+      return;
+    }
+
+    if (outcome === 'hole_open' && this.surface === surface) {
+      this.revealOverHole(surface, isFocused, onReveal);
+      return;
+    }
+
+    // A show the host rejected falls back as a missed deadline does, under
+    // the host's own answer.
+    if (
+      (outcome === 'deadline' || outcome === 'failed') &&
+      this.surface === surface
+    ) {
+      this.refuseVideo(outcome === 'failed' ? 'unsupported' : 'deadline');
+      this.dropSurface(surface);
+    }
+
+    // The surface is gone: the frame shows and plays as today.
+    this.showFrame(isFocused);
+    this.releaseHeldPlay();
+  }
+
+  // A swap's incoming surface whose app opened its hole while hidden. It
+  // plays first, still hidden and muted, and the frame is revealed over the
+  // outgoing surface once it reports playing, so the picture is moving when
+  // it appears and no first frame is held. The surface is shown
+  // showAfterRevealMs later: it reaches the screen sooner than the frame
+  // does, so the two land together. Sound waits for the show, so it never
+  // overlaps the outgoing surface's. A surface that never reports playing is
+  // revealed at the show deadline; past a second deadline on the show the
+  // app keeps <video> in the frame already revealed.
+  private async showSurfaceAfterReveal(
+    surface: WindowSurface,
+    isFocused: boolean,
+    showAfterRevealMs: number,
+    onReveal?: () => void
+  ) {
+    const { surfaceShowDeadlineMs = DEFAULT_SURFACE_SWAP_DELAY_MS } =
+      this.options;
+    const handle = surface.handle as VideoSurface;
+
+    const timers: Array<ReturnType<typeof setTimeout>> = [];
+    const after = <T>(ms: number, value: T) =>
+      new Promise<T>((resolve) => {
+        timers.push(setTimeout(() => resolve(value), ms));
+      });
+    // Resolves when the window is removed or gives its surface up.
+    let wake: () => void = () => undefined;
+    const woken = new Promise<'woken'>((resolve) => {
+      wake = () => resolve('woken');
+    });
+    this.wakeSurfaceShow.push(wake);
+    const isHeld = () => !this.isRemoved && this.surface === surface;
+
+    const playing = new Promise<'playing'>((resolve) => {
+      this.playingWaiter = () => resolve('playing');
+    });
+    handle.play();
+    surface.plays += 1;
+    surface.isPlayingAhead = true;
+
+    let isRevealed = false;
+    let outcome:
+      | 'playing'
+      | 'no_playing'
+      | 'show'
+      | 'shown'
+      | 'deadline'
+      | 'failed'
+      | 'woken' = await Promise.race([
+      playing,
+      after(surfaceShowDeadlineMs, 'no_playing' as const),
+      woken,
+    ]);
+    this.playingWaiter = null;
+    if (outcome === 'no_playing') {
+      this.logWarning(
+        `No 'playing' from the surface of window '${this.options.windowId}', revealing it anyway`
+      );
+    }
+    if ((outcome === 'playing' || outcome === 'no_playing') && isHeld()) {
+      isRevealed = true;
+      this.revealOverHole(surface, isFocused, onReveal);
+      outcome = await Promise.race([
+        after(showAfterRevealMs, 'show' as const),
+        woken,
+      ]);
+    }
+    if (outcome === 'show' && isHeld()) {
+      outcome = await Promise.race([
+        handle.show().then(
+          () => 'shown' as const,
+          () => 'failed' as const
+        ),
+        after(surfaceShowDeadlineMs, 'deadline' as const),
+        woken,
+      ]);
+    }
+    timers.forEach((timer) => clearTimeout(timer));
+    this.wakeSurfaceShow = this.wakeSurfaceShow.filter((w) => w !== wake);
+
+    if (this.isRemoved) {
+      return;
+    }
+
+    if (outcome === 'shown' && this.surface === surface) {
+      if (surface.wantsSound && !this.forceMute) {
+        handle.setMuted(false);
+      }
+      this.sendVideoMessage('video_shown');
+      return;
+    }
+
+    if (
+      (outcome === 'deadline' || outcome === 'failed') &&
+      this.surface === surface
+    ) {
+      this.refuseVideo(outcome === 'failed' ? 'unsupported' : 'deadline');
+      this.dropSurface(surface);
+    }
+
+    // The surface went before its reveal: the frame shows and plays as today.
+    if (!isRevealed) {
+      this.showFrame(isFocused);
+      this.releaseHeldPlay();
+    }
+  }
+
+  // Reveals the frame over its surface's open hole, and runs the caller's
+  // onReveal and any held play in that same task.
+  private revealOverHole(
+    surface: WindowSurface,
+    isFocused: boolean,
+    onReveal?: () => void
+  ) {
+    const { windowId, renderer, surfaceBroker } = this.options;
+    surface.holeOpen = true;
+    (surfaceBroker as SurfaceBroker).onHole(true);
+    if (renderer.setWindowBackground) {
+      renderer.setWindowBackground(windowId, 'transparent');
+    }
+    this.showFrame(isFocused);
+    if (onReveal) onReveal();
+    this.releaseHeldPlay();
+  }
+
+  // Shown before its surface was ready: any surface it holds closes and the
+  // window is offered none from then on.
+  private withdrawSurface() {
+    this.surfaceWithdrawn = true;
+    const surface = this.surface;
+    if (surface) {
+      this.refuseVideo('not_offered');
+      this.dropSurface(surface);
+    }
+  }
+
+  // The window gives its surface up: closed through the broker, its hole
+  // reported closed and its frame background restored. It holds none from
+  // then on, and counts ready and swaps as any other window.
+  private dropSurface(surface: WindowSurface) {
+    const { windowId, renderer, surfaceBroker } = this.options;
+    if (this.surface !== surface || !surfaceBroker) return;
+
+    this.surface = null;
+    this.surfaceWithdrawn = true;
+    surfaceBroker.close(windowId);
+
+    if (surface.holeOpen) {
+      surface.holeOpen = false;
+      surfaceBroker.onHole(false);
+      if (renderer.setWindowBackground) {
+        renderer.setWindowBackground(windowId, this.frameBackground);
+      }
+    }
+
+    this.wakeSurfaceShowWaiters();
+    this.checkIsReadyCallback();
+  }
+
+  private wakeSurfaceShowWaiters() {
+    const waiters = this.wakeSurfaceShow;
+    this.wakeSurfaceShow = [];
+    waiters.forEach((wake) => wake());
+  }
+
+  private releaseHeldPlay() {
+    if (this.isPlayHeld) {
+      this.isPlayHeld = false;
+      this.play();
+    }
+  }
+
+  private refuseVideo(reason: VideoRefusalReason) {
+    this.logWarning(
+      `Sending 'video_refused' to window '${this.options.windowId}', reason=${reason}`
+    );
+    this.sendVideoMessage('video_refused', { reason });
+  }
+
+  // Every video message rides the string channel the app renderer reads.
+  private sendVideoMessage(type: string, payload?: any) {
+    try {
+      this.sendMessageString(type, payload);
+    } catch (err: any) {
+      this.logWarning(`Failed to send '${type}' with '${err.message}'`);
+    }
+  }
+
   private handleReady() {
     this.didReceiveReady = true;
     this.checkIsReadyCallback();