@xiboplayer/utils 0.6.3 → 0.6.4

package/README.md

@@ -6,11 +6,13 @@
 
 Foundation utilities used across the SDK:
 
-- **Logger** — structured logging with configurable levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`) and per-module tags
-- **EventEmitter** — lightweight pub/sub event system
-- **fetchWithRetry** — HTTP fetch with exponential backoff, jitter, and configurable retries
-- **CMS REST client** — JSON API client with ETag caching
-- **Config** — hardware key management and IndexedDB-backed configuration
+- **Logger** -- structured logging with configurable levels (DEBUG, INFO, WARNING, ERROR, NONE) and per-module tags
+- **Log sinks** -- pluggable log destinations (console, LogReporter for CMS submission)
+- **EventEmitter** -- lightweight pub/sub event system
+- **fetchWithRetry** -- HTTP fetch with exponential backoff, jitter, and configurable retries
+- **Config** -- hardware key management, IndexedDB-backed configuration, CMS ID computation
+- **CMS REST API client** -- 77-method JSON API client with ETag caching and JWT auth
+- **PLAYER_API** -- configurable base path for media/widget/dependency URLs
 
 ## Installation
 
@@ -20,17 +22,104 @@ npm install @xiboplayer/utils
 
 ## Usage
 
+### Logger
+
 ```javascript
-import { createLogger, EventEmitter, fetchWithRetry } from '@xiboplayer/utils';
+import { createLogger, setLogLevel, applyCmsLogLevel, registerLogSink } from '@xiboplayer/utils';
 
 const log = createLogger('my-module');
 log.info('Starting...');
-log.debug('Detailed info');
+log.debug('Detailed info', { key: 'value' });
+log.warn('Something unexpected');
+log.error('Critical failure', error);
+
+// Set global log level
+setLogLevel('DEBUG');  // DEBUG, INFO, WARNING, ERROR, NONE
 
-const emitter = new EventEmitter();
-emitter.on('event', (data) => console.log(data));
+// Apply CMS log level (maps CMS values to SDK levels)
+applyCmsLogLevel('audit'); // maps to DEBUG
 
-const response = await fetchWithRetry(url, { retries: 3 });
+// Register a custom log sink (e.g., CMS log reporter)
+registerLogSink({
+  log(level, tag, ...args) {
+    cmsReporter.log(level, args.join(' '), tag);
+  }
+});
+```
+
+### EventEmitter
+
+```javascript
+import { EventEmitter } from '@xiboplayer/utils';
+
+class MyClass extends EventEmitter {
+  doSomething() {
+    this.emit('done', { result: 42 });
+  }
+}
+
+const obj = new MyClass();
+obj.on('done', (data) => console.log(data));
+obj.once('done', (data) => console.log('First time only'));
+obj.off('done', handler);
+```
+
+### fetchWithRetry
+
+```javascript
+import { fetchWithRetry } from '@xiboplayer/utils';
+
+const response = await fetchWithRetry(url, {
+  retries: 3,        // Max retry attempts (default: 2)
+  baseDelay: 2000,   // Base delay in ms (default: 2000)
+  // Backoff: baseDelay * 2^attempt + random jitter
+  headers: { 'Content-Type': 'application/json' },
+  method: 'POST',
+  body: JSON.stringify(data),
+});
+```
+
+### Config
+
+```javascript
+import { config, computeCmsId } from '@xiboplayer/utils';
+
+// Read config values (from localStorage / IndexedDB)
+const cmsUrl = config.data.cmsUrl;
+const hardwareKey = config.data.hardwareKey;
+
+// Compute CMS ID for namespacing databases
+const cmsId = computeCmsId('https://cms.example.com', 'display-key');
+// Returns FNV hash string for unique IndexedDB names per CMS+display pair
+```
+
+### CMS REST API client
+
+```javascript
+import { CmsApiClient } from '@xiboplayer/utils';
+
+const api = new CmsApiClient({
+  baseUrl: 'https://cms.example.com',
+  clientId: 'oauth-client-id',
+  clientSecret: 'oauth-client-secret',
+});
+
+// 77 methods covering all CMS entities
+const displays = await api.getDisplays();
+const layouts = await api.getLayouts();
+await api.authorizeDisplay(displayId);
+```
+
+### PLAYER_API
+
+```javascript
+import { PLAYER_API, setPlayerApi } from '@xiboplayer/utils';
+
+// Default: '/api/v2/player'
+console.log(PLAYER_API); // '/api/v2/player'
+
+// Override before route registration (e.g., in proxy setup)
+setPlayerApi('/custom/player/path');
 ```
 
 ## Exports
@@ -38,9 +127,28 @@ const response = await fetchWithRetry(url, { retries: 3 });
 | Export | Description |
 |--------|-------------|
 | `createLogger(tag)` | Create a tagged logger instance |
-| `EventEmitter` | Pub/sub event emitter |
+| `setLogLevel(level)` | Set global log level |
+| `getLogLevel()` | Get current log level |
+| `isDebug()` | Check if DEBUG level is active |
+| `applyCmsLogLevel(cmsLevel)` | Map CMS log level to SDK level |
+| `registerLogSink(sink)` | Add custom log destination |
+| `unregisterLogSink(sink)` | Remove log destination |
+| `LOG_LEVELS` | Level constants: DEBUG, INFO, WARNING, ERROR, NONE |
+| `EventEmitter` | Pub/sub event emitter class |
 | `fetchWithRetry(url, opts)` | Fetch with exponential backoff |
-| `Config` | Hardware key and IndexedDB config management |
+| `config` | Global config instance (localStorage/IndexedDB) |
+| `extractPwaConfig(config)` | Extract PWA-relevant keys from shell config |
+| `computeCmsId(url, key)` | FNV hash for CMS+display namespacing |
+| `SHELL_ONLY_KEYS` | Config keys not forwarded to PWA |
+| `CmsApiClient` | CMS REST API client (77 methods) |
+| `CmsApiError` | API error class with status code |
+| `PLAYER_API` | Media/widget base path (configurable) |
+| `setPlayerApi(base)` | Override PLAYER_API at runtime |
+| `VERSION` | Package version from package.json |
+
+## Dependencies
+
+No external runtime dependencies.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/utils",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Shared utilities for Xibo Player packages",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,7 @@
     "./config": "./src/config.js"
   },
   "dependencies": {
-    "@xiboplayer/crypto": "0.6.3"
+    "@xiboplayer/crypto": "0.6.4"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/config.js

@@ -1,15 +1,70 @@
 /**
  * Configuration management with priority: env vars → localStorage → defaults
  *
+ * Storage layout (per-CMS namespacing):
+ *   xibo_global       — device identity: hardwareKey, xmrPubKey, xmrPrivKey
+ *   xibo_cms:{cmsId}  — CMS-scoped: cmsUrl, cmsKey, displayName, xmrChannel, ...
+ *   xibo_active_cms   — string cmsId of the currently active CMS
+ *   xibo_config       — legacy flat key (written for rollback compatibility)
+ *
  * In Node.js (tests, CLI): environment variables are the only source.
  * In browser (PWA player): localStorage is primary, env vars override if set.
  */
 import { generateRsaKeyPair, isValidPemKey } from '@xiboplayer/crypto';
 
-const STORAGE_KEY = 'xibo_config';
+const GLOBAL_KEY = 'xibo_global';         // Device identity (all CMSes)
+const CMS_PREFIX = 'xibo_cms:';           // Per-CMS config prefix
+const ACTIVE_CMS_KEY = 'xibo_active_cms'; // Active CMS ID
 const HW_DB_NAME = 'xibo-hw-backup';
 const HW_DB_VERSION = 1;
 
+// Keys that belong to device identity (global, not CMS-scoped)
+const GLOBAL_KEYS = new Set(['hardwareKey', 'xmrPubKey', 'xmrPrivKey']);
+
+/**
+ * FNV-1a hash producing a 12-character hex string.
+ * Deterministic: same input always produces same output.
+ * @param {string} str - Input string to hash
+ * @returns {string} 12-character lowercase hex string
+ */
+export function fnvHash(str) {
+  let hash = 2166136261; // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+  }
+  hash = hash >>> 0;
+
+  // Extend to 12 chars with a second round using a different seed
+  let hash2 = hash + 1234567;
+  for (let i = 0; i < str.length; i++) {
+    hash2 ^= str.charCodeAt(i) + 1;
+    hash2 += (hash2 << 1) + (hash2 << 4) + (hash2 << 7) + (hash2 << 8) + (hash2 << 24);
+  }
+  hash2 = hash2 >>> 0;
+
+  return (hash.toString(16).padStart(8, '0') + hash2.toString(16).padStart(8, '0')).substring(0, 12);
+}
+
+/**
+ * Compute a deterministic CMS ID from a CMS URL.
+ * Format: {hostname}-{fnvHash12}
+ *
+ * @param {string} cmsUrl - Full CMS URL (e.g. "https://displays.superpantalles.com")
+ * @returns {string} CMS ID (e.g. "displays.superpantalles.com-a1b2c3d4e5f6")
+ */
+export function computeCmsId(cmsUrl) {
+  if (!cmsUrl) return null;
+  try {
+    const url = new URL(cmsUrl);
+    const origin = url.origin;
+    return `${url.hostname}-${fnvHash(origin)}`;
+  } catch (e) {
+    // Invalid URL — hash the raw string
+    return `unknown-${fnvHash(cmsUrl)}`;
+  }
+}
+
 /**
  * Check for environment variable config (highest priority).
  * Env vars: CMS_URL, CMS_KEY, DISPLAY_NAME, HARDWARE_KEY, XMR_CHANNEL
@@ -35,6 +90,7 @@ function loadFromEnv() {
 
 export class Config {
   constructor() {
+    this._activeCmsId = null;
     this.data = this.load();
     // Async: try to restore hardware key from IndexedDB if localStorage lost it
     // (only when not running from env vars)
@@ -56,19 +112,63 @@ export class Config {
       return { cmsUrl: '', cmsKey: '', displayName: '', hardwareKey: '', xmrChannel: '' };
     }
 
-    // Try to load from localStorage
-    const json = localStorage.getItem(STORAGE_KEY);
-    let config = {};
+    // Load from split storage (or fresh install)
+    const globalJson = localStorage.getItem(GLOBAL_KEY);
+
+    if (globalJson) {
+      return this._loadSplit();
+    }
+
+    // Fresh install — no config at all
+    return this._loadFresh();
+  }
+
+  /**
+   * Load from split storage (new format).
+   * Merges xibo_global + xibo_cms:{activeCmsId} into a single data object.
+   */
+  _loadSplit() {
+    let global = {};
+    try {
+      global = JSON.parse(localStorage.getItem(GLOBAL_KEY) || '{}');
+    } catch (e) {
+      console.error('[Config] Failed to parse xibo_global:', e);
+    }
+
+    // Determine active CMS
+    const activeCmsId = localStorage.getItem(ACTIVE_CMS_KEY) || null;
+    this._activeCmsId = activeCmsId;
 
-    if (json) {
+    let cmsConfig = {};
+    if (activeCmsId) {
       try {
-        config = JSON.parse(json);
+        const cmsJson = localStorage.getItem(CMS_PREFIX + activeCmsId);
+        if (cmsJson) cmsConfig = JSON.parse(cmsJson);
       } catch (e) {
-        console.error('[Config] Failed to parse localStorage config:', e);
+        console.error('[Config] Failed to parse CMS config:', e);
       }
     }
 
-    // ── Single validation gate (same path for fresh + pre-seeded) ──
+    // Merge global + CMS-scoped
+    const config = { ...global, ...cmsConfig };
+
+    // Validate and generate missing keys
+    return this._validateConfig(config);
+  }
+
+  /**
+   * Fresh install — no existing config.
+   */
+  _loadFresh() {
+    const config = {};
+    return this._validateConfig(config);
+  }
+
+  /**
+   * Validate config, generate missing hardwareKey/xmrChannel.
+   * Shared by all load paths.
+   */
+  _validateConfig(config) {
     let changed = false;
 
     if (!config.hardwareKey || config.hardwareKey.length < 10) {
@@ -91,13 +191,159 @@ export class Config {
     config.cmsKey = config.cmsKey || '';
     config.displayName = config.displayName || '';
 
-    if (changed) {
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(config));
+    if (changed && typeof localStorage !== 'undefined') {
+      // Save via split storage
+      this._saveSplit(config);
     }
 
     return config;
   }
 
+  save() {
+    if (typeof localStorage === 'undefined') return;
+    this._saveSplit(this.data);
+  }
+
+  /**
+   * Write data to split storage: xibo_global + xibo_cms:{id} + legacy xibo_config.
+   */
+  _saveSplit(data) {
+    if (typeof localStorage === 'undefined') return;
+
+    // Split into global and CMS-scoped
+    const global = {};
+    const cmsScoped = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (GLOBAL_KEYS.has(key)) {
+        global[key] = value;
+      } else {
+        cmsScoped[key] = value;
+      }
+    }
+
+    localStorage.setItem(GLOBAL_KEY, JSON.stringify(global));
+
+    // Compute CMS ID (may update if cmsUrl changed)
+    const cmsId = computeCmsId(data.cmsUrl);
+    if (cmsId) {
+      localStorage.setItem(CMS_PREFIX + cmsId, JSON.stringify(cmsScoped));
+      localStorage.setItem(ACTIVE_CMS_KEY, cmsId);
+      this._activeCmsId = cmsId;
+    }
+
+    // Legacy flat key for rollback compatibility (index.html gate, tests, etc.)
+    localStorage.setItem('xibo_config', JSON.stringify(data));
+  }
+
+  /**
+   * Switch to a different CMS. Saves the current CMS profile,
+   * loads (or creates) the target CMS profile.
+   *
+   * @param {string} cmsUrl - New CMS URL to switch to
+   * @returns {{ cmsId: string, isNew: boolean }} The new CMS ID and whether it was newly created
+   */
+  switchCms(cmsUrl) {
+    if (typeof localStorage === 'undefined') {
+      throw new Error('switchCms requires localStorage (browser only)');
+    }
+
+    // Save current state
+    this.save();
+
+    const newCmsId = computeCmsId(cmsUrl);
+    if (!newCmsId) throw new Error('Invalid CMS URL');
+
+    // Try to load existing CMS profile
+    const existingJson = localStorage.getItem(CMS_PREFIX + newCmsId);
+    let cmsConfig = {};
+    let isNew = true;
+
+    if (existingJson) {
+      try {
+        cmsConfig = JSON.parse(existingJson);
+        isNew = false;
+        console.log(`[Config] Switching to existing CMS profile: ${newCmsId}`);
+      } catch (e) {
+        console.error('[Config] Failed to parse target CMS config:', e);
+      }
+    } else {
+      console.log(`[Config] Creating new CMS profile: ${newCmsId}`);
+      cmsConfig = {
+        cmsUrl,
+        cmsKey: '',
+        displayName: '',
+        xmrChannel: this.generateXmrChannel(),
+      };
+      localStorage.setItem(CMS_PREFIX + newCmsId, JSON.stringify(cmsConfig));
+    }
+
+    // Update active CMS
+    localStorage.setItem(ACTIVE_CMS_KEY, newCmsId);
+    this._activeCmsId = newCmsId;
+
+    // Merge global + new CMS config into data
+    let global = {};
+    try {
+      global = JSON.parse(localStorage.getItem(GLOBAL_KEY) || '{}');
+    } catch (_) {}
+
+    this.data = { ...global, ...cmsConfig };
+
+    // Ensure cmsUrl is set (in case the profile was pre-existing without it)
+    if (!this.data.cmsUrl) {
+      this.data.cmsUrl = cmsUrl;
+    }
+
+    return { cmsId: newCmsId, isNew };
+  }
+
+  /**
+   * List all CMS profiles stored in localStorage.
+   * @returns {Array<{ cmsId: string, cmsUrl: string, displayName: string, isActive: boolean }>}
+   */
+  listCmsProfiles() {
+    if (typeof localStorage === 'undefined') return [];
+
+    const profiles = [];
+    const activeCmsId = localStorage.getItem(ACTIVE_CMS_KEY) || null;
+
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (!key.startsWith(CMS_PREFIX)) continue;
+
+      const cmsId = key.slice(CMS_PREFIX.length);
+      try {
+        const data = JSON.parse(localStorage.getItem(key));
+        profiles.push({
+          cmsId,
+          cmsUrl: data.cmsUrl || '',
+          displayName: data.displayName || '',
+          isActive: cmsId === activeCmsId,
+        });
+      } catch (_) {}
+    }
+
+    return profiles;
+  }
+
+  /**
+   * Get the active CMS ID (deterministic hash of the CMS URL origin).
+   * Returns null if no CMS is configured.
+   * @returns {string|null}
+   */
+  get activeCmsId() {
+    // Return cached value if available
+    if (this._activeCmsId) return this._activeCmsId;
+    // Compute from current cmsUrl
+    const id = computeCmsId(this.data?.cmsUrl);
+    this._activeCmsId = id;
+    return id;
+  }
+
+  isConfigured() {
+    return !!(this.data.cmsUrl && this.data.cmsKey && this.data.displayName);
+  }
+
   /**
    * Backup keys to IndexedDB (more persistent than localStorage).
    * IndexedDB survives "Clear site data" in some browsers where localStorage doesn't.
@@ -179,16 +425,6 @@ export class Config {
     }
   }
 
-  save() {
-    if (typeof localStorage !== 'undefined') {
-      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.data));
-    }
-  }
-
-  isConfigured() {
-    return !!(this.data.cmsUrl && this.data.cmsKey && this.data.displayName);
-  }
-
   generateStableHardwareKey() {
     // Generate a stable UUID-based hardware key
     // CRITICAL: This is generated ONCE and saved to localStorage
@@ -331,6 +567,10 @@ export class Config {
 
   get googleGeoApiKey() { return this.data.googleGeoApiKey || ''; }
   set googleGeoApiKey(val) { this.data.googleGeoApiKey = val; this.save(); }
+
+  get controls() { return this.data.controls || {}; }
+  get transport() { return this.data.transport || 'auto'; }
+  get debug() { return this.data.debug || {}; }
 }
 
 export const config = new Config();
@@ -343,16 +583,50 @@ export const config = new Config();
  * to extractPwaConfig().
  *
  * Electron extras:  autoLaunch
- * Chromium extras:  browser, extraBrowserFlags, relaxSslCerts
+ * Chromium extras:  browser, extraBrowserFlags
  */
+/**
+ * Keys that are specific to a particular shell platform.
+ * Used by warnPlatformMismatch() to detect config.json mistakes.
+ */
+const PLATFORM_KEYS = {
+  kioskMode:          ['electron', 'chromium'],
+  autoLaunch:         ['electron'],
+  allowShellCommands: ['electron', 'chromium'],
+  browser:            ['chromium'],
+  extraBrowserFlags:  ['chromium'],
+};
+
+/**
+ * Log warnings for config keys that don't belong to the current platform.
+ * Informational only — does not prevent startup.
+ *
+ * @param {Object} configObj - The full config.json object
+ * @param {string} platform - Current platform: 'electron' or 'chromium'
+ */
+export function warnPlatformMismatch(configObj, platform) {
+  if (!configObj || !platform) return;
+  const p = platform.toLowerCase();
+  for (const [key, platforms] of Object.entries(PLATFORM_KEYS)) {
+    if (key in configObj && !platforms.includes(p)) {
+      console.warn(
+        `[Config] Key "${key}" is only supported on ${platforms.join('/')}, ` +
+        `but current platform is ${p} — this key will be ignored`
+      );
+    }
+  }
+}
+
 export const SHELL_ONLY_KEYS = new Set([
   'serverPort',
   'kioskMode',
   'fullscreen',
   'hideMouseCursor',
   'preventSleep',
+  'allowShellCommands',
   'width',
   'height',
+  'relaxSslCerts',
 ]);
 
 /**

package/src/config.test.js

@@ -1,7 +1,8 @@
 /**
  * Config Tests
  *
- * Tests for configuration management with localStorage persistence
+ * Tests for configuration management with split localStorage persistence
+ * (xibo_global + xibo_cms:{cmsId} + xibo_active_cms)
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
@@ -24,7 +25,27 @@ vi.mock('@xiboplayer/crypto', () => {
   };
 });
 
-import { Config } from './config.js';
+import { Config, computeCmsId, fnvHash, warnPlatformMismatch } from './config.js';
+
+/**
+ * Seed split localStorage with a full config (global + CMS-scoped).
+ * Helper to set up pre-existing config in the new format.
+ */
+function seedConfig(storage, data) {
+  const GLOBAL_KEYS = new Set(['hardwareKey', 'xmrPubKey', 'xmrPrivKey']);
+  const global = {};
+  const cms = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (GLOBAL_KEYS.has(k)) global[k] = v;
+    else cms[k] = v;
+  }
+  storage.setItem('xibo_global', JSON.stringify(global));
+  const cmsId = computeCmsId(data.cmsUrl);
+  if (cmsId) {
+    storage.setItem(`xibo_cms:${cmsId}`, JSON.stringify(cms));
+    storage.setItem('xibo_active_cms', cmsId);
+  }
+}
 
 describe('Config', () => {
   let config;
@@ -32,7 +53,7 @@ describe('Config', () => {
   let mockRandomUUID;
 
   beforeEach(() => {
-    // Mock localStorage
+    // Mock localStorage (with key/length for iteration in listCmsProfiles)
     mockLocalStorage = {
       data: {},
       getItem(key) {
@@ -46,6 +67,12 @@ describe('Config', () => {
       },
       clear() {
         this.data = {};
+      },
+      key(index) {
+        return Object.keys(this.data)[index] || null;
+      },
+      get length() {
+        return Object.keys(this.data).length;
       }
     };
 
@@ -91,14 +118,14 @@ describe('Config', () => {
       expect(hwKey).toBe('pwa-1234567812344567890123456789');
     });
 
-    it('should save config to localStorage on creation', () => {
+    it('should save config to split localStorage on creation', () => {
       config = new Config();
 
-      const stored = JSON.parse(mockLocalStorage.getItem('xibo_config'));
-      expect(stored).toEqual(config.data);
+      const global = JSON.parse(mockLocalStorage.getItem('xibo_global'));
+      expect(global.hardwareKey).toBe(config.data.hardwareKey);
     });
 
-    it('should load existing config from localStorage', () => {
+    it('should load existing config from split localStorage', () => {
       const existingConfig = {
         cmsUrl: 'https://test.cms.com',
         cmsKey: 'test-key',
@@ -107,23 +134,25 @@ describe('Config', () => {
         xmrChannel: '12345678-1234-4567-8901-234567890abc'
       };
 
-      mockLocalStorage.setItem('xibo_config', JSON.stringify(existingConfig));
+      seedConfig(mockLocalStorage, existingConfig);
 
       config = new Config();
 
-      expect(config.data).toEqual(existingConfig);
+      expect(config.data.cmsUrl).toBe('https://test.cms.com');
+      expect(config.data.cmsKey).toBe('test-key');
+      expect(config.data.displayName).toBe('Test Display');
+      expect(config.data.hardwareKey).toBe('pwa-existinghardwarekey1234567');
+      expect(config.data.xmrChannel).toBe('12345678-1234-4567-8901-234567890abc');
     });
 
     it('should regenerate hardware key if invalid in stored config', () => {
-      const invalidConfig = {
+      seedConfig(mockLocalStorage, {
         cmsUrl: 'https://test.cms.com',
         cmsKey: 'test-key',
         displayName: 'Test Display',
         hardwareKey: 'short', // Invalid: too short
         xmrChannel: '12345678-1234-4567-8901-234567890abc'
-      };
-
-      mockLocalStorage.setItem('xibo_config', JSON.stringify(invalidConfig));
+      });
 
       config = new Config();
 
@@ -132,7 +161,7 @@ describe('Config', () => {
     });
 
     it('should handle corrupted JSON in localStorage', () => {
-      mockLocalStorage.setItem('xibo_config', 'invalid-json{');
+      mockLocalStorage.setItem('xibo_global', 'invalid-json{');
 
       config = new Config();
 
@@ -307,11 +336,12 @@ describe('Config', () => {
       expect(config.data.cmsUrl).toBe('https://new.cms.com');
     });
 
-    it('should save to localStorage when cmsUrl set', () => {
+    it('should save to split localStorage when cmsUrl set', () => {
       config.cmsUrl = 'https://test.com';
 
-      const stored = JSON.parse(mockLocalStorage.getItem('xibo_config'));
-      expect(stored.cmsUrl).toBe('https://test.com');
+      const cmsId = computeCmsId('https://test.com');
+      const cms = JSON.parse(mockLocalStorage.getItem(`xibo_cms:${cmsId}`));
+      expect(cms.cmsUrl).toBe('https://test.com');
     });
 
     it('should get/set cmsKey', () => {
@@ -383,22 +413,24 @@ describe('Config', () => {
       config = new Config();
     });
 
-    it('should save current config to localStorage', () => {
+    it('should save current config to split localStorage', () => {
       config.data.cmsUrl = 'https://manual.com';
       config.data.cmsKey = 'manual-key';
 
       config.save();
 
-      const stored = JSON.parse(mockLocalStorage.getItem('xibo_config'));
-      expect(stored.cmsUrl).toBe('https://manual.com');
-      expect(stored.cmsKey).toBe('manual-key');
+      const cmsId = computeCmsId('https://manual.com');
+      const cms = JSON.parse(mockLocalStorage.getItem(`xibo_cms:${cmsId}`));
+      expect(cms.cmsUrl).toBe('https://manual.com');
+      expect(cms.cmsKey).toBe('manual-key');
     });
 
     it('should auto-save when setters used', () => {
       config.cmsUrl = 'https://auto.com';
 
-      const stored = JSON.parse(mockLocalStorage.getItem('xibo_config'));
-      expect(stored.cmsUrl).toBe('https://auto.com');
+      const cmsId = computeCmsId('https://auto.com');
+      const cms = JSON.parse(mockLocalStorage.getItem(`xibo_cms:${cmsId}`));
+      expect(cms.cmsUrl).toBe('https://auto.com');
     });
   });
 
@@ -419,12 +451,12 @@ describe('Config', () => {
 
   describe('Edge Cases', () => {
     it('should handle missing hardwareKey in loaded config', () => {
-      mockLocalStorage.setItem('xibo_config', JSON.stringify({
+      seedConfig(mockLocalStorage, {
         cmsUrl: 'https://test.com',
         cmsKey: 'test-key',
         displayName: 'Test'
         // hardwareKey missing
-      }));
+      });
 
       config = new Config();
 
@@ -433,13 +465,13 @@ describe('Config', () => {
     });
 
     it('should handle null values in config', () => {
-      mockLocalStorage.setItem('xibo_config', JSON.stringify({
+      seedConfig(mockLocalStorage, {
         cmsUrl: null,
         cmsKey: null,
         displayName: null,
         hardwareKey: 'pwa-1234567812344567890123456789',
         xmrChannel: '12345678-1234-4567-8901-234567890abc'
-      }));
+      });
 
       config = new Config();
 
@@ -506,12 +538,12 @@ describe('Config', () => {
       expect(config.data.xmrPrivKey).toMatch(/^-----BEGIN PRIVATE KEY-----/);
     });
 
-    it('should persist keys to localStorage', async () => {
+    it('should persist keys to xibo_global', async () => {
       await config.ensureXmrKeyPair();
 
-      const stored = JSON.parse(mockLocalStorage.getItem('xibo_config'));
-      expect(stored.xmrPubKey).toMatch(/^-----BEGIN PUBLIC KEY-----/);
-      expect(stored.xmrPrivKey).toMatch(/^-----BEGIN PRIVATE KEY-----/);
+      const global = JSON.parse(mockLocalStorage.getItem('xibo_global'));
+      expect(global.xmrPubKey).toMatch(/^-----BEGIN PUBLIC KEY-----/);
+      expect(global.xmrPrivKey).toMatch(/^-----BEGIN PRIVATE KEY-----/);
     });
 
     it('should be idempotent — second call preserves existing keys', async () => {
@@ -579,4 +611,235 @@ describe('Config', () => {
       expect(config.xmrPrivKey).toMatch(/^-----BEGIN PRIVATE KEY-----/);
     });
   });
+
+  describe('warnPlatformMismatch()', () => {
+    let warnSpy;
+
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('should warn when Chromium-only key is used in Electron', () => {
+      warnPlatformMismatch({ browser: 'chrome', cmsUrl: 'https://test.com' }, 'electron');
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0][0]).toContain('browser');
+      expect(warnSpy.mock.calls[0][0]).toContain('chromium');
+    });
+
+    it('should warn when Electron-only key is used in Chromium', () => {
+      warnPlatformMismatch({ autoLaunch: true }, 'chromium');
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0][0]).toContain('autoLaunch');
+      expect(warnSpy.mock.calls[0][0]).toContain('electron');
+    });
+
+    it('should not warn for shared keys', () => {
+      warnPlatformMismatch({ kioskMode: true, cmsUrl: 'https://test.com' }, 'electron');
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not warn when config or platform is missing', () => {
+      warnPlatformMismatch(null, 'electron');
+      warnPlatformMismatch({ browser: 'chrome' }, '');
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should warn for multiple mismatched keys', () => {
+      warnPlatformMismatch({ browser: 'chrome', extraBrowserFlags: '--flag' }, 'electron');
+
+      expect(warnSpy).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Per-CMS Namespacing', () => {
+    describe('fnvHash()', () => {
+      it('should produce 12-char hex string', () => {
+        expect(fnvHash('test')).toMatch(/^[0-9a-f]{12}$/);
+      });
+
+      it('should be deterministic', () => {
+        expect(fnvHash('hello')).toBe(fnvHash('hello'));
+      });
+
+      it('should differ for different inputs', () => {
+        expect(fnvHash('hello')).not.toBe(fnvHash('world'));
+      });
+    });
+
+    describe('computeCmsId()', () => {
+      it('should produce hostname-hash format', () => {
+        const id = computeCmsId('https://displays.superpantalles.com');
+        expect(id).toMatch(/^displays\.superpantalles\.com-[0-9a-f]{12}$/);
+      });
+
+      it('should handle localhost with port', () => {
+        const id = computeCmsId('http://localhost:8080');
+        expect(id).toMatch(/^localhost-[0-9a-f]{12}$/);
+      });
+
+      it('should return null for empty URL', () => {
+        expect(computeCmsId('')).toBeNull();
+        expect(computeCmsId(null)).toBeNull();
+        expect(computeCmsId(undefined)).toBeNull();
+      });
+
+      it('should be deterministic for same URL', () => {
+        const id1 = computeCmsId('https://cms.example.com');
+        const id2 = computeCmsId('https://cms.example.com');
+        expect(id1).toBe(id2);
+      });
+
+      it('should differ for different URLs', () => {
+        const id1 = computeCmsId('https://cms1.example.com');
+        const id2 = computeCmsId('https://cms2.example.com');
+        expect(id1).not.toBe(id2);
+      });
+
+      it('should handle invalid URL gracefully', () => {
+        const id = computeCmsId('not-a-url');
+        expect(id).toMatch(/^unknown-[0-9a-f]{12}$/);
+      });
+    });
+
+    describe('activeCmsId', () => {
+      it('should return null when no CMS configured', () => {
+        config = new Config();
+        expect(config.activeCmsId).toBeNull();
+      });
+
+      it('should return CMS ID when configured', () => {
+        seedConfig(mockLocalStorage, {
+          cmsUrl: 'https://test.cms.com',
+          cmsKey: 'key',
+          displayName: 'Test',
+          hardwareKey: 'pwa-existinghardwarekey1234567',
+          xmrChannel: '12345678-1234-4567-8901-234567890abc',
+        });
+
+        config = new Config();
+        expect(config.activeCmsId).toBe(computeCmsId('https://test.cms.com'));
+      });
+    });
+
+    describe('switchCms()', () => {
+      it('should switch to a new CMS and preserve hardwareKey', () => {
+        seedConfig(mockLocalStorage, {
+          cmsUrl: 'https://cms1.com',
+          cmsKey: 'key1',
+          displayName: 'Display on CMS1',
+          hardwareKey: 'pwa-existinghardwarekey1234567',
+          xmrChannel: '12345678-1234-4567-8901-234567890abc',
+        });
+
+        config = new Config();
+        const hwKey = config.hardwareKey;
+
+        const result = config.switchCms('https://cms2.com');
+
+        expect(result.isNew).toBe(true);
+        expect(result.cmsId).toBe(computeCmsId('https://cms2.com'));
+        expect(config.hardwareKey).toBe(hwKey); // Same device identity
+        expect(config.cmsUrl).toBe('https://cms2.com');
+        expect(config.cmsKey).toBe(''); // New CMS, no key yet
+      });
+
+      it('should switch back to a previously known CMS', () => {
+        seedConfig(mockLocalStorage, {
+          cmsUrl: 'https://cms1.com',
+          cmsKey: 'key1',
+          displayName: 'Display on CMS1',
+          hardwareKey: 'pwa-existinghardwarekey1234567',
+          xmrChannel: '12345678-1234-4567-8901-234567890abc',
+        });
+
+        config = new Config();
+
+        // Switch to CMS2
+        config.switchCms('https://cms2.com');
+        config.cmsKey = 'key2';
+        config.displayName = 'Display on CMS2';
+
+        // Switch back to CMS1
+        const result = config.switchCms('https://cms1.com');
+
+        expect(result.isNew).toBe(false);
+        expect(config.cmsKey).toBe('key1');
+        expect(config.displayName).toBe('Display on CMS1');
+      });
+    });
+
+    describe('listCmsProfiles()', () => {
+      it('should list all CMS profiles', () => {
+        seedConfig(mockLocalStorage, {
+          cmsUrl: 'https://cms1.com',
+          cmsKey: 'key1',
+          displayName: 'Display 1',
+          hardwareKey: 'pwa-existinghardwarekey1234567',
+          xmrChannel: '12345678-1234-4567-8901-234567890abc',
+        });
+
+        config = new Config();
+        config.switchCms('https://cms2.com');
+        config.displayName = 'Display 2';
+        config.save();
+
+        const profiles = config.listCmsProfiles();
+
+        expect(profiles.length).toBe(2);
+        expect(profiles.find(p => p.cmsUrl === 'https://cms1.com')).toBeTruthy();
+        expect(profiles.find(p => p.cmsUrl === 'https://cms2.com')).toBeTruthy();
+        // Only one should be active
+        expect(profiles.filter(p => p.isActive).length).toBe(1);
+      });
+    });
+
+    describe('Split storage save/load', () => {
+      it('should write split keys on save', () => {
+        config = new Config();
+        config.data.cmsUrl = 'https://test.com';
+        config.data.cmsKey = 'k';
+        config.save();
+
+        // Global key should exist
+        expect(mockLocalStorage.getItem('xibo_global')).toBeTruthy();
+        // CMS key should exist
+        const cmsId = computeCmsId('https://test.com');
+        expect(mockLocalStorage.getItem(`xibo_cms:${cmsId}`)).toBeTruthy();
+
+        // Global should have hardwareKey, not cmsUrl
+        const global = JSON.parse(mockLocalStorage.getItem('xibo_global'));
+        expect(global.hardwareKey).toBeTruthy();
+        expect(global.cmsUrl).toBeUndefined();
+
+        // CMS should have cmsUrl, not hardwareKey
+        const cms = JSON.parse(mockLocalStorage.getItem(`xibo_cms:${cmsId}`));
+        expect(cms.cmsUrl).toBe('https://test.com');
+        expect(cms.hardwareKey).toBeUndefined();
+      });
+
+      it('should reload from split storage correctly', () => {
+        // Write config
+        config = new Config();
+        config.data.cmsUrl = 'https://reload.com';
+        config.data.cmsKey = 'reload-key';
+        config.data.displayName = 'Reload Test';
+        config.save();
+
+        // Reload
+        const config2 = new Config();
+        expect(config2.cmsUrl).toBe('https://reload.com');
+        expect(config2.cmsKey).toBe('reload-key');
+        expect(config2.displayName).toBe('Reload Test');
+        expect(config2.hardwareKey).toBe(config.hardwareKey);
+      });
+    });
+  });
 });

package/src/index.js

@@ -4,7 +4,7 @@ export const VERSION = pkg.version;
 export { createLogger, setLogLevel, getLogLevel, isDebug, applyCmsLogLevel, mapCmsLogLevel, registerLogSink, unregisterLogSink, LOG_LEVELS } from './logger.js';
 export { EventEmitter } from './event-emitter.js';
 import { config as _config } from './config.js';
-export { config, SHELL_ONLY_KEYS, extractPwaConfig } from './config.js';
+export { config, SHELL_ONLY_KEYS, extractPwaConfig, computeCmsId, fnvHash, warnPlatformMismatch } from './config.js';
 export { fetchWithRetry } from './fetch-retry.js';
 export { CmsApiClient, CmsApiError } from './cms-api.js';
 
@@ -12,14 +12,14 @@ export { CmsApiClient, CmsApiError } from './cms-api.js';
  * CMS Player API base path — all media, dependencies, and widgets are served
  * under this prefix.
  *
- * Default: '/api/v2/player' (standalone index.php endpoint).
+ * Default: '/player/api/v2' (standalone index.php endpoint).
  * Override: set `playerApiBase` in config.json / localStorage, or call
  *           setPlayerApi('/new/path') before route registration (proxy).
  *
  * Browser: reads from config.data.playerApiBase at import time.
  * Node:    call setPlayerApi() before createProxyApp().
  */
-const DEFAULT_PLAYER_API = '/api/v2/player';
+const DEFAULT_PLAYER_API = '/player/api/v2';
 let _playerApi = _config.data?.playerApiBase || DEFAULT_PLAYER_API;
 
 /** Current Player API base path (no trailing slash). */