@xiboplayer/renderer 0.6.1 → 0.6.3

package/src/renderer-lite.js

@@ -41,12 +41,13 @@
 
 import { createNanoEvents } from 'nanoevents';
 import { createLogger, isDebug, PLAYER_API } from '@xiboplayer/utils';
+import { parseLayoutDuration } from '@xiboplayer/schedule';
 import { LayoutPool } from './layout-pool.js';
 
 /**
  * Transition utilities for widget animations
  */
-const Transitions = {
+export const Transitions = {
   /**
    * Apply fade in transition
    */
@@ -161,11 +162,15 @@ const Transitions = {
 
     switch (type) {
       case 'fade':
+        return isIn ? this.fadeIn(element, duration) : this.fadeOut(element, duration);
       case 'fadein':
         return isIn ? this.fadeIn(element, duration) : null;
       case 'fadeout':
         return isIn ? null : this.fadeOut(element, duration);
       case 'fly':
+        return isIn
+          ? this.flyIn(element, duration, direction, regionWidth, regionHeight)
+          : this.flyOut(element, duration, direction, regionWidth, regionHeight);
       case 'flyin':
         return isIn ? this.flyIn(element, duration, direction, regionWidth, regionHeight) : null;
       case 'flyout':
@@ -186,7 +191,7 @@ export class RendererLite {
    * @param {string} config.hardwareKey - Display hardware key
    * @param {HTMLElement} container - DOM container for rendering
    * @param {Object} options - Renderer options
-   * @param {Function} options.getMediaUrl - Function to get media file URL (mediaId) => url
+   * @param {Map<string,string>} [options.fileIdToSaveAs] - Map from numeric file ID to storedAs filename (for layout backgrounds)
    * @param {Function} options.getWidgetHtml - Function to get widget HTML (layoutId, regionId, widgetId) => html
    */
   constructor(config, container, options = {}) {
@@ -203,6 +208,7 @@ export class RendererLite {
     // State
     this.currentLayout = null;
     this.currentLayoutId = null;
+    this._preloadingLayoutId = null; // Set during preload for blob URL tracking
     this.regions = new Map(); // regionId => { element, widgets, currentIndex, timer }
     this.layoutTimer = null;
     this.layoutEndEmitted = false; // Prevents double layoutEnd on stop after timer
@@ -210,7 +216,6 @@ export class RendererLite {
     this._layoutTimerStartedAt = null;  // Date.now() when layout timer started
     this._layoutTimerDurationMs = null; // Total layout duration in ms
     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)
 
@@ -238,6 +243,12 @@ export class RendererLite {
     // Setup container styles
     this.setupContainer();
 
+    // Interactive Control (XIC) event handlers
+    this.emitter.on('interactiveTrigger', (data) => this._handleInteractiveTrigger(data));
+    this.emitter.on('widgetExpire', (data) => this._handleWidgetExpire(data));
+    this.emitter.on('widgetExtendDuration', (data) => this._handleWidgetExtendDuration(data));
+    this.emitter.on('widgetSetDuration', (data) => this._handleWidgetSetDuration(data));
+
     this.log.info('Initialized');
   }
 
@@ -410,6 +421,7 @@ export class RendererLite {
     const regionAndDrawerEls = layoutEl.querySelectorAll(':scope > region, :scope > drawer');
     for (const regionEl of regionAndDrawerEls) {
       const isDrawer = regionEl.tagName === 'drawer';
+      const regionType = regionEl.getAttribute('type') || null;
       const region = {
         id: regionEl.getAttribute('id'),
         width: parseInt(regionEl.getAttribute('width') || '0'),
@@ -425,6 +437,7 @@ export class RendererLite {
         transitionDirection: null,
         loop: true, // Default: cycle widgets. Spec: loop=0 means single media stays visible
         isDrawer,
+        isCanvas: regionType === 'canvas', // Canvas regions render all widgets simultaneously
         widgets: []
       };
 
@@ -467,39 +480,28 @@ export class RendererLite {
         region.widgets.push(widget);
       }
 
+      // Auto-detect canvas from CMS "global" widget (CMS bundles canvas sub-widgets
+      // into a single type="global" media element in the XLF)
+      if (!region.isCanvas && region.widgets.some(w => w.type === 'global')) {
+        region.isCanvas = true;
+      }
+
       layout.regions.push(region);
 
       if (isDrawer) {
         this.log.info(`Parsed drawer: id=${region.id} with ${region.widgets.length} widgets`);
       }
+
+      if (region.isCanvas) {
+        this.log.info(`Parsed canvas region: id=${region.id} with ${region.widgets.length} widgets (all render simultaneously)`);
+      }
     }
 
     // Calculate layout duration if not specified (duration=0)
-    // Drawers don't contribute to layout duration (they're action-triggered)
+    // Uses shared parseLayoutDuration() — single source of truth for XLF-based duration calc
     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
-        for (const widget of region.widgets) {
-          if (widget.duration > 0) {
-            regionDuration += widget.duration;
-          } else {
-            // Widget with duration=0 means "use media length"
-            // Default to 60s here; actual duration is detected dynamically
-            // from video.loadedmetadata event and updateLayoutDuration() recalculates
-            regionDuration = 60;
-            break;
-          }
-        }
-
-        maxDuration = Math.max(maxDuration, regionDuration);
-      }
-
-      layout.duration = maxDuration > 0 ? maxDuration : 60;
+      const { duration } = parseLayoutDuration(xlfXml);
+      layout.duration = duration;
       this.log.info(`Calculated layout duration: ${layout.duration}s (not specified in XLF)`);
     }
 
@@ -642,7 +644,7 @@ export class RendererLite {
    * @param {string} blobUrl - Blob URL to track
    */
   trackBlobUrl(blobUrl) {
-    const layoutId = this.currentLayoutId || 0;
+    const layoutId = this._preloadingLayoutId || this.currentLayoutId || 0;
 
     if (!layoutId) {
       this.log.warn('trackBlobUrl called without currentLayoutId, tracking under key 0');
@@ -693,10 +695,10 @@ export class RendererLite {
       maxRegionDuration = Math.max(maxRegionDuration, regionDuration);
     }
 
-    // If we calculated a LONGER duration, update layout.
-    // Never downgrade — widgets with useDuration=0 start at duration=0
-    // until loadedmetadata fires, so early calculations undercount.
-    if (maxRegionDuration > 0 && maxRegionDuration > this.currentLayout.duration) {
+    // Update layout duration if recalculated value differs.
+    // Both upgrades (video metadata revealing longer duration) and downgrades
+    // (DURATION comment correcting an overestimate) are legitimate.
+    if (maxRegionDuration > 0 && maxRegionDuration !== this.currentLayout.duration) {
       const oldDuration = this.currentLayout.duration;
       this.currentLayout.duration = maxRegionDuration;
 
@@ -878,6 +880,133 @@ export class RendererLite {
     }
   }
 
+  // ── Interactive Control (XIC) ─────────────────────────────────────
+
+  /**
+   * Find a region containing a widget by widget ID.
+   * Searches main regions first, then overlay regions.
+   * @param {string} widgetId
+   * @returns {{ regionId: string, region: Object, widget: Object, widgetIndex: number, regionMap: Map }|null}
+   */
+  _findRegionByWidgetId(widgetId) {
+    // Search main regions
+    for (const [regionId, region] of this.regions) {
+      const widgetIndex = region.widgets.findIndex(w => w.id === widgetId);
+      if (widgetIndex !== -1) {
+        return { regionId, region, widget: region.widgets[widgetIndex], widgetIndex, regionMap: this.regions };
+      }
+    }
+    // Search overlay regions
+    for (const overlay of this.activeOverlays.values()) {
+      if (!overlay.regions) continue;
+      for (const [regionId, region] of overlay.regions) {
+        const widgetIndex = region.widgets.findIndex(w => w.id === widgetId);
+        if (widgetIndex !== -1) {
+          return { regionId, region, widget: region.widgets[widgetIndex], widgetIndex, regionMap: overlay.regions };
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Advance a region to its next widget using the standard cycle.
+   * @param {string} regionId
+   * @param {Map} regionMap - The Map containing this region (main or overlay)
+   */
+  _advanceRegion(regionId, regionMap) {
+    const region = regionMap.get(regionId);
+    if (!region) return;
+    region.currentIndex = (region.currentIndex + 1) % region.widgets.length;
+    const isMain = regionMap === this.regions;
+    this._startRegionCycle(
+      region, regionId,
+      isMain ? (rid, idx) => this.renderWidget(rid, idx) : (rid, idx) => this.renderWidget(rid, idx),
+      isMain ? (rid, idx) => this.stopWidget(rid, idx) : (rid, idx) => this.stopWidget(rid, idx),
+      isMain ? () => this.checkLayoutComplete() : undefined
+    );
+  }
+
+  /**
+   * Handle interactiveTrigger XIC event — navigate to a target widget.
+   * @param {{ targetId: string, triggerCode: string }} data
+   */
+  _handleInteractiveTrigger({ targetId, triggerCode }) {
+    this.log.info(`XIC interactiveTrigger: target=${targetId} code=${triggerCode}`);
+    const found = this._findRegionByWidgetId(targetId);
+    if (found) {
+      this.navigateToWidget(targetId);
+    } else {
+      this.log.warn(`XIC interactiveTrigger: widget ${targetId} not found`);
+    }
+  }
+
+  /**
+   * Handle widgetExpire XIC event — immediately expire a widget and advance.
+   * @param {{ widgetId: string }} data
+   */
+  _handleWidgetExpire({ widgetId }) {
+    const found = this._findRegionByWidgetId(widgetId);
+    if (!found) {
+      this.log.warn(`XIC widgetExpire: widget ${widgetId} not found`);
+      return;
+    }
+    const { regionId, region, widgetIndex, regionMap } = found;
+    this.log.info(`XIC widgetExpire: widget=${widgetId} region=${regionId}`);
+    if (region.timer) {
+      clearTimeout(region.timer);
+      region.timer = null;
+    }
+    this.stopWidget(regionId, widgetIndex);
+    this._advanceRegion(regionId, regionMap);
+  }
+
+  /**
+   * Handle widgetExtendDuration XIC event — extend the current widget timer.
+   * @param {{ widgetId: string, duration: number }} data - duration in seconds (added to remaining)
+   */
+  _handleWidgetExtendDuration({ widgetId, duration }) {
+    const found = this._findRegionByWidgetId(widgetId);
+    if (!found) {
+      this.log.warn(`XIC widgetExtendDuration: widget ${widgetId} not found`);
+      return;
+    }
+    const { regionId, region } = found;
+    this.log.info(`XIC widgetExtendDuration: widget=${widgetId} +${duration}s`);
+    if (region.timer) {
+      clearTimeout(region.timer);
+      region.timer = null;
+    }
+    // Re-arm timer with the extended duration
+    region.timer = setTimeout(() => {
+      this.stopWidget(regionId, region.currentIndex);
+      this._advanceRegion(regionId, found.regionMap);
+    }, duration * 1000);
+  }
+
+  /**
+   * Handle widgetSetDuration XIC event — replace the widget timer with an absolute duration.
+   * @param {{ widgetId: string, duration: number }} data - duration in seconds (absolute)
+   */
+  _handleWidgetSetDuration({ widgetId, duration }) {
+    const found = this._findRegionByWidgetId(widgetId);
+    if (!found) {
+      this.log.warn(`XIC widgetSetDuration: widget ${widgetId} not found`);
+      return;
+    }
+    const { regionId, region } = found;
+    this.log.info(`XIC widgetSetDuration: widget=${widgetId} ${duration}s`);
+    if (region.timer) {
+      clearTimeout(region.timer);
+      region.timer = null;
+    }
+    // Set timer with the absolute duration
+    region.timer = setTimeout(() => {
+      this.stopWidget(regionId, region.currentIndex);
+      this._advanceRegion(regionId, found.regionMap);
+    }, duration * 1000);
+  }
+
   /**
    * Navigate to a specific widget within a region (for navWidget actions)
    */
@@ -914,6 +1043,9 @@ export class RendererLite {
           if (region.isDrawer && nextIndex === 0) {
             region.element.style.display = 'none';
             this.log.info(`Drawer region ${regionId} hidden (cycle complete)`);
+          } else if (region.isDrawer) {
+            // Continue cycling through remaining drawer widgets (will hide on wrap to 0)
+            this.navigateToWidget(region.widgets[nextIndex].id);
           } else {
             this.startRegion(regionId);
           }
@@ -961,6 +1093,60 @@ export class RendererLite {
     this.navigateToWidget(targetWidget.id);
   }
 
+  // ── Layout Helpers ───────────────────────────────────────────────
+
+  /**
+   * Get media file URL for storedAs filename.
+   * @param {string} storedAs - The storedAs filename (e.g. "42_abc123.jpg")
+   * @returns {string} Full URL for the media file
+   */
+  _mediaFileUrl(storedAs) {
+    return `${window.location.origin}${PLAYER_API}/media/file/${storedAs}`;
+  }
+
+  /**
+   * Position a widget element to fill its region (hidden by default).
+   * @param {HTMLElement} element
+   */
+  _positionWidgetElement(element) {
+    Object.assign(element.style, {
+      position: 'absolute',
+      top: '0',
+      left: '0',
+      width: '100%',
+      height: '100%',
+      visibility: 'hidden',
+      opacity: '0',
+    });
+  }
+
+  /**
+   * Apply a background image with cover styling.
+   * @param {HTMLElement} element
+   * @param {string} url - Image URL
+   */
+  _applyBackgroundImage(element, url) {
+    Object.assign(element.style, {
+      backgroundImage: `url(${url})`,
+      backgroundSize: 'cover',
+      backgroundPosition: 'center',
+      backgroundRepeat: 'no-repeat',
+    });
+  }
+
+  /**
+   * Clear all region timers in a region map.
+   * @param {Map} regions - Region map (regionId → region)
+   */
+  _clearRegionTimers(regions) {
+    for (const [, region] of regions) {
+      if (region.timer) {
+        clearTimeout(region.timer);
+        region.timer = null;
+      }
+    }
+  }
+
   // ── Layout Rendering ──────────────────────────────────────────────
 
   /**
@@ -980,13 +1166,9 @@ 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
-        for (const [regionId, region] of this.regions) {
-          if (region.timer) {
-            clearTimeout(region.timer);
-            region.timer = null;
-          }
-          // Reset to first widget
+        // Stop all region timers and reset to first widget
+        this._clearRegionTimers(this.regions);
+        for (const [, region] of this.regions) {
           region.currentIndex = 0;
         }
 
@@ -998,7 +1180,6 @@ export class RendererLite {
         this.layoutEndEmitted = false;
 
         // DON'T call stopCurrentLayout() - keep elements alive!
-        // DON'T clear mediaUrlCache - keep blob URLs alive!
         // DON'T recreate regions/elements - already exist!
 
         // Emit layout start event
@@ -1045,50 +1226,11 @@ export class RendererLite {
       this.container.style.backgroundImage = ''; // Reset previous
 
       // Apply background image if specified in XLF
-      if (layout.background && this.options.getMediaUrl) {
-        try {
-          const bgUrl = await this.options.getMediaUrl(parseInt(layout.background));
-          if (bgUrl) {
-            this.container.style.backgroundImage = `url(${bgUrl})`;
-            this.container.style.backgroundSize = 'cover';
-            this.container.style.backgroundPosition = 'center';
-            this.container.style.backgroundRepeat = 'no-repeat';
-            this.log.info(`Background image set: ${layout.background}`);
-          }
-        } catch (err) {
-          this.log.warn('Failed to load background image:', err);
-        }
-      }
-
-      // PRE-FETCH: Get all media URLs in parallel (huge speedup!)
-      if (this.options.getMediaUrl) {
-        const mediaPromises = [];
-        this.mediaUrlCache.clear(); // Clear previous layout's cache
-
-        for (const region of layout.regions) {
-          for (const widget of region.widgets) {
-            if (widget.fileId) {
-              const fileId = parseInt(widget.fileId || widget.id);
-              if (!this.mediaUrlCache.has(fileId)) {
-                mediaPromises.push(
-                  this.options.getMediaUrl(fileId)
-                    .then(url => {
-                      this.mediaUrlCache.set(fileId, url);
-                    })
-                    .catch(err => {
-                      this.log.warn(`Failed to fetch media ${fileId}:`, err);
-                    })
-                );
-              }
-            }
-          }
-        }
-
-        if (mediaPromises.length > 0) {
-          this.log.info(`Pre-fetching ${mediaPromises.length} media URLs in parallel...`);
-          await Promise.all(mediaPromises);
-          this.log.info(`All media URLs pre-fetched`);
-        }
+      // With storedAs refactor, background may be a filename (e.g. "43.png") or a numeric fileId
+      if (layout.background) {
+        const saveAs = this.options.fileIdToSaveAs?.get(String(layout.background)) || layout.background;
+        this._applyBackgroundImage(this.container, this._mediaFileUrl(saveAs));
+        this.log.info(`Background image set: ${layout.background} → ${saveAs}`);
       }
 
       // Create regions
@@ -1106,13 +1248,7 @@ export class RendererLite {
 
           try {
             const element = await this.createWidgetElement(widget, region);
-            element.style.position = 'absolute';
-            element.style.top = '0';
-            element.style.left = '0';
-            element.style.width = '100%';
-            element.style.height = '100%';
-            element.style.visibility = 'hidden'; // Hidden by default
-            element.style.opacity = '0';
+            this._positionWidgetElement(element);
             region.element.appendChild(element);
             region.widgetElements.set(widget.id, element);
           } catch (error) {
@@ -1192,6 +1328,7 @@ export class RendererLite {
       height: regionConfig.height * sf,
       complete: false, // Track if region has played all widgets once
       isDrawer: regionConfig.isDrawer || false,
+      isCanvas: regionConfig.isCanvas || false, // Canvas regions render all widgets simultaneously
       widgetElements: new Map() // widgetId -> DOM element (for element reuse)
     });
   }
@@ -1465,13 +1602,15 @@ export class RendererLite {
       region.element.appendChild(element);
     }
 
-    // Hide all other widgets in region
+    // Hide all other widgets in region (skip for canvas — all widgets stay visible)
     // Cancel fill:forwards animations first — they override inline styles
-    for (const [widgetId, widgetEl] of region.widgetElements) {
-      if (widgetId !== widget.id) {
-        widgetEl.getAnimations?.().forEach(a => a.cancel());
-        widgetEl.style.visibility = 'hidden';
-        widgetEl.style.opacity = '0';
+    if (!region.isCanvas) {
+      for (const [widgetId, widgetEl] of region.widgetElements) {
+        if (widgetId !== widget.id) {
+          widgetEl.getAnimations?.().forEach(a => a.cancel());
+          widgetEl.style.visibility = 'hidden';
+          widgetEl.style.opacity = '0';
+        }
       }
     }
 
@@ -1512,22 +1651,8 @@ export class RendererLite {
       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_API}/media/${audioNode.uri}`;
-        });
-      } else if (!audioSrc) {
-        audio.src = `${window.location.origin}${PLAYER_API}/media/${audioNode.uri}`;
-      } else {
-        audio.src = audioSrc;
-      }
+      // Direct URL from storedAs filename
+      audio.src = audioNode.uri ? this._mediaFileUrl(audioNode.uri) : '';
 
       // Append to DOM to prevent garbage collection in some browsers
       audio.style.display = 'none';
@@ -1661,12 +1786,15 @@ export class RendererLite {
    * @param {Object} widget - Widget config (duration may be updated)
    */
   _parseDurationComments(html, widget) {
+    const oldDuration = widget.duration;
+
     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;
+        if (widget.duration !== oldDuration) this.updateLayoutDuration();
         return;
       }
     }
@@ -1680,6 +1808,8 @@ export class RendererLite {
         widget.duration = newDuration;
       }
     }
+
+    if (widget.duration !== oldDuration) this.updateLayoutDuration();
   }
 
   /**
@@ -1723,10 +1853,17 @@ export class RendererLite {
         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);
+        // Round-robin based on cycle index, respecting playCount
+        const state = this._subPlaylistCycleIndex.get(groupId) || { widgetIdx: 0, playsDone: 0 };
+        selectedWidget = groupWidgets[state.widgetIdx % groupWidgets.length];
+        const effectivePlayCount = selectedWidget.playCount || 1;
+
+        state.playsDone++;
+        if (state.playsDone >= effectivePlayCount) {
+          state.widgetIdx++;
+          state.playsDone = 0;
+        }
+        this._subPlaylistCycleIndex.set(groupId, state);
       }
 
       this.log.info(`Sub-playlist cycle: group ${groupId} selected widget ${selectedWidget.id} (${groupWidgets.length} in group)`);
@@ -1747,6 +1884,13 @@ export class RendererLite {
   _startRegionCycle(region, regionId, showFn, hideFn, onCycleComplete) {
     if (!region || region.widgets.length === 0) return;
 
+    // Canvas regions: render ALL widgets simultaneously (stacked), no cycling.
+    // Duration = max widget duration; region completes when the longest widget expires.
+    if (region.isCanvas) {
+      this._startCanvasRegion(region, regionId, showFn, onCycleComplete);
+      return;
+    }
+
     // Non-looping region with a single widget: show it and stay (spec: loop=0)
     if (region.widgets.length === 1) {
       showFn(regionId, 0);
@@ -1760,6 +1904,7 @@ export class RendererLite {
       showFn(regionId, widgetIndex);
 
       const duration = widget.duration * 1000;
+      this.log.info(`Region ${regionId} widget ${widget.id} (${widget.type}) playing for ${widget.duration}s (useDuration=${widget.useDuration}, index ${widgetIndex}/${region.widgets.length})`);
       region.timer = setTimeout(() => {
         this._handleWidgetCycleEnd(widget, region, regionId, widgetIndex, showFn, hideFn, onCycleComplete, playNext);
       }, duration);
@@ -1768,6 +1913,37 @@ export class RendererLite {
     playNext();
   }
 
+  /**
+   * Start a canvas region — render all widgets simultaneously (stacked).
+   * Canvas regions show every widget at once rather than cycling through them.
+   * The region duration is the maximum widget duration.
+   * @param {Object} region - Region state
+   * @param {string} regionId - Region ID
+   * @param {Function} showFn - Show widget function (regionId, widgetIndex)
+   * @param {Function} onCycleComplete - Callback when region completes
+   */
+  _startCanvasRegion(region, regionId, showFn, onCycleComplete) {
+    // Show all widgets at once
+    for (let i = 0; i < region.widgets.length; i++) {
+      showFn(regionId, i);
+    }
+
+    // Mark region as complete after max widget duration
+    const maxDuration = Math.max(...region.widgets.map(w => w.duration)) * 1000;
+    if (maxDuration > 0) {
+      region.timer = setTimeout(() => {
+        if (!region.complete) {
+          region.complete = true;
+          onCycleComplete?.();
+        }
+      }, maxDuration);
+    } else {
+      // No duration — immediately complete
+      region.complete = true;
+      onCycleComplete?.();
+    }
+  }
+
   /**
    * Handle widget cycle end — shared logic for timer-based and event-based cycling
    */
@@ -1791,10 +1967,11 @@ export class RendererLite {
       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);
+    // Non-looping single-widget region (loop=0): don't replay.
+    // Multi-widget regions (playlists) always cycle regardless of loop setting —
+    // in Xibo, loop=0 only means "don't repeat a single media item."
+    if (nextIndex === 0 && region.config?.loop === false && region.widgets.length === 1) {
+      showFn(regionId, 0);
       return;
     }
 
@@ -1886,17 +2063,12 @@ export class RendererLite {
 
     img.style.opacity = '0';
 
-    // Get media URL from cache (already pre-fetched!) or fetch on-demand
-    const fileId = parseInt(widget.fileId || widget.id);
-    let imageSrc = this.mediaUrlCache.get(fileId);
-
-    if (!imageSrc && this.options.getMediaUrl) {
-      imageSrc = await this.options.getMediaUrl(fileId);
-    } else if (!imageSrc) {
-      imageSrc = `${window.location.origin}${PLAYER_API}/media/${widget.options.uri}`;
-    }
+    // Direct URL from storedAs filename — store key = widget reference = serve URL
+    const src = widget.options.uri
+      ? this._mediaFileUrl(widget.options.uri)
+      : '';
 
-    img.src = imageSrc;
+    img.src = src;
     return img;
   }
 
@@ -1919,27 +2091,22 @@ export class RendererLite {
     video.controls = false; // Hidden by default — toggle with V key in PWA
     video.playsInline = true; // Prevent fullscreen on mobile
 
-    // Get media URL from cache (already pre-fetched!) or fetch on-demand
-    const fileId = parseInt(widget.fileId || widget.id);
+    // Direct URL from storedAs filename
+    const storedAs = widget.options.uri || '';
+    const fileId = widget.fileId || widget.id;
 
     // Handle video end - pause on last frame instead of showing black
     // Widget cycling will restart the video via updateMediaElement()
     const onEnded = () => {
       if (widget.options.loop === '1') {
         video.currentTime = 0;
-        this.log.info(`Video ${fileId} ended - reset to start, waiting for widget cycle to replay`);
+        this.log.info(`Video ${storedAs} ended - reset to start, waiting for widget cycle to replay`);
       } else {
-        this.log.info(`Video ${fileId} ended - paused on last frame`);
+        this.log.info(`Video ${storedAs} ended - paused on last frame`);
       }
     };
     video.addEventListener('ended', onEnded);
-    let videoSrc = this.mediaUrlCache.get(fileId);
-
-    if (!videoSrc && this.options.getMediaUrl) {
-      videoSrc = await this.options.getMediaUrl(fileId);
-    } else if (!videoSrc) {
-      videoSrc = `${window.location.origin}${PLAYER_API}/media/${fileId}`;
-    }
+    let videoSrc = storedAs ? this._mediaFileUrl(storedAs) : '';
 
     // HLS/DASH streaming support
     const isHlsStream = videoSrc.includes('.m3u8');
@@ -1985,7 +2152,7 @@ export class RendererLite {
     const createdForLayoutId = this.currentLayoutId;
     const onLoadedMetadata = () => {
       const videoDuration = Math.floor(video.duration);
-      this.log.info(`Video ${fileId} duration detected: ${videoDuration}s`);
+      this.log.info(`Video ${storedAs} duration detected: ${videoDuration}s`);
 
       if (widget.duration === 0 || widget.useDuration === 0) {
         widget.duration = videoDuration;
@@ -1994,14 +2161,14 @@ export class RendererLite {
         if (this.currentLayoutId === createdForLayoutId) {
           this.updateLayoutDuration();
         } else {
-          this.log.info(`Video ${fileId} duration set but layout timer not updated (preloaded for layout ${createdForLayoutId}, current is ${this.currentLayoutId})`);
+          this.log.info(`Video ${storedAs} duration set but layout timer not updated (preloaded for layout ${createdForLayoutId}, current is ${this.currentLayoutId})`);
         }
       }
     };
     video.addEventListener('loadedmetadata', onLoadedMetadata);
 
     const onLoadedData = () => {
-      this.log.info('Video loaded and ready:', fileId);
+      this.log.info('Video loaded and ready:', storedAs);
     };
     video.addEventListener('loadeddata', onLoadedData);
 
@@ -2009,13 +2176,13 @@ export class RendererLite {
       const error = video.error;
       const errorCode = error?.code;
       const errorMessage = error?.message || 'Unknown error';
-      this.log.warn(`Video error: ${fileId}, code: ${errorCode}, time: ${video.currentTime.toFixed(1)}s, message: ${errorMessage}`);
-      this.emit('videoError', { fileId, errorCode, errorMessage, currentTime: video.currentTime });
+      this.log.warn(`Video error: ${storedAs}, code: ${errorCode}, time: ${video.currentTime.toFixed(1)}s, message: ${errorMessage}`);
+      this.emit('videoError', { storedAs, fileId, errorCode, errorMessage, currentTime: video.currentTime });
     };
     video.addEventListener('error', onError);
 
     const onPlaying = () => {
-      this.log.info('Video playing:', fileId);
+      this.log.info('Video playing:', storedAs);
     };
     video.addEventListener('playing', onPlaying);
 
@@ -2028,7 +2195,7 @@ export class RendererLite {
       ['playing', onPlaying],
     ];
 
-    this.log.info('Video element created:', fileId, video.src);
+    this.log.info('Video element created:', storedAs, video.src);
 
     return video;
   }
@@ -2113,25 +2280,18 @@ export class RendererLite {
     audio.loop = widget.options.loop === '1';
     audio.volume = parseFloat(widget.options.volume || '100') / 100;
 
-    // Get media URL from cache (already pre-fetched!) or fetch on-demand
-    const fileId = parseInt(widget.fileId || widget.id);
-    let audioSrc = this.mediaUrlCache.get(fileId);
-
-    if (!audioSrc && this.options.getMediaUrl) {
-      audioSrc = await this.options.getMediaUrl(fileId);
-    } else if (!audioSrc) {
-      audioSrc = `${window.location.origin}${PLAYER_API}/media/${fileId}`;
-    }
-
-    audio.src = audioSrc;
+    // Direct URL from storedAs filename
+    const storedAs = widget.options.uri || '';
+    const fileId = widget.fileId || widget.id;
+    audio.src = storedAs ? this._mediaFileUrl(storedAs) : '';
 
     // Handle audio end - similar to video ended handling
     const onAudioEnded = () => {
       if (widget.options.loop === '1') {
         audio.currentTime = 0;
-        this.log.info(`Audio ${fileId} ended - reset to start, waiting for widget cycle to replay`);
+        this.log.info(`Audio ${storedAs} ended - reset to start, waiting for widget cycle to replay`);
       } else {
-        this.log.info(`Audio ${fileId} ended - playback complete`);
+        this.log.info(`Audio ${storedAs} ended - playback complete`);
       }
     };
     audio.addEventListener('ended', onAudioEnded);
@@ -2140,7 +2300,7 @@ export class RendererLite {
     const audioCreatedForLayoutId = this.currentLayoutId;
     const onAudioLoadedMetadata = () => {
       const audioDuration = Math.floor(audio.duration);
-      this.log.info(`Audio ${fileId} duration detected: ${audioDuration}s`);
+      this.log.info(`Audio ${storedAs} duration detected: ${audioDuration}s`);
 
       if (widget.duration === 0 || widget.useDuration === 0) {
         widget.duration = audioDuration;
@@ -2149,7 +2309,7 @@ export class RendererLite {
         if (this.currentLayoutId === audioCreatedForLayoutId) {
           this.updateLayoutDuration();
         } else {
-          this.log.info(`Audio ${fileId} duration set but layout timer not updated (preloaded for layout ${audioCreatedForLayoutId}, current is ${this.currentLayoutId})`);
+          this.log.info(`Audio ${storedAs} duration set but layout timer not updated (preloaded for layout ${audioCreatedForLayoutId}, current is ${this.currentLayoutId})`);
         }
       }
     };
@@ -2158,7 +2318,7 @@ export class RendererLite {
     // Handle audio errors
     const onAudioError = () => {
       const error = audio.error;
-      this.log.warn(`Audio error (non-fatal): ${fileId}, code: ${error?.code}, message: ${error?.message || 'Unknown'}`);
+      this.log.warn(`Audio error (non-fatal): ${storedAs}, code: ${error?.code}, message: ${error?.message || 'Unknown'}`);
     };
     audio.addEventListener('error', onAudioError);
 
@@ -2293,15 +2453,10 @@ export class RendererLite {
       }
     }
 
-    // Get PDF URL from cache (already pre-fetched!) or fetch on-demand
-    const fileId = parseInt(widget.fileId || widget.id);
-    let pdfUrl = this.mediaUrlCache.get(fileId);
-
-    if (!pdfUrl && this.options.getMediaUrl) {
-      pdfUrl = await this.options.getMediaUrl(fileId);
-    } else if (!pdfUrl) {
-      pdfUrl = `${window.location.origin}${PLAYER_API}/media/${widget.options.uri}`;
-    }
+    // Direct URL from storedAs filename
+    let pdfUrl = widget.options.uri
+      ? this._mediaFileUrl(widget.options.uri)
+      : '';
 
     // Render PDF with multi-page cycling
     try {
@@ -2593,54 +2748,13 @@ export class RendererLite {
       wrapper.style.backgroundColor = layout.bgcolor;
 
       // Apply background image if specified
-      if (layout.background && this.options.getMediaUrl) {
-        try {
-          const bgUrl = await this.options.getMediaUrl(parseInt(layout.background));
-          if (bgUrl) {
-            wrapper.style.backgroundImage = `url(${bgUrl})`;
-            wrapper.style.backgroundSize = 'cover';
-            wrapper.style.backgroundPosition = 'center';
-            wrapper.style.backgroundRepeat = 'no-repeat';
-          }
-        } catch (err) {
-          this.log.warn('Preload: Failed to load background image:', err);
-        }
-      }
-
-      // Pre-fetch all media URLs in parallel
-      const preloadMediaUrlCache = new Map();
-      if (this.options.getMediaUrl) {
-        const mediaPromises = [];
-
-        for (const region of layout.regions) {
-          for (const widget of region.widgets) {
-            if (widget.fileId) {
-              const fileId = parseInt(widget.fileId || widget.id);
-              if (!preloadMediaUrlCache.has(fileId)) {
-                mediaPromises.push(
-                  this.options.getMediaUrl(fileId)
-                    .then(url => {
-                      preloadMediaUrlCache.set(fileId, url);
-                    })
-                    .catch(err => {
-                      this.log.warn(`Preload: Failed to fetch media ${fileId}:`, err);
-                    })
-                );
-              }
-            }
-          }
-        }
-
-        if (mediaPromises.length > 0) {
-          this.log.info(`Preload: fetching ${mediaPromises.length} media URLs...`);
-          await Promise.all(mediaPromises);
-        }
+      // With storedAs refactor, background may be a filename or a numeric fileId
+      if (layout.background) {
+        const saveAs = this.options.fileIdToSaveAs?.get(String(layout.background)) || layout.background;
+        this._applyBackgroundImage(wrapper, this._mediaFileUrl(saveAs));
       }
 
-      // Temporarily swap mediaUrlCache so createWidgetElement uses preload cache
-      const savedMediaUrlCache = this.mediaUrlCache;
       const savedCurrentLayoutId = this.currentLayoutId;
-      this.mediaUrlCache = preloadMediaUrlCache;
 
       // Create regions in the hidden wrapper
       const preloadRegions = new Map();
@@ -2680,8 +2794,9 @@ export class RendererLite {
       this.layoutBlobUrls = new Map();
       this.layoutBlobUrls.set(layoutId, preloadBlobUrls);
 
-      // Temporarily set currentLayoutId for trackBlobUrl to work
-      this.currentLayoutId = layoutId;
+      // Set _preloadingLayoutId so trackBlobUrl routes to the correct layout
+      // without corrupting currentLayoutId (which other code reads during awaits)
+      this._preloadingLayoutId = layoutId;
 
       // Pre-create all widget elements
       for (const [regionId, region] of preloadRegions) {
@@ -2692,13 +2807,7 @@ export class RendererLite {
 
           try {
             const element = await this.createWidgetElement(widget, region);
-            element.style.position = 'absolute';
-            element.style.top = '0';
-            element.style.left = '0';
-            element.style.width = '100%';
-            element.style.height = '100%';
-            element.style.visibility = 'hidden';
-            element.style.opacity = '0';
+            this._positionWidgetElement(element);
             region.element.appendChild(element);
             region.widgetElements.set(widget.id, element);
           } catch (error) {
@@ -2708,7 +2817,6 @@ export class RendererLite {
       }
 
       // Restore state
-      this.mediaUrlCache = savedMediaUrlCache;
       this.currentLayoutId = savedCurrentLayoutId;
 
       // Pause all videos in preloaded layout (autoplay starts them even when hidden)
@@ -2730,10 +2838,9 @@ export class RendererLite {
         layout,
         regions: preloadRegions,
         blobUrls: preloadBlobUrls,
-        mediaUrlCache: preloadMediaUrlCache
       });
 
-      this.log.info(`Layout ${layoutId} preloaded into pool (${preloadRegions.size} regions, ${preloadMediaUrlCache.size} media)`);
+      this.log.info(`Layout ${layoutId} preloaded into pool (${preloadRegions.size} regions)`);
       return true;
 
     } catch (error) {
@@ -2782,15 +2889,12 @@ export class RendererLite {
       // Old layout was rendered normally — manual cleanup.
       // Region elements live directly in this.container (not a wrapper),
       // so we must remove them individually.
-      for (const [regionId, region] of this.regions) {
-        if (region.timer) {
-          clearTimeout(region.timer);
-          region.timer = null;
-        }
+      this._clearRegionTimers(this.regions);
+      for (const [, region] of this.regions) {
         // Release video/audio resources before removing from DOM
         LayoutPool.releaseMediaElements(region.element);
         // Apply region exit transition if configured, then remove
-        if (region.config && region.config.exitTransition) {
+        if (region.config?.exitTransition) {
           const animation = Transitions.apply(
             region.element, region.config.exitTransition, false,
             region.width, region.height
@@ -2809,11 +2913,6 @@ export class RendererLite {
       if (oldLayoutId) {
         this.revokeBlobUrlsForLayout(oldLayoutId);
       }
-      for (const [fileId, blobUrl] of this.mediaUrlCache) {
-        if (blobUrl && typeof blobUrl === 'string' && blobUrl.startsWith('blob:')) {
-          URL.revokeObjectURL(blobUrl);
-        }
-      }
     }
 
     // Emit layoutEnd for old layout if timer hasn't already
@@ -2822,7 +2921,6 @@ export class RendererLite {
     }
 
     this.regions.clear();
-    this.mediaUrlCache.clear();
 
     // ── Activate preloaded layout ──
     preloaded.container.style.visibility = 'visible';
@@ -2833,16 +2931,15 @@ export class RendererLite {
     this.currentLayout = preloaded.layout;
     this.currentLayoutId = layoutId;
     this.regions = preloaded.regions;
-    this.mediaUrlCache = preloaded.mediaUrlCache || new Map();
     this.layoutEndEmitted = false;
 
     // Update container background to match preloaded layout
     this.container.style.backgroundColor = preloaded.layout.bgcolor;
     if (preloaded.container.style.backgroundImage) {
-      this.container.style.backgroundImage = preloaded.container.style.backgroundImage;
-      this.container.style.backgroundSize = preloaded.container.style.backgroundSize;
-      this.container.style.backgroundPosition = preloaded.container.style.backgroundPosition;
-      this.container.style.backgroundRepeat = preloaded.container.style.backgroundRepeat;
+      // Copy background styles from preloaded wrapper to main container
+      for (const prop of ['backgroundImage', 'backgroundSize', 'backgroundPosition', 'backgroundRepeat']) {
+        this.container.style[prop] = preloaded.container.style[prop];
+      }
     } else {
       this.container.style.backgroundImage = '';
     }
@@ -2942,12 +3039,8 @@ export class RendererLite {
       }
 
       // Stop all regions
+      this._clearRegionTimers(this.regions);
       for (const [regionId, region] of this.regions) {
-        if (region.timer) {
-          clearTimeout(region.timer);
-          region.timer = null;
-        }
-
         // Stop current widget
         if (region.widgets.length > 0) {
           this.stopWidget(regionId, region.currentIndex);
@@ -2957,13 +3050,12 @@ export class RendererLite {
         LayoutPool.releaseMediaElements(region.element);
 
         // Apply region exit transition if configured, then remove
-        if (region.config && region.config.exitTransition) {
+        if (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 {
@@ -2974,17 +3066,10 @@ export class RendererLite {
         }
       }
 
-      // Revoke media blob URLs from cache
-      for (const [fileId, blobUrl] of this.mediaUrlCache) {
-        if (blobUrl && blobUrl.startsWith('blob:')) {
-          URL.revokeObjectURL(blobUrl);
-        }
-      }
     }
 
     // Clear state
     this.regions.clear();
-    this.mediaUrlCache.clear();
 
     // Emit layout end event only if timer hasn't already emitted it.
     // Timer-based layoutEnd (natural expiry) is authoritative — stopCurrentLayout
@@ -3033,34 +3118,6 @@ export class RendererLite {
       overlayDiv.style.pointerEvents = 'auto'; // Enable clicks on overlay
       overlayDiv.style.backgroundColor = layout.bgcolor;
 
-      // Pre-fetch all media URLs for overlay
-      if (this.options.getMediaUrl) {
-        const mediaPromises = [];
-        for (const region of layout.regions) {
-          for (const widget of region.widgets) {
-            if (widget.fileId) {
-              const fileId = parseInt(widget.fileId || widget.id);
-              if (!this.mediaUrlCache.has(fileId)) {
-                mediaPromises.push(
-                  this.options.getMediaUrl(fileId)
-                    .then(url => {
-                      this.mediaUrlCache.set(fileId, url);
-                    })
-                    .catch(err => {
-                      this.log.warn(`Failed to fetch overlay media ${fileId}:`, err);
-                    })
-                );
-              }
-            }
-          }
-        }
-
-        if (mediaPromises.length > 0) {
-          this.log.info(`Pre-fetching ${mediaPromises.length} overlay media URLs...`);
-          await Promise.all(mediaPromises);
-        }
-      }
-
       // Calculate scale for overlay layout
       this.calculateScale(layout);
 
@@ -3090,6 +3147,7 @@ export class RendererLite {
           width: regionConfig.width * sf,
           height: regionConfig.height * sf,
           complete: false,
+          isCanvas: regionConfig.isCanvas || false,
           widgetElements: new Map()
         });
       }
@@ -3102,8 +3160,7 @@ export class RendererLite {
 
           try {
             const element = await this.createWidgetElement(widget, region);
-            element.style.visibility = 'hidden';
-            element.style.opacity = '0';
+            this._positionWidgetElement(element);
             region.element.appendChild(element);
             region.widgetElements.set(widget.id, element);
           } catch (error) {