feat(14.2-02): three-tier delay display, sync mode footer, and syncing overlay

- Add optional syncMode field to BufferDelayMessage and SyncMode type in types.ts
- Track lastAutoSyncMode separately from manualMode for correct auto-restore
- getDelayDisplayText shows "measured", "calculated", or "manual" (replaces generic "auto")
- syncMode runtime validated: only 'measured'|'calculated' accepted, unknown defaults to 'calculated' (T-14.2-06)
- showSyncingOverlay/hideSyncingOverlay with replace semantics for repeated updates (D-09)
- onBufferDelay in main.ts passes syncMode and triggers overlay for measured mode only
- Update existing video-sync tests from "(auto)" to "(calculated)"
- All 109 companion tests pass including 21 new instamode-sync tests

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mkschulze

companion/src/__tests__/video-sync.test.ts

@@ -99,9 +99,9 @@ describe('Video Sync Dual-State Delay Model (VID-08)', () => {
       expect(getDelayDisplayText()).toBe('--');
     });
 
-    it('returns "8.0s (auto)" when activeDelayMs=8000, auto mode', () => {
+    it('returns "8.0s (calculated)" when activeDelayMs=8000, calculated mode', () => {
       setLastAutoDelay(8000);
-      expect(getDelayDisplayText()).toBe('8.0s (auto)');
+      expect(getDelayDisplayText()).toBe('8.0s (calculated)');
     });
 
     it('returns "0.0s (manual) No delay" when activeDelayMs=0, manual mode', () => {
@@ -114,9 +114,9 @@ describe('Video Sync Dual-State Delay Model (VID-08)', () => {
       expect(getDelayDisplayText()).toBe('5.0s (manual)');
     });
 
-    it('returns "0.0s (auto) No delay" when activeDelayMs=0, auto mode', () => {
+    it('returns "0.0s (calculated) No delay" when activeDelayMs=0, calculated mode', () => {
       setLastAutoDelay(0);
-      expect(getDelayDisplayText()).toBe('0.0s (auto) No delay');
+      expect(getDelayDisplayText()).toBe('0.0s (calculated) No delay');
     });
   });
 

companion/src/main.ts

@@ -19,6 +19,7 @@ import {
   getSavedEffect,
   saveEffect,
   setLastAutoDelay,
+  showSyncingOverlay,
   initDelayControls,
   updateFooterDelayStatus,
   renderRosterStrip,
@@ -233,9 +234,16 @@ const callbacks: WsCallbacks = {
   },
 
   onBufferDelay(msg) {
-    console.log('VideoSync: plugin sent bufferDelay:', msg.delayMs, 'ms');
-    setLastAutoDelay(msg.delayMs);
+    console.log('VideoSync: plugin sent bufferDelay:', msg.delayMs, 'ms',
+      msg.syncMode ? `(${msg.syncMode})` : '');
+    setLastAutoDelay(msg.delayMs, msg.syncMode);
     updateFooterDelayStatus();
+    // D-09: show sync overlay when measured delay arrives.
+    // Only for 'measured' mode -- calculated mode doesn't need a visible sync phase
+    // because it's a theoretical estimate, not a probe-triggered calibration.
+    if (msg.syncMode === 'measured' && msg.delayMs > 0) {
+      showSyncingOverlay(msg.delayMs);
+    }
   },
 
   onBeatHeartbeat(msg) {

companion/src/types.ts

@@ -22,6 +22,7 @@ export interface RosterMessage {
 export interface BufferDelayMessage {
   type: 'bufferDelay';
   delayMs: number;
+  syncMode?: 'measured' | 'calculated';
 }
 
 export interface PopoutMessage {
@@ -40,6 +41,8 @@ export interface DeactivateMessage {
   type: 'deactivate';
 }
 
+export type SyncMode = 'measured' | 'calculated' | 'manual';
+
 export type PluginMessage = ConfigMessage | RosterMessage | BufferDelayMessage | PopoutMessage | BeatHeartbeatMessage | DeactivateMessage;
 
 // ── Runtime validation (addresses review: protocol resilience) ──

companion/src/ui.ts

@@ -232,18 +232,30 @@ const VDO_NINJA_ORIGIN = 'https://vdo.ninja';
 let lastAutoDelayMs: number | null = null;
 let activeDelayMs: number | null = null;
 let manualMode = false;
+// Phase 14.2 (D-12): Track the last auto sync mode separately from manual mode.
+// This preserves the mode label so switchToAuto can restore it correctly.
+// Addresses review concern: separate lastAutoSyncMode from manualMode.
+let lastAutoSyncMode: 'measured' | 'calculated' = 'calculated';
 
 /** Called when plugin sends bufferDelay message. Always updates lastAutoDelayMs.
  *  In auto mode, also updates activeDelayMs and sends to iframe.
- *  In manual mode, silently tracks the plugin value for later switchToAuto(). */
-export function setLastAutoDelay(delayMs: number): void {
+ *  In manual mode, silently tracks the plugin value for later switchToAuto().
+ *  syncMode is runtime-validated: only 'measured' | 'calculated' accepted (T-14.2-06). */
+export function setLastAutoDelay(delayMs: number, syncMode?: 'measured' | 'calculated'): void {
   lastAutoDelayMs = delayMs;
+  // Runtime validation: only accept known values (addresses review concern #3).
+  // Unknown or absent syncMode defaults to 'calculated' for backward compatibility (D-13).
+  if (syncMode === 'measured' || syncMode === 'calculated') {
+    lastAutoSyncMode = syncMode;
+  }
+  // else: keep current lastAutoSyncMode (defaults to 'calculated' on init/reset)
   if (!manualMode) {
     activeDelayMs = delayMs;
-    console.log('VideoSync: auto delay applied:', delayMs, 'ms');
+    console.log('VideoSync: auto delay applied:', delayMs, 'ms', syncMode ? `(${syncMode})` : '');
     sendBufferDelayToIframe(delayMs);
   } else {
-    console.log('VideoSync: auto delay updated:', delayMs, 'ms (manual mode, not applied)');
+    console.log('VideoSync: auto delay updated:', delayMs, 'ms (manual mode, not applied)',
+      syncMode ? `(${syncMode})` : '');
   }
 }
 
@@ -280,13 +292,23 @@ export function isManualMode(): boolean {
   return manualMode;
 }
 
-/** Get formatted display text for the current delay state. */
+/** Get the last auto sync mode (measured or calculated). */
+export function getLastAutoSyncMode(): 'measured' | 'calculated' {
+  return lastAutoSyncMode;
+}
+
+/** Get formatted display text for the current delay state.
+ *  Three-tier display: manual > measured > calculated (D-11, D-12). */
 export function getDelayDisplayText(): string {
   if (activeDelayMs === null) return '--';
-  const mode = manualMode ? 'manual' : 'auto';
   const seconds = (activeDelayMs / 1000).toFixed(1);
-  if (activeDelayMs === 0) return `${seconds}s (${mode}) No delay`;
-  return `${seconds}s (${mode})`;
+  if (manualMode) {
+    if (activeDelayMs === 0) return `${seconds}s (manual) No delay`;
+    return `${seconds}s (manual)`;
+  }
+  // Auto mode: display the specific sync mode (measured or calculated)
+  if (activeDelayMs === 0) return `${seconds}s (${lastAutoSyncMode}) No delay`;
+  return `${seconds}s (${lastAutoSyncMode})`;
 }
 
 function sendBufferDelayToIframe(delayMs: number): void {
@@ -312,6 +334,42 @@ export function resetDelayState(): void {
   lastAutoDelayMs = null;
   activeDelayMs = null;
   manualMode = false;
+  lastAutoSyncMode = 'calculated';
+}
+
+/** D-09: Show a black syncing overlay over the video area.
+ *  Overlay fades out after delayMs + 500ms grace period.
+ *  Only one overlay exists at a time -- calling again replaces the existing one
+ *  (addresses review concern: repeated measured update behavior).
+ *  NOTE: Single overlay covers entire video area because VDO.Ninja iframe is
+ *  cross-origin (cannot position per-tile overlays). All tiles share the same
+ *  measured delay, so global overlay is functionally equivalent. */
+export function showSyncingOverlay(delayMs: number): void {
+  // Remove any existing overlay first (replace semantics for repeated updates)
+  hideSyncingOverlay();
+
+  const overlay = document.createElement('div');
+  overlay.id = 'sync-overlay';
+  overlay.style.cssText = 'position:absolute;inset:0;background:#000;'
+    + 'transition:opacity 0.8s ease;opacity:1;pointer-events:none;z-index:10;'
+    + 'display:flex;align-items:center;justify-content:center;color:#888;font-size:14px;';
+  overlay.textContent = 'Syncing video\u2026';
+
+  const mainArea = document.getElementById('main-area');
+  if (mainArea) {
+    mainArea.style.position = 'relative';
+    mainArea.appendChild(overlay);
+    // Fade out after buffer fills (delayMs + 500ms grace)
+    setTimeout(() => {
+      overlay.style.opacity = '0';
+      setTimeout(() => overlay.remove(), 900);  // remove after CSS transition completes
+    }, delayMs + 500);
+  }
+}
+
+/** Remove the syncing overlay immediately. */
+export function hideSyncingOverlay(): void {
+  document.getElementById('sync-overlay')?.remove();
 }
 
 // Legacy aliases for backward compatibility with existing tests