@esp-vision/device-core 0.5.1 → 0.6.0

package/tests/test-browser-rom.mjs

@@ -2,84 +2,221 @@
 // SPDX-License-Identifier: Apache-2.0
 import test from 'node:test'
 import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
 import { openBrowserRom } from '../src/browser.js'
-import { browserRomCompatibility } from '../src/browser_rom_compat.js'
+import { createOfficialBrowserLoader, browserRomInterface, ROM_UART_BAUD_RATES } from '../src/browser_rom.js'
+import { browserTransportCompatibility, browserRomCompatibility, readBrowserFlash, romWords } from '../src/browser_rom_compat.js'
+import { romMd5 } from '../src/rom_md5.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() })
+const passivePort = () => ({ open() { throw new Error('Port must remain passive') }, close() {} })
+test('browser ROM construction and disconnect remain passive without browser globals', async () => {
+  const adapter = openBrowserRom({ port: passivePort() })
   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 () => {
+test('browser ROM validates its port and cancellation before loading the dependency', async () => {
   assert.throws(() => openBrowserRom(), /SerialPort/)
-  assert.throws(() => openBrowserRom({ port: port(), signal: {} }), /AbortSignal/)
+  assert.throws(() => openBrowserRom({ port: passivePort(), 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
-    },
+  await assert.rejects(openBrowserRom({ port: passivePort(), signal: controller.signal }).initialize(), /cancelled before open/)
+})
+test('interface discovery separates known bridge, OTG and JTAG; custom descriptors need evidence', () => {
+  const port = (usbVendorId, usbProductId) => ({ getInfo: () => ({ usbVendorId, usbProductId }) })
+  assert.equal(browserRomInterface(port(0x10c4, 0xea60)), 'uart')
+  assert.equal(browserRomInterface(port(0x303a, 32)), 'usb-otg')
+  assert.equal(browserRomInterface(port(0x303a, 0x1001)), 'usb-jtag')
+  assert.equal(browserRomInterface(port(0x303a, 0x1234)), 'unknown')
+  assert.equal(browserRomInterface(port(undefined, undefined)), 'unknown')
+  assert.equal(browserRomInterface(port(1, 2), 'uart'), 'uart')
+  assert.throws(() => browserRomInterface(port(1, 2), 'usb'), /interface/)
+})
+test('ROM transport MD5 matches independent known vectors and multi-block data', () => {
+  for (const input of ['', 'a', 'abc', 'message digest', 'a'.repeat(55), 'b'.repeat(56), 'c'.repeat(65), 'x'.repeat(65536)]) {
+    const bytes = new TextEncoder().encode(input)
+    assert.equal(Buffer.from(romMd5(bytes)).toString('hex'), createHash('md5').update(bytes).digest('hex'))
+  }
+})
+function transportFixture() {
+  return browserTransportCompatibility({ device: { readable: {}, writable: {} }, buffer: new Uint8Array(0),
+    appendArray(a, b) { return new Uint8Array([...a, ...b]) }, async write() {},
+  })
+}
+test('SLIP keeps a valid packet after boot noise, trailing packets and escaped bytes', async () => {
+  const transport = transportFixture()
+  transport.buffer = new Uint8Array([71, 97, 114, 0xc0, 0xc0, 79, 72, 65, 73, 0xc0, 0xc0, 0xdb, 0xdc, 0xdb, 0xdd, 0xc0])
+  assert.deepEqual(await transport.read(100), new Uint8Array([79, 72, 65, 73]))
+  assert.deepEqual(await transport.read(100), new Uint8Array([0xc0, 0xdb]))
+  transport.buffer = new Uint8Array([0xc0, 0xdb, 0x47, 0xc0])
+  await assert.rejects(transport.read(100), { code: 'ROM_SLIP_ESCAPE' })
+})
+test('SLIP preserves state across partial incoming chunks and has a total packet deadline', async () => {
+  const transport = transportFixture()
+  transport.buffer = new Uint8Array([0xc0, 1, 0xdb])
+  const later = setTimeout(() => { transport.buffer = new Uint8Array([0xdc, 2, 0xc0]) }, 5)
+  try { assert.deepEqual(await transport.read(100), new Uint8Array([1, 0xc0, 2])) } finally { clearTimeout(later) }
+  transport.buffer = new Uint8Array([0xc0, 1])
+  await assert.rejects(transport.read(15), { code: 'ROM_READ_TIMEOUT' })
+  transport.device.readable = null
+  await assert.rejects(transport.read(100), { code: 'ROM_PORT_LOST' })
+  transport.device.writable = null
+  await assert.rejects(transport.write(new Uint8Array()), { code: 'ROM_PORT_LOST' })
+})
+function readFixture({ data = new Uint8Array([1, 2, 3]), packets, digest = romMd5(data), delay = 0 } = {}) {
+  const received = [], reads = [...(packets ?? [data]), digest]
+  const loader = { IS_STUB: true, ESP_READ_FLASH: 0xd2, transport: { baudrate: 2000000,
+    async read() { if (delay) await new Promise(resolve => setTimeout(resolve, delay)); const packet = reads.shift(); if (!packet) throw new Error('missing packet'); return packet },
+    async write(bytes) { received.push(new DataView(bytes.buffer).getUint32(0, true)) },
+  }, async checkCommand(description, opcode, payload) { assert.equal(description, 'read flash'); assert.equal(opcode, 0xd2); assert.deepEqual(payload, romWords(0x20000, data.length, 1024, 1)); return 0 } }
+  return { loader, data, received, reads }
+}
+test('readback ACKs partial packets and consumes the delayed trailing digest before returning', async () => {
+  const f = readFixture({ packets: [new Uint8Array([1]), new Uint8Array([2, 3])], delay: 3 })
+  assert.deepEqual(await readBrowserFlash(f.loader, 0x20000, 3), f.data)
+  assert.deepEqual(f.received, [1, 3]); assert.equal(f.reads.length, 0)
+})
+test('readback rejects malformed packets, incomplete data, incorrect or absent digest', async () => {
+  for (const config of [{ packets: [new Uint8Array(0)] }, { packets: [new Uint8Array([1, 2, 3, 4])] }, { digest: new Uint8Array(16) }, { digest: new Uint8Array(15) }]) {
+    const f = readFixture(config)
+    await assert.rejects(readBrowserFlash(f.loader, 0x20000, 3), /packet|digest/i)
+  }
+  const f = readFixture(); f.loader.transport.read = async () => { throw Object.assign(new Error('timeout waiting for trailing digest'), { code: 'ROM_READ_TIMEOUT' }) }
+  await assert.rejects(readBrowserFlash(f.loader, 0x20000, 3), { code: 'ROM_READ_TIMEOUT' })
+})
+test('native USB MEM_END timeout exception never bypasses validated stub greeting', async () => {
+  const native = browserRomCompatibility({ memFinish: async () => { throw new Error('Timed out receiving a complete ROM packet') } }, { nativeUsb: true })
+  await native.memFinish()
+  const uart = browserRomCompatibility({ memFinish: async () => { throw new Error('Timed out') } })
+  await assert.rejects(uart.memFinish(), /Timed out/)
+  const lost = browserRomCompatibility({ memFinish: async () => { throw new Error('Port disconnected') } }, { nativeUsb: true })
+  await assert.rejects(lost.memFinish(), /disconnected/)
+})
+function officialFixture({ failRates = [], usb = false, security = { flags: 0, flashCryptCnt: 0 }, failWrite = false, recoverSecurity, recoverFamily, detach = false, reopenResets = false, flashId = 0x1840ef, stubStarts = true } = {}) {
+  const events = [], calls = [], loaders = [], opens = [], reads = []
+  const port = { readable: null, writable: null,
+    getInfo: () => ({ usbVendorId: usb ? 0x303a : 0x10c4, usbProductId: usb ? 32 : 0xea60 }),
+    async open({ baudRate }) { opens.push(baudRate); this.readable = {}; this.writable = {} },
+    async close() { this.readable = null; this.writable = null },
+  }
+  class FakeTransport {
+    constructor(device) { this.device = device; this.buffer = new Uint8Array(0); this.baudrate = 115200 }
+    appendArray(a, b) { return new Uint8Array([...a, ...b]) }
+    flushInput() { this.buffer = new Uint8Array(0) }
+    async disconnect() { calls.push('close'); await port.close() }
+    async changeBaudrate(rate) { calls.push(['retune', rate]); this.baudrate = rate; if (detach) throw Object.assign(new Error('Port detached'), { code: 'ROM_PORT_LOST' }); await port.close(); await port.open({ baudRate: rate }); if (reopenResets) loaders.at(-1).IS_STUB = false }
+    async write() {}
+    async setDTR(value) { calls.push(['dtr', value]) }
+    async setRTS(value) { calls.push(['rts', value]) }
+  }
+  class FakeLoader {
+    constructor({ transport }) { this.transport = transport; this.CHIP_DETECT_MAGIC_REG_ADDR = 0x40001000; this.ESP_CHANGE_BAUDRATE = 15; this.ESP_READ_FLASH = 0xd2; this.chip = { CHIP_NAME: loaders.length && recoverFamily ? recoverFamily : 'ESP32-S31', getChipRevision: async () => 0, postConnect: async () => calls.push('postConnect') }; loaders.push(this) }
+    async detectChip(mode) { calls.push(['detect', mode]); await port.open({ baudRate: 115200 }); this.transport.baudrate = 115200 }
+    async getSecurityInfo() { return loaders.length > 1 && recoverSecurity ? recoverSecurity : security }
+    async runStub() { calls.push('stub'); this.IS_STUB = stubStarts }
+    async readReg() { if (!this.IS_STUB || failRates.includes(this.transport.baudrate)) throw new Error('speed probe timeout'); return 123 }
+    async readFlashId() { return flashId }
+    async writeReg(...args) { calls.push(['register-write', ...args]) }
+    async checkCommand(description, _opcode, request) {
+      if (description === 'change baud rate') { calls.push(['change', new DataView(request.buffer).getUint32(0, true)]); return 0 }
+      const length = new DataView(request.buffer).getUint32(4, true), data = new Uint8Array(length)
+      const frame = bytes => new Uint8Array([0xc0, ...bytes, 0xc0])
+      // All-zero bytes and their digest need no SLIP escaping in this fixture.
+      const payload = []
+      for (let offset = 0; offset < length; offset += 1024) payload.push(...frame(data.slice(offset, offset + 1024)))
+      const md5 = romMd5(data)
+      const escaped = []
+      for (const byte of md5) { if (byte === 0xc0) escaped.push(0xdb, 0xdc); else if (byte === 0xdb) escaped.push(0xdb, 0xdd); else escaped.push(byte) }
+      payload.push(0xc0, ...escaped, 0xc0); this.transport.buffer = new Uint8Array(payload); reads.push(length)
+      return 0
+    }
+    async writeFlash(options) { calls.push(['write', options.compress, options.eraseAll, options.fileArray[0].address]); if (failWrite) throw new Error('write interrupted'); options.reportProgress(0, 10, 10) }
   }
-  return { loader: browserRomCompatibility(raw), stub, timeout: () => timeout, reads: () => reads }
+  const adapter = createOfficialBrowserLoader({ ESPLoader: FakeLoader, Transport: FakeTransport }, port, {}, { onStatus: event => events.push(event) })
+  return { adapter, events, calls, port, loaders, opens, 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)
+test('ROM UART starts at 115200, checks candidates in order and stops at the first success', async () => {
+  const f = officialFixture({ failRates: [2000000, 1500000] })
+  await f.adapter.initialize(); assert.equal(f.adapter.chipFamily, 0x3231)
+  const stub = await f.adapter.runStub(true)
+  assert.equal(stub.IS_STUB, true)
+  assert.equal(f.adapter.baudRate, 921600)
+  assert.deepEqual(f.events.filter(event => event.phase === 'baud-testing').map(event => event.baudRate), ROM_UART_BAUD_RATES.slice(0, 3))
+  assert.equal(f.loaders.length, 3, 'failed candidates must have fresh synchronized, qualified stubs')
+  assert.deepEqual(f.opens, [115200, 2000000, 115200, 1500000, 115200, 921600])
+  await stub.flashData(new ArrayBuffer(4), () => {}, 0x10000, false)
+  assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', true, false, 0x10000])
+  await f.adapter.disconnect()
+})
+test('all high rates fail safely back to validated 115200', async () => {
+  const f = officialFixture({ failRates: ROM_UART_BAUD_RATES.slice(0, -1) })
+  await f.adapter.initialize(); await f.adapter.runStub()
+  assert.equal(f.adapter.baudRate, 115200)
+  assert.deepEqual(f.events.filter(event => event.phase === 'baud-testing').map(event => event.baudRate), ROM_UART_BAUD_RATES)
+})
+test('port reopen that resets the board does not count as an initialized high-speed stub', async () => {
+  const f = officialFixture({ reopenResets: true })
+  await f.adapter.initialize(); await f.adapter.runStub()
+  assert.equal(f.adapter.baudRate, 115200)
+  assert.equal(f.loaders.length, 5)
+})
+test('native USB connects directly to ready ROM without UART rate or signal changes', async () => {
+  const f = officialFixture({ usb: true })
+  await f.adapter.initialize(); await f.adapter.runStub()
+  assert.deepEqual(f.calls[0], ['detect', 'no_reset'])
+  assert.equal(f.adapter.interface, 'usb-otg'); assert.equal(f.adapter.baudRate, null)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && ['retune', 'rts', 'dtr'].includes(call[0])))
+})
+test('recovery rechecks chip identity and security before another stub or write', async () => {
+  for (const setting of [{ recoverSecurity: { flags: 1, flashCryptCnt: 0 }, code: 'ROM_SECURITY' }, { recoverFamily: 'ESP32-S3', code: 'ROM_IDENTITY_CHANGED' }]) {
+    const f = officialFixture({ failRates: [2000000], ...setting })
+    await f.adapter.initialize()
+    await assert.rejects(f.adapter.runStub(), { code: setting.code })
+    assert.equal(f.calls.filter(call => call === 'stub').length, 1)
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  }
+})
+test('write interruption invalidates the session and never retries or resumes compressed data', async () => {
+  const f = officialFixture({ failWrite: true })
+  await f.adapter.initialize(); const stub = await f.adapter.runStub()
+  await assert.rejects(stub.flashData(new ArrayBuffer(4), () => {}, 0, true), /write interrupted/)
+  await assert.rejects(stub.readFlash(0, 4), /write interrupted/)
+  assert.equal(f.calls.filter(call => Array.isArray(call) && call[0] === 'write').length, 1)
+  assert.equal(f.port.readable, null)
+})
+test('detached download port is reported instead of blind fallback using a stale handle', async () => {
+  const f = officialFixture({ detach: true })
+  await f.adapter.initialize()
+  await assert.rejects(f.adapter.runStub(), { code: 'ROM_PORT_LOST' })
+  assert.equal(f.loaders.length, 1)
+})
+
+test('S31 native USB reset uses the watchdog without stale-port control signals', async () => {
+  const f = officialFixture({ usb: true })
+  await f.adapter.initialize(); await f.adapter.runStub(); await f.adapter.hardReset()
+  assert.deepEqual(f.calls.filter(call => Array.isArray(call) && call[0] === 'register-write'), [
+    ['register-write', 0x20801018, 0x50d83aa1], ['register-write', 0x20801004, 2000], ['register-write', 0x20801000, 0xd0000102], ['register-write', 0x20801018, 0],
+  ])
+  assert.ok(!f.calls.some(call => Array.isArray(call) && ['rts', 'dtr'].includes(call[0])))
+})
+
+test('SPI RDID normalizes only the documented24bits while rejecting non-register values', async () => {
+  for (const raw of [-15187898, 0xff184046]) {
+    const f = officialFixture({ usb: true, flashId: raw })
+    await f.adapter.initialize(); const stub = await f.adapter.runStub()
+    assert.equal(await stub.flashId(), 0x184046)
+  }
+  const f = officialFixture({ usb: true, flashId: NaN })
+  await f.adapter.initialize(); const stub = await f.adapter.runStub()
+  await assert.rejects(stub.flashId(), { code: 'ROM_FLASH_ID' })
+})
+
+test('missing native stub handshake never creates a usable stub or starts a write', async () => {
+  const f = officialFixture({ usb: true, stubStarts: false })
+  await f.adapter.initialize()
+  await assert.rejects(f.adapter.runStub(), { code: 'ROM_STUB_REQUIRED' })
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.equal(f.port.readable, null)
 })

package/tests/test-browser-serial.mjs

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { serialTransport } from '../src/browser.js'
+
+class Port extends EventTarget {
+  opens = []
+  openOptions = []
+  closes = 0
+  writes = []
+  lines = []
+  rejected = []
+  async open(options) {
+    const { baudRate } = options
+    this.openOptions.push(options)
+    this.opens.push(baudRate)
+    if (this.rejected.includes(baudRate)) throw new Error('unsupported speed')
+    assert.ok(!this.readable && !this.writable)
+    this.readable = new ReadableStream({ start: controller => { this.input = controller } })
+    this.writable = new WritableStream({ write: async bytes => {
+      if (this.writeGate) await this.writeGate
+      this.writes.push(new Uint8Array(bytes))
+    } })
+  }
+  async close() {
+    assert.ok(!this.readable?.locked, 'read lock must be released before SerialPort.close')
+    assert.ok(!this.writable?.locked, 'write lock must be released before SerialPort.close')
+    this.readable = this.writable = null
+    this.closes++
+  }
+  async setSignals(signals) { this.lines.push(signals) }
+  forget() { throw new Error('Internal retune must preserve browser authorization') }
+}
+
+test('browser runtime adapter is passive and reopens its authorized port without disconnect events', async () => {
+  const port = new Port(), transport = serialTransport({ port }), data = [], events = []
+  assert.deepEqual(port.opens, [])
+  const unsubscribe = transport.subscribe({ data: bytes => data.push(...bytes), close: () => events.push('close'), error: error => events.push(error.code) })
+  await transport.connect()
+  assert.deepEqual(port.opens, [115200])
+  port.input.enqueue(new Uint8Array([1, 2]))
+  await transport.setBaudRate(2000000)
+  port.input.enqueue(new Uint8Array([3, 4]))
+  await transport.writeBytes(new Uint8Array([5, 6]))
+  assert.deepEqual(data, [1, 2, 3, 4])
+  assert.deepEqual(port.opens, [115200, 2000000])
+  assert.deepEqual(port.openOptions, [{ baudRate: 115200, bufferSize: 256 * 1024 }, { baudRate: 2000000, bufferSize: 256 * 1024 }])
+  assert.equal(port.closes, 1)
+  assert.deepEqual(events, [])
+  assert.deepEqual(transport.getDiagnostics(), { baudRate: 2000000, connected: true, reopening: false })
+  assert.deepEqual(port.lines, [{ dataTerminalReady: true, requestToSend: false }, { dataTerminalReady: true, requestToSend: false }])
+  await transport.disconnect()
+  await transport.disconnect()
+  assert.equal(port.closes, 2)
+  assert.deepEqual(events, [])
+  unsubscribe()
+})
+
+test('browser retune waits for writes to finish and a rejected rate can reopen baseline', async () => {
+  const port = new Port(), transport = serialTransport({ port })
+  transport.subscribe({})
+  await transport.connect()
+  let release
+  port.writeGate = new Promise(resolve => { release = resolve })
+  const writing = transport.writeBytes(new Uint8Array([0xff, 0, 0x1e]))
+  const changing = transport.setBaudRate(2000000)
+  await new Promise(resolve => setTimeout(resolve, 1))
+  assert.equal(port.closes, 0)
+  release()
+  await writing
+  await changing
+  assert.deepEqual(port.writes[0], new Uint8Array([0xff, 0, 0x1e]))
+  port.rejected.push(1500000)
+  await assert.rejects(transport.setBaudRate(1500000), /unsupported speed/)
+  await transport.setBaudRate(115200)
+  assert.equal(transport.getDiagnostics().baudRate, 115200)
+  assert.deepEqual(port.opens, [115200, 2000000, 1500000, 115200])
+  await transport.disconnect()
+})
+
+test('physical browser disconnect is reported while internal reopen remains subscribed', async () => {
+  const port = new Port(), transport = serialTransport({ port }), events = []
+  transport.subscribe({ close: () => events.push('close') })
+  await transport.connect()
+  await transport.setBaudRate(921600)
+  assert.deepEqual(events, [])
+  port.dispatchEvent(new Event('disconnect'))
+  assert.deepEqual(events, ['close'])
+  await transport.disconnect()
+})
+
+test('native USB ports without modem control lines can still connect', async () => {
+  const port = new Port()
+  port.setSignals = async () => { throw Object.assign(new Error('No control lines'), { name: 'NotSupportedError' }) }
+  const transport = serialTransport({ port })
+  await transport.connect()
+  await transport.writeBytes(new Uint8Array([1]))
+  assert.deepEqual(port.writes, [new Uint8Array([1])])
+  await transport.disconnect()
+})
+
+test('browser cancellation releases a port that finishes opening late', async () => {
+  const port = new Port(), original = port.open.bind(port), transport = serialTransport({ port })
+  let finish
+  const started = new Promise(resolve => {
+    port.open = async options => { await new Promise(release => { finish = release; resolve() }); await original(options) }
+  })
+  const controller = new AbortController()
+  const connecting = transport.connect({ signal: controller.signal })
+  await started
+  controller.abort()
+  await assert.rejects(connecting, { name: 'AbortError' })
+  await transport.disconnect()
+  finish()
+  await new Promise(resolve => setTimeout(resolve, 1))
+  assert.equal(port.closes, 1)
+  assert.equal(port.readable, null)
+})
+
+test('an aborted retune cannot complete later at a stale rate after baseline recovery', async () => {
+  const port = new Port(), original = port.open.bind(port), transport = serialTransport({ port }), controller = new AbortController()
+  await transport.connect()
+  let finish
+  const started = new Promise(resolve => {
+    port.open = async options => {
+      if (options.baudRate === 2000000) await new Promise(release => { finish = release; resolve() })
+      await original(options)
+    }
+  })
+  const changing = transport.setBaudRate(2000000, { signal: controller.signal })
+  await started
+  controller.abort()
+  const failed = assert.rejects(changing, { name: 'AbortError' })
+  const recovery = transport.setBaudRate(115200)
+  finish()
+  await failed
+  await recovery
+  assert.deepEqual(port.opens, [115200, 2000000, 115200])
+  assert.equal(port.closes, 2, 'the stale high-rate open is closed before baseline is acquired')
+  assert.equal(transport.getDiagnostics().baudRate, 115200)
+  await transport.disconnect()
+})

package/tests/test-device-api.mjs

@@ -6,9 +6,10 @@ import * as api from '../src/index.js'
 import { DeviceSession, EV_MUX_REQUIRED_FEATURES, EV_MUX_REQUIRED_CHANNELS, EV_MUX_DEFAULT_LIMITS } from '../src/device_session.js'
 import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
 import { EvRepl } from '../src/evrepl.js'
+import { jpegFixture } from './jpeg-fixtures.mjs'
 
 const capabilities = { ok: true, protocol: { evMuxVersion: 4 },
-  features: [...EV_MUX_REQUIRED_FEATURES, 'debug.capture_frame', 'script.write', 'script.run', 'device.control'],
+  features: [...EV_MUX_REQUIRED_FEATURES, 'debug.capture_frame', 'debug.capture_frame.observed.v1', 'script.write', 'script.run', 'device.control'],
   channels: EV_MUX_REQUIRED_CHANNELS, limits: { ...EV_MUX_DEFAULT_LIMITS, txLargePayloadMax: 262144 },
   session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 } }
 function peer({ silent = false, screen = false, vmReady = true, interactiveScripts = false } = {}) {
@@ -44,7 +45,7 @@ function peer({ silent = false, screen = false, vmReady = true, interactiveScrip
     if (metadata.method === 'capabilities') result = { ...capabilities, features: [...capabilities.features, ...(screen ? ['debug.capture_screen'] : [])] }
     if (metadata.method === 'session.keepalive') result = { ok: true, sessionId: id, vmEpoch: 1 }
     if (metadata.method === 'debug.capture_frame' || (screen && metadata.method === 'debug.capture_screen')) {
-      handlers.data(makeEvMuxFrame({ channel: 'debug.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq, sessionId: id, vmEpoch: 1, contentType: 'image/jpeg', width: 2, height: 1, payload: new Uint8Array([255,216,0,255,217]) })); return false
+      handlers.data(makeEvMuxFrame({ channel: 'debug.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq, sessionId: id, vmEpoch: 1, contentType: 'image/jpeg', encoding: 'binary', width: 2, height: 1, payload: jpegFixture().data })); return false
     }
     handlers.data(makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq, ...((metadata.method !== 'capabilities' && (metadata.method !== 'hello' || payload.acquire)) ? {sessionId: id, vmEpoch: 1} : {}), payload: JSON.stringify(result) }))
     return false
@@ -86,6 +87,38 @@ test('facade subscribes before connection, negotiates, streams input and dispose
   await assert.rejects(d.files.read({path:'/x'}), {code:'DEVICE_NOT_READY'})
 })
 
+test('hard reset disposes an open transport without releasing its expired lease and permits reconnect', async () => {
+  const p = peer(), d = api.createDevice({ transport: p.transport })
+  try {
+    await d.connect({ role: 'tcp', probeRepl: false })
+    assert.deepEqual(await d.control({ action: 'reset', mode: 'hard' }), { ok: true })
+    assert.equal(p.disconnects, 0, 'the transport remains open after the reset ACK')
+    await d.disconnect()
+    assert.equal(p.disconnects, 1)
+    assert.equal(p.subscriptions, 0)
+    assert.equal(p.requests.filter(request => request.metadata.method === 'session.release').length, 0)
+    await d.connect({ role: 'tcp', probeRepl: false })
+    await d.disconnect()
+    assert.equal(p.disconnects, 2)
+    assert.equal(p.requests.filter(request => request.metadata.method === 'session.release').length, 1,
+      'normal disconnect still releases the new session')
+  } finally { await d.disconnect() }
+})
+
+test('bootloader submission survives facade cleanup without releasing the obsolete lease', async () => {
+  const p = peer(), d = api.createDevice({ transport: p.transport })
+  try {
+    await d.connect({ role: 'tcp', probeRepl: false })
+    assert.deepEqual(await d.control({ action: 'bootloader' }), {
+      ok: true, operation: 'bootloader', acknowledged: false, outcome: 'unknown',
+    })
+    await d.disconnect()
+    assert.equal(p.disconnects, 1)
+    assert.equal(p.subscriptions, 0)
+    assert.equal(p.requests.filter(r => r.metadata.method === 'session.release').length, 0)
+  } finally { await d.disconnect() }
+})
+
 test('connect can acquire and inspect a session without interrupting the REPL', async () => {
   const p = peer({ vmReady: false }), d = api.createDevice({ transport: p.transport })
   try {
@@ -113,7 +146,7 @@ test('capture returns binary bytes and unsupported LCD capture never captures th
   try {
     await d.connect({role:'tcp'})
     const image = await d.capture({source:'camera',quality:70})
-    assert.deepEqual(image.data,new Uint8Array([255,216,0,255,217]))
+    assert.deepEqual(image.data,jpegFixture().data)
     assert.equal(image.mimeType,'image/jpeg')
     const count=p.requests.length
     await assert.rejects(d.capture({source:'screen'}),{code:'UNSUPPORTED_OPERATION'})
@@ -200,13 +233,13 @@ test('binary capture results correlate by sequence even when responses arrive in
   let s;const requests=[]
   const parser=new EvMuxParser({filterFrame(metadata){requests.push(metadata);return false}})
   s=new DeviceSession({transport:{async writeBytes(b){parser.feedBytes(b)}},EvMuxParser,EvRepl,makeEvMuxFrame})
-  s.state='ready';s.sessionId='a'.repeat(32);s.vmEpoch=1;s.vmReady=true;s.capabilities={features:[]}
+  s.state='ready';s.sessionId='a'.repeat(32);s.vmEpoch=1;s.vmReady=true;s.capabilities={features:['debug.capture_frame', 'debug.capture_frame.observed.v1']}
   try {
     const first=s.captureImage('debug.capture_frame'),second=s.captureImage('debug.capture_frame')
     first.catch(()=>{});second.catch(()=>{})
     await new Promise(setImmediate)
-    for(const [index,payload] of [[1,22],[0,11]]){const req=requests[index];s.feedBytes(makeEvMuxFrame({channel:'debug.rpc',type:'rsp',method:req.method,seq:req.seq,sessionId:s.sessionId,vmEpoch:1,contentType:'image/jpeg',payload:new Uint8Array([payload])}))}
-    assert.deepEqual((await first).data,new Uint8Array([11]));assert.deepEqual((await second).data,new Uint8Array([22]))
+    for(const [index,name] of [[1,'alternate'],[0,'tiny']]){const req=requests[index];s.feedBytes(makeEvMuxFrame({channel:'debug.rpc',type:'rsp',method:req.method,seq:req.seq,sessionId:s.sessionId,vmEpoch:1,contentType:'image/jpeg',encoding:'binary',width:2,height:1,payload:jpegFixture(name).data}))}
+    assert.deepEqual((await first).data,jpegFixture().data);assert.deepEqual((await second).data,jpegFixture('alternate').data)
   }finally{s.close()}
 })
 
@@ -251,7 +284,7 @@ test('LCD capture uses its advertised screen method and preserves dimensions and
     assert.equal(image.mimeType, 'image/jpeg')
     assert.equal(image.metadata.width, 2)
     assert.equal(image.metadata.height, 1)
-    assert.deepEqual(image.data, new Uint8Array([255,216,0,255,217]))
+    assert.deepEqual(image.data, jpegFixture().data)
     const request = p.requests.find(x => x.metadata.method === 'debug.capture_screen')
     assert.deepEqual(request.payload, { quality: 85 })
     assert.equal(p.requests.some(x => x.metadata.method === 'debug.capture_frame'), false)

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

@@ -7,6 +7,7 @@ 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'
+import { jpegFixture } from './jpeg-fixtures.mjs'
 
 function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {}) {
   const files = new Map(), calls = [], listeners = new Map()
@@ -30,7 +31,7 @@ function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {})
     async capture({ source }) {
       calls.push(['capture', source])
       if (source === 'screen' && screenFails) throw Object.assign(new Error('Not supported'), { code: 'UNSUPPORTED_OPERATION' })
-      return { data: new Uint8Array([255, 216, 0, 255, 217]), mimeType: 'image/jpeg', metadata: { width: 240, height: 320 } }
+      return { data: jpegFixture('screen').data, mimeType: 'image/jpeg', metadata: { width: 240, height: 320 } }
     },
   }
 }
@@ -90,7 +91,7 @@ test('screen JPEG is captured while display fixture is alive and saved on host',
   const output = join(directory, 'screen.jpg'), device = devicePeer()
   try {
     await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'display', '--screen-output', output]), { nonce: 'abc123', report() {} })
-    assert.deepEqual(await readFile(output), Buffer.from([255, 216, 0, 255, 217]))
+    assert.deepEqual(await readFile(output), Buffer.from(jpegFixture('screen').data))
     const captureAt = device.calls.findIndex(call => call[0] === 'capture' && call[1] === 'screen')
     const closeAt = device.calls.findIndex(call => call[0] === 'execute' && call[1].includes("['close_display']()"))
     assert.ok(captureAt > 0 && closeAt > captureAt)
@@ -98,6 +99,15 @@ test('screen JPEG is captured while display fixture is alive and saved on host',
   } finally { await rm(directory, { recursive: true, force: true }) }
 })
 
+test('camera acceptance explicitly publishes an application snapshot before passive observation', async () => {
+  const device = devicePeer()
+  await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'camera']), { nonce: 'abc123', report() {} })
+  const published = device.calls.findIndex(call => call[0] === 'execute' && call[1].includes("['run_check'](\"camera\""))
+  const observed = device.calls.findIndex(call => call[0] === 'capture' && call[1] === 'camera')
+  assert.ok(published > 0 && observed > published)
+  assert.equal(device.files.size, 0)
+})
+
 test('truncated JPEG and missing dimensions are refused before host artifact is written', async () => {
   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' })

package/tests/test-device-operations-api.mjs

@@ -2,8 +2,9 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import { createDeviceOperations } from '../src/device_operations.js'
+import { jpegFixture } from './jpeg-fixtures.mjs'
 
-function fixture({ enabled = true, features = ['network.background', 'network.configure', 'debug.capture_frame', 'device.control', 'storage.writer.lease'] } = {}) {
+function fixture({ enabled = true, features = ['network.background', 'network.configure', 'debug.capture_frame', 'debug.capture_frame.observed.v1', 'device.control', 'storage.writer.lease'] } = {}) {
   const calls = []
   let operation = null
   let sequence = 0
@@ -17,7 +18,7 @@ function fixture({ enabled = true, features = ['network.background', 'network.co
     async forgetNetwork(opts) { calls.push(['forget', opts]); enabled = false; operation = { id: String(++sequence), state: 'succeeded' }; return { accepted: true, operationId: operation.id } },
     async rpc(method, payload, opts) { calls.push(['rpc', method, payload, opts]); return { ok: true } },
     async control(command, opts) { calls.push(['control', command, opts]); return { ok: true } },
-    async captureImage(method, payload, opts) { calls.push(['capture', method, payload, opts]); return { data: new Uint8Array([255, 216]), mimeType: 'image/jpeg', metadata: { seq: 1 } } },
+    async captureImage(method, payload, opts) { calls.push(['capture', method, payload, opts]); return { data: jpegFixture().data, mimeType: 'image/jpeg', metadata: { seq: 1, width: 2, height: 1 } } },
   }
   return { session, state, calls, api: createDeviceOperations({ session, state }) }
 }
@@ -107,7 +108,7 @@ test('control maps explicit commands, validates mode and can interrupt Python bu
 test('capture returns binary JPEG, forwards quality and never substitutes camera for unsupported screen', async () => {
   const { api, calls, state } = fixture()
   const image = await api.capture({ source: 'camera', format: 'jpeg', quality: 80 })
-  assert.deepEqual(image.data, new Uint8Array([255, 216]))
+  assert.deepEqual(image.data, jpegFixture().data)
   assert.equal(calls[0][1], 'debug.capture_frame')
   assert.deepEqual(calls[0][2], { quality: 80 })
   await assert.rejects(api.capture({ source: 'screen' }), error => error.code === 'UNSUPPORTED_OPERATION')