@xiboplayer/settings 0.9.0

package/README.md

@@ -0,0 +1,293 @@
+# @xiboplayer/settings
+
+CMS display settings management and application for Xibo players.
+
+## Features
+
+- Parse all settings from RegisterDisplay CMS response
+- Validate and normalize setting values
+- Dynamic collection interval updates
+- Download window enforcement (same-day and overnight windows)
+- Screenshot interval tracking
+- Event emission on setting changes
+- Comprehensive error handling
+
+## Installation
+
+```bash
+npm install @xiboplayer/settings
+```
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { DisplaySettings } from '@xiboplayer/settings';
+
+const displaySettings = new DisplaySettings();
+
+// Apply settings from RegisterDisplay response
+const result = displaySettings.applySettings(cmsSettings);
+
+console.log('Changed settings:', result.changed);
+console.log('Collection interval:', result.settings.collectInterval);
+```
+
+### With PlayerCore
+
+```javascript
+import { PlayerCore } from '@xiboplayer/core';
+import { DisplaySettings } from '@xiboplayer/settings';
+
+const displaySettings = new DisplaySettings();
+
+const core = new PlayerCore({
+  config,
+  xmds,
+  cache,
+  schedule,
+  renderer,
+  xmrWrapper,
+  displaySettings // Inject DisplaySettings
+});
+
+// Settings are automatically applied after RegisterDisplay
+await core.collect();
+```
+
+### Event Handling
+
+```javascript
+// Listen for collection interval changes
+displaySettings.on('interval-changed', (newInterval) => {
+  console.log(`Collection interval changed to ${newInterval}s`);
+});
+
+// Listen for any settings changes
+displaySettings.on('settings-applied', (settings, changes) => {
+  console.log('Settings updated:', changes.join(', '));
+});
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+const displaySettings = new DisplaySettings();
+```
+
+### Methods
+
+#### `applySettings(settings)`
+
+Apply CMS settings from RegisterDisplay response.
+
+**Parameters:**
+- `settings` (Object): Raw settings from CMS
+
+**Returns:**
+- Object with `changed` (array) and `settings` (object)
+
+**Example:**
+```javascript
+const result = displaySettings.applySettings({
+  collectInterval: 600,
+  displayName: 'Main Display',
+  statsEnabled: '1',
+  xmrWebSocketAddress: 'ws://xmr.example.com:9505'
+});
+
+console.log(result.changed); // ['collectInterval']
+console.log(result.settings.collectInterval); // 600
+```
+
+#### `getCollectInterval()`
+
+Get current collection interval in seconds.
+
+**Returns:** Number (seconds)
+
+#### `getDisplayName()`
+
+Get display name from CMS.
+
+**Returns:** String
+
+#### `getDisplaySize()`
+
+Get display dimensions.
+
+**Returns:** Object `{ width: number, height: number }`
+
+#### `isStatsEnabled()`
+
+Check if stats/proof of play is enabled.
+
+**Returns:** Boolean
+
+#### `getAllSettings()`
+
+Get all current settings as an object.
+
+**Returns:** Object
+
+#### `getSetting(key, defaultValue)`
+
+Get a specific setting by key.
+
+**Parameters:**
+- `key` (String): Setting key
+- `defaultValue` (Any): Default if not set
+
+**Returns:** Setting value or default
+
+#### `isInDownloadWindow()`
+
+Check if current time is within the download window.
+
+**Returns:** Boolean
+
+**Example:**
+```javascript
+// Configure download window 09:00-17:00
+displaySettings.applySettings({
+  downloadStartWindow: '09:00',
+  downloadEndWindow: '17:00'
+});
+
+// Check if downloads are allowed now
+if (displaySettings.isInDownloadWindow()) {
+  await downloadFiles();
+}
+```
+
+#### `getNextDownloadWindow()`
+
+Get the next download window start time.
+
+**Returns:** Date object or null
+
+#### `shouldTakeScreenshot(lastScreenshot)`
+
+Check if screenshot interval has elapsed.
+
+**Parameters:**
+- `lastScreenshot` (Date): Last screenshot timestamp
+
+**Returns:** Boolean
+
+## Supported Settings
+
+### Collection
+- `collectInterval` - Collection interval in seconds (60-86400, default: 300)
+
+### Display Info
+- `displayName` - Display name (default: 'Unknown Display')
+- `sizeX` - Display width in pixels (default: 1920)
+- `sizeY` - Display height in pixels (default: 1080)
+
+### Stats/Logging
+- `statsEnabled` - Enable proof of play ('1' or '0')
+- `aggregationLevel` - Stats aggregation ('Individual' or 'Aggregate')
+- `logLevel` - Log level ('error', 'audit', 'info', 'debug')
+
+### XMR
+- `xmrNetworkAddress` - XMR TCP address (e.g., 'tcp://xmr.example.com:9505')
+- `xmrWebSocketAddress` - XMR WebSocket address (e.g., 'ws://xmr.example.com:9505')
+- `xmrCmsKey` - XMR encryption key
+
+### Features
+- `preventSleep` - Prevent display sleep (boolean, default: true)
+- `embeddedServerPort` - Embedded server port (default: 9696)
+- `screenshotInterval` - Screenshot interval in seconds (default: 120)
+
+### Download Windows
+- `downloadStartWindow` - Download start time ('HH:MM')
+- `downloadEndWindow` - Download end time ('HH:MM')
+
+### Other
+- `licenceCode` - Commercial license code
+- `isSspEnabled` - Enable SSP ad space (boolean)
+
+## Setting Name Formats
+
+Supports both lowercase and CamelCase (uppercase first letter):
+
+```javascript
+// Both formats work
+displaySettings.applySettings({
+  collectInterval: 600,   // lowercase
+  CollectInterval: 600    // CamelCase
+});
+
+displaySettings.applySettings({
+  displayName: 'Test',    // lowercase
+  DisplayName: 'Test'     // CamelCase
+});
+```
+
+## Download Windows
+
+### Same-Day Window
+
+```javascript
+displaySettings.applySettings({
+  downloadStartWindow: '09:00',
+  downloadEndWindow: '17:00'
+});
+
+// Downloads allowed 09:00-17:00
+```
+
+### Overnight Window
+
+```javascript
+displaySettings.applySettings({
+  downloadStartWindow: '22:00',
+  downloadEndWindow: '06:00'
+});
+
+// Downloads allowed 22:00-23:59 and 00:00-06:00
+```
+
+## Events
+
+### `interval-changed`
+
+Emitted when collection interval changes.
+
+**Callback:** `(newInterval: number) => void`
+
+### `settings-applied`
+
+Emitted when settings are applied.
+
+**Callback:** `(settings: Object, changes: Array<string>) => void`
+
+## Testing
+
+```bash
+npm test
+```
+
+The test suite includes:
+- 44 comprehensive test cases
+- Constructor defaults
+- Setting parsing and validation
+- Collection interval enforcement (60s-24h)
+- Boolean parsing ('1', '0', true, false)
+- Download window logic (same-day and overnight)
+- Screenshot interval tracking
+- Edge cases and error handling
+
+## Integration with Upstream
+
+Based on upstream electron-player implementation:
+- `/upstream_players/electron-player/src/main/config/config.ts`
+- `/upstream_players/electron-player/src/main/xmds/response/registerDisplay.ts`
+
+## License
+
+AGPL-3.0-or-later

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@xiboplayer/settings",
+  "version": "0.9.0",
+  "description": "CMS settings management and application for Xibo Player",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./manager": "./src/settings.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@xiboplayer/utils": "file:../utils"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.1",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "xibo",
+    "digital-signage",
+    "settings",
+    "configuration",
+    "display-settings"
+  ],
+  "author": "Pau Aliagas <linuxnow@gmail.com>",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xibo/xibo-players.git",
+    "directory": "packages/settings"
+  }
+}

package/src/index.js

@@ -0,0 +1,7 @@
+// @xiboplayer/settings - CMS settings management
+
+/**
+ * Settings manager for Xibo Player
+ * @module @xiboplayer/settings
+ */
+export { DisplaySettings } from './settings.js';

package/src/settings.js

@@ -0,0 +1,352 @@
+/**
+ * DisplaySettings - CMS display settings management
+ *
+ * Parses and applies configuration from RegisterDisplay response.
+ * Based on upstream electron-player implementation.
+ *
+ * Architecture:
+ * ┌─────────────────────────────────────────────────────┐
+ * │ PlayerCore                                          │
+ * │ - Receives RegisterDisplay response                 │
+ * │ - Passes to DisplaySettings.applySettings()         │
+ * └─────────────────────────────────────────────────────┘
+ *                          ↓
+ * ┌─────────────────────────────────────────────────────┐
+ * │ DisplaySettings (this module)                       │
+ * │ - Parse all CMS settings                            │
+ * │ - Validate and normalize values                     │
+ * │ - Apply collection interval                         │
+ * │ - Check download windows                            │
+ * │ - Handle screenshot requests                        │
+ * │ - Emit events on changes                            │
+ * └─────────────────────────────────────────────────────┘
+ *                          ↓
+ * ┌─────────────────────────────────────────────────────┐
+ * │ Platform Layer (PWA/Electron/Mobile)                │
+ * │ - Listen for setting change events                  │
+ * │ - Update UI with display name                       │
+ * │ - Handle screenshot requests                        │
+ * │ - Respect download windows                          │
+ * └─────────────────────────────────────────────────────┘
+ *
+ * Usage:
+ *   const settings = new DisplaySettings();
+ *   settings.applySettings(regResult.settings);
+ *
+ *   // Get settings
+ *   const collectInterval = settings.getCollectInterval();
+ *   const canDownload = settings.isInDownloadWindow();
+ *
+ *   // Listen for changes
+ *   settings.on('interval-changed', (newInterval) => { ... });
+ */
+
+import { EventEmitter } from '@xiboplayer/utils';
+
+export class DisplaySettings extends EventEmitter {
+  constructor() {
+    super();
+
+    // Current settings (with defaults)
+    this.settings = {
+      // Collection
+      collectInterval: 300, // seconds (5 minutes default)
+
+      // Display info
+      displayName: 'Unknown Display',
+      sizeX: 1920,
+      sizeY: 1080,
+
+      // Stats
+      statsEnabled: false,
+      aggregationLevel: 'Individual', // or 'Aggregate'
+
+      // Logging
+      logLevel: 'error', // 'error', 'audit', 'info', 'debug'
+
+      // XMR
+      xmrNetworkAddress: null,
+      xmrWebSocketAddress: null,
+      xmrCmsKey: null,
+
+      // Features
+      preventSleep: true,
+      embeddedServerPort: 9696,
+      screenshotInterval: 120, // seconds
+
+      // Download windows
+      downloadStartWindow: null,
+      downloadEndWindow: null,
+
+      // License
+      licenceCode: null,
+
+      // SSP (ad space)
+      isSspEnabled: false,
+    };
+  }
+
+  /**
+   * Apply settings from RegisterDisplay response
+   * @param {Object} settings - Raw settings from CMS
+   * @returns {Object} Applied settings with changes
+   */
+  applySettings(settings) {
+    if (!settings) {
+      console.warn('[DisplaySettings] No settings provided');
+      return { changed: [], settings: this.settings };
+    }
+
+    const changes = [];
+    const oldInterval = this.settings.collectInterval;
+
+    // Parse all settings with defaults
+    // Handle both lowercase and CamelCase (uppercase first letter)
+    this.settings.collectInterval = this.parseCollectInterval(settings.collectInterval || settings.CollectInterval);
+    this.settings.displayName = settings.displayName || settings.DisplayName || this.settings.displayName;
+    this.settings.sizeX = parseInt(settings.sizeX || settings.SizeX || this.settings.sizeX);
+    this.settings.sizeY = parseInt(settings.sizeY || settings.SizeY || this.settings.sizeY);
+
+    // Stats
+    this.settings.statsEnabled = this.parseBoolean(settings.statsEnabled || settings.StatsEnabled);
+    this.settings.aggregationLevel = settings.aggregationLevel || settings.AggregationLevel || this.settings.aggregationLevel;
+
+    // Logging
+    this.settings.logLevel = settings.logLevel || settings.LogLevel || this.settings.logLevel;
+
+    // XMR
+    this.settings.xmrNetworkAddress = settings.xmrNetworkAddress || settings.XmrNetworkAddress || this.settings.xmrNetworkAddress;
+    this.settings.xmrWebSocketAddress = settings.xmrWebSocketAddress || settings.XmrWebSocketAddress || this.settings.xmrWebSocketAddress;
+    this.settings.xmrCmsKey = settings.xmrCmsKey || settings.XmrCmsKey || this.settings.xmrCmsKey;
+
+    // Features
+    this.settings.preventSleep = this.parseBoolean(settings.preventSleep || settings.PreventSleep, true);
+    this.settings.embeddedServerPort = parseInt(settings.embeddedServerPort || settings.EmbeddedServerPort || this.settings.embeddedServerPort);
+    this.settings.screenshotInterval = parseInt(settings.screenshotInterval || settings.ScreenshotInterval || this.settings.screenshotInterval);
+
+    // Download windows
+    this.settings.downloadStartWindow = settings.downloadStartWindow || settings.DownloadStartWindow || this.settings.downloadStartWindow;
+    this.settings.downloadEndWindow = settings.downloadEndWindow || settings.DownloadEndWindow || this.settings.downloadEndWindow;
+
+    // License
+    this.settings.licenceCode = settings.licenceCode || settings.LicenceCode || this.settings.licenceCode;
+
+    // SSP
+    this.settings.isSspEnabled = this.parseBoolean(settings.isAdspaceEnabled || settings.IsAdspaceEnabled);
+
+    // Detect changes
+    if (oldInterval !== this.settings.collectInterval) {
+      changes.push('collectInterval');
+      this.emit('interval-changed', this.settings.collectInterval);
+    }
+
+    // Emit generic settings-applied event
+    this.emit('settings-applied', this.settings, changes);
+
+    console.log('[DisplaySettings] Applied settings:', {
+      collectInterval: this.settings.collectInterval,
+      displayName: this.settings.displayName,
+      statsEnabled: this.settings.statsEnabled,
+      changes
+    });
+
+    return { changed: changes, settings: this.settings };
+  }
+
+  /**
+   * Parse collection interval (seconds)
+   * @param {*} value - Raw value from CMS
+   * @returns {number} Collection interval in seconds
+   */
+  parseCollectInterval(value) {
+    const interval = parseInt(value, 10);
+
+    // Validate range (minimum 60s, maximum 86400s = 24h)
+    if (isNaN(interval) || interval < 60) {
+      return 300; // 5 minutes default
+    }
+
+    if (interval > 86400) {
+      return 86400; // 24 hours max
+    }
+
+    return interval;
+  }
+
+  /**
+   * Parse boolean setting
+   * @param {*} value - Raw value from CMS (string '1' or '0', or boolean)
+   * @param {boolean} defaultValue - Default if not set
+   * @returns {boolean}
+   */
+  parseBoolean(value, defaultValue = false) {
+    if (value === true || value === false) {
+      return value;
+    }
+
+    if (value === '1' || value === 1) {
+      return true;
+    }
+
+    if (value === '0' || value === 0) {
+      return false;
+    }
+
+    return defaultValue;
+  }
+
+  /**
+   * Get collection interval in seconds
+   * @returns {number}
+   */
+  getCollectInterval() {
+    return this.settings.collectInterval;
+  }
+
+  /**
+   * Get display name
+   * @returns {string}
+   */
+  getDisplayName() {
+    return this.settings.displayName;
+  }
+
+  /**
+   * Get display size
+   * @returns {{ width: number, height: number }}
+   */
+  getDisplaySize() {
+    return {
+      width: this.settings.sizeX,
+      height: this.settings.sizeY
+    };
+  }
+
+  /**
+   * Check if stats are enabled
+   * @returns {boolean}
+   */
+  isStatsEnabled() {
+    return this.settings.statsEnabled;
+  }
+
+  /**
+   * Get all settings
+   * @returns {Object}
+   */
+  getAllSettings() {
+    return { ...this.settings };
+  }
+
+  /**
+   * Get a specific setting by key
+   * @param {string} key - Setting key
+   * @param {*} defaultValue - Default value if not set
+   * @returns {*}
+   */
+  getSetting(key, defaultValue = null) {
+    return this.settings[key] !== undefined ? this.settings[key] : defaultValue;
+  }
+
+  /**
+   * Check if current time is within download window
+   * @returns {boolean}
+   */
+  isInDownloadWindow() {
+    // If no download window configured, always allow
+    if (!this.settings.downloadStartWindow || !this.settings.downloadEndWindow) {
+      return true;
+    }
+
+    try {
+      const now = new Date();
+      const currentTime = now.getHours() * 60 + now.getMinutes();
+
+      const start = this.parseTimeWindow(this.settings.downloadStartWindow);
+      const end = this.parseTimeWindow(this.settings.downloadEndWindow);
+
+      // Handle overnight window (e.g., 22:00 - 06:00)
+      if (start > end) {
+        // Overnight: allow if AFTER start OR BEFORE end
+        return currentTime >= start || currentTime < end;
+      } else {
+        // Same day: allow if AFTER start AND BEFORE end
+        return currentTime >= start && currentTime < end;
+      }
+    } catch (error) {
+      console.warn('[DisplaySettings] Failed to parse download window:', error);
+      return true; // Allow downloads if parsing fails
+    }
+  }
+
+  /**
+   * Parse time window string to minutes since midnight
+   * @param {string} timeStr - Time string (e.g., "14:30", "22:00")
+   * @returns {number} Minutes since midnight
+   */
+  parseTimeWindow(timeStr) {
+    if (!timeStr || typeof timeStr !== 'string') {
+      throw new Error('Invalid time window format');
+    }
+
+    const parts = timeStr.split(':');
+    if (parts.length !== 2) {
+      throw new Error('Invalid time window format (expected HH:MM)');
+    }
+
+    const hours = parseInt(parts[0], 10);
+    const minutes = parseInt(parts[1], 10);
+
+    if (isNaN(hours) || isNaN(minutes) || hours < 0 || hours > 23 || minutes < 0 || minutes > 59) {
+      throw new Error('Invalid time window values');
+    }
+
+    return hours * 60 + minutes;
+  }
+
+  /**
+   * Get next download window start time
+   * @returns {Date|null} Next window start, or null if always allowed
+   */
+  getNextDownloadWindow() {
+    if (!this.settings.downloadStartWindow || !this.settings.downloadEndWindow) {
+      return null;
+    }
+
+    try {
+      const now = new Date();
+      const currentTime = now.getHours() * 60 + now.getMinutes();
+      const start = this.parseTimeWindow(this.settings.downloadStartWindow);
+
+      const nextWindow = new Date(now);
+
+      if (currentTime < start) {
+        // Window is later today
+        nextWindow.setHours(Math.floor(start / 60), start % 60, 0, 0);
+      } else {
+        // Window is tomorrow
+        nextWindow.setDate(nextWindow.getDate() + 1);
+        nextWindow.setHours(Math.floor(start / 60), start % 60, 0, 0);
+      }
+
+      return nextWindow;
+    } catch (error) {
+      console.warn('[DisplaySettings] Failed to calculate next download window:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Check if screenshot interval has elapsed
+   * @param {Date} lastScreenshot - Last screenshot timestamp
+   * @returns {boolean}
+   */
+  shouldTakeScreenshot(lastScreenshot) {
+    if (!lastScreenshot) {
+      return true;
+    }
+
+    const elapsed = (Date.now() - lastScreenshot.getTime()) / 1000;
+    return elapsed >= this.settings.screenshotInterval;
+  }
+}

package/src/settings.test.js

@@ -0,0 +1,480 @@
+/**
+ * DisplaySettings tests
+ * Comprehensive test suite covering all settings parsing and validation
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { DisplaySettings } from './settings.js';
+
+describe('DisplaySettings', () => {
+  let settings;
+
+  beforeEach(() => {
+    settings = new DisplaySettings();
+  });
+
+  describe('constructor', () => {
+    it('should initialize with default settings', () => {
+      expect(settings.settings.collectInterval).toBe(300);
+      expect(settings.settings.displayName).toBe('Unknown Display');
+      expect(settings.settings.sizeX).toBe(1920);
+      expect(settings.settings.sizeY).toBe(1080);
+      expect(settings.settings.statsEnabled).toBe(false);
+      expect(settings.settings.logLevel).toBe('error');
+    });
+  });
+
+  describe('applySettings', () => {
+    it('should handle null settings gracefully', () => {
+      const result = settings.applySettings(null);
+      expect(result.changed).toEqual([]);
+      expect(result.settings.collectInterval).toBe(300);
+    });
+
+    it('should apply all settings from CMS response', () => {
+      const cmsSettings = {
+        collectInterval: 600,
+        displayName: 'Test Display',
+        sizeX: '3840',
+        sizeY: '2160',
+        statsEnabled: '1',
+        logLevel: 'debug',
+        xmrWebSocketAddress: 'ws://xmr.example.com:9505',
+        preventSleep: '1',
+        screenshotInterval: '180'
+      };
+
+      const result = settings.applySettings(cmsSettings);
+
+      expect(result.settings.collectInterval).toBe(600);
+      expect(result.settings.displayName).toBe('Test Display');
+      expect(result.settings.sizeX).toBe(3840);
+      expect(result.settings.sizeY).toBe(2160);
+      expect(result.settings.statsEnabled).toBe(true);
+      expect(result.settings.logLevel).toBe('debug');
+      expect(result.settings.xmrWebSocketAddress).toBe('ws://xmr.example.com:9505');
+      expect(result.settings.preventSleep).toBe(true);
+      expect(result.settings.screenshotInterval).toBe(180);
+    });
+
+    it('should detect collection interval changes', () => {
+      const listener = vi.fn();
+      settings.on('interval-changed', listener);
+
+      settings.applySettings({ collectInterval: 600 });
+
+      expect(listener).toHaveBeenCalledWith(600);
+    });
+
+    it('should emit settings-applied event', () => {
+      const listener = vi.fn();
+      settings.on('settings-applied', listener);
+
+      const cmsSettings = { collectInterval: 600 };
+      settings.applySettings(cmsSettings);
+
+      expect(listener).toHaveBeenCalled();
+      expect(listener.mock.calls[0][1]).toContain('collectInterval');
+    });
+
+    it('should handle CamelCase setting names (uppercase first letter)', () => {
+      const cmsSettings = {
+        CollectInterval: 600,
+        DisplayName: 'CamelCase Display',
+        SizeX: '1920',
+        SizeY: '1080',
+        StatsEnabled: '1',
+        LogLevel: 'info'
+      };
+
+      settings.applySettings(cmsSettings);
+
+      expect(settings.settings.collectInterval).toBe(600);
+      expect(settings.settings.displayName).toBe('CamelCase Display');
+      expect(settings.settings.sizeX).toBe(1920);
+      expect(settings.settings.sizeY).toBe(1080);
+      expect(settings.settings.statsEnabled).toBe(true);
+      expect(settings.settings.logLevel).toBe('info');
+    });
+  });
+
+  describe('parseCollectInterval', () => {
+    it('should parse valid interval', () => {
+      expect(settings.parseCollectInterval(600)).toBe(600);
+      expect(settings.parseCollectInterval('900')).toBe(900);
+    });
+
+    it('should enforce minimum interval (60 seconds)', () => {
+      expect(settings.parseCollectInterval(30)).toBe(300);
+      expect(settings.parseCollectInterval(0)).toBe(300);
+      expect(settings.parseCollectInterval(-100)).toBe(300);
+    });
+
+    it('should enforce maximum interval (24 hours)', () => {
+      expect(settings.parseCollectInterval(100000)).toBe(86400);
+      expect(settings.parseCollectInterval(999999)).toBe(86400);
+    });
+
+    it('should handle invalid input', () => {
+      expect(settings.parseCollectInterval('invalid')).toBe(300);
+      expect(settings.parseCollectInterval(null)).toBe(300);
+      expect(settings.parseCollectInterval(undefined)).toBe(300);
+      expect(settings.parseCollectInterval(NaN)).toBe(300);
+    });
+  });
+
+  describe('parseBoolean', () => {
+    it('should parse boolean values', () => {
+      expect(settings.parseBoolean(true)).toBe(true);
+      expect(settings.parseBoolean(false)).toBe(false);
+    });
+
+    it('should parse string values', () => {
+      expect(settings.parseBoolean('1')).toBe(true);
+      expect(settings.parseBoolean('0')).toBe(false);
+    });
+
+    it('should parse numeric values', () => {
+      expect(settings.parseBoolean(1)).toBe(true);
+      expect(settings.parseBoolean(0)).toBe(false);
+    });
+
+    it('should use default value for invalid input', () => {
+      expect(settings.parseBoolean(null)).toBe(false);
+      expect(settings.parseBoolean(undefined)).toBe(false);
+      expect(settings.parseBoolean('yes')).toBe(false);
+      expect(settings.parseBoolean('no')).toBe(false);
+      expect(settings.parseBoolean(null, true)).toBe(true);
+    });
+  });
+
+  describe('getters', () => {
+    beforeEach(() => {
+      settings.applySettings({
+        collectInterval: 900,
+        displayName: 'My Display',
+        sizeX: '2560',
+        sizeY: '1440',
+        statsEnabled: '1'
+      });
+    });
+
+    it('should get collection interval', () => {
+      expect(settings.getCollectInterval()).toBe(900);
+    });
+
+    it('should get display name', () => {
+      expect(settings.getDisplayName()).toBe('My Display');
+    });
+
+    it('should get display size', () => {
+      const size = settings.getDisplaySize();
+      expect(size.width).toBe(2560);
+      expect(size.height).toBe(1440);
+    });
+
+    it('should check if stats enabled', () => {
+      expect(settings.isStatsEnabled()).toBe(true);
+    });
+
+    it('should get all settings', () => {
+      const allSettings = settings.getAllSettings();
+      expect(allSettings.collectInterval).toBe(900);
+      expect(allSettings.displayName).toBe('My Display');
+      expect(allSettings.statsEnabled).toBe(true);
+    });
+
+    it('should get specific setting', () => {
+      expect(settings.getSetting('collectInterval')).toBe(900);
+      expect(settings.getSetting('displayName')).toBe('My Display');
+      expect(settings.getSetting('unknownSetting', 'default')).toBe('default');
+    });
+  });
+
+  describe('download windows', () => {
+    describe('isInDownloadWindow', () => {
+      it('should return true if no download window configured', () => {
+        expect(settings.isInDownloadWindow()).toBe(true);
+      });
+
+      it('should return true if only start window configured', () => {
+        settings.applySettings({ downloadStartWindow: '14:00' });
+        expect(settings.isInDownloadWindow()).toBe(true);
+      });
+
+      it('should return true if only end window configured', () => {
+        settings.applySettings({ downloadEndWindow: '18:00' });
+        expect(settings.isInDownloadWindow()).toBe(true);
+      });
+
+      it('should check normal same-day window', () => {
+        settings.applySettings({
+          downloadStartWindow: '09:00',
+          downloadEndWindow: '17:00'
+        });
+
+        // Mock current time to 12:00 (within window)
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date(2026, 0, 15, 12, 0, 0));
+
+        expect(settings.isInDownloadWindow()).toBe(true);
+
+        // Mock current time to 08:00 (before window)
+        vi.setSystemTime(new Date(2026, 0, 15, 8, 0, 0));
+        expect(settings.isInDownloadWindow()).toBe(false);
+
+        // Mock current time to 18:00 (after window)
+        vi.setSystemTime(new Date(2026, 0, 15, 18, 0, 0));
+        expect(settings.isInDownloadWindow()).toBe(false);
+
+        vi.useRealTimers();
+      });
+
+      it('should check overnight window (crosses midnight)', () => {
+        settings.applySettings({
+          downloadStartWindow: '22:00',
+          downloadEndWindow: '06:00'
+        });
+
+        // Mock current time to 23:00 (within overnight window)
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date(2026, 0, 15, 23, 0, 0));
+
+        expect(settings.isInDownloadWindow()).toBe(true);
+
+        // Mock current time to 02:00 (within overnight window)
+        vi.setSystemTime(new Date(2026, 0, 15, 2, 0, 0));
+        expect(settings.isInDownloadWindow()).toBe(true);
+
+        // Mock current time to 12:00 (outside overnight window)
+        vi.setSystemTime(new Date(2026, 0, 15, 12, 0, 0));
+        expect(settings.isInDownloadWindow()).toBe(false);
+
+        vi.useRealTimers();
+      });
+
+      it('should handle invalid time window gracefully', () => {
+        settings.applySettings({
+          downloadStartWindow: 'invalid',
+          downloadEndWindow: '17:00'
+        });
+
+        // Should return true (allow downloads) if parsing fails
+        expect(settings.isInDownloadWindow()).toBe(true);
+      });
+    });
+
+    describe('parseTimeWindow', () => {
+      it('should parse valid time strings', () => {
+        expect(settings.parseTimeWindow('00:00')).toBe(0);
+        expect(settings.parseTimeWindow('12:30')).toBe(750);
+        expect(settings.parseTimeWindow('23:59')).toBe(1439);
+      });
+
+      it('should reject invalid formats', () => {
+        expect(() => settings.parseTimeWindow('12')).toThrow('Invalid time window format');
+        expect(() => settings.parseTimeWindow('12:30:00')).toThrow('Invalid time window format');
+        expect(() => settings.parseTimeWindow('invalid')).toThrow('Invalid time window format');
+        expect(() => settings.parseTimeWindow(null)).toThrow('Invalid time window format');
+        expect(() => settings.parseTimeWindow(undefined)).toThrow('Invalid time window format');
+      });
+
+      it('should reject invalid values', () => {
+        expect(() => settings.parseTimeWindow('24:00')).toThrow('Invalid time window values');
+        expect(() => settings.parseTimeWindow('12:60')).toThrow('Invalid time window values');
+        expect(() => settings.parseTimeWindow('-1:30')).toThrow('Invalid time window values');
+        expect(() => settings.parseTimeWindow('12:-1')).toThrow('Invalid time window values');
+      });
+    });
+
+    describe('getNextDownloadWindow', () => {
+      it('should return null if no download window configured', () => {
+        expect(settings.getNextDownloadWindow()).toBeNull();
+      });
+
+      it('should calculate next window later today', () => {
+        settings.applySettings({
+          downloadStartWindow: '15:00',
+          downloadEndWindow: '18:00'
+        });
+
+        // Mock current time to 10:00
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date(2026, 0, 15, 10, 0, 0));
+
+        const nextWindow = settings.getNextDownloadWindow();
+        expect(nextWindow).toBeTruthy();
+        expect(nextWindow.getHours()).toBe(15);
+        expect(nextWindow.getMinutes()).toBe(0);
+
+        vi.useRealTimers();
+      });
+
+      it('should calculate next window tomorrow', () => {
+        settings.applySettings({
+          downloadStartWindow: '09:00',
+          downloadEndWindow: '17:00'
+        });
+
+        // Mock current time to 20:00 (after window)
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date(2026, 0, 15, 20, 0, 0));
+
+        const nextWindow = settings.getNextDownloadWindow();
+        expect(nextWindow).toBeTruthy();
+        expect(nextWindow.getDate()).toBe(16); // Tomorrow
+        expect(nextWindow.getHours()).toBe(9);
+        expect(nextWindow.getMinutes()).toBe(0);
+
+        vi.useRealTimers();
+      });
+
+      it('should handle invalid time window gracefully', () => {
+        settings.applySettings({
+          downloadStartWindow: 'invalid',
+          downloadEndWindow: '17:00'
+        });
+
+        expect(settings.getNextDownloadWindow()).toBeNull();
+      });
+    });
+  });
+
+  describe('screenshot', () => {
+    beforeEach(() => {
+      settings.applySettings({ screenshotInterval: 120 });
+    });
+
+    it('should return true if no last screenshot', () => {
+      expect(settings.shouldTakeScreenshot(null)).toBe(true);
+    });
+
+    it('should return false if interval not elapsed', () => {
+      vi.useFakeTimers();
+      const now = new Date(2026, 0, 15, 12, 0, 0);
+      vi.setSystemTime(now);
+
+      const lastScreenshot = new Date(now.getTime() - 60000); // 60 seconds ago
+      expect(settings.shouldTakeScreenshot(lastScreenshot)).toBe(false);
+
+      vi.useRealTimers();
+    });
+
+    it('should return true if interval elapsed', () => {
+      vi.useFakeTimers();
+      const now = new Date(2026, 0, 15, 12, 0, 0);
+      vi.setSystemTime(now);
+
+      const lastScreenshot = new Date(now.getTime() - 130000); // 130 seconds ago
+      expect(settings.shouldTakeScreenshot(lastScreenshot)).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    it('should handle exact interval boundary', () => {
+      vi.useFakeTimers();
+      const now = new Date(2026, 0, 15, 12, 0, 0);
+      vi.setSystemTime(now);
+
+      const lastScreenshot = new Date(now.getTime() - 120000); // Exactly 120 seconds ago
+      expect(settings.shouldTakeScreenshot(lastScreenshot)).toBe(true);
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('edge cases and integration', () => {
+    it('should handle empty settings object', () => {
+      const result = settings.applySettings({});
+      expect(result.changed).toEqual([]);
+      expect(result.settings.collectInterval).toBe(300); // Default
+    });
+
+    it('should handle mixed case and missing values', () => {
+      const cmsSettings = {
+        CollectInterval: '450',
+        displayName: null,
+        SizeX: undefined,
+        statsEnabled: ''
+      };
+
+      settings.applySettings(cmsSettings);
+
+      expect(settings.settings.collectInterval).toBe(450);
+      expect(settings.settings.displayName).toBe('Unknown Display'); // Default
+      expect(settings.settings.sizeX).toBe(1920); // Default
+      expect(settings.settings.statsEnabled).toBe(false); // Default
+    });
+
+    it('should handle multiple consecutive applies', () => {
+      // First apply
+      settings.applySettings({ collectInterval: 600, displayName: 'Display 1' });
+      expect(settings.settings.collectInterval).toBe(600);
+      expect(settings.settings.displayName).toBe('Display 1');
+
+      // Second apply (different interval)
+      settings.applySettings({ collectInterval: 900, displayName: 'Display 2' });
+      expect(settings.settings.collectInterval).toBe(900);
+      expect(settings.settings.displayName).toBe('Display 2');
+
+      // Third apply (same interval, different name)
+      settings.applySettings({ collectInterval: 900, displayName: 'Display 3' });
+      expect(settings.settings.collectInterval).toBe(900);
+      expect(settings.settings.displayName).toBe('Display 3');
+    });
+
+    it('should preserve settings across multiple applies', () => {
+      // Apply initial settings
+      settings.applySettings({
+        collectInterval: 600,
+        displayName: 'Test',
+        statsEnabled: '1'
+      });
+
+      expect(settings.settings.statsEnabled).toBe(true);
+      expect(settings.settings.displayName).toBe('Test');
+
+      // Apply partial update (NOTE: settings are re-applied from scratch, not preserved)
+      // This matches upstream behavior where each RegisterDisplay overwrites settings
+      settings.applySettings({ collectInterval: 900 });
+
+      // After partial update, missing values revert to defaults (not preserved)
+      expect(settings.settings.statsEnabled).toBe(false); // Reverts to default
+      expect(settings.settings.collectInterval).toBe(900);
+    });
+
+    it('should handle SSP (ad space) settings', () => {
+      settings.applySettings({ isAdspaceEnabled: '1' });
+      expect(settings.settings.isSspEnabled).toBe(true);
+
+      settings.applySettings({ isAdspaceEnabled: '0' });
+      expect(settings.settings.isSspEnabled).toBe(false);
+
+      settings.applySettings({ IsAdspaceEnabled: '1' });
+      expect(settings.settings.isSspEnabled).toBe(true);
+    });
+
+    it('should handle XMR settings', () => {
+      const cmsSettings = {
+        xmrNetworkAddress: 'tcp://xmr.example.com:9505',
+        xmrWebSocketAddress: 'ws://xmr.example.com:9505',
+        xmrCmsKey: 'test-key-12345'
+      };
+
+      settings.applySettings(cmsSettings);
+
+      expect(settings.settings.xmrNetworkAddress).toBe('tcp://xmr.example.com:9505');
+      expect(settings.settings.xmrWebSocketAddress).toBe('ws://xmr.example.com:9505');
+      expect(settings.settings.xmrCmsKey).toBe('test-key-12345');
+    });
+
+    it('should handle all supported log levels', () => {
+      const levels = ['error', 'audit', 'info', 'debug'];
+
+      for (const level of levels) {
+        settings.applySettings({ logLevel: level });
+        expect(settings.settings.logLevel).toBe(level);
+      }
+    });
+  });
+});

package/vitest.config.js

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.js'],
+  },
+});

package/vitest.setup.js

@@ -0,0 +1,23 @@
+/**
+ * Vitest setup file
+ * Mocks browser APIs that are not available in test environment
+ */
+
+// Mock localStorage
+const localStorageMock = {
+  store: {},
+  getItem(key) {
+    return this.store[key] || null;
+  },
+  setItem(key, value) {
+    this.store[key] = String(value);
+  },
+  removeItem(key) {
+    delete this.store[key];
+  },
+  clear() {
+    this.store = {};
+  },
+};
+
+global.localStorage = localStorageMock;