@xiboplayer/sync 0.6.2 → 0.6.4

package/README.md

@@ -1,17 +1,44 @@
 # @xiboplayer/sync
 
-**Multi-display synchronization for Xibo video walls.**
+**Multi-display synchronization for Xibo video walls — same-machine and cross-device.**
 
 ## Overview
 
-BroadcastChannel-based lead/follower synchronization:
+Coordinates layout transitions and video playback across multiple displays:
 
-- **Lead election** — automatic leader selection among browser tabs/windows
-- **Synchronized playback** — video start coordinated across displays
-- **Layout sync** — all displays transition to the same layout simultaneously
-- **Stats/logs delegation** — follower tabs delegate proof-of-play stats and log submission to the sync lead via BroadcastChannel, avoiding duplicate CMS traffic in video wall setups
+- **Same-machine sync** (Phase 2) — BroadcastChannel for multi-tab/multi-window setups on a single device
+- **Cross-device sync** (Phase 3) — WebSocket relay for LAN video walls where each screen is a separate mini-PC
 
-Designed for video wall setups where multiple screens show synchronized content.
+Both modes share the same sync protocol — only the transport layer differs.
+
+### Capabilities
+
+- **Synchronized layout transitions** — lead signals followers to change layout, waits for all to be ready, then sends a simultaneous "show" signal
+- **Coordinated video start** — video playback begins at the same moment on all displays
+- **Stats/logs delegation** — followers delegate proof-of-play stats and log submission through the lead, avoiding duplicate CMS traffic
+- **Automatic follower discovery** — heartbeats every 5s, stale detection after 15s
+- **Graceful degradation** — if a follower is unresponsive, the lead proceeds after a 10s timeout
+- **Auto-reconnect** — WebSocket transport reconnects with exponential backoff (1s → 30s)
+
+## Architecture
+
+```
+Same-machine (BroadcastChannel):       Cross-device (WebSocket relay):
+
+  Tab 1 (Lead)    Tab 2 (Follower)      PC 1 (Lead)         PC 2 (Follower)
+  ┌──────────┐    ┌──────────┐          ┌──────────┐        ┌──────────┐
+  │SyncMgr   │    │SyncMgr   │          │SyncMgr   │        │SyncMgr   │
+  │ └─BC     │◄──►│ └─BC     │          │ └─WS     │        │ └─WS     │
+  └──────────┘    └──────────┘          └────┬─────┘        └────┬─────┘
+       BroadcastChannel                      │                    │
+                                             ▼                    │
+                                      ┌────────────┐             │
+                                      │Proxy :8765 │◄────────────┘
+                                      │ └─SyncRelay│  (LAN WebSocket)
+                                      └────────────┘
+```
+
+The relay is a dumb pipe — it broadcasts each message to all other connected clients. The sync protocol (heartbeats, ready-waits, layout changes) runs entirely in SyncManager.
 
 ## Installation
 
@@ -21,13 +48,170 @@ npm install @xiboplayer/sync
 
 ## Usage
 
+### Same-machine sync (default)
+
+No extra configuration needed. When multiple tabs/windows run on the same origin, BroadcastChannel handles message passing automatically.
+
 ```javascript
 import { SyncManager } from '@xiboplayer/sync';
 
-const sync = new SyncManager({ displayId: 'screen-1' });
-sync.on('layout-sync', ({ layoutId }) => renderer.show(layoutId));
-sync.init();
+// Lead display
+const lead = new SyncManager({
+  displayId: 'screen-1',
+  syncConfig: { isLead: true, syncGroup: 'lead', syncSwitchDelay: 750 },
+  onLayoutShow: (layoutId) => renderer.show(layoutId),
+});
+lead.start();
+
+// Request synchronized layout change (waits for followers)
+await lead.requestLayoutChange('42');
+```
+
+```javascript
+// Follower display (different tab)
+const follower = new SyncManager({
+  displayId: 'screen-2',
+  syncConfig: { isLead: false, syncGroup: '192.168.1.100', syncSwitchDelay: 750 },
+  onLayoutChange: async (layoutId) => {
+    await renderer.prepareLayout(layoutId);
+    follower.reportReady(layoutId);
+  },
+  onLayoutShow: (layoutId) => renderer.show(layoutId),
+});
+follower.start();
+```
+
+### Cross-device sync (LAN video wall)
+
+When `syncGroup` is an IP address (not `"lead"`) and `syncPublisherPort` is set, the PWA automatically builds a WebSocket relay URL. The lead connects to its own proxy at `ws://localhost:<port>/sync`; followers connect to `ws://<lead-ip>:<port>/sync`.
+
+**Lead config.json** (e.g. `~/.config/xiboplayer/electron/config.json`):
+
+```json
+{
+  "cmsUrl": "https://cms.example.com",
+  "cmsKey": "yourKey",
+  "displayName": "videowall-lead",
+  "listenAddress": "0.0.0.0"
+}
+```
+
+The `listenAddress: "0.0.0.0"` makes the proxy reachable from the LAN. The CMS sync settings (`syncGroup`, `syncPublisherPort`) are sent via the RegisterDisplay response.
+
+**CMS Display Settings:**
+
+| Setting | Lead | Follower |
+|---------|------|----------|
+| Sync Group | `lead` | `192.168.1.100` (lead's IP) |
+| Sync Publisher Port | `8765` | `8765` |
+
+The SyncManager detects this configuration and selects the WebSocket transport:
+
+```javascript
+// This happens automatically in packages/pwa/src/main.ts:
+if (syncConfig.syncPublisherPort && syncConfig.syncGroup !== 'lead') {
+  const host = syncConfig.isLead ? 'localhost' : syncConfig.syncGroup;
+  syncConfig.relayUrl = `ws://${host}:${syncConfig.syncPublisherPort}/sync`;
+}
+```
+
+### Injecting a custom transport
+
+For testing or custom setups, you can inject any object that implements the transport interface:
+
+```javascript
+const transport = {
+  send(msg) { /* ... */ },
+  onMessage(callback) { /* ... */ },
+  close() { /* ... */ },
+  get connected() { return true; },
+};
+
+const sync = new SyncManager({
+  displayId: 'test-1',
+  syncConfig: { isLead: true },
+  transport,
+});
+sync.start();
+```
+
+## Transport Interface
+
+Both `BroadcastChannelTransport` and `WebSocketTransport` implement:
+
+```typescript
+interface SyncTransport {
+  send(msg: any): void;           // Send message to peers
+  onMessage(cb: (msg) => void);   // Register message handler
+  close(): void;                   // Clean up resources
+  readonly connected: boolean;     // Connection status
+}
+```
+
+## Sync Protocol
+
 ```
+Lead                              Follower(s)
+────                              ──────────
+heartbeat (every 5s)            → discovers peers
+layout-change(layoutId, showAt) → loads layout, prepares DOM
+                                ← layout-ready(layoutId, displayId)
+(waits for all or timeout 10s)
+layout-show(layoutId)           → shows layout simultaneously
+video-start(layoutId, regionId) → unpauses video
+stats-report / logs-report      ← delegates stats to lead
+stats-ack / logs-ack            → confirms submission
+```
+
+## Example: 4-screen video wall
+
+```
+┌─────────────┬─────────────┐
+│ Screen 1    │ Screen 2    │
+│ (LEAD)      │ (follower)  │
+│ 192.168.1.10│ 192.168.1.11│
+├─────────────┼─────────────┤
+│ Screen 3    │ Screen 4    │
+│ (follower)  │ (follower)  │
+│ 192.168.1.12│ 192.168.1.13│
+└─────────────┴─────────────┘
+```
+
+**CMS setup:** Create 4 displays. Set Screen 1's sync group to `lead`. Set Screens 2-4's sync group to `192.168.1.10`. Set sync publisher port to `8765` on all four.
+
+**Screen 1 config.json:** Add `"listenAddress": "0.0.0.0"` so the proxy listens on all interfaces.
+
+All four screens run the same Electron/Chromium player. The lead drives layout transitions; followers load content in parallel and show simultaneously when all are ready.
+
+## API
+
+### `new SyncManager(options)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `displayId` | string | This display's unique hardware key |
+| `syncConfig` | SyncConfig | Sync configuration from CMS RegisterDisplay |
+| `transport` | SyncTransport? | Optional pre-built transport (for testing) |
+| `onLayoutChange` | Function? | Called when lead requests layout change |
+| `onLayoutShow` | Function? | Called when lead gives show signal |
+| `onVideoStart` | Function? | Called when lead gives video start signal |
+| `onStatsReport` | Function? | (Lead) Called when follower sends stats |
+| `onLogsReport` | Function? | (Lead) Called when follower sends logs |
+| `onStatsAck` | Function? | (Follower) Called when lead confirms stats |
+| `onLogsAck` | Function? | (Follower) Called when lead confirms logs |
+
+### Methods
+
+| Method | Role | Description |
+|--------|------|-------------|
+| `start()` | Both | Opens transport, begins heartbeats |
+| `stop()` | Both | Closes transport, clears timers |
+| `requestLayoutChange(layoutId)` | Lead | Sends layout-change, waits for ready, sends show |
+| `requestVideoStart(layoutId, regionId)` | Lead | Signals synchronized video start |
+| `reportReady(layoutId)` | Follower | Reports layout is loaded and ready |
+| `reportStats(statsXml)` | Follower | Delegates stats submission to lead |
+| `reportLogs(logsXml)` | Follower | Delegates logs submission to lead |
+| `getStatus()` | Both | Returns sync status including follower details |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/sync",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Multi-display synchronization for Xibo Player",
   "type": "module",
   "main": "src/sync-manager.js",
@@ -12,7 +12,7 @@
     }
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.6.2"
+    "@xiboplayer/utils": "0.6.4"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/bc-transport.js

@@ -0,0 +1,51 @@
+/**
+ * BroadcastChannelTransport — same-machine sync transport
+ *
+ * Wraps the browser BroadcastChannel API behind the sync transport interface.
+ * Used for multi-tab / multi-window sync on a single device.
+ *
+ * Transport interface: { send(msg), onMessage(callback), close(), get connected() }
+ */
+
+const DEFAULT_CHANNEL = 'xibo-sync';
+
+export class BroadcastChannelTransport {
+  /**
+   * @param {string} [channelName='xibo-sync']
+   */
+  constructor(channelName = DEFAULT_CHANNEL) {
+    this.channel = new BroadcastChannel(channelName);
+    this._connected = true;
+  }
+
+  /**
+   * Send a message to all other tabs/windows on this channel.
+   * @param {Object} msg — plain object (structured-cloned by BroadcastChannel)
+   */
+  send(msg) {
+    if (!this.channel) return;
+    this.channel.postMessage(msg);
+  }
+
+  /**
+   * Register a callback for incoming messages.
+   * @param {Function} callback — receives the message data (already deserialized)
+   */
+  onMessage(callback) {
+    this.channel.onmessage = (e) => callback(e.data);
+  }
+
+  /** Close the channel. */
+  close() {
+    if (this.channel) {
+      this.channel.close();
+      this.channel = null;
+    }
+    this._connected = false;
+  }
+
+  /** @returns {boolean} Whether the channel is open */
+  get connected() {
+    return this._connected && !!this.channel;
+  }
+}

package/src/index.d.ts

@@ -1,22 +1,79 @@
 export const VERSION: string;
 
+export interface SyncTransport {
+  send(msg: any): void;
+  onMessage(callback: (msg: any) => void): void;
+  close(): void;
+  readonly connected: boolean;
+}
+
 export interface SyncConfig {
   syncGroup: string;
   syncPublisherPort: number;
   syncSwitchDelay: number;
   syncVideoPauseDelay: number;
   isLead: boolean;
+  relayUrl?: string;
+}
+
+export class BroadcastChannelTransport implements SyncTransport {
+  constructor(channelName?: string);
+  send(msg: any): void;
+  onMessage(callback: (msg: any) => void): void;
+  close(): void;
+  readonly connected: boolean;
+}
+
+export class WebSocketTransport implements SyncTransport {
+  constructor(url: string);
+  send(msg: any): void;
+  onMessage(callback: (msg: any) => void): void;
+  close(): void;
+  readonly connected: boolean;
 }
 
 export class SyncManager {
-  constructor(config: SyncConfig, displayId: string);
-  config: SyncConfig;
+  constructor(options: {
+    displayId: string;
+    syncConfig: SyncConfig;
+    transport?: SyncTransport;
+    onLayoutChange?: (layoutId: string, showAt: number) => void;
+    onLayoutShow?: (layoutId: string) => void;
+    onVideoStart?: (layoutId: string, regionId: string) => void;
+    onStatsReport?: (followerId: string, statsXml: string, ack: () => void) => void;
+    onLogsReport?: (followerId: string, logsXml: string, ack: () => void) => void;
+    onStatsAck?: (targetDisplayId: string) => void;
+    onLogsAck?: (targetDisplayId: string) => void;
+  });
+
+  displayId: string;
+  syncConfig: SyncConfig;
   isLead: boolean;
+  transport: SyncTransport | null;
+  /** Backward-compatible alias for transport */
+  channel: SyncTransport | null;
+  followers: Map<string, any>;
 
   start(): void;
   stop(): void;
-  requestLayoutChange(layoutId: number, showDelay?: number): void;
-  notifyLayoutReady(layoutId: number): void;
-  onLayoutShow(callback: (layoutId: number) => void): void;
-  onLayoutChange(callback: (layoutId: number) => void): void;
+  requestLayoutChange(layoutId: string | number): Promise<void>;
+  requestVideoStart(layoutId: string | number, regionId: string): Promise<void>;
+  reportReady(layoutId: string | number): void;
+  reportStats(statsXml: string): void;
+  reportLogs(logsXml: string): void;
+  getStatus(): {
+    started: boolean;
+    isLead: boolean;
+    displayId: string;
+    followers: number;
+    pendingLayoutId: string | null;
+    transport: 'websocket' | 'broadcast-channel';
+    followerDetails: Array<{
+      displayId: string;
+      lastSeen: number;
+      ready: boolean;
+      readyLayoutId: string | null;
+      stale: boolean;
+    }>;
+  };
 }

package/src/sync-manager.js

@@ -1,8 +1,9 @@
 /**
- * SyncManager - Multi-display synchronization via BroadcastChannel
+ * SyncManager - Multi-display synchronization
  *
  * Coordinates layout transitions across multiple browser tabs/windows
- * on the same machine (video wall, multi-monitor setups).
+ * (same machine via BroadcastChannel) or across devices on a LAN
+ * (via WebSocket relay on the lead's proxy server).
  *
  * Protocol:
  *   Lead                              Follower(s)
@@ -17,21 +18,28 @@
  *   Lead tracks active followers. If a follower goes silent for 15s,
  *   it's considered offline and excluded from ready-wait.
  *
+ * Transport:
+ *   Pluggable — BroadcastChannelTransport (same-machine) or
+ *   WebSocketTransport (cross-device via relay). Selected automatically
+ *   based on syncConfig.relayUrl.
+ *
  * @module @xiboplayer/sync
  */
 
 /**
  * @typedef {Object} SyncConfig
  * @property {string} syncGroup - "lead" or leader's LAN IP
- * @property {number} syncPublisherPort - TCP port (unused in browser, kept for compat)
+ * @property {number} syncPublisherPort - TCP port (used for WebSocket relay URL)
  * @property {number} syncSwitchDelay - Delay in ms before showing new content
  * @property {number} syncVideoPauseDelay - Delay in ms before unpausing video
  * @property {boolean} isLead - Whether this display is the leader
+ * @property {string} [relayUrl] - WebSocket relay URL for cross-device sync
  */
 
 import { createLogger } from '@xiboplayer/utils';
+import { BroadcastChannelTransport } from './bc-transport.js';
+import { WebSocketTransport } from './ws-transport.js';
 
-const CHANNEL_NAME = 'xibo-sync';
 const HEARTBEAT_INTERVAL = 5000;   // Send heartbeat every 5s
 const FOLLOWER_TIMEOUT = 15000;    // Consider follower offline after 15s silence
 const READY_TIMEOUT = 10000;       // Max wait for followers to be ready
@@ -41,6 +49,7 @@ export class SyncManager {
    * @param {Object} options
    * @param {string} options.displayId - This display's unique hardware key
    * @param {SyncConfig} options.syncConfig - Sync configuration from RegisterDisplay
+   * @param {Object} [options.transport] - Optional pre-built transport (for testing)
    * @param {Function} [options.onLayoutChange] - Called when lead requests layout change
    * @param {Function} [options.onLayoutShow] - Called when lead gives show signal
    * @param {Function} [options.onVideoStart] - Called when lead gives video start signal
@@ -66,7 +75,7 @@ export class SyncManager {
     this.onLogsAck = options.onLogsAck || null;
 
     // State
-    this.channel = null;
+    this.transport = options.transport || null;
     this.followers = new Map();      // displayId → { lastSeen, ready }
     this._heartbeatTimer = null;
     this._cleanupTimer = null;
@@ -79,20 +88,30 @@ export class SyncManager {
     this._log = createLogger(this.isLead ? 'Sync:LEAD' : 'Sync:FOLLOW');
   }
 
+  /** Backward-compatible alias for transport */
+  get channel() { return this.transport; }
+  set channel(v) { this.transport = v; }
+
   /**
-   * Start the sync manager (opens BroadcastChannel, begins heartbeats)
+   * Start the sync manager — selects transport, begins heartbeats.
    */
   start() {
     if (this._started) return;
     this._started = true;
 
-    if (typeof BroadcastChannel === 'undefined') {
-      this._log.warn( 'BroadcastChannel not available — sync disabled');
-      return;
+    // Select transport if none injected
+    if (!this.transport) {
+      if (this.syncConfig.relayUrl) {
+        this.transport = new WebSocketTransport(this.syncConfig.relayUrl);
+      } else if (typeof BroadcastChannel !== 'undefined') {
+        this.transport = new BroadcastChannelTransport();
+      } else {
+        this._log.warn('No transport available — sync disabled');
+        return;
+      }
     }
 
-    this.channel = new BroadcastChannel(CHANNEL_NAME);
-    this.channel.onmessage = (event) => this._handleMessage(event.data);
+    this.transport.onMessage((msg) => this._handleMessage(msg));
 
     // Start heartbeat
     this._heartbeatTimer = setInterval(() => this._sendHeartbeat(), HEARTBEAT_INTERVAL);
@@ -103,7 +122,8 @@ export class SyncManager {
       this._cleanupTimer = setInterval(() => this._cleanupStaleFollowers(), HEARTBEAT_INTERVAL);
     }
 
-    this._log.info( 'Started. DisplayId:', this.displayId);
+    this._log.info('Started. DisplayId:', this.displayId,
+      this.syncConfig.relayUrl ? `(relay: ${this.syncConfig.relayUrl})` : '(BroadcastChannel)');
   }
 
   /**
@@ -121,13 +141,13 @@ export class SyncManager {
       clearInterval(this._cleanupTimer);
       this._cleanupTimer = null;
     }
-    if (this.channel) {
-      this.channel.close();
-      this.channel = null;
+    if (this.transport) {
+      this.transport.close();
+      this.transport = null;
     }
 
     this.followers.clear();
-    this._log.info( 'Stopped');
+    this._log.info('Stopped');
   }
 
   // ── Lead API ──────────────────────────────────────────────────────
@@ -141,7 +161,7 @@ export class SyncManager {
    */
   async requestLayoutChange(layoutId) {
     if (!this.isLead) {
-      this._log.warn( 'requestLayoutChange called on follower — ignoring');
+      this._log.warn('requestLayoutChange called on follower — ignoring');
       return;
     }
 
@@ -156,7 +176,7 @@ export class SyncManager {
 
     const showAt = Date.now() + this.switchDelay;
 
-    this._log.info( `Requesting layout change: ${layoutId} (show at ${new Date(showAt).toISOString()}, ${this.followers.size} followers)`);
+    this._log.info(`Requesting layout change: ${layoutId} (show at ${new Date(showAt).toISOString()}, ${this.followers.size} followers)`);
 
     // Broadcast layout-change to all followers
     this._send({
@@ -178,7 +198,7 @@ export class SyncManager {
     }
 
     // Send show signal
-    this._log.info( `Sending layout-show: ${layoutId}`);
+    this._log.info(`Sending layout-show: ${layoutId}`);
     this._send({
       type: 'layout-show',
       layoutId,
@@ -225,7 +245,7 @@ export class SyncManager {
   reportReady(layoutId) {
     layoutId = String(layoutId);
 
-    this._log.info( `Reporting ready for layout ${layoutId}`);
+    this._log.info(`Reporting ready for layout ${layoutId}`);
 
     this._send({
       type: 'layout-ready',
@@ -283,7 +303,7 @@ export class SyncManager {
       case 'layout-change':
         // Follower: lead is requesting a layout change
         if (!this.isLead) {
-          this._log.info( `Layout change requested: ${msg.layoutId}`);
+          this._log.info(`Layout change requested: ${msg.layoutId}`);
           this.onLayoutChange(msg.layoutId, msg.showAt);
         }
         break;
@@ -298,7 +318,7 @@ export class SyncManager {
       case 'layout-show':
         // Follower: lead says show now
         if (!this.isLead) {
-          this._log.info( `Layout show signal: ${msg.layoutId}`);
+          this._log.info(`Layout show signal: ${msg.layoutId}`);
           this.onLayoutShow(msg.layoutId);
         }
         break;
@@ -306,7 +326,7 @@ export class SyncManager {
       case 'video-start':
         // Follower: lead says start video
         if (!this.isLead) {
-          this._log.info( `Video start signal: ${msg.layoutId} region ${msg.regionId}`);
+          this._log.info(`Video start signal: ${msg.layoutId} region ${msg.regionId}`);
           this.onVideoStart(msg.layoutId, msg.regionId);
         }
         break;
@@ -344,7 +364,7 @@ export class SyncManager {
         break;
 
       default:
-        this._log.warn( 'Unknown message type:', msg.type);
+        this._log.warn('Unknown message type:', msg.type);
     }
   }
 
@@ -361,7 +381,7 @@ export class SyncManager {
         readyLayoutId: null,
         role: msg.role || 'unknown',
       });
-      this._log.info( `Follower joined: ${msg.displayId} (${this.followers.size} total)`);
+      this._log.info(`Follower joined: ${msg.displayId} (${this.followers.size} total)`);
     }
   }
 
@@ -381,12 +401,12 @@ export class SyncManager {
       follower.lastSeen = Date.now();
     }
 
-    this._log.info( `Follower ${msg.displayId} ready for layout ${msg.layoutId}`);
+    this._log.info(`Follower ${msg.displayId} ready for layout ${msg.layoutId}`);
 
     // Check if all followers are now ready
     if (this._pendingLayoutId === msg.layoutId && this._readyResolve) {
       if (this._allFollowersReady(msg.layoutId)) {
-        this._log.info( 'All followers ready');
+        this._log.info('All followers ready');
         this._readyResolve();
         this._readyResolve = null;
       }
@@ -425,7 +445,7 @@ export class SyncManager {
               notReady.push(id);
             }
           }
-          this._log.warn( `Ready timeout — proceeding without: ${notReady.join(', ')}`);
+          this._log.warn(`Ready timeout — proceeding without: ${notReady.join(', ')}`);
           this._readyResolve = null;
           resolve();
         }
@@ -450,7 +470,7 @@ export class SyncManager {
     const now = Date.now();
     for (const [id, follower] of this.followers) {
       if (now - follower.lastSeen > FOLLOWER_TIMEOUT) {
-        this._log.info( `Removing stale follower: ${id} (last seen ${Math.round((now - follower.lastSeen) / 1000)}s ago)`);
+        this._log.info(`Removing stale follower: ${id} (last seen ${Math.round((now - follower.lastSeen) / 1000)}s ago)`);
         this.followers.delete(id);
       }
     }
@@ -458,11 +478,11 @@ export class SyncManager {
 
   /** @private */
   _send(msg) {
-    if (!this.channel) return;
+    if (!this.transport) return;
     try {
-      this.channel.postMessage(msg);
+      this.transport.send(msg);
     } catch (e) {
-      this._log.error( 'Failed to send:', e);
+      this._log.error('Failed to send:', e);
     }
   }
 
@@ -479,6 +499,7 @@ export class SyncManager {
       displayId: this.displayId,
       followers: this.followers.size,
       pendingLayoutId: this._pendingLayoutId,
+      transport: this.syncConfig.relayUrl ? 'websocket' : 'broadcast-channel',
       followerDetails: Array.from(this.followers.entries()).map(([id, f]) => ({
         displayId: id,
         lastSeen: f.lastSeen,
@@ -489,3 +510,6 @@ export class SyncManager {
     };
   }
 }
+
+export { BroadcastChannelTransport } from './bc-transport.js';
+export { WebSocketTransport } from './ws-transport.js';

package/src/sync-manager.test.js

@@ -1,11 +1,12 @@
 /**
  * SyncManager unit tests
  *
- * Tests multi-display sync coordination via BroadcastChannel.
- * Uses a simple BroadcastChannel mock for Node.js environment.
+ * Tests multi-display sync coordination via pluggable transports.
+ * Uses a simple BroadcastChannel mock for the default transport path
+ * and a mock transport for the transport-injection path.
  */
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { SyncManager } from './sync-manager.js';
+import { SyncManager, BroadcastChannelTransport, WebSocketTransport } from './sync-manager.js';
 
 // ── BroadcastChannel mock ──────────────────────────────────────────
 // Simulates same-origin message passing between instances
@@ -51,6 +52,24 @@ class MockBroadcastChannel {
 // Install mock globally
 globalThis.BroadcastChannel = MockBroadcastChannel;
 
+// ── Mock Transport (for transport-injection tests) ──────────────────
+class MockTransport {
+  constructor() {
+    this._callback = null;
+    this._sent = [];
+    this._connected = true;
+  }
+  send(msg) { this._sent.push(msg); }
+  onMessage(callback) { this._callback = callback; }
+  close() { this._connected = false; }
+  get connected() { return this._connected; }
+
+  /** Simulate receiving a message from remote */
+  _receive(msg) {
+    if (this._callback) this._callback(msg);
+  }
+}
+
 // ── Helper to flush microtasks ──────────────────────────────────────
 const tick = (ms = 10) => new Promise(r => setTimeout(r, ms));
 
@@ -100,7 +119,7 @@ describe('SyncManager', () => {
       expect(follower1.isLead).toBe(false);
     });
 
-    it('should start and open BroadcastChannel', () => {
+    it('should start and open BroadcastChannel transport', () => {
       lead = new SyncManager({
         displayId: 'pwa-lead',
         syncConfig: makeSyncConfig(true),
@@ -108,10 +127,11 @@ describe('SyncManager', () => {
       lead.start();
 
       expect(lead.channel).not.toBeNull();
+      expect(lead.transport).not.toBeNull();
       expect(lead.getStatus().started).toBe(true);
     });
 
-    it('should stop and close BroadcastChannel', () => {
+    it('should stop and close transport', () => {
       lead = new SyncManager({
         displayId: 'pwa-lead',
         syncConfig: makeSyncConfig(true),
@@ -120,10 +140,73 @@ describe('SyncManager', () => {
       lead.stop();
 
       expect(lead.channel).toBeNull();
+      expect(lead.transport).toBeNull();
       expect(lead.getStatus().started).toBe(false);
     });
   });
 
+  describe('Transport injection', () => {
+    it('should use injected transport instead of BroadcastChannel', () => {
+      const transport = new MockTransport();
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+        transport,
+      });
+      lead.start();
+
+      expect(lead.transport).toBe(transport);
+      // Should have sent initial heartbeat
+      expect(transport._sent.length).toBe(1);
+      expect(transport._sent[0].type).toBe('heartbeat');
+    });
+
+    it('should handle messages from injected transport', () => {
+      const onLayoutChange = vi.fn();
+      const transport = new MockTransport();
+
+      follower1 = new SyncManager({
+        displayId: 'pwa-f1',
+        syncConfig: makeSyncConfig(false),
+        transport,
+        onLayoutChange,
+      });
+      follower1.start();
+
+      // Simulate a layout-change message from lead
+      transport._receive({
+        type: 'layout-change',
+        layoutId: '42',
+        showAt: Date.now() + 1000,
+        displayId: 'pwa-lead',
+      });
+
+      expect(onLayoutChange).toHaveBeenCalledWith('42', expect.any(Number));
+    });
+
+    it('should report websocket transport type in status when relayUrl set', () => {
+      const transport = new MockTransport();
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: { ...makeSyncConfig(true), relayUrl: 'ws://localhost:8765/sync' },
+        transport,
+      });
+      lead.start();
+
+      expect(lead.getStatus().transport).toBe('websocket');
+    });
+
+    it('should report broadcast-channel transport type by default', () => {
+      lead = new SyncManager({
+        displayId: 'pwa-lead',
+        syncConfig: makeSyncConfig(true),
+      });
+      lead.start();
+
+      expect(lead.getStatus().transport).toBe('broadcast-channel');
+    });
+  });
+
   describe('Heartbeat', () => {
     it('should discover followers via heartbeat', async () => {
       lead = new SyncManager({

package/src/ws-transport.js

@@ -0,0 +1,125 @@
+/**
+ * WebSocketTransport — cross-device sync transport
+ *
+ * Connects to the lead player's proxy WebSocket relay at /sync.
+ * Used for LAN video walls where each screen is a separate device.
+ *
+ * Features:
+ * - Auto-reconnect with exponential backoff (1s → 2s → 4s → max 30s)
+ * - JSON serialization (WebSocket sends strings, not structured clones)
+ * - Same transport interface as BroadcastChannelTransport
+ *
+ * Transport interface: { send(msg), onMessage(callback), close(), get connected() }
+ */
+
+import { createLogger } from '@xiboplayer/utils';
+
+const INITIAL_RETRY_MS = 1000;
+const MAX_RETRY_MS = 30000;
+const BACKOFF_FACTOR = 2;
+
+export class WebSocketTransport {
+  /**
+   * @param {string} url — WebSocket URL, e.g. ws://192.168.1.100:8765/sync
+   */
+  constructor(url) {
+    this._url = url;
+    this._callback = null;
+    this._closed = false;
+    this._retryMs = INITIAL_RETRY_MS;
+    this._retryTimer = null;
+    this._log = createLogger('WS-Sync');
+    this.ws = null;
+
+    this._connect();
+  }
+
+  /**
+   * Send a message to the relay (which broadcasts to other clients).
+   * @param {Object} msg — plain object (JSON-serialized for WebSocket)
+   */
+  send(msg) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  /**
+   * Register a callback for incoming messages.
+   * @param {Function} callback — receives the parsed message object
+   */
+  onMessage(callback) {
+    this._callback = callback;
+  }
+
+  /** Close the connection and stop reconnecting. */
+  close() {
+    this._closed = true;
+    if (this._retryTimer) {
+      clearTimeout(this._retryTimer);
+      this._retryTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /** @returns {boolean} Whether the WebSocket is open */
+  get connected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /** @private */
+  _connect() {
+    if (this._closed) return;
+
+    try {
+      this.ws = new WebSocket(this._url);
+    } catch (e) {
+      this._log.error('WebSocket creation failed:', e.message);
+      this._scheduleReconnect();
+      return;
+    }
+
+    this.ws.onopen = () => {
+      this._log.info(`Connected to ${this._url}`);
+      this._retryMs = INITIAL_RETRY_MS; // Reset backoff on success
+    };
+
+    this.ws.onmessage = (event) => {
+      if (!this._callback) return;
+      try {
+        const msg = JSON.parse(event.data);
+        this._callback(msg);
+      } catch (e) {
+        this._log.warn('Failed to parse message:', e.message);
+      }
+    };
+
+    this.ws.onclose = () => {
+      if (!this._closed) {
+        this._log.info('Connection closed — will reconnect');
+        this._scheduleReconnect();
+      }
+    };
+
+    this.ws.onerror = (e) => {
+      // onclose will fire after onerror, triggering reconnect
+      this._log.warn('WebSocket error');
+    };
+  }
+
+  /** @private */
+  _scheduleReconnect() {
+    if (this._closed || this._retryTimer) return;
+
+    this._log.info(`Reconnecting in ${this._retryMs}ms...`);
+    this._retryTimer = setTimeout(() => {
+      this._retryTimer = null;
+      this._connect();
+    }, this._retryMs);
+
+    this._retryMs = Math.min(this._retryMs * BACKOFF_FACTOR, MAX_RETRY_MS);
+  }
+}

package/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+  },
+});