@xiboplayer/renderer 0.1.3 → 0.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @xiboplayer/renderer
+
+**XLF layout rendering engine for Xibo digital signage.**
+
+## Overview
+
+RendererLite parses Xibo Layout Format (XLF) files and builds a live DOM with:
+
+- **Rich media** — video (MP4/HLS), images, PDF (via PDF.js), text/ticker, web pages, clock, calendar, weather
+- **Transitions** — fade and fly (8-direction compass) via Web Animations API
+- **Interactive actions** — touch/click and keyboard triggers for widget navigation, layout jumps, and commands
+- **Layout preloading** — 2-layout pool pre-builds upcoming layouts at 75% of current duration for zero-gap transitions
+- **Proportional scaling** — ResizeObserver-based scaling to fit any screen resolution
+- **Overlay support** — multiple simultaneous overlay layouts with independent z-index (1000+)
+
+## Installation
+
+```bash
+npm install @xiboplayer/renderer
+```
+
+## Usage
+
+```javascript
+import { RendererLite } from '@xiboplayer/renderer';
+
+const renderer = new RendererLite({
+  container: document.getElementById('player'),
+});
+
+// Render a layout from parsed XLF
+await renderer.renderLayout(xlf, { mediaBaseUrl: '/cache/' });
+```
+
+## Widget Types
+
+| Widget | Implementation |
+|--------|---------------|
+| Video | `<video>` with native HLS (Safari) + hls.js fallback, pause-on-last-frame |
+| Image | `<img>` with objectFit contain, blob URL from cache |
+| PDF | PDF.js canvas rendering (dynamically imported) |
+| Text / Ticker | iframe with CMS-rendered HTML via GetResource |
+| Web page | bare `<iframe src="...">` |
+| Clock, Calendar, Weather | iframe via GetResource (server-rendered) |
+| All other CMS widgets | Generic iframe via GetResource |
+
+## Dependencies
+
+- `@xiboplayer/utils` — logger, events
+- `pdfjs-dist` — PDF rendering
+
+---
+
+**Part of the [XiboPlayer SDK](https://github.com/linuxnow/xiboplayer)**

package/package.json

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

package/src/index.js

@@ -1,4 +1,6 @@
 // @xiboplayer/renderer - Layout rendering
+import pkg from '../package.json' with { type: 'json' };
+export const VERSION = pkg.version;
 export { RendererLite } from './renderer-lite.js';
 export { LayoutPool } from './layout-pool.js';
-export { parseLayout, translateXLF } from './layout.js';
+export { LayoutTranslator } from './layout.js';

package/src/layout.js

@@ -3,136 +3,6 @@
  * Based on arexibo layout.rs
  */
 
-// Transition utility functions
-const Transitions = {
-  /**
-   * Apply fade in transition
-   */
-  fadeIn(element, duration) {
-    const keyframes = [
-      { opacity: 0 },
-      { opacity: 1 }
-    ];
-    const timing = {
-      duration: duration,
-      easing: 'linear',
-      fill: 'forwards'
-    };
-    return element.animate(keyframes, timing);
-  },
-
-  /**
-   * Apply fade out transition
-   */
-  fadeOut(element, duration) {
-    const keyframes = [
-      { opacity: 1 },
-      { opacity: 0, zIndex: 0 }
-    ];
-    const timing = {
-      duration: duration,
-      easing: 'linear',
-      fill: 'forwards'
-    };
-    return element.animate(keyframes, timing);
-  },
-
-  /**
-   * Get fly keyframes based on compass direction
-   */
-  getFlyKeyframes(direction, width, height, isIn) {
-    const keyframes = { from: {}, to: {} };
-
-    // Map compass directions to transform values
-    const dirMap = {
-      'N': { x: 0, y: isIn ? -height : height },
-      'NE': { x: isIn ? width : -width, y: isIn ? -height : height },
-      'E': { x: isIn ? width : -width, y: 0 },
-      'SE': { x: isIn ? width : -width, y: isIn ? height : -height },
-      'S': { x: 0, y: isIn ? height : -height },
-      'SW': { x: isIn ? -width : width, y: isIn ? height : -height },
-      'W': { x: isIn ? -width : width, y: 0 },
-      'NW': { x: isIn ? -width : width, y: isIn ? -height : height }
-    };
-
-    const offset = dirMap[direction] || dirMap['N'];
-
-    if (isIn) {
-      keyframes.from = {
-        transform: `translate(${offset.x}px, ${offset.y}px)`,
-        opacity: 0
-      };
-      keyframes.to = {
-        transform: 'translate(0, 0)',
-        opacity: 1
-      };
-    } else {
-      keyframes.from = {
-        transform: 'translate(0, 0)',
-        opacity: 1
-      };
-      keyframes.to = {
-        transform: `translate(${offset.x}px, ${offset.y}px)`,
-        opacity: 0
-      };
-    }
-
-    return keyframes;
-  },
-
-  /**
-   * Apply fly in transition
-   */
-  flyIn(element, duration, direction, regionWidth, regionHeight) {
-    const keyframes = this.getFlyKeyframes(direction, regionWidth, regionHeight, true);
-    const timing = {
-      duration: duration,
-      easing: 'ease-out',
-      fill: 'forwards'
-    };
-    return element.animate([keyframes.from, keyframes.to], timing);
-  },
-
-  /**
-   * Apply fly out transition
-   */
-  flyOut(element, duration, direction, regionWidth, regionHeight) {
-    const keyframes = this.getFlyKeyframes(direction, regionWidth, regionHeight, false);
-    const timing = {
-      duration: duration,
-      easing: 'ease-in',
-      fill: 'forwards'
-    };
-    return element.animate([keyframes.from, keyframes.to], timing);
-  },
-
-  /**
-   * Apply transition based on type
-   */
-  apply(element, transitionConfig, isIn, regionWidth, regionHeight) {
-    if (!transitionConfig || !transitionConfig.type) {
-      return null;
-    }
-
-    const type = transitionConfig.type.toLowerCase();
-    const duration = transitionConfig.duration || 1000;
-    const direction = transitionConfig.direction || 'N';
-
-    switch (type) {
-      case 'fadein':
-        return isIn ? this.fadeIn(element, duration) : null;
-      case 'fadeout':
-        return isIn ? null : this.fadeOut(element, duration);
-      case 'flyin':
-        return isIn ? this.flyIn(element, duration, direction, regionWidth, regionHeight) : null;
-      case 'flyout':
-        return isIn ? null : this.flyOut(element, duration, direction, regionWidth, regionHeight);
-      default:
-        return null;
-    }
-  }
-};
-
 export class LayoutTranslator {
   constructor(xmds) {
     this.xmds = xmds;
@@ -513,6 +383,63 @@ ${mediaJS}
   }`;
   }
 
+  /**
+   * Generate iframe widget JS for text/ticker and generic widget types.
+   * Returns { startFn, stopFn } strings for the media item.
+   */
+  _generateIframeWidgetJS(regionId, mediaId, widgetUrl, transIn, transOut) {
+    const iframeId = `widget_${regionId}_${mediaId}`;
+    const startFn = `() => {
+        const region = document.getElementById('region_${regionId}');
+        let iframe = document.getElementById('${iframeId}');
+        if (!iframe) {
+          iframe = document.createElement('iframe');
+          iframe.id = '${iframeId}';
+          iframe.src = '${widgetUrl}';
+          iframe.style.width = '100%';
+          iframe.style.height = '100%';
+          iframe.style.border = 'none';
+          iframe.scrolling = 'no';
+          iframe.style.opacity = '0';
+          region.innerHTML = '';
+          region.appendChild(iframe);
+
+          // Apply transition after iframe loads
+          iframe.onload = () => {
+            const transIn = ${transIn};
+            if (transIn && window.Transitions) {
+              const regionRect = region.getBoundingClientRect();
+              window.Transitions.apply(iframe, transIn, true, regionRect.width, regionRect.height);
+            } else {
+              iframe.style.opacity = '1';
+            }
+          };
+        } else {
+          iframe.style.display = 'block';
+          iframe.style.opacity = '1';
+        }
+      }`;
+    const stopFn = `() => {
+        const region = document.getElementById('region_${regionId}');
+        const iframe = document.getElementById('${iframeId}');
+        if (iframe) {
+          const transOut = ${transOut};
+          if (transOut && window.Transitions) {
+            const regionRect = region.getBoundingClientRect();
+            const animation = window.Transitions.apply(iframe, transOut, false, regionRect.width, regionRect.height);
+            if (animation) {
+              animation.onfinish = () => {
+                iframe.style.display = 'none';
+              };
+              return;
+            }
+          }
+          iframe.style.display = 'none';
+        }
+      }`;
+    return { startFn, stopFn };
+  }
+
   /**
    * Generate JavaScript for a single media item
    */
@@ -616,63 +543,16 @@ ${mediaJS}
 
       case 'text':
       case 'ticker':
-        // Use cache URL pattern for text/ticker widgets - must be in /player/ scope for SW
+        // Text/ticker widgets use the same iframe pattern as default widgets.
+        // If no widgetCacheKey, fall through to the default case which handles unsupported types.
         if (media.options.widgetCacheKey) {
           const textUrl = `${window.location.origin}/player${media.options.widgetCacheKey}`;
-          const iframeId = `widget_${regionId}_${media.id}`;
-          startFn = `() => {
-        const region = document.getElementById('region_${regionId}');
-        let iframe = document.getElementById('${iframeId}');
-        if (!iframe) {
-          iframe = document.createElement('iframe');
-          iframe.id = '${iframeId}';
-          iframe.src = '${textUrl}';
-          iframe.style.width = '100%';
-          iframe.style.height = '100%';
-          iframe.style.border = 'none';
-          iframe.scrolling = 'no';
-          iframe.style.opacity = '0';
-          region.innerHTML = '';
-          region.appendChild(iframe);
-
-          // Apply transition after iframe loads
-          iframe.onload = () => {
-            const transIn = ${transIn};
-            if (transIn && window.Transitions) {
-              const regionRect = region.getBoundingClientRect();
-              window.Transitions.apply(iframe, transIn, true, regionRect.width, regionRect.height);
-            } else {
-              iframe.style.opacity = '1';
-            }
-          };
-        } else {
-          iframe.style.display = 'block';
-          iframe.style.opacity = '1';
-        }
-      }`;
-          stopFn = `() => {
-        const region = document.getElementById('region_${regionId}');
-        const iframe = document.getElementById('${iframeId}');
-        if (iframe) {
-          const transOut = ${transOut};
-          if (transOut && window.Transitions) {
-            const regionRect = region.getBoundingClientRect();
-            const animation = window.Transitions.apply(iframe, transOut, false, regionRect.width, regionRect.height);
-            if (animation) {
-              animation.onfinish = () => {
-                iframe.style.display = 'none';
-              };
-              return;
-            }
-          }
-          iframe.style.display = 'none';
-        }
-      }`;
-        } else {
-          console.warn(`[Layout] Text media without widgetCacheKey`);
-          startFn = `() => console.log('Text media without cache key')`;
+          const iframe = this._generateIframeWidgetJS(regionId, media.id, textUrl, transIn, transOut);
+          startFn = iframe.startFn;
+          stopFn = iframe.stopFn;
+          break;
         }
-        break;
+        // Fall through to default (handles missing widgetCacheKey as unsupported)
 
       case 'audio':
         const audioSrc = `${window.location.origin}/player/cache/media/${media.options.uri}`;
@@ -1007,55 +887,9 @@ ${mediaJS}
         // Keep widget iframes alive across duration cycles (arexibo behavior)
         if (media.options.widgetCacheKey) {
           const widgetUrl = `${window.location.origin}/player${media.options.widgetCacheKey}`;
-          const iframeId = `widget_${regionId}_${media.id}`;
-          startFn = `() => {
-        const region = document.getElementById('region_${regionId}');
-        let iframe = document.getElementById('${iframeId}');
-        if (!iframe) {
-          iframe = document.createElement('iframe');
-          iframe.id = '${iframeId}';
-          iframe.src = '${widgetUrl}';
-          iframe.style.width = '100%';
-          iframe.style.height = '100%';
-          iframe.style.border = 'none';
-          iframe.scrolling = 'no';
-          iframe.style.opacity = '0';
-          region.innerHTML = '';
-          region.appendChild(iframe);
-
-          // Apply transition after iframe loads
-          iframe.onload = () => {
-            const transIn = ${transIn};
-            if (transIn && window.Transitions) {
-              const regionRect = region.getBoundingClientRect();
-              window.Transitions.apply(iframe, transIn, true, regionRect.width, regionRect.height);
-            } else {
-              iframe.style.opacity = '1';
-            }
-          };
-        } else {
-          iframe.style.display = 'block';
-          iframe.style.opacity = '1';
-        }
-      }`;
-          stopFn = `() => {
-        const region = document.getElementById('region_${regionId}');
-        const iframe = document.getElementById('${iframeId}');
-        if (iframe) {
-          const transOut = ${transOut};
-          if (transOut && window.Transitions) {
-            const regionRect = region.getBoundingClientRect();
-            const animation = window.Transitions.apply(iframe, transOut, false, regionRect.width, regionRect.height);
-            if (animation) {
-              animation.onfinish = () => {
-                iframe.style.display = 'none';
-              };
-              return;
-            }
-          }
-          iframe.style.display = 'none';
-        }
-      }`;
+          const iframe = this._generateIframeWidgetJS(regionId, media.id, widgetUrl, transIn, transOut);
+          startFn = iframe.startFn;
+          stopFn = iframe.stopFn;
         } else {
           console.warn(`[Layout] Unsupported media type: ${media.type}`);
           startFn = `() => console.log('Unsupported media type: ${media.type}')`;
@@ -1070,4 +904,3 @@ ${mediaJS}
   }
 }
 
-export const layoutTranslator = new LayoutTranslator();

package/src/renderer-lite.js

@@ -204,6 +204,10 @@ 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._paused = false;
+    this._layoutTimerStartedAt = null;  // Date.now() when layout timer started
+    this._layoutTimerDurationMs = null; // Total layout duration in ms
+    this._layoutTimerRemaining = null;  // ms remaining when paused
     this.widgetTimers = new Map(); // widgetId => timer
     this.mediaUrlCache = new Map(); // fileId => blob URL (for parallel pre-fetching)
     this.layoutBlobUrls = new Map(); // layoutId => Set<blobUrl> (for lifecycle tracking)
@@ -555,6 +559,7 @@ 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);
 
       // Reset layout timer with new duration — but only if a timer is already running.
       // If startLayoutTimerWhenReady() hasn't fired yet (still waiting for widgets),
@@ -1002,48 +1007,15 @@ export class RendererLite {
    */
   startRegion(regionId) {
     const region = this.regions.get(regionId);
-    if (!region || region.widgets.length === 0) {
-      return;
-    }
-
-    // If only one widget, just render it (no cycling)
-    // Don't set completion timer - layout duration controls ending
-    // Region completion is NOT tracked for single-widget regions
-    // (they display continuously until layout timer expires)
-    if (region.widgets.length === 1) {
-      this.renderWidget(regionId, 0);
-      return;
-    }
-
-    // Multiple widgets - cycle through them
-    const playNext = () => {
-      const widgetIndex = region.currentIndex;
-      const widget = region.widgets[widgetIndex];
-
-      // Render widget
-      this.renderWidget(regionId, widgetIndex);
-
-      // Schedule next widget
-      const duration = widget.duration * 1000;
-      region.timer = setTimeout(() => {
-        this.stopWidget(regionId, widgetIndex);
-
-        // Move to next widget (wraps to 0 if at end)
-        const nextIndex = (region.currentIndex + 1) % region.widgets.length;
-
-        // Check if completing full cycle (wrapped back to 0)
-        if (nextIndex === 0 && !region.complete) {
-          region.complete = true;
-          this.log.info(`Region ${regionId} completed one full cycle`);
-          this.checkLayoutComplete();
-        }
-
-        region.currentIndex = nextIndex;
-        playNext();
-      }, duration);
-    };
-
-    playNext();
+    this._startRegionCycle(
+      region, regionId,
+      (rid, idx) => this.renderWidget(rid, idx),
+      (rid, idx) => this.stopWidget(rid, idx),
+      () => {
+        this.log.info(`Region ${regionId} completed one full cycle`);
+        this.checkLayoutComplete();
+      }
+    );
   }
 
   /**
@@ -1090,48 +1062,31 @@ export class RendererLite {
    * @param {Object} widget - Widget config
    */
   updateMediaElement(element, widget) {
-    // Videos: ALWAYS restart on widget show (even if looping)
-    const videoEl = this.findMediaElement(element, 'VIDEO');
-    if (videoEl) {
-      videoEl.currentTime = 0;
-      // Wait for seek to complete before playing — avoids DOMException
-      // "The play() request was interrupted" when calling play() mid-seek
-      const playAfterSeek = () => {
-        videoEl.removeEventListener('seeked', playAfterSeek);
-        videoEl.play().catch(() => {}); // Silently ignore — autoplay will retry
-      };
-      videoEl.addEventListener('seeked', playAfterSeek);
-      // Fallback: if seeked doesn't fire (already at 0), try play directly
-      if (videoEl.currentTime === 0 && videoEl.readyState >= 2) {
-        videoEl.removeEventListener('seeked', playAfterSeek);
-        videoEl.play().catch(() => {});
-      }
-      this.log.info(`Video restarted: ${widget.fileId || widget.id}`);
-      return;
+    // Restart video or audio on widget show (even if looping)
+    const mediaEl = this.findMediaElement(element, 'VIDEO') || this.findMediaElement(element, 'AUDIO');
+    if (mediaEl) {
+      this._restartMediaElement(mediaEl);
+      this.log.info(`${mediaEl.tagName === 'VIDEO' ? 'Video' : 'Audio'} restarted: ${widget.fileId || widget.id}`);
     }
+  }
 
-    // Audio: ALWAYS restart on widget show (even if looping)
-    const audioEl = this.findMediaElement(element, 'AUDIO');
-    if (audioEl) {
-      audioEl.currentTime = 0;
-      const playAfterSeek = () => {
-        audioEl.removeEventListener('seeked', playAfterSeek);
-        audioEl.play().catch(() => {});
-      };
-      audioEl.addEventListener('seeked', playAfterSeek);
-      if (audioEl.currentTime === 0 && audioEl.readyState >= 2) {
-        audioEl.removeEventListener('seeked', playAfterSeek);
-        audioEl.play().catch(() => {});
-      }
-      this.log.info(`Audio restarted: ${widget.fileId || widget.id}`);
-      return;
+  /**
+   * Restart a media element from the beginning.
+   * Waits for seek to complete before playing — avoids DOMException
+   * "The play() request was interrupted" when calling play() mid-seek.
+   */
+  _restartMediaElement(el) {
+    el.currentTime = 0;
+    const playAfterSeek = () => {
+      el.removeEventListener('seeked', playAfterSeek);
+      el.play().catch(() => {});
+    };
+    el.addEventListener('seeked', playAfterSeek);
+    // Fallback: if seeked doesn't fire (already at 0), try play directly
+    if (el.currentTime === 0 && el.readyState >= 2) {
+      el.removeEventListener('seeked', playAfterSeek);
+      el.play().catch(() => {});
     }
-
-    // Images: Could refresh src if needed (future enhancement)
-    // const imgEl = this.findMediaElement(element, 'IMG');
-
-    // Iframes: Could reload if needed (future enhancement)
-    // const iframeEl = this.findMediaElement(element, 'IFRAME');
   }
 
   /**
@@ -1228,6 +1183,8 @@ export class RendererLite {
     const layoutDurationMs = layout.duration * 1000;
     this.log.info(`Layout ${layoutId} will end after ${layout.duration}s`);
 
+    this._layoutTimerStartedAt = Date.now();
+    this._layoutTimerDurationMs = layoutDurationMs;
     this.layoutTimer = setTimeout(() => {
       this.log.info(`Layout ${layoutId} duration expired (${layout.duration}s)`);
       if (this.currentLayoutId) {
@@ -1242,120 +1199,152 @@ export class RendererLite {
    * @param {string} regionId - Region ID
    * @param {number} widgetIndex - Widget index in region
    */
-  async renderWidget(regionId, widgetIndex) {
-    const region = this.regions.get(regionId);
-    if (!region) return;
-
+  /**
+   * Core: show a widget in a region (shared by main layout + overlay)
+   * Returns the widget object on success, null on failure.
+   */
+  async _showWidget(region, widgetIndex) {
     const widget = region.widgets[widgetIndex];
-    if (!widget) return;
-
-    try {
-      this.log.info(`Showing widget ${widget.type} (${widget.id}) in region ${regionId}`);
-
-      // REUSE: Get existing element instead of creating new one
-      let element = region.widgetElements.get(widget.id);
-
-      if (!element) {
-        // Fallback: create if doesn't exist (shouldn't happen with pre-creation)
-        this.log.warn(`Widget ${widget.id} not pre-created, creating now`);
-        widget.layoutId = this.currentLayoutId;
-        widget.regionId = regionId;
-        element = await this.createWidgetElement(widget, region);
-        region.widgetElements.set(widget.id, element);
-        region.element.appendChild(element);
-      }
+    if (!widget) return null;
 
-      // Hide all other widgets in region
-      for (const [widgetId, widgetEl] of region.widgetElements) {
-        if (widgetId !== widget.id) {
-          widgetEl.style.visibility = 'hidden';
-          widgetEl.style.opacity = '0';
-        }
-      }
+    let element = region.widgetElements.get(widget.id);
 
-      // Update media element if needed (restart videos)
-      this.updateMediaElement(element, widget);
-
-      // Show this widget
-      element.style.visibility = 'visible';
+    if (!element) {
+      this.log.warn(`Widget ${widget.id} not pre-created, creating now`);
+      element = await this.createWidgetElement(widget, region);
+      region.widgetElements.set(widget.id, element);
+      region.element.appendChild(element);
+    }
 
-      // Apply in transition
-      if (widget.transitions.in) {
-        Transitions.apply(element, widget.transitions.in, true, region.width, region.height);
-      } else {
-        element.style.opacity = '1';
+    // Hide all other widgets in region
+    for (const [widgetId, widgetEl] of region.widgetElements) {
+      if (widgetId !== widget.id) {
+        widgetEl.style.visibility = 'hidden';
+        widgetEl.style.opacity = '0';
       }
+    }
 
-      // Emit widget start event
-      this.emit('widgetStart', {
-        widgetId: widget.id,
-        regionId,
-        layoutId: this.currentLayoutId,
-        mediaId: parseInt(widget.fileId || widget.id) || null,
-        type: widget.type,
-        duration: widget.duration
-      });
+    this.updateMediaElement(element, widget);
+    element.style.visibility = 'visible';
 
-    } catch (error) {
-      this.log.error(`Error rendering widget:`, error);
-      this.emit('error', { type: 'widgetError', error, widgetId: widget.id, regionId });
+    if (widget.transitions.in) {
+      Transitions.apply(element, widget.transitions.in, true, region.width, region.height);
+    } else {
+      element.style.opacity = '1';
     }
+
+    return widget;
   }
 
   /**
-   * Stop a widget (with element reuse - don't revoke blob URLs!)
-   * @param {string} regionId - Region ID
-   * @param {number} widgetIndex - Widget index
+   * Core: hide a widget in a region (shared by main layout + overlay).
+   * Returns { widget, animPromise } synchronously — callers await animPromise if needed.
+   * NOT async, so callers that don't need the animation stay on the same microtask.
    */
-  async stopWidget(regionId, widgetIndex) {
-    const region = this.regions.get(regionId);
-    if (!region) return;
-
+  _hideWidget(region, widgetIndex) {
     const widget = region.widgets[widgetIndex];
-    if (!widget) return;
+    if (!widget) return { widget: null, animPromise: null };
 
-    // Get widget element from reuse cache
     const widgetElement = region.widgetElements.get(widget.id);
-    if (!widgetElement) return;
+    if (!widgetElement) return { widget: null, animPromise: null };
 
-    // Apply out transition
+    let animPromise = null;
     if (widget.transitions.out) {
       const animation = Transitions.apply(
-        widgetElement,
-        widget.transitions.out,
-        false,
-        region.width,
-        region.height
+        widgetElement, widget.transitions.out, false, region.width, region.height
       );
-
       if (animation) {
-        await new Promise(resolve => {
-          animation.onfinish = resolve;
-        });
+        animPromise = new Promise(resolve => { animation.onfinish = resolve; });
       }
     }
 
-    // Pause media elements (but DON'T revoke URLs - element will be reused!)
     const videoEl = widgetElement.querySelector('video');
-    if (videoEl && widget.options.loop !== '1') {
-      videoEl.pause();
-      // Keep src intact for next cycle
-    }
+    if (videoEl && widget.options.loop !== '1') videoEl.pause();
 
     const audioEl = widgetElement.querySelector('audio');
-    if (audioEl && widget.options.loop !== '1') {
-      audioEl.pause();
-      // Keep src intact for next cycle
-    }
-
-    // Emit widget end event
-    this.emit('widgetEnd', {
-      widgetId: widget.id,
-      regionId,
-      layoutId: this.currentLayoutId,
-      mediaId: parseInt(widget.fileId || widget.id) || null,
-      type: widget.type
-    });
+    if (audioEl && widget.options.loop !== '1') audioEl.pause();
+
+    return { widget, animPromise };
+  }
+
+  /**
+   * Core: cycle through widgets in a region (shared by main layout + overlay)
+   * @param {Object} region - Region state object
+   * @param {string} regionId - Region ID
+   * @param {Function} showFn - (regionId, widgetIndex) => show widget
+   * @param {Function} hideFn - (regionId, widgetIndex) => hide widget
+   * @param {Function} [onCycleComplete] - Called when region completes one full cycle
+   */
+  _startRegionCycle(region, regionId, showFn, hideFn, onCycleComplete) {
+    if (!region || region.widgets.length === 0) return;
+
+    if (region.widgets.length === 1) {
+      showFn(regionId, 0);
+      return;
+    }
+
+    const playNext = () => {
+      const widgetIndex = region.currentIndex;
+      const widget = region.widgets[widgetIndex];
+
+      showFn(regionId, widgetIndex);
+
+      const duration = widget.duration * 1000;
+      region.timer = setTimeout(() => {
+        hideFn(regionId, widgetIndex);
+
+        const nextIndex = (region.currentIndex + 1) % region.widgets.length;
+        if (nextIndex === 0 && !region.complete) {
+          region.complete = true;
+          onCycleComplete?.();
+        }
+
+        region.currentIndex = nextIndex;
+        playNext();
+      }, duration);
+    };
+
+    playNext();
+  }
+
+  async renderWidget(regionId, widgetIndex) {
+    const region = this.regions.get(regionId);
+    if (!region) return;
+
+    try {
+      const widget = await this._showWidget(region, widgetIndex);
+      if (widget) {
+        this.log.info(`Showing widget ${widget.type} (${widget.id}) in region ${regionId}`);
+        this.emit('widgetStart', {
+          widgetId: widget.id, regionId, layoutId: this.currentLayoutId,
+          mediaId: parseInt(widget.fileId || widget.id) || null,
+          type: widget.type, duration: widget.duration
+        });
+      }
+    } catch (error) {
+      this.log.error(`Error rendering widget:`, error);
+      this.emit('error', { type: 'widgetError', error, widgetId: region.widgets[widgetIndex]?.id, regionId });
+    }
+  }
+
+  /**
+   * Stop a widget (with element reuse - don't revoke blob URLs!)
+   * @param {string} regionId - Region ID
+   * @param {number} widgetIndex - Widget index
+   */
+  async stopWidget(regionId, widgetIndex) {
+    const region = this.regions.get(regionId);
+    if (!region) return;
+
+    const { widget, animPromise } = this._hideWidget(region, widgetIndex);
+    if (animPromise) await animPromise;
+    if (widget) {
+      this.emit('widgetEnd', {
+        widgetId: widget.id, regionId, layoutId: this.currentLayoutId,
+        mediaId: parseInt(widget.fileId || widget.id) || null,
+        type: widget.type
+      });
+    }
   }
 
   /**
@@ -2378,44 +2367,12 @@ export class RendererLite {
     if (!overlayState) return;
 
     const region = overlayState.regions.get(regionId);
-    if (!region || region.widgets.length === 0) {
-      return;
-    }
-
-    // If only one widget, just render it (no cycling)
-    if (region.widgets.length === 1) {
-      this.renderOverlayWidget(overlayId, regionId, 0);
-      return;
-    }
-
-    // Multiple widgets - cycle through them
-    const playNext = () => {
-      const widgetIndex = region.currentIndex;
-      const widget = region.widgets[widgetIndex];
-
-      // Render widget
-      this.renderOverlayWidget(overlayId, regionId, widgetIndex);
-
-      // Schedule next widget
-      const duration = widget.duration * 1000;
-      region.timer = setTimeout(() => {
-        this.stopOverlayWidget(overlayId, regionId, widgetIndex);
-
-        // Move to next widget (wraps to 0 if at end)
-        const nextIndex = (region.currentIndex + 1) % region.widgets.length;
-
-        // Check if completing full cycle (wrapped back to 0)
-        if (nextIndex === 0 && !region.complete) {
-          region.complete = true;
-          this.log.info(`Overlay ${overlayId} region ${regionId} completed one full cycle`);
-        }
-
-        region.currentIndex = nextIndex;
-        playNext();
-      }, duration);
-    };
-
-    playNext();
+    this._startRegionCycle(
+      region, regionId,
+      (rid, idx) => this.renderOverlayWidget(overlayId, rid, idx),
+      (rid, idx) => this.stopOverlayWidget(overlayId, rid, idx),
+      () => this.log.info(`Overlay ${overlayId} region ${regionId} completed one full cycle`)
+    );
   }
 
   /**
@@ -2431,55 +2388,18 @@ export class RendererLite {
     const region = overlayState.regions.get(regionId);
     if (!region) return;
 
-    const widget = region.widgets[widgetIndex];
-    if (!widget) return;
-
     try {
-      this.log.info(`Showing overlay widget ${widget.type} (${widget.id}) in overlay ${overlayId} region ${regionId}`);
-
-      // Get existing element (pre-created)
-      let element = region.widgetElements.get(widget.id);
-
-      if (!element) {
-        this.log.warn(`Overlay widget ${widget.id} not pre-created, creating now`);
-        element = await this.createWidgetElement(widget, region);
-        region.widgetElements.set(widget.id, element);
-        region.element.appendChild(element);
-      }
-
-      // Hide all other widgets in region
-      for (const [widgetId, widgetEl] of region.widgetElements) {
-        if (widgetId !== widget.id) {
-          widgetEl.style.visibility = 'hidden';
-          widgetEl.style.opacity = '0';
-        }
-      }
-
-      // Update media element if needed (restart videos)
-      this.updateMediaElement(element, widget);
-
-      // Show this widget
-      element.style.visibility = 'visible';
-
-      // Apply in transition
-      if (widget.transitions.in) {
-        Transitions.apply(element, widget.transitions.in, true, region.width, region.height);
-      } else {
-        element.style.opacity = '1';
+      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.emit('overlayWidgetStart', {
+          overlayId, widgetId: widget.id, regionId,
+          type: widget.type, duration: widget.duration
+        });
       }
-
-      // Emit widget start event
-      this.emit('overlayWidgetStart', {
-        overlayId,
-        widgetId: widget.id,
-        regionId,
-        type: widget.type,
-        duration: widget.duration
-      });
-
     } catch (error) {
       this.log.error(`Error rendering overlay widget:`, error);
-      this.emit('error', { type: 'overlayWidgetError', error, widgetId: widget.id, regionId, overlayId });
+      this.emit('error', { type: 'overlayWidgetError', error, widgetId: region.widgets[widgetIndex]?.id, regionId, overlayId });
     }
   }
 
@@ -2496,47 +2416,13 @@ export class RendererLite {
     const region = overlayState.regions.get(regionId);
     if (!region) return;
 
-    const widget = region.widgets[widgetIndex];
-    if (!widget) return;
-
-    const widgetElement = region.widgetElements.get(widget.id);
-    if (!widgetElement) return;
-
-    // Apply out transition
-    if (widget.transitions.out) {
-      const animation = Transitions.apply(
-        widgetElement,
-        widget.transitions.out,
-        false,
-        region.width,
-        region.height
-      );
-
-      if (animation) {
-        await new Promise(resolve => {
-          animation.onfinish = resolve;
-        });
-      }
-    }
-
-    // Pause media elements
-    const videoEl = widgetElement.querySelector('video');
-    if (videoEl && widget.options.loop !== '1') {
-      videoEl.pause();
-    }
-
-    const audioEl = widgetElement.querySelector('audio');
-    if (audioEl && widget.options.loop !== '1') {
-      audioEl.pause();
+    const { widget, animPromise } = this._hideWidget(region, widgetIndex);
+    if (animPromise) await animPromise;
+    if (widget) {
+      this.emit('overlayWidgetEnd', {
+        overlayId, widgetId: widget.id, regionId, type: widget.type
+      });
     }
-
-    // Emit widget end event
-    this.emit('overlayWidgetEnd', {
-      overlayId,
-      widgetId: widget.id,
-      regionId,
-      type: widget.type
-    });
   }
 
   /**
@@ -2607,6 +2493,80 @@ export class RendererLite {
     return Array.from(this.activeOverlays.keys());
   }
 
+  /**
+   * Pause playback: stop layout timer, pause all media, stop widget cycling.
+   * The layout timer's remaining time is saved so resume() can restart it.
+   */
+  pause() {
+    if (this._paused) return;
+    this._paused = true;
+
+    // Save remaining layout time
+    if (this.layoutTimer && this._layoutTimerStartedAt) {
+      const elapsed = Date.now() - this._layoutTimerStartedAt;
+      this._layoutTimerRemaining = Math.max(0, this._layoutTimerDurationMs - elapsed);
+      clearTimeout(this.layoutTimer);
+      this.layoutTimer = null;
+    }
+
+    // Stop all region widget-cycling timers
+    for (const [, region] of this.regions) {
+      if (region.timer) {
+        clearTimeout(region.timer);
+        region.timer = null;
+      }
+    }
+
+    // Pause all video/audio elements
+    this._forEachMedia(el => el.pause());
+
+    this.emit('paused');
+    this.log.info('Playback paused');
+  }
+
+  /**
+   * Resume playback: restart layout timer with remaining time, resume media and widget cycling.
+   */
+  resume() {
+    if (!this._paused) return;
+    this._paused = false;
+
+    // Resume layout timer with remaining time
+    if (this._layoutTimerRemaining != null && this._layoutTimerRemaining > 0) {
+      this._layoutTimerStartedAt = Date.now();
+      this._layoutTimerDurationMs = this._layoutTimerRemaining;
+      const layoutId = this.currentLayoutId;
+      this.layoutTimer = setTimeout(() => {
+        this.log.info(`Layout ${layoutId} duration expired (resumed)`);
+        if (this.currentLayoutId) {
+          this.layoutEndEmitted = true;
+          this.emit('layoutEnd', this.currentLayoutId);
+        }
+      }, this._layoutTimerRemaining);
+      this._layoutTimerRemaining = null;
+    }
+
+    // Resume all video/audio
+    this._forEachMedia(el => el.play().catch(() => {}));
+
+    // Restart region widget cycling (re-enters cycle from current widget)
+    for (const [regionId] of this.regions) {
+      this.startRegion(regionId);
+    }
+
+    this.emit('resumed');
+    this.log.info('Playback resumed');
+  }
+
+  /**
+   * Apply a function to every video/audio element in all regions.
+   */
+  _forEachMedia(fn) {
+    for (const [, region] of this.regions) {
+      region.element?.querySelectorAll('video, audio').forEach(fn);
+    }
+  }
+
   /**
    * Cleanup renderer
    */

package/docs/README.md

@@ -1,98 +0,0 @@
-# @xiboplayer/renderer Documentation
-
-**RendererLite: Fast, efficient layout rendering engine.**
-
-## Overview
-
-The `@xiboplayer/renderer` package provides:
-
-- **RendererLite** - Lightweight XLF layout renderer
-- **Layout parser** - XLF to JSON translation
-- **Widget system** - Extensible widget rendering
-- **Transition engine** - Smooth layout transitions
-- **Element reuse** - Performance optimization (50% memory reduction)
-
-## Installation
-
-```bash
-npm install @xiboplayer/renderer
-```
-
-## Usage
-
-```javascript
-import { RendererLite } from '@xiboplayer/renderer';
-
-const renderer = new RendererLite({
-  container: document.getElementById('player'),
-  cacheManager: cache
-});
-
-await renderer.loadLayout(xlf);
-renderer.start();
-```
-
-## Features
-
-### Element Reuse Pattern
-
-Pre-creates all widget elements at layout load, toggles visibility instead of recreating DOM:
-
-- **50% memory reduction** over 10 cycles
-- **10x faster** layout replay (<0.5s vs 2-3s)
-- Zero GC pressure from DOM churn
-
-### Parallel Media Pre-fetch
-
-Fetches all media URLs upfront in parallel, enabling instant widget rendering.
-
-### Dynamic Video Duration
-
-Respects `useDuration` flag from XLF, uses video metadata when duration should be dynamic.
-
-## API Reference
-
-### RendererLite
-
-```javascript
-class RendererLite {
-  constructor(options)
-  async loadLayout(xlf)
-  start()
-  stop()
-  pause()
-  resume()
-  on(event, callback)
-}
-```
-
-### Events
-
-- `layout:loaded` - Layout parsed and ready
-- `layout:start` - Layout playback started
-- `layout:end` - Layout completed
-- `region:start` - Region playback started
-- `widget:start` - Widget started
-
-## Performance
-
-| Metric | XLR | Arexibo | RendererLite |
-|--------|-----|---------|--------------|
-| Initial load | 17-20s | 12-15s | **3-5s** |
-| Layout replay | 2-3s | <1s | **<0.5s** |
-| Memory (10 cycles) | +500MB | Stable | **Stable** |
-
-## Dependencies
-
-- `@xiboplayer/utils` - Logger, EventEmitter
-- `pdfjs-dist` - PDF rendering
-
-## Related Packages
-
-- [@xiboplayer/core](../../core/docs/) - Player orchestration
-- [@xiboplayer/cache](../../cache/docs/) - Media caching
-
----
-
-**Package Version**: 1.0.0
-**Last Updated**: 2026-02-10