livedesk 0.1.149 → 0.1.151

package/README.md

@@ -24,6 +24,13 @@ The client signs in with Google, discovers the active Hub, and connects to the w
 On Windows, enable **Start with Windows** on the connection page to reconnect
 automatically after reboot.
 
+## Frame modes
+
+- Mode 2: independent 320x180 RGB565+LZO tiles for large, stable walls.
+- Mode 3: direct hardware H.264 for focused remote control up to 4K.
+- Mode 4: client Mode 2 inputs composited by an isolated Hub worker into one
+  1920x1080 H.264 Atlas stream for the browser wall.
+
 ## Plans
 
 - Free: 5 personal devices with a standard wall banner ad.

package/hub/package.json

@@ -14,8 +14,10 @@
     "check": "node --check src/server.js && node --check src/remote-hub.js"
   },
   "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",
+    "ffmpeg-static": "^5.3.0",
     "path-to-regexp": "0.1.13",
     "ws": "^8.18.3"
   },

package/hub/src/lzo1x.js

@@ -0,0 +1,109 @@
+function requireInput(input, index, length) {
+  if (length < 0 || index < 0 || index + length > input.length) {
+    throw new Error('Invalid LZO1X block: input overrun.');
+  }
+}
+
+function readExtendedLength(input, state, basis) {
+  let zeroBytes = 0;
+  while (true) {
+    requireInput(input, state.inputIndex, 1);
+    if (input[state.inputIndex] !== 0) break;
+    zeroBytes += 1;
+    state.inputIndex += 1;
+  }
+  const length = zeroBytes * 255 + basis + input[state.inputIndex];
+  state.inputIndex += 1;
+  return length;
+}
+
+function copyLiteral(input, state, output, length) {
+  requireInput(input, state.inputIndex, length);
+  if (state.outputIndex + length > output.length) {
+    throw new Error('Invalid LZO1X block: output overrun.');
+  }
+  output.set(input.subarray(state.inputIndex, state.inputIndex + length), state.outputIndex);
+  state.inputIndex += length;
+  state.outputIndex += length;
+}
+
+export function decodeLzo1xBlock(input, outputLength) {
+  if (!(input instanceof Uint8Array) || input.length < 3 || outputLength < 0) {
+    throw new Error('Invalid LZO1X block.');
+  }
+  const output = new Uint8Array(outputLength);
+  const cursor = { inputIndex: 0, outputIndex: 0 };
+  let state = 0;
+  let matchLength = 0;
+  if (input[cursor.inputIndex] >= 22) {
+    const length = input[cursor.inputIndex] - 17;
+    cursor.inputIndex += 1;
+    copyLiteral(input, cursor, output, length);
+    state = 4;
+  } else if (input[cursor.inputIndex] >= 18) {
+    state = input[cursor.inputIndex] - 17;
+    cursor.inputIndex += 1;
+    copyLiteral(input, cursor, output, state);
+  }
+  while (true) {
+    requireInput(input, cursor.inputIndex, 1);
+    const instruction = input[cursor.inputIndex++];
+    let nextState;
+    let matchIndex;
+    if ((instruction & 0xc0) !== 0) {
+      requireInput(input, cursor.inputIndex, 1);
+      matchIndex = cursor.outputIndex - ((input[cursor.inputIndex] << 3) + ((instruction >> 2) & 7) + 1);
+      cursor.inputIndex += 1;
+      matchLength = (instruction >> 5) + 1;
+      nextState = instruction & 3;
+    } else if ((instruction & 0x20) !== 0) {
+      matchLength = (instruction & 0x1f) + 2;
+      if (matchLength === 2) matchLength += readExtendedLength(input, cursor, 31);
+      requireInput(input, cursor.inputIndex, 2);
+      const encoded = input[cursor.inputIndex] | (input[cursor.inputIndex + 1] << 8);
+      cursor.inputIndex += 2;
+      matchIndex = cursor.outputIndex - ((encoded >> 2) + 1);
+      nextState = encoded & 3;
+    } else if ((instruction & 0x10) !== 0) {
+      matchLength = (instruction & 7) + 2;
+      if (matchLength === 2) matchLength += readExtendedLength(input, cursor, 7);
+      requireInput(input, cursor.inputIndex, 2);
+      const encoded = input[cursor.inputIndex] | (input[cursor.inputIndex + 1] << 8);
+      cursor.inputIndex += 2;
+      matchIndex = cursor.outputIndex - (((instruction & 8) << 11) + (encoded >> 2));
+      nextState = encoded & 3;
+      if (matchIndex === cursor.outputIndex) break;
+      matchIndex -= 0x4000;
+    } else if (state === 0) {
+      let length = instruction + 3;
+      if (length === 3) length += readExtendedLength(input, cursor, 15);
+      copyLiteral(input, cursor, output, length);
+      state = 4;
+      continue;
+    } else if (state !== 4) {
+      requireInput(input, cursor.inputIndex, 1);
+      nextState = instruction & 3;
+      matchIndex = cursor.outputIndex - ((instruction >> 2) + (input[cursor.inputIndex] << 2) + 1);
+      cursor.inputIndex += 1;
+      matchLength = 2;
+    } else {
+      requireInput(input, cursor.inputIndex, 1);
+      nextState = instruction & 3;
+      matchIndex = cursor.outputIndex - ((instruction >> 2) + (input[cursor.inputIndex] << 2) + 2049);
+      cursor.inputIndex += 1;
+      matchLength = 3;
+    }
+    if (matchIndex < 0 || cursor.outputIndex + matchLength + nextState > output.length) {
+      throw new Error('Invalid LZO1X block: lookbehind overrun.');
+    }
+    for (let index = 0; index < matchLength; index += 1) {
+      output[cursor.outputIndex++] = output[matchIndex++];
+    }
+    state = nextState;
+    copyLiteral(input, cursor, output, nextState);
+  }
+  if (matchLength !== 3 || cursor.inputIndex !== input.length || cursor.outputIndex !== output.length) {
+    throw new Error('Invalid LZO1X block: incomplete output.');
+  }
+  return output;
+}

package/hub/src/mode4-atlas-worker.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { decodeLzo1xBlock } from './lzo1x.js';
+
+const require = createRequire(import.meta.url);
+const DEFAULT_WIDTH = 1920;
+const DEFAULT_HEIGHT = 1080;
+const DEFAULT_FPS = 20;
+const MAX_DEVICES = 100;
+const FRAME_POOL_SIZE = 3;
+
+let config = normalizeConfig({});
+let layoutVersion = 0;
+let layout = [];
+let latestTiles = new Map();
+let framePool = [];
+let encoder = null;
+let encoderCandidateIndex = 0;
+let encoderCandidates = [];
+let encoderOutputSeen = false;
+let encoderRestartTimer = null;
+let encoderStartupTimer = null;
+let outputBuffer = Buffer.alloc(0);
+let frameSeq = 0;
+let tickTimer = null;
+let closed = false;
+
+function clamp(value, min, max, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, Math.round(number))) : fallback;
+}
+
+function normalizeConfig(value) {
+  const deviceIds = [...new Set((Array.isArray(value?.deviceIds) ? value.deviceIds : [])
+    .map(item => String(item || '').trim()).filter(Boolean))].slice(0, MAX_DEVICES);
+  return {
+    deviceIds,
+    width: clamp(value?.width, 640, 3840, DEFAULT_WIDTH),
+    height: clamp(value?.height, 360, 2160, DEFAULT_HEIGHT),
+    fps: clamp(value?.fps, 1, 30, DEFAULT_FPS)
+  };
+}
+
+function send(message) {
+  if (process.connected) process.send?.(message);
+}
+
+function resolveFfmpegPaths() {
+  const paths = [];
+  const add = value => {
+    const path = String(value || '').trim();
+    if (path && !paths.includes(path)) paths.push(path);
+  };
+  add(process.env.LIVEDESK_FFMPEG);
+  try { add(require('@ffmpeg-installer/ffmpeg')?.path); } catch {}
+  try { add(require('ffmpeg-static')); } catch {}
+  add('ffmpeg');
+  return paths;
+}
+
+function buildEncoderCandidates() {
+  const codecCandidates = process.platform === 'win32'
+    ? [
+        ['windows-nvenc', ['-c:v', 'h264_nvenc', '-preset', 'llhp', '-profile:v', 'baseline', '-rc:v', 'cbr_ld_hq', '-b:v', '6M', '-maxrate', '6M', '-bufsize', '1M', '-rc-lookahead', '0', '-zerolatency', '1', '-g', String(config.fps), '-bf', '0']],
+        ['windows-qsv', ['-c:v', 'h264_qsv', '-preset', 'veryfast', '-global_quality', '28', '-look_ahead', '0', '-g', String(config.fps), '-bf', '0']],
+        ['windows-amf', ['-c:v', 'h264_amf', '-quality', 'speed', '-usage', 'lowlatency', '-rc', 'cqp', '-qp_i', '25', '-qp_p', '28', '-g', String(config.fps), '-bf', '0']]
+      ]
+    : process.platform === 'darwin'
+      ? [['macos-videotoolbox', ['-c:v', 'h264_videotoolbox', '-realtime', '1', '-allow_sw', '0', '-b:v', '6M', '-g', String(config.fps), '-bf', '0']]]
+      : [['linux-nvenc', ['-c:v', 'h264_nvenc', '-preset', 'llhp', '-profile:v', 'baseline', '-rc-lookahead', '0', '-zerolatency', '1', '-g', String(config.fps), '-bf', '0']]];
+  codecCandidates.push(['software-x264', [
+    '-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'zerolatency',
+    '-profile:v', 'baseline', '-crf', '28', '-g', String(config.fps),
+    '-keyint_min', String(config.fps), '-sc_threshold', '0', '-bf', '0',
+    '-x264-params', 'aud=1:repeat-headers=1'
+  ]]);
+  return resolveFfmpegPaths().flatMap(path => codecCandidates.map(([name, args]) => ({ path, name, args })));
+}
+
+function startEncoder() {
+  if (closed || encoder || encoderCandidates.length === 0) return;
+  if (encoderCandidateIndex >= encoderCandidates.length) {
+    send({ type: 'status', state: 'error', error: 'No Mode 4 H.264 encoder is available.' });
+    return;
+  }
+  const candidate = encoderCandidates[encoderCandidateIndex++];
+  const args = [
+    '-hide_banner', '-loglevel', 'warning',
+    '-f', 'rawvideo', '-pixel_format', 'rgb24',
+    '-video_size', `${config.width}x${config.height}`,
+    '-framerate', String(config.fps), '-i', 'pipe:0', '-an',
+    ...candidate.args,
+    '-bsf:v', 'h264_metadata=aud=insert', '-f', 'h264', 'pipe:1'
+  ];
+  const child = spawn(candidate.path, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+  encoder = { child, candidate };
+  encoderOutputSeen = false;
+  outputBuffer = Buffer.alloc(0);
+  child.stdout.on('data', appendEncodedBytes);
+  child.stdin.on('error', error => {
+    send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name} input: ${error.message}` });
+  });
+  child.stderr.on('data', chunk => {
+    const message = String(chunk || '').trim();
+    if (message) send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: ${message.slice(0, 600)}` });
+  });
+  child.on('error', error => send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: ${error.message}` }));
+  child.on('exit', code => {
+    clearTimeout(encoderStartupTimer);
+    encoderStartupTimer = null;
+    const wasCurrent = encoder?.child === child;
+    if (wasCurrent) encoder = null;
+    flushEncodedUnit();
+    if (closed) return;
+    send({ type: 'status', state: 'encoder-restart', encoder: candidate.name, code, emitted: encoderOutputSeen });
+    clearTimeout(encoderRestartTimer);
+    encoderRestartTimer = setTimeout(startEncoder, encoderOutputSeen ? 800 : 120);
+  });
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = setTimeout(() => {
+    if (encoder?.child === child && !encoderOutputSeen) {
+      send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: no output during startup; trying the next encoder.` });
+      try { child.kill(); } catch {}
+    }
+  }, 3500);
+  send({ type: 'status', state: 'encoder-starting', encoder: candidate.name });
+}
+
+function stopEncoder() {
+  clearTimeout(encoderRestartTimer);
+  encoderRestartTimer = null;
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = null;
+  const child = encoder?.child;
+  encoder = null;
+  if (!child) return;
+  try { child.stdin.end(); } catch {}
+  setTimeout(() => { try { child.kill(); } catch {} }, 250).unref?.();
+}
+
+function findStartCodes(buffer) {
+  const starts = [];
+  for (let index = 0; index + 3 < buffer.length; index += 1) {
+    if (buffer[index] !== 0 || buffer[index + 1] !== 0) continue;
+    if (buffer[index + 2] === 1) {
+      starts.push({ offset: index, header: index + 3 });
+      index += 2;
+    } else if (buffer[index + 2] === 0 && buffer[index + 3] === 1) {
+      starts.push({ offset: index, header: index + 4 });
+      index += 3;
+    }
+  }
+  return starts;
+}
+
+function appendEncodedBytes(chunk) {
+  outputBuffer = outputBuffer.length ? Buffer.concat([outputBuffer, chunk]) : Buffer.from(chunk);
+  while (true) {
+    const auds = findStartCodes(outputBuffer).filter(start => (outputBuffer[start.header] & 0x1f) === 9);
+    if (auds.length < 2) break;
+    const boundary = auds[1].offset;
+    emitEncodedUnit(outputBuffer.subarray(0, boundary));
+    outputBuffer = outputBuffer.subarray(boundary);
+  }
+}
+
+function flushEncodedUnit() {
+  if (outputBuffer.length > 0) emitEncodedUnit(outputBuffer);
+  outputBuffer = Buffer.alloc(0);
+}
+
+function emitEncodedUnit(payload) {
+  if (!payload?.length) return;
+  const starts = findStartCodes(payload);
+  const isKeyFrame = starts.some(start => (payload[start.header] & 0x1f) === 5);
+  encoderOutputSeen = true;
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = null;
+  frameSeq += 1;
+  send({
+    type: 'frame',
+    payload: Buffer.from(payload),
+    metadata: {
+      frameSeq,
+      streamFrameSeq: frameSeq,
+      width: config.width,
+      height: config.height,
+      fps: config.fps,
+      durationUs: Math.round(1_000_000 / config.fps),
+      timestampUs: Math.round(frameSeq * 1_000_000 / config.fps),
+      isKeyFrame,
+      chunkType: isKeyFrame ? 'key' : 'delta',
+      hardwareEncoder: encoder?.candidate?.name || '',
+      layoutVersion
+    }
+  });
+}
+
+function rebuildLayout() {
+  const count = Math.max(1, config.deviceIds.length);
+  const columns = Math.max(1, Math.ceil(Math.sqrt(count)));
+  const rows = Math.max(1, Math.ceil(count / columns));
+  const cellWidth = Math.floor(config.width / columns);
+  const cellHeight = Math.floor(config.height / rows);
+  layoutVersion += 1;
+  layout = config.deviceIds.map((deviceId, index) => ({
+    deviceId,
+    index,
+    column: index % columns,
+    row: Math.floor(index / columns),
+    x: (index % columns) * cellWidth,
+    y: Math.floor(index / columns) * cellHeight,
+    width: index % columns === columns - 1 ? config.width - (index % columns) * cellWidth : cellWidth,
+    height: Math.floor(index / columns) === rows - 1 ? config.height - Math.floor(index / columns) * cellHeight : cellHeight
+  }));
+  for (const tile of latestTiles.values()) tile.rendered = null;
+  framePool = Array.from({ length: FRAME_POOL_SIZE }, () => Buffer.alloc(config.width * config.height * 3));
+  send({ type: 'layout', layoutVersion, width: config.width, height: config.height, columns, rows, tiles: layout });
+}
+
+function renderTile(tileState, tileLayout) {
+  const sourceWidth = tileState.width;
+  const sourceHeight = tileState.height;
+  const scale = Math.min(tileLayout.width / sourceWidth, tileLayout.height / sourceHeight);
+  const width = Math.max(1, Math.floor(sourceWidth * scale));
+  const height = Math.max(1, Math.floor(sourceHeight * scale));
+  const pixels = Buffer.allocUnsafe(width * height * 3);
+  let target = 0;
+  for (let y = 0; y < height; y += 1) {
+    const sourceY = Math.min(sourceHeight - 1, Math.floor((y + 0.5) * sourceHeight / height));
+    for (let x = 0; x < width; x += 1) {
+      const sourceX = Math.min(sourceWidth - 1, Math.floor((x + 0.5) * sourceWidth / width));
+      const source = (sourceY * sourceWidth + sourceX) * 2;
+      const pixel = tileState.rgb565[source] | (tileState.rgb565[source + 1] << 8);
+      pixels[target++] = ((pixel >> 11) & 0x1f) * 255 / 31;
+      pixels[target++] = ((pixel >> 5) & 0x3f) * 255 / 63;
+      pixels[target++] = (pixel & 0x1f) * 255 / 31;
+    }
+  }
+  tileState.rendered = {
+    pixels,
+    width,
+    height,
+    x: tileLayout.x + Math.floor((tileLayout.width - width) / 2),
+    y: tileLayout.y + Math.floor((tileLayout.height - height) / 2),
+    layoutVersion
+  };
+}
+
+function ingestFrame(message) {
+  const deviceId = String(message.deviceId || '');
+  if (!deviceId || !config.deviceIds.includes(deviceId)) return;
+  const width = clamp(message.width, 1, 320, 0);
+  const height = clamp(message.height, 1, 180, 0);
+  const expectedLength = width * height * 2;
+  if (!width || !height || Number(message.uncompressedByteLength) !== expectedLength) return;
+  try {
+    const compressed = Buffer.isBuffer(message.payload) ? message.payload : Buffer.from(message.payload || []);
+    const rgb565 = decodeLzo1xBlock(new Uint8Array(compressed), expectedLength);
+    const tileState = { width, height, rgb565, rendered: null, frameSeq: Number(message.frameSeq || 0) };
+    latestTiles.set(deviceId, tileState);
+    const tileLayout = layout.find(item => item.deviceId === deviceId);
+    if (tileLayout) renderTile(tileState, tileLayout);
+  } catch (error) {
+    send({ type: 'log', level: 'warn', message: `Mode 4 frame rejected for ${deviceId}: ${error.message}` });
+  }
+}
+
+function writeAtlasFrame() {
+  const target = framePool.pop();
+  const stdin = encoder?.child?.stdin;
+  if (!target || !stdin || stdin.destroyed || !stdin.writable) return;
+  target.fill(0);
+  for (const tileLayout of layout) {
+    const tileState = latestTiles.get(tileLayout.deviceId);
+    if (!tileState) continue;
+    if (!tileState.rendered || tileState.rendered.layoutVersion !== layoutVersion) renderTile(tileState, tileLayout);
+    const rendered = tileState.rendered;
+    for (let row = 0; row < rendered.height; row += 1) {
+      const sourceStart = row * rendered.width * 3;
+      const targetStart = ((rendered.y + row) * config.width + rendered.x) * 3;
+      rendered.pixels.copy(target, targetStart, sourceStart, sourceStart + rendered.width * 3);
+    }
+  }
+  try {
+    stdin.write(target, error => {
+      framePool.push(target);
+      if (error) send({ type: 'log', level: 'warn', message: `Mode 4 encoder write: ${error.message}` });
+    });
+  } catch (error) {
+    framePool.push(target);
+    send({ type: 'log', level: 'warn', message: `Mode 4 encoder write: ${error.message}` });
+  }
+}
+
+function configure(value) {
+  const next = normalizeConfig(value);
+  const encoderChanged = next.width !== config.width || next.height !== config.height || next.fps !== config.fps;
+  config = next;
+  latestTiles = new Map([...latestTiles].filter(([deviceId]) => config.deviceIds.includes(deviceId)));
+  rebuildLayout();
+  if (encoderChanged || !encoder) {
+    stopEncoder();
+    encoderCandidates = buildEncoderCandidates();
+    encoderCandidateIndex = 0;
+    startEncoder();
+  }
+  clearInterval(tickTimer);
+  tickTimer = setInterval(writeAtlasFrame, Math.max(1, Math.round(1000 / config.fps)));
+}
+
+process.on('message', message => {
+  if (message?.type === 'configure') configure(message);
+  else if (message?.type === 'frame') ingestFrame(message);
+  else if (message?.type === 'close') shutdown();
+});
+
+function shutdown() {
+  if (closed) return;
+  closed = true;
+  clearInterval(tickTimer);
+  stopEncoder();
+  setTimeout(() => process.exit(0), 50).unref?.();
+}
+
+process.on('disconnect', shutdown);
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+send({ type: 'status', state: 'ready' });

package/hub/src/mode4-atlas.js

@@ -0,0 +1,91 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const workerPath = fileURLToPath(new URL('./mode4-atlas-worker.js', import.meta.url));
+
+export class Mode4AtlasSession {
+  constructor(options = {}) {
+    this.onFrame = typeof options.onFrame === 'function' ? options.onFrame : () => {};
+    this.onLayout = typeof options.onLayout === 'function' ? options.onLayout : () => {};
+    this.onStatus = typeof options.onStatus === 'function' ? options.onStatus : () => {};
+    this.deviceIds = [];
+    this.deviceSet = new Set();
+    this.config = null;
+    this.closed = false;
+    this.worker = null;
+    this.restartTimer = null;
+    this.startWorker();
+  }
+
+  startWorker() {
+    if (this.closed || this.worker) return;
+    const worker = fork(workerPath, [], {
+      env: { ...process.env },
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      serialization: 'advanced',
+      windowsHide: true
+    });
+    this.worker = worker;
+    worker.on('message', message => {
+      if (message?.type === 'frame' && message.metadata && message.payload) {
+        this.onFrame({ metadata: message.metadata, payload: Buffer.from(message.payload) });
+      } else if (message?.type === 'layout') {
+        this.onLayout(message);
+      } else if (message?.type === 'status' || message?.type === 'log') {
+        this.onStatus(message);
+      }
+    });
+    worker.on('exit', code => {
+      if (this.worker === worker) this.worker = null;
+      if (this.closed) return;
+      this.onStatus({ type: 'status', state: 'worker-restart', code });
+      clearTimeout(this.restartTimer);
+      this.restartTimer = setTimeout(() => {
+        this.startWorker();
+        if (this.config) this.worker?.send({ type: 'configure', ...this.config });
+      }, 750);
+    });
+    worker.on('error', error => this.onStatus({ type: 'status', state: 'worker-error', error: error.message }));
+    if (this.config) worker.send({ type: 'configure', ...this.config });
+  }
+
+  configure(options = {}) {
+    this.deviceIds = [...new Set((Array.isArray(options.deviceIds) ? options.deviceIds : [])
+      .map(value => String(value || '').trim()).filter(Boolean))].slice(0, 100);
+    this.deviceSet = new Set(this.deviceIds);
+    this.config = {
+      deviceIds: this.deviceIds,
+      width: Number(options.width || 1920),
+      height: Number(options.height || 1080),
+      fps: Number(options.fps || 20)
+    };
+    this.worker?.send({ type: 'configure', ...this.config });
+  }
+
+  ingest(frameEvent) {
+    if (this.closed || !this.worker) return;
+    const frame = frameEvent?.frame || {};
+    const deviceId = String(frameEvent?.deviceId || frame.deviceId || '').trim();
+    const mode = String(frame.frameMode || frame.mode || '').toLowerCase();
+    if (!this.deviceSet.has(deviceId) || mode !== 'mode2-lzo' || !Buffer.isBuffer(frameEvent?.payload)) return;
+    this.worker.send({
+      type: 'frame',
+      deviceId,
+      frameSeq: Number(frame.frameSeq || 0),
+      width: Number(frame.width || 0),
+      height: Number(frame.height || 0),
+      uncompressedByteLength: Number(frame.uncompressedByteLength || 0),
+      payload: frameEvent.payload
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    clearTimeout(this.restartTimer);
+    const worker = this.worker;
+    this.worker = null;
+    try { worker?.send({ type: 'close' }); } catch {}
+    setTimeout(() => { try { worker?.kill(); } catch {} }, 400).unref?.();
+  }
+}