@mindexec/cli 0.2.494 → 0.2.496

package/electron/native-renderer-owner.cjs

@@ -0,0 +1,1044 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const PROTOCOL_MAGIC = 0x31524e4d;
+const PROTOCOL_VERSION = 1;
+const HEADER_BYTES = 12;
+const MAX_PAYLOAD_BYTES = 32 * 1024 * 1024;
+const READY_TIMEOUT_MS = 10_000;
+const RESPONSE_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 5_000;
+const FORCE_EXIT_TIMEOUT_MS = 5_000;
+const MAX_BOARD_ID_BYTES = 256;
+const MAX_NODE_COUNT = 250_000;
+const MAX_EDGE_COUNT = 500_000;
+const MAX_EDGE_POINT_COUNT = 2_000_000;
+const MAX_PENDING_REQUESTS = 8;
+
+const LIFECYCLE_STATE = Object.freeze({
+  stopped: 'stopped',
+  starting: 'starting',
+  ready: 'ready',
+  stopping: 'stopping',
+  failed: 'failed',
+  stopFailed: 'stop-failed'
+});
+
+const REQUEST_TYPE = Object.freeze({
+  snapshot: 1,
+  camera: 2,
+  detach: 3,
+  shutdown: 4
+});
+
+const RESPONSE_TYPE = Object.freeze({
+  ready: 0x8001,
+  accepted: 0x8002,
+  rejected: 0x8003,
+  shutdown: 0x8004
+});
+
+const MAX_UINT32 = 0xffff_ffff;
+const MAX_UINT64 = 0xffff_ffff_ffff_ffffn;
+
+function createProtocolError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+function toFiniteNumber(value, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  return number;
+}
+
+function toUint32(value, name) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0 || number > MAX_UINT32) {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  return number;
+}
+
+function toUint64(value, name) {
+  let result;
+  try {
+    result = typeof value === 'bigint' ? value : BigInt(value);
+  } catch {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  if (result < 0n || result > MAX_UINT64) {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  if (typeof value === 'number' && !Number.isSafeInteger(value)) {
+    throw createProtocolError(`native-renderer-unsafe-${name}`);
+  }
+  return result;
+}
+
+function encodeUtf8U16(value, name, { allowEmpty = false, maxBytes = 0xffff } = {}) {
+  if (String(value ?? '').includes('\0')) {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  const encoded = Buffer.from(String(value ?? ''), 'utf8');
+  if ((!allowEmpty && encoded.length === 0) || encoded.length > maxBytes) {
+    throw createProtocolError(`native-renderer-invalid-${name}`);
+  }
+  return encoded;
+}
+
+function normalizeOwner(owner) {
+  if (!owner || typeof owner !== 'object' || Array.isArray(owner)) {
+    throw createProtocolError('native-renderer-invalid-owner');
+  }
+  const normalized = {
+    boardId: encodeUtf8U16(owner.boardId, 'board-id', { maxBytes: MAX_BOARD_ID_BYTES }),
+    engineGeneration: toUint64(owner.engineGeneration, 'engine-generation'),
+    boardEpoch: toUint64(owner.boardEpoch, 'board-epoch'),
+    boardRevision: toUint64(owner.boardRevision, 'board-revision'),
+    requestSequence: toUint64(owner.requestSequence, 'request-sequence')
+  };
+  if (
+    normalized.engineGeneration === 0n ||
+    normalized.boardEpoch === 0n ||
+    normalized.boardRevision === 0n ||
+    normalized.requestSequence === 0n
+  ) {
+    throw createProtocolError('native-renderer-owner-token-zero');
+  }
+  return normalized;
+}
+
+function normalizedOwnerKey(requestType, owner) {
+  return [
+    requestType,
+    owner.boardId.toString('hex'),
+    owner.engineGeneration,
+    owner.boardEpoch,
+    owner.boardRevision,
+    owner.requestSequence
+  ].join(':');
+}
+
+function normalizeCamera(camera) {
+  if (!camera || typeof camera !== 'object' || Array.isArray(camera)) {
+    throw createProtocolError('native-renderer-invalid-camera');
+  }
+  const normalized = {
+    x: toFiniteNumber(camera.x, 'camera-x'),
+    y: toFiniteNumber(camera.y, 'camera-y'),
+    z: toFiniteNumber(camera.z, 'camera-z'),
+    near: toFiniteNumber(camera.near, 'camera-near'),
+    far: toFiniteNumber(camera.far, 'camera-far'),
+    fov: toFiniteNumber(camera.fov, 'camera-fov'),
+    viewportW: toFiniteNumber(camera.viewportW, 'camera-viewport-w'),
+    viewportH: toFiniteNumber(camera.viewportH, 'camera-viewport-h'),
+    zoom: toFiniteNumber(camera.zoom, 'camera-zoom')
+  };
+  if (
+    normalized.near <= 0 ||
+    normalized.far <= normalized.near ||
+    normalized.fov <= 0 ||
+    normalized.fov >= 180 ||
+    normalized.viewportW <= 0 ||
+    normalized.viewportH <= 0 ||
+    normalized.zoom <= 0
+  ) {
+    throw createProtocolError('native-renderer-invalid-camera-range');
+  }
+  return normalized;
+}
+
+function normalizeNodes(nodes) {
+  if (!Array.isArray(nodes)) {
+    throw createProtocolError('native-renderer-invalid-nodes');
+  }
+  if (nodes.length > MAX_NODE_COUNT) {
+    throw createProtocolError('native-renderer-too-many-nodes');
+  }
+  const handles = new Set();
+  return nodes.map((node, index) => {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) {
+      throw createProtocolError(`native-renderer-invalid-node-${index}`);
+    }
+    const handle = toUint32(node.handle, `node-handle-${index}`);
+    if (handle === 0 || handles.has(handle)) {
+      throw createProtocolError(`native-renderer-duplicate-node-handle-${index}`);
+    }
+    handles.add(handle);
+    const normalized = {
+      handle,
+      x: toFiniteNumber(node.x, `node-x-${index}`),
+      y: toFiniteNumber(node.y, `node-y-${index}`),
+      z: toFiniteNumber(node.z, `node-z-${index}`),
+      width: toFiniteNumber(node.width, `node-width-${index}`),
+      height: toFiniteNumber(node.height, `node-height-${index}`),
+      fillRgba: toUint32(node.fillRgba, `node-fill-${index}`)
+    };
+    if (normalized.width <= 0 || normalized.height <= 0) {
+      throw createProtocolError(`native-renderer-invalid-node-size-${index}`);
+    }
+    return normalized;
+  });
+}
+
+function normalizeEdges(edges, nodeHandles) {
+  if (!Array.isArray(edges)) {
+    throw createProtocolError('native-renderer-invalid-edges');
+  }
+  if (edges.length > MAX_EDGE_COUNT) {
+    throw createProtocolError('native-renderer-too-many-edges');
+  }
+  const handles = new Set();
+  let totalPointCount = 0;
+  const normalizedEdges = edges.map((edge, index) => {
+    if (!edge || typeof edge !== 'object' || Array.isArray(edge) || !Array.isArray(edge.points)) {
+      throw createProtocolError(`native-renderer-invalid-edge-${index}`);
+    }
+    const handle = toUint32(edge.handle, `edge-handle-${index}`);
+    if (handle === 0 || handles.has(handle)) {
+      throw createProtocolError(`native-renderer-duplicate-edge-handle-${index}`);
+    }
+    handles.add(handle);
+    if (edge.points.length < 2) {
+      throw createProtocolError(`native-renderer-invalid-edge-points-${index}`);
+    }
+    totalPointCount += edge.points.length;
+    if (totalPointCount > MAX_EDGE_POINT_COUNT) {
+      throw createProtocolError('native-renderer-too-many-edge-points');
+    }
+    const points = edge.points.map((point, pointIndex) => {
+      if (!point || typeof point !== 'object' || Array.isArray(point)) {
+        throw createProtocolError(`native-renderer-invalid-edge-point-${index}-${pointIndex}`);
+      }
+      return {
+        x: toFiniteNumber(point.x, `edge-point-x-${index}-${pointIndex}`),
+        y: toFiniteNumber(point.y, `edge-point-y-${index}-${pointIndex}`)
+      };
+    });
+    const normalized = {
+      handle,
+      sourceHandle: toUint32(edge.sourceHandle, `edge-source-${index}`),
+      targetHandle: toUint32(edge.targetHandle, `edge-target-${index}`),
+      z: toFiniteNumber(edge.z, `edge-z-${index}`),
+      width: toFiniteNumber(edge.width, `edge-width-${index}`),
+      colorRgba: toUint32(edge.colorRgba, `edge-color-${index}`),
+      points
+    };
+    if (
+      normalized.sourceHandle === 0 ||
+      normalized.targetHandle === 0 ||
+      !nodeHandles.has(normalized.sourceHandle) ||
+      !nodeHandles.has(normalized.targetHandle) ||
+      normalized.width <= 0
+    ) {
+      throw createProtocolError(`native-renderer-invalid-edge-range-${index}`);
+    }
+    return normalized;
+  });
+  return { edges: normalizedEdges, totalPointCount };
+}
+
+function ownerPayloadBytes(owner) {
+  return 2 + owner.boardId.length + 32;
+}
+
+function writeOwner(buffer, offset, owner) {
+  buffer.writeUInt16LE(owner.boardId.length, offset);
+  offset += 2;
+  owner.boardId.copy(buffer, offset);
+  offset += owner.boardId.length;
+  buffer.writeBigUInt64LE(owner.engineGeneration, offset);
+  offset += 8;
+  buffer.writeBigUInt64LE(owner.boardEpoch, offset);
+  offset += 8;
+  buffer.writeBigUInt64LE(owner.boardRevision, offset);
+  offset += 8;
+  buffer.writeBigUInt64LE(owner.requestSequence, offset);
+  return offset + 8;
+}
+
+function writeCamera(buffer, offset, camera) {
+  for (const value of [
+    camera.x,
+    camera.y,
+    camera.z,
+    camera.near,
+    camera.far,
+    camera.fov,
+    camera.viewportW,
+    camera.viewportH,
+    camera.zoom
+  ]) {
+    buffer.writeDoubleLE(value, offset);
+    offset += 8;
+  }
+  return offset;
+}
+
+function framePayload(requestType, payload) {
+  if (payload.length > MAX_PAYLOAD_BYTES) {
+    throw createProtocolError('native-renderer-payload-too-large');
+  }
+  const frame = Buffer.allocUnsafe(HEADER_BYTES + payload.length);
+  frame.writeUInt32LE(PROTOCOL_MAGIC, 0);
+  frame.writeUInt16LE(PROTOCOL_VERSION, 4);
+  frame.writeUInt16LE(requestType, 6);
+  frame.writeUInt32LE(payload.length, 8);
+  payload.copy(frame, HEADER_BYTES);
+  return frame;
+}
+
+function encodeSnapshotMessage(scene) {
+  if (!scene || typeof scene !== 'object' || Array.isArray(scene)) {
+    throw createProtocolError('native-renderer-invalid-scene');
+  }
+  const owner = normalizeOwner(scene.owner);
+  const camera = normalizeCamera(scene.camera);
+  const nodes = normalizeNodes(scene.nodes);
+  const normalizedEdges = normalizeEdges(scene.edges, new Set(nodes.map(node => node.handle)));
+  const payloadLength = ownerPayloadBytes(owner) + 72 + 12 +
+    nodes.length * 48 + normalizedEdges.edges.length * 36 + normalizedEdges.totalPointCount * 16;
+  if (payloadLength > MAX_PAYLOAD_BYTES) {
+    throw createProtocolError('native-renderer-payload-too-large');
+  }
+  const payload = Buffer.allocUnsafe(payloadLength);
+  let offset = writeOwner(payload, 0, owner);
+  offset = writeCamera(payload, offset, camera);
+  payload.writeUInt32LE(nodes.length, offset);
+  payload.writeUInt32LE(normalizedEdges.edges.length, offset + 4);
+  payload.writeUInt32LE(normalizedEdges.totalPointCount, offset + 8);
+  offset += 12;
+
+  for (const node of nodes) {
+    payload.writeUInt32LE(node.handle, offset);
+    offset += 4;
+    for (const value of [node.x, node.y, node.z, node.width, node.height]) {
+      payload.writeDoubleLE(value, offset);
+      offset += 8;
+    }
+    payload.writeUInt32LE(node.fillRgba, offset);
+    offset += 4;
+  }
+
+  for (const edge of normalizedEdges.edges) {
+    payload.writeUInt32LE(edge.handle, offset);
+    payload.writeUInt32LE(edge.sourceHandle, offset + 4);
+    payload.writeUInt32LE(edge.targetHandle, offset + 8);
+    offset += 12;
+    payload.writeDoubleLE(edge.z, offset);
+    payload.writeDoubleLE(edge.width, offset + 8);
+    offset += 16;
+    payload.writeUInt32LE(edge.colorRgba, offset);
+    payload.writeUInt32LE(edge.points.length, offset + 4);
+    offset += 8;
+    for (const point of edge.points) {
+      payload.writeDoubleLE(point.x, offset);
+      payload.writeDoubleLE(point.y, offset + 8);
+      offset += 16;
+    }
+  }
+
+  if (offset !== payload.length) {
+    throw createProtocolError('native-renderer-snapshot-size-mismatch');
+  }
+  return { frame: framePayload(REQUEST_TYPE.snapshot, payload), owner };
+}
+
+function encodeCameraMessage(frame) {
+  if (!frame || typeof frame !== 'object' || Array.isArray(frame)) {
+    throw createProtocolError('native-renderer-invalid-camera-frame');
+  }
+  const owner = normalizeOwner(frame.owner);
+  const camera = normalizeCamera(frame.camera);
+  const payload = Buffer.allocUnsafe(ownerPayloadBytes(owner) + 72);
+  const offset = writeCamera(payload, writeOwner(payload, 0, owner), camera);
+  if (offset !== payload.length) {
+    throw createProtocolError('native-renderer-camera-size-mismatch');
+  }
+  return { frame: framePayload(REQUEST_TYPE.camera, payload), owner };
+}
+
+function encodeDetachMessage(ownerValue) {
+  const owner = normalizeOwner(ownerValue);
+  const payload = Buffer.allocUnsafe(ownerPayloadBytes(owner));
+  const offset = writeOwner(payload, 0, owner);
+  if (offset !== payload.length) {
+    throw createProtocolError('native-renderer-detach-size-mismatch');
+  }
+  return { frame: framePayload(REQUEST_TYPE.detach, payload), owner };
+}
+
+function encodeShutdownMessage() {
+  return framePayload(REQUEST_TYPE.shutdown, Buffer.alloc(0));
+}
+
+class PayloadReader {
+  constructor(buffer) {
+    this.buffer = buffer;
+    this.offset = 0;
+  }
+
+  require(bytes) {
+    if (this.offset + bytes > this.buffer.length) {
+      throw createProtocolError('native-renderer-response-truncated');
+    }
+  }
+
+  uint8() {
+    this.require(1);
+    return this.buffer.readUInt8(this.offset++);
+  }
+
+  uint16() {
+    this.require(2);
+    const value = this.buffer.readUInt16LE(this.offset);
+    this.offset += 2;
+    return value;
+  }
+
+  uint64() {
+    this.require(8);
+    const value = this.buffer.readBigUInt64LE(this.offset);
+    this.offset += 8;
+    return value;
+  }
+
+  stringU16({ allowEmpty = true } = {}) {
+    const length = this.uint16();
+    this.require(length);
+    const value = this.buffer.toString('utf8', this.offset, this.offset + length);
+    this.offset += length;
+    if (!allowEmpty && value.length === 0) {
+      throw createProtocolError('native-renderer-response-empty-string');
+    }
+    return value;
+  }
+
+  owner() {
+    return {
+      boardId: this.stringU16({ allowEmpty: false }),
+      engineGeneration: this.uint64(),
+      boardEpoch: this.uint64(),
+      boardRevision: this.uint64(),
+      requestSequence: this.uint64()
+    };
+  }
+
+  finish() {
+    if (this.offset !== this.buffer.length) {
+      throw createProtocolError('native-renderer-response-trailing-bytes');
+    }
+  }
+}
+
+function decodeResponse(responseType, payload) {
+  const reader = new PayloadReader(payload);
+  let response;
+  switch (responseType) {
+    case RESPONSE_TYPE.ready:
+      response = { type: 'ready', backend: reader.stringU16({ allowEmpty: false }) };
+      break;
+    case RESPONSE_TYPE.accepted:
+      response = { type: 'accepted', requestType: reader.uint16(), owner: reader.owner() };
+      break;
+    case RESPONSE_TYPE.rejected: {
+      const requestType = reader.uint16();
+      const hasOwner = reader.uint8();
+      if (hasOwner !== 0 && hasOwner !== 1) {
+        throw createProtocolError('native-renderer-response-invalid-owner-flag');
+      }
+      response = {
+        type: 'rejected',
+        requestType,
+        owner: hasOwner === 1 ? reader.owner() : null,
+        reason: reader.stringU16({ allowEmpty: false })
+      };
+      break;
+    }
+    case RESPONSE_TYPE.shutdown:
+      response = { type: 'shutdown' };
+      break;
+    default:
+      throw createProtocolError('native-renderer-response-type-unknown');
+  }
+  reader.finish();
+  return response;
+}
+
+function responseOwnerKey(requestType, owner) {
+  const normalized = {
+    boardId: Buffer.from(owner.boardId, 'utf8'),
+    engineGeneration: owner.engineGeneration,
+    boardEpoch: owner.boardEpoch,
+    boardRevision: owner.boardRevision,
+    requestSequence: owner.requestSequence
+  };
+  return normalizedOwnerKey(requestType, normalized);
+}
+
+function defaultExecutablePath({ appIsPackaged, resourcesPath, packageRoot }) {
+  if (appIsPackaged) {
+    return path.join(resourcesPath, 'native-renderer', 'windows-x64', 'mindexec_windows_host.exe');
+  }
+  return path.resolve(packageRoot, '..', 'artifacts', 'cpp', 'windows-x64-release', 'mindexec_windows_host.exe');
+}
+
+class NativeRendererOwner {
+  constructor(options = {}) {
+    this.mode = options.mode === 'mirror' ? 'mirror' : 'off';
+    this.appIsPackaged = options.appIsPackaged === true;
+    this.executablePath = path.resolve(options.executablePath || defaultExecutablePath({
+      appIsPackaged: this.appIsPackaged,
+      resourcesPath: options.resourcesPath || process.resourcesPath || '',
+      packageRoot: options.packageRoot || path.resolve(__dirname, '..')
+    }));
+    this.spawnProcess = options.spawnProcess || spawn;
+    this.onStatus = typeof options.onStatus === 'function' ? options.onStatus : () => undefined;
+    this.log = typeof options.log === 'function' ? options.log : () => undefined;
+    this.readyTimeoutMs = options.readyTimeoutMs || READY_TIMEOUT_MS;
+    this.responseTimeoutMs = options.responseTimeoutMs || RESPONSE_TIMEOUT_MS;
+    this.stopTimeoutMs = options.stopTimeoutMs || STOP_TIMEOUT_MS;
+    this.forceExitTimeoutMs = options.forceExitTimeoutMs || FORCE_EXIT_TIMEOUT_MS;
+
+    this.child = null;
+    this.startPromise = null;
+    this.stopPromise = null;
+    this.ready = false;
+    this.backend = '';
+    this.engineGeneration = 0;
+    this.acceptedFrames = 0;
+    this.rejectedFrames = 0;
+    this.lastError = '';
+    this.stdoutBuffer = Buffer.alloc(0);
+    this.pending = new Map();
+    this.readyResolver = null;
+    this.readyRejecter = null;
+    this.intentionalStop = false;
+    this.lifecycleState = LIFECYCLE_STATE.stopped;
+  }
+
+  getStatus() {
+    return {
+      mode: this.mode,
+      ready: this.ready,
+      backend: this.backend,
+      engineGeneration: this.engineGeneration,
+      acceptedFrames: this.acceptedFrames,
+      rejectedFrames: this.rejectedFrames,
+      lastError: this.lastError,
+      processId: this.child?.exitCode === null ? Number(this.child.pid || 0) : 0
+    };
+  }
+
+  isRunning() {
+    return Boolean(this.child && this.child.exitCode === null);
+  }
+
+  emitStatus() {
+    this.onStatus(this.getStatus());
+  }
+
+  validatePackageFiles() {
+    if (!this.appIsPackaged) return '';
+    const packageDirectory = path.dirname(this.executablePath);
+    const requiredPaths = [
+      path.join(packageDirectory, 'native-renderer-manifest.json'),
+      path.join(packageDirectory, 'shaders', 'dxbc', 'vs_canvas_shape.sc.bin'),
+      path.join(packageDirectory, 'shaders', 'dxbc', 'fs_canvas_shape.sc.bin')
+    ];
+    const missingPath = requiredPaths.find(filePath => !fs.existsSync(filePath));
+    if (missingPath) {
+      return `native-renderer-package-file-missing:${missingPath}`;
+    }
+    try {
+      const manifest = JSON.parse(fs.readFileSync(requiredPaths[0], 'utf8'));
+      const manifestFiles = new Set(
+        Array.isArray(manifest.files) ? manifest.files.map(entry => String(entry?.path || '')) : []
+      );
+      if (
+        manifest.schema !== 'mindexec-native-renderer-package/v1' ||
+        manifest.platform !== 'windows-x64' ||
+        Number(manifest.protocol) !== PROTOCOL_VERSION ||
+        !manifestFiles.has('mindexec_windows_host.exe') ||
+        !manifestFiles.has('shaders/dxbc/vs_canvas_shape.sc.bin') ||
+        !manifestFiles.has('shaders/dxbc/fs_canvas_shape.sc.bin')
+      ) {
+        return 'native-renderer-package-manifest-invalid';
+      }
+    } catch (error) {
+      return `native-renderer-package-manifest-invalid:${error?.message || error}`;
+    }
+    return '';
+  }
+
+  async start() {
+    if (this.mode !== 'mirror') {
+      return this.getStatus();
+    }
+    if (this.lifecycleState === LIFECYCLE_STATE.stopping || this.stopPromise) {
+      return this.getStatus();
+    }
+    if (this.ready && this.isRunning()) {
+      return this.getStatus();
+    }
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+    if (this.isRunning()) {
+      this.lastError ||= 'native-renderer-child-not-ready';
+      this.emitStatus();
+      return this.getStatus();
+    }
+    this.lifecycleState = LIFECYCLE_STATE.starting;
+    this.startPromise = this.startCore().finally(() => {
+      this.startPromise = null;
+      if (this.lifecycleState === LIFECYCLE_STATE.starting) {
+        this.lifecycleState = this.ready
+          ? LIFECYCLE_STATE.ready
+          : (this.isRunning() ? LIFECYCLE_STATE.failed : LIFECYCLE_STATE.stopped);
+      }
+    });
+    return this.startPromise;
+  }
+
+  async startCore() {
+    if (process.platform !== 'win32' && !this.spawnProcess.__allowNonWindowsForTest) {
+      this.lastError = 'native-renderer-windows-only';
+      this.emitStatus();
+      return this.getStatus();
+    }
+    if (!fs.existsSync(this.executablePath)) {
+      this.lastError = `native-renderer-executable-missing:${this.executablePath}`;
+      this.emitStatus();
+      return this.getStatus();
+    }
+    const packageError = this.validatePackageFiles();
+    if (packageError) {
+      this.lastError = packageError;
+      this.emitStatus();
+      return this.getStatus();
+    }
+
+    this.intentionalStop = false;
+    this.ready = false;
+    this.backend = '';
+    this.lastError = '';
+    this.stdoutBuffer = Buffer.alloc(0);
+    this.engineGeneration += 1;
+    this.acceptedFrames = 0;
+    this.rejectedFrames = 0;
+
+    let child;
+    try {
+      child = this.spawnProcess(this.executablePath, ['--mirror-stdio'], {
+        cwd: path.dirname(this.executablePath),
+        env: { ...process.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: false
+      });
+    } catch (error) {
+      this.lastError = `native-renderer-spawn-failed:${error?.message || error}`;
+      this.lifecycleState = LIFECYCLE_STATE.failed;
+      this.emitStatus();
+      return this.getStatus();
+    }
+    this.child = child;
+    child.stdout?.on('data', chunk => this.handleStdout(chunk));
+    child.stderr?.on('data', chunk => this.log(`[native-renderer:error] ${String(chunk).trimEnd()}`));
+    child.on('error', error => this.handleProcessError(error));
+    child.on('exit', (code, signal) => this.handleProcessExit(child, code, signal));
+    this.log(`[native-renderer:start] pid=${String(child.pid)} generation=${this.engineGeneration}`);
+
+    const readyResult = await new Promise(resolve => {
+      const timer = setTimeout(() => {
+        this.readyResolver = null;
+        this.lastError = 'native-renderer-ready-timeout';
+        resolve(false);
+      }, this.readyTimeoutMs);
+      timer.unref?.();
+      this.readyResolver = () => {
+        clearTimeout(timer);
+        this.readyResolver = null;
+        resolve(true);
+      };
+      this.readyRejecter = reason => {
+        clearTimeout(timer);
+        this.readyResolver = null;
+        this.readyRejecter = null;
+        this.lastError = reason;
+        resolve(false);
+      };
+    });
+
+    if (!readyResult && this.child === child && child.exitCode === null) {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // Process may have exited between the state check and kill.
+      }
+    }
+    this.emitStatus();
+    return this.getStatus();
+  }
+
+  handleStdout(chunk) {
+    this.stdoutBuffer = this.stdoutBuffer.length === 0
+      ? Buffer.from(chunk)
+      : Buffer.concat([this.stdoutBuffer, chunk]);
+    try {
+      while (this.stdoutBuffer.length >= HEADER_BYTES) {
+        const magic = this.stdoutBuffer.readUInt32LE(0);
+        const version = this.stdoutBuffer.readUInt16LE(4);
+        const responseType = this.stdoutBuffer.readUInt16LE(6);
+        const payloadLength = this.stdoutBuffer.readUInt32LE(8);
+        if (magic !== PROTOCOL_MAGIC || version !== PROTOCOL_VERSION || payloadLength > MAX_PAYLOAD_BYTES) {
+          throw createProtocolError('native-renderer-response-header-invalid');
+        }
+        const frameLength = HEADER_BYTES + payloadLength;
+        if (this.stdoutBuffer.length < frameLength) {
+          return;
+        }
+        const payload = this.stdoutBuffer.subarray(HEADER_BYTES, frameLength);
+        this.stdoutBuffer = this.stdoutBuffer.subarray(frameLength);
+        this.handleResponse(decodeResponse(responseType, payload));
+      }
+    } catch (error) {
+      this.handleProtocolError(error);
+    }
+  }
+
+  handleResponse(response) {
+    if (response.type === 'ready') {
+      if (this.lifecycleState === LIFECYCLE_STATE.stopping) {
+        this.readyRejecter?.('native-renderer-stopping');
+        return;
+      }
+      this.ready = true;
+      this.backend = response.backend;
+      this.lastError = '';
+      this.lifecycleState = LIFECYCLE_STATE.ready;
+      const resolveReady = this.readyResolver;
+      this.readyResolver = null;
+      this.readyRejecter = null;
+      resolveReady?.();
+      this.emitStatus();
+      return;
+    }
+    if (response.type === 'shutdown') {
+      this.ready = false;
+      return;
+    }
+    if (!response.owner) {
+      if (response.requestType === REQUEST_TYPE.snapshot || response.requestType === REQUEST_TYPE.camera) {
+        this.rejectedFrames += 1;
+      }
+      this.resolveOldestPending(response.requestType, {
+        accepted: false,
+        reason: response.reason || 'native-renderer-rejected-without-owner'
+      });
+      this.emitStatus();
+      return;
+    }
+
+    const key = responseOwnerKey(response.requestType, response.owner);
+    const pending = this.pending.get(key);
+    if (!pending) {
+      this.log(`[native-renderer:orphan-response] type=${response.requestType} key=${key}`);
+      return;
+    }
+    this.pending.delete(key);
+    clearTimeout(pending.timer);
+    if (response.type === 'accepted') {
+      if (response.requestType === REQUEST_TYPE.snapshot || response.requestType === REQUEST_TYPE.camera) {
+        this.acceptedFrames += 1;
+      }
+      pending.resolve({ accepted: true });
+      return;
+    }
+    if (response.requestType === REQUEST_TYPE.snapshot || response.requestType === REQUEST_TYPE.camera) {
+      this.rejectedFrames += 1;
+    }
+    pending.resolve({ accepted: false, reason: response.reason || 'native-renderer-rejected' });
+    this.emitStatus();
+  }
+
+  resolveOldestPending(requestType, result) {
+    for (const [key, pending] of this.pending) {
+      if (pending.requestType !== requestType) continue;
+      this.pending.delete(key);
+      clearTimeout(pending.timer);
+      pending.resolve(result);
+      return;
+    }
+  }
+
+  handleProtocolError(error) {
+    this.lastError = error?.message || String(error);
+    this.ready = false;
+    if (this.lifecycleState !== LIFECYCLE_STATE.stopping) {
+      this.lifecycleState = LIFECYCLE_STATE.failed;
+    }
+    this.failPending(this.lastError);
+    this.readyRejecter?.(this.lastError);
+    this.emitStatus();
+    const child = this.child;
+    if (child && child.exitCode === null) {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // Process may already be exiting.
+      }
+    }
+  }
+
+  handleProcessError(error) {
+    this.lastError = `native-renderer-process-error:${error?.message || error}`;
+    this.ready = false;
+    if (this.lifecycleState !== LIFECYCLE_STATE.stopping) {
+      this.lifecycleState = LIFECYCLE_STATE.failed;
+    }
+    this.failPending(this.lastError);
+    this.readyRejecter?.(this.lastError);
+    this.emitStatus();
+  }
+
+  handleProcessExit(child, code, signal) {
+    if (this.child !== child) return;
+    this.child = null;
+    this.ready = false;
+    this.backend = '';
+    this.lifecycleState = this.intentionalStop
+      ? LIFECYCLE_STATE.stopped
+      : LIFECYCLE_STATE.failed;
+    const reason = `native-renderer-exit:${String(code)}:${String(signal)}`;
+    this.failPending(reason);
+    this.readyRejecter?.(reason);
+    if (!this.intentionalStop && !this.lastError) {
+      this.lastError = reason;
+    }
+    this.log(`[native-renderer:exit] code=${String(code)} signal=${String(signal)}`);
+    this.emitStatus();
+  }
+
+  failPending(reason) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      if (pending.requestType === REQUEST_TYPE.snapshot || pending.requestType === REQUEST_TYPE.camera) {
+        this.rejectedFrames += 1;
+      }
+      pending.resolve({ accepted: false, reason });
+    }
+    this.pending.clear();
+  }
+
+  ownerGenerationMatches(owner) {
+    try {
+      return toUint64(owner?.engineGeneration, 'engine-generation') === BigInt(this.engineGeneration);
+    } catch {
+      return false;
+    }
+  }
+
+  rejectBeforeSend(requestType, reason) {
+    if (requestType === REQUEST_TYPE.snapshot || requestType === REQUEST_TYPE.camera) {
+      this.rejectedFrames += 1;
+    }
+    this.emitStatus();
+    return { ...this.getStatus(), accepted: false, reason };
+  }
+
+  async sendSnapshot(scene) {
+    return this.sendOwned(REQUEST_TYPE.snapshot, scene?.owner, () => encodeSnapshotMessage(scene));
+  }
+
+  async sendCamera(frame) {
+    return this.sendOwned(REQUEST_TYPE.camera, frame?.owner, () => encodeCameraMessage(frame));
+  }
+
+  async detach(owner) {
+    return this.sendOwned(REQUEST_TYPE.detach, owner, () => encodeDetachMessage(owner));
+  }
+
+  async sendOwned(requestType, ownerValue, encode) {
+    if (this.mode !== 'mirror') {
+      return this.rejectBeforeSend(requestType, 'native-renderer-mode-off');
+    }
+    if (this.lifecycleState === LIFECYCLE_STATE.stopping || this.stopPromise) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-stopping');
+    }
+    await this.start();
+    if (this.lifecycleState === LIFECYCLE_STATE.stopping || this.stopPromise) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-stopping');
+    }
+    if (!this.ready || !this.isRunning()) {
+      return this.rejectBeforeSend(requestType, this.lastError || 'native-renderer-not-ready');
+    }
+    if (!this.ownerGenerationMatches(ownerValue)) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-engine-generation-mismatch');
+    }
+    if (this.pending.size >= MAX_PENDING_REQUESTS) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-pending-limit');
+    }
+
+    let encoded;
+    try {
+      encoded = encode();
+    } catch (error) {
+      return this.rejectBeforeSend(requestType, error?.message || String(error));
+    }
+    const key = normalizedOwnerKey(requestType, encoded.owner);
+    if (this.pending.has(key)) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-request-duplicate');
+    }
+    const child = this.child;
+    if (!child?.stdin || child.exitCode !== null) {
+      return this.rejectBeforeSend(requestType, 'native-renderer-not-ready');
+    }
+
+    const result = await new Promise(resolve => {
+      const timer = setTimeout(() => {
+        if (!this.pending.delete(key)) return;
+        if (requestType === REQUEST_TYPE.snapshot || requestType === REQUEST_TYPE.camera) {
+          this.rejectedFrames += 1;
+        }
+        resolve({ accepted: false, reason: 'native-renderer-response-timeout' });
+        this.emitStatus();
+      }, this.responseTimeoutMs);
+      timer.unref?.();
+      this.pending.set(key, { requestType, resolve, timer });
+      child.stdin.write(encoded.frame, error => {
+        if (!error || !this.pending.delete(key)) return;
+        clearTimeout(timer);
+        if (requestType === REQUEST_TYPE.snapshot || requestType === REQUEST_TYPE.camera) {
+          this.rejectedFrames += 1;
+        }
+        resolve({ accepted: false, reason: `native-renderer-write-failed:${error.message}` });
+        this.emitStatus();
+      });
+    });
+    return { ...this.getStatus(), ...result };
+  }
+
+  async stop() {
+    if (this.stopPromise) return this.stopPromise;
+    this.stopPromise = this.stopCore().finally(() => {
+      this.stopPromise = null;
+    });
+    return this.stopPromise;
+  }
+
+  async stopCore() {
+    const child = this.child;
+    this.intentionalStop = true;
+    this.ready = false;
+    this.lifecycleState = LIFECYCLE_STATE.stopping;
+    this.readyRejecter?.('native-renderer-stopping');
+    this.failPending('native-renderer-stopping');
+    if (!child || child.exitCode !== null) {
+      this.child = null;
+      this.backend = '';
+      this.lifecycleState = LIFECYCLE_STATE.stopped;
+      this.emitStatus();
+      return this.getStatus();
+    }
+
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let forceExitTimer = null;
+      const cleanup = () => {
+        clearTimeout(gracefulTimer);
+        if (forceExitTimer) clearTimeout(forceExitTimer);
+        child.removeListener('exit', confirmExit);
+      };
+      const confirmExit = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const rejectWithoutExit = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        this.lastError = 'native-renderer-force-exit-timeout';
+        this.lifecycleState = LIFECYCLE_STATE.stopFailed;
+        this.emitStatus();
+        reject(createProtocolError(this.lastError));
+      };
+      const gracefulTimer = setTimeout(() => {
+        if (child.exitCode === null) {
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            // Process may have exited between the check and kill.
+          }
+        }
+        if (child.exitCode !== null) {
+          confirmExit();
+          return;
+        }
+        forceExitTimer = setTimeout(rejectWithoutExit, this.forceExitTimeoutMs);
+      }, this.stopTimeoutMs);
+      child.once('exit', confirmExit);
+      if (child.exitCode !== null) {
+        confirmExit();
+        return;
+      }
+      try {
+        child.stdin?.write(encodeShutdownMessage(), error => {
+          if (error && child.exitCode === null) {
+            try {
+              child.kill('SIGTERM');
+            } catch {
+              // The exit listener or the bounded force-exit timeout owns completion.
+            }
+          }
+        });
+      } catch {
+        try {
+          child.kill('SIGTERM');
+        } catch {
+          // The exit listener or the bounded force-exit timeout owns completion.
+        }
+      }
+    });
+    if (this.child === child || child.exitCode === null) {
+      this.lastError = 'native-renderer-exit-not-confirmed';
+      this.lifecycleState = LIFECYCLE_STATE.stopFailed;
+      this.emitStatus();
+      throw createProtocolError(this.lastError);
+    }
+    this.backend = '';
+    this.failPending('native-renderer-stopped');
+    this.lifecycleState = LIFECYCLE_STATE.stopped;
+    this.emitStatus();
+    return this.getStatus();
+  }
+}
+
+function createNativeRendererOwner(options) {
+  return new NativeRendererOwner(options);
+}
+
+module.exports = {
+  HEADER_BYTES,
+  MAX_PAYLOAD_BYTES,
+  PROTOCOL_MAGIC,
+  PROTOCOL_VERSION,
+  REQUEST_TYPE,
+  RESPONSE_TYPE,
+  createNativeRendererOwner,
+  decodeResponse,
+  encodeCameraMessage,
+  encodeDetachMessage,
+  encodeShutdownMessage,
+  encodeSnapshotMessage,
+  framePayload
+};