@xiboplayer/renderer 0.6.5 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/renderer",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "RendererLite - Fast, efficient XLF layout rendering engine",
   "type": "module",
   "main": "./src/index.js",
@@ -13,9 +13,9 @@
   "dependencies": {
     "nanoevents": "^9.1.0",
     "pdfjs-dist": "^4.10.38",
-    "@xiboplayer/cache": "0.6.5",
-    "@xiboplayer/schedule": "0.6.5",
-    "@xiboplayer/utils": "0.6.5"
+    "@xiboplayer/cache": "0.6.7",
+    "@xiboplayer/schedule": "0.6.7",
+    "@xiboplayer/utils": "0.6.7"
   },
   "devDependencies": {
     "vitest": "^2.0.0",

package/src/index.d.ts

@@ -38,6 +38,7 @@ export class RendererLite {
   scaleFactor: number;
   offsetX: number;
   offsetY: number;
+  _resizeSuppressed: boolean;
 
   on(event: string, callback: (...args: any[]) => void): () => void;
   emit(event: string, ...args: any[]): void;

package/src/layout.js

@@ -4,7 +4,7 @@
  */
 
 import { cacheWidgetHtml } from '@xiboplayer/cache';
-import { createLogger, PLAYER_API } from '@xiboplayer/utils';
+import { createLogger, isDebug, PLAYER_API } from '@xiboplayer/utils';
 
 const log = createLogger('Layout');
 
@@ -754,6 +754,7 @@ ${mediaJS}
             border-radius: 4px;
             font-size: 14px;
             z-index: 10;
+            display: ${isDebug() ? 'block' : 'none'};
           \`;
           container.appendChild(pageIndicator);
 

package/src/renderer-lite.js

@@ -212,6 +212,7 @@ export class RendererLite {
     this.regions = new Map(); // regionId => { element, widgets, currentIndex, timer }
     this.layoutTimer = null;
     this.layoutEndEmitted = false; // Prevents double layoutEnd on stop after timer
+    this._deferredTimerLayoutId = null; // Set when timer is deferred for dynamic layouts
     this._paused = false;
     this._layoutTimerStartedAt = null;  // Date.now() when layout timer started
     this._layoutTimerDurationMs = null; // Total layout duration in ms
@@ -235,6 +236,9 @@ export class RendererLite {
     // Sub-playlist cycle state (round-robin per parentWidgetId group)
     this._subPlaylistCycleIndex = new Map();
 
+    // Widget lifecycle tracking — ensures symmetric start/stop
+    this._startedWidgets = new Set(); // "regionId:widgetIndex" keys
+
     // Layout preload pool (2-layout pool for instant transitions)
     this.layoutPool = new LayoutPool(2);
     this.preloadTimer = null;
@@ -262,9 +266,11 @@ export class RendererLite {
     this.container.style.overflow = 'hidden';
 
     // Watch for container resize to rescale layout (debounced to avoid spam)
+    this._resizeSuppressed = false;
     if (typeof ResizeObserver !== 'undefined') {
       let resizeTimer = null;
       this.resizeObserver = new ResizeObserver(() => {
+        if (this._resizeSuppressed) return;
         if (resizeTimer) clearTimeout(resizeTimer);
         resizeTimer = setTimeout(() => this.rescaleRegions(), 150);
       });
@@ -500,9 +506,10 @@ export class RendererLite {
     // Calculate layout duration if not specified (duration=0)
     // Uses shared parseLayoutDuration() — single source of truth for XLF-based duration calc
     if (layout.duration === 0) {
-      const { duration } = parseLayoutDuration(xlfXml);
+      const { duration, isDynamic } = parseLayoutDuration(xlfXml);
       layout.duration = duration;
-      this.log.info(`Calculated layout duration: ${layout.duration}s (not specified in XLF)`);
+      layout.isDynamic = isDynamic;
+      this.log.info(`Calculated layout duration: ${layout.duration}s (not specified in XLF)${isDynamic ? ' [dynamic — has useDuration=0 video]' : ''}`);
     }
 
     return layout;
@@ -703,12 +710,29 @@ export class RendererLite {
       this.currentLayout.duration = maxRegionDuration;
 
       this.log.info(`Layout duration updated: ${oldDuration}s → ${maxRegionDuration}s (based on video metadata)`);
-      this.emit('layoutDurationUpdated', this.currentLayoutId, maxRegionDuration);
+      const final_ = !this._hasUnprobedVideos();
+      this.emit('layoutDurationUpdated', this.currentLayoutId, maxRegionDuration, final_);
 
-      // Reset layout timer with REMAINING time — not full duration.
-      // If startLayoutTimerWhenReady() hasn't fired yet (still waiting for widgets),
-      // it will pick up the updated duration when it starts the timer.
-      if (this.layoutTimer) {
+      // Deferred timer: video metadata arrived, start the timer now
+      if (this._deferredTimerLayoutId === this.currentLayoutId && !this.layoutTimer) {
+        if (this._hasUnprobedVideos()) {
+          this.log.info(`Layout duration updated to ${maxRegionDuration}s but still has unprobed videos — keeping timer deferred`);
+        } else {
+          const elapsed = Date.now() - (this._layoutTimerStartedAt || Date.now());
+          const remainingMs = Math.max(1000, maxRegionDuration * 1000 - elapsed);
+          this._deferredTimerLayoutId = null;
+          this._layoutTimerDurationMs = remainingMs;
+          this.layoutTimer = setTimeout(() => {
+            this.log.info(`Layout ${this.currentLayoutId} duration expired (${this.currentLayout.duration}s)`);
+            if (this.currentLayoutId) {
+              this.layoutEndEmitted = true;
+              this.emit('layoutEnd', this.currentLayoutId);
+            }
+          }, remainingMs);
+          this.log.info(`All video durations resolved — deferred timer started: ${(remainingMs / 1000).toFixed(1)}s remaining (waited ${(elapsed / 1000).toFixed(1)}s for metadata)`);
+        }
+      } else if (this.layoutTimer) {
+        // Reset layout timer with REMAINING time — not full duration.
         clearTimeout(this.layoutTimer);
 
         const elapsed = Date.now() - (this._layoutTimerStartedAt || Date.now());
@@ -1166,10 +1190,12 @@ export class RendererLite {
         // OPTIMIZATION: Reuse existing elements for same layout (Arexibo pattern)
         this.log.info(`Replaying layout ${layoutId} - reusing elements (no recreation!)`);
 
-        // Stop all region timers and reset to first widget
+        // Stop all region timers and widgets, then reset to first widget
         this._clearRegionTimers(this.regions);
+        this._stopAllRegionWidgets(this.regions, (rid, idx) => this.stopWidget(rid, idx));
         for (const [, region] of this.regions) {
           region.currentIndex = 0;
+          region.complete = false;
         }
 
         // Clear layout timer
@@ -1177,6 +1203,7 @@ export class RendererLite {
           clearTimeout(this.layoutTimer);
           this.layoutTimer = null;
         }
+        this._deferredTimerLayoutId = null;
         this.layoutEndEmitted = false;
 
         // DON'T call stopCurrentLayout() - keep elements alive!
@@ -1561,6 +1588,36 @@ export class RendererLite {
       return;
     }
 
+    // Dynamic layouts (useDuration=0 videos): defer timer until video metadata
+    // provides real durations. Without this, the 60s fallback fires prematurely
+    // causing rapid layout cycling ("layout storm") on startup.
+    if (layout.isDynamic && this._hasUnprobedVideos()) {
+      this._deferredTimerLayoutId = layoutId;
+      this._layoutTimerStartedAt = Date.now();
+      this.log.info(`Layout ${layoutId} has unprobed videos — deferring timer until metadata loads`);
+      return;
+    }
+
+    this._startLayoutTimer(layoutId, layout);
+  }
+
+  /**
+   * Check if any video widget in current layout still has duration=0 (metadata not loaded).
+   */
+  _hasUnprobedVideos() {
+    for (const [, region] of this.regions) {
+      for (const widget of region.widgets) {
+        if (widget.useDuration === 0 && widget.duration === 0) return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Actually start the layout timer. Called directly or after deferred timer resolves.
+   */
+  _startLayoutTimer(layoutId, layout) {
+    this._deferredTimerLayoutId = null;
     const layoutDurationMs = layout.duration * 1000;
     this.log.info(`Layout ${layoutId} will end after ${layout.duration}s`);
 
@@ -1990,6 +2047,7 @@ export class RendererLite {
       const widget = await this._showWidget(region, widgetIndex);
       if (widget) {
         this.log.info(`Showing widget ${widget.type} (${widget.id}) in region ${regionId}`);
+        this._startedWidgets.add(`${regionId}:${widgetIndex}`);
         this.emit('widgetStart', {
           widgetId: widget.id, regionId, layoutId: this.currentLayoutId,
           mediaId: parseInt(widget.fileId || widget.id) || null,
@@ -2022,6 +2080,9 @@ export class RendererLite {
    * @param {number} widgetIndex - Widget index
    */
   async stopWidget(regionId, widgetIndex) {
+    const key = `${regionId}:${widgetIndex}`;
+    if (!this._startedWidgets.delete(key)) return; // idempotent: already stopped
+
     const region = this.regions.get(regionId);
     if (!region) return;
 
@@ -2037,6 +2098,24 @@ export class RendererLite {
     }
   }
 
+  /**
+   * Stop all started widgets across regions (symmetric counterpart to startRegion)
+   * Canvas regions start ALL widgets; non-canvas regions have one active widget.
+   * @param {Map} regions - Region map
+   * @param {Function} stopFn - (regionId, widgetIndex) => void
+   */
+  _stopAllRegionWidgets(regions, stopFn) {
+    for (const [regionId, region] of regions) {
+      if (region.isCanvas) {
+        for (let i = 0; i < region.widgets.length; i++) {
+          stopFn(regionId, i);
+        }
+      } else if (region.widgets.length > 0) {
+        stopFn(regionId, region.currentIndex);
+      }
+    }
+  }
+
   /**
    * Render image widget
    */
@@ -2433,7 +2512,7 @@ export class RendererLite {
     container.className = 'renderer-lite-widget pdf-widget';
     container.style.width = '100%';
     container.style.height = '100%';
-    container.style.backgroundColor = '#525659';
+    container.style.backgroundColor = 'transparent';
     container.style.opacity = '0';
     container.style.position = 'relative';
 
@@ -2481,9 +2560,10 @@ export class RendererLite {
       const ctx = canvas.getContext('2d');
       container.appendChild(canvas);
 
-      // Page indicator (bottom-right, v1-style pill)
+      // Page indicator (bottom-right, v1-style pill) — debug only
       const indicator = document.createElement('div');
       indicator.style.cssText = 'position:absolute;bottom:10px;right:10px;background:rgba(0,0,0,0.7);color:white;padding:8px 12px;border-radius:4px;font:14px system-ui;z-index:1;';
+      if (!isDebug()) indicator.style.display = 'none';
       container.appendChild(indicator);
 
       let currentPage = 1;
@@ -2882,6 +2962,10 @@ export class RendererLite {
 
     const oldLayoutId = this.currentLayoutId;
 
+    this.layoutEndEmitted = false;
+    this.currentLayout = null;
+    this.currentLayoutId = null;
+
     if (oldLayoutId && this.layoutPool.has(oldLayoutId)) {
       // Old layout was preloaded — evict from pool (safe: removes its wrapper div)
       this.layoutPool.evict(oldLayoutId);
@@ -2890,6 +2974,7 @@ export class RendererLite {
       // Region elements live directly in this.container (not a wrapper),
       // so we must remove them individually.
       this._clearRegionTimers(this.regions);
+      this._stopAllRegionWidgets(this.regions, (rid, idx) => this.stopWidget(rid, idx));
       for (const [, region] of this.regions) {
         // Release video/audio resources before removing from DOM
         LayoutPool.releaseMediaElements(region.element);
@@ -2915,11 +3000,6 @@ export class RendererLite {
       }
     }
 
-    // Emit layoutEnd for old layout if timer hasn't already
-    if (oldLayoutId && !this.layoutEndEmitted) {
-      this.emit('layoutEnd', oldLayoutId);
-    }
-
     this.regions.clear();
 
     // ── Activate preloaded layout ──
@@ -2931,7 +3011,13 @@ export class RendererLite {
     this.currentLayout = preloaded.layout;
     this.currentLayoutId = layoutId;
     this.regions = preloaded.regions;
-    this.layoutEndEmitted = false;
+
+    // Emit layoutEnd for old layout AFTER setting new currentLayoutId —
+    // the listener guard in main.ts sees the new layout already playing
+    // and skips advance, while stats/tracking still run.
+    if (oldLayoutId) {
+      this.emit('layoutEnd', oldLayoutId);
+    }
 
     // Update container background to match preloaded layout
     this.container.style.backgroundColor = preloaded.layout.bgcolor;
@@ -3007,16 +3093,19 @@ export class RendererLite {
 
     this.log.info(`Stopping layout ${this.currentLayoutId}`);
 
-    // Remove interactive action listeners before teardown
-    this.removeActionListeners();
+    const endedLayoutId = this.currentLayoutId;
+    const shouldEmit = endedLayoutId && !this.layoutEndEmitted;
 
-    // Clear layout timer
+    this.layoutEndEmitted = false;
+    this._deferredTimerLayoutId = null;
+    this.currentLayout = null;
+    this.currentLayoutId = null;
+
+    // Clear timers
     if (this.layoutTimer) {
       clearTimeout(this.layoutTimer);
       this.layoutTimer = null;
     }
-
-    // Clear preload timers
     if (this.preloadTimer) {
       clearTimeout(this.preloadTimer);
       this.preloadTimer = null;
@@ -3026,26 +3115,25 @@ export class RendererLite {
       this._preloadRetryTimer = null;
     }
 
+    // Remove interactive action listeners before teardown
+    this.removeActionListeners();
+
     // If layout was preloaded (has its own wrapper div in pool), evict safely.
     // Normally-rendered layouts are NOT in the pool, so we do manual cleanup.
-    if (this.currentLayoutId && this.layoutPool.has(this.currentLayoutId)) {
-      this.layoutPool.evict(this.currentLayoutId);
+    if (endedLayoutId && this.layoutPool.has(endedLayoutId)) {
+      this.layoutPool.evict(endedLayoutId);
     } else {
       // Normally-rendered layout - manual cleanup (regions are in this.container)
 
       // Revoke all blob URLs for this layout (tracked lifecycle management)
-      if (this.currentLayoutId) {
-        this.revokeBlobUrlsForLayout(this.currentLayoutId);
+      if (endedLayoutId) {
+        this.revokeBlobUrlsForLayout(endedLayoutId);
       }
 
-      // Stop all regions
+      // Stop all regions — use helper to stop ALL started widgets (canvas fix)
       this._clearRegionTimers(this.regions);
-      for (const [regionId, region] of this.regions) {
-        // Stop current widget
-        if (region.widgets.length > 0) {
-          this.stopWidget(regionId, region.currentIndex);
-        }
-
+      this._stopAllRegionWidgets(this.regions, (rid, idx) => this.stopWidget(rid, idx));
+      for (const [, region] of this.regions) {
         // Release video/audio resources before removing from DOM
         LayoutPool.releaseMediaElements(region.element);
 
@@ -3068,21 +3156,13 @@ export class RendererLite {
 
     }
 
-    // Clear state
     this.regions.clear();
 
-    // Emit layout end event only if timer hasn't already emitted it.
-    // Timer-based layoutEnd (natural expiry) is authoritative — stopCurrentLayout
-    // is called afterwards during the switch to the next layout, so we skip the
-    // duplicate. But if the layout is forcibly stopped mid-playback (e.g., XMR
-    // schedule change), the timer hasn't fired yet, so we DO emit here.
-    if (this.currentLayoutId && !this.layoutEndEmitted) {
-      this.emit('layoutEnd', this.currentLayoutId);
+    // Emit LAST — re-entrant renderLayout() sees currentLayout=null,
+    // so stopCurrentLayout() returns early. No cascade.
+    if (shouldEmit) {
+      this.emit('layoutEnd', endedLayoutId);
     }
-
-    this.layoutEndEmitted = false;
-    this.currentLayout = null;
-    this.currentLayoutId = null;
   }
 
   /**
@@ -3245,6 +3325,7 @@ export class RendererLite {
       const widget = await this._showWidget(region, widgetIndex);
       if (widget) {
         this.log.info(`Showing overlay widget ${widget.type} (${widget.id}) in overlay ${overlayId} region ${regionId}`);
+        this._startedWidgets.add(`overlay:${overlayId}:${regionId}:${widgetIndex}`);
         this.emit('overlayWidgetStart', {
           overlayId, widgetId: widget.id, regionId,
           type: widget.type, duration: widget.duration
@@ -3263,6 +3344,9 @@ export class RendererLite {
    * @param {number} widgetIndex - Widget index
    */
   async stopOverlayWidget(overlayId, regionId, widgetIndex) {
+    const key = `overlay:${overlayId}:${regionId}:${widgetIndex}`;
+    if (!this._startedWidgets.delete(key)) return; // idempotent
+
     const overlayState = this.activeOverlays.get(overlayId);
     if (!overlayState) return;
 
@@ -3298,17 +3382,11 @@ export class RendererLite {
     }
 
     // Stop all overlay regions
-    for (const [regionId, region] of overlayState.regions) {
-      if (region.timer) {
-        clearTimeout(region.timer);
-        region.timer = null;
-      }
-
-      // Stop current widget
-      if (region.widgets.length > 0) {
-        this.stopOverlayWidget(layoutId, regionId, region.currentIndex);
-      }
+    for (const [, region] of overlayState.regions) {
+      if (region.timer) { clearTimeout(region.timer); region.timer = null; }
     }
+    this._stopAllRegionWidgets(overlayState.regions,
+      (rid, idx) => this.stopOverlayWidget(layoutId, rid, idx));
 
     // Remove overlay container from DOM
     if (overlayState.container) {
@@ -3411,6 +3489,7 @@ export class RendererLite {
   cleanup() {
     this.stopAllOverlays();
     this.stopCurrentLayout();
+    this._startedWidgets.clear();
 
     // Clean up any remaining audio overlays
     for (const widgetId of this.audioOverlays.keys()) {

package/src/renderer-lite.test.js

@@ -2698,4 +2698,223 @@ describe('RendererLite', () => {
       vi.useRealTimers();
     });
   });
+
+  describe('Widget Lifecycle Symmetry', () => {
+    it('should emit symmetric widgetStart/widgetEnd for single-widget layout', async () => {
+      vi.useFakeTimers();
+      const starts = [];
+      const ends = [];
+      renderer.on('widgetStart', (e) => starts.push(e));
+      renderer.on('widgetEnd', (e) => ends.push(e));
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="10">
+          <region id="r1" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="10" fileId="1">
+              <options><uri>test.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      const renderPromise = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+
+      expect(starts).toHaveLength(1);
+      expect(ends).toHaveLength(0);
+
+      renderer.stopCurrentLayout();
+
+      expect(ends).toHaveLength(1);
+      expect(ends[0].widgetId).toBe(starts[0].widgetId);
+      expect(renderer._startedWidgets.size).toBe(0);
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await renderPromise;
+      vi.useRealTimers();
+    });
+
+    it('should stop ALL widgets in canvas region on teardown', async () => {
+      vi.useFakeTimers();
+      const starts = [];
+      const ends = [];
+      renderer.on('widgetStart', (e) => starts.push(e));
+      renderer.on('widgetEnd', (e) => ends.push(e));
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="30">
+          <region id="r1" type="canvas" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="10" fileId="1">
+              <options><uri>img1.png</uri></options>
+            </media>
+            <media id="m2" type="image" duration="10" fileId="2">
+              <options><uri>img2.png</uri></options>
+            </media>
+            <media id="m3" type="image" duration="10" fileId="3">
+              <options><uri>img3.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      const renderPromise = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+
+      expect(starts).toHaveLength(3);
+      expect(ends).toHaveLength(0);
+
+      renderer.stopCurrentLayout();
+
+      expect(ends).toHaveLength(3);
+      expect(renderer._startedWidgets.size).toBe(0);
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await renderPromise;
+      vi.useRealTimers();
+    });
+
+    it('should stop widgets before restarting on same-layout replay', async () => {
+      vi.useFakeTimers();
+      const events = [];
+      renderer.on('widgetStart', (e) => events.push({ type: 'start', id: e.widgetId }));
+      renderer.on('widgetEnd', (e) => events.push({ type: 'end', id: e.widgetId }));
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="10">
+          <region id="r1" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="10" fileId="1">
+              <options><uri>test.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      // First render
+      const p1 = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+      expect(events).toHaveLength(1); // 1 start
+
+      // Same-layout replay
+      events.length = 0;
+      const p2 = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+
+      // widgetEnd should fire before widgetStart for the replay
+      expect(events.length).toBeGreaterThanOrEqual(2);
+      const endIdx = events.findIndex(e => e.type === 'end');
+      const startIdx = events.findIndex(e => e.type === 'start');
+      expect(endIdx).toBeLessThan(startIdx);
+      expect(renderer._startedWidgets.size).toBe(1);
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await p1;
+      await p2;
+      vi.useRealTimers();
+    });
+
+    it('should be idempotent on double stopWidget calls', async () => {
+      vi.useFakeTimers();
+      const ends = [];
+      renderer.on('widgetEnd', (e) => ends.push(e));
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="10">
+          <region id="r1" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="10" fileId="1">
+              <options><uri>test.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      const renderPromise = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+
+      // Stop twice
+      await renderer.stopWidget('r1', 0);
+      await renderer.stopWidget('r1', 0);
+
+      expect(ends).toHaveLength(1); // only 1 widgetEnd, not 2
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await renderPromise;
+      vi.useRealTimers();
+    });
+
+    it('should not double-emit widgetEnd on layout timer + stopCurrentLayout', async () => {
+      vi.useFakeTimers();
+      const ends = [];
+      renderer.on('widgetEnd', (e) => ends.push(e));
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="5">
+          <region id="r1" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="5" fileId="1">
+              <options><uri>test.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      const renderPromise = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(2000);
+
+      // Advance past layout duration (layout timer fires, which triggers stopCurrentLayout internally via layoutEnd)
+      await vi.advanceTimersByTimeAsync(5000);
+
+      // Now explicitly stop (as renderLayout(next) would do)
+      renderer.stopCurrentLayout();
+
+      // Should only have 1 widgetEnd total, not 2
+      expect(ends).toHaveLength(1);
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await renderPromise;
+      vi.useRealTimers();
+    });
+
+    it('should balance starts and ends during multi-widget cycling', async () => {
+      vi.useFakeTimers();
+      let startCount = 0;
+      let endCount = 0;
+      renderer.on('widgetStart', () => startCount++);
+      renderer.on('widgetEnd', () => endCount++);
+
+      const xlf = `
+        <layout width="1920" height="1080" duration="30">
+          <region id="r1" width="1920" height="1080" top="0" left="0">
+            <media id="m1" type="image" duration="2" fileId="1">
+              <options><uri>img1.png</uri></options>
+            </media>
+            <media id="m2" type="image" duration="2" fileId="2">
+              <options><uri>img2.png</uri></options>
+            </media>
+            <media id="m3" type="image" duration="2" fileId="3">
+              <options><uri>img3.png</uri></options>
+            </media>
+          </region>
+        </layout>
+      `;
+
+      const renderPromise = renderer.renderLayout(xlf, 1);
+      await vi.advanceTimersByTimeAsync(1000);
+
+      // Cycle through several widgets (3 widgets × 2s each = 6s per cycle)
+      for (let i = 0; i < 12; i++) {
+        await vi.advanceTimersByTimeAsync(2000);
+      }
+
+      // At any point, starts should be >= ends
+      expect(startCount).toBeGreaterThanOrEqual(endCount);
+
+      // After full teardown, they should balance
+      renderer.stopCurrentLayout();
+      expect(startCount).toBe(endCount);
+      expect(renderer._startedWidgets.size).toBe(0);
+
+      await vi.advanceTimersByTimeAsync(60000);
+      await renderPromise;
+      vi.useRealTimers();
+    });
+  });
 });