@esp-vision/device-core 0.1.0 → 0.2.0

package/src/device_session.js

@@ -47,6 +47,7 @@ const EV_MUX_USER_RPC_METHODS = new Set([
   'capabilities',
   'session.keepalive',
   'session.release',
+  'file.write',
   'script.write',
   'script.run',
   'device.control',
@@ -146,7 +147,7 @@ function isNetworkAction(method, payload) {
 }
 
 function isVmRpc(method, payload) {
-  if (method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
+  if (method === 'file.write' || method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
   if (method === 'debug.info') return payload?.scope !== 'transport.stats'
   return false
 }
@@ -155,30 +156,6 @@ function payloadBytes(payload) {
   return payload instanceof Uint8Array ? payload : utf8Bytes(payload)
 }
 
-function maxScriptChunkBytes({ path, encoding, mode, runAfterWrite, rxPayloadMax, totalBytes }) {
-  let low = 1
-  let high = Math.max(1, Math.min(EV_MUX_SCRIPT_CHUNK_BYTES, rxPayloadMax))
-  while (low < high) {
-    const candidate = Math.ceil((low + high) / 2)
-    const payload = {
-      path, encoding, mode, offset: Math.max(0, totalBytes - 1), totalBytes,
-      contentBase64: 'A'.repeat(Math.ceil(candidate / 3) * 4), runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length <= rxPayloadMax) low = candidate
-    else high = candidate - 1
-  }
-  return low
-}
-
-function bytesToBase64(bytes) {
-  let binary = ''
-  const chunkSize = 0x8000
-  for (let i = 0; i < bytes.length; i += chunkSize) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize))
-  }
-  return btoa(binary)
-}
-
 function defaultSleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -262,6 +239,11 @@ export function validateEvmuxCapabilities(payload) {
   }
 
   for (const key of Object.keys(EV_MUX_DEFAULT_LIMITS)) validateLimit(payload.limits, key)
+  if (payload.features.includes('file.write.binary') && (!Number.isSafeInteger(payload.limits.fileWriteChunkMax)
+      || payload.limits.fileWriteChunkMax < 4096 || payload.limits.fileWriteChunkMax > 16384
+      || payload.limits.fileWriteChunkMax % 4096 !== 0)) {
+    throw new Error('EV-MUX v4 capabilities are missing a valid limits.fileWriteChunkMax')
+  }
   if (payload.session?.policy !== 'firstCome'
       || !Number.isSafeInteger(payload.session.leaseMs)
       || !Number.isSafeInteger(payload.session.keepaliveMs)
@@ -622,6 +604,7 @@ export class DeviceSession {
     redactSsid = true,
     forceNetwork = false,
   } = {}) {
+    if (payload instanceof Uint8Array) return { binaryBytes: payload.byteLength }
     if (!forceNetwork && !isNetworkAction(method, payload) && !isNetworkAction(method, requestPayload)) return payload
     const secrets = [requestPayload?.ssid, requestPayload?.password]
       .filter((value) => typeof value === 'string' && value.length > 0)
@@ -687,6 +670,7 @@ export class DeviceSession {
     seq: requestedSeq = null,
     signal = null,
     writeTimeout = null,
+    encoding = undefined,
   } = {}) {
     if (this.state === 'disconnected') {
       throw new Error('EV-MUX is not connected')
@@ -715,7 +699,9 @@ export class DeviceSession {
         && (payloadData.length !== 1 || payloadData[0] !== 0x03)) {
       throw new Error('EV-MUX repl.signal only accepts the single-byte Ctrl-C signal 0x03')
     }
-    if (this.capabilities && payloadData.length > this.limits.rxPayloadMax) {
+    const payloadLimit = method === 'file.write' && encoding === 'binary' && this.hasFeature('file.write.binary')
+      ? this.limits.fileWriteChunkMax + 20 : this.limits.rxPayloadMax
+    if (this.capabilities && payloadData.length > payloadLimit) {
       throw new Error(`EV-MUX payload is ${payloadData.length} bytes; device limit is ${this.limits.rxPayloadMax}`)
     }
     if ((channel === 'repl.stdin' || channel === 'repl.signal') && payloadData.length > this.limits.replInputMax) {
@@ -727,7 +713,7 @@ export class DeviceSession {
       seq,
       channel,
       type: frameType,
-      encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+      encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
       ...(method ? { method } : {}),
       ...(needsAuthorization ? { sessionId: this.sessionId } : {}),
       ...(usesVm && needsAuthorization ? { vmEpoch: this.vmEpoch } : {}),
@@ -738,6 +724,7 @@ export class DeviceSession {
     const frame = this.makeEvMuxFrame({
       channel,
       type: frameType,
+      encoding,
       method,
       payload,
       seq,
@@ -764,6 +751,7 @@ export class DeviceSession {
       throw new Error('EV-MUX is not connected')
     }
     if (signal?.aborted) throw abortError(signal)
+    if (payload instanceof Uint8Array && method !== 'file.write') throw new TypeError('Raw binary requests are only supported for file.write')
     if (method === 'script.write' || method === 'script.run') validateRpcPath(payload?.path)
     if (method === 'debug.info' && (payload?.scope === 'fs.list' || payload?.scope === 'fs.read')) {
       validateRpcPath(payload.path ?? (payload.scope === 'fs.list' ? '/' : undefined))
@@ -816,7 +804,8 @@ export class DeviceSession {
     this.handlers.rpcRequest?.({ channel: rpcChannel, method, seq, timeout, payload: safePayload })
     this._diagnostic('rpc.request', { channel: rpcChannel, method, seq })
     try {
-      await this.writeFrame(rpcChannel, 'req', method, JSON.stringify(payload), {
+      await this.writeFrame(rpcChannel, 'req', method, payload instanceof Uint8Array ? payload : JSON.stringify(payload), {
+        encoding: payload instanceof Uint8Array ? 'binary' : undefined,
         vmRequest,
         seq,
         signal,
@@ -1089,41 +1078,45 @@ export class DeviceSession {
       : content instanceof Uint8Array
         ? content
         : new Uint8Array(content)
-    const chunkBytes = maxScriptChunkBytes({
-      path, encoding, mode, runAfterWrite, rxPayloadMax: this.limits.rxPayloadMax, totalBytes: bytes.length,
-    })
-    if (this.hasFeature('script.write.chunked') && bytes.length > chunkBytes) {
-      let lastResponse = null
-      for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+    if (!this.hasFeature('file.write.binary')) {
+      throw Object.assign(new Error('File upload requires firmware with file.write.binary; update the device firmware'), { code: 'UNSUPPORTED_OPERATION' })
+    }
+    const limit = this.limits.fileWriteChunkMax
+    if (!Number.isSafeInteger(limit) || limit < 4096 || limit > 16384 || limit % 4096 !== 0 || bytes.length > 0xffffffff) {
+      throw new Error('Invalid negotiated binary file transfer limit or file size')
+    }
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes))
+    if (signal?.aborted) throw abortError(signal)
+    const sha256 = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('')
+    const uploadId = randomHex()
+    let committed = false
+    try {
+      const begin = await this.rpc('file.write', { action: 'begin', path, mode, totalBytes: bytes.length, sha256, uploadId }, { timeout: 8000, signal })
+      if (begin.uploadId !== uploadId || begin.chunkBytes !== limit) throw new Error('Invalid binary file transfer acknowledgement')
+      const token = Uint8Array.from(begin.uploadId.match(/../g), byte => parseInt(byte, 16))
+      for (let offset = 0; offset < bytes.length; offset += limit) {
         if (signal?.aborted) throw abortError(signal)
-        const chunk = bytes.subarray(offset, Math.min(offset + chunkBytes, bytes.length))
-        lastResponse = await this.rpc('script.write', {
-          path,
-          encoding,
-          mode,
-          offset,
-          totalBytes: bytes.length,
-          contentBase64: bytesToBase64(chunk),
-          runAfterWrite: runAfterWrite && offset + chunk.length >= bytes.length,
-        }, { timeout: 8000, signal })
+        const chunk = bytes.subarray(offset, Math.min(offset + limit, bytes.length))
+        const payload = new Uint8Array(20 + chunk.length)
+        payload.set(token)
+        new DataView(payload.buffer).setUint32(16, offset, true)
+        payload.set(chunk, 20)
+        const response = await this.rpc('file.write', payload, { timeout: 8000, signal })
+        if (response.writtenBytes !== offset + chunk.length) throw new Error('Incomplete binary file transfer acknowledgement')
         onProgress?.({ writtenBytes: offset + chunk.length, totalBytes: bytes.length })
       }
-      return lastResponse
-    }
-
-    const payload = {
-      path,
-      encoding,
-      mode,
-      contentBase64: bytesToBase64(bytes),
-      runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length > this.limits.rxPayloadMax) {
-      throw new Error(`script.write payload exceeds the device RX limit ${this.limits.rxPayloadMax}; firmware must support script.write.chunked.`)
+      const result = await this.rpc('file.write', { action: 'commit', uploadId: begin.uploadId }, { timeout: 8000, signal })
+      if (result.complete !== true || result.bytes !== bytes.length) throw new Error('Incomplete binary file commit acknowledgement')
+      committed = true
+      if (bytes.length === 0) onProgress?.({ writtenBytes: 0, totalBytes: 0 })
+      if (runAfterWrite) await this.rpc('script.run', { path }, { timeout: 8000, signal })
+      return { ...result, path, runAfterWrite }
+    } finally {
+      if (!committed) {
+        // Cancellation does not cancel cleanup, and cleanup cannot mask the primary error.
+        await this.rpc('file.write', { action: 'abort', uploadId }, { timeout: 1500 }).catch(() => {})
+      }
     }
-    const response = await this.rpc('script.write', payload, { timeout: 8000, signal })
-    onProgress?.({ writtenBytes: bytes.length, totalBytes: bytes.length })
-    return response
   }
 
   async writeScript(path, content, { runAfterWrite = false, signal = null } = {}) {
@@ -1217,10 +1210,10 @@ export class DeviceSession {
     if (commandBytes <= inputLimit) {
       return this.repl.execPy(source, { timeout, signal })
     }
-    if (!this.hasFeature('script.write') || !this.hasFeature('script.run')) {
+    if (!this.hasFeature('file.write.binary') || !this.hasFeature('script.run')) {
       throw new Error(
         `Python source requires ${commandBytes} REPL bytes, above the firmware limit ${inputLimit}; ` +
-        'upgrade firmware with script.write and script.run support.',
+        'upgrade firmware with file.write.binary and script.run support.',
       )
     }
 
@@ -1365,8 +1358,8 @@ export class DeviceSession {
     if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
       throw new RangeError('Script timeout must be a positive number or null for an interactive run')
     }
-    if ((content !== undefined && !this.hasFeature('script.write')) || !this.hasFeature('script.run')) {
-      throw new Error('Running scripts requires script.run and uploading source also requires script.write')
+    if ((content !== undefined && !this.hasFeature('file.write.binary')) || !this.hasFeature('script.run')) {
+      throw new Error('Running scripts requires script.run and uploading source also requires file.write.binary')
     }
     if (this.runCapture || this.runStarting) {
       throw new Error('A script is already running')

package/src/evmux.js

@@ -389,14 +389,14 @@ export class EvMuxParser {
     }
 }
 
-export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined }) {
+export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined, encoding = undefined }) {
     const payloadBytes = payload instanceof Uint8Array ? payload : new TextEncoder().encode(payload)
     const metadata = {
         sid,
         seq,
         channel,
         type,
-    encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+    encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
     ...(sessionId ? { sessionId } : {}),
     ...(vmEpoch !== undefined ? { vmEpoch } : {}),
     ...(contentType ? { contentType } : {}),
@@ -408,7 +408,8 @@ export function makeEvMuxFrame({ channel, type = 'data', method = null, payload
         metadata.method = method
     }
     const metadataBytes = new TextEncoder().encode(JSON.stringify(metadata))
-    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=00000000\r\n`)
+    const checksum = encoding === 'binary' ? crc32(payloadBytes).toString(16).padStart(8, '0') : '00000000'
+    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=${checksum}\r\n`)
     const out = new Uint8Array(header.length + metadataBytes.length + payloadBytes.length + 1)
     out.set(header, 0)
     out.set(metadataBytes, header.length)

package/tests/check-package.mjs

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, rm, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+assert.equal(manifest.license, 'Apache-2.0')
+assert.match(await readFile(join(root, 'LICENSE'), 'utf8'), /Apache License[\s\S]*Version 2\.0/)
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-device-core-package-'))
+try {
+  const [packed] = JSON.parse(execFileSync('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', temporary], { cwd: root, encoding: 'utf8' }))
+  assert.ok(packed.files.some(({ path }) => path === 'LICENSE'))
+  assert.ok(packed.files.some(({ path }) => path === 'NOTICE'))
+  assert.ok(packed.files.some(({ path }) => path === 'schemas/device-actions-v1.json'))
+  assert.ok(packed.files.every(({ path }) => /^(src\/|schemas\/|tests\/|scripts\/|package\.json$|README\.md$|LICENSE$|NOTICE$|CHANGELOG\.md$)/.test(path)), 'tarball must contain only the standalone library')
+  assert.ok(!packed.files.some(({ path }) => path.startsWith('docs/')), 'Documentation is published by the ESP-VISION documentation center')
+  assert.ok(!packed.files.some(({ path }) => path.includes('__pycache__') || path.endsWith('.pyc')), 'Never ship host Python bytecode')
+  const consumer = join(temporary, 'consumer')
+  await mkdir(consumer)
+  execFileSync('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)], { cwd: consumer, stdio: 'pipe' })
+  const installed = join(consumer, 'node_modules/@esp-vision/device-core')
+  assert.equal(await readFile(join(installed, 'LICENSE'), 'utf8'), await readFile(join(root, 'LICENSE'), 'utf8'))
+  const notice = await readFile(join(installed, 'NOTICE'), 'utf8')
+  assert.ok(notice.includes('Copyright (c) 2024 Volodymyr Shymanskyy'))
+  assert.ok(notice.includes('Permission is hereby granted, free of charge'))
+  const entryPoints = Object.keys(manifest.exports).map(key => manifest.name + (key === '.' ? '' : key.slice(1)))
+  const script = `for (const name of ${JSON.stringify(entryPoints)}) {
+    const module = await import(name);
+    if (!Object.keys(module).length) throw new Error('Empty entry point: ' + name);
+  }
+  const api = await import('@esp-vision/device-core');
+  if (Object.keys(api).sort().join(',') !== 'createDevice') throw new Error('Root must expose only the application API');
+  const { DeviceSession } = await import('@esp-vision/device-core/session');
+  const { FirmwareFlashSession } = await import('@esp-vision/device-core/firmware');
+  const { tcpTransport, serialTransport } = await import('@esp-vision/device-core/node');
+  if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
+  const { createNodeDiscovery } = await import('@esp-vision/device-core/discovery/node');
+  const { EventEmitter } = await import('node:events');
+  let queries = 0;
+  const provider = createNodeDiscovery({ createMdns() {
+    const mdns = new EventEmitter(); mdns.query = () => { queries++ }; mdns.destroy = () => {}; return mdns;
+  } });
+  const device = api.createDevice({ discovery: provider });
+  if (typeof provider.list !== 'function') throw new Error('Discovery providers must expose list()');
+  if ((await device.discover({ timeout: 50 })).length !== 0 || !queries) throw new Error('Device discovery did not call its provider');
+  // Constructors must be passive: these endpoints need not exist to create adapters.
+  api.createDevice({ transport: tcpTransport({ host: '127.0.0.1', port: 1 }) });
+  api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });
+  if (typeof DeviceSession !== 'function' || typeof FirmwareFlashSession !== 'function') throw new Error('Missing host adapter APIs');`
+  execFileSync(process.execPath, ['--input-type=module', '-e', script], { cwd: consumer, stdio: 'pipe' })
+  assert.equal(manifest.bin['esp-vision-device'], './src/cli.js')
+  const help = execFileSync(process.execPath, [join(consumer, 'node_modules/@esp-vision/device-core/src/cli.js'), '--help'], { encoding: 'utf8' })
+  assert.ok(help.includes('esp-vision-device inspect'))
+  if (process.platform !== 'win32') {
+    const installedHelp = execFileSync(join(consumer, 'node_modules/.bin/esp-vision-device'), ['--help'], { encoding: 'utf8' })
+    assert.ok(installedHelp.includes('esp-vision-device inspect'), 'The installed npm command must execute through its symlink')
+  }
+  for (const required of ['src/node_serial.py', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.mjs', 'tests/fixtures/device-checks.py']) {
+    assert.ok(packed.files.some(({ path }) => path === required), `Missing installed check asset: ${required}`)
+  }
+  const unitOutput = execFileSync('npm', ['test'], { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
+  const unitCount = Number(/^# tests (\d+)$/m.exec(unitOutput)?.[1] ?? 0)
+  assert.ok(unitCount > 0, 'Installed npm test must execute a nonempty suite')
+  const hardwareHelp = execFileSync('npm', ['run', 'test:hardware', '--', '--help'], { cwd: installed, encoding: 'utf8' })
+  assert.ok(hardwareHelp.includes('--serial PATH'), 'Installed hardware runner must load and show its help')
+  // A damaged tarball must fail instead of reporting a successful zero-test run.
+  await rm(join(installed, 'tests'), { recursive: true })
+  await mkdir(join(installed, 'tests'))
+  const empty = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  assert.equal(empty.status, 1, 'An empty suite must fail closed')
+  assert.match(empty.stderr, /No Device Core unit tests found/)
+  await rm(join(installed, 'tests'), { recursive: true })
+  const missing = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  assert.equal(missing.status, 1, 'Missing tests must fail closed')
+  console.log(JSON.stringify({ package: packed.name, version: packed.version, entryPoints, unitCount, standalone: true }))
+} finally {
+  await rm(temporary, { recursive: true, force: true })
+}

package/tests/device-checks.mjs

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+// Application-level HIL checks. All device I/O goes through createDevice's API.
+import { readFile, mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream'])
+const MARKER = '__EVDEVICECHECK__'
+const failure = (code, message) => Object.assign(new Error(message), { code })
+const unsupported = error => error?.code === 'UNSUPPORTED_OPERATION' || /ESP_ERR_NOT_SUPPORTED|ESP_ERR_NOT_FOUND|no module named|ENODEV/i.test(error?.message ?? '')
+function cancelled(signal) { if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : failure('CANCELLED', 'Device checks cancelled') }
+
+export function parseCheckResult(output, name) {
+  const lines = output.split(/\r?\n/).filter(line => line.startsWith(MARKER))
+  if (lines.length !== 1) throw failure('CHECK_REPORT_INVALID', 'Expected exactly one device check report')
+  let result
+  try { result = JSON.parse(lines[0].slice(MARKER.length)) } catch { throw failure('CHECK_REPORT_INVALID', 'Invalid device check JSON') }
+  if (!result || result.name !== name || !['PASS', 'SKIP', 'FAIL'].includes(result.status)) throw failure('CHECK_REPORT_INVALID', 'Unexpected device check result')
+  if (result.status === 'PASS' && (!result.data || typeof result.data !== 'object' || Array.isArray(result.data))) throw failure('CHECK_REPORT_INVALID', 'Missing device measurements')
+  if (result.status !== 'PASS' && (!result.error || typeof result.error.message !== 'string')) throw failure('CHECK_REPORT_INVALID', 'Missing device failure details')
+  return result
+}
+
+export async function saveJpeg(image, output) {
+  const data = image?.data
+  if (image?.mimeType !== 'image/jpeg' || !(data instanceof Uint8Array) || data.length < 4 || data[0] !== 255 || data[1] !== 216 || data.at(-2) !== 255 || data.at(-1) !== 217) throw failure('CAPTURE_INVALID', 'Capture is not a complete JPEG')
+  if (!(image.metadata?.width > 0 && image.metadata?.height > 0)) throw failure('CAPTURE_INVALID', 'Capture has no valid image dimensions')
+  if (output) { await mkdir(dirname(output), { recursive: true }); await writeFile(output, data) }
+  return { bytes: data.length, width: image.metadata.width, height: image.metadata.height }
+}
+
+function pause(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort) }
+    const abort = () => { cleanup(); reject(signal.reason ?? failure('CANCELLED', 'Device check cancelled')) }
+    const timer = setTimeout(() => { cleanup(); resolve() }, milliseconds)
+    signal?.addEventListener('abort', abort, { once: true })
+    if (signal?.aborted) abort()
+  })
+}
+
+export async function runDeviceChecks(device, options, { signal, nonce, report = value => console.log(JSON.stringify(value)) } = {}) {
+  const results = [], fixturePath = `/evhil_${nonce}.py`, namespace = `_evhil_${nonce}`
+  let ownsFixture = false, loaded = false, namespaceStarted = false, loadError = null
+  const parameters = { frames: options.frames, framesize: options.framesize, pixformat: options.pixformat, displayHold: options.displayHold, screenCapture: Boolean(options.screenOutput) }
+  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
+  const execute = async (source, timeout = 10000, operationSignal = signal) => {
+    const result = await device.python.execute({ source, timeout, maxOutputChars: 16384, signal: operationSignal })
+    if (result.ok === false || result.outputTruncated) throw failure('PYTHON_CHECK', 'Device Python check did not complete')
+    return result.output
+  }
+  const load = async () => {
+    if (loaded) return
+    if (loadError) throw loadError
+    try {
+      const entries = await device.files.list({ path: '/', signal })
+      if (entries.some(entry => [fixturePath, `${fixturePath}.tmp`].includes(entry.path))) throw failure('TEST_PATH_EXISTS', 'Fixture path already exists')
+      const source = await readFile(new URL('./fixtures/device-checks.py', import.meta.url), 'utf8')
+      ownsFixture = true
+      await device.files.write({ path: fixturePath, data: source, overwrite: false, signal })
+      namespaceStarted = true
+      const loader = `with open(${JSON.stringify(fixturePath)}) as _fixture:\n exec(_fixture.read(),globals())`
+      await execute(`${namespace}={};exec(${JSON.stringify(loader)},${namespace})`)
+      loaded = true
+      await device.files.remove({ path: fixturePath, signal })
+    } catch (error) { loadError = error; throw error }
+  }
+  const invoke = async name => {
+    await load()
+    const output = await execute(`${namespace}['run_check'](${JSON.stringify(name)},${JSON.stringify(JSON.stringify(parameters))})`, timeoutFor(name))
+    return parseCheckResult(output, name)
+  }
+  const requirePass = result => {
+    if (result.status !== 'PASS') throw Object.assign(failure(result.status === 'SKIP' ? 'UNSUPPORTED_OPERATION' : 'DEVICE_CHECK_FAILED', result.error.message), { checkResult: result })
+    return result.data
+  }
+  const record = result => { results.push(result); report({ check: result.name, ...result, name: undefined }) }
+  try {
+    for (const name of options.checks) {
+      cancelled(signal)
+      const started = Date.now()
+      let result
+      try {
+        let data
+        if (name === 'identity') {
+          const info = await device.inspect({ fields: ['identity', 'capabilities', 'runtime'], signal })
+          if (!info.identity?.board || !info.identity.firmwareVersion || info.capabilities?.protocol?.evMuxVersion !== 4 || info.runtime?.vmReady !== true) throw failure('IDENTITY_INVALID', 'Expected a ready EV-MUX v4 firmware identity')
+          data = { identity: info.identity, features: info.capabilities.features, vmReady: info.runtime.vmReady }
+        } else if (name === 'camera') {
+          const image = await device.capture({ source: 'camera', format: 'jpeg', quality: options.quality, timeout: options.frameTimeout * 1000, signal })
+          data = await saveJpeg(image, options.output)
+          data.sensor = requirePass(await invoke('sensor_state'))
+        } else if (name === 'preview') {
+          let count = 0
+          const unsubscribe = device.on('preview', image => { if (image.data?.length) count++ })
+          try {
+            data = requirePass(await invoke(name))
+            await pause(2000, signal)
+            if (!count) throw failure('PREVIEW_EMPTY', 'No preview frame arrived')
+            data.received = count
+          } finally { unsubscribe() }
+        } else {
+          const response = await invoke(name)
+          if (name === 'ipa_stats' && response.status === 'SKIP') {
+            const info = await device.inspect({ fields: ['identity'], signal })
+            const board = (info.identity?.board ?? '').toUpperCase().replaceAll('-', '_')
+            if (['ESP32_P4X_EYE', 'ESP32_P4X_FUNCTION_EV_BOARD'].includes(board)) throw failure('IPA_REQUIRED', 'IPA statistics are required on this board')
+          }
+          data = requirePass(response)
+          if (name === 'display' && options.screenOutput) {
+            const image = await device.capture({ source: 'screen', format: 'jpeg', quality: options.quality, timeout: options.frameTimeout * 1000, signal })
+            const captured = await saveJpeg(image, options.screenOutput)
+            if (captured.width !== data.width || captured.height !== data.height) throw failure('SCREEN_SIZE_MISMATCH', 'LCD capture dimensions differ from display dimensions')
+            data.screen = captured
+          }
+        }
+        result = { name, status: 'PASS', data }
+      } catch (error) {
+        cancelled(signal)
+        const skip = unsupported(error) && !(name === 'display' && options.screenOutput)
+        result = { name, status: skip ? 'SKIP' : 'FAIL', error: { code: error.code ?? 'DEVICE_CHECK_FAILED', message: String(error.message ?? 'Device check failed').slice(0, 240) } }
+        if (error.code === 'WRITE_FAILED') {
+          try {
+            const status = await device.inspect({ fields: ['storage'], timeout: 3000, signal })
+            result.storage = Object.fromEntries(Object.entries(status.storage).map(([volume, state]) => [volume, { present: state.present, mounted: state.mounted, status: state.status, writable: state.writable, reason: state.reason }]))
+          } catch { /* Preserve the upload failure. */ }
+        }
+      } finally {
+        if (name === 'display' && loaded) {
+          try { await execute(`${namespace}['close_display']()`, 5000, AbortSignal.timeout(6000)) }
+          catch { result = { name, status: 'FAIL', error: { code: 'DISPLAY_CLEANUP_FAILED', message: 'Could not release the test display' } } }
+        }
+      }
+      result.seconds = (Date.now() - started) / 1000
+      record(result)
+    }
+  } finally {
+    const cleanupSignal = AbortSignal.timeout(10000)
+    let cleanupError
+    if (namespaceStarted) {
+      try { await execute(`if ${JSON.stringify(namespace)} in globals():\n ${namespace}.get('close_display',lambda:None)()\n del ${namespace}`, 5000, cleanupSignal) }
+      catch (error) { cleanupError = error }
+    }
+    if (ownsFixture) {
+      try {
+        const entries = await device.files.list({ path: '/', signal: cleanupSignal })
+        for (const entry of entries) if ([fixturePath, `${fixturePath}.tmp`].includes(entry.path)) await device.files.remove({ path: entry.path, signal: cleanupSignal })
+      } catch (error) { cleanupError ??= error }
+    }
+    if (cleanupError) record({ name: 'fixture-cleanup', status: 'FAIL', error: { code: 'FIXTURE_CLEANUP_FAILED', message: 'Could not clean up the hardware fixture', path: fixturePath } })
+  }
+  const summary = { passed: results.filter(result => result.status === 'PASS').length, failed: results.filter(result => result.status === 'FAIL').length, skipped: results.filter(result => result.status === 'SKIP').length }
+  report({ check: 'summary', ...summary })
+  if (summary.failed) throw Object.assign(failure('DEVICE_CHECKS_FAILED', 'One or more device checks failed'), { results })
+  return results
+}