@esp-vision/device-core 0.5.1 → 0.6.0

package/tests/test-device-reset.mjs

@@ -0,0 +1,292 @@
+// 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 { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function fixture({ reset = 'ack', release = 'ack' } = {}) {
+  let session, respondReset, respondRelease
+  const requests = [], owner = 'a'.repeat(32)
+  const reply = (metadata, payload, owned = true) => session.feedBytes(makeEvMuxFrame({
+    channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq,
+    ...(owned ? { sessionId: owner, vmEpoch: 1 } : {}), payload: JSON.stringify(payload),
+  }))
+  const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const payload = metadata.channel.endsWith('.rpc') ? JSON.parse(new TextDecoder().decode(bytes)) : new TextDecoder().decode(bytes)
+    requests.push({ metadata, payload })
+    if (metadata.method === 'device.control' && payload.action === 'reset') {
+      if (['SESSION_REQUIRED', 'SESSION_EXPIRED', 'NOT_OWNER'].includes(reset)) {
+        reply(metadata, { ok: false, error: { code: reset, message: 'Session is no longer owned' } }, false)
+        return false
+      }
+      respondReset = () => reply(metadata, reset === 'reject'
+        ? { ok: false, error: { code: 'RESET_DENIED', message: 'Reset was rejected' } }
+        : { ok: true, action: 'reset' })
+      if (reset === 'write-error') throw Object.assign(new Error('Write failed'), { code: 'TRANSPORT_WRITE' })
+      if (reset === 'ack' || reset === 'reject') respondReset()
+    } else if (metadata.method === 'session.release') {
+      respondRelease = () => reply(metadata, { ok: true, accepted: true })
+      if (release === 'ack') respondRelease()
+    }
+    return false
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { parser.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  session.state = 'ready'
+  session.sessionId = owner
+  session.vmEpoch = 1
+  session.vmReady = true
+  session.capabilities = { features: ['device.control'] }
+  return { session, requests, owner, ack: () => respondReset(), ackRelease: () => respondRelease() }
+}
+
+test('hard-reset ACK invalidates the old session even while USJ remains open', async t => {
+  const f = fixture(); t.after(() => f.session.close())
+  f.session._startKeepalive()
+  const reset = f.session.control('hard-reset')
+  assert.equal(f.session.state, 'resetting')
+  assert.equal(f.session.keepaliveTimer, null)
+  assert.deepEqual(await reset, { ok: true, action: 'reset' })
+  assert.equal(f.session.state, 'disconnected')
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.keepaliveTimer, null)
+  assert.deepEqual(await f.session.release(), { ok: true, accepted: false })
+  assert.equal(f.requests.filter(r => r.metadata.method === 'session.release').length, 0)
+})
+
+test('reset timeout stays an unknown failure and cannot become a cleanup timeout', async t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const f = fixture({ reset: 'silent' }); t.after(() => f.session.close())
+  const reset = f.session.control('hard-reset', { timeout: 50 })
+  const rejected = assert.rejects(reset, error => error.code === 'TIMEOUT'
+    && error.message === 'EV-MUX device.control timeout' && error.reset?.outcome === 'unknown')
+  await new Promise(resolve => setImmediate(resolve))
+  t.mock.timers.tick(50)
+  await rejected
+  assert.equal(f.session.sessionId, null)
+  await f.session.release()
+  assert.equal(f.requests.length, 1, 'an uncertain reset is neither replayed nor followed by stale release')
+})
+
+test('transport loss and a partial write retain their original reset failures', async t => {
+  for (const mode of ['silent', 'write-error']) {
+    const f = fixture({ reset: mode }); t.after(() => f.session.close())
+    const result = f.session.control('hard-reset')
+    const expected = mode === 'silent' ? 'LINK_LOST' : 'TRANSPORT_WRITE'
+    const rejected = assert.rejects(result, error => error.code === expected && error.reset?.outcome === 'unknown')
+    if (mode === 'silent') f.session.close(Object.assign(new Error('Link lost'), { code: expected }))
+    await rejected
+    assert.equal(f.session.sessionId, null)
+    await f.session.release()
+    assert.equal(f.requests.length, 1)
+  }
+})
+
+test('pre-cancelled reset leaves the lease live; cancellation after submission invalidates it', async t => {
+  for (const before of [true, false]) {
+    const f = fixture({ reset: 'silent' }); t.after(() => f.session.close())
+    const controller = new AbortController()
+    const reason = Object.assign(new Error('Cancelled'), { code: 'CANCELLED' })
+    if (before) controller.abort(reason)
+    const reset = f.session.control('hard-reset', { signal: controller.signal })
+    const rejected = assert.rejects(reset, error => error === reason)
+    if (!before) controller.abort(reason)
+    await rejected
+    assert.equal(f.session.sessionId, before ? f.owner : null)
+    assert.equal(f.requests.length, before ? 0 : 1)
+  }
+})
+
+test('a confirmed reset rejection retains its live lease and normal release behavior', async t => {
+  const f = fixture({ reset: 'reject' }); t.after(() => f.session.close())
+  await assert.rejects(f.session.control('hard-reset'), { code: 'RESET_DENIED' })
+  assert.equal(f.session.state, 'ready')
+  assert.equal(f.session.sessionId, f.owner)
+  assert.notEqual(f.session.keepaliveTimer, null)
+  await f.session.release()
+  assert.equal(f.requests.filter(r => r.metadata.method === 'session.release').length, 1)
+})
+
+test('an ownership rejection discards the obsolete lease without claiming an unknown reset outcome', async t => {
+  for (const code of ['SESSION_REQUIRED', 'SESSION_EXPIRED', 'NOT_OWNER']) {
+    const f = fixture({ reset: code }); t.after(() => f.session.close())
+    await assert.rejects(f.session.control('hard-reset'), error => error.code === code && !error.reset)
+    assert.equal(f.session.state, 'disconnected')
+    assert.equal(f.session.sessionId, null)
+    await f.session.release()
+    assert.equal(f.requests.length, 1)
+  }
+})
+
+test('ordinary release timeouts and release failures after a rejected reset remain visible', async t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  for (const rejectedReset of [false, true]) {
+    const f = fixture({ reset: 'reject', release: 'silent' }); t.after(() => f.session.close())
+    if (rejectedReset) await assert.rejects(f.session.control('hard-reset'), { code: 'RESET_DENIED' })
+    const released = f.session.release({ timeout: 50 })
+    const rejected = assert.rejects(released, { code: 'TIMEOUT', message: 'EV-MUX session.release timeout' })
+    await new Promise(resolve => setImmediate(resolve))
+    t.mock.timers.tick(50)
+    await rejected
+  }
+})
+
+test('release joins a pending reset; concurrent commands cannot write during reset', async t => {
+  const f = fixture({ reset: 'defer' }); t.after(() => f.session.close())
+  const resetting = f.session.control('hard-reset')
+  await assert.rejects(f.session.control('hard-reset'), { code: 'DEVICE_RESETTING' })
+  await assert.rejects(f.session.control('stop'), { code: 'DEVICE_RESETTING' })
+  await assert.rejects(f.session.negotiate({ drainMs: 0 }), { code: 'DEVICE_RESETTING' })
+  assert.equal(f.session.state, 'resetting')
+  assert.equal(f.requests.length, 1)
+  const released = f.session.release()
+  f.ack()
+  await resetting
+  assert.deepEqual(await released, { ok: true, accepted: false })
+  assert.equal(f.requests.length, 1)
+})
+
+test('accepted reset settles pre-existing RPCs and clears pending timers', async t => {
+  const f = fixture(); t.after(() => f.session.close())
+  const pending = f.session.rpc('debug.info', { scope: 'transport.stats' })
+  const rejected = assert.rejects(pending, { code: 'DEVICE_RESET' })
+  await f.session.control('hard-reset')
+  await rejected
+  assert.equal(f.session.pendingRpc.size, 0)
+  assert.equal(f.session.keepaliveTimer, null)
+  assert.equal(f.session.resetPromise, null)
+})
+
+test('a release already in flight excludes a new destructive reset', async t => {
+  const f = fixture({ release: 'defer' }); t.after(() => f.session.close())
+  const releasing = f.session.release()
+  assert.equal(f.session.state, 'ready', 'release has not received its ACK yet')
+  await assert.rejects(f.session.control('hard-reset'), { code: 'DEVICE_RELEASING' })
+  assert.deepEqual(f.requests.map(r => r.metadata.method), ['session.release'])
+  f.ackRelease()
+  assert.deepEqual(await releasing, { ok: true, accepted: true })
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.pendingRpc.size, 0)
+})
+
+function replResetFixture({ write = async () => {} } = {}) {
+  const f = fixture()
+  const original = f.session.transport.writeBytes
+  f.session.transport.writeBytes = async bytes => {
+    await original(bytes)
+    const request = f.requests.at(-1)
+    if (request.metadata.channel.startsWith('repl.')) await write(request)
+  }
+  return f
+}
+
+test('bootloader submission invalidates the lease without claiming a ROM acknowledgement', async t => {
+  const f = replResetFixture(); t.after(() => f.session.close())
+  f.session._startKeepalive()
+  assert.deepEqual(await f.session.control('bootloader'), {
+    ok: true, operation: 'bootloader', acknowledged: false, outcome: 'unknown',
+  })
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.session.keepaliveTimer, null)
+  assert.deepEqual(await f.session.release(), { ok: true, accepted: false })
+  assert.deepEqual(f.requests.map(r => r.metadata.channel), ['repl.signal', 'repl.stdin'])
+  assert.match(f.requests[1].payload, /machine\.bootloader\(\)/)
+})
+
+test('release joins a pending bootloader write and excludes concurrent commands', async t => {
+  let complete
+  const f = replResetFixture({ write: request => request.metadata.channel === 'repl.stdin'
+    ? new Promise(resolve => { complete = resolve }) : undefined })
+  t.after(() => f.session.close())
+  const bootloader = f.session.control('bootloader')
+  await new Promise(resolve => setImmediate(resolve))
+  assert.equal(typeof complete, 'function')
+  await assert.rejects(f.session.control('bootloader'), { code: 'DEVICE_RESETTING' })
+  await assert.rejects(f.session.control('stop'), { code: 'DEVICE_RESETTING' })
+  await assert.rejects(f.session.control('hard-reset'), { code: 'DEVICE_RESETTING' })
+  const released = f.session.release()
+  complete()
+  await bootloader
+  assert.deepEqual(await released, { ok: true, accepted: false })
+  assert.equal(f.requests.length, 2)
+})
+
+test('bootloader partial writes preserve the original failure without stale release or replay', async t => {
+  const failure = Object.assign(new Error('USB interface removed during write'), { code: 'USB_GONE' })
+  const f = replResetFixture({ write: request => {
+    if (request.metadata.channel === 'repl.stdin') throw failure
+  } }); t.after(() => f.session.close())
+  await assert.rejects(f.session.control('bootloader'), error => error === failure
+    && error.reset?.outcome === 'unknown' && error.reset.acknowledged === false)
+  await f.session.release()
+  assert.equal(f.session.sessionId, null)
+  assert.equal(f.requests.length, 2)
+})
+
+test('pre-cancelled bootloader leaves its lease; cancellation during submission invalidates it', async t => {
+  for (const before of [true, false]) {
+    const controller = new AbortController()
+    const reason = Object.assign(new Error('Cancelled'), { code: 'CANCELLED' })
+    const f = replResetFixture({ write: request => request.metadata.channel === 'repl.stdin'
+      ? new Promise(() => {}) : undefined }); t.after(() => f.session.close())
+    if (before) controller.abort(reason)
+    const result = f.session.control('bootloader', { signal: controller.signal })
+    const rejected = assert.rejects(result, error => error === reason)
+    if (!before) {
+      await new Promise(resolve => setImmediate(resolve))
+      controller.abort(reason)
+    }
+    await rejected
+    assert.equal(f.session.sessionId, before ? f.owner : null)
+    assert.equal(f.requests.length, before ? 0 : 2)
+  }
+})
+
+test('a bounded bootloader write timeout remains unknown and never becomes a release timeout', async t => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const f = replResetFixture({ write: request => request.metadata.channel === 'repl.stdin'
+    ? new Promise(() => {}) : undefined }); t.after(() => f.session.close())
+  const result = f.session.control('bootloader', { timeout: 50 })
+  const rejected = assert.rejects(result, error => error.code === 'TIMEOUT'
+    && error.message === 'Device reset submission timed out' && error.reset?.outcome === 'unknown')
+  await new Promise(resolve => setImmediate(resolve))
+  t.mock.timers.tick(50)
+  await rejected
+  await f.session.release()
+  assert.equal(f.requests.length, 2)
+})
+
+test('failure before a bootloader command retains its live lease and normal cleanup', async t => {
+  const failure = Object.assign(new Error('Interrupt write failed'), { code: 'WRITE_FAILED' })
+  const f = replResetFixture({ write: () => { throw failure } }); t.after(() => f.session.close())
+  await assert.rejects(f.session.control('bootloader'), error => error === failure && !error.reset)
+  assert.equal(f.session.sessionId, f.owner)
+  assert.equal(f.session.state, 'ready')
+  await f.session.release()
+  assert.deepEqual(f.requests.map(r => r.metadata.channel), ['repl.signal', 'user.rpc'])
+})
+
+test('bootloader cleanup waits for an actual transport drain, without treating it as a device ACK', async t => {
+  let drained
+  const f = replResetFixture(); t.after(() => f.session.close())
+  f.session.transport.drain = () => new Promise(resolve => { drained = resolve })
+  const resetting = f.session.control('bootloader')
+  const release = f.session.release()
+  await new Promise(resolve => setImmediate(resolve))
+  assert.equal(f.session.state, 'resetting')
+  assert.equal(f.session.sessionId, f.owner)
+  drained()
+  assert.equal((await resetting).acknowledged, false)
+  assert.deepEqual(await release, { ok: true, accepted: false })
+  assert.equal(f.requests.length, 2)
+})
+
+test('a release already in flight excludes a bootloader command', async t => {
+  const f = fixture({ release: 'defer' }); t.after(() => f.session.close())
+  const releasing = f.session.release()
+  await assert.rejects(f.session.control('bootloader'), { code: 'DEVICE_RELEASING' })
+  assert.equal(f.requests.length, 1)
+  f.ackRelease()
+  await releasing
+})

package/tests/test-firmware-flash.mjs

@@ -28,7 +28,7 @@ test('application-only write is read back in full before reset, with port cleanu
   const f = await fixture()
   await f.session.connect(f.bytes)
   await f.session.flash(f.bytes)
-  assert.deepEqual(f.calls, [['initialize'], ['stub', true], ['read', 0x8000], ['write', 0x10000, false], ['read', 0x10000], ['reset'], ['close']])
+  assert.deepEqual(f.calls, [['initialize'], ['stub', true], ['read', 0x8000], ['write', 0x10000, true], ['read', 0x10000], ['reset'], ['close']])
 })
 test('corrupt readback never reports success or resets into unverified firmware', async () => {
   const f = await fixture()

package/tests/test-jpeg-validation.mjs

@@ -0,0 +1,233 @@
+// 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 { validateJpegImage } from '../src/jpeg_validate.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { DeviceSession } from '../src/device_session.js'
+import { EvRepl } from '../src/evrepl.js'
+import { DeviceActionRegistry } from '../src/device_actions.js'
+import { bindSessionDeviceActions } from '../src/device_bindings.js'
+import { JPEG_FIXTURES, jpegFixture } from './jpeg-fixtures.mjs'
+
+const invalidImage = error => error.code === 'INVALID_IMAGE' && /^Invalid JPEG image: /.test(error.message)
+const join = (...parts) => Uint8Array.from(parts.flatMap(part => Array.from(part)))
+const change = (bytes, offset, value) => { const result = bytes.slice(); result[offset] = value; return result }
+// Locate a known fixture's header segments only; this is not a JPEG validator.
+function headers(bytes) {
+  const result = []
+  for (let start = 2; start < bytes.length;) {
+    const marker = bytes[start + 1], length = bytes[start + 2] * 256 + bytes[start + 3]
+    result.push({ marker, start, end: start + length + 2 })
+    if (marker === 0xda) break
+    start += length + 2
+  }
+  return result
+}
+const header = (bytes, marker) => headers(bytes).find(segment => segment.marker === marker)
+const replace = (bytes, segment, replacement) => join(bytes.subarray(0, segment.start), replacement, bytes.subarray(segment.end))
+const segment = (marker, content) => join([0xff, marker, (content.length + 2) >> 8, (content.length + 2) & 255], content)
+
+test('self-created baseline and progressive JPEG fixtures pass structural and metadata checks', () => {
+  for (const name of Object.keys(JPEG_FIXTURES)) {
+    const image = jpegFixture(name)
+    assert.deepEqual(validateJpegImage(image.data, image), { width: image.width, height: image.height })
+  }
+  const image = jpegFixture(), sos = header(image.data, 0xda)
+  // Metadata markers and unused 16-bit tables are bounded but do not alter pixels.
+  const unusedQuant = segment(0xdb, [0x13, ...Array.from({ length: 64 }, () => [0, 1]).flat()])
+  const enriched = join(image.data.subarray(0, sos.start), segment(0xfe, [65, 66]), unusedQuant, image.data.subarray(sos.start))
+  assert.deepEqual(validateJpegImage(enriched, image), { width: 2, height: 1 })
+})
+
+test('JPEG validation rejects fake images, every truncated prefix, trailing bytes and mismatched dimensions', () => {
+  const image = jpegFixture()
+  for (const bytes of [new Uint8Array(), Uint8Array.of(0xff, 0xd8, 0xff, 0xd9), join(image.data, [0]), change(image.data, 0, 0)]) {
+    assert.throws(() => validateJpegImage(bytes, image), invalidImage)
+  }
+  for (let length = 0; length < image.data.length; length++) {
+    assert.throws(() => validateJpegImage(image.data.subarray(0, length), image), invalidImage, `prefix ${length}`)
+  }
+  assert.throws(() => validateJpegImage(Array.from(image.data), image), invalidImage)
+  for (const metadata of [{}, { width: '2', height: 1 }, { width: 2.5, height: 1 }, { width: 2, height: 0 }, { width: 2, height: 65536 }, { width: 3, height: 1 }]) {
+    assert.throws(() => validateJpegImage(image.data, metadata), invalidImage)
+  }
+})
+
+test('JPEG table, component and scan references fail closed within segment bounds', () => {
+  const image = jpegFixture(), bytes = image.data
+  const sof = header(bytes, 0xc0), dqt = header(bytes, 0xdb), dht = header(bytes, 0xc4), sos = header(bytes, 0xda)
+  const oversized = change(change(bytes, dqt.start + 2, 0xff), dqt.start + 3, 0xff)
+  const used16bitQuant = replace(bytes, dqt, segment(0xdb, [0x10, ...Array.from({ length: 64 }, () => [0, 1]).flat()]))
+  const repeatedSof = join(bytes.subarray(0, sos.start), bytes.subarray(sof.start, sof.end), bytes.subarray(sos.start))
+  const missingCoverage = replace(bytes, sos, segment(0xda, [1, bytes[sos.start + 5], bytes[sos.start + 6], 0, 63, 0]))
+  const malformed = [
+    oversized, change(bytes, dqt.start + 5, 0), used16bitQuant,
+    change(bytes, dht.start + 4, 0x24), // unsupported Huffman selector
+    change(bytes, dht.start + 5, 3), // more one-bit codes than available
+    change(bytes, dht.start + 5, 2), // entirely occupied code space, reserved all-ones code
+    change(bytes, sof.start + 1, 0xc3), // unsupported lossless frame
+    change(bytes, sof.start + 4, 12), // unsupported sample precision
+    change(bytes, sof.start + 13, bytes[sof.start + 10]), // repeated component id
+    change(bytes, sof.start + 11, 0x50), // invalid sampling factor
+    change(bytes, sof.start + 12, 3), // missing quantization table
+    repeatedSof, missingCoverage,
+    change(bytes, sos.start + 5, 99), // undefined component
+    change(bytes, sos.start + 6, 0x33), // missing Huffman tables
+    change(bytes, sos.end - 2, 62), // sequential scans must include coefficients 0..63
+  ]
+  for (const candidate of malformed) assert.throws(() => validateJpegImage(candidate, image), invalidImage)
+})
+
+test('entropy stuffing, restart order and every restart segment require bounded nonempty data', () => {
+  const image = jpegFixture(), sos = header(image.data, 0xda)
+  const prefix = image.data.subarray(0, sos.start), scanHeader = image.data.subarray(sos.start, sos.end)
+  const dri = segment(0xdd, [0, 1]), eoi = [0xff, 0xd9]
+  const malformed = [
+    join(prefix, scanHeader, eoi),
+    join(prefix, scanHeader, [1, 0xff, 0xff, 0, 2], eoi),
+    join(prefix, scanHeader, [1, 0xff, 0xd0, 2], eoi), // no DRI
+    join(prefix, dri, scanHeader, [0xff, 0xd0, 1], eoi), // empty first segment
+    join(prefix, dri, scanHeader, [1, 0xff, 0xd0], eoi), // empty last segment
+    join(prefix, dri, scanHeader, [1, 0xff, 0xd1, 2], eoi), // sequence must start at RST0
+    join(prefix, dri, scanHeader, [1, 0xff, 0xd0, 2, 0xff, 0xd0, 3], eoi),
+  ]
+  for (const candidate of malformed) assert.throws(() => validateJpegImage(candidate, image), invalidImage)
+  // These mutations demonstrate structural scope only; entropy is deliberately not decoded.
+  assert.doesNotThrow(() => validateJpegImage(join(prefix, dri, scanHeader, [1, 0xff, 0xd0, 2, 0xff, 0xd1, 3], eoi), image))
+  assert.doesNotThrow(() => validateJpegImage(join(prefix, scanHeader, [1, 0xff, 0, 2], eoi), image))
+})
+
+test('progressive scan layout and initial component coverage are validated without decoding coefficients', () => {
+  const image = jpegFixture('progressive'), bytes = image.data, sos = header(bytes, 0xda)
+  assert.throws(() => validateJpegImage(change(bytes, sos.end - 2, 63), image), invalidImage, 'a DC scan must end at coefficient zero')
+  assert.throws(() => validateJpegImage(change(bytes, sos.end - 1, 0x31), image), invalidImage, 'successive approximation must progress by one bit')
+  assert.throws(() => validateJpegImage(change(bytes, sos.start + 6, 0x30), image), invalidImage, 'initial DC scan needs its selected Huffman table')
+  const noInitialDc = change(bytes, sos.end - 1, 0x10)
+  assert.throws(() => validateJpegImage(noInitialDc, image), invalidImage, 'refinement alone does not establish initial component coverage')
+})
+
+function fixture(t) {
+  const requests = [], events = { preview: [], debugImage: [], rpcResponse: [], diagnostic: [] }
+  const recorder = new EvMuxParser({ filterFrame(metadata) { requests.push(metadata); return false } })
+  const session = new DeviceSession({ transport: { async writeBytes(bytes) { recorder.feedBytes(bytes) } },
+    handlers: Object.fromEntries(Object.keys(events).map(name => [name, (...args) => events[name].push(args)])), EvMuxParser, makeEvMuxFrame, EvRepl })
+  session.state = 'ready'; session.sessionId = 'a'.repeat(32); session.vmEpoch = 1; session.vmReady = true
+  session.capabilities = { features: ['debug.capture_frame', 'debug.capture_frame.observed.v1', 'debug.capture_screen'] }
+  t.after(() => session.close())
+  const imageFrame = (request, { image = jpegFixture(), payload = image.data, ...overrides } = {}) => makeEvMuxFrame({
+    ...request, channel: request.channel ?? 'debug.rpc', type: 'rsp', method: request.method ?? 'debug.capture_frame',
+    sessionId: session.sessionId, vmEpoch: 1, contentType: 'image/jpeg', encoding: 'binary',
+    width: image.width, height: image.height, payload, ...overrides,
+  })
+  const jsonFrame = (request, payload, overrides = {}) => makeEvMuxFrame({ ...request, type: 'rsp', sessionId: session.sessionId, vmEpoch: 1, payload, ...overrides })
+  return { session, requests, events, imageFrame, jsonFrame }
+}
+const tick = () => new Promise(setImmediate)
+function feedFragments(session, bytes) {
+  for (let cursor = 0, size = 1; cursor < bytes.length; size = size % 19 + 1) {
+    session.feedBytes(bytes.subarray(cursor, cursor + size)); cursor += size
+  }
+}
+
+test('CRC-valid malformed camera and screen JPEGs reject correlated captures immediately with no image callback', async t => {
+  const f = fixture(t)
+  for (const method of ['debug.capture_frame', 'debug.capture_screen']) {
+    const pending = f.session.captureImage(method, {}, { timeout: 5000 })
+    const rejected = assert.rejects(pending, invalidImage)
+    await tick()
+    feedFragments(f.session, f.imageFrame(f.requests.at(-1), { payload: Uint8Array.of(0xff, 0xd8, 0xff, 0xd9) }))
+    await rejected
+    assert.equal(f.session.pendingRpc.size, 0)
+  }
+  assert.equal(f.events.debugImage.length, 0); assert.equal(f.events.preview.length, 0); assert.equal(f.events.rpcResponse.length, 0)
+  assert.equal(f.session.parser.getDiagnostics().invalidImageFrames, 2)
+  assert.equal(f.session.parser.getDiagnostics().droppedFrames, 2)
+  assert.equal(f.events.diagnostic.filter(([value]) => value.event === 'image.invalid').length, 2)
+  const next = f.session.captureImage('debug.capture_frame'); await tick()
+  feedFragments(f.session, f.imageFrame(f.requests.at(-1)))
+  assert.deepEqual((await next).data, jpegFixture().data, 'a valid image recovers after rejected frames')
+})
+
+test('a CRC-damaged image is dropped before JPEG validation and does not consume the matching request', async t => {
+  const f = fixture(t), pending = f.session.captureImage('debug.capture_frame'); await tick()
+  const request = f.requests.at(-1), frame = f.imageFrame(request)
+  frame[frame.length - jpegFixture().data.length - 1] = 0 // corrupt SOI, retaining the original frame CRC
+  feedFragments(f.session, frame)
+  assert.equal(f.session.pendingRpc.size, 1)
+  assert.equal(f.session.parser.getDiagnostics().invalidImageFrames, 0)
+  assert.equal(f.session.parser.getDiagnostics().droppedFrames, 1)
+  assert.equal(f.events.debugImage.length, 0)
+  f.session.feedBytes(f.imageFrame(request))
+  assert.deepEqual((await pending).data, jpegFixture().data)
+})
+
+test('invalid previews drop a complete frame, retain pending requests and recover on fragmented valid preview', async t => {
+  const f = fixture(t)
+  const pending = f.session.rpc('debug.info', { scope: 'transport.stats' }); await tick()
+  const request = f.requests.at(-1)
+  for (const overrides of [{ payload: Uint8Array.of(0xff, 0xd8, 0xff, 0xd9) }, { width: 99 }, { encoding: 'text' }, { type: 'rsp' }]) {
+    feedFragments(f.session, f.imageFrame({ channel: 'preview.frame', seq: request.seq }, { type: 'data', ...overrides }))
+    assert.equal(f.session.pendingRpc.size, 1)
+  }
+  assert.equal(f.events.preview.length, 0); assert.equal(f.events.debugImage.length, 0)
+  feedFragments(f.session, f.imageFrame({ channel: 'preview.frame', seq: request.seq }, { type: 'data' }))
+  assert.equal(f.events.preview.length, 1)
+  assert.deepEqual(f.events.preview[0][2], jpegFixture().data)
+  const stats = f.session.parser.getDiagnostics()
+  assert.equal(stats.invalidImageFrames, 4); assert.equal(stats.droppedFrames, 4); assert.equal(stats.frames, 1)
+  f.session.feedBytes(f.jsonFrame(request, JSON.stringify({ ok: true, stats: {} })))
+  assert.equal((await pending).ok, true)
+})
+
+test('capture JSON success, malformed JSON and nonbinary JPEG reject while firmware capture errors remain explicit', async t => {
+  const f = fixture(t)
+  for (const response of [
+    request => f.jsonFrame(request, JSON.stringify({ ok: true })),
+    request => f.jsonFrame(request, '{'),
+    request => f.jsonFrame(request, JSON.stringify({ ok: false })),
+    request => f.imageFrame(request, { encoding: 'json' }),
+    request => f.imageFrame(request, { contentType: 'image/png' }),
+    request => f.jsonFrame(request, JSON.stringify({ ok: false, error: { code: 'NOT_OWNER' } }), { contentType: 'image/jpeg', sessionId: undefined, vmEpoch: undefined }),
+  ]) {
+    // Even lower-level generic RPC callers cannot accept a JPEG-less capture success.
+    const pending = f.session.rpc('debug.capture_frame', {}, { timeout: 5000 })
+    const rejected = assert.rejects(pending, invalidImage); await tick()
+    f.session.feedBytes(response(f.requests.at(-1))); await rejected
+  }
+  const pending = f.session.captureImage('debug.capture_screen'); const rejected = assert.rejects(pending, { code: 'JPEG_FAILED' }); await tick()
+  f.session.feedBytes(f.jsonFrame(f.requests.at(-1), JSON.stringify({ ok: false, error: { code: 'JPEG_FAILED', message: 'Encoding failed' } })))
+  await rejected
+  assert.equal(f.events.debugImage.length, 0); assert.equal(f.events.rpcResponse.length, 1)
+})
+
+test('malformed stale image responses cannot reject captures or unrelated RPCs', async t => {
+  const f = fixture(t), pending = f.session.captureImage('debug.capture_frame'), query = f.session.rpc('debug.info', { scope: 'transport.stats' })
+  await tick()
+  const capture = f.requests.find(request => request.method === 'debug.capture_frame'), info = f.requests.find(request => request.method === 'debug.info')
+  for (const overrides of [{ seq: capture.seq + 100 }, { sessionId: 'b'.repeat(32) }, { vmEpoch: 2 }, { method: 'debug.capture_screen' }, { seq: info.seq }]) {
+    f.session.feedBytes(f.imageFrame(capture, { payload: Uint8Array.of(0xff, 0xd8, 0xff, 0xd9), ...overrides }))
+    f.session.feedBytes(f.jsonFrame({ ...capture, ...overrides }, JSON.stringify({ ok: true }), overrides))
+    assert.equal(f.session.pendingRpc.size, 2)
+  }
+  assert.equal(f.session.parser.getDiagnostics().invalidImageFrames, 0, 'correlation rejects stale responses before JPEG validation')
+  assert.equal(f.events.debugImage.length, 0)
+  f.session.feedBytes(f.jsonFrame(info, JSON.stringify({ ok: true, stats: { marker: 7 } })))
+  f.session.feedBytes(f.imageFrame(capture))
+  assert.equal((await query).stats.marker, 7); assert.deepEqual((await pending).data, jpegFixture().data)
+})
+
+test('frame.capture action returns its own binary image when concurrent responses arrive in reverse order', async t => {
+  const f = fixture(t), registry = new DeviceActionRegistry(); bindSessionDeviceActions(registry)
+  const capture = registry.handler('frame.capture')
+  const first = capture({ timeoutMs: 5000 }, { session: f.session }), second = capture({ timeoutMs: 5000 }, { session: f.session })
+  await tick()
+  const firstRequest = f.requests[0], secondRequest = f.requests[1]
+  f.session.feedBytes(f.imageFrame(secondRequest, { image: jpegFixture('small') }))
+  f.session.feedBytes(f.imageFrame(firstRequest, { image: jpegFixture('alternate') }))
+  const [a, b] = await Promise.all([first, second])
+  assert.equal(a.base64, JPEG_FIXTURES.alternate.base64); assert.equal(a.metadata.seq, firstRequest.seq)
+  assert.equal(a.metadata.width, 2); assert.equal(a.metadata.height, 1)
+  assert.equal(b.base64, JPEG_FIXTURES.small.base64); assert.equal(b.metadata.seq, secondRequest.seq)
+  assert.equal(b.metadata.width, 4); assert.equal(b.metadata.height, 3)
+})