lightman-agent 1.0.22 → 1.0.24

package/scripts/lightman-shell.bat

@@ -15,6 +15,7 @@ REM ================================================================
 
 set INSTALL_DIR=C:\Program Files\Lightman\Agent
 set CONFIG_FILE=%INSTALL_DIR%\agent.config.json
+set URL_SIDECAR=C:\ProgramData\Lightman\kiosk-url.txt
 set CHROME_DATA=C:\ProgramData\Lightman\chrome-kiosk
 set LOG_FILE=C:\ProgramData\Lightman\logs\shell.log
 
@@ -68,14 +69,27 @@ if not "%DEVICE_SLUG%"=="" (
     echo [%date% %time%] WARNING: No slug in config! >> "%LOG_FILE%"
 )
 
+REM If agent wrote a URL sidecar (includes deviceId/apiKey), prefer it.
+if exist "%URL_SIDECAR%" (
+    for /f "usebackq delims=" %%u in ("%URL_SIDECAR%") do set SIDE_URL=%%u
+    if not "%SIDE_URL%"=="" (
+        set URL=%SIDE_URL%
+        echo [%date% %time%] Using sidecar URL >> "%LOG_FILE%"
+    )
+)
+
 REM Fallback browser
 if "%BROWSER%"=="" (
     if exist "C:\Program Files\Google\Chrome\Application\chrome.exe" (
         set "BROWSER=C:\Program Files\Google\Chrome\Application\chrome.exe"
     ) else if exist "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" (
         set "BROWSER=C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"
+    ) else if exist "C:\Program Files\Microsoft\Edge\Application\msedge.exe" (
+        set "BROWSER=C:\Program Files\Microsoft\Edge\Application\msedge.exe"
+    ) else if exist "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" (
+        set "BROWSER=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
     ) else (
-        echo [%date% %time%] ERROR: Chrome not found! >> "%LOG_FILE%"
+        echo [%date% %time%] ERROR: No supported kiosk browser found! >> "%LOG_FILE%"
         start explorer.exe
         exit /b 1
     )
@@ -109,20 +123,27 @@ REM ----------------------------------------------------------------
 REM Infinite Chrome loop
 REM ----------------------------------------------------------------
 :loop
-    REM Re-read slug from config on every loop iteration
-    REM This way if someone changes agent.config.json, the next
-    REM Chrome restart picks up the new slug automatically.
-    if exist "%CONFIG_FILE%" (
-        for /f "delims=" %%a in ('node -e "try{console.log(JSON.parse(require('fs').readFileSync(String.raw`%CONFIG_FILE%`,'utf8')).deviceSlug)}catch(e){console.log('')}" 2^>nul') do (
-            if not "%%a"=="" set URL=http://localhost:3403/display/%%a
+    REM Prefer sidecar URL for auth params/device routing; fallback to slug URL.
+    set SIDE_URL=
+    if exist "%URL_SIDECAR%" (
+        for /f "usebackq delims=" %%u in ("%URL_SIDECAR%") do set SIDE_URL=%%u
+    )
+    if not "%SIDE_URL%"=="" (
+        set URL=%SIDE_URL%
+    ) else (
+        REM Re-read slug from config on every loop iteration.
+        if exist "%CONFIG_FILE%" (
+            for /f "delims=" %%a in ('node -e "try{console.log(JSON.parse(require('fs').readFileSync(String.raw`%CONFIG_FILE%`,'utf8')).deviceSlug)}catch(e){console.log('')}" 2^>nul') do (
+                if not "%%a"=="" set URL=http://localhost:3403/display/%%a
+            )
         )
     )
 
-    echo [%date% %time%] Launching Chrome: %URL% >> "%LOG_FILE%"
+    echo [%date% %time%] Launching browser: %URL% >> "%LOG_FILE%"
 
     start /wait "" "%BROWSER%" --kiosk --noerrdialogs --disable-infobars --disable-session-crashed-bubble --no-first-run --no-default-browser-check --start-fullscreen --disable-translate --disable-extensions --autoplay-policy=no-user-gesture-required --disable-features=TranslateUI --user-data-dir="%CHROME_DATA%" "%URL%"
 
-    echo [%date% %time%] Chrome exited (code: %errorlevel%). Restarting in 3s... >> "%LOG_FILE%"
+    echo [%date% %time%] Browser exited (code: %errorlevel%). Restarting in 3s... >> "%LOG_FILE%"
     timeout /t 3 /nobreak >nul
 
 goto loop

package/scripts/setup.ps1

@@ -2,8 +2,8 @@
 # Generates agent.config.json for this specific device.
 #
 # Usage (run from agent directory or scripts directory):
-#   powershell -ExecutionPolicy Bypass -File setup.ps1 -Slug "f-av01" -Server "http://192.168.1.100:3401"
-#   powershell -ExecutionPolicy Bypass -File setup.ps1 -Slug "f-av01" -Server "http://192.168.1.100:3401" -Timezone "Asia/Kolkata"
+#   powershell -ExecutionPolicy Bypass -File setup.ps1 -Slug "f-av01" -Server "http://192.168.10.100:3401"
+#   powershell -ExecutionPolicy Bypass -File setup.ps1 -Slug "f-av01" -Server "http://192.168.10.100:3401" -Timezone "Asia/Kolkata"
 #
 # This script MUST be run once on every new device installation.
 # It clears any cached identity so the device provisions fresh.
@@ -42,6 +42,23 @@ Write-Host "  Install dir: $InstallDir"
 Write-Host "  Timezone:    $Timezone"
 Write-Host ""
 
+function Get-KioskBrowserPath {
+    $candidates = @(
+        "C:\Program Files\Google\Chrome\Application\chrome.exe",
+        "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+        (Join-Path $env:LOCALAPPDATA "Google\Chrome\Application\chrome.exe"),
+        "C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+        "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+        (Join-Path $env:LOCALAPPDATA "Microsoft\Edge\Application\msedge.exe")
+    ) | Where-Object { $_ -and (Test-Path $_) }
+
+    if ($candidates.Count -gt 0) {
+        return $candidates[0]
+    }
+
+    throw "Neither Google Chrome nor Microsoft Edge was found. Install one of them and re-run setup."
+}
+
 # 1. Clear cached identity (CRITICAL - prevents old device credentials leaking)
 $IdentityFile = Join-Path $InstallDir ".lightman-identity.json"
 if (Test-Path $IdentityFile) {
@@ -55,13 +72,12 @@ if (Test-Path $IdentityFile) {
 $KioskUrl  = "http://localhost:3403/display/$Slug"
 
 # 3. Detect browser path
-$BrowserPath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
-if (-not (Test-Path $BrowserPath)) {
-    $BrowserPath = "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"
-}
-if (-not (Test-Path $BrowserPath)) {
-    $BrowserPath = "chromium-browser"
-    Write-Host "[WARN] Chrome not found - using 'chromium-browser'" -ForegroundColor Yellow
+try {
+    $BrowserPath = Get-KioskBrowserPath
+    Write-Host "[OK] Using kiosk browser: $BrowserPath" -ForegroundColor Green
+} catch {
+    Write-Host "[ERROR] $($_.Exception.Message)" -ForegroundColor Red
+    exit 1
 }
 
 $ChromeDataDir = "C:\ProgramData\Lightman\chrome-kiosk"

package/scripts/setup.sh

@@ -3,8 +3,8 @@
 # Generates agent.config.json for this specific device.
 #
 # Usage:
-#   sudo bash setup.sh --slug f-av01 --server http://192.168.1.100:3401
-#   sudo bash setup.sh --slug f-av01 --server http://192.168.1.100:3401 --timezone Asia/Kolkata --dir /opt/lightman/agent
+#   sudo bash setup.sh --slug f-av01 --server http://192.168.10.100:3401
+#   sudo bash setup.sh --slug f-av01 --server http://192.168.10.100:3401 --timezone Asia/Kolkata --dir /opt/lightman/agent
 #
 # This script MUST be run once on every new device installation.
 # It clears any cached identity so the device provisions fresh.
@@ -37,13 +37,13 @@ done
 
 if [[ -z "$SLUG" ]]; then
     echo "Error: --slug is required"
-    echo "Usage: bash setup.sh --slug f-av01 --server http://192.168.1.100:3401"
+    echo "Usage: bash setup.sh --slug f-av01 --server http://192.168.10.100:3401"
     exit 1
 fi
 
 if [[ -z "$SERVER" ]]; then
     echo "Error: --server is required"
-    echo "Usage: bash setup.sh --slug f-av01 --server http://192.168.1.100:3401"
+    echo "Usage: bash setup.sh --slug f-av01 --server http://192.168.10.100:3401"
     exit 1
 fi
 

package/src/index.ts

@@ -10,11 +10,11 @@ import { KioskManager } from './services/kiosk.js';
 import { registerPowerCommands } from './commands/power.js';
 import { registerKioskCommands, registerMultiScreenKioskCommands } from './commands/kiosk.js';
 import { registerScreenshotCommands } from './commands/screenshot.js';
-import { MultiScreenKioskManager } from './services/multiScreenKiosk.js';
-import { detectScreens } from './lib/screens.js';
-import type { DetectedScreen } from './lib/screens.js';
-import { resolveScreenMap } from './lib/screenMap.js';
-import { registerDisplayCommands } from './commands/display.js';
+import { MultiScreenKioskManager } from './services/multiScreenKiosk.js';
+import { detectScreens } from './lib/screens.js';
+import type { DetectedScreen } from './lib/screens.js';
+import { resolveScreenMap } from './lib/screenMap.js';
+import { registerDisplayCommands } from './commands/display.js';
 import { registerNetworkCommands } from './commands/network.js';
 import { Updater } from './services/updater.js';
 import { registerUpdateCommands } from './commands/update.js';
@@ -32,7 +32,7 @@ import { SerialBridge } from './services/serialBridge.js';
 import { OscBridge } from './services/oscBridge.js';
 import { LocalEventServer } from './services/localEvents.js';
 import { PresenceSensor } from './services/presenceSensor.js';
-import type { WsMessage, KioskConfig, PowerScheduleConfig, Identity, ScreenMapping } from './lib/types.js';
+import type { WsMessage, KioskConfig, PowerScheduleConfig, Identity, ScreenMapping } from './lib/types.js';
 
 function getAgentVersion(): string {
   try {
@@ -111,10 +111,26 @@ async function main(): Promise<void> {
     serverUrl: config.serverUrl,
     identity,
     logger,
-    onMessage: (msg: WsMessage) => {
-      handleServerMessage(msg, commandExecutor, logger, powerScheduler, startSerialBridge, stopSerialBridge, startOscBridge, stopOscBridge, multiScreenKiosk, getIdentity, kioskManager, watchdog, startPresenceSensor, stopPresenceSensor);
-    },
-  });
+    onMessage: (msg: WsMessage) => {
+      handleServerMessage(
+        msg,
+        commandExecutor,
+        logger,
+        powerScheduler,
+        startSerialBridge,
+        stopSerialBridge,
+        startOscBridge,
+        stopOscBridge,
+        multiScreenKiosk,
+        getIdentity,
+        kioskManager,
+        watchdog,
+        startPresenceSensor,
+        stopPresenceSensor,
+        () => lastKnownTotalScreens
+      );
+    },
+  });
 
   // 4. Start health monitor
   const healthMonitor = new HealthMonitor(
@@ -163,65 +179,66 @@ async function main(): Promise<void> {
   const kioskManager = new KioskManager(kioskConfig, logger);
   registerKioskCommands(commandExecutor.register.bind(commandExecutor), kioskManager, logger);
 
-  // Multi-screen kiosk manager — handles multiple Chrome instances on multi-display devices
-  const multiScreenKiosk = new MultiScreenKioskManager(kioskConfig, logger);
-  const getIdentity = () => identity!;
-  registerMultiScreenKioskCommands(commandExecutor.register.bind(commandExecutor), multiScreenKiosk, getIdentity, logger);
-
+  // Multi-screen kiosk manager — handles multiple Chrome instances on multi-display devices
+  const multiScreenKiosk = new MultiScreenKioskManager(kioskConfig, logger);
+  const getIdentity = () => identity!;
+  registerMultiScreenKioskCommands(commandExecutor.register.bind(commandExecutor), multiScreenKiosk, getIdentity, logger);
+
   // Detect physical screens and keep them fresh (multi-display setups can change after boot).
+  let lastKnownTotalScreens = 0;
   let detectedScreens = detectScreens(logger);
   multiScreenKiosk.setDetectedScreens(detectedScreens);
-
-  const toScreenPayload = (screens: DetectedScreen[]) => (
-    screens.map((s) => ({
-      hardwareId: s.hardwareId,
-      name: s.name,
-      index: s.index,
-      width: s.width,
-      height: s.height,
-      x: s.x,
-      y: s.y,
-      primary: s.primary,
-    }))
-  );
-
-  const sendAgentRegister = () => {
-    wsClient.send({
-      type: 'agent:register',
-      payload: {
-        agentVersion: getAgentVersion(),
-        screens: toScreenPayload(detectedScreens),
-      },
-      timestamp: Date.now(),
-    });
-  };
-
-  const refreshDetectedScreens = async (reason: string) => {
-    const latest = detectScreens(logger);
-    if (!haveScreensChanged(detectedScreens, latest)) return;
-
-    logger.info(`[Screens] Topology changed (${reason}): ${detectedScreens.length} -> ${latest.length}`);
-    detectedScreens = latest;
-    multiScreenKiosk.setDetectedScreens(detectedScreens);
-
-    if (wsClient.isConnected()) {
-      sendAgentRegister();
-    }
-
-    if (multiScreenKiosk.hasDesiredScreenMap()) {
-      try {
-        await multiScreenKiosk.reapplyDesiredMap(identity);
-      } catch (err) {
-        logger.error('[MultiKiosk] Failed to reapply desired screen map after topology change:', err);
-      }
-    }
-  };
-
-  const screenRefreshInterval = setInterval(() => {
-    refreshDetectedScreens('periodic-refresh').catch((err) => {
-      logger.error('[Screens] Periodic refresh failed:', err);
-    });
-  }, 20_000);
+
+  const toScreenPayload = (screens: DetectedScreen[]) => (
+    screens.map((s) => ({
+      hardwareId: s.hardwareId,
+      name: s.name,
+      index: s.index,
+      width: s.width,
+      height: s.height,
+      x: s.x,
+      y: s.y,
+      primary: s.primary,
+    }))
+  );
+
+  const sendAgentRegister = () => {
+    wsClient.send({
+      type: 'agent:register',
+      payload: {
+        agentVersion: getAgentVersion(),
+        screens: toScreenPayload(detectedScreens),
+      },
+      timestamp: Date.now(),
+    });
+  };
+
+  const refreshDetectedScreens = async (reason: string) => {
+    const latest = detectScreens(logger);
+    if (!haveScreensChanged(detectedScreens, latest)) return;
+
+    logger.info(`[Screens] Topology changed (${reason}): ${detectedScreens.length} -> ${latest.length}`);
+    detectedScreens = latest;
+    multiScreenKiosk.setDetectedScreens(detectedScreens);
+
+    if (wsClient.isConnected()) {
+      sendAgentRegister();
+    }
+
+    if (multiScreenKiosk.hasDesiredScreenMap()) {
+      try {
+        await multiScreenKiosk.reapplyDesiredMap(identity);
+      } catch (err) {
+        logger.error('[MultiKiosk] Failed to reapply desired screen map after topology change:', err);
+      }
+    }
+  };
+
+  const screenRefreshInterval = setInterval(() => {
+    refreshDetectedScreens('periodic-refresh').catch((err) => {
+      logger.error('[Screens] Periodic refresh failed:', err);
+    });
+  }, 20_000);
 
   // Create Watchdog (Phase 20)
   const watchdog = new Watchdog(
@@ -464,11 +481,11 @@ async function main(): Promise<void> {
   watchdog.start();
   powerScheduler.start();
 
-  // Send registration message once connected, then auto-launch kiosk
-  const registerInterval = setInterval(() => {
-    if (wsClient.isConnected()) {
-      sendAgentRegister();
-      clearInterval(registerInterval);
+  // Send registration message once connected, then auto-launch kiosk
+  const registerInterval = setInterval(() => {
+    if (wsClient.isConnected()) {
+      sendAgentRegister();
+      clearInterval(registerInterval);
 
       // Fetch device config first to decide single vs multi-screen kiosk
       fetchDeviceConfig(config.serverUrl, identity, logger).then((deviceCfg) => {
@@ -499,31 +516,30 @@ async function main(): Promise<void> {
         } else {
           logger.info('[Presence] Template is not presence-enabled — sensor not started');
         }
-        // Multi-screen handling:
-        // 1) Use explicit screenMap when present.
-        // 2) For multi-screen apps without a saved map, auto-create placeholders.
+        // Multi-screen handling:
+        // 1) Use explicit screenMap when present.
+        // 2) For multi-screen apps without a saved map, auto-create placeholders.
         const requestedScreenMap = deviceCfg?.screenMap || [];
-        const isMultiScreenApp = !!deviceCfg && deviceCfg.totalScreens > 1;
-        const effectiveRequestedMap = requestedScreenMap.length > 0
-          ? requestedScreenMap
-          : (isMultiScreenApp ? createPlaceholderScreenMap(deviceCfg.totalScreens) : []);
+        const totalScreens = Math.max(deviceCfg?.totalScreens || 0, requestedScreenMap.length);
+        lastKnownTotalScreens = totalScreens;
+        const effectiveRequestedMap = normalizeScreenMapForTotalScreens(requestedScreenMap, totalScreens);
 
         if (effectiveRequestedMap.length > 0) {
           const resolved = resolveScreenMap({
             requestedScreenMap: effectiveRequestedMap,
             detectedScreens,
-            totalScreens: Math.max(deviceCfg?.totalScreens || 0, effectiveRequestedMap.length),
+            totalScreens,
           });
           logger.info(
-            `[MultiKiosk] Effective map ready: requested=${effectiveRequestedMap.length}, mode=${resolved.mode}, totalScreens=${deviceCfg?.totalScreens || 0}`
+            `[MultiKiosk] Effective map ready: requested=${requestedScreenMap.length}, effective=${effectiveRequestedMap.length}, mode=${resolved.mode}, totalScreens=${totalScreens}`
           );
           watchdog.setMultiScreenActive(true);
           multiScreenKiosk.applyScreenMap(effectiveRequestedMap, identity).catch((err) => {
             logger.error('[MultiKiosk] Failed to apply effective screenMap from config:', err);
-          });
-          return;
-        }
-
+          });
+          return;
+        }
+
         // No effective multi-screen map - launch single-screen kiosk as before
         if (config.kiosk) {
           if (config.kiosk.shellMode) {
@@ -552,10 +568,10 @@ async function main(): Promise<void> {
   }, 1000);
 
   // 7. Graceful shutdown
-  const shutdown = async (signal: string): Promise<void> => {
-    logger.info(`${signal} received. Shutting down...`);
-    clearInterval(registerInterval);
-    clearInterval(screenRefreshInterval);
+  const shutdown = async (signal: string): Promise<void> => {
+    logger.info(`${signal} received. Shutting down...`);
+    clearInterval(registerInterval);
+    clearInterval(screenRefreshInterval);
 
     // Wait for updater to finish if it's busy (max 60s)
     if (updater.isBusy()) {
@@ -603,50 +619,74 @@ async function main(): Promise<void> {
     process.exit(1);
   });
 
-  logger.info('LIGHTMAN Agent running.');
-}
-
+  logger.info('LIGHTMAN Agent running.');
+}
+
 function createPlaceholderScreenMap(totalScreens: number): ScreenMapping[] {
   const count = Math.max(0, Math.floor(totalScreens || 0));
   return Array.from({ length: count }, () => ({ hardwareId: '', url: '' }));
 }
 
-function haveScreensChanged(prev: DetectedScreen[], next: DetectedScreen[]): boolean {
-  if (prev.length !== next.length) return true;
-  for (let i = 0; i < prev.length; i++) {
-    const a = prev[i];
-    const b = next[i];
-    if (
-      a.hardwareId !== b.hardwareId
-      || a.index !== b.index
-      || a.x !== b.x
-      || a.y !== b.y
-      || a.width !== b.width
-      || a.height !== b.height
-      || a.primary !== b.primary
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
+function normalizeScreenMapForTotalScreens(
+  screenMap: ScreenMapping[] | undefined,
+  totalScreens: number
+): ScreenMapping[] {
+  const requested = Array.isArray(screenMap)
+    ? screenMap.map((m) => ({
+      hardwareId: String(m.hardwareId || ''),
+      url: String(m.url || ''),
+      ...(m.label ? { label: String(m.label) } : {}),
+    }))
+    : [];
 
+  const targetCount = Math.max(requested.length, Math.max(0, Math.floor(totalScreens || 0)));
+  if (targetCount === 0) return [];
+
+  if (requested.length >= targetCount) return requested;
+
+  return [
+    ...requested,
+    ...createPlaceholderScreenMap(targetCount - requested.length),
+  ];
+}
+
+function haveScreensChanged(prev: DetectedScreen[], next: DetectedScreen[]): boolean {
+  if (prev.length !== next.length) return true;
+  for (let i = 0; i < prev.length; i++) {
+    const a = prev[i];
+    const b = next[i];
+    if (
+      a.hardwareId !== b.hardwareId
+      || a.index !== b.index
+      || a.x !== b.x
+      || a.y !== b.y
+      || a.width !== b.width
+      || a.height !== b.height
+      || a.primary !== b.primary
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function handleServerMessage(
   msg: WsMessage,
-  commandExecutor: CommandExecutor,
+  commandExecutor: CommandExecutor,
   logger: Logger,
   powerScheduler?: PowerScheduler,
   startSerialBridge?: (comPort: string, controllerId: string, baudRate?: number) => void,
   stopSerialBridge?: () => void,
   startOscBridgeFn?: (oscPort: number, oscAddress: string, oscHost?: string) => void,
   stopOscBridgeFn?: () => void,
-  multiScreenKiosk?: MultiScreenKioskManager,
-  getIdentity?: () => Identity,
-  kioskManager?: KioskManager,
-  watchdog?: Watchdog,
-  startPresenceSensorFn?: (port?: string) => void,
-  stopPresenceSensorFn?: () => void
-): void {
+  multiScreenKiosk?: MultiScreenKioskManager,
+  getIdentity?: () => Identity,
+  kioskManager?: KioskManager,
+  watchdog?: Watchdog,
+  startPresenceSensorFn?: (port?: string) => void,
+  stopPresenceSensorFn?: () => void,
+  getTotalScreensHint?: () => number
+): void {
   switch (msg.type) {
     case 'connected':
       logger.info('Server acknowledged connection');
@@ -698,16 +738,25 @@ function handleServerMessage(
         }
 
         // Admin pushed updated screenMap via device config save
-        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
-        if (screenMap && Array.isArray(screenMap) && multiScreenKiosk && getIdentity) {
-          if (screenMap.length > 0) {
-            logger.info(`[MultiKiosk] Received screenMap update: ${screenMap.length} mapping(s) — killing single kiosk`);
-            if (kioskManager) kioskManager.kill().catch(() => {});
-            if (watchdog) watchdog.setMultiScreenActive(true);
-            multiScreenKiosk.applyScreenMap(screenMap, getIdentity()).catch((err) => {
-              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
-            });
-          } else {
+        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
+        if (screenMap && Array.isArray(screenMap) && multiScreenKiosk && getIdentity) {
+          const payloadTotalScreens = Number(msg.payload.totalScreens || 0);
+          const hintTotalScreens = Math.max(
+            Number.isFinite(payloadTotalScreens) ? payloadTotalScreens : 0,
+            getTotalScreensHint ? getTotalScreensHint() : 0
+          );
+          const effectiveScreenMap = screenMap.length > 0
+            ? normalizeScreenMapForTotalScreens(screenMap, hintTotalScreens)
+            : screenMap;
+
+          if (screenMap.length > 0) {
+            logger.info(`[MultiKiosk] Received screenMap update: requested=${screenMap.length}, effective=${effectiveScreenMap.length}, totalScreens=${hintTotalScreens} — killing single kiosk`);
+            if (kioskManager) kioskManager.kill().catch(() => {});
+            if (watchdog) watchdog.setMultiScreenActive(true);
+            multiScreenKiosk.applyScreenMap(effectiveScreenMap, getIdentity()).catch((err) => {
+              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
+            });
+          } else {
             // Empty screenMap — deactivate multi-screen, resume single kiosk
             logger.info('[MultiKiosk] Empty screenMap received — deactivating multi-screen');
             multiScreenKiosk.killAll().catch(() => {});
@@ -719,16 +768,25 @@ function handleServerMessage(
     case 'agent:screenMap':
       // Direct screenMap push from server
       if (msg.payload && multiScreenKiosk && getIdentity) {
-        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
-        if (screenMap && Array.isArray(screenMap)) {
-          if (screenMap.length > 0) {
-            logger.info(`[MultiKiosk] Received agent:screenMap: ${screenMap.length} mapping(s) — killing single kiosk`);
-            if (kioskManager) kioskManager.kill().catch(() => {});
-            if (watchdog) watchdog.setMultiScreenActive(true);
-            multiScreenKiosk.applyScreenMap(screenMap, getIdentity()).catch((err) => {
-              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
-            });
-          } else {
+        const screenMap = msg.payload.screenMap as ScreenMapping[] | undefined;
+        if (screenMap && Array.isArray(screenMap)) {
+          const payloadTotalScreens = Number(msg.payload.totalScreens || 0);
+          const hintTotalScreens = Math.max(
+            Number.isFinite(payloadTotalScreens) ? payloadTotalScreens : 0,
+            getTotalScreensHint ? getTotalScreensHint() : 0
+          );
+          const effectiveScreenMap = screenMap.length > 0
+            ? normalizeScreenMapForTotalScreens(screenMap, hintTotalScreens)
+            : screenMap;
+
+          if (screenMap.length > 0) {
+            logger.info(`[MultiKiosk] Received agent:screenMap: requested=${screenMap.length}, effective=${effectiveScreenMap.length}, totalScreens=${hintTotalScreens} — killing single kiosk`);
+            if (kioskManager) kioskManager.kill().catch(() => {});
+            if (watchdog) watchdog.setMultiScreenActive(true);
+            multiScreenKiosk.applyScreenMap(effectiveScreenMap, getIdentity()).catch((err) => {
+              logger.error('[MultiKiosk] Failed to apply screenMap:', err);
+            });
+          } else {
             logger.info('[MultiKiosk] Empty agent:screenMap — deactivating multi-screen');
             multiScreenKiosk.killAll().catch(() => {});
             if (watchdog) watchdog.setMultiScreenActive(false);
@@ -756,17 +814,17 @@ async function fetchDeviceConfig(
   serverUrl: string,
   identity: Identity,
   logger: Logger
-): Promise<{
-  comPort: string;
-  controllerId: string;
-  baudRate: number;
-  screenMap: ScreenMapping[];
-  totalScreens: number;
-  oscPort: number;
-  oscAddress: string;
-  oscHost: string;
-  templateType: string;
-} | null> {
+): Promise<{
+  comPort: string;
+  controllerId: string;
+  baudRate: number;
+  screenMap: ScreenMapping[];
+  totalScreens: number;
+  oscPort: number;
+  oscAddress: string;
+  oscHost: string;
+  templateType: string;
+} | null> {
   try {
     const url = `${serverUrl}/api/devices/${identity.deviceId}/config`;
     const res = await fetch(url, {
@@ -788,12 +846,12 @@ async function fetchDeviceConfig(
     const controllerId = (appConfig.controllerId as string) || comPort;
     const baudRate = (device?.baud_rate as number) || 115200;
 
-    // Screen map from device config (set by admin)
-    const screenMap = (device?.screenMap as ScreenMapping[]) || [];
-    const appScreens = (appConfig.screens as Array<Record<string, unknown>>) || [];
-    const totalScreens = appScreens.length > 0
-      ? appScreens.length
-      : ((appConfig.totalScreens as number) || 0);
+    // Screen map from device config (set by admin)
+    const screenMap = (device?.screenMap as ScreenMapping[]) || [];
+    const appScreens = (appConfig.screens as Array<Record<string, unknown>>) || [];
+    const totalScreens = appScreens.length > 0
+      ? appScreens.length
+      : ((appConfig.totalScreens as number) || 0);
 
     // OSC settings from app config (custom07-osc template)
     const inputSource = appConfig.inputSource as string;
@@ -803,7 +861,7 @@ async function fetchDeviceConfig(
 
     const templateType = (assignedApp?.templateType as string) || '';
 
-    return { comPort, controllerId, baudRate, screenMap, totalScreens, oscPort, oscAddress, oscHost, templateType };
+    return { comPort, controllerId, baudRate, screenMap, totalScreens, oscPort, oscAddress, oscHost, templateType };
   } catch (err) {
     logger.debug('Failed to fetch device config:', err);
     return null;