@xiboplayer/schedule 0.3.7 → 0.4.0

package/package.json

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

package/src/criteria.js

@@ -12,6 +12,13 @@
  * - hour: Hour (0-23)
  * - isoDay: ISO day of week (1=Monday, 7=Sunday)
  *
+ * Weather metrics (require weatherData in options):
+ * - weatherTemp: Current temperature
+ * - weatherHumidity: Current humidity percentage
+ * - weatherWindSpeed: Current wind speed
+ * - weatherCondition: Current weather condition (e.g. "Clear", "Rain")
+ * - weatherCloudCover: Cloud cover percentage
+ *
  * Supported conditions:
  * - equals, notEquals
  * - greaterThan, greaterThanOrEquals, lessThan, lessThanOrEquals
@@ -28,14 +35,26 @@ const log = createLogger('schedule:criteria');
 
 const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
+/**
+ * Weather metric name → weatherData property mapping
+ */
+const WEATHER_METRICS = {
+  weatherTemp: 'temperature',
+  weatherHumidity: 'humidity',
+  weatherWindSpeed: 'windSpeed',
+  weatherCondition: 'condition',
+  weatherCloudCover: 'cloudCover',
+};
+
 /**
  * Get built-in metric value from current date/time
  * @param {string} metric - Metric name
  * @param {Date} now - Current date
  * @param {Object} displayProperties - Display property map from CMS
+ * @param {Object} weatherData - Weather data from GetWeather XMDS call
  * @returns {string|null} Metric value or null if unknown
  */
-function getMetricValue(metric, now, displayProperties = {}) {
+function getMetricValue(metric, now, displayProperties = {}, weatherData = {}) {
   switch (metric) {
     case 'dayOfWeek':
       return DAY_NAMES[now.getDay()];
@@ -48,6 +67,15 @@ function getMetricValue(metric, now, displayProperties = {}) {
     case 'isoDay':
       return String(now.getDay() === 0 ? 7 : now.getDay());
     default:
+      // Check weather metrics
+      if (WEATHER_METRICS[metric]) {
+        const weatherKey = WEATHER_METRICS[metric];
+        if (weatherData[weatherKey] !== undefined) {
+          return String(weatherData[weatherKey]);
+        }
+        log.debug(`Weather metric "${metric}" requested but no weather data available`);
+        return null;
+      }
       // Check display properties (custom fields set in CMS)
       if (displayProperties[metric] !== undefined) {
         return String(displayProperties[metric]);
@@ -113,6 +141,7 @@ function evaluateCondition(actual, condition, expected, type) {
  * @param {Object} options
  * @param {Date} [options.now] - Current date (defaults to new Date())
  * @param {Object} [options.displayProperties] - Display property map from CMS
+ * @param {Object} [options.weatherData] - Weather data from GetWeather XMDS call
  * @returns {boolean} True if all criteria match (or no criteria)
  */
 export function evaluateCriteria(criteria, options = {}) {
@@ -120,9 +149,10 @@ export function evaluateCriteria(criteria, options = {}) {
 
   const now = options.now || new Date();
   const displayProperties = options.displayProperties || {};
+  const weatherData = options.weatherData || {};
 
   for (const criterion of criteria) {
-    const actual = getMetricValue(criterion.metric, now, displayProperties);
+    const actual = getMetricValue(criterion.metric, now, displayProperties, weatherData);
     const matches = evaluateCondition(actual, criterion.condition, criterion.value, criterion.type);
 
     if (!matches) {

package/src/overlays.js

@@ -115,8 +115,8 @@ export class OverlayScheduler {
    * @returns {boolean}
    */
   isTimeActive(overlay, now) {
-    const from = overlay.fromDt ? new Date(overlay.fromDt) : null;
-    const to = overlay.toDt ? new Date(overlay.toDt) : null;
+    const from = (overlay.fromdt || overlay.fromDt) ? new Date(overlay.fromdt || overlay.fromDt) : null;
+    const to = (overlay.todt || overlay.toDt) ? new Date(overlay.todt || overlay.toDt) : null;
 
     // Check time bounds
     if (from && now < from) {

package/src/schedule.dayparting.test.js

@@ -387,4 +387,248 @@ describe('ScheduleManager - Dayparting', () => {
       expect(layouts[0]).toBe('999');
     });
   });
+
+  describe('Daily Recurrence', () => {
+    it('should activate daily schedule during time window', () => {
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          {
+            file: '800',
+            priority: 10,
+            fromdt: timeStr(9, 0),
+            todt: timeStr(17, 0),
+            recurrenceType: 'Day',
+          }
+        ],
+        campaigns: []
+      });
+
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('800');
+    });
+
+    it('should not activate daily schedule outside time window', () => {
+      manager.setSchedule({
+        default: '999',
+        layouts: [
+          {
+            file: '800',
+            priority: 10,
+            fromdt: timeStr(9, 0),
+            todt: timeStr(17, 0),
+            recurrenceType: 'Day',
+          }
+        ],
+        campaigns: []
+      });
+
+      const earlyMorning = new Date();
+      earlyMorning.setHours(7, 0, 0, 0);
+      mockTimeAt(earlyMorning);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('999');
+    });
+
+    it('should respect recurrenceDetail interval (every N days)', () => {
+      // Create a schedule that started 2 days ago with interval=2
+      const startDate = new Date();
+      startDate.setDate(startDate.getDate() - 2);
+      startDate.setHours(9, 0, 0, 0);
+
+      const endDate = new Date();
+      endDate.setDate(endDate.getDate() + 30);
+      endDate.setHours(17, 0, 0, 0);
+
+      manager.setSchedule({
+        default: '999',
+        layouts: [
+          {
+            file: '801',
+            priority: 10,
+            fromdt: startDate.toISOString(),
+            todt: endDate.toISOString(),
+            recurrenceType: 'Day',
+            recurrenceDetail: 2,
+          }
+        ],
+        campaigns: []
+      });
+
+      // 2 days later = day 2, 2 % 2 = 0, should be active
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('801');
+    });
+
+    it('should skip days not matching interval', () => {
+      // Create a schedule that started 3 days ago with interval=2
+      const startDate = new Date();
+      startDate.setDate(startDate.getDate() - 3);
+      startDate.setHours(9, 0, 0, 0);
+
+      const endDate = new Date();
+      endDate.setDate(endDate.getDate() + 30);
+      endDate.setHours(17, 0, 0, 0);
+
+      manager.setSchedule({
+        default: '999',
+        layouts: [
+          {
+            file: '802',
+            priority: 10,
+            fromdt: startDate.toISOString(),
+            todt: endDate.toISOString(),
+            recurrenceType: 'Day',
+            recurrenceDetail: 2,
+          }
+        ],
+        campaigns: []
+      });
+
+      // 3 days later = day 3, 3 % 2 = 1, should NOT be active
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('999');
+    });
+  });
+
+  describe('Monthly Recurrence', () => {
+    it('should activate on matching day of month', () => {
+      const today = new Date();
+      const dayOfMonth = today.getDate();
+
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          {
+            file: '900',
+            priority: 10,
+            fromdt: timeStr(9, 0),
+            todt: timeStr(17, 0),
+            recurrenceType: 'Month',
+            recurrenceRepeatsOn: dayOfMonth.toString(),
+          }
+        ],
+        campaigns: []
+      });
+
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('900');
+    });
+
+    it('should not activate on wrong day of month', () => {
+      const today = new Date();
+      // Pick a day that isn't today (and is valid 1-28)
+      const otherDay = today.getDate() === 15 ? 16 : 15;
+
+      manager.setSchedule({
+        default: '999',
+        layouts: [
+          {
+            file: '901',
+            priority: 10,
+            fromdt: timeStr(9, 0),
+            todt: timeStr(17, 0),
+            recurrenceType: 'Month',
+            recurrenceRepeatsOn: otherDay.toString(),
+          }
+        ],
+        campaigns: []
+      });
+
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('999');
+    });
+
+    it('should support multiple days of month', () => {
+      const today = new Date();
+      const dayOfMonth = today.getDate();
+
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          {
+            file: '902',
+            priority: 10,
+            fromdt: timeStr(9, 0),
+            todt: timeStr(17, 0),
+            recurrenceType: 'Month',
+            recurrenceRepeatsOn: `1,${dayOfMonth},28`,
+          }
+        ],
+        campaigns: []
+      });
+
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('902');
+    });
+
+    it('should respect recurrenceDetail interval (every N months)', () => {
+      // Start date 2 months ago, interval=2 → should be active
+      const startDate = new Date();
+      startDate.setMonth(startDate.getMonth() - 2);
+      startDate.setHours(9, 0, 0, 0);
+
+      const endDate = new Date();
+      endDate.setFullYear(endDate.getFullYear() + 1);
+      endDate.setHours(17, 0, 0, 0);
+
+      const dayOfMonth = new Date().getDate();
+
+      manager.setSchedule({
+        default: '999',
+        layouts: [
+          {
+            file: '903',
+            priority: 10,
+            fromdt: startDate.toISOString(),
+            todt: endDate.toISOString(),
+            recurrenceType: 'Month',
+            recurrenceDetail: 2,
+            recurrenceRepeatsOn: dayOfMonth.toString(),
+          }
+        ],
+        campaigns: []
+      });
+
+      const noon = new Date();
+      noon.setHours(12, 0, 0, 0);
+      mockTimeAt(noon);
+
+      const layouts = manager.getCurrentLayouts();
+      expect(layouts).toHaveLength(1);
+      expect(layouts[0]).toBe('903');
+    });
+  });
 });

package/src/schedule.js

@@ -13,6 +13,7 @@ export class ScheduleManager {
     this.playHistory = new Map(); // Track plays per layout: layoutId -> [timestamps]
     this.interruptScheduler = options.interruptScheduler || null; // Optional interrupt scheduler
     this.displayProperties = options.displayProperties || {}; // CMS display custom properties
+    this.weatherData = {}; // Weather data from GetWeather XMDS call
     this.playerLocation = null; // { latitude, longitude } from Geolocation API
     this._layoutMetadata = new Map(); // layoutFile → { syncEvent, shareOfVoice, ... }
   }
@@ -24,6 +25,14 @@ export class ScheduleManager {
     this.schedule = schedule;
   }
 
+  /**
+   * Update weather data for criteria evaluation
+   * @param {Object} data - Parsed weather object { temperature, humidity, windSpeed, condition, cloudCover }
+   */
+  setWeatherData(data) {
+    this.weatherData = data || {};
+  }
+
   /**
    * Get data connectors from current schedule
    * @returns {Array} Data connector configurations, or empty array
@@ -33,8 +42,8 @@ export class ScheduleManager {
   }
 
   /**
-   * Check if a schedule item is active based on recurrence rules
-   * Supports weekly dayparting (recurring schedules on specific days/times)
+   * Check if a schedule item is active based on recurrence rules.
+   * Supports Week, Day, and Month recurrence types.
    */
   isRecurringScheduleActive(item, now) {
     // If no recurrence, it's not a recurring schedule
@@ -42,23 +51,7 @@ export class ScheduleManager {
       return true; // Not a recurring schedule, use date/time checks instead
     }
 
-    // Currently only support Weekly recurrence (dayparting)
-    if (item.recurrenceType !== 'Week') {
-      return true; // Unsupported recurrence type, fallback to date/time checks
-    }
-
-    // Check if current day of week matches recurrenceRepeatsOn
-    // recurrenceRepeatsOn format: "1,2,3,4,5" (1=Monday, 7=Sunday, ISO format)
-    if (item.recurrenceRepeatsOn) {
-      const currentDayOfWeek = this.getIsoDayOfWeek(now);
-      const allowedDays = item.recurrenceRepeatsOn.split(',').map(d => parseInt(d.trim()));
-
-      if (!allowedDays.includes(currentDayOfWeek)) {
-        return false; // Today is not in the allowed days
-      }
-    }
-
-    // Check recurrence range if specified
+    // Check recurrence range first (applies to all types)
     if (item.recurrenceRange) {
       const rangeEnd = new Date(item.recurrenceRange);
       if (now > rangeEnd) {
@@ -66,7 +59,61 @@ export class ScheduleManager {
       }
     }
 
-    return true;
+    switch (item.recurrenceType) {
+      case 'Week': {
+        // Check if current day of week matches recurrenceRepeatsOn
+        // recurrenceRepeatsOn format: "1,2,3,4,5" (1=Monday, 7=Sunday, ISO format)
+        if (item.recurrenceRepeatsOn) {
+          const currentDayOfWeek = this.getIsoDayOfWeek(now);
+          const allowedDays = item.recurrenceRepeatsOn.split(',').map(d => parseInt(d.trim()));
+          if (!allowedDays.includes(currentDayOfWeek)) {
+            return false;
+          }
+        }
+        return true;
+      }
+
+      case 'Day': {
+        // Daily recurrence with optional interval (recurrenceDetail)
+        // If recurrenceDetail > 1, only active every N days from fromdt
+        const interval = item.recurrenceDetail || 1;
+        if (interval > 1 && item.fromdt) {
+          const startDate = new Date(item.fromdt);
+          const diffMs = now.getTime() - startDate.getTime();
+          const diffDays = Math.floor(diffMs / 86400000);
+          if (diffDays < 0 || diffDays % interval !== 0) {
+            return false;
+          }
+        }
+        return true;
+      }
+
+      case 'Month': {
+        // Monthly recurrence — recurrenceRepeatsOn is day-of-month (1-31)
+        if (item.recurrenceRepeatsOn) {
+          const allowedDays = item.recurrenceRepeatsOn.split(',').map(d => parseInt(d.trim()));
+          const currentDayOfMonth = now.getDate();
+          if (!allowedDays.includes(currentDayOfMonth)) {
+            return false;
+          }
+        }
+        // If recurrenceDetail > 1, only active every N months from fromdt
+        const interval = item.recurrenceDetail || 1;
+        if (interval > 1 && item.fromdt) {
+          const startDate = new Date(item.fromdt);
+          const monthsDiff = (now.getFullYear() - startDate.getFullYear()) * 12
+            + now.getMonth() - startDate.getMonth();
+          if (monthsDiff < 0 || monthsDiff % interval !== 0) {
+            return false;
+          }
+        }
+        return true;
+      }
+
+      default:
+        log.debug(`Unsupported recurrence type: ${item.recurrenceType}`);
+        return true; // Unknown type, fallback to date/time checks
+    }
   }
 
   /**
@@ -86,7 +133,7 @@ export class ScheduleManager {
     const to = item.todt ? new Date(item.todt) : null;
 
     // For recurring schedules, check time-of-day instead of full datetime
-    if (item.recurrenceType === 'Week') {
+    if (item.recurrenceType === 'Week' || item.recurrenceType === 'Day' || item.recurrenceType === 'Month') {
       // Extract time from fromdt/todt and compare with current time
       if (from && to) {
         const currentTime = now.getHours() * 3600 + now.getMinutes() * 60 + now.getSeconds();
@@ -169,7 +216,7 @@ export class ScheduleManager {
         if (!this.isRecurringScheduleActive(layout, now)) continue;
         if (!this.isTimeActive(layout, now)) continue;
         if (layout.criteria && layout.criteria.length > 0) {
-          if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties })) continue;
+          if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties, weatherData: this.weatherData })) continue;
         }
         if (layout.isGeoAware && layout.geoLocation) {
           if (!this.isWithinGeoFence(layout.geoLocation)) continue;
@@ -200,6 +247,80 @@ export class ScheduleManager {
     return results;
   }
 
+  /**
+   * Detect schedule conflicts: time windows where multiple layouts compete
+   * and lower-priority ones are hidden.
+   *
+   * Scans the schedule in 1-minute increments over the given window.
+   * At each point, collects all time-active layouts (after criteria/geofence
+   * filtering but before priority filtering). If multiple priorities exist,
+   * the lower-priority entries are reported as hidden.
+   *
+   * @param {Object} [options]
+   * @param {Date}   [options.from]  - Start time (default: now)
+   * @param {number} [options.hours] - Hours to scan (default: 24)
+   * @returns {Array<{startTime: Date, endTime: Date, winner: {file: string, priority: number}, hidden: Array<{file: string, priority: number}>}>}
+   */
+  detectConflicts(options = {}) {
+    const from = options.from || new Date();
+    const hours = options.hours || 24;
+    const to = new Date(from.getTime() + hours * 3600000);
+    const stepMs = 60000; // 1-minute granularity
+    const conflicts = [];
+    let current = null; // Current conflict window being built
+
+    for (let t = from.getTime(); t < to.getTime(); t += stepMs) {
+      const time = new Date(t);
+      const allLayouts = this.getAllLayoutsAtTime(time);
+
+      if (allLayouts.length === 0) {
+        // No layouts → close any open conflict
+        if (current) { conflicts.push(current); current = null; }
+        continue;
+      }
+
+      const maxPriority = Math.max(...allLayouts.map(l => l.priority));
+      const hidden = allLayouts.filter(l => l.priority < maxPriority);
+
+      if (hidden.length === 0) {
+        // No conflict at this time
+        if (current) { conflicts.push(current); current = null; }
+        continue;
+      }
+
+      // Conflict exists — build or extend window
+      const winners = allLayouts.filter(l => l.priority === maxPriority);
+      const winnerKey = winners.map(w => w.file).sort().join(',');
+      const hiddenKey = hidden.map(h => `${h.file}:${h.priority}`).sort().join(',');
+
+      if (current && current._winnerKey === winnerKey && current._hiddenKey === hiddenKey) {
+        // Same conflict continues — extend window
+        current.endTime = new Date(t + stepMs);
+      } else {
+        // New or changed conflict
+        if (current) conflicts.push(current);
+        current = {
+          startTime: new Date(t),
+          endTime: new Date(t + stepMs),
+          winner: { file: winners[0].file, priority: maxPriority },
+          hidden: hidden.map(h => ({ file: h.file, priority: h.priority })),
+          _winnerKey: winnerKey,
+          _hiddenKey: hiddenKey,
+        };
+      }
+    }
+
+    if (current) conflicts.push(current);
+
+    // Clean internal keys
+    for (const c of conflicts) {
+      delete c._winnerKey;
+      delete c._hiddenKey;
+    }
+
+    return conflicts;
+  }
+
   /**
    * Internal: evaluate schedule at a given time.
    * @param {Date} now - Time to evaluate
@@ -258,7 +379,7 @@ export class ScheduleManager {
 
         // Check criteria conditions (date/time, display properties)
         if (layout.criteria && layout.criteria.length > 0) {
-          if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties })) {
+          if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties, weatherData: this.weatherData })) {
             _log('[Schedule] Layout', layout.id, 'filtered by criteria');
             continue;
           }
@@ -454,6 +575,45 @@ export class ScheduleManager {
     return this._layoutMetadata.get(layoutFile) || null;
   }
 
+  /**
+   * Get current layouts with the default layout interleaved between scheduled layouts.
+   *
+   * Xibo CMS expects the default layout (fallback) to play between each scheduled
+   * layout in the rotation. For example, with layouts [A, B, C] and default D,
+   * the result is [A, D, B, D, C, D].
+   *
+   * No interleaving when:
+   * - There is no default layout configured
+   * - There are no scheduled layouts (only default plays)
+   * - There is only one scheduled layout (no gaps to fill)
+   *
+   * @returns {string[]} Layout files with default interleaved
+   */
+  getInterleavedLayouts() {
+    const layouts = this.getCurrentLayouts();
+    const defaultLayout = this.schedule?.default;
+
+    // No interleaving needed: no default, no layouts, or single layout
+    if (!defaultLayout || layouts.length <= 1) {
+      return layouts;
+    }
+
+    // If the only layout is the default itself, return as-is
+    if (layouts.length === 1 && layouts[0] === defaultLayout) {
+      return layouts;
+    }
+
+    // Interleave: A, D, B, D, C, D
+    const interleaved = [];
+    for (const layout of layouts) {
+      interleaved.push(layout);
+      interleaved.push(defaultLayout);
+    }
+
+    log.info('[Schedule] Interleaved', layouts.length, 'layouts with default', defaultLayout);
+    return interleaved;
+  }
+
   /**
    * Check if any current layouts are sync events
    * @returns {boolean}

package/src/schedule.test.js

@@ -196,6 +196,132 @@ describe('ScheduleManager - Campaigns', () => {
   });
 });
 
+describe('ScheduleManager - Default Layout Interleaving', () => {
+  let manager;
+
+  beforeEach(() => {
+    manager = new ScheduleManager();
+  });
+
+  it('should interleave default layout between multiple scheduled layouts', () => {
+    manager.setSchedule({
+      default: '999',
+      layouts: [
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        { file: '300', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+      ],
+      campaigns: []
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    expect(layouts).toEqual(['100', '999', '200', '999', '300', '999']);
+  });
+
+  it('should not interleave when only default layout is active', () => {
+    manager.setSchedule({
+      default: '999',
+      layouts: [],
+      campaigns: []
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    expect(layouts).toEqual(['999']);
+  });
+
+  it('should not interleave when only one scheduled layout', () => {
+    manager.setSchedule({
+      default: '999',
+      layouts: [
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+      ],
+      campaigns: []
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    expect(layouts).toEqual(['100']);
+  });
+
+  it('should preserve layout order when interleaving', () => {
+    manager.setSchedule({
+      default: '999',
+      layouts: [],
+      campaigns: [
+        {
+          id: '1',
+          priority: 10,
+          fromdt: dateStr(-1),
+          todt: dateStr(1),
+          layouts: [
+            { file: '205' },
+            { file: '203' },
+            { file: '204' }
+          ]
+        }
+      ]
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    // Order must be preserved: 205, default, 203, default, 204, default
+    expect(layouts).toEqual(['205', '999', '203', '999', '204', '999']);
+  });
+
+  it('should return empty array when no schedule is set', () => {
+    const layouts = manager.getInterleavedLayouts();
+
+    expect(layouts).toEqual([]);
+  });
+
+  it('should not interleave when no default layout is configured', () => {
+    manager.setSchedule({
+      layouts: [
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+      ],
+      campaigns: []
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    // No default, so no interleaving — just the scheduled layouts
+    expect(layouts).toEqual(['100', '200']);
+  });
+
+  it('should interleave with campaign and standalone layouts at same priority', () => {
+    manager.setSchedule({
+      default: '999',
+      layouts: [
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+      ],
+      campaigns: [
+        {
+          id: '1',
+          priority: 10,
+          fromdt: dateStr(-1),
+          todt: dateStr(1),
+          layouts: [
+            { file: '200' },
+            { file: '201' }
+          ]
+        }
+      ]
+    });
+
+    const layouts = manager.getInterleavedLayouts();
+
+    // 3 scheduled layouts + 3 default insertions = 6
+    expect(layouts).toHaveLength(6);
+    // Every odd-indexed element should be the default
+    expect(layouts[1]).toBe('999');
+    expect(layouts[3]).toBe('999');
+    expect(layouts[5]).toBe('999');
+  });
+});
+
 describe('ScheduleManager - Actions and Commands', () => {
   let manager;
 
@@ -502,4 +628,83 @@ describe('ScheduleManager - Actions and Commands', () => {
       expect(commands).toEqual([]);
     });
   });
+
+  describe('Conflict Detection', () => {
+    it('should detect no conflicts when all layouts share the same priority', () => {
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          { file: '100', priority: 5, fromdt: dateStr(-1), todt: dateStr(1) },
+          { file: '101', priority: 5, fromdt: dateStr(-1), todt: dateStr(1) },
+        ],
+        campaigns: [],
+      });
+
+      const conflicts = manager.detectConflicts({ hours: 2 });
+      expect(conflicts).toEqual([]);
+    });
+
+    it('should detect conflict when higher-priority layout hides lower-priority', () => {
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          { file: '100', priority: 5, fromdt: dateStr(-1), todt: dateStr(1) },
+          { file: '101', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        ],
+        campaigns: [],
+      });
+
+      const conflicts = manager.detectConflicts({ hours: 2 });
+      expect(conflicts.length).toBeGreaterThan(0);
+      expect(conflicts[0].winner.file).toBe('101');
+      expect(conflicts[0].winner.priority).toBe(10);
+      expect(conflicts[0].hidden).toEqual([{ file: '100', priority: 5 }]);
+    });
+
+    it('should detect conflict between campaign and standalone layout', () => {
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          { file: '100', priority: 3, fromdt: dateStr(-1), todt: dateStr(1) },
+        ],
+        campaigns: [
+          {
+            id: '1',
+            priority: 8,
+            fromdt: dateStr(-1),
+            todt: dateStr(1),
+            layouts: [{ file: '200' }],
+          },
+        ],
+      });
+
+      const conflicts = manager.detectConflicts({ hours: 2 });
+      expect(conflicts.length).toBeGreaterThan(0);
+      expect(conflicts[0].winner.priority).toBe(8);
+      expect(conflicts[0].hidden[0].file).toBe('100');
+    });
+
+    it('should return empty array when no schedule is set', () => {
+      const conflicts = manager.detectConflicts();
+      expect(conflicts).toEqual([]);
+    });
+
+    it('should merge consecutive minutes into a single conflict window', () => {
+      manager.setSchedule({
+        default: '0',
+        layouts: [
+          { file: '100', priority: 5, fromdt: dateStr(-1), todt: dateStr(1) },
+          { file: '101', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        ],
+        campaigns: [],
+      });
+
+      const conflicts = manager.detectConflicts({ hours: 2 });
+      // Should be 1 merged window, not 120 individual minutes
+      expect(conflicts.length).toBe(1);
+      const windowMs = conflicts[0].endTime.getTime() - conflicts[0].startTime.getTime();
+      // Window should span most of the 2-hour scan (overlap runs for ~2h)
+      expect(windowMs).toBeGreaterThanOrEqual(60 * 60 * 1000); // at least 1 hour
+    });
+  });
 });

package/src/timeline.js

@@ -175,12 +175,20 @@ export function calculateTimeline(schedule, durations, options = {}) {
     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);
@@ -211,13 +219,17 @@ export function calculateTimeline(schedule, durations, options = {}) {
       const dur = durations.get(file) || defaultDuration;
       const endMs = currentTime.getTime() + dur * 1000;
 
-      timeline.push({
+      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) {