loukai-app 0.4.3 → 0.6.0

package/README.md

@@ -11,6 +11,12 @@
 
 Loukai is a free, open source karaoke software that runs locally on your computer to **play** and **create** karaoke files from your own music. Built on M4A Stems (MPEG-4 multi-track audio), it uses industry-standard formats compatible with DJ software, giving you full control over your personal karaoke library.
 
+## Quick start (with nodejs installed)
+
+```
+npx loukai-app
+```
+
 **Key highlights:**
 - **Open Format**: Built on NI Stems — no vendor lock-in, works with Traktor, Mixxx, and other DJ software
 - **Create Your Own**: Built-in Creator processes your audio files into stem-separated karaoke with AI-transcribed lyrics
@@ -24,7 +30,7 @@ Loukai is a free, open source karaoke software that runs locally on your compute
 ## Features
 
 ### Audio & Playback
-- **M4A Stems Format (Primary)**: Built on [NI Stems](https://www.native-instruments.com/en/specials/stems/) with karaoke extensions
+- **MP4 Stems Format (Primary)**: Built on [NI Stems](https://www.native-instruments.com/en/specials/stems/) with karaoke extensions
   - Compatible with DJ software (Traktor, Mixxx) via standard NI Stems metadata
   - Smaller file sizes than legacy formats
   - Embedded lyrics with word-level timing in custom atoms
@@ -51,7 +57,7 @@ Loukai is a free, open source karaoke software that runs locally on your compute
 
 ### Library & Search
 - **Fast Library Scanning**: Automatic metadata extraction from thousands of songs
-- **M4A Stems Native**: Optimized for MPEG-4 multi-track audio with full metadata support
+- **MP4 Stems Native**: Optimized for MPEG-4 multi-track audio with full metadata support
 - **Legacy Format Support**: Also reads CDG/MP3 pairs
 - **Smart Search**: Fuzzy search across titles, artists, and albums
 - **Alphabet Navigation**: Quick filtering by first letter
@@ -194,7 +200,7 @@ Loukai is built with a multi-process architecture:
 - **Library Scanner**: Metadata extraction and caching
 - **Web Server**: Express 5 REST API + Socket.IO
 - **State Management**: Centralized app state with event emitters
-- **File System**: M4A/CDG file parsing and manipulation
+- **File System**: MP4/CDG file parsing and manipulation
 - **IPC Handlers**: Communication bridge to renderer
 
 ### Renderer Process (React)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loukai-app",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "type": "module",
   "description": "Loukai Karaoke - Free and open source karaoke system for playing and creating stem-based karaoke files",
   "main": "src/main/main.js",
@@ -16,6 +16,7 @@
     "build:win": "npm run build:all && electron-builder --win && node scripts/rename-artifacts.js",
     "build:mac": "npm run build:all && electron-builder --mac && node scripts/rename-artifacts.js",
     "rebuild": "electron-rebuild",
+    "postinstall": "node scripts/ensure-electron.js",
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
@@ -46,6 +47,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "autoprefixer": "^10.4.21",
+    "electron": "^40.6.0",
     "electron-builder": "^26.0.12",
     "eslint": "^9.37.0",
     "eslint-config-prettier": "^10.1.8",
@@ -74,7 +76,6 @@
     "cdgraphics": "^7.0.0",
     "cookie-session": "^2.1.1",
     "cors": "^2.8.5",
-    "electron": "^40.6.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.1.0",
     "fuse.js": "^7.1.0",
@@ -236,6 +237,7 @@
     "src/",
     "public/",
     "bin/",
-    "static/"
+    "static/",
+    "scripts/ensure-electron.js"
   ]
 }

package/scripts/ensure-electron.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Ensure Electron is installed AND correctly extracted.
+ *
+ * Electron lives in `devDependencies` because electron-builder requires it
+ * there (and bundles its own copy into the DMG/installer — Electron in
+ * `dependencies`/`optionalDependencies` makes electron-builder copy the whole
+ * ~200MB Electron package into the app on top of the framework). But a
+ * production/npx install skips devDependencies, so Electron is absent at
+ * runtime. `postinstall` still runs for those installs, so this bridges the gap
+ * with two jobs:
+ *
+ *  1. INSTALL: if Electron is missing (production/npx consumer), install it from
+ *     the version range declared in our own package.json. In the dev repo
+ *     Electron is already present, so this never triggers.
+ *
+ *  2. REPAIR: Electron's own postinstall extracts its binary with `extract-zip`
+ *     (bundling the unmaintained `yauzl@2.x`). On Node 24 that extractor
+ *     silently stalls after the first zip entry, leaving a half-written `dist/`
+ *     (only `LICENSES.chromium.html`, no `path.txt`). We re-extract the
+ *     downloaded zip with the system archive tool (`unzip` on macOS/Linux,
+ *     PowerShell on Windows), which is unaffected by the bug, then write
+ *     `path.txt`.
+ *
+ * When Electron is already present and healthy, this is a silent no-op.
+ * Best-effort throughout: it never fails the install; if it can't finish it
+ * logs actionable guidance and exits 0.
+ */
+
+import { createRequire } from 'module';
+import { execFileSync } from 'child_process';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  rmSync,
+  mkdirSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+const projectDir = join(here, '..'); // package root (postinstall cwd may vary)
+
+function log(msg) {
+  console.log(`[ensure-electron] ${msg}`);
+}
+
+function platformBinaryPath(platform) {
+  switch (platform) {
+    case 'mas':
+    case 'darwin':
+      return 'Electron.app/Contents/MacOS/Electron';
+    case 'freebsd':
+    case 'openbsd':
+    case 'linux':
+      return 'electron';
+    case 'win32':
+      return 'electron.exe';
+    default:
+      return null;
+  }
+}
+
+function resolveElectronDir() {
+  try {
+    return dirname(require.resolve('electron/package.json', { paths: [projectDir] }));
+  } catch {
+    return null;
+  }
+}
+
+function declaredElectronRange() {
+  try {
+    const pkg = require(join(projectDir, 'package.json'));
+    return (
+      (pkg.devDependencies && pkg.devDependencies.electron) ||
+      (pkg.dependencies && pkg.dependencies.electron) ||
+      null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function isInstalled(electronDir, version, platformPath) {
+  try {
+    const distVersion = readFileSync(join(electronDir, 'dist', 'version'), 'utf-8').replace(/^v/, '');
+    if (distVersion !== version) return false;
+    if (readFileSync(join(electronDir, 'path.txt'), 'utf-8') !== platformPath) return false;
+  } catch {
+    return false;
+  }
+  return existsSync(join(electronDir, 'dist', platformPath));
+}
+
+function extractZip(zipPath, destDir) {
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  if (process.platform === 'win32') {
+    execFileSync(
+      'powershell',
+      ['-NoProfile', '-NonInteractive', '-Command', `Expand-Archive -Path "${zipPath}" -DestinationPath "${destDir}" -Force`],
+      { stdio: 'ignore' }
+    );
+  } else {
+    // `unzip` ships with macOS and virtually every Linux base image.
+    execFileSync('unzip', ['-q', '-o', zipPath, '-d', destDir], { stdio: 'ignore' });
+  }
+}
+
+function installElectron(range) {
+  const spec = `electron@${range || 'latest'}`;
+  log(`Electron not found; installing ${spec} (devDependency is skipped by production/npx installs)…`);
+  // --no-save: don't touch package.json; install into this package's node_modules.
+  execFileSync(
+    'npm',
+    ['install', spec, '--no-save', '--no-audit', '--no-fund', '--loglevel', 'error'],
+    { cwd: projectDir, stdio: 'inherit', env: { ...process.env, npm_config_save: 'false' } }
+  );
+}
+
+async function main() {
+  if (process.env.ELECTRON_SKIP_BINARY_DOWNLOAD) {
+    return; // user opted out of the binary entirely
+  }
+
+  const platform = process.env.npm_config_platform || process.platform;
+  const arch = process.env.npm_config_arch || process.arch;
+  const platformPath = platformBinaryPath(platform);
+  if (!platformPath) {
+    log(`Unsupported platform "${platform}"; leaving Electron untouched.`);
+    return;
+  }
+
+  // ---- Job 1: ensure the Electron package is present ----
+  let electronDir = resolveElectronDir();
+  if (electronDir == null) {
+    const range = declaredElectronRange();
+    if (range == null) {
+      return; // we don't declare Electron at all — nothing to do
+    }
+    try {
+      installElectron(range);
+    } catch (err) {
+      log(`Could not install Electron automatically: ${err.message}`);
+      log('Install it manually with `npm install electron`, then re-run.');
+      return;
+    }
+    electronDir = resolveElectronDir();
+    if (electronDir == null) {
+      log('Electron still not resolvable after install; aborting (best-effort).');
+      return;
+    }
+  }
+
+  const { version } = require(join(electronDir, 'package.json'));
+
+  // ---- Job 2: ensure the binary is actually extracted ----
+  if (isInstalled(electronDir, version, platformPath)) {
+    return; // healthy — silent no-op (the common dev-repo case)
+  }
+
+  log(`Electron ${version} is not fully extracted; repairing (Node ${process.version} extract-zip workaround)…`);
+
+  let zipPath;
+  try {
+    const getRequire = createRequire(join(electronDir, 'package.json'));
+    const { downloadArtifact } = getRequire('@electron/get');
+    let checksums;
+    try {
+      checksums = getRequire(join(electronDir, 'checksums.json'));
+    } catch {
+      checksums = undefined;
+    }
+    zipPath = await downloadArtifact({ version, artifactName: 'electron', platform, arch, checksums });
+  } catch (err) {
+    log(`Could not obtain the Electron zip: ${err.message}`);
+    log('Run `npm rebuild electron` (Node 22 or earlier), or reinstall, to fix.');
+    return;
+  }
+
+  const distDir = join(electronDir, 'dist');
+  try {
+    extractZip(zipPath, distDir);
+    const srcTypeDef = join(distDir, 'electron.d.ts');
+    if (existsSync(srcTypeDef)) {
+      renameSync(srcTypeDef, join(electronDir, 'electron.d.ts'));
+    }
+    writeFileSync(join(electronDir, 'path.txt'), platformPath);
+  } catch (err) {
+    log(`Extraction failed: ${err.message}`);
+    log('Ensure `unzip` (macOS/Linux) or PowerShell (Windows) is available, then reinstall.');
+    return;
+  }
+
+  if (isInstalled(electronDir, version, platformPath)) {
+    log('Electron ready.');
+  } else {
+    log('Repair did not produce a valid install; try `npm rebuild electron`.');
+  }
+}
+
+main().catch((err) => {
+  log(`Unexpected error (ignored): ${err.message}`);
+});

package/src/main/creator/conversionService.js

@@ -287,7 +287,7 @@ export async function runConversion(
     let llmStats = null;
     if (settingsManager && referenceLyrics) {
       try {
-        const llmSettings = llmService.getLLMSettings(settingsManager);
+        const llmSettings = llmService.getLLMSettingsRaw(settingsManager);
         // Local LLM (lmstudio) doesn't require API key
         const hasValidConfig = llmSettings.provider === 'lmstudio' || llmSettings.apiKey;
         if (llmSettings.enabled && hasValidConfig) {

package/src/main/creator/llmService.js

@@ -297,13 +297,49 @@ function parseCorrection(llmResponse, originalOutput) {
 }
 
 /**
- * Get LLM settings from app settings
- * Uses unified defaults from shared/defaults.js
+ * Whether an API key value is a masked placeholder (contains the bullet char
+ * used by getLLMSettings) rather than a real key. Real keys are ASCII, so any
+ * occurrence of '•' (U+2022) means it came from the masked, renderer-facing
+ * settings and must never be used as a real key or persisted.
  */
-export function getLLMSettings(settingsManager) {
+function isMaskedApiKey(key) {
+  return typeof key === 'string' && key.includes('•');
+}
+
+/**
+ * Read the real (unmasked) stored API key.
+ */
+function getStoredApiKey(settingsManager) {
+  const llmConfig = settingsManager.get('creator.llm', {});
+  return llmConfig.apiKey || LLM_DEFAULTS.apiKey || '';
+}
+
+/**
+ * Get LLM settings with the REAL API key, for internal main-process use
+ * (actual API calls). Never send this to the renderer.
+ */
+export function getLLMSettingsRaw(settingsManager) {
   const llmConfig = settingsManager.get('creator.llm', {});
   const apiKey = llmConfig.apiKey || LLM_DEFAULTS.apiKey;
 
+  return {
+    enabled: llmConfig.enabled ?? LLM_DEFAULTS.enabled,
+    provider: llmConfig.provider || LLM_DEFAULTS.provider,
+    model: llmConfig.model || getDefaultModel(llmConfig.provider),
+    apiKey,
+    hasApiKey: Boolean(apiKey),
+    baseUrl: llmConfig.baseUrl || LLM_DEFAULTS.baseUrl,
+  };
+}
+
+/**
+ * Get LLM settings from app settings, with the API key MASKED for the renderer.
+ * Uses unified defaults from shared/defaults.js
+ */
+export function getLLMSettings(settingsManager) {
+  const raw = getLLMSettingsRaw(settingsManager);
+  const { apiKey } = raw;
+
   // SECURITY FIX (#25): Mask API key - only show last 4 chars to renderer
   const maskedApiKey =
     apiKey && apiKey.length > 8
@@ -313,20 +349,36 @@ export function getLLMSettings(settingsManager) {
         : '';
 
   return {
-    enabled: llmConfig.enabled ?? LLM_DEFAULTS.enabled,
-    provider: llmConfig.provider || LLM_DEFAULTS.provider,
-    model: llmConfig.model || getDefaultModel(llmConfig.provider),
+    ...raw,
     apiKey: maskedApiKey,
-    hasApiKey: Boolean(apiKey), // Let renderer know if key is set
-    baseUrl: llmConfig.baseUrl || LLM_DEFAULTS.baseUrl,
   };
 }
 
 /**
- * Save LLM settings
+ * Resolve runtime settings coming from the renderer into settings with a REAL
+ * API key. If the renderer sent back the masked placeholder (key unchanged),
+ * substitute the stored real key. Used before any actual API call.
+ */
+export function resolveRuntimeSettings(settingsManager, settings) {
+  if (isMaskedApiKey(settings.apiKey)) {
+    return { ...settings, apiKey: getStoredApiKey(settingsManager) };
+  }
+  return settings;
+}
+
+/**
+ * Save LLM settings. Never persist a masked placeholder key over the real one:
+ * if the renderer didn't change the key, keep the stored value.
  */
 export function saveLLMSettings(settingsManager, llmSettings) {
-  settingsManager.set('creator.llm', llmSettings);
+  const next = { ...llmSettings };
+  delete next.hasApiKey; // renderer-only helper field, not real config
+
+  if (isMaskedApiKey(next.apiKey)) {
+    next.apiKey = getStoredApiKey(settingsManager);
+  }
+
+  settingsManager.set('creator.llm', next);
 }
 
 /**

package/src/main/handlers/creatorHandlers.js

@@ -151,9 +151,11 @@ export function registerCreatorHandlers(mainApp) {
     return { success: true };
   });
 
-  // Test LLM connection
+  // Test LLM connection. The renderer may send back the masked key (unchanged);
+  // resolve it to the real stored key before calling the provider.
   ipcMain.handle(CREATOR_CHANNELS.TEST_LLM_CONNECTION, (_event, settings) => {
-    return llmService.testLLMConnection(settings);
+    const resolved = llmService.resolveRuntimeSettings(mainApp.settings, settings);
+    return llmService.testLLMConnection(resolved);
   });
 
   log('✅ Creator handlers registered');

package/src/main/handlers/index.js

@@ -39,6 +39,8 @@ import { registerAutotuneHandlers } from './autotuneHandlers.js';
 log('✓ autotuneHandlers');
 import { registerCreatorHandlers } from './creatorHandlers.js';
 log('✓ creatorHandlers');
+import { registerStreamingHandlers } from './streamingHandlers.js';
+log('✓ streamingHandlers');
 
 /**
  * Register all IPC handlers
@@ -72,6 +74,9 @@ export function registerAllHandlers(mainApp) {
     // Creator handlers
     registerCreatorHandlers(mainApp);
 
+    // Streaming (browser viewer) handlers
+    registerStreamingHandlers(mainApp);
+
     log('✅ All IPC handlers registered');
   } catch (error) {
     console.error('❌ Failed to register IPC handlers:', error);

package/src/main/handlers/streamingHandlers.js

@@ -0,0 +1,70 @@
+import { log } from '../logger.js';
+import { ipcMain, shell } from 'electron';
+
+/**
+ * Streaming IPC Handlers
+ *
+ * Bridges signaling between the embedded web server's Socket.IO (admin-authed
+ * `viewer-clients` room) and the renderer-side StreamingSender. Also exposes a
+ * helper for opening the viewer URL in the system browser.
+ */
+
+/**
+ * Register all streaming-related IPC handlers.
+ * @param {Object} mainApp - Main application instance
+ */
+export function registerStreamingHandlers(mainApp) {
+  // Compute the URL the admin should open to view the stream.
+  const getViewerUrl = () => {
+    const port = mainApp.webServer?.port;
+    if (!port) return null;
+    // Use loopback by default; admin can manually substitute the LAN IP when
+    // pointing a TV/phone browser at this URL.
+    return `http://localhost:${port}/viewer`;
+  };
+
+  ipcMain.handle('streaming:getViewerUrl', () => {
+    return { url: getViewerUrl() };
+  });
+
+  ipcMain.handle('streaming:openViewer', async () => {
+    const url = getViewerUrl();
+    if (!url) {
+      return { success: false, error: 'Web server not running' };
+    }
+    try {
+      await shell.openExternal(url);
+      return { success: true, url };
+    } catch (err) {
+      log('Failed to open viewer URL:', err);
+      return { success: false, error: err.message };
+    }
+  });
+
+  // Renderer → web server: forward an offer to a specific viewer socket
+  ipcMain.handle('streaming:sendViewerOffer', (_event, { viewerId, offer }) => {
+    mainApp.webServer?.sendToViewer?.(viewerId, 'viewer:offer', { offer });
+  });
+
+  // Renderer → web server: forward an ICE candidate to a specific viewer socket
+  ipcMain.handle('streaming:sendViewerICE', (_event, { viewerId, candidate }) => {
+    mainApp.webServer?.sendToViewer?.(viewerId, 'viewer:ice', { candidate });
+  });
+
+  // Stats for debugging
+  ipcMain.handle('streaming:getStats', () => {
+    const count = mainApp.webServer?.getViewerCount?.() ?? 0;
+    return { viewerCount: count };
+  });
+}
+
+/**
+ * Forward signaling events from the web server (called from webServer.js
+ * when a viewer socket sends an event) to the main renderer where the
+ * StreamingSender lives.
+ */
+export function forwardViewerEvent(mainApp, event, payload) {
+  if (mainApp.mainWindow && !mainApp.mainWindow.isDestroyed()) {
+    mainApp.mainWindow.webContents.send(`streaming:${event}`, payload);
+  }
+}

package/src/main/preload.js

@@ -96,6 +96,31 @@ const api = {
     sendFrame: (dataUrl) => ipcRenderer.invoke('canvas:sendFrame', dataUrl),
   },
 
+  streaming: {
+    // Open the browser viewer URL via the system browser
+    openViewer: () => ipcRenderer.invoke('streaming:openViewer'),
+    // Get the viewer URL (for showing in UI without opening)
+    getViewerUrl: () => ipcRenderer.invoke('streaming:getViewerUrl'),
+
+    // Outbound signaling to viewers (sent through the web server's Socket.IO)
+    sendViewerOffer: ({ viewerId, offer }) =>
+      ipcRenderer.invoke('streaming:sendViewerOffer', { viewerId, offer }),
+    sendViewerICE: ({ viewerId, candidate }) =>
+      ipcRenderer.invoke('streaming:sendViewerICE', { viewerId, candidate }),
+
+    // Inbound signaling from viewers (forwarded from the web server)
+    onViewerJoin: (callback) =>
+      ipcRenderer.on('streaming:viewerJoin', (_e, payload) => callback(payload)),
+    onViewerAnswer: (callback) =>
+      ipcRenderer.on('streaming:viewerAnswer', (_e, payload) => callback(payload)),
+    onViewerICE: (callback) =>
+      ipcRenderer.on('streaming:viewerICE', (_e, payload) => callback(payload)),
+    onViewerLeave: (callback) =>
+      ipcRenderer.on('streaming:viewerLeave', (_e, payload) => callback(payload)),
+
+    getStats: () => ipcRenderer.invoke('streaming:getStats'),
+  },
+
   library: {
     getSongsFolder: () => ipcRenderer.invoke('library:getSongsFolder'),
     setSongsFolder: () => ipcRenderer.invoke('library:setSongsFolder'),
@@ -188,10 +213,16 @@ const api = {
     sendWebRTCResponse: (command, result) => {
       // SECURITY FIX (#24): Whitelist allowed WebRTC commands to prevent IPC channel injection
       const ALLOWED_COMMANDS = [
+        // Receiver side (canvas window)
         'setupReceiver',
         'checkReceiverReady',
         'setOfferAndCreateAnswer',
         'getReceiverStatus',
+        // Sender side (main window)
+        'setupSender',
+        'createOffer',
+        'setAnswer',
+        'getSenderStatus',
       ];
       if (!ALLOWED_COMMANDS.includes(command)) {
         console.warn('Blocked invalid WebRTC command:', command);

package/src/main/webServer.js

@@ -7,6 +7,7 @@ import os from 'os';
 import crypto from 'crypto';
 import bcrypt from 'bcryptjs';
 import cookieSession from 'cookie-session';
+import Keygrip from 'keygrip';
 import { Server } from 'socket.io';
 import http from 'http';
 import rateLimit from 'express-rate-limit';
@@ -24,6 +25,7 @@ import { getSetting } from '../shared/services/settingsService.js';
 import * as serverSettingsService from '../shared/services/serverSettingsService.js';
 import * as creatorService from '../shared/services/creatorService.js';
 import { validateSongPath, validateBase64Path } from './utils/pathValidator.js';
+import { forwardViewerEvent } from './handlers/streamingHandlers.js';
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -54,10 +56,30 @@ class WebServer {
     this.songPathToId = new Map();
     this.songIdToPath = new Map();
 
+    // Viewer sockets keyed by viewerId for WebRTC signaling
+    this.viewerSockets = new Map();
+
     this.setupMiddleware();
     this.setupRoutes();
   }
 
+  /**
+   * Send a Socket.IO event to a specific viewer by id.
+   * Called from streamingHandlers when the renderer-side sender produces
+   * an offer or ICE candidate for that viewer.
+   */
+  sendToViewer(viewerId, event, payload) {
+    const socket = this.viewerSockets.get(viewerId);
+    if (socket) {
+      socket.emit(event, payload);
+    }
+  }
+
+  /** Number of currently connected, authenticated viewer sockets. */
+  getViewerCount() {
+    return this.viewerSockets.size;
+  }
+
   /**
    * Generate an opaque ID for a song path (security: don't expose file paths)
    * Uses a deterministic hash so the same path always gets the same ID
@@ -313,6 +335,20 @@ class WebServer {
       }
     });
 
+    // Browser viewer page — admin-auth gated. Unlike requireAuth (which is
+    // for API endpoints and returns JSON 401), redirect unauthenticated
+    // browsers to the admin login UI so the user gets a sensible flow.
+    const requireAuthOrRedirect = (req, res, next) => {
+      if (req.session && req.session.isAdmin) {
+        next();
+      } else {
+        res.redirect('/admin');
+      }
+    };
+    this.app.get('/viewer', requireAuthOrRedirect, (req, res) => {
+      res.sendFile(path.join(__dirname, '../../static/viewer.html'));
+    });
+
     // Get available letters for alphabet navigation
     this.app.get('/api/letters', async (req, res) => {
       try {
@@ -2025,6 +2061,23 @@ class WebServer {
           socket.join('electron-apps');
         } else if (data.type === 'web-ui') {
           socket.join('web-clients');
+        } else if (data.type === 'viewer') {
+          // Viewer (browser tab opened from "Open Viewer" admin action) — auth-gated.
+          const session = this.validateSocketSession(socket);
+          if (!session || !session.isAdmin) {
+            console.warn('⚠️ Unauthorized viewer connection attempt:', socket.id);
+            socket.emit('auth-error', { message: 'Admin authentication required' });
+            return;
+          }
+          const viewerId = socket.id;
+          socket.viewerId = viewerId;
+          socket.join('viewer-clients');
+          this.viewerSockets.set(viewerId, socket);
+          log(`🎥 Viewer connected: ${viewerId}`);
+          socket.emit('viewer:ready');
+          // Tell the renderer-side StreamingSender to build a peer connection
+          // and send an offer back through us for this viewer.
+          forwardViewerEvent(this.mainApp, 'viewerJoin', { viewerId });
         } else if (data.type === 'admin') {
           // SECURITY FIX (#22): Validate admin session before allowing admin room access
           const session = this.validateSocketSession(socket);
@@ -2062,9 +2115,33 @@ class WebServer {
         }
       });
 
+      // Viewer signaling (answer + ICE candidates from the browser viewer)
+      socket.on('viewer:answer', ({ answer }) => {
+        if (socket.viewerId && this.viewerSockets.has(socket.viewerId)) {
+          forwardViewerEvent(this.mainApp, 'viewerAnswer', {
+            viewerId: socket.viewerId,
+            answer,
+          });
+        }
+      });
+
+      socket.on('viewer:ice', ({ candidate }) => {
+        if (socket.viewerId && this.viewerSockets.has(socket.viewerId)) {
+          forwardViewerEvent(this.mainApp, 'viewerICE', {
+            viewerId: socket.viewerId,
+            candidate,
+          });
+        }
+      });
+
       // Handle disconnection
       socket.on('disconnect', () => {
         log('Client disconnected:', socket.id);
+        if (socket.viewerId && this.viewerSockets.has(socket.viewerId)) {
+          this.viewerSockets.delete(socket.viewerId);
+          forwardViewerEvent(this.mainApp, 'viewerLeave', { viewerId: socket.viewerId });
+          log(`🎥 Viewer disconnected: ${socket.viewerId}`);
+        }
       });
 
       // Song request events
@@ -2520,7 +2597,6 @@ class WebServer {
       }
 
       // Verify signature using Keygrip (same mechanism as cookie-session)
-      const Keygrip = require('keygrip');
       const keys = new Keygrip([this.getOrCreateSecretKey()]);
 
       if (!keys.verify('kai-admin-session=' + sessionCookie, sigCookie)) {