@xiboplayer/renderer 0.3.7 → 0.4.0

package/src/renderer-lite.js

@@ -160,10 +160,12 @@ const Transitions = {
     const direction = transitionConfig.direction || 'N';
 
     switch (type) {
+      case 'fade':
       case 'fadein':
         return isIn ? this.fadeIn(element, duration) : null;
       case 'fadeout':
         return isIn ? null : this.fadeOut(element, duration);
+      case 'fly':
       case 'flyin':
         return isIn ? this.flyIn(element, duration, direction, regionWidth, regionHeight) : null;
       case 'flyout':
@@ -211,6 +213,7 @@ export class RendererLite {
     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)
+    this.audioOverlays = new Map(); // widgetId => [HTMLAudioElement] (audio overlays for widgets)
 
     // Scale state (for fitting layout to screen)
     this.scaleFactor = 1;
@@ -225,6 +228,9 @@ export class RendererLite {
     this._keydownHandler = null; // Document keydown listener (single, shared)
     this._keyboardActions = []; // Active keyboard actions for current layout
 
+    // Sub-playlist cycle state (round-robin per parentWidgetId group)
+    this._subPlaylistCycleIndex = new Map();
+
     // Layout preload pool (2-layout pool for instant transitions)
     this.layoutPool = new LayoutPool(2);
     this.preloadTimer = null;
@@ -346,11 +352,16 @@ export class RendererLite {
     for (const actionEl of parentEl.children) {
       if (actionEl.tagName !== 'action') continue;
       actions.push({
+        id: actionEl.getAttribute('id') || '',
         actionType: actionEl.getAttribute('actionType') || '',
         triggerType: actionEl.getAttribute('triggerType') || '',
         triggerCode: actionEl.getAttribute('triggerCode') || '',
-        layoutCode: actionEl.getAttribute('layoutCode') || '',
+        source: actionEl.getAttribute('source') || '',
+        sourceId: actionEl.getAttribute('sourceId') || '',
+        target: actionEl.getAttribute('target') || '',
         targetId: actionEl.getAttribute('targetId') || '',
+        widgetId: actionEl.getAttribute('widgetId') || '',
+        layoutCode: actionEl.getAttribute('layoutCode') || '',
         commandCode: actionEl.getAttribute('commandCode') || ''
       });
     }
@@ -373,48 +384,102 @@ export class RendererLite {
 
     const layoutDurationAttr = layoutEl.getAttribute('duration');
     const layout = {
+      schemaVersion: parseInt(layoutEl.getAttribute('schemaVersion') || '1'),
       width: parseInt(layoutEl.getAttribute('width') || '1920'),
       height: parseInt(layoutEl.getAttribute('height') || '1080'),
       duration: layoutDurationAttr ? parseInt(layoutDurationAttr) : 0, // 0 = calculate from widgets
-      bgcolor: layoutEl.getAttribute('bgcolor') || '#000000',
+      bgcolor: layoutEl.getAttribute('backgroundColor') || layoutEl.getAttribute('bgcolor') || '#000000',
       background: layoutEl.getAttribute('background') || null, // Background image fileId
       enableStat: layoutEl.getAttribute('enableStat') !== '0', // absent or "1" = enabled
+      actions: this.parseActions(layoutEl),
       regions: []
     };
 
+    if (layout.schemaVersion > 1) {
+      this.log.debug(`XLF schema version: ${layout.schemaVersion}`);
+    }
+
     if (layoutDurationAttr) {
       this.log.info(`Layout duration from XLF: ${layout.duration}s`);
     } else {
       this.log.info(`Layout duration NOT in XLF, will calculate from widgets`);
     }
 
-    // Parse regions
-    for (const regionEl of doc.querySelectorAll('region')) {
+    // Parse regions and drawers (drawers are invisible regions for interactive actions)
+    const regionAndDrawerEls = layoutEl.querySelectorAll(':scope > region, :scope > drawer');
+    for (const regionEl of regionAndDrawerEls) {
+      const isDrawer = regionEl.tagName === 'drawer';
       const region = {
         id: regionEl.getAttribute('id'),
-        width: parseInt(regionEl.getAttribute('width')),
-        height: parseInt(regionEl.getAttribute('height')),
-        top: parseInt(regionEl.getAttribute('top')),
-        left: parseInt(regionEl.getAttribute('left')),
-        zindex: parseInt(regionEl.getAttribute('zindex') || '0'),
+        width: parseInt(regionEl.getAttribute('width') || '0'),
+        height: parseInt(regionEl.getAttribute('height') || '0'),
+        top: parseInt(regionEl.getAttribute('top') || '0'),
+        left: parseInt(regionEl.getAttribute('left') || '0'),
+        zindex: parseInt(regionEl.getAttribute('zindex') || (isDrawer ? '2000' : '0')),
+        enableStat: regionEl.getAttribute('enableStat') !== '0',
         actions: this.parseActions(regionEl),
+        exitTransition: null,
+        transitionType: null, // Region-level default widget transition type
+        transitionDuration: null,
+        transitionDirection: null,
+        loop: true, // Default: cycle widgets. Spec: loop=0 means single media stays visible
+        isDrawer,
         widgets: []
       };
 
-      // Parse media/widgets
-      for (const mediaEl of regionEl.querySelectorAll('media')) {
-        const widget = this.parseWidget(mediaEl);
+      // Parse region-level options (exit transitions, loop)
+      // Use direct children only to avoid matching <options> inside <media>
+      const regionOptionsEl = Array.from(regionEl.children).find(el => el.tagName === 'options');
+      if (regionOptionsEl) {
+        const exitTransType = regionOptionsEl.querySelector('exitTransType');
+        if (exitTransType && exitTransType.textContent) {
+          const exitTransDuration = regionOptionsEl.querySelector('exitTransDuration');
+          const exitTransDirection = regionOptionsEl.querySelector('exitTransDirection');
+          region.exitTransition = {
+            type: exitTransType.textContent,
+            duration: parseInt((exitTransDuration && exitTransDuration.textContent) || '1000'),
+            direction: (exitTransDirection && exitTransDirection.textContent) || 'N'
+          };
+        }
+
+        // Region loop option: 0 = single media stays on screen, 1 = cycles (default)
+        const loopEl = regionOptionsEl.querySelector('loop');
+        if (loopEl) {
+          region.loop = loopEl.textContent !== '0';
+        }
+
+        // Region-level default transition for widgets (applied if widget has no own transition)
+        const transType = regionOptionsEl.querySelector('transitionType');
+        if (transType && transType.textContent) {
+          region.transitionType = transType.textContent;
+          const transDuration = regionOptionsEl.querySelector('transitionDuration');
+          const transDirection = regionOptionsEl.querySelector('transitionDirection');
+          region.transitionDuration = parseInt((transDuration && transDuration.textContent) || '1000');
+          region.transitionDirection = (transDirection && transDirection.textContent) || 'N';
+        }
+      }
+
+      // Parse media/widgets (use direct children to avoid nested matches)
+      for (const child of regionEl.children) {
+        if (child.tagName !== 'media') continue;
+        const widget = this.parseWidget(child);
         region.widgets.push(widget);
       }
 
       layout.regions.push(region);
+
+      if (isDrawer) {
+        this.log.info(`Parsed drawer: id=${region.id} with ${region.widgets.length} widgets`);
+      }
     }
 
     // Calculate layout duration if not specified (duration=0)
+    // Drawers don't contribute to layout duration (they're action-triggered)
     if (layout.duration === 0) {
       let maxDuration = 0;
 
       for (const region of layout.regions) {
+        if (region.isDrawer) continue;
         let regionDuration = 0;
 
         // Calculate region duration based on widgets
@@ -490,17 +555,84 @@ export class RendererLite {
     // Parse widget-level actions
     const actions = this.parseActions(mediaEl);
 
+    // Parse audio overlay nodes (<audio> child elements on the widget)
+    // Spec format: <audio><uri volume="" loop="" mediaId="">filename.mp3</uri></audio>
+    // Also supports flat format: <audio mediaId="" uri="" volume="" loop="">
+    const audioNodes = [];
+    for (const child of mediaEl.children) {
+      if (child.tagName.toLowerCase() === 'audio') {
+        const uriEl = child.querySelector('uri');
+        if (uriEl) {
+          // Spec format: attributes on <uri>, filename as text content
+          audioNodes.push({
+            mediaId: uriEl.getAttribute('mediaId') || null,
+            uri: uriEl.textContent || '',
+            volume: parseInt(uriEl.getAttribute('volume') || '100'),
+            loop: uriEl.getAttribute('loop') === '1'
+          });
+        } else {
+          // Flat format fallback: attributes directly on <audio>
+          audioNodes.push({
+            mediaId: child.getAttribute('mediaId') || null,
+            uri: child.getAttribute('uri') || '',
+            volume: parseInt(child.getAttribute('volume') || '100'),
+            loop: child.getAttribute('loop') === '1'
+          });
+        }
+      }
+    }
+
+    // Parse commands on media (shell/native commands triggered on widget start)
+    // Spec: <commands><command commandCode="code" commandString="args"/></commands>
+    const commands = [];
+    const commandsEl = Array.from(mediaEl.children).find(el => el.tagName === 'commands');
+    if (commandsEl) {
+      for (const cmdEl of commandsEl.children) {
+        if (cmdEl.tagName === 'command') {
+          commands.push({
+            commandCode: cmdEl.getAttribute('commandCode') || '',
+            commandString: cmdEl.getAttribute('commandString') || ''
+          });
+        }
+      }
+    }
+
+    // Sub-playlist attributes (widgets grouped by parentWidgetId)
+    const parentWidgetId = mediaEl.getAttribute('parentWidgetId') || null;
+    const displayOrder = parseInt(mediaEl.getAttribute('displayOrder') || '0');
+    const cyclePlayback = mediaEl.getAttribute('cyclePlayback') === '1';
+    const playCount = parseInt(mediaEl.getAttribute('playCount') || '0');
+    const isRandom = mediaEl.getAttribute('isRandom') === '1';
+
+    // Media expiry dates (per-widget time-gating within a layout)
+    const fromDt = mediaEl.getAttribute('fromDt') || mediaEl.getAttribute('fromdt') || null;
+    const toDt = mediaEl.getAttribute('toDt') || mediaEl.getAttribute('todt') || null;
+
+    // Render mode: 'native' (player renders directly) or 'html' (use GetResource)
+    const render = mediaEl.getAttribute('render') || null;
+
     return {
       type,
       duration,
       useDuration, // Whether to use specified duration (1) or media length (0)
       id,
       fileId, // Media library file ID for cache lookup
+      render, // 'native' or 'html' — null means use type-based dispatch
+      fromDt, // Widget valid-from date (Y-m-d H:i:s)
+      toDt, // Widget valid-to date (Y-m-d H:i:s)
       enableStat: mediaEl.getAttribute('enableStat') !== '0', // absent or "1" = enabled
+      webhookUrl: options.webhookUrl || null,
       options,
       raw,
       transitions,
-      actions
+      actions,
+      audioNodes, // Audio overlays attached to this widget
+      commands, // Shell commands triggered on widget start
+      parentWidgetId,
+      displayOrder,
+      cyclePlayback,
+      playCount,
+      isRandom
     };
   }
 
@@ -544,6 +676,7 @@ export class RendererLite {
     let maxRegionDuration = 0;
 
     for (const region of this.currentLayout.regions) {
+      if (region.isDrawer) continue;
       let regionDuration = 0;
 
       for (const widget of region.widgets) {
@@ -601,6 +734,16 @@ export class RendererLite {
     const allKeyboardActions = [];
     let touchActionCount = 0;
 
+    // Layout-level actions (attached to the main container)
+    for (const action of (layout.actions || [])) {
+      if (action.triggerType === 'touch') {
+        this.attachTouchAction(this.container, action, null, null);
+        touchActionCount++;
+      } else if (action.triggerType?.startsWith('keyboard:')) {
+        allKeyboardActions.push(action);
+      }
+    }
+
     for (const regionConfig of layout.regions) {
       const region = this.regions.get(regionConfig.id);
       if (!region) continue;
@@ -737,6 +880,12 @@ export class RendererLite {
 
       this.log.info(`Navigating to widget ${targetWidgetId} in region ${regionId} (index ${widgetIndex})`);
 
+      // Show drawer region if hidden (drawers start display:none)
+      if (region.isDrawer && region.element.style.display === 'none') {
+        region.element.style.display = '';
+        this.log.info(`Drawer region ${regionId} revealed`);
+      }
+
       if (region.timer) {
         clearTimeout(region.timer);
         region.timer = null;
@@ -753,7 +902,22 @@ export class RendererLite {
           this.stopWidget(regionId, widgetIndex);
           const nextIndex = (widgetIndex + 1) % region.widgets.length;
           region.currentIndex = nextIndex;
-          this.startRegion(regionId);
+          // For drawers, hide again after last widget; for normal regions, continue cycling
+          if (region.isDrawer && nextIndex === 0) {
+            region.element.style.display = 'none';
+            this.log.info(`Drawer region ${regionId} hidden (cycle complete)`);
+          } else {
+            this.startRegion(regionId);
+          }
+        }, duration);
+      } else if (region.isDrawer) {
+        // Single-widget drawer: hide after widget duration
+        const widget = region.widgets[widgetIndex];
+        const duration = widget.duration * 1000;
+        region.timer = setTimeout(() => {
+          this.stopWidget(regionId, widgetIndex);
+          region.element.style.display = 'none';
+          this.log.info(`Drawer region ${regionId} hidden (single widget done)`);
         }, duration);
       }
       return;
@@ -832,8 +996,9 @@ export class RendererLite {
         // Emit layout start event
         this.emit('layoutStart', layoutId, this.currentLayout);
 
-        // Restart all regions from widget 0
+        // Restart all regions from widget 0 (except drawers)
         for (const [regionId, region] of this.regions) {
+          if (region.isDrawer) continue;
           this.startRegion(regionId);
         }
 
@@ -950,8 +1115,9 @@ export class RendererLite {
       // Emit layout start event
       this.emit('layoutStart', layoutId, layout);
 
-      // Start all regions
+      // Start all regions (except drawers — they're action-triggered)
       for (const [regionId, region] of this.regions) {
+        if (region.isDrawer) continue;
         this.startRegion(regionId);
       }
 
@@ -983,22 +1149,36 @@ export class RendererLite {
     regionEl.style.zIndex = regionConfig.zindex;
     regionEl.style.overflow = 'hidden';
 
+    // Drawer regions start fully hidden — shown only by navWidget actions
+    if (regionConfig.isDrawer) {
+      regionEl.style.display = 'none';
+    }
+
     // Apply scaled positioning
     this.applyRegionScale(regionEl, regionConfig);
 
     this.container.appendChild(regionEl);
 
+    // Filter expired widgets (fromDt/toDt time-gating within XLF)
+    let widgets = regionConfig.widgets.filter(w => this._isWidgetActive(w));
+
+    // For regions with sub-playlist cycle playback, select which widgets play this cycle
+    if (widgets.some(w => w.cyclePlayback)) {
+      widgets = this._applyCyclePlayback(widgets);
+    }
+
     // Store region state (dimensions use scaled values for transitions)
     const sf = this.scaleFactor;
     this.regions.set(regionConfig.id, {
       element: regionEl,
       config: regionConfig,
-      widgets: regionConfig.widgets,
+      widgets,
       currentIndex: 0,
       timer: null,
       width: regionConfig.width * sf,
       height: regionConfig.height * sf,
       complete: false, // Track if region has played all widgets once
+      isDrawer: regionConfig.isDrawer || false,
       widgetElements: new Map() // widgetId -> DOM element (for element reuse)
     });
   }
@@ -1027,6 +1207,11 @@ export class RendererLite {
    * @returns {Promise<HTMLElement>} Widget DOM element
    */
   async createWidgetElement(widget, region) {
+    // render="html" forces GetResource iframe regardless of native type
+    if (widget.render === 'html') {
+      return await this.renderGenericWidget(widget, region);
+    }
+
     switch (widget.type) {
       case 'image':
         return await this.renderImage(widget, region);
@@ -1041,6 +1226,13 @@ export class RendererLite {
         return await this.renderPdf(widget, region);
       case 'webpage':
         return await this.renderWebpage(widget, region);
+      case 'localvideo':
+        return await this.renderVideo(widget, region);
+      case 'powerpoint':
+      case 'flash':
+        // Legacy Windows-only types — show placeholder instead of failing silently
+        this.log.warn(`Widget type '${widget.type}' is not supported on web players (widget ${widget.id})`);
+        return this._renderUnsupportedPlaceholder(widget, region);
       default:
         // Generic widget (clock, calendar, weather, etc.)
         return await this.renderGenericWidget(widget, region);
@@ -1125,6 +1317,27 @@ export class RendererLite {
       });
     }
 
+    // Audio widgets: wait for playback to start
+    const audioEl = this.findMediaElement(element, 'AUDIO');
+    if (audioEl) {
+      if (!audioEl.paused && audioEl.readyState >= 3) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          this.log.warn(`Audio ready timeout (${READY_TIMEOUT}ms) for widget ${widget.id}`);
+          resolve();
+        }, READY_TIMEOUT);
+        const onPlaying = () => {
+          audioEl.removeEventListener('playing', onPlaying);
+          clearTimeout(timer);
+          this.log.info(`Audio widget ${widget.id} ready (playing)`);
+          resolve();
+        };
+        audioEl.addEventListener('playing', onPlaying);
+      });
+    }
+
     // Image widgets: wait for image decode
     const imgEl = this.findMediaElement(element, 'IMG');
     if (imgEl) {
@@ -1235,9 +1448,86 @@ export class RendererLite {
       element.style.opacity = '1';
     }
 
+    // Start audio overlays attached to this widget
+    this._startAudioOverlays(widget);
+
     return widget;
   }
 
+  /**
+   * Start audio overlay elements for a widget.
+   * Audio overlays are <audio> child nodes in the XLF that play alongside
+   * the visual widget (e.g. background music for an image slideshow).
+   * @param {Object} widget - Widget config with audioNodes array
+   */
+  _startAudioOverlays(widget) {
+    if (!widget.audioNodes || widget.audioNodes.length === 0) return;
+
+    // Stop any existing audio overlays for this widget first
+    this._stopAudioOverlays(widget.id);
+
+    const audioElements = [];
+    for (const audioNode of widget.audioNodes) {
+      if (!audioNode.uri) continue;
+
+      const audio = document.createElement('audio');
+      audio.autoplay = true;
+      audio.loop = audioNode.loop;
+      audio.volume = Math.max(0, Math.min(1, audioNode.volume / 100));
+
+      // Resolve audio URI via cache/proxy
+      const mediaId = parseInt(audioNode.mediaId);
+      let audioSrc = mediaId ? this.mediaUrlCache.get(mediaId) : null;
+
+      if (!audioSrc && mediaId && this.options.getMediaUrl) {
+        // Async — fire and forget, set src when ready
+        this.options.getMediaUrl(mediaId).then(url => {
+          audio.src = url;
+        }).catch(() => {
+          audio.src = `${window.location.origin}/player/cache/media/${audioNode.uri}`;
+        });
+      } else if (!audioSrc) {
+        audio.src = `${window.location.origin}/player/cache/media/${audioNode.uri}`;
+      } else {
+        audio.src = audioSrc;
+      }
+
+      // Append to DOM to prevent garbage collection in some browsers
+      audio.style.display = 'none';
+      this.container.appendChild(audio);
+
+      // Handle autoplay restrictions gracefully (play() may return undefined in some envs)
+      const playPromise = audio.play();
+      if (playPromise && playPromise.catch) playPromise.catch(() => {});
+
+      audioElements.push(audio);
+      this.log.info(`Audio overlay started for widget ${widget.id}: ${audioNode.uri} (loop=${audioNode.loop}, vol=${audioNode.volume})`);
+    }
+
+    if (audioElements.length > 0) {
+      this.audioOverlays.set(widget.id, audioElements);
+    }
+  }
+
+  /**
+   * Stop and clean up audio overlay elements for a widget.
+   * @param {string} widgetId - Widget ID
+   */
+  _stopAudioOverlays(widgetId) {
+    const audioElements = this.audioOverlays.get(widgetId);
+    if (!audioElements) return;
+
+    for (const audio of audioElements) {
+      audio.pause();
+      audio.removeAttribute('src');
+      audio.load(); // Release resources
+      if (audio.parentNode) audio.parentNode.removeChild(audio); // Remove from DOM
+    }
+
+    this.audioOverlays.delete(widgetId);
+    this.log.info(`Audio overlays stopped for widget ${widgetId}`);
+  }
+
   /**
    * Core: hide a widget in a region (shared by main layout + overlay).
    * Returns { widget, animPromise } synchronously — callers await animPromise if needed.
@@ -1266,9 +1556,115 @@ export class RendererLite {
     const audioEl = widgetElement.querySelector('audio');
     if (audioEl && widget.options.loop !== '1') audioEl.pause();
 
+    // Stop audio overlays attached to this widget
+    this._stopAudioOverlays(widget.id);
+
     return { widget, animPromise };
   }
 
+  /**
+   * Check if a widget is within its valid time window (fromDt/toDt).
+   * Widgets without dates are always active.
+   * @param {Object} widget - Widget config with optional fromDt/toDt
+   * @returns {boolean}
+   */
+  _isWidgetActive(widget) {
+    const now = new Date();
+    if (widget.fromDt) {
+      const from = new Date(widget.fromDt);
+      if (now < from) return false;
+    }
+    if (widget.toDt) {
+      const to = new Date(widget.toDt);
+      if (now > to) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Parse NUMITEMS and DURATION HTML comments from GetResource responses.
+   * CMS embeds these in widget HTML to override duration for dynamic content
+   * (e.g. DataSet tickers, RSS feeds). Format: <!-- NUMITEMS=5 --> <!-- DURATION=30 -->
+   * DURATION takes precedence; otherwise NUMITEMS × widget.duration is used.
+   * @param {string} html - Widget HTML content
+   * @param {Object} widget - Widget config (duration may be updated)
+   */
+  _parseDurationComments(html, widget) {
+    const durationMatch = html.match(/<!--\s*DURATION=(\d+)\s*-->/);
+    if (durationMatch) {
+      const newDuration = parseInt(durationMatch[1], 10);
+      if (newDuration > 0) {
+        this.log.info(`Widget ${widget.id}: DURATION comment overrides duration ${widget.duration}→${newDuration}s`);
+        widget.duration = newDuration;
+        return;
+      }
+    }
+
+    const numItemsMatch = html.match(/<!--\s*NUMITEMS=(\d+)\s*-->/);
+    if (numItemsMatch) {
+      const numItems = parseInt(numItemsMatch[1], 10);
+      if (numItems > 0 && widget.duration > 0) {
+        const newDuration = numItems * widget.duration;
+        this.log.info(`Widget ${widget.id}: NUMITEMS=${numItems} × ${widget.duration}s = ${newDuration}s`);
+        widget.duration = newDuration;
+      }
+    }
+  }
+
+  /**
+   * Apply sub-playlist cycle playback filtering.
+   * Groups widgets by parentWidgetId, then selects one widget per group for this cycle.
+   * Non-grouped widgets pass through unchanged.
+   *
+   * @param {Array} widgets - All widgets in the region
+   * @returns {Array} Filtered widgets for this playback cycle
+   */
+  _applyCyclePlayback(widgets) {
+    // Track cycle indices per group for deterministic round-robin
+    if (!this._subPlaylistCycleIndex) {
+      this._subPlaylistCycleIndex = new Map();
+    }
+
+    // Group widgets by parentWidgetId
+    const groups = new Map(); // parentWidgetId → [widgets]
+    const result = [];
+
+    for (const widget of widgets) {
+      if (widget.parentWidgetId && widget.cyclePlayback) {
+        if (!groups.has(widget.parentWidgetId)) {
+          groups.set(widget.parentWidgetId, []);
+        }
+        groups.get(widget.parentWidgetId).push(widget);
+      } else {
+        // Non-grouped widget: add a placeholder to preserve order
+        result.push({ type: 'direct', widget });
+      }
+    }
+
+    // For each group, select one widget for this cycle
+    for (const [groupId, groupWidgets] of groups) {
+      // Sort by displayOrder
+      groupWidgets.sort((a, b) => a.displayOrder - b.displayOrder);
+
+      let selectedWidget;
+      if (groupWidgets.some(w => w.isRandom)) {
+        // Random selection
+        const idx = Math.floor(Math.random() * groupWidgets.length);
+        selectedWidget = groupWidgets[idx];
+      } else {
+        // Round-robin based on cycle index
+        const cycleIdx = this._subPlaylistCycleIndex.get(groupId) || 0;
+        selectedWidget = groupWidgets[cycleIdx % groupWidgets.length];
+        this._subPlaylistCycleIndex.set(groupId, cycleIdx + 1);
+      }
+
+      this.log.info(`Sub-playlist cycle: group ${groupId} selected widget ${selectedWidget.id} (${groupWidgets.length} in group)`);
+      result.push({ type: 'direct', widget: selectedWidget });
+    }
+
+    return result.map(r => r.widget);
+  }
+
   /**
    * Core: cycle through widgets in a region (shared by main layout + overlay)
    * @param {Object} region - Region state object
@@ -1280,6 +1676,7 @@ export class RendererLite {
   _startRegionCycle(region, regionId, showFn, hideFn, onCycleComplete) {
     if (!region || region.widgets.length === 0) return;
 
+    // Non-looping region with a single widget: show it and stay (spec: loop=0)
     if (region.widgets.length === 1) {
       showFn(regionId, 0);
       return;
@@ -1293,22 +1690,47 @@ export class RendererLite {
 
       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();
+        this._handleWidgetCycleEnd(widget, region, regionId, widgetIndex, showFn, hideFn, onCycleComplete, playNext);
       }, duration);
     };
 
     playNext();
   }
 
+  /**
+   * Handle widget cycle end — shared logic for timer-based and event-based cycling
+   */
+  _handleWidgetCycleEnd(widget, region, regionId, widgetIndex, showFn, hideFn, onCycleComplete, playNext) {
+    // Emit widgetAction if widget has a webhook URL configured
+    if (widget.webhookUrl) {
+      this.emit('widgetAction', {
+        type: 'durationEnd',
+        widgetId: widget.id,
+        layoutId: this.currentLayoutId,
+        regionId,
+        url: widget.webhookUrl
+      });
+    }
+
+    hideFn(regionId, widgetIndex);
+
+    const nextIndex = (region.currentIndex + 1) % region.widgets.length;
+    if (nextIndex === 0 && !region.complete) {
+      region.complete = true;
+      onCycleComplete?.();
+    }
+
+    // Non-looping region (loop=0): stop after one full cycle
+    if (nextIndex === 0 && region.config?.loop === false) {
+      // Show the last widget again and keep it visible
+      showFn(regionId, region.widgets.length - 1);
+      return;
+    }
+
+    region.currentIndex = nextIndex;
+    playNext();
+  }
+
   async renderWidget(regionId, widgetIndex) {
     const region = this.regions.get(regionId);
     if (!region) return;
@@ -1323,6 +1745,19 @@ export class RendererLite {
           type: widget.type, duration: widget.duration,
           enableStat: widget.enableStat
         });
+
+        // Execute commands attached to this widget (shell/native commands)
+        if (widget.commands && widget.commands.length > 0) {
+          for (const cmd of widget.commands) {
+            this.emit('widgetCommand', {
+              commandCode: cmd.commandCode,
+              commandString: cmd.commandString,
+              widgetId: widget.id,
+              regionId,
+              layoutId: this.currentLayoutId
+            });
+          }
+        }
       }
     } catch (error) {
       this.log.error(`Error rendering widget:`, error);
@@ -1359,7 +1794,18 @@ export class RendererLite {
     img.className = 'renderer-lite-widget';
     img.style.width = '100%';
     img.style.height = '100%';
-    img.style.objectFit = 'contain';
+    // Scale type: stretch → fill, center → none (natural size), default → contain
+    const scaleType = widget.options.scaleType;
+    const fitMap = { stretch: 'fill', center: 'none', fit: 'contain' };
+    img.style.objectFit = fitMap[scaleType] || 'contain';
+
+    // Alignment: map align/valign to CSS object-position
+    const alignMap = { left: 'left', center: 'center', right: 'right' };
+    const valignMap = { top: 'top', middle: 'center', bottom: 'bottom' };
+    const hPos = alignMap[widget.options.align] || 'center';
+    const vPos = valignMap[widget.options.valign] || 'center';
+    img.style.objectPosition = `${hPos} ${vPos}`;
+
     img.style.opacity = '0';
 
     // Get media URL from cache (already pre-fetched!) or fetch on-demand
@@ -1384,7 +1830,9 @@ export class RendererLite {
     video.className = 'renderer-lite-widget';
     video.style.width = '100%';
     video.style.height = '100%';
-    video.style.objectFit = 'contain';
+    const vScaleType = widget.options.scaleType;
+    const vFitMap = { stretch: 'fill', center: 'none', fit: 'contain' };
+    video.style.objectFit = vFitMap[vScaleType] || 'contain';
     video.style.opacity = '1'; // Immediately visible
     video.autoplay = true;
     video.preload = 'auto'; // Eagerly buffer - chunks are pre-warmed in SW BlobCache
@@ -1528,6 +1976,34 @@ export class RendererLite {
 
     audio.src = audioSrc;
 
+    // Handle audio end - similar to video ended handling
+    audio.addEventListener('ended', () => {
+      if (widget.options.loop === '1') {
+        audio.currentTime = 0;
+        this.log.info(`Audio ${fileId} ended - reset to start, waiting for widget cycle to replay`);
+      } else {
+        this.log.info(`Audio ${fileId} ended - playback complete`);
+      }
+    });
+
+    // Detect audio duration for dynamic layout timing (when useDuration=0)
+    audio.addEventListener('loadedmetadata', () => {
+      const audioDuration = Math.floor(audio.duration);
+      this.log.info(`Audio ${fileId} duration detected: ${audioDuration}s`);
+
+      if (widget.duration === 0 || widget.useDuration === 0) {
+        widget.duration = audioDuration;
+        this.log.info(`Updated widget ${widget.id} duration to ${audioDuration}s (useDuration=0)`);
+        this.updateLayoutDuration();
+      }
+    });
+
+    // Handle audio errors
+    audio.addEventListener('error', () => {
+      const error = audio.error;
+      this.log.warn(`Audio error (non-fatal): ${fileId}, code: ${error?.code}, message: ${error?.message || 'Unknown'}`);
+    });
+
     // Visual feedback
     const icon = document.createElement('div');
     icon.innerHTML = '♪';
@@ -1581,7 +2057,7 @@ export class RendererLite {
             try {
               // Our cached widget HTML has a <base> tag; server 404 page doesn't
               if (!iframe.contentDocument?.querySelector('base')) {
-                console.warn('[RendererLite] Cache URL failed (hard reload?), using original CMS URLs');
+                self.log.warn('Cache URL failed (hard reload?), using original CMS URLs');
                 const blob = new Blob([result.fallback], { type: 'text/html' });
                 const blobUrl = URL.createObjectURL(blob);
                 self.trackBlobUrl(blobUrl);
@@ -1591,11 +2067,21 @@ export class RendererLite {
           }, { once: true });
         }
 
+        // Parse NUMITEMS/DURATION from fallback HTML (cache path)
+        if (result.fallback) {
+          this._parseDurationComments(result.fallback, widget);
+        }
+
         return iframe;
       }
       html = result;
     }
 
+    if (html) {
+      // Parse NUMITEMS/DURATION HTML comments for dynamic widget duration
+      this._parseDurationComments(html, widget);
+    }
+
     // Fallback: Create blob URL for iframe
     const blob = new Blob([html], { type: 'text/html' });
     const blobUrl = URL.createObjectURL(blob);
@@ -1680,6 +2166,13 @@ export class RendererLite {
    * Render webpage widget
    */
   async renderWebpage(widget, region) {
+    // modeId=1 (or absent) = Open Natively (direct URL), modeId=0 = Manual/GetResource
+    const modeId = parseInt(widget.options.modeId || '1');
+    if (modeId === 0) {
+      // GetResource mode: treat like a generic widget (fetch HTML from CMS)
+      return await this.renderGenericWidget(widget, region);
+    }
+
     const iframe = document.createElement('iframe');
     iframe.className = 'renderer-lite-widget';
     iframe.style.width = '100%';
@@ -1718,7 +2211,7 @@ export class RendererLite {
             try {
               // Our cached widget HTML has a <base> tag; server 404 page doesn't
               if (!iframe.contentDocument?.querySelector('base')) {
-                console.warn('[RendererLite] Cache URL failed (hard reload?), using original CMS URLs');
+                self.log.warn('Cache URL failed (hard reload?), using original CMS URLs');
                 const blob = new Blob([result.fallback], { type: 'text/html' });
                 const blobUrl = URL.createObjectURL(blob);
                 self.trackBlobUrl(blobUrl);
@@ -1728,12 +2221,21 @@ export class RendererLite {
           }, { once: true });
         }
 
+        // Parse NUMITEMS/DURATION from fallback HTML (cache path)
+        if (result.fallback) {
+          this._parseDurationComments(result.fallback, widget);
+        }
+
         return iframe;
       }
       html = result;
     }
 
     if (html) {
+      // Parse NUMITEMS/DURATION HTML comments for dynamic widget duration
+      // Format: <!-- NUMITEMS=5 --> and <!-- DURATION=30 -->
+      this._parseDurationComments(html, widget);
+
       const blob = new Blob([html], { type: 'text/html' });
       const blobUrl = URL.createObjectURL(blob);
       iframe.src = blobUrl;
@@ -1748,6 +2250,24 @@ export class RendererLite {
     return iframe;
   }
 
+  /**
+   * Render a placeholder for unsupported widget types (powerpoint, flash)
+   */
+  _renderUnsupportedPlaceholder(widget, region) {
+    const div = document.createElement('div');
+    div.className = 'renderer-lite-widget';
+    div.style.width = '100%';
+    div.style.height = '100%';
+    div.style.display = 'flex';
+    div.style.alignItems = 'center';
+    div.style.justifyContent = 'center';
+    div.style.backgroundColor = '#111';
+    div.style.color = '#666';
+    div.style.fontSize = '14px';
+    div.textContent = `Unsupported: ${widget.type}`;
+    return div;
+  }
+
   // ── Layout Preload Pool ─────────────────────────────────────────────
 
   /**
@@ -2030,7 +2550,21 @@ export class RendererLite {
           v.removeAttribute('src');
           v.load();
         });
-        region.element.remove();
+        // Apply region exit transition if configured, then remove
+        if (region.config && region.config.exitTransition) {
+          const animation = Transitions.apply(
+            region.element, region.config.exitTransition, false,
+            region.width, region.height
+          );
+          if (animation) {
+            const el = region.element;
+            animation.onfinish = () => el.remove();
+          } else {
+            region.element.remove();
+          }
+        } else {
+          region.element.remove();
+        }
       }
       // Revoke blob URLs
       if (oldLayoutId) {
@@ -2178,8 +2712,22 @@ export class RendererLite {
           this.stopWidget(regionId, region.currentIndex);
         }
 
-        // Remove region element
-        region.element.remove();
+        // Apply region exit transition if configured, then remove
+        if (region.config && region.config.exitTransition) {
+          const animation = Transitions.apply(
+            region.element, region.config.exitTransition, false,
+            region.width, region.height
+          );
+          if (animation) {
+            // Remove element after exit transition completes
+            const el = region.element;
+            animation.onfinish = () => el.remove();
+          } else {
+            region.element.remove();
+          }
+        } else {
+          region.element.remove();
+        }
       }
 
       // Revoke media blob URLs from cache
@@ -2528,6 +3076,13 @@ export class RendererLite {
     this.log.info('Playback paused');
   }
 
+  /**
+   * Check if playback is currently paused.
+   */
+  isPaused() {
+    return this._paused;
+  }
+
   /**
    * Resume playback: restart layout timer with remaining time, resume media and widget cycling.
    */
@@ -2578,6 +3133,11 @@ export class RendererLite {
     this.stopAllOverlays();
     this.stopCurrentLayout();
 
+    // Clean up any remaining audio overlays
+    for (const widgetId of this.audioOverlays.keys()) {
+      this._stopAudioOverlays(widgetId);
+    }
+
     // Clear the layout preload pool
     this.layoutPool.clear();