@raydiant/playlist-window-manager 0.29.1 → 0.29.2

package/build/PlaylistWindowManager.js

@@ -904,7 +904,7 @@ var PlaylistWindowManager = /** @class */ (function (_super) {
     };
     PlaylistWindowManager.prototype.swapWindows = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var nextPreviewPresentationId, preview, result, nextPresentation, shouldPreload, closeWindowPromise;
+            var nextPreviewPresentationId, preview, result, nextPresentation, shouldPreload, closeWindowPromise, windowToClose_1, incomingWindow_1, closeWindowDelayMs_1;
             var _this = this;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -943,32 +943,42 @@ var PlaylistWindowManager = /** @class */ (function (_super) {
                         }
                         if (!this.currentWindow) return [3 /*break*/, 3];
                         if (!(this.options.closeWindowDelayMs !== undefined)) return [3 /*break*/, 1];
-                        // Don't await here because this will cause a slight delay when playing the next window.
-                        // Instead we want to wait for window close at the end of this method.
-                        closeWindowPromise = new Promise(function (resolve) {
-                            // Capture the current window reference to close because this.currentWindow will be
-                            // set to the next window before the timeout fires.
-                            var windowToClose = _this.currentWindow;
-                            setTimeout(function () { return __awaiter(_this, void 0, void 0, function () {
-                                return __generator(this, function (_a) {
-                                    switch (_a.label) {
-                                        case 0:
-                                            if (!windowToClose) return [3 /*break*/, 2];
-                                            // We can't use this.removeCurrentWindow because the currentWindow reference has already
-                                            // changed by the time the timeout fires.
-                                            return [4 /*yield*/, windowToClose.remove()];
-                                        case 1:
-                                            // We can't use this.removeCurrentWindow because the currentWindow reference has already
-                                            // changed by the time the timeout fires.
-                                            _a.sent();
-                                            _a.label = 2;
-                                        case 2:
-                                            resolve(undefined);
-                                            return [2 /*return*/];
-                                    }
-                                });
-                            }); }, _this.options.closeWindowDelayMs);
-                        });
+                        windowToClose_1 = this.currentWindow;
+                        incomingWindow_1 = this.nextWindow;
+                        closeWindowDelayMs_1 = this.options.closeWindowDelayMs;
+                        // The outgoing window stays on screen only as a visual backdrop from
+                        // here on: stop delivering its events (a late complete or error must
+                        // not end the incoming presentation) and mute it so audio does not
+                        // bleed into the incoming presentation during the overlap.
+                        windowToClose_1.detachCallbacks();
+                        windowToClose_1.mute();
+                        closeWindowPromise = (function () { return __awaiter(_this, void 0, void 0, function () {
+                            return __generator(this, function (_a) {
+                                switch (_a.label) {
+                                    case 0:
+                                        if (!incomingWindow_1) return [3 /*break*/, 2];
+                                        return [4 /*yield*/, incomingWindow_1.waitForFirstPaint(closeWindowDelayMs_1)];
+                                    case 1:
+                                        _a.sent();
+                                        return [3 /*break*/, 4];
+                                    case 2: return [4 /*yield*/, new Promise(function (resolve) {
+                                            return setTimeout(resolve, closeWindowDelayMs_1);
+                                        })];
+                                    case 3:
+                                        _a.sent();
+                                        _a.label = 4;
+                                    case 4: 
+                                    // We can't use this.removeCurrentWindow because the currentWindow
+                                    // reference has already changed by the time the wait finishes.
+                                    return [4 /*yield*/, windowToClose_1.remove()];
+                                    case 5:
+                                        // We can't use this.removeCurrentWindow because the currentWindow
+                                        // reference has already changed by the time the wait finishes.
+                                        _a.sent();
+                                        return [2 /*return*/];
+                                }
+                            });
+                        }); })();
                         return [3 /*break*/, 3];
                     case 1:
                         this.currentWindow.hide();

package/build/PresentationWindow.d.ts

@@ -54,6 +54,8 @@ export default class PresentationWindow {
     private disableInterruptLockCallback;
     private analyticsEventCallback;
     private chargeRequestCallback;
+    private didPaintSinceLastPlay;
+    private firstPaintResolvers;
     private builderState;
     private presentation;
     private playlistWindowManagerState;
@@ -81,6 +83,10 @@ export default class PresentationWindow {
     pause(): void;
     resume(): void;
     reset(): void;
+    waitForFirstPaint(timeoutMs: number): Promise<void>;
+    detachCallbacks(): void;
+    mute(): void;
+    private resolveFirstPaintWaiters;
     onComplete(callback: (() => void) | null): void;
     onError(callback: ((err: Error) => void) | null): void;
     onEnableInterruptLock(callback: (() => void) | null): void;

package/build/PresentationWindow.js

@@ -81,7 +81,7 @@ var PlaylistWindowManager_1 = __importDefault(require("./PlaylistWindowManager")
 var WindowTimeoutError_1 = __importDefault(require("./WindowTimeoutError"));
 var WindowLoadError_1 = __importDefault(require("./WindowLoadError"));
 // TODO: Automatically inject latest version when building in CI.
-var defaultAppRendererUrl = 'https://apps.raydiant.com/3.1.0/index.html';
+var defaultAppRendererUrl = 'https://apps.raydiant.com/3.1.1/index.html';
 var isValidNumber = function (value) {
     return typeof value === 'number' && !isNaN(value);
 };
@@ -140,6 +140,8 @@ var PresentationWindow = /** @class */ (function () {
         this.disableInterruptLockCallback = null;
         this.analyticsEventCallback = null;
         this.chargeRequestCallback = null;
+        this.didPaintSinceLastPlay = false;
+        this.firstPaintResolvers = [];
         this.forceMute = false;
         this.error = null;
         this.workerState = {};
@@ -382,6 +384,11 @@ var PresentationWindow = /** @class */ (function () {
                     this.logInfo("Received 'presentation_complete' from window '".concat(windowId, "'"));
                     this.handleComplete();
                 }
+                if (type === 'first_painted') {
+                    this.logDebug("Received 'first_painted' from window '".concat(windowId, "'"));
+                    this.didPaintSinceLastPlay = true;
+                    this.resolveFirstPaintWaiters();
+                }
                 if (type === 'enable_interrupt_lock') {
                     this.logInfo("Received 'enable_interrupt_lock' from window '".concat(windowId, "'"));
                     this.enableInteruptLock();
@@ -510,6 +517,9 @@ var PresentationWindow = /** @class */ (function () {
                             clearTimeout(this.configurableDurationTimeout);
                             this.configurableDurationTimeout = null;
                         }
+                        // Release anything waiting on a paint signal so callers never hang on a
+                        // window that is going away.
+                        this.resolveFirstPaintWaiters();
                         // Remove any child window managers.
                         Object.values(this.windowManagers).forEach(function (wm) {
                             wm.destroy();
@@ -540,6 +550,9 @@ var PresentationWindow = /** @class */ (function () {
     PresentationWindow.prototype.play = function () {
         var _this = this;
         var _a = this.options, applicationVersion = _a.applicationVersion, presentation = _a.presentation;
+        // 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) {
             var durationMs = Math.max(presentation.duration * 1000, 5000);
             if (this.configurableDurationTimeout) {
@@ -579,6 +592,55 @@ var PresentationWindow = /** @class */ (function () {
     PresentationWindow.prototype.reset = function () {
         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.
+    PresentationWindow.prototype.waitForFirstPaint = function (timeoutMs) {
+        var _this = this;
+        if (this.didPaintSinceLastPlay) {
+            return Promise.resolve();
+        }
+        return new Promise(function (resolve) {
+            var settled = false;
+            var settle = function () {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                var index = _this.firstPaintResolvers.indexOf(settle);
+                if (index !== -1) {
+                    _this.firstPaintResolvers.splice(index, 1);
+                }
+                resolve();
+            };
+            var 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.
+    PresentationWindow.prototype.detachCallbacks = function () {
+        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.
+    PresentationWindow.prototype.mute = function () {
+        var _a = this.options, windowId = _a.windowId, renderer = _a.renderer;
+        renderer.muteWindow(windowId);
+    };
+    PresentationWindow.prototype.resolveFirstPaintWaiters = function () {
+        var resolvers = this.firstPaintResolvers;
+        this.firstPaintResolvers = [];
+        resolvers.forEach(function (resolve) { return resolve(); });
+    };
     PresentationWindow.prototype.onComplete = function (callback) {
         this.completeCallback = callback;
     };

package/build/PresentationWindow.test.js

@@ -431,3 +431,189 @@ describe('interrupt locks', function () {
     }); });
 });
 // TODO: Backfill tests for all legacy and embedded apps.
+describe('waitForFirstPaint', function () {
+    // The default (non-embedded) window resolves load() only after the app
+    // reports ready, so drive the handshake through the mock renderer.
+    var loadPresentationWindow = function (testRenderer, window) { return __awaiter(void 0, void 0, void 0, function () {
+        var loadPromise;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    loadPromise = window.load();
+                    return [4 /*yield*/, delay(0)];
+                case 1:
+                    _a.sent();
+                    testRenderer.runReceiveMessageCallback('loaded', undefined);
+                    testRenderer.runReceiveMessageCallback('presentation_ready', undefined);
+                    return [4 /*yield*/, loadPromise];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); };
+    test('resolves when the window reports first_painted', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window, resolved, wait;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-first-paint',
+                        renderer: testRenderer,
+                    });
+                    return [4 /*yield*/, loadPresentationWindow(testRenderer, window)];
+                case 1:
+                    _a.sent();
+                    resolved = false;
+                    wait = window.waitForFirstPaint(5000).then(function () {
+                        resolved = true;
+                    });
+                    return [4 /*yield*/, delay(10)];
+                case 2:
+                    _a.sent();
+                    expect(resolved).toBe(false);
+                    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+                    return [4 /*yield*/, wait];
+                case 3:
+                    _a.sent();
+                    expect(resolved).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('falls back to the timeout when no paint signal arrives', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-first-paint-timeout',
+                        renderer: testRenderer,
+                    });
+                    return [4 /*yield*/, loadPresentationWindow(testRenderer, window)];
+                case 1:
+                    _a.sent();
+                    // Resolves via the timeout even though first_painted never arrives.
+                    return [4 /*yield*/, window.waitForFirstPaint(20)];
+                case 2:
+                    // Resolves via the timeout even though first_painted never arrives.
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('resolves immediately when the window already painted since the last play', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window, resolved;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-first-paint-immediate',
+                        renderer: testRenderer,
+                    });
+                    return [4 /*yield*/, loadPresentationWindow(testRenderer, window)];
+                case 1:
+                    _a.sent();
+                    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+                    resolved = false;
+                    window.waitForFirstPaint(5000).then(function () {
+                        resolved = true;
+                    });
+                    return [4 /*yield*/, Promise.resolve()];
+                case 2:
+                    _a.sent();
+                    expect(resolved).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('play starts a new paint cycle', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window, resolved, wait;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-first-paint-replay',
+                        renderer: testRenderer,
+                    });
+                    return [4 /*yield*/, loadPresentationWindow(testRenderer, window)];
+                case 1:
+                    _a.sent();
+                    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+                    window.play();
+                    resolved = false;
+                    wait = window.waitForFirstPaint(5000).then(function () {
+                        resolved = true;
+                    });
+                    return [4 /*yield*/, delay(10)];
+                case 2:
+                    _a.sent();
+                    expect(resolved).toBe(false);
+                    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+                    return [4 /*yield*/, wait];
+                case 3:
+                    _a.sent();
+                    expect(resolved).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    test('resolves pending waiters when the window is removed', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window, wait;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-first-paint-removed',
+                        renderer: testRenderer,
+                    });
+                    return [4 /*yield*/, loadPresentationWindow(testRenderer, window)];
+                case 1:
+                    _a.sent();
+                    wait = window.waitForFirstPaint(5000);
+                    return [4 /*yield*/, window.remove()];
+                case 2:
+                    _a.sent();
+                    return [4 /*yield*/, wait];
+                case 3:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});
+describe('detachCallbacks', function () {
+    test('stops delivering events to the window manager', function () { return __awaiter(void 0, void 0, void 0, function () {
+        var testRenderer, window, loadPromise, onComplete;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    testRenderer = (0, testUtils_1.createRenderer)();
+                    window = (0, testUtils_1.createPresentationWindow)({
+                        windowId: 'test-detach',
+                        renderer: testRenderer,
+                    });
+                    loadPromise = window.load();
+                    return [4 /*yield*/, delay(0)];
+                case 1:
+                    _a.sent();
+                    testRenderer.runReceiveMessageCallback('loaded', undefined);
+                    testRenderer.runReceiveMessageCallback('presentation_ready', undefined);
+                    return [4 /*yield*/, loadPromise];
+                case 2:
+                    _a.sent();
+                    onComplete = jest.fn();
+                    window.onComplete(onComplete);
+                    window.detachCallbacks();
+                    testRenderer.runReceiveMessageCallback('presentation_complete', undefined);
+                    expect(onComplete).not.toHaveBeenCalled();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raydiant/playlist-window-manager",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "Window manager for playlist playback.",
   "main": "build/index.js",
   "scripts": {

package/src/PlaylistWindowManager.ts

@@ -754,21 +754,38 @@ export default class PlaylistWindowManager extends EventEmitter {
     let closeWindowPromise;
     if (this.currentWindow) {
       if (this.options.closeWindowDelayMs !== undefined) {
+        // Keep the outgoing window on screen until the incoming one reports
+        // its first painted frame. A newly shown window still needs a few
+        // frames to rasterize, and removing the outgoing window before that
+        // exposes the transparent window stack (a white flash on device).
+        // closeWindowDelayMs is the ceiling for windows that never report a
+        // paint (embedded apps, error states).
         // Don't await here because this will cause a slight delay when playing the next window.
         // Instead we want to wait for window close at the end of this method.
-        closeWindowPromise = new Promise((resolve) => {
-          // Capture the current window reference to close because this.currentWindow will be
-          // set to the next window before the timeout fires.
-          const windowToClose = this.currentWindow;
-          setTimeout(async () => {
-            if (windowToClose) {
-              // We can't use this.removeCurrentWindow because the currentWindow reference has already
-              // changed by the time the timeout fires.
-              await windowToClose.remove();
-            }
-            resolve(undefined);
-          }, this.options.closeWindowDelayMs);
-        });
+        // Capture both window references because this.currentWindow and
+        // this.nextWindow change before the wait finishes.
+        const windowToClose = this.currentWindow;
+        const incomingWindow = this.nextWindow;
+        const closeWindowDelayMs = this.options.closeWindowDelayMs;
+
+        // The outgoing window stays on screen only as a visual backdrop from
+        // here on: stop delivering its events (a late complete or error must
+        // not end the incoming presentation) and mute it so audio does not
+        // bleed into the incoming presentation during the overlap.
+        windowToClose.detachCallbacks();
+        windowToClose.mute();
+        closeWindowPromise = (async () => {
+          if (incomingWindow) {
+            await incomingWindow.waitForFirstPaint(closeWindowDelayMs);
+          } else {
+            await new Promise((resolve) =>
+              setTimeout(resolve, closeWindowDelayMs)
+            );
+          }
+          // We can't use this.removeCurrentWindow because the currentWindow
+          // reference has already changed by the time the wait finishes.
+          await windowToClose.remove();
+        })();
       } else {
         this.currentWindow.hide();
         await this.removeCurrentWindow();

package/src/PresentationWindow.test.ts

@@ -454,3 +454,127 @@ describe('interrupt locks', () => {
 });
 
 // TODO: Backfill tests for all legacy and embedded apps.
+
+describe('waitForFirstPaint', () => {
+  // The default (non-embedded) window resolves load() only after the app
+  // reports ready, so drive the handshake through the mock renderer.
+  const loadPresentationWindow = async (
+    testRenderer: ReturnType<typeof createRenderer>,
+    window: ReturnType<typeof createPresentationWindow>
+  ) => {
+    const loadPromise = window.load();
+    await delay(0);
+    testRenderer.runReceiveMessageCallback('loaded', undefined);
+    testRenderer.runReceiveMessageCallback('presentation_ready', undefined);
+    await loadPromise;
+  };
+
+  test('resolves when the window reports first_painted', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-first-paint',
+      renderer: testRenderer,
+    });
+    await loadPresentationWindow(testRenderer, window);
+
+    let resolved = false;
+    const wait = window.waitForFirstPaint(5000).then(() => {
+      resolved = true;
+    });
+
+    await delay(10);
+    expect(resolved).toBe(false);
+
+    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+    await wait;
+    expect(resolved).toBe(true);
+  });
+
+  test('falls back to the timeout when no paint signal arrives', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-first-paint-timeout',
+      renderer: testRenderer,
+    });
+    await loadPresentationWindow(testRenderer, window);
+
+    // Resolves via the timeout even though first_painted never arrives.
+    await window.waitForFirstPaint(20);
+  });
+
+  test('resolves immediately when the window already painted since the last play', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-first-paint-immediate',
+      renderer: testRenderer,
+    });
+    await loadPresentationWindow(testRenderer, window);
+
+    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+
+    let resolved = false;
+    window.waitForFirstPaint(5000).then(() => {
+      resolved = true;
+    });
+    await Promise.resolve();
+    expect(resolved).toBe(true);
+  });
+
+  test('play starts a new paint cycle', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-first-paint-replay',
+      renderer: testRenderer,
+    });
+    await loadPresentationWindow(testRenderer, window);
+
+    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+    window.play();
+
+    let resolved = false;
+    const wait = window.waitForFirstPaint(5000).then(() => {
+      resolved = true;
+    });
+    await delay(10);
+    expect(resolved).toBe(false);
+
+    testRenderer.runReceiveMessageCallback('first_painted', undefined);
+    await wait;
+    expect(resolved).toBe(true);
+  });
+
+  test('resolves pending waiters when the window is removed', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-first-paint-removed',
+      renderer: testRenderer,
+    });
+    await loadPresentationWindow(testRenderer, window);
+
+    const wait = window.waitForFirstPaint(5000);
+    await window.remove();
+    await wait;
+  });
+});
+
+describe('detachCallbacks', () => {
+  test('stops delivering events to the window manager', async () => {
+    const testRenderer = createRenderer();
+    const window = createPresentationWindow({
+      windowId: 'test-detach',
+      renderer: testRenderer,
+    });
+    const loadPromise = window.load();
+    await delay(0);
+    testRenderer.runReceiveMessageCallback('loaded', undefined);
+    testRenderer.runReceiveMessageCallback('presentation_ready', undefined);
+    await loadPromise;
+
+    const onComplete = jest.fn();
+    window.onComplete(onComplete);
+    window.detachCallbacks();
+
+    testRenderer.runReceiveMessageCallback('presentation_complete', undefined);
+    expect(onComplete).not.toHaveBeenCalled();
+  });
+});

package/src/PresentationWindow.ts

@@ -63,7 +63,7 @@ export interface PresentationWindowOptions {
 }
 
 // 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';
 
 const isValidNumber = (value: any) =>
   typeof value === 'number' && !isNaN(value);
@@ -130,6 +130,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;
@@ -241,6 +243,10 @@ 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();
+
     // Remove any child window managers.
     Object.values(this.windowManagers).forEach((wm) => {
       wm.destroy();
@@ -269,6 +275,10 @@ export default class PresentationWindow {
   public play(): void {
     const { applicationVersion, presentation } = this.options;
 
+    // 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) {
@@ -314,6 +324,57 @@ 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);
+  }
+
+  private resolveFirstPaintWaiters() {
+    const resolvers = this.firstPaintResolvers;
+    this.firstPaintResolvers = [];
+    resolvers.forEach((resolve) => resolve());
+  }
+
   public onComplete(callback: (() => void) | null) {
     this.completeCallback = callback;
   }
@@ -1300,6 +1361,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}'`