@esp-vision/device-core 0.3.0 → 0.4.1

package/src/firmware_updates.js

@@ -3,6 +3,8 @@
  */
 import { loadOfficialFirmware } from './firmware_feed.js'
 import { FirmwareFlashSession, validateFirmwareImage, firmwareMode } from './firmware_flash.js'
+import { validateFirmwareRelease as release } from './firmware_release.js'
+import { downloadBytes, MAX_FIRMWARE_BYTES } from './firmware_io.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -16,38 +18,7 @@ function identity(value) {
   if (!value || typeof value.board !== 'string' || !value.board || typeof value.firmwareVersion !== 'string' || !value.firmwareVersion) throw new TypeError('An inspected identity with board and firmwareVersion is required')
   return structuredClone(value)
 }
-function release(value, mode = 'update') {
-  if (!value || typeof value.board !== 'string' || !value.board || typeof value.version !== 'string' || !value.version) throw new TypeError('Release requires board and version')
-  const image = value.image
-  const revisionValid = image?.chipRevision !== undefined
-    ? Number.isSafeInteger(image.chipRevision) && image.chipRevision >= 0
-    : Number.isSafeInteger(image?.chipRevisionMin) && image.chipRevisionMin >= 0
-      && Number.isSafeInteger(image?.chipRevisionMax) && image.chipRevisionMax >= image.chipRevisionMin
-  if (!image || image.evMuxVersion !== 4 || !Number.isSafeInteger(image.chipFamily)
-      || image.chipFamily < 0 || !revisionValid || !Number.isSafeInteger(image.offset) || image.offset < 0
-      || !Number.isSafeInteger(image.bytes) || image.bytes <= 0 || !Number.isSafeInteger(image.partitionSize) || image.bytes > image.partitionSize
-      || !/^[a-f0-9]{64}$/.test(image.sha256 ?? '') || !Number.isSafeInteger(image.partitionTable?.offset) || image.partitionTable.offset < 0
-      || !Number.isSafeInteger(image.partitionTable?.bytes) || image.partitionTable.bytes <= 0
-      || !/^[a-f0-9]{64}$/.test(image.partitionTable?.sha256 ?? '')) throw new TypeError('Release requires complete EV-MUX v4 application/chip/partition/SHA-256 metadata')
-  if (mode === 'install') {
-    const install = value.install
-    if (!install || install.offset !== 0 || !Number.isSafeInteger(install.bytes) || install.bytes <= 0
-        || !Number.isSafeInteger(install.flashSize) || install.flashSize < install.bytes || install.flashSize > 2 ** 30
-        || !Number.isInteger(Math.log2(install.flashSize)) || install.flashSize < 2 ** 18
-        || !/^[a-f0-9]{64}$/.test(install.sha256 ?? '') || !install.bootloader
-        || !Number.isSafeInteger(install.chipRevisionMin) || !Number.isSafeInteger(install.chipRevisionMax)
-        || install.chipRevisionMin < (image.chipRevision ?? image.chipRevisionMin) || install.chipRevisionMax > (image.chipRevision ?? image.chipRevisionMax)
-        || install.chipRevisionMin < 0 || install.chipRevisionMax < install.chipRevisionMin) throw Object.assign(new TypeError('Release lacks qualified complete-install metadata'), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
-    let end = 0
-    for (const part of [install.bootloader, image.partitionTable, image]) {
-      if (!Number.isSafeInteger(part.offset) || !Number.isSafeInteger(part.bytes) || part.bytes <= 0
-          || part.offset < end || part.offset + part.bytes > install.bytes
-          || !/^[a-f0-9]{64}$/.test(part.sha256 ?? '')) throw new TypeError('Invalid complete-install segment bounds or hashes')
-      end = part.offset + part.bytes
-    }
-  }
-  return structuredClone(value)
-}
+
 async function download(url, fetcher, signal) {
   if (typeof url !== 'string' || new URL(url).protocol !== 'https:') throw new TypeError('Firmware URLs must use HTTPS')
   if (typeof fetcher !== 'function') throw new TypeError('Provide fetch or an in-memory catalog/image')
@@ -64,7 +35,7 @@ export async function checkFirmware(request = {}, connectedIdentity) {
   if (request.version !== undefined && (typeof request.version !== 'string' || !request.version.trim())) throw new TypeError('version must be a non-empty firmware version string')
   const mode = firmwareMode(request.mode)
   const current = identity(connectedIdentity ?? request.identity)
-  const catalog = request.catalog === undefined ? await loadOfficialFirmware({ board: current.board, fetch: fetcher, signal }) : typeof request.catalog === 'string' ? await (await download(request.catalog, fetcher, signal)).json() : structuredClone(request.catalog)
+  const catalog = request.catalog === undefined ? await loadOfficialFirmware({ board: current.board, version: request.version, fetch: fetcher, signal }) : typeof request.catalog === 'string' ? await (await download(request.catalog, fetcher, signal)).json() : structuredClone(request.catalog)
   abort(signal)
   if (catalog?.schemaVersion !== 1 || !Array.isArray(catalog.releases)) throw new TypeError('Catalog requires schemaVersion 1 and releases ordered newest first')
   // Feed ordering is authoritative: firmware versions may be calendar/git labels.
@@ -88,15 +59,25 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   if (typeof openLoader !== 'function' || typeof onProgress !== 'function' || typeof onPhase !== 'function' || (reset !== undefined && typeof reset !== 'function')) throw new TypeError('Firmware update requires openLoader and valid callbacks')
   const mode = firmwareMode(request.mode)
   const target = release(request.release, mode)
-  const image = mode === 'install' ? {
+  const installation = target.install ? {
     ...target.image, offset: target.install.offset, bytes: target.install.bytes,
     flashSize: target.install.flashSize, sha256: target.install.sha256, url: target.install.url,
     bootloader: target.install.bootloader, application: target.image,
     chipRevision: undefined, chipRevisionMin: target.install.chipRevisionMin, chipRevisionMax: target.install.chipRevisionMax,
-  } : target.image
+  } : null
+  const image = mode === 'install' ? installation : target.image
   const board = connectedIdentity?.board ?? request.board
   if (!board || board !== target.board || (request.board !== undefined && request.board !== board)) throw new TypeError('Firmware release does not match the connected or explicitly selected board')
-  const bytes = request.data === undefined ? new Uint8Array(await (await download(image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  const source = mode === 'update' ? image.source : undefined
+  const descriptor = source ?? image
+  let bytes = request.data === undefined
+    ? await downloadBytes(descriptor.url, { fetch: fetcher, signal, maxBytes: MAX_FIRMWARE_BYTES, expectedBytes: descriptor.bytes, immutable: target.image.source !== undefined })
+    : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  if (source) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength !== source.bytes) throw new Error('Complete BIN source size does not match the approved build')
+    await validateFirmwareImage(installation, bytes, { mode: 'install' })
+    bytes = bytes.slice(source.offset, source.offset + image.bytes)
+  }
   await validateFirmwareImage(image, bytes, { mode })
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.

package/tests/check-browser.mjs

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import vm from 'node:vm'
+import { webcrypto } from 'node:crypto'
+import { build } from 'esbuild'
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-browser-'))
+try {
+  // Bundle the actual pinned dependency and its dynamic JSON stubs for browsers.
+  const result = await build({
+    stdin: { contents: `export { createDevice } from './src/index.js'; export { openBrowserRom } from './src/browser.js'; export { loadReleaseManifest } from './src/firmware.js'; export { ESPLoader as TestLoader } from 'tasmota-webserial-esptool'; export { browserRomCompatibility as testCompatibility } from './src/browser_rom_compat.js';`, resolveDir: root },
+    bundle: true, platform: 'browser', format: 'iife', globalName: 'DeviceCore',
+    write: false, metafile: true,
+  })
+  const code = result.outputFiles[0].text
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('tasmota-webserial-esptool/dist/esp_loader.js')))
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32p4.json')))
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32s31.json')))
+  assert.ok(!Object.keys(result.metafile.inputs).some(path => /src\/(node|cli)/.test(path)))
+  const context = vm.createContext({ EventTarget, URL, TextDecoder, TextEncoder, Uint8Array, AbortController, setTimeout, clearTimeout, console, crypto: webcrypto, structuredClone })
+  vm.runInContext(code, context)
+  let opens = 0, closes = 0
+  const adapter = context.DeviceCore.openBrowserRom({ port: {
+    async open() { opens++; throw new Error('real dependency reached SerialPort.open') },
+    async close() { closes++ },
+  } })
+  assert.equal(opens, 0, 'import and construction must not open/reset the port')
+  await assert.rejects(adapter.initialize(), /real dependency reached SerialPort.open/)
+  assert.equal(opens, 1)
+  // Run upstream's actual SLIP parser in both CDC and UART modes. A blank board
+  // may emit a boot log before the stub greeting; invalid escapes must still fail.
+  for (const cdc of [false, true]) {
+    const raw = new context.DeviceCore.TestLoader({}, { log() {}, error() {}, debug() {} })
+    context.DeviceCore.testCompatibility(raw)
+    raw._isCDCDevice = cdc
+    raw.__inputBuffer = []
+    raw._inputBuffer.push(71, 97, 114, 0xc0, 79, 72, 65, 73, 0xc0)
+    assert.deepEqual(Array.from(await raw.readPacket(100)), [79, 72, 65, 73])
+    raw._clearInputBuffer()
+    raw._inputBuffer.push(0xc0, 0xdb, 0x47, 0xc0)
+    await assert.rejects(raw.readPacket(100), /Invalid SLIP escape/)
+  }
+  const prototype = context.DeviceCore.TestLoader.prototype
+  const originals = Object.fromEntries(['initialize', 'disconnect', 'getSecurityInfo', 'runStub', 'hardReset'].map(key => [key, prototype[key]]))
+  let initializeCalls = 0, disconnectCalls = 0
+  prototype.disconnect = async function () { disconnectCalls++; await this.port.close() }
+  const fakePort = () => ({
+    async open() { this.readable = {}; this.writable = {} },
+    async close() { this.readable = null; this.writable = null },
+  })
+  try {
+    prototype.initialize = async () => { initializeCalls++ }
+    const controller = new AbortController()
+    const loader = context.DeviceCore.openBrowserRom({ port: fakePort(), signal: controller.signal })
+    const first = loader.initialize()
+    assert.equal(loader.initialize(), first, 'initialize must share one ROM connection')
+    await first
+    controller.abort()
+    assert.equal(disconnectCalls, 0, 'abort after initialization must not interrupt flash/readback')
+    await loader.disconnect(); await loader.disconnect()
+    assert.equal(disconnectCalls, 1)
+    assert.equal(initializeCalls, 1)
+    prototype.initialize = async () => { throw new Error('sync failed') }
+    await assert.rejects(context.DeviceCore.openBrowserRom({ port: fakePort() }).initialize(), /sync failed/)
+    assert.equal(disconnectCalls, 2, 'failed ROM sync must release the acquired port')
+    let finishOpen
+    const waitingPort = fakePort()
+    const open = waitingPort.open
+    waitingPort.open = async function () {
+      await new Promise(resolve => { finishOpen = resolve })
+      await open.call(this)
+    }
+    const cancelled = new AbortController()
+    const late = context.DeviceCore.openBrowserRom({ port: waitingPort, signal: cancelled.signal })
+    const starting = late.initialize()
+    while (!finishOpen) await new Promise(resolve => setTimeout(resolve, 1))
+    cancelled.abort()
+    await assert.rejects(starting, { name: 'AbortError' })
+    finishOpen()
+    await new Promise(resolve => setTimeout(resolve, 5))
+    assert.equal(disconnectCalls, 3, 'an open completing after cancellation must close')
+    assert.equal(waitingPort.readable, null)
+    const data = new Uint8Array([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5])
+    const hash = async bytes => Array.from(new Uint8Array(await webcrypto.subtle.digest('SHA-256', bytes)), byte => byte.toString(16).padStart(2, '0')).join('')
+    const release = { board: 'BOARD', version: 'browser-test', image: {
+      evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302,
+      offset: 65536, bytes: data.byteLength, partitionSize: 4096,
+      sha256: await hash(data), partitionTable: { offset: 32768, bytes: table.byteLength, sha256: await hash(table) },
+    } }
+    let stubs = 0, writes = 0, resets = 0
+    prototype.initialize = async function () { this.chipFamily = 0x3280; this.chipRevision = 302 }
+    prototype.getSecurityInfo = async () => ({ flags: 1, flashCryptCnt: 0 })
+    prototype.runStub = async () => { stubs++; throw new Error('must not launch') }
+    const device = context.DeviceCore.createDevice()
+    const request = {
+      release, board: 'BOARD', data,
+      openLoader: ({ signal }) => context.DeviceCore.openBrowserRom({ port: fakePort(), signal }),
+    }
+    await assert.rejects(device.firmware.update(request), /Secure boot/)
+    assert.equal(stubs, 0, 'ROM security must be checked before the browser launches a stub')
+    await assert.rejects(device.firmware.update({ ...request, data: new Uint8Array(4) }), /SHA-256/)
+    assert.equal(stubs, 0)
+    prototype.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 0 })
+    const writing = new AbortController()
+    prototype.runStub = async () => {
+      stubs++
+      return {
+        IS_STUB: true,
+        async flashData() { writes++; writing.abort() },
+        async readFlash(offset) { return offset === 32768 ? table : data },
+        async readRegister() { return 0 },
+      }
+    }
+    prototype.hardReset = async () => { resets++ }
+    const beforeUpdateCloses = disconnectCalls
+    const updated = await device.firmware.update({ ...request, signal: writing.signal })
+    assert.equal(updated.verified, true)
+    assert.equal(updated.needsReset, false)
+    assert.equal(stubs, 1); assert.equal(writes, 1); assert.equal(resets, 1)
+    assert.equal(disconnectCalls, beforeUpdateCloses + 1, 'write-time abort must preserve complete readback, reset and one cleanup')
+    const manifest = { schemaVersion: 1, version: 'browser-test', sourceCommit: 'a'.repeat(40), pipelineId: 1, layout: 'legacy',
+      releases: [{ ...release, image: { ...release.image, url: 'https://dl.espressif.com/AE/esp-vision/bin/app.bin' } }],
+      website: { schemaVersion: '1.0.0', release: 'browser-test', releases: ['browser-test'], binaryNameTemplate: '{board}-{tag}.bin',
+        boards: [{ board: 'BOARD', name: 'Board', slug: 'board', flashable: true }], models: [] }, mcp: null }
+    const rawManifest = new TextEncoder().encode(JSON.stringify(manifest)), caches = []
+    const snapshot = await context.DeviceCore.loadReleaseManifest({ url: 'https://dl.espressif.com/AE/esp-vision/releases/browser-test/manifest.json', sha256: await hash(rawManifest),
+      async fetch(_url, options) {
+        caches.push(options.cache)
+        if (caches.length === 1) throw new TypeError('Cached response CORS failure from the host realm')
+        return new Response(rawManifest)
+      } })
+    assert.equal(snapshot.version, 'browser-test')
+    assert.deepEqual(caches, ['default', 'no-store'], 'real browser bundle must recover a fetch TypeError from host-provided fetch')
+
+  } finally { Object.assign(prototype, originals) }
+  // Node import must not eagerly resolve tasmota's browser-only, extensionless ESM.
+  const { openBrowserRom } = await import(pathToFileURL(join(root, 'src/browser.js')))
+  assert.equal(typeof openBrowserRom, 'function')
+  const dependency = JSON.parse(await readFile(join(root, 'node_modules/tasmota-webserial-esptool/package.json'), 'utf8'))
+  assert.equal(dependency.version, '9.4.2')
+  const stubsLicense = await readFile(join(root, 'node_modules/tasmota-webserial-esptool/src/stubs/README.md'), 'utf8')
+  assert.match(stubsLicense, /dual licensed.*Apache License Version 2.0 or the MIT license/s)
+  await writeFile(join(temporary, 'browser.js'), code)
+  console.log(JSON.stringify({ browserBundle: true, dependency: dependency.version, bytes: code.length, passiveImports: true, p4AndS31Stubs: true, cleanupAndCancellation: true, coreSafetyChecks: true }))
+} finally { await rm(temporary, { recursive: true, force: true }) }

package/tests/check-package.mjs

@@ -37,8 +37,11 @@ try {
   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 { FirmwareFlashSession, loadOfficialFirmware, loadReleaseManifest } = await import('@esp-vision/device-core/firmware');
+  if (typeof loadOfficialFirmware !== 'function' || typeof loadReleaseManifest !== 'function') throw new Error('Missing public release manifest readers');
   const { tcpTransport, serialTransport, openNodeRom } = await import('@esp-vision/device-core/node');
+  const { openBrowserRom } = await import('@esp-vision/device-core/browser');
+  if (typeof openBrowserRom !== 'function' || typeof openBrowserRom({ port: { open() { throw new Error('Not opened'); }, close() {} } }).initialize !== 'function') throw new Error('Missing passive browser ROM adapter');
   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');

package/tests/device-checks.mjs

@@ -2,6 +2,7 @@
 // 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'
+import { EV_REPL_INPUT_MAX_BYTES, evReplExecInputBytes } from '../src/evrepl.js'
 
 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__'
@@ -39,11 +40,14 @@ function pause(milliseconds, signal) {
 }
 
 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 results = [], namespace = `_evhil_${nonce}`
+  let loaded = false, namespaceStarted = false, loadError = null, inputLimit = EV_REPL_INPUT_MAX_BYTES
   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) => {
+    // Larger python.execute() requests use temporary files in Device Core.
+    // Keep fixtures in RAM by respecting the actual encoded REPL-line budget.
+    if (evReplExecInputBytes(source) > inputLimit) throw failure('REPL_INPUT_LIMIT', 'Hardware fixture command exceeds the device REPL input limit')
     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
@@ -52,16 +56,25 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
     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 info = await device.inspect({ fields: ['capabilities'], signal })
+      const advertised = info.capabilities?.limits?.replInputMax
+      if (Number.isSafeInteger(advertised) && advertised > 0) inputLimit = Math.min(inputLimit, advertised)
       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})`)
+      await execute(`${namespace}={'_source':[]}`)
+      const append = chunk => `${namespace}['_source'].append(${JSON.stringify(chunk)})`
+      let chunk = ''
+      for (const character of source) {
+        if (evReplExecInputBytes(append(chunk + character)) > inputLimit) {
+          if (!chunk) throw failure('REPL_INPUT_LIMIT', 'Device REPL input limit cannot load hardware fixtures')
+          await execute(append(chunk))
+          chunk = ''
+        }
+        chunk += character
+      }
+      if (chunk) await execute(append(chunk))
+      await execute(`exec(''.join(${namespace}['_source']),${namespace});del ${namespace}['_source']`)
       loaded = true
-      await device.files.remove({ path: fixturePath, signal })
     } catch (error) { loadError = error; throw error }
   }
   const invoke = async name => {
@@ -83,8 +96,12 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
         let data
         if (name === 'identity') {
           const info = await device.inspect({ fields: ['identity', 'capabilities', 'runtime'], signal })
+          if (info.capabilities?.features?.includes('storage.writer.lease')) {
+            info.storage = (await device.inspect({ fields: ['storage'], signal })).storage
+          }
           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 }
+          data = { identity: info.identity, features: info.capabilities.features, vmReady: info.runtime.vmReady,
+            storage: info.storage && Object.fromEntries(Object.entries(info.storage).map(([volume, state]) => [volume, { present: state.present, mounted: state.mounted, writable: state.writable, reason: state.reason }])) }
         } 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)
@@ -116,14 +133,8 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
         result = { name, status: 'PASS', data }
       } catch (error) {
         cancelled(signal)
-        const skip = unsupported(error) && !(name === 'display' && options.screenOutput)
+        const skip = unsupported(error) && !options.requireAll && !(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)) }
@@ -140,13 +151,7 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
       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 } })
+    if (cleanupError) record({ name: 'fixture-cleanup', status: 'FAIL', error: { code: 'FIXTURE_CLEANUP_FAILED', message: 'Could not release the hardware fixture namespace' } })
   }
   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 })

package/tests/fixtures/device-checks.py

@@ -6,6 +6,11 @@ All transport, ownership and cleanup are supplied by the public JS SDK.
 """
 
 
+def is_unsupported(exc):
+    message = str(exc).lower()
+    return any(token in message for token in ('esp_err_not_supported', 'esp_err_not_found', 'no module named', 'enodev'))
+
+
 def framesizes(opts):
     import sensor
     sensor.reset()
@@ -18,8 +23,10 @@ def framesizes(opts):
             img = sensor.snapshot()
             results.append(dict(name=name, supported=True, width=img.width(), height=img.height(),
                                 reportedWidth=sensor.width(), reportedHeight=sensor.height()))
-        except Exception:
-            results.append(dict(name=name, supported=False))
+        except Exception as exc:
+            if not is_unsupported(exc):
+                raise
+            results.append(dict(name=name, supported=False, reason=str(exc)))
     working = [item for item in results if item['supported']]
     assert working, 'no framesize produced a frame'
     for item in working:
@@ -39,8 +46,10 @@ def pixformats(opts):
             img = sensor.snapshot()
             results.append(dict(name=name, supported=True, width=img.width(), height=img.height(),
                                 actualBytes=img.size(), expectedBytes=img.width() * img.height() * depth))
-        except Exception:
-            results.append(dict(name=name, supported=False))
+        except Exception as exc:
+            if not is_unsupported(exc):
+                raise
+            results.append(dict(name=name, supported=False, reason=str(exc)))
     working = [item for item in results if item['supported']]
     assert working, 'no pixel format produced a frame'
     for item in working:
@@ -311,7 +320,6 @@ def run_check(name, opts):
         result = dict(name=name, status='PASS', data=data)
     except Exception as exc:
         message = str(exc)
-        unsupported = ('ESP_ERR_NOT_SUPPORTED', 'ESP_ERR_NOT_FOUND', 'no module named', 'ENODEV')
-        status = 'SKIP' if any(token.lower() in message.lower() for token in unsupported) else 'FAIL'
+        status = 'SKIP' if is_unsupported(exc) else 'FAIL'
         result = dict(name=name, status=status, error=dict(type=type(exc).__name__, message=message))
     print('__EVDEVICECHECK__' + json.dumps(result))

package/tests/hardware-check.mjs

@@ -7,7 +7,7 @@ export { tcpTransport, serialTransport } from '../src/node_transport.js'
 import { createDevice } from '../src/index.js'
 import { DEVICE_CHECKS, runDeviceChecks, saveJpeg } from './device-checks.mjs'
 
-export const usage = 'Usage: npm run test:hardware -- (--tcp HOST[:PORT] | --serial PATH) [--role usj|usb|uart] [--python PYTHON] [--write] [--capture] [--checks all|CSV] [--frames N] [--framesize QVGA] [--pixformat RGB565] [--quality 60] [--frame-timeout SECONDS] [--display-hold SECONDS] [--output CAMERA.jpg] [--screen-output LCD.jpg] [--timeout MILLISECONDS]'
+export const usage = 'Usage: npm run test:hardware -- (--tcp HOST[:PORT] | --serial PATH) [--role usj|usb|uart] [--python PYTHON] [--expect-board BOARD] [--expect-firmware-version VERSION] [--write] [--capture] [--checks all|CSV] [--require-all] [--frames N] [--framesize QVGA] [--pixformat RGB565] [--quality 60] [--frame-timeout SECONDS] [--display-hold SECONDS] [--output CAMERA.jpg] [--screen-output LCD.jpg] [--timeout MILLISECONDS]'
 const fail = (code, message) => Object.assign(new Error(message), { code })
 
 export function parseArgs(args) {
@@ -16,8 +16,8 @@ export function parseArgs(args) {
   for (let index = 0; index < args.length; index++) {
     const option = args[index]
     if (option === '--help') return { help: true }
-    if (option === '--write' || option === '--capture') { options[option.slice(2)] = true; continue }
-    if (!['--tcp', '--serial', '--role', '--python', '--timeout', '--checks', '--screen-output', '--output', '--frames', '--display-hold', '--framesize', '--pixformat', '--quality', '--frame-timeout'].includes(option)) throw fail('ARGUMENT', 'Unknown argument')
+    if (['--write', '--capture', '--require-all'].includes(option)) { options[option === '--require-all' ? 'requireAll' : option.slice(2)] = true; continue }
+    if (!['--tcp', '--serial', '--role', '--python', '--timeout', '--checks', '--screen-output', '--output', '--frames', '--display-hold', '--framesize', '--pixformat', '--quality', '--frame-timeout', '--expect-board', '--expect-firmware-version'].includes(option)) throw fail('ARGUMENT', 'Unknown argument')
     const value = args[++index]
     if (!value || value.startsWith('--')) throw fail('ARGUMENT', 'Missing argument value')
     const key = option.slice(2).replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())
@@ -75,13 +75,20 @@ export async function checkHardware(options, { device = createDevice({ transport
     await device.connect({ role: options.role, timeout: Math.min(options.timeout, 30000), signal: controller.signal })
     cancelled()
     const status = await device.inspect({ fields: ['identity', 'capabilities', 'runtime'], signal: controller.signal })
+    if (options.expectBoard && status.identity?.board !== options.expectBoard) throw fail('BOARD_MISMATCH', 'Connected board does not match the requested board')
+    if (options.expectFirmwareVersion && status.identity?.firmwareVersion !== options.expectFirmwareVersion) throw fail('FIRMWARE_MISMATCH', 'Running firmware does not match the selected build artifact')
     // Only selected public identity fields are logged; never network credentials or Python output.
-    report({ check: 'inspect', ok: true, identity: { deviceId: status.identity?.deviceId ?? null, board: status.identity?.board ?? null, hostname: status.identity?.hostname ?? null } })
+    report({ check: 'inspect', ok: true, identity: { deviceId: status.identity?.deviceId ?? null, board: status.identity?.board ?? null, hostname: status.identity?.hostname ?? null, firmwareVersion: status.identity?.firmwareVersion ?? null } })
     const marker = `EV_HARDWARE_${nonce}`
     const execution = await device.python.execute({ source: `print('${marker}')`, timeout: 10000, maxOutputChars: 1024, signal: controller.signal })
     if (!execution.ok || !execution.output.split(/\r?\n/).some(line => line.trim() === marker)) throw fail('PYTHON_CHECK', 'Python marker was not received')
     report({ check: 'python', ok: true })
     if (options.write) {
+      const storage = await device.inspect({ fields: ['storage'], signal: controller.signal })
+      const flash = storage.storage?.flash
+      const ready = flash?.present === true && flash?.mounted === true && flash?.writable === true
+      report({ check: 'storage', ok: ready, flash: { present: flash?.present ?? null, mounted: flash?.mounted ?? null, writable: flash?.writable ?? null, reason: flash?.reason ?? null } })
+      if (!ready) throw fail('STORAGE_UNAVAILABLE', 'File acceptance requires a mounted writable Flash filesystem; no formatting was attempted')
       const entries = await device.files.list({ path: '/', signal: controller.signal })
       if (entries.some(entry => entry.path === path || entry.path === `${path}.tmp`)) throw fail('TEST_PATH_EXISTS', 'Test path already exists; refusing to modify it')
       ownedPath = path

package/tests/test-browser-rom.mjs

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { openBrowserRom } from '../src/browser.js'
+import { browserRomCompatibility } from '../src/browser_rom_compat.js'
+
+const port = () => ({ open() { throw new Error('Port must remain passive') }, close() {} })
+test('browser ROM construction and disconnect are passive without browser globals', async () => {
+  const adapter = openBrowserRom({ port: port() })
+  assert.equal(adapter.chipFamily, null)
+  assert.equal(adapter.chipRevision, null)
+  assert.equal(adapter.chipName, null)
+  await adapter.disconnect(); await adapter.disconnect()
+  await assert.rejects(adapter.initialize(), { code: 'ROM_CLOSED' })
+})
+test('browser ROM validates its port and cancellation before loading the browser dependency', async () => {
+  assert.throws(() => openBrowserRom(), /SerialPort/)
+  assert.throws(() => openBrowserRom({ port: port(), signal: {} }), /AbortSignal/)
+  const controller = new AbortController()
+  controller.abort(new Error('cancelled before open'))
+  await assert.rejects(openBrowserRom({ port: port(), signal: controller.signal }).initialize(), /cancelled before open/)
+})
+test('SLIP prefix compatibility retries only pre-header bytes within the original deadline', async () => {
+  let count = 0
+  const loader = browserRomCompatibility({ async readPacket() {
+    if (++count < 3) throw new Error('Invalid head of packet (0x47)')
+    return [79, 72, 65, 73]
+  } })
+  assert.deepEqual(await loader.readPacket(100), [79, 72, 65, 73])
+  loader.readPacket = browserRomCompatibility({ readPacket: async () => { throw new Error('Invalid SLIP escape (0xdb, 0x47)') } }).readPacket
+  await assert.rejects(loader.readPacket(100), /Invalid SLIP escape/)
+})
+test('SLIP log noise cannot extend the operation deadline indefinitely', async () => {
+  let count = 0
+  const loader = browserRomCompatibility({ async readPacket() {
+    count++
+    await new Promise(resolve => setTimeout(resolve, 5))
+    throw new Error('Invalid head of packet (0x47)')
+  } })
+  await assert.rejects(loader.readPacket(15), /Invalid head/)
+  assert.ok(count <= 4)
+})
+function stubFixture({ native = true, error = 'Timed out waiting for packet header', handshake = true } = {}) {
+  let timeout, reads = 0
+  const stub = { IS_STUB: true, readPacket: async () => [], checkCommand: (...args) => { timeout = args[3] } }
+  const raw = {
+    isUsbJtagOrOtg: native,
+    memFinish: async () => { if (error) throw new Error(error) },
+    readPacket: async () => { reads++; return handshake ? [79, 72, 65, 73] : [] },
+    async runStub(skip) {
+      assert.equal(skip, true)
+      await this.memFinish()
+      assert.deepEqual(await this.readPacket(2500), [79, 72, 65, 73], 'OHAI required')
+      return stub
+    },
+  }
+  return { loader: browserRomCompatibility(raw), stub, timeout: () => timeout, reads: () => reads }
+}
+test('native USB may miss MEM_END acknowledgement but still requires OHAI', async () => {
+  const fixture = stubFixture()
+  assert.equal(await fixture.loader.runStub(true), fixture.stub)
+  assert.equal(fixture.reads(), 1)
+  await assert.rejects(stubFixture({ handshake: false }).loader.runStub(true), /OHAI required/)
+})
+test('UART timeouts and native USB non-timeout errors retain their failures', async () => {
+  await assert.rejects(stubFixture({ native: false }).loader.runStub(true), /Timed out/)
+  await assert.rejects(stubFixture({ error: 'Port disconnected' }).loader.runStub(true), /Port disconnected/)
+})
+test('stub launch restores temporary hooks on failure and rejects ROM fallback', async () => {
+  const fixture = stubFixture({ handshake: false })
+  const finish = fixture.loader.memFinish, packet = fixture.loader.readPacket
+  await assert.rejects(fixture.loader.runStub(true))
+  assert.equal(fixture.loader.memFinish, finish)
+  assert.equal(fixture.loader.readPacket, packet)
+  await assert.rejects(browserRomCompatibility({ runStub: async () => ({ IS_STUB: false }) }).runStub(true), /no supported browser flash stub/)
+})
+test('stub FLASH_BEGIN timeout scales with uncompressed erase size and preserves other commands', async () => {
+  const fixture = stubFixture()
+  const stub = await fixture.loader.runStub(true)
+  await stub.checkCommand(2, [0, 0, 128, 0], 0, 3000)
+  assert.ok(fixture.timeout() > 240000)
+  await stub.checkCommand(3, [], 0, 1234)
+  assert.equal(fixture.timeout(), 1234)
+})

package/tests/test-device-functional-checks.mjs

@@ -3,6 +3,7 @@ import test from 'node:test'
 import assert from 'node:assert/strict'
 import { readFile, mkdtemp, rm } from 'node:fs/promises'
 import { join } from 'node:path'
+import { EV_REPL_INPUT_MAX_BYTES, evReplExecInputBytes } from '../src/evrepl.js'
 import { tmpdir } from 'node:os'
 import { parseArgs } from './hardware-check.mjs'
 import { DEVICE_CHECKS, parseCheckResult, runDeviceChecks, saveJpeg } from './device-checks.mjs'
@@ -11,11 +12,11 @@ function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {})
   const files = new Map(), calls = [], listeners = new Map()
   return {
     calls, files, listeners,
-    async inspect({ fields }) { calls.push(['inspect', fields]); return { identity: { board, firmwareVersion: 'test' }, capabilities: { protocol: { evMuxVersion: 4 }, features: [] }, runtime: { vmReady: true } } },
+    async inspect({ fields }) { calls.push(['inspect', fields]); return { identity: { board, firmwareVersion: 'test' }, capabilities: { protocol: { evMuxVersion: 4 }, features: ['storage.writer.lease'], limits: { replInputMax: EV_REPL_INPUT_MAX_BYTES } }, runtime: { vmReady: true }, storage: { flash: { present: true, mounted: false, writable: false } } } },
     files: Object.assign(files, {
-      async list() { return [...files.keys()].map(path => ({ path })) },
-      async write({ path, data, overwrite }) { calls.push(['write', path]); assert.equal(overwrite, false); files.set(path, data) },
-      async remove({ path }) { calls.push(['remove', path]); files.delete(path) },
+      async list() { throw new Error('Runtime checks must not access storage') },
+      async write() { throw Object.assign(new Error('Flash unmounted'), { code: 'FILE_OPEN_FAILED' }) },
+      async remove() { throw new Error('Runtime checks must not access storage') },
     }),
     python: { async execute({ source }) {
       calls.push(['execute', source])
@@ -48,10 +49,15 @@ test('device check reports reject stale, duplicated and malformed markers', () =
   for (const output of ['', valid + '\n' + valid, '__EVDEVICECHECK__bad', valid.replace('memory', 'camera'), valid.replace('PASS', 'UNKNOWN')]) assert.throws(() => parseCheckResult(output, 'memory'), { code: 'CHECK_REPORT_INVALID' })
 })
 
-test('functional checks stage their shared fixture once and consume preview via public events', async () => {
+test('functional checks load fixtures in RAM despite unmounted storage and consume public preview events', async () => {
   const device = devicePeer(), reports = []
   await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'memory,preview,orientation']), { nonce: 'abc123', report: value => reports.push(value) })
-  assert.equal(device.calls.filter(call => call[0] === 'write').length, 1)
+  const commands = device.calls.filter(call => call[0] === 'execute').map(call => call[1])
+  assert.ok(commands.every(source => evReplExecInputBytes(source) <= EV_REPL_INPUT_MAX_BYTES))
+  assert.equal(commands.filter(source => source.startsWith("exec(''.join(")).length, 1)
+  const loader = commands.filter(source => source.includes("['_source']") || source.includes("={'_source':"))
+  const uploaded = loader.filter(source => source.includes("['_source'].append(")).map(source => JSON.parse(source.slice(source.indexOf('.append(') + 8, -1))).join('')
+  assert.equal(uploaded, await readFile(new URL('./fixtures/device-checks.py', import.meta.url), 'utf8'))
   assert.equal(device.files.size, 0)
   assert.equal(device.listeners.size, 0)
   assert.equal(reports.find(result => result.check === 'preview').data.received, 1)
@@ -96,3 +102,36 @@ test('truncated JPEG and missing dimensions are refused before host artifact is
   await assert.rejects(saveJpeg({ data: new Uint8Array([255, 216]), mimeType: 'image/jpeg', metadata: { width: 1, height: 1 } }), { code: 'CAPTURE_INVALID' })
   await assert.rejects(saveJpeg({ data: new Uint8Array([255, 216, 255, 217]), mimeType: 'image/jpeg' }), { code: 'CAPTURE_INVALID' })
 })
+
+
+test('strict acceptance fails unsupported selected checks without preventing independent identity evidence', async () => {
+  const device = devicePeer({ results: { memory: { name: 'memory', status: 'SKIP', error: { message: 'ESP_ERR_NOT_SUPPORTED' } } } }), reports = []
+  await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'memory,identity', '--require-all']), { nonce: 'abc123', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+  assert.equal(reports.find(result => result.check === 'memory').status, 'FAIL')
+  assert.equal(reports.find(result => result.check === 'identity').status, 'PASS')
+  assert.equal(reports.find(result => result.check === 'identity').data.storage.flash.mounted, false)
+})
+
+test('failed partial RAM loading still releases its namespace without filesystem cleanup', async () => {
+  const device = devicePeer(), reports = [], execute = device.python.execute
+  let failed = false
+  device.python.execute = async request => {
+    if (!failed && request.source.includes("['_source'].append")) { failed = true; throw new Error('fixture load failed') }
+    return execute(request)
+  }
+  await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'memory']), { nonce: 'abc123', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+  assert.ok(device.calls.some(call => call[0] === 'execute' && call[1].includes('del _evhil_abc123')))
+  assert.equal(reports.at(-1).failed, 1)
+})
+
+test('identity and RAM checks do not require optional storage inspection support', async () => {
+  const device = devicePeer(), inspect = device.inspect, reports = []
+  device.inspect = async request => {
+    assert.ok(!request.fields.includes('storage'))
+    const info = await inspect(request)
+    info.capabilities.features = []
+    return info
+  }
+  await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'identity,memory']), { nonce: 'abc123', report: value => reports.push(value) })
+  assert.deepEqual(reports.at(-1), { check: 'summary', passed: 2, failed: 0, skipped: 0 })
+})