@xiboplayer/sync 0.6.12 → 0.7.0

package/README.md

@@ -1,21 +1,25 @@
 # @xiboplayer/sync
 
-**Multi-display synchronization for Xibo video walls — same-machine and cross-device.**
+**Multi-display synchronization for Xibo video walls — same-machine and cross-device. New in v0.7.0.**
 
 ## Overview
 
-Coordinates layout transitions and video playback across multiple displays:
+Coordinates layout transitions and video playback across multiple displays with <8ms precision:
 
-- **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
+- **Cross-device sync** — WebSocket relay for LAN video walls where each screen is a separate device
+- **Same-machine sync** — BroadcastChannel for multi-tab/multi-window setups on a single device
 
 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
+- **12 choreography effects** — diagonal cascade, wave sweep, center-out, and more for dramatic transition patterns
 - **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
+- **Token authentication** — shared CMS key secures the WebSocket relay
+- **Sync group isolation** — multiple sync groups can share the same relay via `syncGroupId`
+- **Offline LAN sync** — persisted config enables sync without CMS connectivity
 - **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)

package/examples/test-multi-display.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * Multi-Display Sync Demo — test all sync features locally
+ *
+ * Starts a relay + simulates 4 displays in a 2×2 grid with choreography.
+ * Demonstrates: group isolation, wall mode (layoutMap), topology,
+ * auto-detected totalDisplays, and transition choreography.
+ *
+ * Usage:
+ *   node packages/sync/examples/test-multi-display.js
+ *
+ * What it does:
+ *   1. Starts a standalone relay on port 9590
+ *   2. Creates 4 SyncManager instances (1 lead + 3 followers)
+ *   3. All join group "lobby" with 2×2 topology
+ *   4. Lead requests layout changes — followers sync
+ *   5. Choreography staggers are computed and logged
+ *   6. Wall mode maps lead's layout to position-specific layouts
+ */
+
+import http from 'node:http';
+import { attachSyncRelay } from '../../proxy/src/sync-relay.js';
+import { SyncManager } from '../src/sync-manager.js';
+import { WebSocketTransport } from '../src/ws-transport.js';
+import { computeStagger } from '../src/choreography.js';
+
+const PORT = 9590;
+const RELAY_URL = `ws://127.0.0.1:${PORT}/sync`;
+
+// ── Display configs ──────────────────────────────────────────────
+const displays = [
+  {
+    id: 'display-lead',
+    isLead: true,
+    topology: { x: 0, y: 0, orientation: 0 },
+    layoutMap: null, // lead plays the original layout
+  },
+  {
+    id: 'display-top-right',
+    isLead: false,
+    topology: { x: 1, y: 0, orientation: 0 },
+    layoutMap: { '100': 201 }, // wall mode: lead's 100 → this display's 201
+  },
+  {
+    id: 'display-bottom-left',
+    isLead: false,
+    topology: { x: 0, y: 1, orientation: 90 }, // portrait totem
+    layoutMap: { '100': 202 },
+  },
+  {
+    id: 'display-bottom-right',
+    isLead: false,
+    topology: { x: 1, y: 1, orientation: 0 },
+    layoutMap: { '100': 203 },
+  },
+];
+
+const CHOREOGRAPHY = 'diagonal-tl';
+const STAGGER_MS = 200;
+const GRID_COLS = 2;
+const GRID_ROWS = 2;
+
+// ── Start relay ──────────────────────────────────────────────────
+const server = http.createServer((_req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ service: 'test-relay', status: 'ok' }));
+});
+attachSyncRelay(server);
+
+server.listen(PORT, async () => {
+  console.log(`\n🔄 Relay running on ws://127.0.0.1:${PORT}/sync\n`);
+
+  // Wait for server to be ready
+  await sleep(200);
+
+  // ── Create SyncManagers ──────────────────────────────────────
+  const managers = [];
+
+  for (const display of displays) {
+    const syncConfig = {
+      syncGroup: 'lobby',
+      syncPublisherPort: PORT,
+      syncSwitchDelay: 500,
+      syncVideoPauseDelay: 100,
+      isLead: display.isLead,
+      relayUrl: RELAY_URL,
+      topology: display.topology,
+      layoutMap: display.layoutMap,
+      choreography: CHOREOGRAPHY,
+      staggerMs: STAGGER_MS,
+      gridCols: GRID_COLS,
+      gridRows: GRID_ROWS,
+    };
+
+    const transport = new WebSocketTransport(RELAY_URL, {
+      syncGroup: 'lobby',
+      displayId: display.id,
+      topology: display.topology,
+    });
+
+    const manager = new SyncManager({
+      displayId: display.id,
+      syncConfig,
+      transport,
+      onLayoutChange: (layoutId) => {
+        // Wall mode: map lead's layout to position-specific
+        const mapped = display.layoutMap?.[layoutId] ?? layoutId;
+        const tag = mapped !== layoutId ? ` (wall: ${layoutId}→${mapped})` : '';
+        console.log(`  📺 ${display.id}: Loading layout ${mapped}${tag}`);
+
+        // Simulate load time
+        setTimeout(() => {
+          manager.reportReady(layoutId);
+          console.log(`  ✅ ${display.id}: Ready`);
+        }, 100 + Math.random() * 200);
+      },
+      onLayoutShow: (layoutId) => {
+        const stagger = computeStagger({
+          choreography: CHOREOGRAPHY,
+          topology: display.topology,
+          gridCols: GRID_COLS,
+          gridRows: GRID_ROWS,
+          staggerMs: STAGGER_MS,
+        });
+        console.log(`  🎬 ${display.id}: Show layout ${layoutId} (delay: ${stagger}ms, ${CHOREOGRAPHY})`);
+      },
+      onVideoStart: (layoutId, regionId) => {
+        console.log(`  ▶️  ${display.id}: Video start in layout ${layoutId} region ${regionId}`);
+      },
+      onGroupUpdate: (totalDisplays, topology) => {
+        console.log(`  📡 ${display.id}: Group update — ${totalDisplays} displays, topology:`, JSON.stringify(topology));
+      },
+    });
+
+    manager.start();
+    managers.push({ display, manager });
+    console.log(`${display.isLead ? '👑' : '👤'} ${display.id} joined (${display.topology.x},${display.topology.y}) orientation=${display.topology.orientation ?? 0}°`);
+    await sleep(300);
+  }
+
+  console.log('\n--- All displays connected ---\n');
+  await sleep(500);
+
+  // ── Show choreography stagger table ────────────────────────
+  console.log(`\n📊 Choreography: ${CHOREOGRAPHY} (${STAGGER_MS}ms stagger)`);
+  console.log('┌─────────────────────────┬──────────┬──────────┐');
+  console.log('│ Display                 │ Position │ Delay    │');
+  console.log('├─────────────────────────┼──────────┼──────────┤');
+  for (const { display } of managers) {
+    const stagger = computeStagger({
+      choreography: CHOREOGRAPHY,
+      topology: display.topology,
+      gridCols: GRID_COLS,
+      gridRows: GRID_ROWS,
+      staggerMs: STAGGER_MS,
+    });
+    console.log(`│ ${display.id.padEnd(23)} │ (${display.topology.x},${display.topology.y})    │ ${String(stagger).padStart(4)}ms   │`);
+  }
+  console.log('└─────────────────────────┴──────────┴──────────┘\n');
+
+  // ── Lead requests layout change ────────────────────────────
+  const lead = managers.find(m => m.display.isLead);
+
+  console.log('🚀 Lead requesting layout 100 (wall mode: each display maps to its own layout)...\n');
+  await lead.manager.requestLayoutChange(100);
+  console.log('\n✅ Layout 100 shown across all displays!\n');
+
+  await sleep(1000);
+
+  console.log('🚀 Lead requesting layout 200 (mirror mode: all show same layout)...\n');
+  await lead.manager.requestLayoutChange(200);
+  console.log('\n✅ Layout 200 shown across all displays!\n');
+
+  await sleep(500);
+
+  // ── Show other choreography patterns ──────────────────────
+  console.log('\n📊 All choreography patterns for this 2×2 grid:\n');
+  const patterns = ['simultaneous', 'wave-right', 'wave-left', 'wave-down', 'wave-up',
+    'diagonal-tl', 'diagonal-tr', 'diagonal-bl', 'diagonal-br',
+    'center-out', 'outside-in'];
+
+  for (const pattern of patterns) {
+    const delays = displays.map(d => computeStagger({
+      choreography: pattern,
+      topology: d.topology,
+      gridCols: GRID_COLS,
+      gridRows: GRID_ROWS,
+      staggerMs: STAGGER_MS,
+    }));
+    const grid = `(0,0)=${delays[0]}ms  (1,0)=${delays[1]}ms  |  (0,1)=${delays[2]}ms  (1,1)=${delays[3]}ms`;
+    console.log(`  ${pattern.padEnd(14)} → ${grid}`);
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────
+  console.log('\n🧹 Cleaning up...');
+  for (const { manager } of managers) {
+    manager.stop();
+  }
+  server.close();
+  console.log('Done.\n');
+});
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/package.json

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

package/src/choreography.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * Transition choreography — compute stagger delays for cascading
+ * layout transitions across multiple displays.
+ *
+ * Supports two modes:
+ *
+ * 1D mode (position-based):
+ *   Displays are numbered 0..N-1 in a row. Simple linear choreographies.
+ *   Config: { position, totalDisplays }
+ *
+ * 2D mode (topology-based):
+ *   Each display has (x, y) coordinates and an orientation vector.
+ *   Enables directional sweeps, diagonal cascades, and radial effects.
+ *   Config: { topology: { x, y, orientation? }, gridCols, gridRows }
+ *
+ * Topology format:
+ *   { x: 1, y: 0, orientation: 0 }
+ *   - x, y: grid coordinates (0-indexed)
+ *   - orientation: degrees clockwise from upright (0=landscape, 90=portrait-right,
+ *     180=inverted, 270=portrait-left). Defaults to 0.
+ *
+ * Choreographies:
+ *   simultaneous — all at once (default, no delay)
+ *   wave-right   — sweep left to right (by x)
+ *   wave-left    — sweep right to left (by x)
+ *   wave-down    — sweep top to bottom (by y, 2D only)
+ *   wave-up      — sweep bottom to top (by y, 2D only)
+ *   diagonal-tl  — cascade from top-left corner (2D only)
+ *   diagonal-tr  — cascade from top-right corner (2D only)
+ *   diagonal-bl  — cascade from bottom-left corner (2D only)
+ *   diagonal-br  — cascade from bottom-right corner (2D only)
+ *   center-out   — explode from center to edges
+ *   outside-in   — implode from edges to center
+ *   random       — random delay per display
+ *
+ * @module @xiboplayer/sync/choreography
+ */
+
+/**
+ * Compute the stagger delay for a display.
+ *
+ * @param {Object} options
+ * @param {string} options.choreography — choreography name
+ * @param {number} [options.position] — 1D: this display's 0-indexed position
+ * @param {number} [options.totalDisplays] — 1D: total displays in the group
+ * @param {Object} [options.topology] — 2D: this display's topology { x, y, orientation? }
+ * @param {number} [options.gridCols] — 2D: grid width (columns)
+ * @param {number} [options.gridRows] — 2D: grid height (rows)
+ * @param {number} options.staggerMs — base delay between consecutive displays (ms)
+ * @returns {number} delay in ms before this display should execute its transition
+ *
+ * @example
+ * // 1D: 4 displays, wave-right with 150ms stagger
+ * computeStagger({ choreography: 'wave-right', position: 2, totalDisplays: 4, staggerMs: 150 })
+ * // → 300
+ *
+ * @example
+ * // 2D: 3×2 grid, diagonal from top-left
+ * computeStagger({
+ *   choreography: 'diagonal-tl',
+ *   topology: { x: 2, y: 1 },
+ *   gridCols: 3, gridRows: 2,
+ *   staggerMs: 100,
+ * })
+ * // → 300 (Manhattan distance 2+1=3, so 3×100)
+ */
+export function computeStagger({ choreography, position, totalDisplays, topology, gridCols, gridRows, staggerMs }) {
+  if (!choreography || choreography === 'simultaneous' || !staggerMs) {
+    return 0;
+  }
+
+  // 2D mode: topology with grid dimensions
+  if (topology && gridCols != null && gridRows != null) {
+    if (gridCols <= 1 && gridRows <= 1) return 0;
+    return _computeStagger2D(choreography, topology, gridCols, gridRows, staggerMs);
+  }
+
+  // 1D mode: position-based
+  if (totalDisplays == null || totalDisplays <= 1) return 0;
+  return _computeStagger1D(choreography, position ?? 0, totalDisplays, staggerMs);
+}
+
+/** @private 1D stagger computation */
+function _computeStagger1D(choreography, position, totalDisplays, staggerMs) {
+  const last = totalDisplays - 1;
+  const center = last / 2;
+
+  switch (choreography) {
+    case 'wave-right':
+      return position * staggerMs;
+
+    case 'wave-left':
+      return (last - position) * staggerMs;
+
+    case 'center-out':
+      return Math.round(Math.abs(position - center)) * staggerMs;
+
+    case 'outside-in': {
+      const maxDist = Math.round(center);
+      return (maxDist - Math.round(Math.abs(position - center))) * staggerMs;
+    }
+
+    case 'random':
+      return Math.floor(Math.random() * last * staggerMs);
+
+    default:
+      return 0;
+  }
+}
+
+/** @private 2D stagger computation */
+function _computeStagger2D(choreography, topology, gridCols, gridRows, staggerMs) {
+  const { x, y } = topology;
+  const maxX = gridCols - 1;
+  const maxY = gridRows - 1;
+  const centerX = maxX / 2;
+  const centerY = maxY / 2;
+
+  switch (choreography) {
+    // Axis-aligned sweeps
+    case 'wave-right':
+      return x * staggerMs;
+
+    case 'wave-left':
+      return (maxX - x) * staggerMs;
+
+    case 'wave-down':
+      return y * staggerMs;
+
+    case 'wave-up':
+      return (maxY - y) * staggerMs;
+
+    // Corner diagonals (Manhattan distance from corner)
+    case 'diagonal-tl':
+      return (x + y) * staggerMs;
+
+    case 'diagonal-tr':
+      return ((maxX - x) + y) * staggerMs;
+
+    case 'diagonal-bl':
+      return (x + (maxY - y)) * staggerMs;
+
+    case 'diagonal-br':
+      return ((maxX - x) + (maxY - y)) * staggerMs;
+
+    // Radial patterns (Euclidean distance from center)
+    case 'center-out': {
+      const dist = Math.sqrt((x - centerX) ** 2 + (y - centerY) ** 2);
+      return Math.round(dist) * staggerMs;
+    }
+
+    case 'outside-in': {
+      const maxDist = Math.round(Math.sqrt(centerX ** 2 + centerY ** 2));
+      const dist = Math.sqrt((x - centerX) ** 2 + (y - centerY) ** 2);
+      return (maxDist - Math.round(dist)) * staggerMs;
+    }
+
+    case 'random': {
+      const maxSteps = maxX + maxY; // Manhattan extent
+      return Math.floor(Math.random() * maxSteps * staggerMs);
+    }
+
+    default:
+      return 0;
+  }
+}

package/src/choreography.test.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
+import { describe, it, expect } from 'vitest';
+import { computeStagger } from './choreography.js';
+
+// ── 1D helpers ────────────────────────────────────────────────────
+const opts = (choreography, position, totalDisplays = 4, staggerMs = 150) =>
+  ({ choreography, position, totalDisplays, staggerMs });
+
+// ── 2D helpers ────────────────────────────────────────────────────
+const opts2D = (choreography, x, y, gridCols = 3, gridRows = 2, staggerMs = 100) =>
+  ({ choreography, topology: { x, y }, gridCols, gridRows, staggerMs });
+
+// ══════════════════════════════════════════════════════════════════
+// 1D MODE (backward compatible)
+// ══════════════════════════════════════════════════════════════════
+describe('computeStagger — 1D mode', () => {
+  describe('simultaneous (default)', () => {
+    it('returns 0 for simultaneous', () => {
+      expect(computeStagger(opts('simultaneous', 0))).toBe(0);
+      expect(computeStagger(opts('simultaneous', 3))).toBe(0);
+    });
+
+    it('returns 0 when no choreography', () => {
+      expect(computeStagger(opts(null, 2))).toBe(0);
+      expect(computeStagger(opts(undefined, 2))).toBe(0);
+      expect(computeStagger(opts('', 2))).toBe(0);
+    });
+
+    it('returns 0 for single display', () => {
+      expect(computeStagger(opts('wave-right', 0, 1, 150))).toBe(0);
+    });
+
+    it('returns 0 when staggerMs is 0', () => {
+      expect(computeStagger(opts('wave-right', 2, 4, 0))).toBe(0);
+    });
+  });
+
+  describe('wave-right', () => {
+    it('staggers left to right', () => {
+      expect(computeStagger(opts('wave-right', 0))).toBe(0);
+      expect(computeStagger(opts('wave-right', 1))).toBe(150);
+      expect(computeStagger(opts('wave-right', 2))).toBe(300);
+      expect(computeStagger(opts('wave-right', 3))).toBe(450);
+    });
+  });
+
+  describe('wave-left', () => {
+    it('staggers right to left', () => {
+      expect(computeStagger(opts('wave-left', 0))).toBe(450);
+      expect(computeStagger(opts('wave-left', 1))).toBe(300);
+      expect(computeStagger(opts('wave-left', 2))).toBe(150);
+      expect(computeStagger(opts('wave-left', 3))).toBe(0);
+    });
+  });
+
+  describe('center-out', () => {
+    it('explodes from center (even count)', () => {
+      // 4 displays: center = 1.5
+      // pos 0: |0-1.5| = 1.5 → round(1.5)*150 = 2*150 = 300
+      // pos 1: |1-1.5| = 0.5 → round(0.5)*150 = 1*150 = 150  (JS rounds .5 up)
+      // pos 2: |2-1.5| = 0.5 → round(0.5)*150 = 1*150 = 150
+      // pos 3: |3-1.5| = 1.5 → round(1.5)*150 = 2*150 = 300
+      expect(computeStagger(opts('center-out', 0))).toBe(300);
+      expect(computeStagger(opts('center-out', 1))).toBe(150);
+      expect(computeStagger(opts('center-out', 2))).toBe(150);
+      expect(computeStagger(opts('center-out', 3))).toBe(300);
+    });
+
+    it('explodes from center (odd count)', () => {
+      // 5 displays: center = 2
+      expect(computeStagger(opts('center-out', 0, 5, 100))).toBe(200);
+      expect(computeStagger(opts('center-out', 1, 5, 100))).toBe(100);
+      expect(computeStagger(opts('center-out', 2, 5, 100))).toBe(0);
+      expect(computeStagger(opts('center-out', 3, 5, 100))).toBe(100);
+      expect(computeStagger(opts('center-out', 4, 5, 100))).toBe(200);
+    });
+  });
+
+  describe('outside-in', () => {
+    it('implodes from edges (odd count)', () => {
+      expect(computeStagger(opts('outside-in', 0, 5, 100))).toBe(0);
+      expect(computeStagger(opts('outside-in', 1, 5, 100))).toBe(100);
+      expect(computeStagger(opts('outside-in', 2, 5, 100))).toBe(200);
+      expect(computeStagger(opts('outside-in', 3, 5, 100))).toBe(100);
+      expect(computeStagger(opts('outside-in', 4, 5, 100))).toBe(0);
+    });
+  });
+
+  describe('random', () => {
+    it('returns a value within range', () => {
+      const delay = computeStagger(opts('random', 2));
+      expect(delay).toBeGreaterThanOrEqual(0);
+      expect(delay).toBeLessThan(3 * 150); // last * staggerMs
+    });
+  });
+
+  describe('unknown choreography', () => {
+    it('returns 0 for unrecognized name', () => {
+      expect(computeStagger(opts('zigzag', 2))).toBe(0);
+    });
+  });
+});
+
+// ══════════════════════════════════════════════════════════════════
+// 2D MODE (topology-based)
+// ══════════════════════════════════════════════════════════════════
+describe('computeStagger — 2D mode', () => {
+  // 3×2 grid:
+  //   (0,0) (1,0) (2,0)
+  //   (0,1) (1,1) (2,1)
+
+  describe('edge cases', () => {
+    it('returns 0 for 1×1 grid', () => {
+      expect(computeStagger(opts2D('wave-right', 0, 0, 1, 1, 100))).toBe(0);
+    });
+
+    it('returns 0 for simultaneous', () => {
+      expect(computeStagger(opts2D('simultaneous', 1, 1))).toBe(0);
+    });
+  });
+
+  describe('wave-right (by x only)', () => {
+    it('staggers by x coordinate', () => {
+      expect(computeStagger(opts2D('wave-right', 0, 0))).toBe(0);
+      expect(computeStagger(opts2D('wave-right', 1, 0))).toBe(100);
+      expect(computeStagger(opts2D('wave-right', 2, 0))).toBe(200);
+      // Same x = same delay regardless of y
+      expect(computeStagger(opts2D('wave-right', 1, 1))).toBe(100);
+    });
+  });
+
+  describe('wave-left (by x, reversed)', () => {
+    it('staggers right to left', () => {
+      expect(computeStagger(opts2D('wave-left', 0, 0))).toBe(200);
+      expect(computeStagger(opts2D('wave-left', 2, 0))).toBe(0);
+    });
+  });
+
+  describe('wave-down (by y only)', () => {
+    it('staggers by y coordinate', () => {
+      expect(computeStagger(opts2D('wave-down', 0, 0))).toBe(0);
+      expect(computeStagger(opts2D('wave-down', 0, 1))).toBe(100);
+      // Same y = same delay regardless of x
+      expect(computeStagger(opts2D('wave-down', 2, 0))).toBe(0);
+    });
+  });
+
+  describe('wave-up (by y, reversed)', () => {
+    it('staggers bottom to top', () => {
+      expect(computeStagger(opts2D('wave-up', 0, 0))).toBe(100);
+      expect(computeStagger(opts2D('wave-up', 0, 1))).toBe(0);
+    });
+  });
+
+  describe('diagonal-tl (from top-left)', () => {
+    it('staggers by Manhattan distance from (0,0)', () => {
+      // (0,0)→0, (1,0)→1, (2,0)→2, (0,1)→1, (1,1)→2, (2,1)→3
+      expect(computeStagger(opts2D('diagonal-tl', 0, 0))).toBe(0);
+      expect(computeStagger(opts2D('diagonal-tl', 1, 0))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-tl', 0, 1))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-tl', 2, 0))).toBe(200);
+      expect(computeStagger(opts2D('diagonal-tl', 1, 1))).toBe(200);
+      expect(computeStagger(opts2D('diagonal-tl', 2, 1))).toBe(300);
+    });
+  });
+
+  describe('diagonal-tr (from top-right)', () => {
+    it('staggers by Manhattan distance from (maxX,0)', () => {
+      // maxX=2: (2,0)→0, (1,0)→1, (0,0)→2, (2,1)→1, (1,1)→2, (0,1)→3
+      expect(computeStagger(opts2D('diagonal-tr', 2, 0))).toBe(0);
+      expect(computeStagger(opts2D('diagonal-tr', 1, 0))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-tr', 0, 0))).toBe(200);
+      expect(computeStagger(opts2D('diagonal-tr', 0, 1))).toBe(300);
+    });
+  });
+
+  describe('diagonal-bl (from bottom-left)', () => {
+    it('staggers by Manhattan distance from (0,maxY)', () => {
+      // maxY=1: (0,1)→0, (1,1)→1, (0,0)→1, (2,1)→2, (1,0)→2, (2,0)→3
+      expect(computeStagger(opts2D('diagonal-bl', 0, 1))).toBe(0);
+      expect(computeStagger(opts2D('diagonal-bl', 0, 0))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-bl', 2, 1))).toBe(200);
+      expect(computeStagger(opts2D('diagonal-bl', 2, 0))).toBe(300);
+    });
+  });
+
+  describe('diagonal-br (from bottom-right)', () => {
+    it('staggers by Manhattan distance from (maxX,maxY)', () => {
+      // (2,1)→0, (1,1)→1, (2,0)→1, (0,1)→2, (1,0)→2, (0,0)→3
+      expect(computeStagger(opts2D('diagonal-br', 2, 1))).toBe(0);
+      expect(computeStagger(opts2D('diagonal-br', 1, 1))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-br', 2, 0))).toBe(100);
+      expect(computeStagger(opts2D('diagonal-br', 0, 0))).toBe(300);
+    });
+  });
+
+  describe('center-out (Euclidean from center)', () => {
+    it('radiates from center of 3×3 grid', () => {
+      // 3×3 grid, center = (1,1)
+      // (1,1)→0, (0,1)→1, (1,0)→1, (0,0)→√2≈1.41→round=1
+      const o = (x, y) => opts2D('center-out', x, y, 3, 3, 100);
+      expect(computeStagger(o(1, 1))).toBe(0);     // center
+      expect(computeStagger(o(0, 1))).toBe(100);   // dist 1
+      expect(computeStagger(o(1, 0))).toBe(100);   // dist 1
+      expect(computeStagger(o(0, 0))).toBe(100);   // dist √2 ≈ 1.41 → round = 1
+      expect(computeStagger(o(2, 2))).toBe(100);   // dist √2 ≈ 1.41 → round = 1
+    });
+  });
+
+  describe('outside-in (reverse radial)', () => {
+    it('edges first, center last on 3×3', () => {
+      // 3×3: maxDist = round(√(1²+1²)) = round(1.41) = 1
+      // (0,0): dist=√2≈1.41→round=1 → (1-1)=0 → 0ms
+      // (1,1): dist=0→round=0 → (1-0)=1 → 100ms
+      const o = (x, y) => opts2D('outside-in', x, y, 3, 3, 100);
+      expect(computeStagger(o(0, 0))).toBe(0);     // corner, starts first
+      expect(computeStagger(o(1, 1))).toBe(100);   // center, last
+    });
+  });
+
+  describe('random (2D)', () => {
+    it('returns a value within range', () => {
+      const delay = computeStagger(opts2D('random', 1, 1));
+      // maxSteps = maxX + maxY = 2 + 1 = 3
+      expect(delay).toBeGreaterThanOrEqual(0);
+      expect(delay).toBeLessThan(3 * 100);
+    });
+  });
+
+  describe('unknown 2D choreography', () => {
+    it('returns 0', () => {
+      expect(computeStagger(opts2D('spiral', 1, 1))).toBe(0);
+    });
+  });
+
+  describe('topology with orientation', () => {
+    it('orientation does not affect stagger (cosmetic metadata)', () => {
+      const base = computeStagger(opts2D('wave-right', 1, 0));
+      const withOrientation = computeStagger({
+        choreography: 'wave-right',
+        topology: { x: 1, y: 0, orientation: 90 },
+        gridCols: 3, gridRows: 2, staggerMs: 100,
+      });
+      expect(withOrientation).toBe(base);
+    });
+  });
+});

package/src/index.d.ts

@@ -9,6 +9,24 @@ export interface SyncTransport {
   readonly connected: boolean;
 }
 
+export type Choreography =
+  | 'simultaneous'
+  | 'wave-right' | 'wave-left'
+  | 'wave-down' | 'wave-up'
+  | 'diagonal-tl' | 'diagonal-tr' | 'diagonal-bl' | 'diagonal-br'
+  | 'center-out' | 'outside-in'
+  | 'random';
+
+/** Display topology — position and orientation in the physical grid */
+export interface DisplayTopology {
+  /** X coordinate in the grid (0-indexed, left to right) */
+  x: number;
+  /** Y coordinate in the grid (0-indexed, top to bottom) */
+  y: number;
+  /** Screen orientation in degrees clockwise (0=landscape, 90=portrait-right, 270=portrait-left) */
+  orientation?: number;
+}
+
 export interface SyncConfig {
   syncGroup: string;
   syncPublisherPort: number;
@@ -16,6 +34,30 @@ export interface SyncConfig {
   syncVideoPauseDelay: number;
   isLead: boolean;
   relayUrl?: string;
+  /** Auth token for relay join validation (typically CMS server key) */
+  syncToken?: string;
+  /** Wall mode: map lead layoutId → this display's position-specific layoutId */
+  layoutMap?: Record<string, string | number>;
+
+  // ── Choreography (1D mode) ─────────────────────────────────────
+  /** This display's 0-indexed position in a row (1D choreography) */
+  position?: number;
+  /** Total displays in the group (auto-detected from relay if omitted) */
+  totalDisplays?: number;
+
+  // ── Choreography (2D mode) ─────────────────────────────────────
+  /** This display's topology { x, y, orientation } (enables 2D choreography) */
+  topology?: DisplayTopology;
+  /** Grid width in columns (required for 2D choreography) */
+  gridCols?: number;
+  /** Grid height in rows (required for 2D choreography) */
+  gridRows?: number;
+
+  // ── Choreography (common) ──────────────────────────────────────
+  /** Transition choreography pattern */
+  choreography?: Choreography;
+  /** Base delay between consecutive displays in ms (default: 150) */
+  staggerMs?: number;
 }
 
 export class BroadcastChannelTransport implements SyncTransport {
@@ -27,13 +69,30 @@ export class BroadcastChannelTransport implements SyncTransport {
 }
 
 export class WebSocketTransport implements SyncTransport {
-  constructor(url: string);
+  constructor(url: string, options?: {
+    syncGroup?: string;
+    displayId?: string;
+    topology?: DisplayTopology;
+    token?: string;
+  });
   send(msg: any): void;
   onMessage(callback: (msg: any) => void): void;
   close(): void;
   readonly connected: boolean;
 }
 
+export function computeStagger(options: {
+  choreography: string;
+  staggerMs: number;
+  // 1D mode
+  position?: number;
+  totalDisplays?: number;
+  // 2D mode
+  topology?: DisplayTopology;
+  gridCols?: number;
+  gridRows?: number;
+}): number;
+
 export class SyncManager {
   constructor(options: {
     displayId: string;
@@ -46,6 +105,7 @@ export class SyncManager {
     onLogsReport?: (followerId: string, logsXml: string, ack: () => void) => void;
     onStatsAck?: (targetDisplayId: string) => void;
     onLogsAck?: (targetDisplayId: string) => void;
+    onGroupUpdate?: (totalDisplays: number, topology: Record<string, DisplayTopology>) => void;
   });
 
   displayId: string;

package/src/sync-manager.js

@@ -75,6 +75,7 @@ export class SyncManager {
     this.onLogsReport = options.onLogsReport || null;
     this.onStatsAck = options.onStatsAck || null;
     this.onLogsAck = options.onLogsAck || null;
+    this.onGroupUpdate = options.onGroupUpdate || null;
 
     // State
     this.transport = options.transport || null;
@@ -104,7 +105,12 @@ export class SyncManager {
     // Select transport if none injected
     if (!this.transport) {
       if (this.syncConfig.relayUrl) {
-        this.transport = new WebSocketTransport(this.syncConfig.relayUrl);
+        this.transport = new WebSocketTransport(this.syncConfig.relayUrl, {
+          syncGroup: this.syncConfig.syncGroup,
+          displayId: this.displayId,
+          topology: this.syncConfig.topology,
+          token: this.syncConfig.syncToken,
+        });
       } else if (typeof BroadcastChannel !== 'undefined') {
         this.transport = new BroadcastChannelTransport();
       } else {
@@ -294,6 +300,15 @@ export class SyncManager {
 
   /** @private */
   _handleMessage(msg) {
+    // Relay-originated messages (no displayId)
+    if (msg.type === 'group-update') {
+      this._log.info(`Group update: ${msg.totalDisplays} displays`);
+      if (this.onGroupUpdate) {
+        this.onGroupUpdate(msg.totalDisplays, msg.topology || {});
+      }
+      return;
+    }
+
     // Ignore our own messages
     if (msg.displayId === this.displayId) return;
 
@@ -515,3 +530,4 @@ export class SyncManager {
 
 export { BroadcastChannelTransport } from './bc-transport.js';
 export { WebSocketTransport } from './ws-transport.js';
+export { computeStagger } from './choreography.js';

package/src/sync-manager.test.js

@@ -558,4 +558,120 @@ describe('SyncManager', () => {
       expect(onLogsAck).toHaveBeenCalledWith('pwa-f1');
     });
   });
+
+  // ── Local sync config fallback ────────────────────────────────
+
+  describe('local sync config fallback pattern', () => {
+    // Tests the pattern used in main.ts: when CMS returns syncConfig: null
+    // but config.data.sync is set, the player emits 'sync-config' on
+    // register-complete. This tests the EventEmitter contract, not the DOM.
+
+    it('should initialize SyncManager from local config when CMS provides no syncConfig', () => {
+      // Simulate the pattern from main.ts:
+      // core.on('register-complete') → if no CMS sync → emit 'sync-config' from local
+      const { EventEmitter } = require('@xiboplayer/utils');
+      const core = new EventEmitter();
+
+      const localSyncConfig = {
+        syncGroup: 'lobby',
+        syncPublisherPort: 9590,
+        syncSwitchDelay: 500,
+        syncVideoPauseDelay: 100,
+        isLead: false,
+      };
+
+      const syncConfigReceived = vi.fn();
+      core.on('sync-config', syncConfigReceived);
+
+      // Simulate the fallback listener (mirrors main.ts logic)
+      core.on('register-complete', (regResult) => {
+        if (!regResult.syncConfig && localSyncConfig) {
+          core.emit('sync-config', localSyncConfig);
+        }
+      });
+
+      // CMS returns no syncConfig
+      core.emit('register-complete', { syncConfig: null, settings: {} });
+
+      expect(syncConfigReceived).toHaveBeenCalledWith(localSyncConfig);
+    });
+
+    it('should NOT use local config when CMS provides syncConfig', () => {
+      const { EventEmitter } = require('@xiboplayer/utils');
+      const core = new EventEmitter();
+
+      const localSyncConfig = { syncGroup: 'local', isLead: false };
+      const cmsSyncConfig = { syncGroup: 'cms-group', isLead: true };
+
+      const syncConfigReceived = vi.fn();
+      core.on('sync-config', syncConfigReceived);
+
+      // Fallback listener
+      core.on('register-complete', (regResult) => {
+        if (!regResult.syncConfig && localSyncConfig) {
+          core.emit('sync-config', localSyncConfig);
+        }
+      });
+
+      // CMS provides syncConfig — fallback should NOT fire
+      core.emit('register-complete', { syncConfig: cmsSyncConfig, settings: {} });
+
+      // The fallback listener should NOT have emitted sync-config
+      expect(syncConfigReceived).not.toHaveBeenCalled();
+    });
+
+    it('should NOT emit sync-config when neither CMS nor local provides config', () => {
+      const { EventEmitter } = require('@xiboplayer/utils');
+      const core = new EventEmitter();
+
+      const syncConfigReceived = vi.fn();
+      core.on('sync-config', syncConfigReceived);
+
+      // Fallback with null local config
+      const localSyncConfig = null;
+      core.on('register-complete', (regResult) => {
+        if (!regResult.syncConfig && localSyncConfig) {
+          core.emit('sync-config', localSyncConfig);
+        }
+      });
+
+      core.emit('register-complete', { syncConfig: null, settings: {} });
+
+      expect(syncConfigReceived).not.toHaveBeenCalled();
+    });
+
+    it('should create SyncManager with local config values', () => {
+      const localConfig = {
+        syncGroup: 'lobby',
+        syncPublisherPort: 9590,
+        syncSwitchDelay: 750,
+        syncVideoPauseDelay: 100,
+        isLead: true,
+        topology: { x: 0, y: 0, orientation: 0 },
+        choreography: 'wave-right',
+        staggerMs: 150,
+        gridCols: 2,
+        gridRows: 2,
+      };
+
+      const transport = {
+        send: vi.fn(),
+        onMessage: vi.fn(),
+        close: vi.fn(),
+        connected: true,
+      };
+
+      const manager = new SyncManager({
+        displayId: 'test-local',
+        syncConfig: localConfig,
+        transport,
+      });
+
+      expect(manager.displayId).toBe('test-local');
+      expect(manager.isLead).toBe(true);
+      expect(manager.syncConfig.topology).toEqual({ x: 0, y: 0, orientation: 0 });
+      expect(manager.syncConfig.choreography).toBe('wave-right');
+      manager.stop();
+    });
+  });
 });

package/src/ws-transport.js

@@ -23,9 +23,18 @@ const BACKOFF_FACTOR = 2;
 export class WebSocketTransport {
   /**
    * @param {string} url — WebSocket URL, e.g. ws://192.168.1.100:8765/sync
+   * @param {Object} [options]
+   * @param {string} [options.syncGroup] — group name for relay isolation
+   * @param {string} [options.displayId] — this display's unique ID
+   * @param {Object} [options.topology] — this display's topology { x, y, orientation? }
+   * @param {string} [options.token] — auth token for relay join validation
    */
-  constructor(url) {
+  constructor(url, { syncGroup, displayId, topology, token } = {}) {
     this._url = url;
+    this._syncGroup = syncGroup || null;
+    this._displayId = displayId || null;
+    this._topology = topology || null;
+    this._token = token || null;
     this._callback = null;
     this._closed = false;
     this._retryMs = INITIAL_RETRY_MS;
@@ -87,12 +96,27 @@ export class WebSocketTransport {
     this.ws.onopen = () => {
       this._log.info(`Connected to ${this._url}`);
       this._retryMs = INITIAL_RETRY_MS; // Reset backoff on success
+
+      // Join sync group for relay isolation (+ topology for auto-detection)
+      if (this._syncGroup) {
+        const join = { type: 'join', syncGroup: this._syncGroup };
+        if (this._displayId) join.displayId = this._displayId;
+        if (this._topology) join.topology = this._topology;
+        if (this._token) join.token = this._token;
+        this.ws.send(JSON.stringify(join));
+      }
     };
 
-    this.ws.onmessage = (event) => {
+    this.ws.onmessage = async (event) => {
       if (!this._callback) return;
       try {
-        const msg = JSON.parse(event.data);
+        // Browser WebSocket delivers string; Node ws delivers Buffer;
+        // Node 22+ native WebSocket delivers Blob. Handle all three.
+        let raw = event.data;
+        if (typeof raw !== 'string') {
+          raw = (raw instanceof Blob) ? await raw.text() : String(raw);
+        }
+        const msg = JSON.parse(raw);
         this._callback(msg);
       } catch (e) {
         this._log.warn('Failed to parse message:', e.message);

package/src/ws-transport.test.js

@@ -0,0 +1,261 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2024-2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * WebSocketTransport tests
+ *
+ * Focuses on message parsing — the onmessage handler must correctly parse
+ * JSON from three different event.data types:
+ *   1. string  — browser WebSocket (standard)
+ *   2. Buffer  — Node.js `ws` package
+ *   3. Blob    — Node 22+ native WebSocket (undici)
+ *
+ * Uses a mock WebSocket to test the transport in isolation.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// ── Mock WebSocket ──────────────────────────────────────────────
+// Captures onopen/onmessage/onclose/onerror handlers set by the transport
+
+class MockWebSocket {
+  static OPEN = 1;
+  static instances = [];
+
+  constructor(url) {
+    this.url = url;
+    this.readyState = MockWebSocket.OPEN;
+    this.onopen = null;
+    this.onmessage = null;
+    this.onclose = null;
+    this.onerror = null;
+    this._sent = [];
+    MockWebSocket.instances.push(this);
+
+    // Auto-fire onopen in next microtask
+    queueMicrotask(() => {
+      if (this.onopen) this.onopen();
+    });
+  }
+
+  send(data) {
+    this._sent.push(data);
+  }
+
+  close() {
+    this.readyState = 3; // CLOSED
+    if (this.onclose) this.onclose();
+  }
+
+  // Test helper: simulate receiving a message with arbitrary event.data
+  simulateMessage(data) {
+    if (this.onmessage) {
+      this.onmessage({ data });
+    }
+  }
+}
+
+// Install mock before importing the transport
+const originalWebSocket = globalThis.WebSocket;
+
+beforeEach(() => {
+  MockWebSocket.instances = [];
+  globalThis.WebSocket = MockWebSocket;
+});
+
+afterEach(() => {
+  globalThis.WebSocket = originalWebSocket;
+});
+
+// Dynamic import so it picks up our mock WebSocket
+async function createTransport(url = 'ws://localhost:9590/sync', opts = {}) {
+  const { WebSocketTransport } = await import('./ws-transport.js');
+  return new WebSocketTransport(url, opts);
+}
+
+// ── Tests ───────────────────────────────────────────────────────
+
+describe('WebSocketTransport', () => {
+  describe('message parsing', () => {
+    const testMsg = { type: 'layout-change', layoutId: '42', showAt: 12345 };
+
+    it('parses string data (browser WebSocket)', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      const received = vi.fn();
+      transport.onMessage(received);
+
+      // Browser sends string
+      ws.simulateMessage(JSON.stringify(testMsg));
+
+      // Allow async onmessage to complete
+      await vi.waitFor(() => expect(received).toHaveBeenCalled());
+      expect(received).toHaveBeenCalledWith(testMsg);
+
+      transport.close();
+    });
+
+    it('parses Buffer data (Node ws package)', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      const received = vi.fn();
+      transport.onMessage(received);
+
+      // Node ws sends Buffer
+      const buffer = Buffer.from(JSON.stringify(testMsg));
+      ws.simulateMessage(buffer);
+
+      await vi.waitFor(() => expect(received).toHaveBeenCalled());
+      expect(received).toHaveBeenCalledWith(testMsg);
+
+      transport.close();
+    });
+
+    it('parses Blob data (Node 22+ native WebSocket)', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      const received = vi.fn();
+      transport.onMessage(received);
+
+      // Node 22+ native WS (undici) sends Blob
+      const blob = new Blob([JSON.stringify(testMsg)]);
+      ws.simulateMessage(blob);
+
+      await vi.waitFor(() => expect(received).toHaveBeenCalled());
+      expect(received).toHaveBeenCalledWith(testMsg);
+
+      transport.close();
+    });
+
+    it('warns on unparseable data without crashing', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      const received = vi.fn();
+      transport.onMessage(received);
+
+      // Send garbage
+      ws.simulateMessage('not json {{{');
+
+      // Give async handler a tick
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(received).not.toHaveBeenCalled();
+
+      transport.close();
+    });
+
+    it('ignores messages when no callback registered', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      // No onMessage callback set — should not throw
+      ws.simulateMessage(JSON.stringify(testMsg));
+      await new Promise(r => setTimeout(r, 50));
+
+      transport.close();
+    });
+  });
+
+  describe('join message', () => {
+    it('sends join with syncGroup on connect', async () => {
+      const transport = await createTransport('ws://localhost:9590/sync', {
+        syncGroup: 'lobby',
+      });
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      // Wait for onopen to fire and send join
+      await vi.waitFor(() => expect(ws._sent.length).toBeGreaterThan(0));
+
+      const join = JSON.parse(ws._sent[0]);
+      expect(join.type).toBe('join');
+      expect(join.syncGroup).toBe('lobby');
+
+      transport.close();
+    });
+
+    it('includes displayId and topology in join', async () => {
+      const transport = await createTransport('ws://localhost:9590/sync', {
+        syncGroup: 'wall',
+        displayId: 'display-1',
+        topology: { x: 1, y: 0, orientation: 90 },
+      });
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      await vi.waitFor(() => expect(ws._sent.length).toBeGreaterThan(0));
+
+      const join = JSON.parse(ws._sent[0]);
+      expect(join.displayId).toBe('display-1');
+      expect(join.topology).toEqual({ x: 1, y: 0, orientation: 90 });
+
+      transport.close();
+    });
+
+    it('does not send join when no syncGroup', async () => {
+      const transport = await createTransport('ws://localhost:9590/sync', {});
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+      const ws = MockWebSocket.instances[0];
+
+      // Give time for onopen
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(ws._sent.length).toBe(0);
+
+      transport.close();
+    });
+  });
+
+  describe('send', () => {
+    it('serializes objects to JSON', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+
+      transport.send({ type: 'heartbeat', displayId: 'test' });
+      const ws = MockWebSocket.instances[0];
+      const lastSent = ws._sent[ws._sent.length - 1];
+      expect(JSON.parse(lastSent)).toEqual({ type: 'heartbeat', displayId: 'test' });
+
+      transport.close();
+    });
+
+    it('does not send when connection is closed', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+
+      transport.close();
+      transport.send({ type: 'heartbeat' });
+      // Should not throw
+    });
+  });
+
+  describe('lifecycle', () => {
+    it('reports connected when WebSocket is OPEN', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+
+      expect(transport.connected).toBe(true);
+
+      transport.close();
+      expect(transport.connected).toBe(false);
+    });
+
+    it('close() prevents reconnection', async () => {
+      const transport = await createTransport();
+      await vi.waitFor(() => expect(MockWebSocket.instances.length).toBe(1));
+
+      transport.close();
+
+      // Wait to ensure no reconnect
+      await new Promise(r => setTimeout(r, 200));
+      expect(MockWebSocket.instances.length).toBe(1); // no new instance
+    });
+  });
+});