@esp-vision/device-core 0.5.1 → 0.6.1

package/src/device_session.js

@@ -8,9 +8,12 @@
  * drift between the two entry points.
  */
 
+import { requireObservedCameraCapture } from './device_capture.js'
+
 export const EV_MUX_PAYLOAD_LIMIT = 1800
 export const EV_MUX_SCRIPT_CHUNK_BYTES = 900
 export const EV_MUX_VERSION = 4
+export const UART_BAUD_CANDIDATES = Object.freeze([2000000, 1500000, 921600, 460800, 115200])
 const INLINE_PYTHON_REPL_TIMEOUT_MS = 5000
 const SCRIPT_START_ACK_TIMEOUT_MS = 5000
 // MicroPython has a 128-byte VFS path buffer; script.write also appends .tmp.
@@ -49,6 +52,9 @@ const EV_MUX_USER_RPC_METHODS = new Set([
   'capabilities',
   'session.keepalive',
   'session.release',
+  'transport.uart.prepare',
+  'transport.uart.probe',
+  'transport.uart.commit',
   'file.write',
   'script.write',
   'script.run',
@@ -333,6 +339,7 @@ export class DeviceSession {
     this.negotiatePromise = null
     this.negotiateController = null
     this.releasePromise = null
+    this.resetPromise = null
     this.vmReadinessProbeActive = false
     this.pendingRpc = new Map()
     this.draining = false
@@ -360,10 +367,19 @@ export class DeviceSession {
       },
       rawText: (text) => this.handlers.rawText?.(text),
       preview: (base64, metadata, bytes) => this.handlers.preview?.(base64, metadata, bytes),
+      invalidImage: (metadata, error, payload) => {
+        this._diagnostic('image.invalid', { channel: metadata.channel, method: metadata.method ?? null, seq: metadata.seq,
+          code: 'INVALID_IMAGE', reason: error.reason ?? 'invalid JPEG structure' })
+        const seq = Number(metadata.seq), pending = this.pendingRpc.get(seq)
+        if (metadata.type === 'rsp' && pending && this._matchesPendingResponse(metadata, payload)) {
+          this.pendingRpc.delete(seq)
+          pending.reject(error)
+        }
+      },
       debugImage: (base64, metadata, bytes, frameMetadata) => {
         this.lastDebugImage = { base64, metadata }
         const pending = this.pendingRpc.get(Number(metadata.seq))
-        if (pending?.binaryResponse && frameMetadata && this._matchesPendingResponse(frameMetadata, { ok: true })) {
+        if (pending && frameMetadata && this._matchesPendingResponse(frameMetadata, { ok: true })) {
           pending.image = { data: bytes.slice(), mimeType: 'image/jpeg', metadata: { ...metadata } }
         }
         this.handlers.debugImage?.(base64, metadata)
@@ -691,10 +707,12 @@ export class DeviceSession {
     signal = null,
     writeTimeout = null,
     encoding = undefined,
+    resetToken = null,
   } = {}) {
     if (this.state === 'disconnected') {
       throw new Error('EV-MUX is not connected')
     }
+    if (type === 'req' && method === 'debug.capture_frame') requireObservedCameraCapture(this)
     const seq = requestedSeq === null ? this._allocateSequence() : requestedSeq >>> 0
     const requestPayload = typeof payload === 'string' && method
       ? (() => { try { return JSON.parse(payload) } catch (_err) { return {} } })()
@@ -702,6 +720,10 @@ export class DeviceSession {
     const needsAuthorization = authorize ?? !(method === 'hello' || method === 'capabilities')
     const usesVm = vmRequest ?? (channel === 'repl.stdin' || channel === 'repl.signal'
       || (Boolean(method) && isVmRpc(method, requestPayload)))
+    if (this.state === 'resetting' && !(resetToken && resetToken === this.resetWriteToken)
+        && !(method === 'device.control' && requestPayload?.action === 'reset')) {
+      throw Object.assign(new Error('Device reset is in progress'), { code: 'DEVICE_RESETTING' })
+    }
     if (needsAuthorization && !this.sessionId) {
       throw new Error(`EV-MUX ${method || channel} requires an acquired v4 session`)
     }
@@ -771,6 +793,7 @@ export class DeviceSession {
       throw new Error('EV-MUX is not connected')
     }
     if (signal?.aborted) throw abortError(signal)
+    if (method === 'debug.capture_frame') requireObservedCameraCapture(this)
     if (payload instanceof Uint8Array && method !== 'file.write') throw new TypeError('Raw binary requests are only supported for file.write')
     if (method === 'script.write' || method === 'script.run') validateRpcPath(payload?.path)
     if (method === 'debug.info' && (payload?.scope === 'fs.list' || payload?.scope === 'fs.read')) {
@@ -856,7 +879,7 @@ export class DeviceSession {
       throw error
     }
     if (binaryResponse) {
-      if (!image) throw Object.assign(new Error('Capture returned no binary image'), { code: 'INVALID_RESPONSE' })
+      if (!image) throw Object.assign(new Error('Invalid JPEG image: capture response contains no binary JPEG'), { code: 'INVALID_IMAGE' })
       return image
     }
     return this._redactRpcPayload(method, responsePayload, { requestPayload: payload, redactSsid: false })
@@ -866,9 +889,126 @@ export class DeviceSession {
     return this.rpc(method, payload, { ...options, channel: 'debug.rpc', binaryResponse: true })
   }
 
+  async _setUartBaudRate(baudRate, signal) {
+    const controller = new AbortController()
+    const abort = () => controller.abort(abortError(signal))
+    signal?.addEventListener('abort', abort, { once: true })
+    if (signal?.aborted) abort()
+    try {
+      return await withTimeout(() => this.transport.setBaudRate(baudRate, { signal: controller.signal }), 2000, 'UART speed change timed out', controller.signal)
+    } catch (error) {
+      // Web Serial cannot cancel open(). Mark its in-flight attempt stale so
+      // a late open closes itself rather than changing a recovered link.
+      controller.abort(error)
+      throw error
+    } finally { signal?.removeEventListener('abort', abort) }
+  }
+
+  async _negotiateUartBaud({ hello, discovery, signal, expectedDevice }) {
+    const options = this.capabilities.uartBaud
+    if (options.baseline !== 115200 || !Array.isArray(options.candidates)
+        || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1000 || options.timeoutMs > 10000
+        || !Number.isSafeInteger(options.probeBytes) || options.probeBytes < 32 || options.probeBytes > 512) {
+      this._diagnostic('uart.baud.skipped', { reason: 'invalid_capabilities' })
+      return { hello, discovery }
+    }
+    const candidates = UART_BAUD_CANDIDATES.filter(baud => options.candidates.includes(baud))
+    if (!candidates.includes(115200)) return { hello, discovery }
+    let current = { hello, discovery }
+    for (const baudRate of candidates) {
+      if (signal?.aborted) throw abortError(signal)
+      clearTimeout(this.keepaliveTimer)
+      this.keepaliveGeneration += 1
+      this.state = 'negotiating'
+      const token = randomHex()
+      let commitSent = false
+      this._diagnostic('uart.baud.testing', { baudRate })
+      try {
+        const prepared = await this.rpc('transport.uart.prepare', { baudRate, token }, { timeout: 1500, signal })
+        if (prepared.baudRate !== baudRate || prepared.token !== token || prepared.timeoutMs !== options.timeoutMs) {
+          throw Object.assign(new Error('Invalid UART switch acknowledgement'), { code: 'UART_BAUD_INVALID_RESPONSE' })
+        }
+        const delay = prepared.switchDelayMs ?? options.switchDelayMs ?? 100
+        if (!Number.isSafeInteger(delay) || delay < 0 || delay > 1000) {
+          throw Object.assign(new Error('Invalid UART switch delay'), { code: 'UART_BAUD_INVALID_RESPONSE' })
+        }
+        await this._setUartBaudRate(baudRate, signal)
+        // Firmware drains the old-rate ACK before changing hardware. The host
+        // must not send a new-rate probe into that drain/guard interval.
+        await awaitWithSignal(this.sleep(delay + 20), signal)
+        this.parser.reset()
+        this.parser.active = true
+        for (const length of [...new Set([32, Math.min(128, options.probeBytes), options.probeBytes])]) {
+          for (let round = 0; round < 2; round += 1) {
+            // Framing validates CRC in both directions; exact echo also rejects
+            // stale responses and byte corruption at different packet lengths.
+            const data = randomHex(Math.ceil(length / 2)).slice(0, length)
+            const probe = await this.rpc('transport.uart.probe', { token, data }, { timeout: 800, signal })
+            if (probe.token !== token || probe.data !== data) {
+              throw Object.assign(new Error('UART bidirectional verification failed'), { code: 'UART_BAUD_BAD_ECHO' })
+            }
+          }
+        }
+        commitSent = true
+        let committed
+        try {
+          committed = await this.rpc('transport.uart.commit', { token }, { timeout: 800, signal })
+        } catch (error) {
+          if (signal?.aborted || error.code !== 'TIMEOUT') throw error
+          // Commit is token-idempotent; retry a lost ACK, never business data.
+          committed = await this.rpc('transport.uart.commit', { token }, { timeout: 800, signal })
+        }
+        if (committed.token !== token || committed.baudRate !== baudRate) {
+          throw Object.assign(new Error('Invalid UART commit acknowledgement'), { code: 'UART_BAUD_INVALID_RESPONSE' })
+        }
+        this.capabilities = { ...this.capabilities, uartBaud: { ...options, current: baudRate } }
+        this._diagnostic('uart.baud.selected', { baudRate })
+        this._startKeepalive()
+        return current
+      } catch (error) {
+        if (signal?.aborted) throw abortError(signal)
+        this._diagnostic('uart.baud.failed', { baudRate, code: error.code ?? 'SERIAL_ERROR' })
+        // A reopen can reset a board, or a damaged ACK can hide a successful
+        // device-side switch. Release if possible, then wait for the firmware's
+        // independent rollback before reacquiring at the baseline.
+        let released = false
+        try {
+          await this.rpc('session.release', {}, { timeout: 500, signal })
+          released = true
+        } catch { /* The firmware timeout is the independent recovery path. */ }
+        const rollbackMs = released ? 150 : commitSent ? this.leaseMs + 250 : options.timeoutMs + 250
+        // Each authenticated request may renew the lease, even if its ACK is
+        // lost. Count conservatively from the last release attempt, rather
+        // than from prepare submission or an earlier successful probe.
+        await awaitWithSignal(this.sleep(rollbackMs), signal)
+        await this._setUartBaudRate(115200, signal)
+        clearTimeout(this.keepaliveTimer)
+        this.keepaliveGeneration += 1
+        this.sessionGeneration += 1
+        this.sessionId = null
+        this.vmEpoch = null
+        this.vmReady = false
+        this.vmReadyKnown = false
+        this.clientNonce = randomHex()
+        this.parser.reset()
+        this.state = 'negotiating'
+        current = await this._negotiate({ role: this.role, drainMs: 0, probeRepl: false, autoBaud: false, signal, expectedDevice })
+        this.state = 'negotiating'
+        if (current.hello.session.owner !== 'uart') {
+          throw Object.assign(new Error('UART owner changed during speed recovery'), { code: 'UART_BAUD_RECOVERY_FAILED' })
+        }
+        if (baudRate === 115200) throw Object.assign(new Error('UART baseline verification failed'), { code: 'UART_BAUD_VERIFICATION_FAILED', cause: error })
+      }
+    }
+    return current
+  }
+
   negotiate(options = {}) {
     if (this.negotiatePromise) return this.negotiatePromise
     if (this.releasePromise) return Promise.reject(new Error('EV-MUX session is being released'))
+    if (this.resetPromise) {
+      return Promise.reject(Object.assign(new Error('Device reset is in progress'), { code: 'DEVICE_RESETTING' }))
+    }
 
     const controller = new AbortController()
     const callerSignal = options.signal || null
@@ -878,7 +1018,7 @@ export class DeviceSession {
     this.negotiateController = controller
     const deadlineError = new Error('EV-MUX negotiation deadline exceeded')
     deadlineError.code = 'TIMEOUT'
-    const deadlineTimer = setTimeout(() => controller.abort(deadlineError), 30000)
+    const deadlineTimer = setTimeout(() => controller.abort(deadlineError), 60000)
     const operation = this._negotiate({ ...options, signal: controller.signal })
     const tracked = operation.finally(() => {
       clearTimeout(deadlineTimer)
@@ -891,7 +1031,7 @@ export class DeviceSession {
     return tracked
   }
 
-  async _negotiate({ role = 'unknown', drainMs = 300, signal = null, acquire = true, probeRepl = true, expectedDevice = null } = {}) {
+  async _negotiate({ role = 'unknown', drainMs = 300, signal = null, acquire = true, probeRepl = true, expectedDevice = null, autoBaud = true } = {}) {
     this.role = role
     this.state = 'negotiating'
     this._diagnostic('negotiate.begin', { role })
@@ -986,7 +1126,6 @@ export class DeviceSession {
       this.keepaliveMs = hello.session.keepaliveMs || this.keepaliveMs
       this.leaseMs = hello.session.leaseMs || this.leaseMs
       this.parser.active = true
-      this.state = 'ready'
       this._startKeepalive()
     }
 
@@ -1032,6 +1171,13 @@ export class DeviceSession {
       // Start with the lease timing from the accepted hello immediately, then
       // refresh its cadence once the full capability response is available.
       this._startKeepalive()
+      if (autoBaud && typeof this.transport.setBaudRate === 'function'
+          && hello.session.owner === 'uart' && this.capabilities.uartBaud) {
+        const negotiated = await this._negotiateUartBaud({ hello, discovery, signal, expectedDevice })
+        hello = negotiated.hello
+        discovery = negotiated.discovery
+        capabilities = this.capabilities
+      }
     } else {
       this.parser.active = true
       this.state = 'discovered'
@@ -1199,7 +1345,13 @@ export class DeviceSession {
   release({ timeout = 1200 } = {}) {
     if (this.releasePromise) return this.releasePromise
     const negotiation = this.negotiatePromise
+    const resetting = this.resetPromise
     const operation = (async () => {
+      if (resetting) {
+        // The reset caller owns its result. After an ACK or uncertain reset
+        // there is no old lease to release; a rejected reset retains it.
+        try { await resetting } catch (_resetError) { /* Keep reset failure with its caller. */ }
+      }
       if (negotiation) {
         try {
           await negotiation
@@ -1288,7 +1440,7 @@ export class DeviceSession {
     if (operation === 'stop') return this.interrupt()
     if (signal?.aborted) throw abortError(signal)
     if (operation === 'hard-reset' && this.hasFeature('device.control')) {
-      return this.rpc('device.control', { action: 'reset' }, { timeout, signal })
+      return this._hardReset({ timeout, signal })
     }
     const command = {
       'soft-reset': 'import machine; machine.soft_reset()\r\n',
@@ -1297,10 +1449,111 @@ export class DeviceSession {
     }[operation]
     if (!command) throw new Error(`Unsupported device control operation: ${operation}`)
     if (operation === 'soft-reset') return this._softReset(command, { timeout, signal })
-    await this.writeFrame('repl.signal', 'signal', null, new Uint8Array([0x03]), { signal })
-    await this.writeFrame('repl.stdin', 'data', null, command, { signal })
-    await awaitWithSignal(this.sleep(100), signal)
-    return { ok: true, operation, acknowledged: false }
+    return this._resetViaRepl(operation, command, { timeout, signal })
+  }
+
+  _resetViaRepl(operation, command, { timeout, signal }) {
+    if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('Reset timeout must be positive')
+    if (this.releasePromise) {
+      throw Object.assign(new Error('Device session is being released'), { code: 'DEVICE_RELEASING' })
+    }
+    if (this.resetPromise || this.state !== 'ready') {
+      throw Object.assign(new Error('Device is not ready for reset'), { code: 'DEVICE_RESETTING' })
+    }
+    const deadline = createOperationDeadline(signal, timeout,
+      Object.assign(new Error('Device reset submission timed out'), { code: 'TIMEOUT' }))
+    const owner = this.sessionId
+    const generation = this.sessionGeneration
+    const resetToken = Symbol('REPL reset')
+    this.resetWriteToken = resetToken
+    this.state = 'resetting'
+    clearTimeout(this.keepaliveTimer)
+    this.keepaliveTimer = null
+    this.keepaliveGeneration += 1
+    let commandAttempted = false
+    const resetting = (async () => {
+      try {
+        const options = { signal: deadline.signal, resetToken }
+        await this.writeFrame('repl.signal', 'signal', null, new Uint8Array([0x03]), options)
+        if (deadline.signal.aborted) throw abortError(deadline.signal)
+        commandAttempted = true
+        await this.writeFrame('repl.stdin', 'data', null, command, options)
+        // The Node bridge's pipe write is not a serial write acknowledgement.
+        // Drain its output before cleanup can terminate that bridge process.
+        await awaitWithSignal(this.transport.drain
+          ? this.transport.drain({ signal: deadline.signal }) : this.sleep(100), deadline.signal)
+        // Framed REPL has no reset ACK. A completed write only confirms
+        // submission; ROM identification belongs to the next connection.
+        this.close(Object.assign(new Error('Device reset submitted'), { code: 'DEVICE_RESET' }))
+        return { ok: true, operation, acknowledged: false, outcome: 'unknown' }
+      } catch (error) {
+        // A failed write may have reached the VM. Do not replay it or send
+        // session.release to a possibly rebooted device using the old lease.
+        if (commandAttempted) {
+          error.reset = { acknowledged: false, outcome: 'unknown' }
+          this.close(error)
+        } else if (this.sessionId === owner && this.sessionGeneration === generation) {
+          // Only the interrupt was attempted; no reset command was submitted.
+          this.state = 'ready'
+          this._startKeepalive()
+        }
+        throw error
+      } finally {
+        deadline.dispose()
+        if (this.resetWriteToken === resetToken) this.resetWriteToken = null
+      }
+    })()
+    const tracked = resetting.finally(() => {
+      if (this.resetPromise === tracked) this.resetPromise = null
+    })
+    this.resetPromise = tracked
+    return tracked
+  }
+
+  _hardReset({ timeout, signal }) {
+    if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('Reset timeout must be positive')
+    if (this.releasePromise) {
+      throw Object.assign(new Error('Device session is being released'), { code: 'DEVICE_RELEASING' })
+    }
+    if (this.resetPromise || this.state !== 'ready') {
+      throw Object.assign(new Error('Device is not ready for reset'), { code: 'DEVICE_RESETTING' })
+    }
+    const owner = this.sessionId
+    const generation = this.sessionGeneration
+    this.state = 'resetting'
+    clearTimeout(this.keepaliveTimer)
+    this.keepaliveTimer = null
+    this.keepaliveGeneration += 1
+    const operation = (async () => {
+      try {
+        const response = await this.rpc('device.control', { action: 'reset' }, { timeout, signal })
+        // The ACK confirms acceptance, not a completed reboot. USB Serial/JTAG
+        // can stay open across restart; never send release using its old lease.
+        this.close(Object.assign(new Error('Device reset accepted'), { code: 'DEVICE_RESET' }))
+        return response
+      } catch (error) {
+        const rejected = error.response?.ok === false
+        const leaseLost = ['SESSION_REQUIRED', 'SESSION_EXPIRED', 'NOT_OWNER'].includes(error.code)
+        if (rejected && !leaseLost && this.sessionId === owner && this.sessionGeneration === generation) {
+          // An authenticated rejection proves no reset was accepted. Keep the
+          // live lease so normal cleanup still detects a genuine release error.
+          this.state = 'ready'
+          this._startKeepalive()
+        } else {
+          // Timeout, cancellation or link loss after submission is uncertain.
+          // An ownership rejection also requires dropping the obsolete lease.
+          // Preserve the original failure and never replay a destructive reset.
+          if (!rejected) error.reset = { acknowledged: false, outcome: 'unknown' }
+          this.close(error)
+        }
+        throw error
+      }
+    })()
+    const tracked = operation.finally(() => {
+      if (this.resetPromise === tracked) this.resetPromise = null
+    })
+    this.resetPromise = tracked
+    return tracked
   }
 
   async _softReset(command, { timeout, signal }) {

package/src/evmux.js

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { validateJpegImage } from './jpeg_validate.js'
+
 const SOF = 0x1e
 const EOF_GUARD = 0x1f
 const HEADER_RE = /^EVMUX\/1 h=(\d+) p=(\d+) c=([0-9A-Fa-f]{8})\r\n$/
@@ -98,6 +100,7 @@ export class EvMuxParser {
         this.rxChunks = 0
         this.frames = 0
         this.droppedFrames = 0
+        this.invalidImageFrames = 0
         this.lastChannel = null
         this.maxMetadataLength = 65535
         this.maxPayloadLength = MAX_BUFFER
@@ -175,6 +178,7 @@ export class EvMuxParser {
         this.rxChunks = 0
         this.frames = 0
         this.droppedFrames = 0
+        this.invalidImageFrames = 0
         this.lastChannel = null
     }
 
@@ -186,6 +190,7 @@ export class EvMuxParser {
             bufferedBytes: this.buffer.length,
             frames: this.frames,
             droppedFrames: this.droppedFrames,
+            invalidImageFrames: this.invalidImageFrames,
             lastChannel: this.lastChannel,
         }
     }
@@ -319,9 +324,29 @@ export class EvMuxParser {
                 this.handlers.frameRejected?.(metadata)
                 continue
             }
-            this.frames += 1
-            this.lastChannel = metadata.channel || 'unknown'
-            this.dispatch(metadata, payload)
+            if (this.dispatch(metadata, payload) !== false) {
+                this.frames += 1
+                this.lastChannel = metadata.channel || 'unknown'
+            }
+        }
+    }
+
+    _dropInvalidImage(metadata, error, payload) {
+        this.droppedFrames += 1
+        this.invalidImageFrames += 1
+        this.handlers.invalidImage?.(metadata, error, payload)
+        return false
+    }
+
+    _validateImage(metadata, payload) {
+        try {
+            if (metadata.encoding !== 'binary' || metadata.contentType !== 'image/jpeg') {
+                throw Object.assign(new Error('Invalid JPEG image: response must use binary image/jpeg'), { code: 'INVALID_IMAGE', reason: 'response must use binary image/jpeg' })
+            }
+            validateJpegImage(payload, metadata)
+            return true
+        } catch (error) {
+            return this._dropInvalidImage(metadata, error, payload)
         }
     }
 
@@ -338,9 +363,19 @@ export class EvMuxParser {
             return
         }
         if (channel === 'user.rpc' || channel === 'debug.rpc') {
+            const capture = channel === 'debug.rpc' && metadata.type === 'rsp'
+                && (metadata.method === 'debug.capture_frame' || metadata.method === 'debug.capture_screen')
+            if (capture && metadata.contentType !== 'image/jpeg') {
+                let response
+                try { response = metadata.encoding === 'json' ? JSON.parse(decodePayloadText(payload)) : null } catch { /* The correlated capture is rejected below. */ }
+                if (response?.ok !== false || typeof response.error?.code !== 'string' || !response.error.code) {
+                    return this._dropInvalidImage(metadata, Object.assign(new Error('Invalid JPEG image: capture response contains no binary JPEG'), { code: 'INVALID_IMAGE', reason: 'capture response contains no binary JPEG' }), payload)
+                }
+            }
             // EV-MUX v4: debug.capture_frame answers with the rsp frame itself
             // carrying the binary JPEG payload (no separate data channel).
             if (channel === 'debug.rpc' && metadata.type === 'rsp' && metadata.contentType === 'image/jpeg') {
+                if (!this._validateImage(metadata, payload)) return false
                 this.handlers.debugImage?.(bytesToBase64(payload), {
                     width: Number(metadata.width) || 0,
                     height: Number(metadata.height) || 0,
@@ -373,7 +408,11 @@ export class EvMuxParser {
             this.handlers.command?.(appendLine(`${channel} ${line}`))
             return
         }
-        if (channel === 'preview.frame' && metadata.contentType === 'image/jpeg') {
+        if (channel === 'preview.frame') {
+            if (metadata.type !== 'data') {
+                return this._dropInvalidImage(metadata, Object.assign(new Error('Invalid JPEG image: preview must be a data frame'), { code: 'INVALID_IMAGE', reason: 'preview must be a data frame' }), payload)
+            }
+            if (!this._validateImage(metadata, payload)) return false
             this.handlers.preview?.(bytesToBase64(payload), {
                 width: Number(metadata.width) || 0,
                 height: Number(metadata.height) || 0,

package/src/firmware_flash.js

@@ -85,7 +85,7 @@ export class FirmwareFlashSession {
       await validateFirmwareImage(this.image, bytes, { mode: this.mode })
       onPhase(this.mode === 'install' ? 'Installing complete firmware; existing data in the written range will be replaced' : 'Writing application; bootloader, partition table, NVS and user files are preserved')
       await this.stub.flashData(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
-        (written, total) => onProgress(total ? Math.min(80, Math.round(written / total * 80)) : 0), this.image.offset, false)
+        (written, total) => onProgress(total ? Math.min(80, Math.round(written / total * 80)) : 0), this.image.offset, true)
       onPhase(this.mode === 'install' ? 'Verifying the complete installation image' : 'Verifying the complete application image')
       // maxInFlight is a packet count: one 1 KiB packet bounds USB-JTAG backlog.
       const readback = new Uint8Array(bytes.byteLength)

package/src/jpeg_validate.js

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+
+const invalid = reason => Object.assign(new Error(`Invalid JPEG image: ${reason}`), { code: 'INVALID_IMAGE', reason })
+
+/** Bounded JPEG marker/table checks, not an entropy decoder (ITU-T T.81 B/C). */
+export function validateJpegImage(bytes, metadata = {}) {
+  if (!(bytes instanceof Uint8Array)) throw invalid('payload must be binary bytes')
+  if (!Number.isInteger(metadata.width) || !Number.isInteger(metadata.height)
+      || metadata.width <= 0 || metadata.height <= 0 || metadata.width > 65535 || metadata.height > 65535) throw invalid('invalid image dimensions')
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) throw invalid('missing SOI')
+  const quant = [-1, -1, -1, -1], huffman = new Uint8Array(8), components = []
+  let offset = 2, frame = null, scans = 0, covered = 0, restartInterval = 0
+  const word = index => (bytes[index] << 8) | bytes[index + 1]
+  while (offset < bytes.length) {
+    if (bytes[offset++] !== 0xff) throw invalid('expected a marker')
+    while (offset < bytes.length && bytes[offset] === 0xff) offset++
+    if (offset >= bytes.length) throw invalid('truncated marker')
+    const marker = bytes[offset++]
+    if (marker === 0xd9) {
+      if (!frame || !scans || covered !== (1 << components.length) - 1) throw invalid('incomplete frame or scans')
+      if (offset !== bytes.length) throw invalid('bytes follow EOI')
+      return { width: frame.width, height: frame.height }
+    }
+    if (marker === 0 || marker === 0xd8 || marker >= 0xd0 && marker <= 0xd7) throw invalid('unexpected standalone marker')
+    if (offset + 2 > bytes.length) throw invalid('truncated segment length')
+    const length = word(offset), begin = offset + 2, end = offset + length
+    if (length < 2 || end > bytes.length) throw invalid('segment exceeds image bounds')
+    offset = end
+
+    if (marker >= 0xe0 && marker <= 0xef || marker === 0xfe) continue
+    if (marker === 0xdb) {
+      if (begin === end) throw invalid('empty quantization segment')
+      let cursor = begin
+      while (cursor < end) {
+        const header = bytes[cursor++], precision = header >> 4, table = header & 15
+        if (precision > 1 || table > 3 || cursor + 64 * (precision + 1) > end) throw invalid('invalid quantization table')
+        for (let item = 0; item < 64; item++) {
+          const value = precision ? word(cursor) : bytes[cursor]
+          if (!value) throw invalid('zero quantization value')
+          cursor += precision + 1
+        }
+        quant[table] = precision
+      }
+      continue
+    }
+    if (marker === 0xc4) {
+      if (begin === end) throw invalid('empty Huffman segment')
+      let cursor = begin
+      while (cursor < end) {
+        if (cursor + 17 > end) throw invalid('truncated Huffman table')
+        const header = bytes[cursor++], kind = header >> 4, table = header & 15
+        if (kind > 1 || table > 3) throw invalid('invalid Huffman table selector')
+        let symbols = 0, slots = 1
+        for (let size = 0; size < 16; size++) {
+          const count = bytes[cursor++]
+          symbols += count
+          slots = slots * 2 - count
+          if (slots < 0) throw invalid('oversubscribed Huffman table')
+        }
+        if (!symbols || symbols > 256 || slots === 0 || cursor + symbols > end) throw invalid('invalid Huffman symbol bounds')
+        cursor += symbols
+        huffman[kind * 4 + table] = 1
+      }
+      continue
+    }
+    if (marker === 0xdd) {
+      if (length !== 4) throw invalid('invalid restart interval')
+      restartInterval = word(begin)
+      continue
+    }
+    if (marker >= 0xc0 && marker <= 0xc2) {
+      if (frame || scans || length < 11) throw invalid('invalid or repeated SOF')
+      const count = bytes[begin + 5], width = word(begin + 3), height = word(begin + 1)
+      if (bytes[begin] !== 8 || !count || count > 4 || length !== 8 + 3 * count) throw invalid('unsupported frame layout')
+      if (width !== metadata.width || height !== metadata.height) throw invalid('SOF dimensions do not match metadata')
+      frame = { marker, width, height }
+      for (let index = 0; index < count; index++) {
+        const cursor = begin + 6 + index * 3, id = bytes[cursor], sampling = bytes[cursor + 1], table = bytes[cursor + 2]
+        if (components.some(component => component.id === id) || !(sampling >> 4) || sampling >> 4 > 4
+            || !(sampling & 15) || (sampling & 15) > 4 || table > 3) throw invalid('invalid frame component')
+        components.push({ id, table })
+      }
+      continue
+    }
+    if (marker !== 0xda) throw invalid('unsupported coding marker')
+    if (!frame || length < 8) throw invalid('SOS precedes a complete frame')
+    const count = bytes[begin]
+    if (!count || count > components.length || length !== 6 + 2 * count) throw invalid('invalid scan component bounds')
+    const spectralStart = bytes[end - 3], spectralEnd = bytes[end - 2], high = bytes[end - 1] >> 4, low = bytes[end - 1] & 15
+    const progressive = frame.marker === 0xc2
+    if (!progressive && (spectralStart !== 0 || spectralEnd !== 63 || high || low)) throw invalid('invalid sequential scan parameters')
+    if (progressive && (spectralStart > spectralEnd || spectralEnd > 63 || (spectralStart === 0 ? spectralEnd !== 0 : count !== 1)
+        || high > 13 || low > 13 || high !== 0 && high !== low + 1)) throw invalid('invalid progressive scan parameters')
+    let selected = 0
+    for (let index = 0; index < count; index++) {
+      const cursor = begin + 1 + index * 2, component = components.findIndex(value => value.id === bytes[cursor])
+      const dc = bytes[cursor + 1] >> 4, ac = bytes[cursor + 1] & 15
+      if (component < 0 || selected & (1 << component) || dc > 3 || ac > 3) throw invalid('invalid scan component reference')
+      selected |= 1 << component
+      if (quant[components[component].table] !== 0) throw invalid('missing 8-bit quantization table')
+      if ((!progressive || spectralStart === 0 && high === 0) && !huffman[dc]) throw invalid('missing DC Huffman table')
+      if ((!progressive || spectralStart > 0) && !huffman[4 + ac]) throw invalid('missing AC Huffman table')
+    }
+    if (!progressive || spectralStart === 0 && high === 0) covered |= selected
+    scans++
+    let entropyBytes = 0, restart = 0
+    while (offset < bytes.length) {
+      if (bytes[offset] !== 0xff) { entropyBytes++; offset++; continue }
+      const markerStart = offset++
+      while (offset < bytes.length && bytes[offset] === 0xff) offset++
+      if (offset >= bytes.length) throw invalid('truncated entropy marker')
+      const code = bytes[offset++]
+      if (code === 0) {
+        if (offset !== markerStart + 2) throw invalid('fill bytes precede stuffed entropy')
+        entropyBytes++
+        continue
+      }
+      if (code >= 0xd0 && code <= 0xd7) {
+        if (!restartInterval || !entropyBytes || code !== 0xd0 + restart) throw invalid('invalid restart marker sequence')
+        restart = (restart + 1) & 7
+        entropyBytes = 0
+        continue
+      }
+      if (!entropyBytes) throw invalid('empty entropy scan')
+      offset = markerStart
+      break
+    }
+    if (!entropyBytes) throw invalid('empty entropy scan')
+  }
+  throw invalid('missing final EOI')
+}

package/src/node_inventory.js

@@ -87,7 +87,7 @@ export async function inventory(options = {}, dependencies = {}) {
     signal?.throwIfAborted()
     const device = (dependencies.createDevice ?? createDevice)({ transport: (dependencies.transportFor ?? transportFor)(row, options) })
     try {
-      const result = await device.connect({ role: row.interface === 'serial' ? 'unknown' : row.interface, timeout: options.probeTimeout ?? 5000, signal, probeRepl: false, ...(row.advertisement ? { expectedDevice: row.advertisement } : {}) })
+      const result = await device.connect({ role: row.interface === 'serial' ? 'unknown' : row.interface, timeout: options.probeTimeout ?? 5000, signal, probeRepl: false, autoBaud: false, ...(row.advertisement ? { expectedDevice: row.advertisement } : {}) })
       row.identity = result.identity; row.inspection = await device.inspect({ fields: options.fields, signal }); row.status = 'identified'
     } catch (error) {
       if (signal?.aborted) throw error