@xiboplayer/schedule 0.6.2 → 0.6.4

package/README.md

@@ -1,17 +1,59 @@
 # @xiboplayer/schedule
 
-**Campaign scheduling with dayparting, interrupts, overlays, and timeline prediction.**
+**Complete scheduling solution: campaigns, dayparting, interrupts, overlays, and timeline prediction.**
 
 ## Overview
 
-Complete scheduling solution for Xibo digital signage:
+Manages all aspects of digital signage scheduling to determine which layouts play when:
 
-- **Campaign scheduling** — priority-based campaign rotation with configurable play counts
-- **Dayparting** — weekly time slots with midnight-crossing support
-- **Interrupts** — percentage-based share-of-voice scheduling with even interleaving across the hour
-- **Overlays** — multiple simultaneous overlay layouts with independent scheduling and priority
-- **Geo-fencing** — location-based schedule filtering with criteria evaluation
-- **Timeline prediction** — deterministic future schedule simulation for proactive content preloading
+- **Campaign scheduling** -- groups of layouts with time windows and priorities
+- **Dayparting** -- weekly time slots (Mon-Fri 09:00-17:00, evenings, weekends) with midnight-crossing support
+- **Priority fallback** -- higher-priority layouts hide lower-priority ones; rate limiting triggers automatic fallback
+- **Rate limiting** -- `maxPlaysPerHour` with even distribution (prevents bursts, ensures spacing)
+- **Interrupts (Share of Voice)** -- layouts that must play X% of each hour, interleaved with normal content
+- **Overlays** -- layouts that appear on top of main layouts without interrupting playback
+- **Criteria evaluation** -- conditional display based on time, weather, custom display properties
+- **Geo-fencing** -- location-based filtering (point + radius, Haversine distance)
+- **Timeline prediction** -- deterministic simulation of future playback for UI overlays
+- **Default layout** -- fallback when no campaigns are active
+
+## Architecture
+
+```
+CMS Schedule XML
+        |
+        v
++-------------------------------------+
+|  Schedule Parser                    |
+|  +- campaigns[]                     |
+|  +- layouts[]                       |
+|  +- overlays[]                      |
+|  +- default layout                  |
++-------------------------------------+
+        |
+        v
++-------------------------------------+
+|  Evaluation Engine                  |
+|  +- Recurrence (Week/Day/Month)     |
+|  +- Time windows (dayparting)       |
+|  +- Criteria (weather, properties)  |
+|  +- Geo-fencing                     |
+|  +- Priority + rate-limit filtering |
++-------------------------------------+
+        |
+        v
++-------------------------------------+
+|  Schedule Queue Builder (LCM-based) |
+|  Deterministic round-robin with:    |
+|  +- Rate-limited slots (even spaced)|
+|  +- Priority fallback               |
+|  +- Default fills gaps              |
++-------------------------------------+
+        |
+        +-> getCurrentLayouts()        -> Renderer
+        +-> getLayoutsInTimeRange()    -> Timeline Overlay
+        +-> Track play history         -> Rate limiting
+```
 
 ## Installation
 
@@ -21,19 +63,245 @@ npm install @xiboplayer/schedule
 
 ## Usage
 
+### Basic scheduling
+
+```javascript
+import { ScheduleManager } from '@xiboplayer/schedule';
+
+const schedule = new ScheduleManager();
+
+schedule.setSchedule({
+  campaigns: [
+    {
+      id: 1,
+      priority: 100,
+      fromdt: '2025-01-01 09:00',
+      todt: '2025-12-31 17:00',
+      recurrenceType: 'Week',
+      recurrenceRepeatsOn: '1,2,3,4,5', // Mon-Fri
+      layouts: [
+        { id: 10, file: '10.xlf', duration: 30 },
+        { id: 11, file: '11.xlf', duration: 30 },
+      ],
+    },
+  ],
+  default: '99.xlf',
+});
+
+const layoutsToPlay = schedule.getCurrentLayouts();
+// Business hours: ['10.xlf', '11.xlf']
+// After hours: ['99.xlf'] (default)
+```
+
+### Dayparting with midnight crossing
+
 ```javascript
-import { Schedule } from '@xiboplayer/schedule';
+schedule.setSchedule({
+  layouts: [
+    {
+      id: 1,
+      file: '1.xlf',
+      recurrenceType: 'Week',
+      recurrenceRepeatsOn: '1,2,3,4,5,6,7',
+      fromdt: '1970-01-01 22:00:00', // 10 PM
+      todt: '1970-01-01 02:00:00',   // 2 AM (next day)
+    },
+  ],
+});
+
+// Friday 23:00: returns ['1.xlf']
+// Saturday 01:00: returns ['1.xlf'] (midnight crossing works)
+```
 
-const schedule = new Schedule();
-schedule.update(scheduleXml);
+### Rate limiting with even distribution
 
-const currentLayouts = schedule.getCurrentLayouts();
-const timeline = schedule.getTimeline(now, now + 3600000); // next hour
+```javascript
+schedule.setSchedule({
+  layouts: [
+    {
+      id: 1,
+      file: '1.xlf',
+      maxPlaysPerHour: 3, // 3 times per hour, evenly spaced
+    },
+  ],
+});
+
+schedule.recordPlay('1'); // Play at 09:00
+// Can't play again until 09:20 (60 / 3 = 20 min minimum gap)
+```
+
+### Interrupts (Share of Voice)
+
+```javascript
+schedule.setSchedule({
+  layouts: [
+    { id: 1, file: '1.xlf', duration: 30 },
+    { id: 2, file: '2.xlf', duration: 30, shareOfVoice: 20 }, // 20% of each hour
+  ],
+});
+
+const layouts = schedule.getCurrentLayouts();
+// Interleaved: normal, normal, interrupt, normal, normal, interrupt, ...
+```
+
+### Criteria-based display
+
+```javascript
+schedule.setSchedule({
+  layouts: [
+    {
+      id: 1,
+      file: '1.xlf',
+      criteria: [
+        { metric: 'weatherTemp', condition: 'greaterThan', value: '25', type: 'number' },
+      ],
+    },
+  ],
+});
+
+schedule.setWeatherData({ temperature: 28, humidity: 65 });
+// Layout 1 displays only when temperature > 25
+```
+
+### Geo-fencing
+
+```javascript
+schedule.setLocation(37.7749, -122.4194);
+
+schedule.setSchedule({
+  layouts: [
+    {
+      id: 1,
+      file: '1.xlf',
+      isGeoAware: true,
+      geoLocation: '37.7749,-122.4194,500', // lat,lng,radius_meters
+    },
+  ],
+});
+
+// Returns ['1.xlf'] only if player is within 500m
+```
+
+### Timeline prediction
+
+```javascript
+const timeline = calculateTimeline(queue, queuePosition, {
+  from: new Date(),
+  hours: 2,
+  defaultLayout: schedule.schedule.default,
+  durations: durations,
+});
+
+// Returns:
+// [
+//   { layoutFile: '10.xlf', startTime, endTime, duration: 30, isDefault: false },
+//   { layoutFile: '11.xlf', startTime, endTime, duration: 30, isDefault: false },
+//   ...
+// ]
+```
+
+## Campaign Evaluation Algorithm
+
+When `getCurrentLayouts()` is called:
+
+1. **Filter time-active items** -- campaigns and standalone layouts within their date/time window and recurrence rules
+2. **Apply criteria** -- filter by weather, display properties, geo-fencing
+3. **Apply rate limiting** -- exclude layouts that exceeded `maxPlaysPerHour`
+4. **Find max priority** -- only max priority items win
+5. **Extract layouts** -- campaigns return all their layouts; standalone layouts contribute themselves
+6. **Process interrupts** -- separate interrupt layouts, calculate share-of-voice, interleave
+7. **Return layout files** -- ready for the renderer
+
+## Key Concepts
+
+### Schedule Queue (LCM-based)
+
+The queue is a pre-computed, deterministic round-robin cycle:
+
+- **LCM period** -- Least Common Multiple of all `maxPlaysPerHour` intervals (capped at 2 hours)
+- **Simulation** -- walks the period applying priority and rate-limit rules at each step
+- **Caching** -- reused until the active layout set changes
+- **Predictable** -- answers "what's playing in 30 minutes?" offline
+
+### Dayparting
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Week | Specific days + time-of-day | Mon-Fri 09:00-17:00 |
+| Day | Daily with optional interval | Every 2 days |
+| Month | Specific days of month | 1st, 15th (monthly) |
+
+Midnight crossing: `22:00 - 02:00` works across day boundaries.
+
+### Criteria Evaluation
+
+**Built-in metrics:** `dayOfWeek`, `dayOfMonth`, `month`, `hour`, `isoDay`
+
+**Weather metrics:** `weatherTemp`, `weatherHumidity`, `weatherWindSpeed`, `weatherCondition`, `weatherCloudCover`
+
+**Operators:** `equals`, `notEquals`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `contains`, `startsWith`, `endsWith`, `in`
+
+### Geo-fencing
+
+- Format: `"lat,lng,radius"` (e.g., `"37.7749,-122.4194,500"`)
+- Default radius: 500 meters
+- Calculation: Haversine formula (great-circle distance)
+- Permissive: if no location available, layout displays (fail-open for offline)
+
+## API Reference
+
+### Constructor
+
+```javascript
+new ScheduleManager(options?)
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `interruptScheduler` | InterruptScheduler? | Optional interrupt handler |
+| `displayProperties` | Object? | Custom display fields from CMS |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `setSchedule(schedule)` | void | Load schedule from XMDS response |
+| `getCurrentLayouts()` | string[] | Layouts active now |
+| `getLayoutsAtTime(date)` | string[] | Layouts at specific time |
+| `getAllLayoutsAtTime(date)` | Array | All time-active layouts with metadata |
+| `getScheduleQueue(durations)` | {queue, periodSeconds} | Pre-computed round-robin queue |
+| `popNextFromQueue(durations)` | {layoutId, duration} | Pop next entry, advance position |
+| `peekNextInQueue(durations)` | {layoutId, duration} | Peek without advancing |
+| `recordPlay(layoutId)` | void | Track a play for rate limiting |
+| `canPlayLayout(layoutId, max)` | boolean | Check if layout can play now |
+| `setWeatherData(data)` | void | Update weather for criteria |
+| `setLocation(lat, lng)` | void | Set GPS location for geo-fencing |
+| `setDisplayProperties(props)` | void | Set custom display fields |
+| `detectConflicts(options)` | Array | Find priority-shadowing conflicts |
+
+### Overlay Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `setOverlays(overlays)` | void | Update overlay list |
+| `getCurrentOverlays()` | Array | Active overlays (sorted by priority) |
+| `shouldCheckOverlays(lastCheck)` | boolean | Check interval (every 60s) |
+
+### Timeline Functions
+
+```javascript
+import { calculateTimeline, parseLayoutDuration, buildScheduleQueue } from '@xiboplayer/schedule';
+
+const { duration } = parseLayoutDuration(xlfXml, videoDurations?);
+const { queue, periodSeconds } = buildScheduleQueue(allLayouts, durations);
+const timeline = calculateTimeline(queue, position, { from, hours, defaultLayout, durations });
 ```
 
 ## Dependencies
 
-- `@xiboplayer/utils` — logger, events
+No external dependencies -- fully self-contained scheduling engine.
+
+- `@xiboplayer/utils` -- logging only
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/schedule",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Complete scheduling solution: campaigns, dayparting, interrupts, and overlays",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
     "./overlays": "./src/overlays.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.6.2"
+    "@xiboplayer/utils": "0.6.4"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/index.d.ts

@@ -14,6 +14,6 @@ export class ScheduleManager {
 
 export const scheduleManager: ScheduleManager;
 
-export function calculateTimeline(layouts: any[], durations: Map<string, number>, options?: any): any[];
+export function calculateTimeline(queue: Array<{layoutId: string, duration: number}>, queuePosition: number, options?: any): any[];
 export function parseLayoutDuration(xlf: string, videoDurations?: Map<string, number> | null): { duration: number; isDynamic: boolean };
 export function buildScheduleQueue(schedule: any, durations: Map<string, number>): any[];

package/src/schedule.dayparting.test.js

@@ -35,13 +35,8 @@ function getDifferentDay() {
 
 // Helper to mock Date at specific time
 function mockTimeAt(targetDate) {
-  const RealDate = Date;
-  vi.spyOn(global, 'Date').mockImplementation((...args) => {
-    if (args.length === 0) {
-      return new RealDate(targetDate);
-    }
-    return new RealDate(...args);
-  });
+  vi.useFakeTimers({ shouldAdvanceTime: false });
+  vi.setSystemTime(new Date(targetDate));
 }
 
 describe('ScheduleManager - Dayparting', () => {
@@ -50,14 +45,10 @@ describe('ScheduleManager - Dayparting', () => {
 
   beforeEach(() => {
     manager = new ScheduleManager();
-    originalDate = global.Date;
   });
 
   afterEach(() => {
-    // Restore Date
-    if (vi.isMockFunction(global.Date)) {
-      global.Date = originalDate;
-    }
+    vi.useRealTimers();
   });
 
   describe('Weekday Schedules', () => {

package/src/timeline.js

@@ -38,7 +38,9 @@ export function parseLayoutDuration(xlfXml, videoDurations = null) {
   let maxDuration = 0;
   let isDynamic = false;
   for (const regionEl of layoutEl.querySelectorAll('region')) {
-    if (regionEl.getAttribute('type') === 'drawer') continue; // Drawers are action-triggered, not timed
+    const regionType = regionEl.getAttribute('type');
+    if (regionType === 'drawer') continue; // Drawers are action-triggered, not timed
+    const isCanvas = regionType === 'canvas';
     let regionDuration = 0;
     for (const mediaEl of regionEl.querySelectorAll('media')) {
       const dur = parseInt(mediaEl.getAttribute('duration') || '0', 10);
@@ -46,16 +48,24 @@ export function parseLayoutDuration(xlfXml, videoDurations = null) {
       const fileId = mediaEl.getAttribute('fileId') || '';
       const probed = videoDurations?.get(fileId);
 
+      let widgetDuration;
       if (probed !== undefined) {
-        regionDuration += probed;         // Phase 2: probed video duration
+        widgetDuration = probed;           // Phase 2: probed video duration
       } else if (dur > 0 && useDuration !== 0) {
-        regionDuration += dur;            // Explicit CMS duration
+        widgetDuration = dur;              // Explicit CMS duration
       } else {
         // Video with useDuration=0 means "play to end" — estimate 60s,
         // corrected later via recordLayoutDuration() when video metadata loads
-        regionDuration += 60;
+        widgetDuration = 60;
         isDynamic = true;
       }
+
+      if (isCanvas) {
+        // Canvas regions play all widgets simultaneously — duration is max, not sum
+        regionDuration = Math.max(regionDuration, widgetDuration);
+      } else {
+        regionDuration += widgetDuration;
+      }
     }
     maxDuration = Math.max(maxDuration, regionDuration);
   }
@@ -110,23 +120,6 @@ function canSimulatedPlay(history, maxPlaysPerHour, timeMs) {
   return true;
 }
 
-/**
- * Seed simulated play history from real play history.
- * Maps layoutId-based history to layoutFile-based history.
- * @param {Map<string, number[]>} realHistory - schedule.playHistory (layoutId → [timestamps])
- * @returns {Map<string, number[]>} layoutFile → [timestamps]
- */
-function seedPlayHistory(realHistory) {
-  const simulated = new Map();
-  if (!realHistory) return simulated;
-
-  for (const [layoutId, timestamps] of realHistory) {
-    const file = `${layoutId}.xlf`;
-    simulated.set(file, [...timestamps]);
-  }
-  return simulated;
-}
-
 /**
  * From a list of layout metadata, apply simulated rate limiting and priority
  * filtering to determine which layouts can actually play at the given time.
@@ -156,129 +149,62 @@ function getPlayableLayouts(allLayouts, simPlays, timeMs) {
 }
 
 /**
- * Calculate a deterministic playback timeline by simulating round-robin scheduling
- * with rate limiting (maxPlaysPerHour) and priority fallback. Produces a real
- * schedule prediction that matches actual player behavior.
+ * Calculate a deterministic playback timeline by walking the pre-built schedule queue.
  *
- * When high-priority layouts hit their maxPlaysPerHour limit, the simulation
- * falls back to lower-priority scheduled layouts before using the CMS default.
+ * The queue already has all constraints baked in (maxPlaysPerHour, priorities,
+ * dayparting, default layout fills). This function simply cycles through it from
+ * the current position, generating time-stamped entries for the overlay.
  *
- * @param {Object} schedule - ScheduleManager instance (needs getAllLayoutsAtTime(), schedule.default, playHistory)
- * @param {Map<string, number>} durations - Map of layoutFile → duration in seconds
+ * @param {Array<{layoutId: string, duration: number}>} queue - Pre-built schedule queue from buildScheduleQueue()
+ * @param {number} queuePosition - Current position in the queue (from schedule._queuePosition)
  * @param {Object} [options]
  * @param {Date}   [options.from]    - Start time (default: now)
- * @param {number} [options.hours]   - Hours to simulate (default: 2)
- * @param {number} [options.defaultDuration] - Fallback duration in seconds (default: 60)
+ * @param {number} [options.hours]   - Hours to project (default: 2)
+ * @param {string} [options.defaultLayout] - Default layout file (to tag isDefault entries)
+ * @param {Map<string, number>} [options.durations] - Live durations map (overrides queue entry durations with corrected values)
  * @param {Date}   [options.currentLayoutStartedAt] - When current layout started (adjusts first entry to remaining time)
  * @returns {Array<{layoutFile: string, startTime: Date, endTime: Date, duration: number, isDefault: boolean}>}
  */
-export function calculateTimeline(schedule, durations, options = {}) {
+export function calculateTimeline(queue, queuePosition, options = {}) {
   const from = options.from || new Date();
   const hours = options.hours || 2;
   const to = new Date(from.getTime() + hours * 3600000);
-  const defaultDuration = options.defaultDuration || 60;
   const currentLayoutStartedAt = options.currentLayoutStartedAt || null;
+  const defaultLayout = options.defaultLayout || null;
+  const durations = options.durations || null;
+
+  if (!queue || queue.length === 0) return [];
+
   const timeline = [];
   let currentTime = new Date(from);
+  let pos = queuePosition % queue.length;
   let isFirstEntry = true;
-
-  // Use getAllLayoutsAtTime if available (new API), fall back to getLayoutsAtTime (old API)
-  const hasFullApi = typeof schedule.getAllLayoutsAtTime === 'function';
-
-  // Seed simulated play history from real plays
-  const simPlays = seedPlayHistory(schedule.playHistory);
-
   const maxEntries = 500;
 
   while (currentTime < to && timeline.length < maxEntries) {
-    const timeMs = currentTime.getTime();
-    let playable;
-
-    let hiddenLayouts = null;
-
-    if (hasFullApi) {
-      // Full simulation: get ALL active layouts, apply rate limiting + priority
-      const allLayouts = schedule.getAllLayoutsAtTime(currentTime);
-      playable = allLayouts.length > 0
-        ? getPlayableLayouts(allLayouts, simPlays, timeMs)
-        : [];
-      // Detect hidden layouts (lower priority, not playing)
-      if (allLayouts.length > playable.length) {
-        hiddenLayouts = allLayouts
-          .filter(l => !playable.includes(l.file))
-          .map(l => ({ file: l.file, priority: l.priority }));
-      }
-    } else {
-      // Legacy fallback: no rate limiting simulation
-      playable = schedule.getLayoutsAtTime(currentTime);
-    }
-
-    if (playable.length === 0) {
-      // No playable layouts — use CMS default or skip ahead
-      const defaultFile = schedule.schedule?.default;
-      if (defaultFile) {
-        const dur = durations.get(defaultFile) || defaultDuration;
-        timeline.push({
-          layoutFile: defaultFile,
-          startTime: new Date(currentTime),
-          endTime: new Date(timeMs + dur * 1000),
-          duration: dur,
-          isDefault: true,
-        });
-        currentTime = new Date(timeMs + dur * 1000);
-      } else {
-        currentTime = new Date(timeMs + 60000);
-      }
-      continue;
-    }
-
-    // Round-robin through playable layouts
-    for (let i = 0; i < playable.length && currentTime < to && timeline.length < maxEntries; i++) {
-      const file = playable[i];
-      let dur = durations.get(file) || defaultDuration;
-
-      // First entry: use remaining duration if we know when the current layout started
-      if (isFirstEntry && currentLayoutStartedAt) {
-        const elapsedSec = (from.getTime() - currentLayoutStartedAt.getTime()) / 1000;
-        const remaining = Math.max(1, Math.round(dur - elapsedSec));
-        dur = remaining;
-        isFirstEntry = false;
-      }
-
-      const endMs = currentTime.getTime() + dur * 1000;
-
-      const entry = {
-        layoutFile: file,
-        startTime: new Date(currentTime),
-        endTime: new Date(endMs),
-        duration: dur,
-        isDefault: false,
-      };
-      if (hiddenLayouts && hiddenLayouts.length > 0) {
-        entry.hidden = hiddenLayouts;
-      }
-      timeline.push(entry);
-
-      // Record simulated play
-      if (hasFullApi) {
-        if (!simPlays.has(file)) simPlays.set(file, []);
-        simPlays.get(file).push(currentTime.getTime());
-      }
-
-      currentTime = new Date(endMs);
-
-      // Re-evaluate: if playable set changed, re-enter outer loop
-      if (hasFullApi) {
-        const nextAll = schedule.getAllLayoutsAtTime(currentTime);
-        const nextPlayable = nextAll.length > 0
-          ? getPlayableLayouts(nextAll, simPlays, currentTime.getTime())
-          : [];
-        if (!arraysEqual(playable, nextPlayable)) break;
-      } else {
-        const next = schedule.getLayoutsAtTime(currentTime);
-        if (!arraysEqual(playable, next)) break;
-      }
-    }
+    const entry = queue[pos];
+    // Use live-corrected duration (from video metadata, etc.) if available,
+    // otherwise fall back to the queue's baked-in duration
+    let dur = (durations && durations.get(entry.layoutId)) || entry.duration;
+
+    // Note: queuePosition has already advanced past the current layout
+    // (via popNextFromQueue), so the first entry here is the NEXT layout.
+    // No elapsed-time adjustment needed — the overlay handles countdown
+    // for the current layout via wall-clock layoutStartedAt.
+    isFirstEntry = false;
+
+    const endMs = currentTime.getTime() + dur * 1000;
+
+    timeline.push({
+      layoutFile: entry.layoutId,
+      startTime: new Date(currentTime),
+      endTime: new Date(endMs),
+      duration: dur,
+      isDefault: defaultLayout ? entry.layoutId === defaultLayout : false,
+    });
+
+    currentTime = new Date(endMs);
+    pos = (pos + 1) % queue.length;
   }
 
   return timeline;

package/src/timeline.test.js

@@ -1,60 +1,25 @@
 /**
  * Timeline Calculator Tests
  *
- * Tests for calculateTimeline() — the pure simulation function that produces
- * deterministic playback predictions from schedule + durations.
+ * Tests for calculateTimeline() — walks a pre-built queue to produce
+ * time-stamped playback predictions for the overlay.
  */
 
 import { describe, it, expect } from 'vitest';
 import { calculateTimeline, parseLayoutDuration } from './timeline.js';
 
-// ── Helpers ──────────────────────────────────────────────────────
-
-/** Create a mock schedule with getAllLayoutsAtTime() support */
-function createMockSchedule({ layouts = [], defaultLayout = null, playHistory = null } = {}) {
-  return {
-    schedule: { default: defaultLayout },
-    playHistory: playHistory || new Map(),
-    getAllLayoutsAtTime(time) {
-      const t = time.getTime();
-      return layouts.filter(l => {
-        const from = new Date(l.fromdt).getTime();
-        const to = new Date(l.todt).getTime();
-        return t >= from && t < to;
-      });
-    },
-    getLayoutsAtTime(time) {
-      return this.getAllLayoutsAtTime(time).map(l => l.file);
-    },
-  };
-}
-
-function hoursFromNow(h) {
-  return new Date(Date.now() + h * 3600000).toISOString();
-}
-
 // Fixed "now" for deterministic tests
 const NOW = new Date('2026-03-03T10:00:00Z');
 
-function fixedDate(isoTime) {
-  return new Date(isoTime);
-}
-
 // ── Tests ────────────────────────────────────────────────────────
 
 describe('calculateTimeline', () => {
-  describe('Basic scheduling', () => {
-    it('should produce entries for a single scheduled layout', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 30]]);
+  describe('Basic queue walking', () => {
+    it('should produce entries from a single-entry queue', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 30 }];
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 1,
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.1,
       });
 
       expect(timeline.length).toBeGreaterThan(0);
@@ -63,189 +28,142 @@ describe('calculateTimeline', () => {
       expect(timeline[0].isDefault).toBe(false);
     });
 
-    it('should use default layout when no scheduled layouts exist', () => {
-      const schedule = createMockSchedule({
-        layouts: [],
-        defaultLayout: 'default.xlf',
-      });
-      const durations = new Map([['default.xlf', 45]]);
+    it('should tag default layout entries', () => {
+      const queue = [{ layoutId: 'default.xlf', duration: 45 }];
 
-      const timeline = calculateTimeline(schedule, durations, {
+      const timeline = calculateTimeline(queue, 0, {
         from: NOW, hours: 0.1,
+        defaultLayout: 'default.xlf',
       });
 
-      expect(timeline.length).toBeGreaterThan(0);
       expect(timeline[0].layoutFile).toBe('default.xlf');
       expect(timeline[0].isDefault).toBe(true);
       expect(timeline[0].duration).toBe(45);
     });
 
-    it('should use fallback duration when layout not in durations map', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map(); // No durations known
-
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 0.1, defaultDuration: 42,
-      });
-
-      expect(timeline[0].duration).toBe(42);
-    });
-
-    it('should round-robin multiple layouts at same priority', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-          { file: '200.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
-      });
-      const durations = new Map([['100.xlf', 30], ['200.xlf', 30]]);
+    it('should cycle through multiple queue entries', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 45 },
+      ];
 
-      const timeline = calculateTimeline(schedule, durations, {
+      const timeline = calculateTimeline(queue, 0, {
         from: NOW, hours: 0.1,
       });
 
-      // Both layouts should appear in the timeline
       const files = timeline.map(e => e.layoutFile);
       expect(files).toContain('100.xlf');
       expect(files).toContain('200.xlf');
+      // Should alternate
+      expect(files[0]).toBe('100.xlf');
+      expect(files[1]).toBe('200.xlf');
+      expect(files[2]).toBe('100.xlf');
     });
-  });
 
-  describe('Priority handling', () => {
-    it('should play higher priority layout over lower priority', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: 'low.xlf', priority: 5, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-          { file: 'high.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
+    it('should use live durations map over queue baked-in durations', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 60 }]; // queue says 60s
+      const durations = new Map([['100.xlf', 300]]); // video metadata says 300s
+
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.5, durations,
       });
-      const durations = new Map([['low.xlf', 30], ['high.xlf', 30]]);
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 0.5,
+      expect(timeline[0].duration).toBe(300);
+      // Only ~6 entries in 30min at 300s each, not 30 at 60s
+      expect(timeline.length).toBeLessThanOrEqual(7);
+    });
+
+    it('should fall back to queue duration when not in durations map', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 45 }];
+      const durations = new Map(); // empty
+
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.1, durations,
       });
 
-      // All entries should be high priority
-      const uniqueFiles = [...new Set(timeline.map(e => e.layoutFile))];
-      expect(uniqueFiles).toEqual(['high.xlf']);
+      expect(timeline[0].duration).toBe(45);
     });
 
-    it('should annotate hidden (overshadowed) layouts', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: 'low.xlf', priority: 5, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-          { file: 'high.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
+    it('should start from the given queue position', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 30 },
+        { layoutId: '300.xlf', duration: 30 },
+      ];
+
+      const timeline = calculateTimeline(queue, 2, {
+        from: NOW, hours: 0.1,
       });
-      const durations = new Map([['low.xlf', 30], ['high.xlf', 30]]);
 
-      const timeline = calculateTimeline(schedule, durations, {
+      expect(timeline[0].layoutFile).toBe('300.xlf');
+      expect(timeline[1].layoutFile).toBe('100.xlf');
+      expect(timeline[2].layoutFile).toBe('200.xlf');
+    });
+
+    it('should wrap queue position when past end', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 30 },
+      ];
+
+      const timeline = calculateTimeline(queue, 5, {
         from: NOW, hours: 0.1,
       });
 
-      // First entry should have hidden layouts
-      expect(timeline[0].hidden).toBeDefined();
-      expect(timeline[0].hidden).toEqual(
-        expect.arrayContaining([expect.objectContaining({ file: 'low.xlf' })])
-      );
+      // 5 % 2 = 1, so starts at 200.xlf
+      expect(timeline[0].layoutFile).toBe('200.xlf');
+      expect(timeline[1].layoutFile).toBe('100.xlf');
     });
   });
 
-  describe('Rate limiting (maxPlaysPerHour)', () => {
-    it('should respect maxPlaysPerHour by falling back to lower priority', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: 'limited.xlf', priority: 10, maxPlaysPerHour: 2,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-          { file: 'filler.xlf', priority: 5, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
-      });
-      const durations = new Map([['limited.xlf', 30], ['filler.xlf', 30]]);
+  describe('currentLayoutStartedAt (no adjustment — queuePosition already advanced)', () => {
+    it('should not adjust first entry duration since queue has advanced past current layout', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 60 }];
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 1,
-      });
+      // currentLayoutStartedAt is ignored — the first timeline entry is the
+      // NEXT layout (queuePosition already advanced via popNextFromQueue)
+      const startedAt = new Date(NOW.getTime() - 20000);
 
-      // limited.xlf should appear at most 2 times in the hour
-      const limitedPlays = timeline.filter(e => e.layoutFile === 'limited.xlf');
-      expect(limitedPlays.length).toBeLessThanOrEqual(2);
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.5,
+        currentLayoutStartedAt: startedAt,
+      });
 
-      // filler.xlf should fill the gaps
-      const fillerPlays = timeline.filter(e => e.layoutFile === 'filler.xlf');
-      expect(fillerPlays.length).toBeGreaterThan(0);
+      expect(timeline[0].duration).toBe(60); // Full duration, no adjustment
     });
 
-    it('should fall back to default when all layouts are rate-limited', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: 'limited.xlf', priority: 10, maxPlaysPerHour: 1,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
-        defaultLayout: 'default.xlf',
-      });
-      const durations = new Map([['limited.xlf', 30], ['default.xlf', 30]]);
+    it('should use full duration even when layout would be overdue', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 30 }];
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 1,
-      });
+      const startedAt = new Date(NOW.getTime() - 60000);
 
-      // Should have both limited and default layouts
-      const files = [...new Set(timeline.map(e => e.layoutFile))];
-      expect(files).toContain('limited.xlf');
-      expect(files).toContain('default.xlf');
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.1,
+        currentLayoutStartedAt: startedAt,
+      });
 
-      // limited.xlf at most once per hour
-      const limitedPlays = timeline.filter(e => e.layoutFile === 'limited.xlf');
-      expect(limitedPlays.length).toBeLessThanOrEqual(1);
+      expect(timeline[0].duration).toBe(30); // Full duration
     });
-  });
 
-  describe('Time boundaries', () => {
-    it('should stop at schedule end time', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T10:00:00Z', todt: '2026-03-03T10:30:00Z',
-        }],
-        defaultLayout: 'default.xlf',
-      });
-      const durations = new Map([['100.xlf', 60], ['default.xlf', 60]]);
+    it('should use full duration for all entries', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 60 }];
+      const startedAt = new Date(NOW.getTime() - 20000);
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 1,
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.1,
+        currentLayoutStartedAt: startedAt,
       });
 
-      // After 10:30, should switch to default
-      const afterEnd = timeline.filter(e =>
-        e.startTime >= new Date('2026-03-03T10:30:00Z')
-      );
-      for (const entry of afterEnd) {
-        expect(entry.layoutFile).toBe('default.xlf');
-      }
+      expect(timeline[0].duration).toBe(60); // Full duration
+      expect(timeline[1].duration).toBe(60); // Full duration
     });
+  });
 
+  describe('Time boundaries', () => {
     it('should not produce entries beyond the simulation window', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T14:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 30]]);
+      const queue = [{ layoutId: '100.xlf', duration: 30 }];
 
-      const timeline = calculateTimeline(schedule, durations, {
+      const timeline = calculateTimeline(queue, 0, {
         from: NOW, hours: 1,
       });
 
@@ -254,64 +172,42 @@ describe('calculateTimeline', () => {
         expect(entry.startTime.getTime()).toBeLessThan(endOfWindow.getTime());
       }
     });
-  });
 
-  describe('currentLayoutStartedAt (remaining time adjustment)', () => {
-    it('should adjust first entry duration to remaining time', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 60]]);
-
-      // Layout started 20 seconds ago → 40 seconds remaining
-      const startedAt = new Date(NOW.getTime() - 20000);
+    it('should produce continuous timeline (no gaps between entries)', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 45 },
+      ];
 
-      const timeline = calculateTimeline(schedule, durations, {
+      const timeline = calculateTimeline(queue, 0, {
         from: NOW, hours: 0.5,
-        currentLayoutStartedAt: startedAt,
       });
 
-      expect(timeline[0].duration).toBe(40); // 60 - 20 = 40
+      for (let i = 1; i < timeline.length; i++) {
+        expect(timeline[i].startTime.getTime()).toBe(timeline[i - 1].endTime.getTime());
+      }
     });
 
-    it('should clamp remaining time to at least 1 second', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 30]]);
-
-      // Layout started 60 seconds ago but duration is only 30 → already overdue
-      const startedAt = new Date(NOW.getTime() - 60000);
+    it('should handle a large number of entries without exceeding 500 cap', () => {
+      const queue = [{ layoutId: '100.xlf', duration: 5 }]; // 5s = many entries
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 0.1,
-        currentLayoutStartedAt: startedAt,
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 2,
       });
 
-      expect(timeline[0].duration).toBeGreaterThanOrEqual(1);
+      expect(timeline.length).toBeLessThanOrEqual(500);
     });
   });
 
   describe('Determinism', () => {
     it('should produce identical output for identical inputs', () => {
-      const schedule = createMockSchedule({
-        layouts: [
-          { file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-          { file: '200.xlf', priority: 10, maxPlaysPerHour: 0,
-            fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z' },
-        ],
-      });
-      const durations = new Map([['100.xlf', 30], ['200.xlf', 45]]);
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 45 },
+      ];
 
-      const t1 = calculateTimeline(schedule, durations, { from: NOW, hours: 1 });
-      const t2 = calculateTimeline(schedule, durations, { from: NOW, hours: 1 });
+      const t1 = calculateTimeline(queue, 0, { from: NOW, hours: 1 });
+      const t2 = calculateTimeline(queue, 0, { from: NOW, hours: 1 });
 
       expect(t1.length).toBe(t2.length);
       for (let i = 0; i < t1.length; i++) {
@@ -323,67 +219,54 @@ describe('calculateTimeline', () => {
     });
 
     it('should produce DIFFERENT output when "from" time changes', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 30]]);
+      const queue = [{ layoutId: '100.xlf', duration: 30 }];
 
-      const t1 = calculateTimeline(schedule, durations, { from: NOW, hours: 1 });
+      const t1 = calculateTimeline(queue, 0, { from: NOW, hours: 1 });
       const laterNow = new Date(NOW.getTime() + 300000); // 5 min later
-      const t2 = calculateTimeline(schedule, durations, { from: laterNow, hours: 1 });
+      const t2 = calculateTimeline(queue, 0, { from: laterNow, hours: 1 });
 
       // Start times must differ because the anchor moved
       expect(t1[0].startTime.getTime()).not.toBe(t2[0].startTime.getTime());
     });
-  });
 
-  describe('Edge cases', () => {
-    it('should return empty array when no layouts and no default', () => {
-      const schedule = createMockSchedule({ layouts: [], defaultLayout: null });
-      const durations = new Map();
+    it('should produce DIFFERENT output when position changes', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: '200.xlf', duration: 30 },
+      ];
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 1,
-      });
+      const t1 = calculateTimeline(queue, 0, { from: NOW, hours: 0.1 });
+      const t2 = calculateTimeline(queue, 1, { from: NOW, hours: 0.1 });
 
-      expect(timeline).toEqual([]);
+      expect(t1[0].layoutFile).toBe('100.xlf');
+      expect(t2[0].layoutFile).toBe('200.xlf');
     });
+  });
 
-    it('should handle a large number of entries without exceeding 500 cap', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T20:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 5]]); // 5s = many entries
-
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 2,
-      });
+  describe('Edge cases', () => {
+    it('should return empty array for empty queue', () => {
+      const timeline = calculateTimeline([], 0, { from: NOW, hours: 1 });
+      expect(timeline).toEqual([]);
+    });
 
-      expect(timeline.length).toBeLessThanOrEqual(500);
+    it('should return empty array for null queue', () => {
+      const timeline = calculateTimeline(null, 0, { from: NOW, hours: 1 });
+      expect(timeline).toEqual([]);
     });
 
-    it('should produce continuous timeline (no gaps between entries)', () => {
-      const schedule = createMockSchedule({
-        layouts: [{
-          file: '100.xlf', priority: 10, maxPlaysPerHour: 0,
-          fromdt: '2026-03-03T09:00:00Z', todt: '2026-03-03T12:00:00Z',
-        }],
-      });
-      const durations = new Map([['100.xlf', 30]]);
+    it('should handle mixed default and scheduled entries in queue', () => {
+      const queue = [
+        { layoutId: '100.xlf', duration: 30 },
+        { layoutId: 'default.xlf', duration: 60 },
+      ];
 
-      const timeline = calculateTimeline(schedule, durations, {
-        from: NOW, hours: 0.5,
+      const timeline = calculateTimeline(queue, 0, {
+        from: NOW, hours: 0.1,
+        defaultLayout: 'default.xlf',
       });
 
-      for (let i = 1; i < timeline.length; i++) {
-        expect(timeline[i].startTime.getTime()).toBe(timeline[i - 1].endTime.getTime());
-      }
+      expect(timeline[0].isDefault).toBe(false);
+      expect(timeline[1].isDefault).toBe(true);
     });
   });
 });
@@ -468,6 +351,41 @@ describe('parseLayoutDuration', () => {
     });
   });
 
+  describe('Canvas region duration (#186)', () => {
+    it('should use max widget duration for canvas regions (not sum)', () => {
+      const result = parseLayoutDuration(xlf({
+        regions: [
+          { type: 'canvas', widgets: [
+            { duration: 10, useDuration: 1 },
+            { duration: 30, useDuration: 1 },
+            { duration: 20, useDuration: 1 },
+          ]},
+        ],
+      }));
+      // Canvas: max(10, 30, 20) = 30, not sum(10+30+20) = 60
+      expect(result).toEqual({ duration: 30, isDynamic: false });
+    });
+
+    it('should use sum for normal regions alongside canvas', () => {
+      const result = parseLayoutDuration(xlf({
+        regions: [
+          { type: 'canvas', widgets: [
+            { duration: 10, useDuration: 1 },
+            { duration: 20, useDuration: 1 },
+          ]},
+          { widgets: [
+            { duration: 15, useDuration: 1 },
+            { duration: 25, useDuration: 1 },
+          ]},
+        ],
+      }));
+      // Canvas region: max(10, 20) = 20
+      // Normal region: sum(15+25) = 40
+      // Layout: max(20, 40) = 40
+      expect(result).toEqual({ duration: 40, isDynamic: false });
+    });
+  });
+
   describe('videoDurations (Phase 2 probing)', () => {
     it('should use probed duration when fileId matches', () => {
       const videoDurations = new Map([['vid1', 45]]);