@raydiant/playlist-window-manager 0.29.1 → 0.30.0

package/src/PlaylistWindowManager.test.ts

@@ -0,0 +1,1466 @@
+import * as RE from '@raydiant/playlist-rule-engine';
+import MockDate from 'mockdate';
+import PlaylistWindowManager, {
+  PlaylistWindowManagerOptions,
+} from './PlaylistWindowManager';
+import {
+  createApplicationVersion,
+  createFakeSurfaceHost,
+  createLogger,
+  createPlaylistWindowManagerState,
+  createPresentation,
+  createRecordingRenderer,
+  flush,
+} from './testUtils';
+import { VideoOptions } from './surfaces';
+
+const CLOSE_WINDOW_DELAY_MS = 50;
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Long enough for every scripted app reply and any surface show deadline.
+const settle = async () => {
+  await flush(20);
+  await wait(CLOSE_WINDOW_DELAY_MS * 2);
+  await flush(20);
+};
+
+let now = Date.parse('2026-10-28T12:00:00Z');
+
+// The manager throttles completes that arrive within three seconds of each
+// other; moving the clock past that keeps every test on the unthrottled path.
+const passTime = () => {
+  now += 5000;
+  MockDate.set(now);
+};
+
+beforeEach(() => {
+  MockDate.set(now);
+});
+
+afterEach(() => {
+  MockDate.reset();
+});
+
+interface ManagerSetup {
+  presentationIds: string[];
+  options?: Partial<PlaylistWindowManagerOptions>;
+}
+
+function createManager({ presentationIds, options = {} }: ManagerSetup) {
+  const presentations: Record<
+    string,
+    ReturnType<typeof createPresentation>
+  > = {};
+  const rePresentations: Record<string, RE.Presentation> = {};
+  presentationIds.forEach((id) => {
+    presentations[id] = createPresentation({
+      id,
+      applicationDeploymentId: 'app',
+      applicationVariables: {
+        content: { url: `https://cdn.test/${id}.mp4` },
+        muted: false,
+      },
+    });
+    rePresentations[id] = { id, applicationName: 'videos' };
+  });
+
+  const state = createPlaylistWindowManagerState({
+    presentations,
+    applicationVersions: { app: createApplicationVersion({ id: 'app' }) },
+  });
+  const reState = new RE.State(
+    {
+      main: {
+        id: 'main',
+        mode: RE.PlaylistMode.Sequential,
+        items: presentationIds.map((presentationId) => ({ presentationId })),
+      },
+    },
+    rePresentations,
+    {}
+  );
+
+  const recording = createRecordingRenderer();
+  const manager = new PlaylistWindowManager({
+    ruleEngine: new RE.RuleEngine('main', reState),
+    state,
+    logger: createLogger(),
+    closeWindowDelayMs: CLOSE_WINDOW_DELAY_MS,
+    ...options,
+  });
+  manager.setRenderer(recording.renderer);
+
+  return { manager, recording };
+}
+
+// Plays the app and app renderer the way a still-image app does: ready on
+// render, and a first paint shortly after each play.
+function scriptImageApp(recording: ReturnType<typeof createRecordingRenderer>) {
+  recording.hooks.onLoad = (windowId) => recording.receive(windowId, 'loaded');
+  recording.hooks.onMessage = (windowId, type) => {
+    if (type === 'render') recording.receive(windowId, 'presentation_ready');
+    if (type === 'play') {
+      setTimeout(() => recording.receive(windowId, 'first_painted'), 0);
+    }
+  };
+}
+
+// The window most recently shown, which is the one playing.
+function lastShown(recording: ReturnType<typeof createRecordingRenderer>) {
+  const shows = recording.calls.filter((c) => c.method === 'showWindow');
+  return shows[shows.length - 1].windowId;
+}
+
+// Names windows w1, w2, … in creation order so a sequence reads the same on
+// every run.
+function describeCalls(recording: ReturnType<typeof createRecordingRenderer>) {
+  const aliases: Record<string, string> = {};
+  return recording.calls.map(({ method, windowId, args }) => {
+    if (!aliases[windowId]) {
+      aliases[windowId] = `w${Object.keys(aliases).length + 1}`;
+    }
+    const detail =
+      method === 'sendMessageString' || method === 'sendMessageObject'
+        ? ` ${args[0]}`
+        : '';
+    return `${method} ${aliases[windowId]}${detail}`;
+  });
+}
+
+describe('no surface host', () => {
+  test('a two-presentation swap keeps the renderer call sequence', async () => {
+    const { manager, recording } = createManager({
+      presentationIds: ['a', 'b'],
+    });
+    scriptImageApp(recording);
+
+    await manager.load();
+    await flush();
+    manager.show();
+    manager.play();
+    await flush();
+
+    const current = lastShown(recording);
+    passTime();
+    recording.receive(current, 'presentation_complete');
+    await flush();
+    await new Promise((resolve) => setTimeout(resolve, CLOSE_WINDOW_DELAY_MS));
+    await flush();
+
+    expect(describeCalls(recording)).toMatchSnapshot();
+
+    await manager.destroy();
+  });
+});
+
+type Recording = ReturnType<typeof createRecordingRenderer>;
+type FakeHost = ReturnType<typeof createFakeSurfaceHost>;
+
+interface AppScript {
+  // Presentations whose app is a still image and never asks for a surface.
+  images?: string[];
+  // Presentations whose first frame waits for the test to emit it.
+  holdFirstFrame?: string[];
+  // Presentations whose first window's app never answers video_shown.
+  holdHole?: string[];
+  // Presentations whose app opens its hole once sized, while still hidden,
+  // and again on video_shown.
+  preopenHole?: string[];
+}
+
+// Plays the Videos app and app renderer the way the Videos plan describes,
+// replying a task later as postMessage does: ask for a surface on render when
+// offered one, size the hole and become ready on the first frame, open the
+// hole on video_shown, complete on ended, fall back to <video> on a refusal.
+function scriptApps(recording: Recording, host: FakeHost, script: AppScript) {
+  const images = script.images || [];
+  const holdFirstFrame = new Set(script.holdFirstFrame || []);
+  const holdHole = new Set(script.holdHole || []);
+  const preopenHole = new Set(script.preopenHole || []);
+  const presentationOf: Record<string, string> = {};
+  const isReady: Record<string, boolean> = {};
+
+  const reply = (windowId: string, type: string, payload?: any) => {
+    setTimeout(() => recording.receive(windowId, type, payload), 0);
+  };
+  const ready = (windowId: string) => {
+    if (isReady[windowId]) return;
+    isReady[windowId] = true;
+    reply(windowId, 'presentation_ready');
+  };
+  const surfaceOf = (presentationId: string) => {
+    const opens = host.calls.filter(
+      (c) =>
+        c.method === 'openVideo' &&
+        (c.args[0] as VideoOptions).label === presentationId &&
+        c.id !== undefined
+    );
+    return opens[opens.length - 1].id as number;
+  };
+  const emitFirstFrame = (presentationId: string) => {
+    host.emit(surfaceOf(presentationId), {
+      type: 'first_frame',
+      width: 1920,
+      height: 1080,
+      durationS: 10,
+    });
+  };
+
+  recording.hooks.onLoad = (windowId) => reply(windowId, 'loaded');
+  recording.hooks.onMessage = (windowId, type, payload) => {
+    const presentationId = presentationOf[windowId];
+    switch (type) {
+      case 'render': {
+        const id = payload.presentation.id;
+        presentationOf[windowId] = id;
+        if (payload.nativeVideo && images.indexOf(id) === -1) {
+          reply(windowId, 'open_video', {
+            url: `https://cdn.test/${id}.mp4`,
+            bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+            muted: false,
+          });
+        } else {
+          ready(windowId);
+        }
+        break;
+      }
+      case 'video_refused':
+        ready(windowId);
+        break;
+      case 'video_opened':
+        if (!holdFirstFrame.has(presentationId)) {
+          setTimeout(() => emitFirstFrame(presentationId), 0);
+        }
+        break;
+      case 'video_event':
+        if (payload.type === 'first_frame') {
+          reply(windowId, 'video_bounds', {
+            bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+          });
+          ready(windowId);
+          if (preopenHole.has(presentationId)) {
+            reply(windowId, 'video_hole_open');
+          }
+        }
+        if (payload.type === 'ended') {
+          reply(windowId, 'presentation_complete');
+        }
+        break;
+      case 'video_shown':
+        if (holdHole.has(presentationId)) {
+          holdHole.delete(presentationId);
+        } else {
+          reply(windowId, 'video_hole_open');
+        }
+        break;
+      case 'play':
+        reply(windowId, 'first_painted');
+        break;
+    }
+  };
+
+  const windowOf = (presentationId: string) => {
+    const ids = Object.keys(presentationOf).filter(
+      (w) => presentationOf[w] === presentationId
+    );
+    return ids[ids.length - 1];
+  };
+
+  return { presentationOf, surfaceOf, emitFirstFrame, windowOf };
+}
+
+function createSurfaceManager(
+  presentationIds: string[],
+  script: AppScript = {},
+  hostOpts?: Parameters<typeof createFakeSurfaceHost>[0],
+  managerOptions: Partial<PlaylistWindowManagerOptions> = {},
+  showAfterRevealMs?: number
+) {
+  const host = createFakeSurfaceHost(hostOpts);
+  const warn = jest.fn();
+  const { manager, recording } = createManager({
+    presentationIds,
+    options: {
+      surfaces: { ...host.surfaces, showAfterRevealMs },
+      logger: createLogger({ warn }),
+      ...managerOptions,
+    },
+  });
+  const apps = scriptApps(recording, host, script);
+
+  // Every call and app message in order. A window and its surface are named
+  // by their presentation, and a later window of the same presentation gets
+  // a number: a, then a2.
+  const entries = () => {
+    const nameWith = (counts: Record<string, number>, label: string) => {
+      counts[label] = (counts[label] || 0) + 1;
+      return counts[label] === 1 ? label : `${label}${counts[label]}`;
+    };
+    const windowCounts: Record<string, number> = {};
+    const windowName: Record<string, string> = {};
+    Object.keys(apps.presentationOf).forEach((windowId) => {
+      windowName[windowId] = nameWith(
+        windowCounts,
+        apps.presentationOf[windowId]
+      );
+    });
+    const surfaceCounts: Record<string, number> = {};
+    const labelOf: Record<number, string> = {};
+    host.calls.forEach((c) => {
+      if (c.method === 'openVideo' && c.id !== undefined) {
+        labelOf[c.id] = nameWith(
+          surfaceCounts,
+          (c.args[0] as VideoOptions).label as string
+        );
+      }
+    });
+    const rendererEntries = recording.calls.map((c) => {
+      const name = windowName[c.windowId] || '?';
+      const detail =
+        c.method === 'sendMessageString' || c.method === 'setWindowBackground'
+          ? ` ${c.args[0]}`
+          : '';
+      return { seq: c.seq, text: `${c.method} ${name}${detail}` };
+    });
+    const appEntries = recording.received.map((c) => ({
+      seq: c.seq,
+      text: `app ${windowName[c.windowId] || '?'} ${c.method}`,
+    }));
+    const hostEntries = host.calls.map((c) => {
+      const name = c.id !== undefined ? labelOf[c.id] : '';
+      const detail = c.method === 'setMuted' ? ` ${c.args[0]}` : '';
+      const onHole = c.method === 'onHole' ? ` ${c.args[0]}` : '';
+      return {
+        seq: c.seq,
+        text: `host ${c.method}${name ? ` ${name}` : ''}${detail}${onHole}`,
+      };
+    });
+    return rendererEntries
+      .concat(appEntries, hostEntries)
+      .sort((x, y) => x.seq - y.seq);
+  };
+  const timeline = () => entries().map((e) => e.text);
+
+  const sent = (presentationId: string, type: string) =>
+    recording.calls.filter(
+      (c) =>
+        c.method === 'sendMessageString' &&
+        c.args[0] === type &&
+        apps.presentationOf[c.windowId] === presentationId
+    );
+
+  const hostCalls = (method: string, presentationId?: string) => {
+    const ids =
+      presentationId === undefined
+        ? null
+        : host.calls
+            .filter(
+              (c) =>
+                c.method === 'openVideo' &&
+                (c.args[0] as VideoOptions).label === presentationId
+            )
+            .map((c) => c.id);
+    return host.calls.filter(
+      (c) => c.method === method && (ids === null || ids.indexOf(c.id) !== -1)
+    );
+  };
+
+  const complete = async (presentationId: string) => {
+    passTime();
+    recording.receive(apps.windowOf(presentationId), 'presentation_complete');
+    await settle();
+  };
+
+  const start = async () => {
+    await manager.load();
+    manager.show();
+    manager.play();
+    await settle();
+  };
+
+  return {
+    manager,
+    recording,
+    host,
+    warn,
+    apps,
+    entries,
+    timeline,
+    sent,
+    hostCalls,
+    complete,
+    start,
+  };
+}
+
+// The calls and messages a swap's order is read from.
+const swapSteps = [
+  'host setMuted',
+  'muteWindow',
+  'host show',
+  'sendMessageString',
+  'app',
+  'setWindowBackground',
+  'showWindow',
+  'hideWindow',
+  'host close',
+  'removeWindow',
+];
+// Leaves out the next window's preload, which runs alongside the swap, and
+// messages that are not part of the swap's order.
+const isSwapStep = (line: string) =>
+  swapSteps.some((step) => line.startsWith(step)) &&
+  !/ (\?|[a-z]\d)( |$)/.test(line) &&
+  !/ (render|play|log_\w+|loaded|video_opened|video_event)$/.test(line) &&
+  !/app \S+ (presentation_ready|video_bounds|open_video)/.test(line);
+
+describe('a manager given a surface host', () => {
+  test('an app asks through miraVideo and render carries nativeVideo', async () => {
+    const { manager, sent, hostCalls, start } = createSurfaceManager(['a']);
+    await start();
+
+    expect(sent('a', 'render')[0].args[1]).toMatchObject({
+      nativeVideo: true,
+    });
+    expect(hostCalls('openVideo')).toHaveLength(1);
+    expect(hostCalls('openVideo')[0].args[0]).toEqual({
+      url: 'https://cdn.test/a.mp4',
+      bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+      muted: true,
+      label: 'a',
+    });
+
+    await manager.destroy();
+  });
+
+  test('the first presentation shows its surface before its frame, and plays after the hole opens', async () => {
+    const { manager, host, timeline, start } = createSurfaceManager(['a']);
+    await start();
+
+    const steps = timeline().filter(
+      (line) =>
+        line.startsWith('host show') ||
+        line.startsWith('host play') ||
+        line.startsWith('host onHole') ||
+        line.startsWith('showWindow') ||
+        line === 'sendMessageString a video_shown' ||
+        line === 'sendMessageString a play' ||
+        line === 'app a video_hole_open'
+    );
+    expect(steps).toEqual([
+      'host show a',
+      'sendMessageString a video_shown',
+      'app a video_hole_open',
+      'host onHole true',
+      'showWindow a',
+      'sendMessageString a play',
+      'host play a',
+    ]);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('the next presentation preloads hidden and is ready on its first frame, then its bounds', async () => {
+    const { manager, recording, host, apps, hostCalls, start } =
+      createSurfaceManager(['a', 'b'], { holdFirstFrame: ['b'] });
+    await start();
+
+    const next = (manager as any).nextWindow;
+    expect(hostCalls('openVideo', 'b')).toHaveLength(1);
+    expect(next.isReady()).toBe(false);
+
+    // The first frame alone does not make it ready; the bounds that follow do.
+    recording.hooks.onMessage = ((original) => (w, type, payload) => {
+      if (type === 'video_event' && payload.type === 'first_frame') return;
+      if (original) original(w, type, payload);
+    })(recording.hooks.onMessage);
+    apps.emitFirstFrame('b');
+    await settle();
+    expect(next.isReady()).toBe(false);
+
+    recording.receive(apps.windowOf('b'), 'video_bounds', {
+      bounds: { x: 0, y: 0.4, width: 1920.4, height: 1080 },
+    });
+    recording.receive(apps.windowOf('b'), 'presentation_ready');
+    expect(next.isReady()).toBe(true);
+
+    expect(hostCalls('show', 'b')).toHaveLength(0);
+    expect(hostCalls('setBounds', 'b')[0].args[0]).toEqual({
+      x: 0,
+      y: 0,
+      width: 1920,
+      height: 1080,
+    });
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a video to video swap shows the new before it hides the old', async () => {
+    const { manager, recording, host, apps, timeline, complete, start } =
+      createSurfaceManager(['a', 'b']);
+    await start();
+
+    // The reveal and the outgoing hide land in one task.
+    const a = apps.windowOf('a');
+    const b = apps.windowOf('b');
+    let hiddenInRevealTask: boolean | null = null;
+    const showWindow = recording.renderer.showWindow;
+    recording.renderer.showWindow = (windowId: string, isFocused: boolean) => {
+      showWindow(windowId, isFocused);
+      if (windowId === b) {
+        Promise.resolve().then(() => {
+          hiddenInRevealTask = recording.calls.some(
+            (c) => c.method === 'hideWindow' && c.windowId === a
+          );
+        });
+      }
+    };
+
+    const before = timeline().length;
+    await complete('a');
+    const swap = timeline().slice(before).filter(isSwapStep);
+
+    expect(swap).toEqual([
+      'app a presentation_complete',
+      'host setMuted a true',
+      'host show b',
+      'host setMuted b false',
+      'sendMessageString b video_shown',
+      'app b video_hole_open',
+      'setWindowBackground b transparent',
+      'showWindow b',
+      'hideWindow a',
+      'app b first_painted',
+      'sendMessageString a video_closing',
+      'host close a',
+      'removeWindow a',
+    ]);
+    expect(hiddenInRevealTask).toBe(true);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a video to image swap reveals the image at once and closes the surface after its paint', async () => {
+    const { manager, host, timeline, complete, start } = createSurfaceManager(
+      ['a', 'b'],
+      { images: ['b'] }
+    );
+    await start();
+
+    const before = timeline().length;
+    await complete('a');
+    const swap = timeline().slice(before).filter(isSwapStep);
+
+    expect(swap).toEqual([
+      'app a presentation_complete',
+      'host setMuted a true',
+      'showWindow b',
+      'app b first_painted',
+      'hideWindow a',
+      'sendMessageString a video_closing',
+      'host close a',
+      'removeWindow a',
+    ]);
+    expect(timeline()).toContain('host onHole false');
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('an image to video swap holds the image up until the surface is on screen', async () => {
+    const { manager, host, timeline, complete, start } = createSurfaceManager(
+      ['a', 'b'],
+      { images: ['a'] }
+    );
+    await start();
+
+    const before = timeline().length;
+    await complete('a');
+    const swap = timeline().slice(before).filter(isSwapStep);
+
+    expect(swap).toEqual([
+      'app a presentation_complete',
+      'muteWindow a',
+      'host show b',
+      'host setMuted b false',
+      'sendMessageString b video_shown',
+      'app b video_hole_open',
+      'setWindowBackground b transparent',
+      'showWindow b',
+      'hideWindow a',
+      'app b first_painted',
+      'removeWindow a',
+    ]);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test.each([
+    ['a hung show', { hangShow: true }, {}],
+    ['a missing hole acknowledgement', {}, { holdHole: ['a'] }],
+  ])(
+    'the first presentation with %s falls back to <video> and plays',
+    async (_, hostOpts, script) => {
+      const { manager, host, warn, sent, hostCalls, timeline, start } =
+        createSurfaceManager(['a'], script as AppScript, hostOpts);
+      await start();
+
+      expect(sent('a', 'video_refused').map((c) => c.args[1])).toEqual([
+        { reason: 'deadline' },
+      ]);
+      expect(hostCalls('close', 'a')).toHaveLength(1);
+      expect(timeline()).toContain('showWindow a');
+      expect(sent('a', 'play')).toHaveLength(1);
+      expect(timeline()).not.toContain('host onHole true');
+      expect(
+        warn.mock.calls.filter(([message]) =>
+          /video_refused.*deadline/.test(message)
+        )
+      ).toHaveLength(1);
+      expect(host.violations).toEqual([]);
+
+      await manager.destroy();
+    }
+  );
+
+  test.each([
+    ['a hung show', 'hangShow'],
+    ['a missing hole acknowledgement', 'holdHole'],
+  ])(
+    'a swap with %s falls back to <video> and the playlist advances',
+    async (_, fault) => {
+      const script: AppScript = fault === 'holdHole' ? { holdHole: ['b'] } : {};
+      const { manager, host, sent, hostCalls, timeline, complete, start } =
+        createSurfaceManager(['a', 'b'], script);
+      await start();
+      if (fault === 'hangShow') host.hangNextShow();
+
+      await complete('a');
+
+      expect(sent('b', 'video_refused').map((c) => c.args[1])).toEqual([
+        { reason: 'deadline' },
+      ]);
+      expect(hostCalls('close', 'b')).toHaveLength(1);
+      expect(timeline()).toContain('showWindow b');
+      expect(sent('b', 'play')).toHaveLength(1);
+      expect(
+        timeline().filter((line) => line === 'host onHole true')
+      ).toHaveLength(1);
+      expect(timeline()).toContain('removeWindow a');
+
+      // The playlist advances to a again.
+      await complete('b');
+      expect(sent('a', 'play').length).toBeGreaterThanOrEqual(2);
+
+      await manager.destroy();
+    }
+  );
+
+  test('a window shown before open_video keeps <video>', async () => {
+    const { manager, recording, host, apps, sent, hostCalls, timeline } =
+      createSurfaceManager(['a']);
+    // The app becomes ready before it asks, and asks only after the show.
+    const script = recording.hooks.onMessage;
+    recording.hooks.onMessage = (w, type, payload) => {
+      if (type === 'render') {
+        apps.presentationOf[w] = payload.presentation.id;
+        setTimeout(() => recording.receive(w, 'presentation_ready'), 0);
+        return;
+      }
+      if (script) script(w, type, payload);
+    };
+
+    await manager.load();
+    manager.show();
+    manager.play();
+    recording.receive(apps.windowOf('a'), 'open_video', {
+      url: 'https://cdn.test/a.mp4',
+      bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+      muted: false,
+    });
+    await settle();
+
+    expect(timeline()).toContain('showWindow a');
+    expect(hostCalls('openVideo')).toHaveLength(0);
+    expect(sent('a', 'video_refused').map((c) => c.args[1])).toEqual([
+      { reason: 'not_offered' },
+    ]);
+    expect(sent('a', 'play')).toHaveLength(1);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a window shown between video_opened and first_frame keeps <video>', async () => {
+    const { manager, recording, host, apps, sent, hostCalls, timeline } =
+      createSurfaceManager(['a'], { holdFirstFrame: ['a'] });
+    // The app sends ready without waiting for its first frame, so only the
+    // surface holds the window back, as at the player's first-screen cap.
+    const script = recording.hooks.onMessage;
+    recording.hooks.onMessage = (w, type, payload) => {
+      if (script) script(w, type, payload);
+      if (type === 'video_opened') {
+        setTimeout(() => recording.receive(w, 'presentation_ready'), 0);
+      }
+    };
+
+    const loaded = manager.load();
+    await settle();
+    expect(sent('a', 'video_opened')).toHaveLength(1);
+
+    manager.show();
+    await loaded;
+    manager.play();
+    await settle();
+
+    expect(timeline()).toContain('showWindow a');
+    expect(hostCalls('show')).toHaveLength(0);
+    expect(sent('a', 'video_refused').map((c) => c.args[1])).toEqual([
+      { reason: 'not_offered' },
+    ]);
+    expect(hostCalls('close', 'a')).toHaveLength(1);
+    expect(sent('a', 'play')).toHaveLength(1);
+    expect(hostCalls('onHole')).toHaveLength(0);
+    expect(host.violations).toEqual([]);
+
+    // A later first frame and ask change nothing.
+    recording.receive(apps.windowOf('a'), 'open_video', {
+      url: 'https://cdn.test/a.mp4',
+      bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+      muted: false,
+    });
+    await settle();
+    expect(hostCalls('openVideo')).toHaveLength(1);
+
+    await manager.destroy();
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('a second show() before the hole opens does nothing', async () => {
+    const { manager, recording, apps, sent, hostCalls, timeline } =
+      createSurfaceManager(['a'], { holdHole: ['a'] });
+    await manager.load();
+    manager.show();
+    manager.show();
+    manager.play();
+    await flush(20);
+    recording.receive(apps.windowOf('a'), 'video_hole_open');
+    await settle();
+
+    expect(hostCalls('show')).toHaveLength(1);
+    expect(sent('a', 'video_shown')).toHaveLength(1);
+    expect(
+      timeline().filter((line) => line === 'host onHole true')
+    ).toHaveLength(1);
+
+    await manager.destroy();
+  });
+
+  test('a one-video playlist replays by seeking, and destroy closes every surface', async () => {
+    const { manager, host, hostCalls, complete, start } = createSurfaceManager([
+      'a',
+    ]);
+    await start();
+
+    await complete('a');
+
+    expect(hostCalls('seek', 'a').map((c) => c.args[0])).toEqual([0]);
+    const plays = host.calls.filter(
+      (c) => c.method === 'seek' || c.method === 'play'
+    );
+    expect(plays.map((c) => c.method)).toEqual(['play', 'seek', 'play']);
+    expect(hostCalls('close')).toHaveLength(0);
+
+    await manager.destroy();
+    expect(host.liveIds()).toEqual([]);
+    expect(
+      host.calls.filter((c) => c.method === 'onHole').map((c) => c.args[0])
+    ).toEqual([true, false]);
+  });
+
+  test('a short clip replays once, then advances when the next is ready', async () => {
+    const { manager, host, apps, sent, hostCalls, complete, start } =
+      createSurfaceManager(['a', 'b'], { holdFirstFrame: ['b'] });
+    await start();
+
+    await complete('a');
+    expect(
+      hostCalls('seek', 'a')
+        .map((c) => c.method)
+        .concat(hostCalls('play', 'a').map((c) => c.method))
+    ).toEqual(['seek', 'play', 'play']);
+    expect(hostCalls('close', 'a')).toHaveLength(0);
+    expect(hostCalls('show', 'b')).toHaveLength(0);
+
+    apps.emitFirstFrame('b');
+    await settle();
+    await complete('a');
+
+    expect(hostCalls('show', 'b')).toHaveLength(1);
+    expect(sent('b', 'play')).toHaveLength(1);
+    expect(hostCalls('close', 'a')).toHaveLength(1);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a window whose surface closed before its turn swaps as today', async () => {
+    const {
+      manager,
+      recording,
+      host,
+      apps,
+      hostCalls,
+      timeline,
+      complete,
+      start,
+    } = createSurfaceManager(['a', 'b']);
+    await start();
+
+    recording.receive(apps.windowOf('b'), 'close_video');
+    await settle();
+    expect(hostCalls('close', 'b')).toHaveLength(1);
+
+    await complete('a');
+
+    expect(hostCalls('show', 'b')).toHaveLength(0);
+    expect(timeline()).toContain('showWindow b');
+    expect(timeline()).toContain('removeWindow a');
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('an error event is forwarded, then the surface closes and the frame background returns', async () => {
+    const { manager, host, apps, sent, hostCalls, timeline, start } =
+      createSurfaceManager(['a']);
+    await start();
+
+    host.emit(apps.surfaceOf('a'), { type: 'error', reason: 'decode' });
+    await settle();
+
+    expect(sent('a', 'video_event').map((c) => c.args[1])).toContainEqual({
+      type: 'error',
+      reason: 'decode',
+    });
+    expect(hostCalls('close', 'a')).toHaveLength(1);
+    expect(
+      host.calls.filter((c) => c.method === 'onHole').map((c) => c.args[0])
+    ).toEqual([true, false]);
+    expect(
+      timeline().filter((line) => line.startsWith('setWindowBackground'))
+    ).toEqual([
+      'setWindowBackground a transparent',
+      'setWindowBackground a #000000',
+    ]);
+
+    await manager.destroy();
+  });
+
+  test('stalled is forwarded and leaves the surface open', async () => {
+    const { manager, host, apps, sent, hostCalls, start } =
+      createSurfaceManager(['a']);
+    await start();
+
+    host.emit(apps.surfaceOf('a'), { type: 'stalled' });
+    host.emit(apps.surfaceOf('a'), { type: 'playing' });
+    await settle();
+
+    expect(
+      sent('a', 'video_event').map((c) => (c.args[1] as any).type)
+    ).toEqual(['first_frame', 'stalled', 'playing']);
+    expect(hostCalls('close', 'a')).toHaveLength(0);
+
+    await manager.destroy();
+  });
+});
+
+describe('a swap survives what runs during its wait', () => {
+  // A three-video playlist whose second app holds its hole closed, so the
+  // swap from a to b waits; its deadline outlasts the test's steps.
+  async function startWaitingSwap(images: string[] = []) {
+    const setup = createSurfaceManager(
+      ['a', 'b', 'c'],
+      { holdHole: ['b'], images },
+      undefined,
+      { closeWindowDelayMs: 5000 }
+    );
+    await setup.manager.load();
+    setup.manager.show();
+    setup.manager.play();
+    await settle();
+    const a = setup.apps.windowOf('a');
+    passTime();
+    setup.recording.receive(a, 'presentation_complete');
+    await settle();
+    const b = setup.apps.windowOf('b');
+    expect(setup.sent('b', 'video_shown')).toHaveLength(1);
+    const shown = (windowId: string) =>
+      setup.recording.calls.some(
+        (c) => c.method === 'showWindow' && c.windowId === windowId
+      );
+    const played = (windowId: string) =>
+      setup.recording.calls.filter(
+        (c) =>
+          c.method === 'sendMessageString' &&
+          c.args[0] === 'play' &&
+          c.windowId === windowId
+      ).length;
+    const removed = (windowId: string) =>
+      setup.recording.calls.some(
+        (c) => c.method === 'removeWindow' && c.windowId === windowId
+      );
+    return { ...setup, a, b, shown, played, removed };
+  }
+
+  test('a late complete from the outgoing window starts no second swap', async () => {
+    const { manager, recording, a, b, hostCalls, shown, played } =
+      await startWaitingSwap();
+
+    passTime();
+    recording.receive(a, 'presentation_complete');
+    await settle();
+
+    expect(hostCalls('show')).toHaveLength(2);
+    expect((manager as any).currentWindow).not.toBeNull();
+    expect(shown(b)).toBe(false);
+
+    recording.receive(b, 'video_hole_open');
+    await settle();
+    expect(shown(b)).toBe(true);
+    expect(played(b)).toBe(1);
+
+    await manager.destroy();
+  });
+
+  test('the next window is preloaded only once the swap has finished', async () => {
+    const { manager, recording, apps, b, shown, removed } =
+      await startWaitingSwap();
+
+    expect(apps.windowOf('c')).toBeUndefined();
+    expect((manager as any).nextWindow).toBeNull();
+
+    recording.receive(b, 'video_hole_open');
+    await settle();
+    expect(shown(b)).toBe(true);
+    expect(removed(apps.windowOf('a'))).toBe(true);
+    const c = apps.windowOf('c');
+    expect(c).toBeDefined();
+    expect((manager as any).nextWindow.isReady()).toBe(true);
+
+    await manager.destroy();
+  });
+
+  test('the incoming window failing while its show waits preloads the next at once, and the playlist moves on', async () => {
+    const { manager, recording, host, apps, a, b, shown, played, removed } =
+      await startWaitingSwap(['a']);
+
+    // b fails mid-swap: c preloads now and b restarts while it loads.
+    passTime();
+    recording.fail(b, new Error('crashed'));
+    await settle();
+    const c = apps.windowOf('c');
+    expect(c).toBeDefined();
+    expect((manager as any).nextWindow.isReady()).toBe(true);
+
+    // At b's next complete the manager moves on to c; b is never revealed.
+    passTime();
+    recording.receive(b, 'presentation_complete');
+    await settle();
+
+    expect(removed(b)).toBe(true);
+    expect(shown(b)).toBe(false);
+    expect(played(b)).toBe(0);
+    expect(shown(c)).toBe(true);
+    expect(played(c)).toBe(1);
+    expect(removed(a)).toBe(true);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+    await settle();
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('a publish during the wait preloads its next window at once, and the swap preloads none', async () => {
+    const { manager, recording, host, apps, b, shown, played, removed } =
+      await startWaitingSwap();
+    const created = () =>
+      recording.calls.filter((call) => call.method === 'createWindow').length;
+    const createdBefore = created();
+
+    // Not awaited here: the publish's own preload opens a surface, which
+    // waits for the outgoing close, which waits for b's hole.
+    const ruleEngine = manager.getRuleEngine() as RE.RuleEngine;
+    const published = manager.setRuleEngine(
+      new RE.RuleEngine(
+        'main',
+        new RE.State(
+          {
+            main: {
+              id: 'main',
+              mode: RE.PlaylistMode.Sequential,
+              items: [{ presentationId: 'b' }, { presentationId: 'a' }],
+            },
+          },
+          ruleEngine.state.presentations,
+          {}
+        )
+      )
+    );
+    await settle();
+    expect(created()).toBe(createdBefore + 1);
+    expect(removed(b)).toBe(false);
+
+    recording.receive(b, 'video_hole_open');
+    await settle();
+    await published;
+    expect(shown(b)).toBe(true);
+    expect(played(b)).toBe(1);
+    expect(created()).toBe(createdBefore + 1);
+    expect(apps.windowOf('c')).toBeUndefined();
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+    await settle();
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('a preview change during the wait preloads its next window at once, and the swap preloads none', async () => {
+    const { manager, recording, apps, b, shown, played } =
+      await startWaitingSwap();
+    const created = () =>
+      recording.calls.filter((call) => call.method === 'createWindow').length;
+    const createdBefore = created();
+
+    const ruleEngine = manager.getRuleEngine() as RE.RuleEngine;
+    jest.spyOn(ruleEngine, 'previewNext').mockReturnValue({
+      presentationId: 'a',
+      shouldInterrupt: false,
+      playlistId: 'main',
+      rule: null,
+    });
+    // Not awaited here, for the same reason as a publish.
+    const checked = (manager as any).checkPreviewAction();
+    await settle();
+    expect(created()).toBe(createdBefore + 1);
+
+    recording.receive(b, 'video_hole_open');
+    await settle();
+    await checked;
+    expect(shown(b)).toBe(true);
+    expect(played(b)).toBe(1);
+    expect(created()).toBe(createdBefore + 1);
+    expect(apps.windowOf('c')).toBeUndefined();
+
+    await manager.destroy();
+  });
+
+  test('destroy during the wait leaves no window and no surface', async () => {
+    const { manager, recording, host } = await startWaitingSwap();
+
+    await manager.destroy();
+    const callsAtDestroy = recording.calls.length;
+    await settle();
+
+    expect(
+      recording.calls
+        .slice(callsAtDestroy)
+        .filter((c) => c.method === 'createWindow')
+    ).toHaveLength(0);
+    expect(host.liveIds()).toEqual([]);
+    expect(recording.liveWindowIds()).toEqual([]);
+  });
+});
+
+describe('swap timing, on fake timers', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  // Lets promise callbacks run between fake timers.
+  const microtasks = async () => {
+    for (let i = 0; i < 50; i += 1) {
+      await Promise.resolve();
+    }
+  };
+
+  // A surface manager driven a millisecond at a time, whose host reports
+  // playing 25 ms after each play. Every call and app message is stamped
+  // with the millisecond it happened in.
+  async function startTimed(
+    presentationIds: string[],
+    script: AppScript,
+    hostOpts: Parameters<typeof createFakeSurfaceHost>[0] = {
+      playingAfterMs: 25,
+    },
+    showAfterRevealMs?: number
+  ) {
+    const setup = createSurfaceManager(
+      presentationIds,
+      script,
+      hostOpts,
+      {},
+      showAfterRevealMs
+    );
+    let clock = 0;
+    let mostLive = 0;
+    const stamps: Record<number, number> = {};
+    const stamp = () => {
+      setup.entries().forEach((e) => {
+        if (stamps[e.seq] === undefined) stamps[e.seq] = clock;
+      });
+      mostLive = Math.max(mostLive, setup.host.liveIds().length);
+    };
+    const tick = async (ms: number) => {
+      for (let i = 0; i < ms; i += 1) {
+        jest.advanceTimersByTime(1);
+        clock += 1;
+        await microtasks();
+        stamp();
+      }
+    };
+
+    const loading = setup.manager.load();
+    await tick(10);
+    await loading;
+    setup.manager.show();
+    setup.manager.play();
+    await tick(200);
+
+    // Completes the playing presentation; returns where its swap starts.
+    const completeAt = async (presentationId: string) => {
+      passTime();
+      const entries = setup.entries();
+      const mark = {
+        t0: clock,
+        fromSeq: entries.length ? entries[entries.length - 1].seq : 0,
+      };
+      setup.recording.receive(
+        setup.apps.windowOf(presentationId),
+        'presentation_complete'
+      );
+      await microtasks();
+      stamp();
+      return mark;
+    };
+    // Each line since the mark, after the milliseconds since its swap began.
+    const since = (mark: { t0: number; fromSeq: number }) => {
+      stamp();
+      return setup
+        .entries()
+        .filter((e) => e.seq > mark.fromSeq)
+        .map((e) => `${stamps[e.seq] - mark.t0} ${e.text}`);
+    };
+
+    // Stamps what promise callbacks did since the last millisecond.
+    const settleNow = async () => {
+      await microtasks();
+      stamp();
+    };
+
+    return {
+      ...setup,
+      tick,
+      settleNow,
+      completeAt,
+      since,
+      mostLive: () => mostLive,
+    };
+  }
+
+  // The swap's steps: surface calls, the frames shown, hidden, created and
+  // removed, and the messages that start, show and close a surface.
+  const isTimedStep = (line: string) =>
+    / (host (?!setBounds)|showWindow|hideWindow|removeWindow|createWindow|setWindowBackground)/.test(
+      line
+    ) ||
+    / sendMessageString \S+ (play|video_shown|video_closing|video_refused)$/.test(
+      line
+    ) ||
+    / app \S+ video_hole_open$/.test(line);
+
+  test('an app that opened its hole while hidden plays, is revealed on playing with the outgoing hidden, then is shown and unmuted', async () => {
+    const {
+      manager,
+      recording,
+      host,
+      apps,
+      tick,
+      completeAt,
+      since,
+      mostLive,
+    } = await startTimed(['a', 'b'], { preopenHole: ['a', 'b'] });
+
+    // The reveal and the outgoing hide land in one task.
+    const a = apps.windowOf('a');
+    const b = apps.windowOf('b');
+    let hiddenInRevealTask: boolean | null = null;
+    const showWindow = recording.renderer.showWindow;
+    recording.renderer.showWindow = (windowId: string, isFocused: boolean) => {
+      showWindow(windowId, isFocused);
+      if (windowId === b) {
+        Promise.resolve().then(() => {
+          hiddenInRevealTask = recording.calls.some(
+            (c) => c.method === 'hideWindow' && c.windowId === a
+          );
+        });
+      }
+    };
+
+    const mark = await completeAt('a');
+    await tick(300);
+
+    expect(since(mark).filter(isTimedStep)).toEqual([
+      '0 host setMuted a true',
+      '0 host play b',
+      '25 host onHole true',
+      '25 setWindowBackground b transparent',
+      '25 showWindow b',
+      '25 hideWindow a',
+      '25 sendMessageString b play',
+      '105 host show b',
+      '105 host setMuted b false',
+      '105 sendMessageString b video_shown',
+      '105 sendMessageString a video_closing',
+      '105 host close a',
+      '105 host onHole false',
+      '105 removeWindow a',
+      '105 createWindow a2',
+      '106 app b video_hole_open',
+      '106 host openVideo a2',
+      '107 app a2 video_hole_open',
+    ]);
+    expect(hiddenInRevealTask).toBe(true);
+    expect(mostLive()).toBeLessThanOrEqual(2);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('an app that has not opened its hole keeps the show, hole, reveal, play order', async () => {
+    const { manager, host, tick, completeAt, since, mostLive } =
+      await startTimed(['a', 'b'], {});
+
+    const mark = await completeAt('a');
+    await tick(300);
+
+    expect(since(mark).filter(isTimedStep)).toEqual([
+      '0 host setMuted a true',
+      '0 host show b',
+      '0 host setMuted b false',
+      '0 sendMessageString b video_shown',
+      '1 app b video_hole_open',
+      '1 host onHole true',
+      '1 setWindowBackground b transparent',
+      '1 showWindow b',
+      '1 hideWindow a',
+      '1 sendMessageString b play',
+      '1 host play b',
+      '2 sendMessageString a video_closing',
+      '2 host close a',
+      '2 host onHole false',
+      '2 removeWindow a',
+      '2 createWindow a2',
+      '3 host openVideo a2',
+    ]);
+    expect(mostLive()).toBeLessThanOrEqual(2);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a surface that never reports playing is revealed at the show deadline', async () => {
+    const { manager, host, warn, tick, completeAt, since } = await startTimed(
+      ['a', 'b'],
+      { preopenHole: ['b'] },
+      {}
+    );
+
+    const mark = await completeAt('a');
+    await tick(300);
+
+    const steps = since(mark).filter(isTimedStep);
+    expect(steps).toContain('0 host play b');
+    expect(steps).toContain(`${CLOSE_WINDOW_DELAY_MS} showWindow b`);
+    expect(steps).toContain(`${CLOSE_WINDOW_DELAY_MS + 80} host show b`);
+    expect(
+      warn.mock.calls.filter(([message]) => /No 'playing'/.test(message))
+    ).toHaveLength(1);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('surfaces.showAfterRevealMs sets the show after the reveal', async () => {
+    const { manager, tick, completeAt, since } = await startTimed(
+      ['a', 'b'],
+      { preopenHole: ['b'] },
+      undefined,
+      30
+    );
+
+    const mark = await completeAt('a');
+    await tick(300);
+
+    const steps = since(mark).filter(isTimedStep);
+    expect(steps).toContain('25 showWindow b');
+    expect(steps).toContain('55 host show b');
+    expect(steps).toContain('55 host setMuted b false');
+
+    await manager.destroy();
+  });
+
+  test('over a playlist of swaps, two surfaces never sound at once and never more than two are live', async () => {
+    const { manager, host, tick, completeAt, hostCalls, mostLive } =
+      await startTimed(['a', 'b', 'c'], { preopenHole: ['a', 'b', 'c'] });
+
+    for (const id of ['a', 'b', 'c', 'a']) {
+      await completeAt(id);
+      await tick(1000);
+    }
+
+    expect(hostCalls('show')).toHaveLength(5);
+    expect(mostLive()).toBe(2);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('a publish while the next preload waits for the swap preloads at once, and once', async () => {
+    const { manager, apps, tick, settleNow, completeAt, since, host, sent } =
+      await startTimed(['a', 'b', 'c'], { preopenHole: ['a', 'b', 'c'] });
+
+    const mark = await completeAt('a');
+    await tick(10);
+    const ruleEngine = manager.getRuleEngine() as RE.RuleEngine;
+    manager.setRuleEngine(
+      new RE.RuleEngine(
+        'main',
+        new RE.State(
+          {
+            main: {
+              id: 'main',
+              mode: RE.PlaylistMode.Sequential,
+              items: [{ presentationId: 'a' }, { presentationId: 'c' }],
+            },
+          },
+          ruleEngine.state.presentations,
+          {}
+        )
+      )
+    );
+    await settleNow();
+    await tick(300);
+
+    // The publish's window opens its surface once the outgoing has closed.
+    const steps = since(mark).filter(isTimedStep);
+    expect(steps.filter((line) => / createWindow /.test(line))).toEqual([
+      '10 createWindow a2',
+    ]);
+    expect(steps).toContain('105 host close a');
+    expect(steps).toContain('105 host openVideo a2');
+    expect(sent('b', 'video_shown')).toHaveLength(1);
+    expect(apps.windowOf('a')).not.toBe(undefined);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a show that hangs after the reveal falls back to <video> in the revealed frame', async () => {
+    const { manager, host, tick, completeAt, since, sent, hostCalls } =
+      await startTimed(['a', 'b'], { preopenHole: ['b'] });
+    host.hangNextShow();
+
+    const mark = await completeAt('a');
+    await tick(300);
+
+    expect(sent('b', 'video_refused').map((c) => c.args[1])).toEqual([
+      { reason: 'deadline' },
+    ]);
+    const deadlineAt = 105 + CLOSE_WINDOW_DELAY_MS;
+    const steps = since(mark).filter(isTimedStep);
+    expect(steps).toContain('105 host show b');
+    expect(steps).toContain(`${deadlineAt} host close b`);
+    expect(steps).toContain(`${deadlineAt} setWindowBackground b #000000`);
+    expect(steps.filter((line) => / showWindow b$/.test(line))).toEqual([
+      '25 showWindow b',
+    ]);
+    expect(sent('b', 'play')).toHaveLength(1);
+    expect(sent('b', 'video_shown')).toHaveLength(0);
+    expect(hostCalls('setMuted', 'b')).toHaveLength(0);
+    expect(steps).toContain(`${deadlineAt} removeWindow a`);
+    expect(host.violations).toEqual([]);
+
+    await manager.destroy();
+  });
+
+  test('a swap of two still images in a surface manager preloads in the swap and removes the outgoing at its paint', async () => {
+    const { manager, tick, completeAt, since } = await startTimed(['a', 'b'], {
+      images: ['a', 'b'],
+    });
+
+    const mark = await completeAt('a');
+    await tick(100);
+
+    expect(since(mark).filter(isTimedStep)).toEqual([
+      '0 showWindow b',
+      '0 sendMessageString b play',
+      '0 createWindow a2',
+      '1 removeWindow a',
+    ]);
+
+    await manager.destroy();
+  });
+
+  test('a manager with no surface host preloads in the swap and removes the outgoing at its paint', async () => {
+    const { manager, recording } = createManager({
+      presentationIds: ['a', 'b'],
+    });
+    scriptImageApp(recording);
+    const tick = async (ms: number) => {
+      for (let i = 0; i < ms; i += 1) {
+        jest.advanceTimersByTime(1);
+        await microtasks();
+      }
+    };
+
+    const loading = manager.load();
+    await tick(10);
+    await loading;
+    manager.show();
+    manager.play();
+    await tick(10);
+
+    const before = recording.calls.length;
+    passTime();
+    recording.receive(lastShown(recording), 'presentation_complete');
+    await microtasks();
+    const inSwapTask = describeCalls(recording).slice(before);
+    await tick(5);
+
+    // w1 is the incoming window, preloaded before w2 at load.
+    expect(inSwapTask).toEqual([
+      'showWindow w1',
+      'unMuteWindow w1',
+      'muteWindow w2',
+      'sendMessageString w1 play',
+      'createWindow w3',
+      'muteWindow w3',
+      'loadWindow w3',
+      'sendMessageString w3 render',
+    ]);
+    expect(describeCalls(recording).slice(before)).toContain('removeWindow w2');
+
+    await manager.destroy();
+  });
+});