@xiboplayer/renderer 0.6.2 → 0.6.4

package/README.md

@@ -1,19 +1,53 @@
 # @xiboplayer/renderer
 
-**XLF layout rendering engine for Xibo digital signage.**
+**Fast, memory-efficient XLF layout rendering engine for digital signage.**
 
 ## Overview
 
-RendererLite parses Xibo Layout Format (XLF) files and builds a live DOM with:
+Parses Xibo Layout Format (XLF) files and builds a live DOM with element reuse, instant transitions, and a 2-layout preload pool:
 
-- **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+)
-- **Absolute widget positioning** — widget elements use `position: absolute` within regions to layer correctly in multi-widget regions
-- **Animation cleanup** — `fill: forwards` animations cancelled between widgets to prevent stale visual state (e.g. video hidden after PDF)
+- **Rich media** -- video (MP4/HLS), images (scaleType, align/valign), audio (with visualization), PDF (PDF.js), text/ticker, web pages, clock, calendar, weather, and all CMS widget types
+- **Instant layout transitions** -- 2-layout preload pool keeps the next layout DOM-ready for zero-gap swap
+- **Element reuse** -- pre-creates all widget elements upfront; cycling reuses them instead of destroying/rebuilding
+- **Transitions** -- fade and fly animations with 8 compass directions via Web Animations API
+- **Canvas regions** -- simultaneous multi-widget rendering (stacked layers)
+- **Drawer regions** -- hidden action-triggered areas for interactive controls
+- **Overlays** -- multiple floating layouts with priority z-indexing
+- **Interactive actions** -- touch/click and keyboard triggers for widget navigation, layout jumps, and command execution
+- **Shell commands** -- native command execution via Electron IPC and Chromium HTTP endpoint
+- **Sub-playlist cycling** -- round-robin or random selection from widget groups
+- **Dynamic duration** -- video/audio metadata overrides for accurate timing
+- **Scale-to-fit** -- responsive scaling for any screen size via ResizeObserver
+
+## Architecture
+
+```
+XLF XML -> RendererLite
+            +- parseXlf() -> Layout object {width, height, regions: []}
+            +- renderLayout()
+                +- createRegion() for each region
+                |   +- createWidgetElement() for each widget
+                |       +- renderImage()        [<img>]
+                |       +- renderVideo()        [<video>] (HLS/DASH)
+                |       +- renderAudio()        [<audio> + visual]
+                |       +- renderTextWidget()   [<iframe>] (GetResource)
+                |       +- renderPdf()          [<canvas>] (multi-page)
+                |       +- renderWebpage()      [<iframe>]
+                |       +- renderVideoIn()      [<video>] (webcam)
+                |       +- renderGenericWidget() [<iframe>] (clock, etc.)
+                |
+                +- attachActionListeners() for touch/click/keyboard
+                +- startRegion() -> _startRegionCycle()
+                |   +- renderWidget() / stopWidget() cycling
+                |
+                +- startLayoutTimerWhenReady()
+                    +- Waits for all initial widgets to load
+                    +- Starts layout duration timer
+
+Layout Pool (2 entries max):
+  +- Hot entry    (visible, currently playing)
+  +- Warm entry   (preloaded, hidden, ready for instant swap)
+```
 
 ## Installation
 
@@ -23,33 +57,214 @@ npm install @xiboplayer/renderer
 
 ## Usage
 
+### Basic rendering
+
 ```javascript
 import { RendererLite } from '@xiboplayer/renderer';
 
-const renderer = new RendererLite({
-  container: document.getElementById('player'),
+const renderer = new RendererLite(
+  { cmsUrl: 'https://cms.example.com', hardwareKey: 'DISPLAY-001' },
+  document.getElementById('player')
+);
+
+renderer.on('layoutStart', (layoutId, layout) => {
+  console.log(`Layout ${layoutId} started (${layout.duration}s)`);
 });
 
-// Render a layout from parsed XLF
-await renderer.renderLayout(xlf, { mediaBaseUrl: '/cache/' });
+renderer.on('layoutEnd', (layoutId) => {
+  console.log(`Layout ${layoutId} ended`);
+});
+
+await renderer.renderLayout(xlfXmlContent, 42);
+```
+
+### Preloading for instant transitions
+
+```javascript
+// At 75% of current layout duration, renderer emits:
+renderer.on('request-next-layout-preload', async () => {
+  const nextLayout = await getNextLayoutFromSchedule();
+  if (nextLayout && !renderer.hasPreloadedLayout(nextLayout.id)) {
+    await renderer.preloadLayout(nextLayout.xlf, nextLayout.id);
+  }
+});
+
+// When it's time to show next layout, swap is INSTANT if preloaded
+await renderer.renderLayout(nextXlfXml, nextLayoutId);
+```
+
+### Overlays
+
+```javascript
+// Render an overlay on top of the main layout
+await renderer.renderOverlay(alertXlfXml, 101, 10);
+
+renderer.on('overlayEnd', (overlayId) => console.log('Overlay done'));
+
+// Stop overlay
+renderer.stopOverlay(101);
 ```
 
 ## Widget Types
 
-| Widget | Implementation |
-|--------|---------------|
-| Video | `<video>` with native HLS (Safari) + hls.js fallback, pause-on-last-frame |
-| Image | `<img>` with CMS scaleType mapping (center->contain, stretch->fill, fit->cover), 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 |
+| Type | Element | Source | Notes |
+|------|---------|--------|-------|
+| **image** | `<img>` | Media file | Object-fit: center/stretch/fit. objectPosition: top/middle/bottom, left/center/right |
+| **video** | `<video>` | Media file | HLS via native (Safari) + hls.js fallback. Pause-on-last-frame. Duration detection |
+| **audio** | `<audio>` + visual | Media file | Gradient visualization + music note icon. Volume control. Loop option |
+| **videoin** | `<video>` | getUserMedia() | Webcam/mic capture with mirror mode |
+| **text** | `<iframe>` | GetResource | CMS-rendered HTML. Parses NUMITEMS/DURATION comments |
+| **ticker** | `<iframe>` | GetResource | Data feeds with dynamic cycling |
+| **pdf** | `<canvas>` | Media file | PDF.js multi-page cycling. Page indicator. Time-per-page = duration / pages |
+| **webpage** | `<iframe>` | Direct URL | modeId=1 (URL), modeId=0 (GetResource) |
+| **clock** | `<iframe>` | GetResource | Digital/analogue variants |
+| **calendar** | `<iframe>` | GetResource | Calendar widget HTML |
+| **weather** | `<iframe>` | GetResource | Weather service HTML |
+| **global** | Stacked iframes | GetResource | Canvas region auto-detect for multi-layer content |
+| **all others** | `<iframe>` | GetResource | Generic CMS widget HTML |
+
+## Layout Lifecycle
+
+```
+XLF XML
+  |
+  +- parseXlf() -> {width, height, regions: [{widgets: [...]}]}
+  |
+  +- calculateScale() -> fit layout to screen
+  |
+  +- createRegion() for each region
+  |   +- Filter widgets (fromDt/toDt time-gating)
+  |   +- Apply sub-playlist cycling
+  |
+  +- createWidgetElement() for each widget (pre-creation)
+  |   +- Create DOM element, position absolute, hidden
+  |   +- Track blob URLs for cleanup
+  |
+  +- startRegion() for each region
+  |   +- Canvas: show ALL widgets at once, timer = max duration
+  |   +- Normal: cycle widgets with transitions
+  |
+  +- startLayoutTimerWhenReady()
+  |   +- Wait for video.playing / img.load (or 10s timeout)
+  |   +- Start layout duration timer
+  |
+  +- At 75%: emit 'request-next-layout-preload'
+  |
+  +- Layout duration expires
+      +- emit('layoutEnd', layoutId)
+```
+
+### Element reuse flow
+
+1. All widget elements pre-created during `renderLayout()` -- hidden, opacity 0
+2. Cycling: `renderWidget()` shows current, `stopWidget()` hides (same elements)
+3. No DOM destruction/recreation -- smooth transitions, instant replay
+4. When layout evicted from pool: blob URLs revoked, elements removed
+
+### Ready-wait gating
+
+Layout timer starts only when all initial widgets are loaded:
+- Video: waits for `playing` event
+- Image: waits for `load` event
+- Text/embedded: ready immediately
+- Timeout: 10s per widget (don't block on broken media)
+
+## Transitions
+
+Defined per-widget in XLF options:
+
+**Fade:** `fade`, `fadein`, `fadeout` -- opacity animation
+
+**Fly:** `fly`, `flyin`, `flyout` -- translate animation with compass direction:
+- `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`
+
+```xml
+<media duration="5">
+  <options>
+    <transIn>fly</transIn>
+    <transInDuration>1000</transInDuration>
+    <transInDirection>NE</transInDirection>
+    <transOut>fade</transOut>
+    <transOutDuration>500</transOutDuration>
+  </options>
+</media>
+```
+
+## Interactive Actions
+
+Actions defined in XLF at layout, region, or widget level:
+
+**Trigger types:** `touch` (click), `keyboard:KEY` (e.g., `keyboard:n`, `keyboard:Enter`)
+
+**Action types:** `navWidget` (jump to widget), `nextWidget`, `previousWidget`, `shellCommand`
+
+```javascript
+renderer.on('action-trigger', (actionData) => {
+  console.log(`Action: ${actionData.actionType}`, actionData);
+});
+
+// Programmatic navigation
+renderer.navigateToWidget('target-widget-id');
+renderer.nextWidget('region-id');
+renderer.previousWidget('region-id');
+```
+
+## Events
+
+| Event | Args | Description |
+|-------|------|-------------|
+| `layoutStart` | `(layoutId, layout)` | Layout DOM built and playback started |
+| `layoutEnd` | `(layoutId)` | Layout duration expired |
+| `layoutDurationUpdated` | `(layoutId, newDuration)` | Video metadata revealed actual duration |
+| `widgetStart` | `({ widgetId, regionId, layoutId, type, duration, enableStat })` | Widget now visible |
+| `widgetEnd` | `({ widgetId, regionId, layoutId, type, enableStat })` | Widget hidden/cycled |
+| `widgetCommand` | `({ commandCode, commandString, widgetId, regionId, layoutId })` | Shell command triggered |
+| `widgetAction` | `({ type, widgetId, layoutId, regionId, url })` | Widget webhook URL |
+| `videoError` | `({ storedAs, fileId, errorCode, errorMessage })` | Video playback error |
+| `overlayStart` | `(overlayId, layout)` | Overlay rendered |
+| `overlayEnd` | `(overlayId)` | Overlay finished |
+| `action-trigger` | `({ actionType, triggerType, targetId, commandCode })` | Touch/keyboard action fired |
+| `request-next-layout-preload` | `()` | 75% through layout -- preload next |
+| `error` | `({ type, error, layoutId, widgetId })` | Generic error |
+
+## API Reference
+
+### Constructor
+
+```javascript
+new RendererLite(config, container, options?)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | Object | `{ cmsUrl, hardwareKey }` |
+| `container` | HTMLElement | DOM element to render into |
+| `options.getWidgetHtml` | Function? | `(widget) => htmlString` -- fetch widget HTML from cache |
+| `options.fileIdToSaveAs` | Map? | Map of fileId to storedAs filename |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `renderLayout(xlfXml, layoutId)` | Promise | Parse, build, and start layout. Instant swap if preloaded. |
+| `preloadLayout(xlfXml, layoutId)` | Promise<bool> | Pre-build layout as hidden warm entry |
+| `hasPreloadedLayout(layoutId)` | boolean | Check if layout is in preload pool |
+| `renderOverlay(xlfXml, layoutId, priority)` | Promise | Render overlay on top |
+| `stopCurrentLayout()` | void | Stop main layout |
+| `stopOverlay(layoutId)` | void | Stop and remove overlay |
+| `stopAllOverlays()` | void | Stop all active overlays |
+| `navigateToWidget(widgetId)` | void | Jump to specific widget |
+| `nextWidget(regionId?)` | void | Advance to next widget |
+| `previousWidget(regionId?)` | void | Go back to previous widget |
+| `pause()` | void | Pause media and widget cycling |
+| `resume()` | void | Resume playback |
+| `cleanup()` | void | Stop all, clear pool, revoke blob URLs |
 
 ## Dependencies
 
-- `@xiboplayer/utils` — logger, events
-- `pdfjs-dist` — PDF rendering
+- `@xiboplayer/utils` -- logger, events
+- `pdfjs-dist` -- PDF rendering (dynamic import)
+- `hls.js` -- HLS streaming (dynamic import)
 
 ---
 

package/docs/RENDERER_COMPARISON.md

@@ -464,7 +464,7 @@ XLF → Parse → Pre-create Elements → Toggle Visibility → Transitions
 
 **RendererLite successfully implements the Arexibo pattern** and adds significant performance improvements through parallelization. The implementation is production-ready with minor improvements needed for blob URL lifecycle management.
 
-**Feature Parity**: ~98% (missing only widget action event propagation)
+**Feature Parity**: 100% (all widget types, transitions, interactive control, shell commands)
 **Performance**: Exceeds XLR and Arexibo benchmarks
 **Memory**: Stable with Arexibo pattern correctly implemented
 

package/package.json

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

package/src/layout.js

@@ -303,10 +303,16 @@ window.Transitions = {
     const direction = transitionConfig.direction || 'N';
 
     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':

package/src/renderer-lite.ic.test.js

@@ -0,0 +1,203 @@
+/**
+ * RendererLite Interactive Control (XIC) Tests
+ *
+ * Tests for the XIC event handlers: interactiveTrigger, widgetExpire,
+ * widgetExtendDuration, widgetSetDuration.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { RendererLite } from './renderer-lite.js';
+
+/**
+ * Create a minimal RendererLite instance with stubbed DOM and methods.
+ */
+function createRenderer() {
+  const container = document.createElement('div');
+  const renderer = new RendererLite(
+    { cmsUrl: 'http://localhost', hardwareKey: 'test' },
+    container,
+    { logLevel: 'silent' }
+  );
+
+  // Stub methods that touch DOM or async operations
+  renderer.renderWidget = vi.fn();
+  renderer.stopWidget = vi.fn();
+  renderer.checkLayoutComplete = vi.fn();
+  renderer._startRegionCycle = vi.fn();
+  renderer.navigateToWidget = vi.fn();
+
+  return renderer;
+}
+
+/**
+ * Populate renderer with a fake region containing widgets.
+ */
+function addRegion(renderer, regionId, widgets) {
+  renderer.regions.set(regionId, {
+    element: document.createElement('div'),
+    config: { id: regionId },
+    widgets,
+    currentIndex: 0,
+    timer: null,
+    width: 100,
+    height: 100,
+    complete: false,
+    isDrawer: false,
+    widgetElements: new Map()
+  });
+}
+
+describe('RendererLite XIC', () => {
+  let renderer;
+
+  beforeEach(() => {
+    renderer = createRenderer();
+    addRegion(renderer, 'region-1', [
+      { id: 'w1', type: 'text', duration: 10, options: {} },
+      { id: 'w2', type: 'image', duration: 20, options: {} },
+      { id: 'w3', type: 'video', duration: 30, options: {} }
+    ]);
+  });
+
+  describe('_findRegionByWidgetId', () => {
+    it('should find a widget in main regions', () => {
+      const result = renderer._findRegionByWidgetId('w2');
+      expect(result).not.toBeNull();
+      expect(result.regionId).toBe('region-1');
+      expect(result.widgetIndex).toBe(1);
+      expect(result.widget.id).toBe('w2');
+      expect(result.regionMap).toBe(renderer.regions);
+    });
+
+    it('should return null for unknown widget', () => {
+      const result = renderer._findRegionByWidgetId('w-unknown');
+      expect(result).toBeNull();
+    });
+
+    it('should find a widget in overlay regions', () => {
+      const overlayRegions = new Map();
+      overlayRegions.set('overlay-r1', {
+        element: document.createElement('div'),
+        config: { id: 'overlay-r1' },
+        widgets: [{ id: 'ow1', type: 'text', duration: 5, options: {} }],
+        currentIndex: 0,
+        timer: null,
+        width: 50,
+        height: 50,
+        complete: false,
+        isDrawer: false,
+        widgetElements: new Map()
+      });
+      renderer.activeOverlays.set(100, { regions: overlayRegions });
+
+      const result = renderer._findRegionByWidgetId('ow1');
+      expect(result).not.toBeNull();
+      expect(result.regionId).toBe('overlay-r1');
+      expect(result.widgetIndex).toBe(0);
+      expect(result.regionMap).toBe(overlayRegions);
+    });
+  });
+
+  describe('_handleInteractiveTrigger', () => {
+    it('should call navigateToWidget when target exists', () => {
+      renderer.emit('interactiveTrigger', { targetId: 'w2', triggerCode: 'btn1' });
+      expect(renderer.navigateToWidget).toHaveBeenCalledWith('w2');
+    });
+
+    it('should not call navigateToWidget when target is unknown', () => {
+      renderer.emit('interactiveTrigger', { targetId: 'w-missing', triggerCode: 'btn1' });
+      expect(renderer.navigateToWidget).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('_handleWidgetExpire', () => {
+    it('should clear timer, stop widget, and advance region', () => {
+      const region = renderer.regions.get('region-1');
+      region.timer = setTimeout(() => {}, 99999);
+      region.currentIndex = 0;
+
+      renderer.emit('widgetExpire', { widgetId: 'w1' });
+
+      expect(region.timer).toBeNull();
+      expect(renderer.stopWidget).toHaveBeenCalledWith('region-1', 0);
+      expect(renderer._startRegionCycle).toHaveBeenCalled();
+    });
+
+    it('should do nothing for unknown widget', () => {
+      renderer.emit('widgetExpire', { widgetId: 'w-missing' });
+      expect(renderer.stopWidget).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('_handleWidgetExtendDuration', () => {
+    it('should clear existing timer and re-arm with extended duration', () => {
+      vi.useFakeTimers();
+      const region = renderer.regions.get('region-1');
+      region.timer = setTimeout(() => {}, 99999);
+
+      renderer.emit('widgetExtendDuration', { widgetId: 'w1', duration: 15 });
+
+      // Timer should be re-armed (not null)
+      expect(region.timer).not.toBeNull();
+      // stopWidget should NOT have been called yet (timer hasn't fired)
+      expect(renderer.stopWidget).not.toHaveBeenCalled();
+
+      // Advance time to fire the new timer
+      vi.advanceTimersByTime(15000);
+      expect(renderer.stopWidget).toHaveBeenCalledWith('region-1', 0);
+
+      vi.useRealTimers();
+    });
+
+    it('should do nothing for unknown widget', () => {
+      renderer.emit('widgetExtendDuration', { widgetId: 'w-missing', duration: 10 });
+      expect(renderer.stopWidget).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('_handleWidgetSetDuration', () => {
+    it('should clear existing timer and set absolute duration', () => {
+      vi.useFakeTimers();
+      const region = renderer.regions.get('region-1');
+      region.timer = setTimeout(() => {}, 99999);
+
+      renderer.emit('widgetSetDuration', { widgetId: 'w2', duration: 5 });
+
+      expect(region.timer).not.toBeNull();
+      expect(renderer.stopWidget).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(5000);
+      // w2 is at index 1, but the region's currentIndex determines what gets stopped
+      expect(renderer.stopWidget).toHaveBeenCalled();
+
+      vi.useRealTimers();
+    });
+
+    it('should do nothing for unknown widget', () => {
+      renderer.emit('widgetSetDuration', { widgetId: 'w-missing', duration: 10 });
+      expect(renderer.stopWidget).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('_advanceRegion', () => {
+    it('should increment currentIndex and call _startRegionCycle', () => {
+      const region = renderer.regions.get('region-1');
+      region.currentIndex = 0;
+
+      renderer._advanceRegion('region-1', renderer.regions);
+
+      expect(region.currentIndex).toBe(1);
+      expect(renderer._startRegionCycle).toHaveBeenCalled();
+    });
+
+    it('should wrap around at end of widget list', () => {
+      const region = renderer.regions.get('region-1');
+      region.currentIndex = 2; // last widget
+
+      renderer._advanceRegion('region-1', renderer.regions);
+
+      expect(region.currentIndex).toBe(0);
+      expect(renderer._startRegionCycle).toHaveBeenCalled();
+    });
+  });
+});