@xiboplayer/renderer 0.1.0

package/src/layout-pool.js

@@ -0,0 +1,245 @@
+/**
+ * LayoutPool - Maintains a pool of pre-built layout containers
+ * for instant layout transitions.
+ *
+ * Instead of tearing down and rebuilding the DOM on every layout switch,
+ * the pool keeps up to `maxSize` layout containers alive. The current
+ * layout is marked 'hot' (visible); pre-loaded layouts are 'warm' (hidden).
+ * When transitioning, visibility is swapped instantly - no DOM rebuild.
+ *
+ * Pool entries:
+ *   layoutId -> { container, layout, regions, blobUrls, mediaUrlCache, status, lastAccess }
+ *
+ * Status: 'hot' (currently visible) or 'warm' (preloaded, hidden)
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+
+const log = createLogger('LayoutPool');
+
+export class LayoutPool {
+  /**
+   * @param {number} maxSize - Maximum number of layouts to keep in pool (default: 2)
+   */
+  constructor(maxSize = 2) {
+    /** @type {Map<number, Object>} */
+    this.layouts = new Map();
+    this.maxSize = maxSize;
+    /** @type {number|null} */
+    this.hotLayoutId = null;
+  }
+
+  /**
+   * Check if a layout is in the pool
+   * @param {number} layoutId
+   * @returns {boolean}
+   */
+  has(layoutId) {
+    return this.layouts.has(layoutId);
+  }
+
+  /**
+   * Get a pool entry
+   * @param {number} layoutId
+   * @returns {Object|undefined}
+   */
+  get(layoutId) {
+    return this.layouts.get(layoutId);
+  }
+
+  /**
+   * Add a layout entry to the pool.
+   * If pool is full, evicts the least-recently-used warm entry.
+   *
+   * @param {number} layoutId
+   * @param {Object} entry - Pool entry
+   * @param {HTMLElement} entry.container - Layout container DOM element
+   * @param {Object} entry.layout - Parsed layout object
+   * @param {Map} entry.regions - Region map (regionId => region state)
+   * @param {Set<string>} entry.blobUrls - Tracked blob URLs for this layout
+   * @param {Map} [entry.mediaUrlCache] - Media URL cache (fileId => url)
+   */
+  add(layoutId, entry) {
+    // If already in pool, update in place
+    if (this.layouts.has(layoutId)) {
+      const existing = this.layouts.get(layoutId);
+      Object.assign(existing, entry);
+      existing.lastAccess = Date.now();
+      return;
+    }
+
+    // If pool is full, evict LRU warm entry
+    if (this.layouts.size >= this.maxSize) {
+      this.evictLRU();
+    }
+
+    entry.status = 'warm';
+    entry.lastAccess = Date.now();
+    this.layouts.set(layoutId, entry);
+    log.info(`Added layout ${layoutId} to pool (size: ${this.layouts.size}/${this.maxSize})`);
+  }
+
+  /**
+   * Mark a layout as active (visible).
+   * The previous hot layout is demoted to warm.
+   * @param {number} layoutId
+   */
+  setHot(layoutId) {
+    // Demote previous hot layout to warm
+    if (this.hotLayoutId !== null && this.layouts.has(this.hotLayoutId)) {
+      this.layouts.get(this.hotLayoutId).status = 'warm';
+    }
+
+    if (this.layouts.has(layoutId)) {
+      const entry = this.layouts.get(layoutId);
+      entry.status = 'hot';
+      entry.lastAccess = Date.now();
+    }
+
+    this.hotLayoutId = layoutId;
+  }
+
+  /**
+   * Evict a specific layout from the pool.
+   * Revokes blob URLs and removes the container from the DOM.
+   * @param {number} layoutId
+   */
+  evict(layoutId) {
+    const entry = this.layouts.get(layoutId);
+    if (!entry) return;
+
+    log.info(`Evicting layout ${layoutId} from pool`);
+
+    // Revoke blob URLs
+    if (entry.blobUrls && entry.blobUrls.size > 0) {
+      entry.blobUrls.forEach(url => {
+        URL.revokeObjectURL(url);
+      });
+      log.info(`Revoked ${entry.blobUrls.size} blob URLs for layout ${layoutId}`);
+    }
+
+    // Revoke media URL cache blob URLs
+    if (entry.mediaUrlCache) {
+      for (const [fileId, blobUrl] of entry.mediaUrlCache) {
+        if (blobUrl && typeof blobUrl === 'string' && blobUrl.startsWith('blob:')) {
+          URL.revokeObjectURL(blobUrl);
+        }
+      }
+    }
+
+    // Stop any active region timers
+    if (entry.regions) {
+      for (const [regionId, region] of entry.regions) {
+        if (region.timer) {
+          clearTimeout(region.timer);
+          region.timer = null;
+        }
+      }
+    }
+
+    // Remove container from DOM
+    if (entry.container && entry.container.parentNode) {
+      entry.container.remove();
+    }
+
+    this.layouts.delete(layoutId);
+
+    // Clear hot reference if this was the hot layout
+    if (this.hotLayoutId === layoutId) {
+      this.hotLayoutId = null;
+    }
+  }
+
+  /**
+   * Evict the least-recently-used warm entry.
+   * Only warm entries are eligible for eviction (never the hot layout).
+   */
+  evictLRU() {
+    let oldest = null;
+    let oldestTime = Infinity;
+
+    for (const [id, entry] of this.layouts) {
+      if (entry.status === 'warm' && entry.lastAccess < oldestTime) {
+        oldest = id;
+        oldestTime = entry.lastAccess;
+      }
+    }
+
+    if (oldest !== null) {
+      this.evict(oldest);
+    }
+  }
+
+  /**
+   * Clear all warm (preloaded) entries, keeping the hot layout.
+   * @returns {number} Number of entries cleared
+   */
+  clearWarm() {
+    let count = 0;
+    const warmIds = [];
+
+    for (const [id, entry] of this.layouts) {
+      if (entry.status === 'warm') {
+        warmIds.push(id);
+      }
+    }
+
+    for (const id of warmIds) {
+      this.evict(id);
+      count++;
+    }
+
+    if (count > 0) {
+      log.info(`Cleared ${count} warm layout(s) from pool`);
+    }
+
+    return count;
+  }
+
+  /**
+   * Clear warm entries NOT in the given set of layout IDs.
+   * Keeps warm entries that are still scheduled.
+   * @param {Set<number>} keepIds - Layout IDs to keep
+   * @returns {number} Number of entries cleared
+   */
+  clearWarmNotIn(keepIds) {
+    let count = 0;
+    const evictIds = [];
+
+    for (const [id, entry] of this.layouts) {
+      if (entry.status === 'warm' && !keepIds.has(id)) {
+        evictIds.push(id);
+      }
+    }
+
+    for (const id of evictIds) {
+      this.evict(id);
+      count++;
+    }
+
+    if (count > 0) {
+      log.info(`Cleared ${count} warm layout(s) no longer in schedule`);
+    }
+
+    return count;
+  }
+
+  /**
+   * Clear all entries (both hot and warm).
+   */
+  clear() {
+    const ids = Array.from(this.layouts.keys());
+    for (const id of ids) {
+      this.evict(id);
+    }
+    this.hotLayoutId = null;
+  }
+
+  /**
+   * Get the number of entries in the pool.
+   * @returns {number}
+   */
+  get size() {
+    return this.layouts.size;
+  }
+}

package/src/layout-pool.test.js

@@ -0,0 +1,373 @@
+/**
+ * LayoutPool Test Suite
+ *
+ * Tests for the layout preload pool: add, get, evict, LRU, clear.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LayoutPool } from './layout-pool.js';
+
+describe('LayoutPool', () => {
+  let pool;
+
+  // Mock URL.revokeObjectURL (not available in jsdom)
+  beforeEach(() => {
+    pool = new LayoutPool(2);
+
+    if (!global.URL.revokeObjectURL) {
+      global.URL.revokeObjectURL = vi.fn();
+    } else {
+      vi.spyOn(URL, 'revokeObjectURL');
+    }
+  });
+
+  /**
+   * Helper: create a mock pool entry
+   */
+  function createMockEntry(layoutId) {
+    const container = document.createElement('div');
+    container.id = `layout_${layoutId}`;
+    document.body.appendChild(container);
+
+    return {
+      container,
+      layout: { width: 1920, height: 1080, duration: 60, bgcolor: '#000', regions: [] },
+      regions: new Map(),
+      blobUrls: new Set(),
+      mediaUrlCache: new Map()
+    };
+  }
+
+  describe('constructor', () => {
+    it('should initialize with default maxSize of 2', () => {
+      const defaultPool = new LayoutPool();
+      expect(defaultPool.maxSize).toBe(2);
+      expect(defaultPool.size).toBe(0);
+      expect(defaultPool.hotLayoutId).toBeNull();
+    });
+
+    it('should accept custom maxSize', () => {
+      const customPool = new LayoutPool(5);
+      expect(customPool.maxSize).toBe(5);
+    });
+  });
+
+  describe('has()', () => {
+    it('should return false for empty pool', () => {
+      expect(pool.has(1)).toBe(false);
+    });
+
+    it('should return true after adding a layout', () => {
+      pool.add(1, createMockEntry(1));
+      expect(pool.has(1)).toBe(true);
+    });
+
+    it('should return false for non-existent layout', () => {
+      pool.add(1, createMockEntry(1));
+      expect(pool.has(2)).toBe(false);
+    });
+  });
+
+  describe('get()', () => {
+    it('should return undefined for empty pool', () => {
+      expect(pool.get(1)).toBeUndefined();
+    });
+
+    it('should return the entry after adding', () => {
+      const entry = createMockEntry(1);
+      pool.add(1, entry);
+      const retrieved = pool.get(1);
+      expect(retrieved).toBeTruthy();
+      expect(retrieved.layout).toEqual(entry.layout);
+      expect(retrieved.status).toBe('warm');
+    });
+  });
+
+  describe('add()', () => {
+    it('should add entry as warm status', () => {
+      pool.add(1, createMockEntry(1));
+      const entry = pool.get(1);
+      expect(entry.status).toBe('warm');
+      expect(entry.lastAccess).toBeGreaterThan(0);
+    });
+
+    it('should set pool size correctly', () => {
+      pool.add(1, createMockEntry(1));
+      expect(pool.size).toBe(1);
+
+      pool.add(2, createMockEntry(2));
+      expect(pool.size).toBe(2);
+    });
+
+    it('should update in place when adding same layout ID', () => {
+      const entry1 = createMockEntry(1);
+      entry1.layout.duration = 30;
+      pool.add(1, entry1);
+
+      const entry2 = createMockEntry(1);
+      entry2.layout.duration = 60;
+      pool.add(1, entry2);
+
+      expect(pool.size).toBe(1);
+      expect(pool.get(1).layout.duration).toBe(60);
+    });
+
+    it('should evict LRU warm entry when pool is full', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+
+      // Pool is full (maxSize=2), adding a third should evict the oldest warm
+      pool.add(3, createMockEntry(3));
+
+      expect(pool.size).toBe(2);
+      expect(pool.has(1)).toBe(false); // Oldest evicted
+      expect(pool.has(2)).toBe(true);
+      expect(pool.has(3)).toBe(true);
+    });
+  });
+
+  describe('setHot()', () => {
+    it('should mark entry as hot', () => {
+      pool.add(1, createMockEntry(1));
+      pool.setHot(1);
+
+      expect(pool.get(1).status).toBe('hot');
+      expect(pool.hotLayoutId).toBe(1);
+    });
+
+    it('should demote previous hot entry to warm', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+
+      pool.setHot(1);
+      expect(pool.get(1).status).toBe('hot');
+
+      pool.setHot(2);
+      expect(pool.get(1).status).toBe('warm');
+      expect(pool.get(2).status).toBe('hot');
+      expect(pool.hotLayoutId).toBe(2);
+    });
+  });
+
+  describe('evict()', () => {
+    it('should remove entry from pool', () => {
+      pool.add(1, createMockEntry(1));
+      pool.evict(1);
+
+      expect(pool.has(1)).toBe(false);
+      expect(pool.size).toBe(0);
+    });
+
+    it('should revoke blob URLs on eviction', () => {
+      const entry = createMockEntry(1);
+      entry.blobUrls.add('blob:test-1');
+      entry.blobUrls.add('blob:test-2');
+
+      pool.add(1, entry);
+      pool.evict(1);
+
+      expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:test-1');
+      expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:test-2');
+    });
+
+    it('should revoke media blob URLs on eviction', () => {
+      const entry = createMockEntry(1);
+      entry.mediaUrlCache.set(10, 'blob:media-10');
+      entry.mediaUrlCache.set(20, 'blob:media-20');
+
+      pool.add(1, entry);
+      pool.evict(1);
+
+      expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:media-10');
+      expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:media-20');
+    });
+
+    it('should remove container from DOM', () => {
+      const entry = createMockEntry(1);
+      pool.add(1, entry);
+
+      expect(entry.container.parentNode).toBeTruthy();
+      pool.evict(1);
+      expect(entry.container.parentNode).toBeNull();
+    });
+
+    it('should clear hot reference if evicting hot layout', () => {
+      pool.add(1, createMockEntry(1));
+      pool.setHot(1);
+      expect(pool.hotLayoutId).toBe(1);
+
+      pool.evict(1);
+      expect(pool.hotLayoutId).toBeNull();
+    });
+
+    it('should do nothing for non-existent layout', () => {
+      // Should not throw
+      pool.evict(999);
+      expect(pool.size).toBe(0);
+    });
+
+    it('should clear region timers on eviction', () => {
+      const entry = createMockEntry(1);
+      const mockTimer = setTimeout(() => {}, 99999);
+      const clearSpy = vi.spyOn(global, 'clearTimeout');
+
+      entry.regions.set('r1', {
+        timer: mockTimer,
+        element: document.createElement('div'),
+        widgets: [],
+        widgetElements: new Map()
+      });
+
+      pool.add(1, entry);
+      pool.evict(1);
+
+      expect(clearSpy).toHaveBeenCalledWith(mockTimer);
+      clearSpy.mockRestore();
+    });
+  });
+
+  describe('evictLRU()', () => {
+    it('should evict oldest warm entry', () => {
+      const entry1 = createMockEntry(1);
+      const entry2 = createMockEntry(2);
+
+      // Use deterministic timestamps to ensure entry1 is older
+      let time = 1000;
+      vi.spyOn(Date, 'now').mockImplementation(() => time);
+
+      pool.add(1, entry1);
+      time = 2000;
+      pool.add(2, entry2);
+
+      // entry1 has lastAccess=1000, entry2 has lastAccess=2000
+      // evictLRU should evict entry1 (oldest warm)
+      pool.evictLRU();
+
+      expect(pool.has(1)).toBe(false);
+      expect(pool.has(2)).toBe(true);
+
+      vi.restoreAllMocks();
+    });
+
+    it('should not evict hot entry', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+      pool.setHot(1);
+
+      // Only warm entries can be evicted
+      pool.evictLRU();
+
+      expect(pool.has(1)).toBe(true); // Hot - preserved
+      expect(pool.has(2)).toBe(false); // Warm - evicted
+    });
+
+    it('should do nothing if no warm entries', () => {
+      pool.add(1, createMockEntry(1));
+      pool.setHot(1);
+
+      // Only hot entry exists - nothing to evict
+      pool.evictLRU();
+      expect(pool.size).toBe(1);
+    });
+  });
+
+  describe('clearWarm()', () => {
+    it('should clear all warm entries', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+      pool.setHot(1);
+
+      const count = pool.clearWarm();
+
+      expect(count).toBe(1);
+      expect(pool.has(1)).toBe(true); // Hot - preserved
+      expect(pool.has(2)).toBe(false); // Warm - cleared
+    });
+
+    it('should return 0 when no warm entries', () => {
+      pool.add(1, createMockEntry(1));
+      pool.setHot(1);
+
+      const count = pool.clearWarm();
+      expect(count).toBe(0);
+    });
+
+    it('should clear all entries when all are warm', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+
+      const count = pool.clearWarm();
+
+      expect(count).toBe(2);
+      expect(pool.size).toBe(0);
+    });
+  });
+
+  describe('clear()', () => {
+    it('should clear all entries including hot', () => {
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+      pool.setHot(1);
+
+      pool.clear();
+
+      expect(pool.size).toBe(0);
+      expect(pool.hotLayoutId).toBeNull();
+      expect(pool.has(1)).toBe(false);
+      expect(pool.has(2)).toBe(false);
+    });
+
+    it('should work on empty pool', () => {
+      pool.clear();
+      expect(pool.size).toBe(0);
+    });
+  });
+
+  describe('size', () => {
+    it('should track pool size accurately', () => {
+      expect(pool.size).toBe(0);
+
+      pool.add(1, createMockEntry(1));
+      expect(pool.size).toBe(1);
+
+      pool.add(2, createMockEntry(2));
+      expect(pool.size).toBe(2);
+
+      pool.evict(1);
+      expect(pool.size).toBe(1);
+
+      pool.clear();
+      expect(pool.size).toBe(0);
+    });
+  });
+
+  describe('LRU eviction under pressure', () => {
+    it('should evict oldest warm when adding beyond maxSize', () => {
+      // maxSize=2, add 3 layouts
+      pool.add(1, createMockEntry(1));
+      pool.add(2, createMockEntry(2));
+
+      // Add third - should evict layout 1 (oldest)
+      pool.add(3, createMockEntry(3));
+
+      expect(pool.size).toBe(2);
+      expect(pool.has(1)).toBe(false);
+      expect(pool.has(2)).toBe(true);
+      expect(pool.has(3)).toBe(true);
+    });
+
+    it('should preserve hot layout during LRU eviction', () => {
+      pool.add(1, createMockEntry(1));
+      pool.setHot(1);
+      pool.add(2, createMockEntry(2));
+
+      // Pool is full (1=hot, 2=warm). Adding 3 should evict 2 (warm), not 1 (hot)
+      pool.add(3, createMockEntry(3));
+
+      expect(pool.size).toBe(2);
+      expect(pool.has(1)).toBe(true); // Hot - preserved
+      expect(pool.has(2)).toBe(false); // Warm - evicted
+      expect(pool.has(3)).toBe(true); // Newly added
+    });
+  });
+});