@esp-vision/device-core 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.7.0
+
+### Fixed
+
+- Allow a serial frame split across the initial 300 ms startup drain to finish within the parser's existing progress/total budgets while rejecting old frames and sending no hello. Freeze the total deadline across successive frames, fail when the parser discards an incomplete frame on timeout, and cancel boundary waits on abort or close; retain conservative failure for injected older parsers without receive-budget support. Add payload-free partial-frame timing/timeout diagnostics and regressions for split/coalesced startup data, bounded progress and cleanup.
+
+### Changed
+
+- Expose the browser ROM adapter's canonical factory `chipMac`, matching Node, and accept a strictly validated optional `expectedMac` before any port access. Bind initialization and baud recovery to that MAC as well as chip family/revision; mismatches preserve `ROM_IDENTITY_CHANGED` and close the adapter before another stub, erase or write. Keep initial manually selected ROM usage compatible when the option is omitted.
+
+- Clear and verify the S31 LP download latch at its own target address after programming, preserving unrelated bits before reset so software ROM entry can return to the application.
+
+- Explicit complete installation clears internal FAT filesystem files, including scripts and models, before writing firmware; application updates retain their existing data-preserving behavior. Hosts must explain this deletion before selecting install mode. Complete images may also replace NVS configuration; SD cards are not erased.
+- Require complete installations to derive the unencrypted writable `ffat` range from the hash-approved ESP partition table, verify layout/MD5, application bounds, chip/security and flash capacity, then erase and verify that exact range before any firmware write. Unsupported layouts/adapters, erase/read errors and cancellation before writing fail without reset or automatic retry.
+- Add `eraseRegion(address, size)` to the built-in browser/Node ROM stubs, using fixed official esptool primitives with sector-aligned bounds. Custom full-install adapters need the same capability; application-only adapters do not.
+- Bind installation qualification to private metadata/data snapshots. Cancellation is honored during erase and erased-range verification; once firmware writing starts, the existing complete-verification/reset policy remains in force.
+
 ## 0.6.1
 
 ### Fixed

package/README.md

@@ -19,11 +19,12 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-This source targets **0.6.0**, a minor release after 0.5.1. The **0.6.x** package line is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Declare a minor-locked dependency and use a lockfile to record the resolved patch and integrity; verify the chosen version exists in the public registry before installing. For unpublished source changes, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
+This source targets **0.7.0**, an unpublished minor release after 0.6.1. Device Core is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Declare a minor-locked dependency and use a lockfile to record the resolved patch and integrity; verify the chosen version exists in the public registry before installing. For unpublished source changes, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm view @esp-vision/device-core@0.6.0 version dist.integrity
-npm install '@esp-vision/device-core@~0.6.0' --registry=https://registry.npmjs.org/
+# Published example; the pending 0.7.0 APIs require a candidate tarball.
+npm view @esp-vision/device-core@0.6.1 version dist.integrity
+npm install '@esp-vision/device-core@~0.6.1' --registry=https://registry.npmjs.org/
 ```
 
 A source version, dry run or open merge request does not publish a package. CLI and Plugin bundles keep their own versions and embedded Core bytes; publishing Core alone does not update those installed tools.
@@ -141,7 +142,9 @@ To validate before npm publication, check out an exact reviewed commit, run `npm
 
 ### Browser ROM flashing
 
-`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal?, interface?, baudRate?, onStatus? })`. Construction is passive; `initialize()` lazily loads the official `esptool-js@0.7.1` backend and synchronizes at 115200. Use a browser bundler such as webpack, Vite or esbuild to include the chip stubs. The root and `/node` entry points do not load browser modules. No Python installation or consumer-side dependency patch is needed.
+`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal?, interface?, baudRate?, onStatus?, expectedMac? })`. Construction is passive; `initialize()` lazily loads the official `esptool-js@0.7.1` backend and synchronizes at 115200. Use a browser bundler such as webpack, Vite or esbuild to include the chip stubs. The root and `/node` entry points do not load browser modules. No Python installation or consumer-side dependency patch is needed.
+
+The candidate 0.7.0 browser adapter exposes `chipMac`, using the same 12 lowercase hexadecimal factory-MAC representation as the Node adapter. It is `null` before identity qualification. The browser reads it through the official chip's `readMac(loader)` primitive, without duplicating eFuse layouts. Pass the verified factory MAC of the selected runtime as `expectedMac` when handing that device to ROM, for example a validated `machine.unique_id()` known to match that board's factory MAC. The host must establish this source; an arbitrary legacy `deviceId` or USB VID/PID does not establish the association. If it cannot verify that value, use an explicitly user-selected manual ROM workflow rather than infer an automatic association. The option accepts exactly 12 hexadecimal characters, normalizes uppercase and rejects separators, whitespace, `null` and other types synchronously before opening a port. A mismatch returns `ROM_IDENTITY_CHANGED`, closes the adapter and cannot start a stub, erase or write. An unreadable/malformed MAC response returns `ROM_IDENTITY_INVALID`. Without the option, manually selecting an initial ROM remains supported; all later synchronization/recovery still binds the original family, revision and MAC, rejecting a different same-model device without rebinding.
 
 `interface` accepts `auto` (default), `uart`, `usb-otg` and `usb-jtag`. Auto detection distinguishes known USB-UART bridge descriptors from Espressif OTG and Serial/JTAG; ambiguous custom descriptors stay conservative and can be identified explicitly. A ready OTG ROM is synchronized without toggling DTR/RTS. A detached or re-enumerated device requires selecting its current download port again; the SDK never treats a stale port object as a recovered session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -78,5 +78,5 @@
   "devDependencies": {
     "esbuild": "0.25.12"
   },
-  "espVisionReleaseType": "patch"
+  "espVisionReleaseType": "minor"
 }

package/schemas/device-actions-v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ESP Vision Device Actions",
-  "deviceCoreVersion": "0.6.1",
+  "deviceCoreVersion": "0.7.0",
   "schemaVersion": 1,
   "actions": [
     {

package/src/browser.js

@@ -1,12 +1,14 @@
 // SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
 // SPDX-License-Identifier: Apache-2.0
+import { normalizeExpectedMac } from './rom_identity.js'
 
 export { serialTransport } from './browser_serial.js'
 
 /** Passive browser ROM adapter. Request the SerialPort in the UI's click handler. */
-export function openBrowserRom({ port, logger = {}, signal, interface: romInterface = 'auto', baudRate = 'auto', onStatus = () => {} } = {}) {
+export function openBrowserRom({ port, logger = {}, signal, interface: romInterface = 'auto', baudRate = 'auto', onStatus = () => {}, expectedMac } = {}) {
   if (!port || typeof port.open !== 'function' || typeof port.close !== 'function') throw new TypeError('A browser SerialPort is required')
   if (signal !== undefined && (!signal || typeof signal.addEventListener !== 'function' || typeof signal.aborted !== 'boolean')) throw new TypeError('signal must be an AbortSignal')
+  const expected = normalizeExpectedMac(expectedMac)
   let raw, initialized, closing = false, cleanup
   const closed = () => Object.assign(new Error('Browser ROM adapter is closed'), { code: 'ROM_CLOSED' })
   const cancelled = () => signal.reason instanceof Error ? signal.reason : Object.assign(new Error('Firmware operation cancelled'), { name: 'AbortError' })
@@ -25,6 +27,7 @@ export function openBrowserRom({ port, logger = {}, signal, interface: romInterf
     get chipName() { return raw?.chipName ?? null },
     get chipFamily() { return raw?.chipFamily ?? null },
     get chipRevision() { return raw?.chipRevision ?? null },
+    get chipMac() { return raw?.chipMac ?? null },
     get interface() { return raw?.interface ?? romInterface },
     get baudRate() { return raw?.baudRate ?? null },
     initialize() {
@@ -43,7 +46,7 @@ export function openBrowserRom({ port, logger = {}, signal, interface: romInterf
             log: (...args) => logger.log?.(...args),
             error: (...args) => logger.error?.(...args),
             debug: (...args) => logger.debug?.(...args),
-          }, { interface: romInterface, baudRate, onStatus })
+          }, { interface: romInterface, baudRate, onStatus, signal, expectedMac: expected })
           if (closing || signal?.aborted) { await disconnect(); check() }
           await raw.initialize()
           check()

package/src/browser_rom.js

@@ -3,6 +3,7 @@
 // Loaded only by openBrowserRom.initialize(), never by the root/Node entry point.
 import { ESPLoader, Transport } from 'esptool-js'
 import { browserRomCompatibility, browserTransportCompatibility, readBrowserFlash, romError, romWords } from './browser_rom_compat.js'
+import { normalizeExpectedMac } from './rom_identity.js'
 
 export const ROM_UART_BAUD_RATES = Object.freeze([2000000, 1500000, 921600, 460800, 115200])
 const families = { 'ESP32-S3': 0x3253, 'ESP32-P4': 0x3280, 'ESP32-S31': 0x3231 }
@@ -29,8 +30,9 @@ export function createBrowserLoader(port, logger = {}, options = {}) {
 // Dependency injection is internal to the package and permits lifecycle/error
 // testing against fake official-loader dependencies without browser globals.
 export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: SerialTransport }, port, logger = {}, {
-  interface: requestedInterface = 'auto', baudRate = 'auto', onStatus = () => {},
+  interface: requestedInterface = 'auto', baudRate = 'auto', onStatus = () => {}, signal, expectedMac,
 } = {}) {
+  const expected = normalizeExpectedMac(expectedMac)
   let kind = browserRomInterface(port, requestedInterface)
   if (baudRate !== 'auto' && !ROM_UART_BAUD_RATES.includes(baudRate)) throw new RangeError('Unsupported ROM UART baudRate')
   let loader, transport, identity, initialized = false, active = false, fault, writing = false, disconnected = false
@@ -61,8 +63,19 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
       await loader.detectChip(mode, 3)
       if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
       if (!loader.chip || !families[loader.chip.CHIP_NAME]) throw romError('ROM_CHIP_UNSUPPORTED', 'Browser flashing supports ESP32-S3, ESP32-P4 and ESP32-S31')
-      const current = { name: loader.chip.CHIP_NAME, family: families[loader.chip.CHIP_NAME], revision: await loader.chip.getChipRevision(loader) }
-      if (identity && (identity.family !== current.family || identity.revision !== current.revision)) throw romError('ROM_IDENTITY_CHANGED', 'Chip identity changed while recovering the download session')
+      const revision = await loader.chip.getChipRevision(loader)
+      if (typeof loader.chip.readMac !== 'function') throw romError('ROM_IDENTITY_INVALID', 'The ROM chip does not expose its factory MAC reader')
+      const rawMac = await loader.chip.readMac(loader)
+      // The pinned official chip API returns six colon-separated hex octets.
+      // Keep register layouts and byte ordering owned by that implementation.
+      if (typeof rawMac !== 'string' || rawMac.length !== 17 || !/^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/i.test(rawMac)) throw romError('ROM_IDENTITY_INVALID', 'The ROM did not return a complete factory MAC')
+      const mac = rawMac.replaceAll(':', '').toLowerCase()
+      const current = { name: loader.chip.CHIP_NAME, family: families[loader.chip.CHIP_NAME], revision, mac }
+      if ((expected !== undefined && current.mac !== expected)
+          || (identity && (identity.family !== current.family || identity.revision !== current.revision || identity.mac !== current.mac))) {
+        throw romError('ROM_IDENTITY_CHANGED', 'ROM identity differs from the selected device or the bound download session')
+      }
+      if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
       identity = current
       if (kind === 'unknown') {
         if (await loader.usesUsbOtg()) kind = 'usb-otg'
@@ -71,8 +84,13 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
       initialized = true
       status({ phase: 'rom-connected', interface: kind, baudRate: transport.baudrate })
     } catch (error) {
-      initialized = false
+      initialized = active = false
       await closeTransport().catch(() => {})
+      if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_IDENTITY_INVALID') {
+        fault = error
+        disconnected = true
+        throw error
+      }
       const lost = /device.*lost|disconnected|setSignals|networkerror/i.test(`${error.name} ${error.message}`)
       if (lost) throw romError('ROM_PORT_LOST', 'Download port detached or re-enumerated; select its current ROM port again', error)
       if (kind === 'usb-otg') throw romError('ROM_MANUAL_DOWNLOAD', 'USB-OTG ROM is not ready. Hold BOOT, press RESET, release BOOT, then select the ROM port again', error)
@@ -128,7 +146,7 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
         return
       } catch (error) {
         status({ phase: 'baud-failed', interface: kind, baudRate: candidate, code: error.code ?? 'ROM_BAUD_FAILED', message: error.message })
-        if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_SECURITY' || error.code === 'ROM_PORT_LOST') throw error
+        if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_IDENTITY_INVALID' || error.code === 'ROM_SECURITY' || error.code === 'ROM_PORT_LOST') throw error
         if (index === candidates.length - 1) throw romError('ROM_BAUD_FAILED', 'No requested UART download speed passed verification', error)
       }
     }
@@ -160,6 +178,37 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
     readRegister: address => operation(() => loader.readReg(address)),
     writeRegister: (address, value, mask = 0xffffffff) => operation(() => loader.writeReg(address, value, mask)),
     readFlash: (address, size, progress, options) => operation(() => readBrowserFlash(loader, address, size, progress, options)),
+    eraseRegion(address, size) {
+      return operation(async () => {
+        if (!Number.isSafeInteger(address) || address < 0 || address % 4096 !== 0
+            || !Number.isSafeInteger(size) || size <= 0 || size > 0xffffffff || size % 4096 !== 0
+            || address + size > 0x100000000) throw new RangeError('ROM erase requires a positive, sector-aligned 32-bit address range')
+        if (loader.ESP_ERASE_REGION !== 0xd1 || typeof loader.timeoutPerMb !== 'function'
+            || !Number.isFinite(loader.ERASE_REGION_TIMEOUT_PER_MB) || loader.ERASE_REGION_TIMEOUT_PER_MB <= 0) throw romError('ROM_ERASE_UNSUPPORTED', 'Use the qualified esptool-js region erase primitives')
+        const cancelled = () => signal.reason instanceof Error ? signal.reason : Object.assign(romError('CANCELLED', 'Flash region erase cancelled'), { name: 'AbortError' })
+        if (signal?.aborted) throw cancelled()
+        let abort
+        const aborted = new Promise((_, reject) => {
+          abort = () => { reject(cancelled()); void adapter.disconnect().catch(() => {}) }
+        })
+        signal?.addEventListener('abort', abort, { once: true })
+        try {
+          if (signal?.aborted) throw cancelled()
+          status({ phase: 'erasing-region', address, size })
+          // 0.7.1 exposes the region command and checked request primitives,
+          // but no eraseRegion convenience method. Retain its framing, status
+          // parser and size-scaled timeout rather than implementing transport.
+          const erasing = loader.checkCommand('erase region', loader.ESP_ERASE_REGION, romWords(address, size), 0, 0,
+            loader.timeoutPerMb(loader.ERASE_REGION_TIMEOUT_PER_MB, size))
+          const result = await (signal ? Promise.race([erasing, aborted]) : erasing)
+          assertReady()
+          if (signal?.aborted) throw cancelled()
+          if (!transport.device?.readable || !transport.device?.writable) throw romError('ROM_PORT_LOST', 'Serial device disconnected during Flash region erase')
+          if (!active || !loader.IS_STUB) throw romError('ROM_STUB_REQUIRED', 'Flash region erase lost its validated stub')
+          if (result !== 0) throw romError('ROM_ERASE_STATUS', `Flash region erase command failed: ${result}`)
+        } finally { signal?.removeEventListener('abort', abort) }
+      })
+    },
     flashData(data, progress, address, _compress) {
       return operation(async () => {
         if (writing) throw romError('ROM_WRITE_REUSE', 'Start a fresh download session before another firmware write')
@@ -175,6 +224,7 @@ export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: Seri
     get chipName() { return identity?.name ?? null },
     get chipFamily() { return identity?.family ?? null },
     get chipRevision() { return identity?.revision ?? null },
+    get chipMac() { return identity?.mac ?? null },
     get interface() { return kind },
     get baudRate() { return kind === 'uart' ? transport?.baudrate ?? 115200 : null },
     async initialize() { if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed'); await detect(kind === 'uart' || kind === 'usb-jtag' ? 'default_reset' : 'no_reset') },

package/src/device_session.js

@@ -343,6 +343,7 @@ export class DeviceSession {
     this.vmReadinessProbeActive = false
     this.pendingRpc = new Map()
     this.draining = false
+    this.startupDrainWait = null
     this.lastDebugImage = null
     this.runCapture = null
     this.runStarting = false
@@ -690,6 +691,7 @@ export class DeviceSession {
 
   feedBytes(bytes) {
     this.parser.feedBytes(bytes)
+    this.startupDrainWait?.check()
   }
 
   feedText(text) {
@@ -1031,6 +1033,62 @@ export class DeviceSession {
     return tracked
   }
 
+  _startupFrameError(reason) {
+    this._diagnostic('negotiate.startup_incomplete', { reason, parser: this.parser.getDiagnostics?.() })
+    return Object.assign(new Error('Incomplete EV-MUX frame at end of startup drain'), {
+      code: 'SERIAL_STARTUP_INCOMPLETE_FRAME',
+    })
+  }
+
+  _waitForStartupFrameBoundary(signal, timeoutCount, initial, totalDeadline) {
+    this._diagnostic('negotiate.startup_frame_wait', { parser: this.parser.getDiagnostics?.() })
+    return new Promise((resolve, reject) => {
+      let timer = null
+      let settled = false
+      let receiveDeadline = Math.min(totalDeadline, initial.progressDeadline)
+      const finish = (error) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', abort)
+        if (this.startupDrainWait === waiter) this.startupDrainWait = null
+        if (error) reject(error)
+        else resolve()
+      }
+      const abort = () => finish(abortError(signal))
+      const check = () => {
+        if (settled) return
+        clearTimeout(timer)
+        if (signal?.aborted) { abort(); return }
+        // A parser timeout may have emptied the buffer before this callback.
+        // Discarding an unfinished frame is never a completed startup boundary.
+        if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+          finish(this._startupFrameError('receive_timeout'))
+          return
+        }
+        if (Date.now() >= receiveDeadline) {
+          finish(this._startupFrameError('receive_timeout'))
+          return
+        }
+        if (!this.parser.hasPartialFrame?.()) { finish(); return }
+        const current = this.parser._partialFrameBudget?.()
+        if (!Number.isFinite(current?.totalDeadline) || !Number.isFinite(current?.progressDeadline)) {
+          finish(this._startupFrameError('receive_budget_unavailable'))
+          return
+        }
+        // New frames in a coalesced chunk must not extend the original bound.
+        receiveDeadline = Math.min(totalDeadline, current.totalDeadline, current.progressDeadline)
+        const remaining = receiveDeadline - Date.now()
+        if (remaining <= 0) { finish(this._startupFrameError('receive_timeout')); return }
+        timer = setTimeout(() => finish(this._startupFrameError('receive_timeout')), remaining)
+      }
+      const waiter = { check, fail: finish }
+      this.startupDrainWait = waiter
+      signal?.addEventListener('abort', abort, { once: true })
+      check()
+    })
+  }
+
   async _negotiate({ role = 'unknown', drainMs = 300, signal = null, acquire = true, probeRepl = true, expectedDevice = null, autoBaud = true } = {}) {
     this.role = role
     this.state = 'negotiating'
@@ -1039,23 +1097,40 @@ export class DeviceSession {
     // Unclaimed TCP sockets expire in three seconds: acquire immediately.
     if (role === 'tcp') drainMs = 0
     if (drainMs > 0) {
+      const timeoutCount = this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0
       this.draining = true
       try {
         await awaitWithSignal(this.sleep(drainMs), signal)
+        if (signal?.aborted) throw abortError(signal)
+        if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+          throw this._startupFrameError('receive_timeout')
+        }
+        let totalDeadline = null
+        while (this.parser.hasPartialFrame?.()) {
+          const initial = this.parser._partialFrameBudget?.()
+          if (!Number.isFinite(initial?.totalDeadline) || !Number.isFinite(initial?.progressDeadline)) {
+            throw this._startupFrameError('receive_budget_unavailable')
+          }
+          totalDeadline ??= initial.totalDeadline
+          await this._waitForStartupFrameBoundary(signal, timeoutCount, initial, totalDeadline)
+          // An adapter may synchronously deliver another chunk before the
+          // resolved boundary promise resumes this negotiation continuation.
+          if ((this.parser.getDiagnostics?.()?.incompleteFrameTimeouts ?? 0) !== timeoutCount) {
+            throw this._startupFrameError('receive_timeout')
+          }
+        }
+      } catch (error) {
+        if (error.code === 'SERIAL_STARTUP_INCOMPLETE_FRAME') {
+          this.close(error)
+          this.parser.reset()
+          await this.transport.disconnect?.()
+        }
+        throw error
       } finally {
         this.draining = false
       }
     }
     if (signal?.aborted) throw abortError(signal)
-    if (drainMs > 0 && this.parser.hasPartialFrame?.()) {
-      const error = Object.assign(new Error('Incomplete EV-MUX frame at end of startup drain'), {
-        code: 'SERIAL_STARTUP_INCOMPLETE_FRAME',
-      })
-      this.close(error)
-      this.parser.reset()
-      await this.transport.disconnect?.()
-      throw error
-    }
 
     let capabilities
     let discovery
@@ -1843,6 +1918,7 @@ export class DeviceSession {
 
   close(error = new Error('connection closed')) {
     this.negotiateController?.abort(error)
+    this.startupDrainWait?.fail(error)
     this.draining = false
     clearTimeout(this.keepaliveTimer)
     this.keepaliveTimer = null

package/src/evmux.js

@@ -108,6 +108,7 @@ export class EvMuxParser {
         this.frameTotalTimeoutMs = 12000
         this.partialFrame = null
         this.partialFrameTimer = null
+        this.incompleteFrameTimeouts = 0
     }
 
     setLimits({ metadataMax, payloadMax, frameProgressTimeoutMs, frameTotalTimeoutMs } = {}) {
@@ -152,6 +153,7 @@ export class EvMuxParser {
                 return
             }
             this._clearPartialFrame()
+            this.incompleteFrameTimeouts += 1
             this.buffer = new Uint8Array(0)
             this.rawTextDecoder = new TextDecoder('utf-8', { fatal: false })
             this.replTextDecoders = {
@@ -180,6 +182,17 @@ export class EvMuxParser {
         this.droppedFrames = 0
         this.invalidImageFrames = 0
         this.lastChannel = null
+        this.incompleteFrameTimeouts = 0
+    }
+
+    _partialFrameBudget() {
+        if (!this.partialFrame) return null
+        return {
+            startedAt: this.partialFrame.startedAt,
+            lastProgressAt: this.partialFrame.lastProgressAt,
+            progressDeadline: this.partialFrame.lastProgressAt + this.frameProgressTimeoutMs,
+            totalDeadline: this.partialFrame.startedAt + this.frameTotalTimeoutMs,
+        }
     }
 
     getDiagnostics() {
@@ -192,6 +205,8 @@ export class EvMuxParser {
             droppedFrames: this.droppedFrames,
             invalidImageFrames: this.invalidImageFrames,
             lastChannel: this.lastChannel,
+            partialFrame: this._partialFrameBudget(),
+            incompleteFrameTimeouts: this.incompleteFrameTimeouts,
         }
     }
 

package/src/firmware_flash.js

@@ -1,6 +1,11 @@
 // SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
 // SPDX-License-Identifier: Apache-2.0
 // ROM flashing is separate from DeviceSession and its EV-MUX v4 owner protocol.
+import { planInstallFilesystemErase } from './firmware_partitions.js'
+
+function checkAbort(signal) {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error('Firmware operation cancelled'), { name: 'AbortError' })
+}
 export async function firmwareSha256(bytes) {
   const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
   return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')
@@ -35,45 +40,68 @@ export async function validateFirmwareImage(image, bytes, { mode = 'update' } =
 
 /** Loader injected by the browser host; no Web Serial or ROM protocol duplicated. */
 export class FirmwareFlashSession {
-  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update' } = {}) {
+  #image
+  #mode
+  #filesystem
+  #signal
+
+  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update', signal } = {}) {
     this.mode = firmwareMode(mode)
     this.loader = loader
     this.reset = reset
     this.image = image
     this.state = 'idle'
     this.stub = null
+    this.#signal = signal
   }
 
   async connect(bytes) {
     if (this.state !== 'idle') throw new Error('Firmware loader is already in use')
     this.state = 'connecting'
     try {
-      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
+      checkAbort(this.#signal)
+      // Keep qualification independent of caller mutations during callbacks or
+      // asynchronous ROM operations. Public metadata is not an erase authority.
+      const image = this.#image = structuredClone(this.image)
+      const mode = this.#mode = firmwareMode(this.mode)
+      const payload = bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes
+      await validateFirmwareImage(image, payload, { mode })
+      this.#filesystem = mode === 'install' ? planInstallFilesystemErase(image, payload) : null
+      checkAbort(this.#signal)
       await this.loader.initialize()
-      const revisionMatches = this.image.chipRevision !== undefined ? this.loader.chipRevision === this.image.chipRevision
-        : Number.isInteger(this.image.chipRevisionMin) && Number.isInteger(this.image.chipRevisionMax) && this.loader.chipRevision >= this.image.chipRevisionMin && this.loader.chipRevision <= this.image.chipRevisionMax
-      if (this.loader.chipFamily !== this.image.chipFamily || !revisionMatches) {
+      checkAbort(this.#signal)
+      const revisionMatches = image.chipRevision !== undefined ? this.loader.chipRevision === image.chipRevision
+        : Number.isInteger(image.chipRevisionMin) && Number.isInteger(image.chipRevisionMax) && this.loader.chipRevision >= image.chipRevisionMin && this.loader.chipRevision <= image.chipRevisionMax
+      if (this.loader.chipFamily !== image.chipFamily || !Number.isInteger(this.loader.chipRevision) || !revisionMatches) {
         throw new Error('Chip or silicon revision does not match the approved board firmware')
       }
       const security = await this.loader.getSecurityInfo()
-      if (!Number.isSafeInteger(security.flags) || !Number.isSafeInteger(security.flashCryptCnt)) {
+      checkAbort(this.#signal)
+      if (!Number.isSafeInteger(security.flags) || security.flags < 0 || security.flags > 0xffffffff
+          || !Number.isSafeInteger(security.flashCryptCnt) || security.flashCryptCnt < 0 || security.flashCryptCnt > 0xffffffff) {
         throw new Error('Cannot qualify the device ROM security mode')
       }
       const encrypted = security.flashCryptCnt.toString(2).replace(/0/g, '').length % 2 === 1
-      if ((security.flags & 1) !== 0 || encrypted) throw new Error('Secure boot or encrypted devices require their signed flashing workflow')
+      if ((security.flags & 5) !== 0 || encrypted) throw new Error('Secure boot, secure download or encrypted devices require their signed flashing workflow')
       this.stub = await this.loader.runStub(true)
-      if (this.mode === 'install') {
+      checkAbort(this.#signal)
+      if (mode === 'install') {
         // JEDEC capacity byte encodes log2(bytes); shared with browser loaders.
         if (typeof this.stub.flashId !== 'function') throw new Error('Installation requires ROM flash capacity detection (flashId)')
         const id = await this.stub.flashId()
+        checkAbort(this.#signal)
         const capacity = (id >>> 16) & 0xff
         if (!Number.isSafeInteger(id) || id <= 0 || id > 0xffffff || capacity < 18 || capacity > 30
-            || 2 ** capacity < this.image.flashSize) throw new Error('Detected flash is unknown or smaller than the approved complete image layout')
+            || 2 ** capacity < image.flashSize) throw new Error('Detected flash is unknown or smaller than the approved complete image layout')
+        if (typeof this.stub.eraseRegion !== 'function' || typeof this.stub.readFlash !== 'function' || typeof this.stub.flashData !== 'function') {
+          throw Object.assign(new Error('Complete installation requires bounded filesystem erase and readback support'), { code: 'FIRMWARE_ERASE_UNSUPPORTED' })
+        }
       } else {
-        const table = this.image.partitionTable
+        const table = image.partitionTable
         const existing = await this.stub.readFlash(table.offset, table.bytes)
         if (await firmwareSha256(existing) !== table.sha256) throw new Error('Partition layout differs; select explicit install mode to replace the layout')
       }
+      checkAbort(this.#signal)
       this.state = 'connected'
     } catch (error) { await this.disconnect(); throw error }
   }
@@ -82,33 +110,63 @@ export class FirmwareFlashSession {
     if (this.state !== 'connected') throw new Error('Connect and validate the device before flashing')
     this.state = 'flashing'
     try {
-      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, true)
-      onPhase(this.mode === 'install' ? 'Verifying the complete installation image' : 'Verifying the complete application image')
+      checkAbort(this.#signal)
+      const image = this.#image, install = this.#mode === 'install'
+      const payload = bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes
+      await validateFirmwareImage(image, payload, { mode: this.#mode })
+      checkAbort(this.#signal)
+      if (install) {
+        const { offset, size } = this.#filesystem
+        onPhase('Erasing internal FAT filesystem; device files will be deleted')
+        checkAbort(this.#signal)
+        // Erase only the range parsed from the qualified image. No whole-chip
+        // erase, backups or automatic recovery/replay are part of installation.
+        await this.stub.eraseRegion(offset, size)
+        checkAbort(this.#signal)
+        onPhase('Verifying the erased internal FAT filesystem')
+        checkAbort(this.#signal)
+        for (let position = 0; position < size; position += 65536) {
+          const count = Math.min(65536, size - position)
+          const chunk = await this.stub.readFlash(offset + position, count, undefined,
+            { chunkSize: 65536, blockSize: 1024, maxInFlight: 1 })
+          checkAbort(this.#signal)
+          if (!(chunk instanceof Uint8Array) || chunk.byteLength !== count || chunk.some(value => value !== 0xff)) {
+            throw Object.assign(new Error('Internal FAT filesystem erase verification failed; keep the device in download mode'), { code: 'FIRMWARE_ERASE_VERIFY_FAILED' })
+          }
+          onProgress(Math.floor(20 * (position + count) / size))
+          checkAbort(this.#signal)
+        }
+      }
+      onPhase(install ? 'Installing complete firmware; internal FAT filesystem cleared' : 'Writing application; bootloader, partition table, NVS and user files are preserved')
+      checkAbort(this.#signal)
+      await this.stub.flashData(payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength),
+        (written, total) => onProgress((install ? 20 : 0) + (total ? Math.min(install ? 60 : 80, Math.round(written / total * (install ? 60 : 80))) : 0)), image.offset, true)
+      // Once firmware writing starts, preserve the existing completion policy:
+      // finish verification/reset rather than interrupting a partial image.
+      onPhase(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)
-      for (let offset = 0; offset < bytes.byteLength; offset += 65536) {
-        const count = Math.min(65536, bytes.byteLength - offset)
-        const chunk = await this.stub.readFlash(this.image.offset + offset, count, undefined,
+      const readback = new Uint8Array(payload.byteLength)
+      for (let offset = 0; offset < payload.byteLength; offset += 65536) {
+        const count = Math.min(65536, payload.byteLength - offset)
+        const chunk = await this.stub.readFlash(image.offset + offset, count, undefined,
           { chunkSize: 65536, blockSize: 1024, maxInFlight: 1 })
         if (chunk.byteLength !== count) throw new Error('Written firmware readback is incomplete')
         readback.set(chunk, offset)
-        onProgress(80 + Math.floor(20 * (offset + count) / bytes.byteLength))
+        onProgress(80 + Math.min(19, Math.floor(20 * (offset + count) / payload.byteLength)))
       }
-      if (readback.byteLength !== bytes.byteLength || await firmwareSha256(readback) !== this.image.sha256) throw new Error('Written firmware verification failed; keep the device in download mode for recovery')
+      if (await firmwareSha256(readback) !== image.sha256) throw new Error('Written firmware verification failed; keep the device in download mode for recovery')
+      onProgress(100)
       this.state = 'verified'
       try {
-        // P4 software download requests survive a CPU reset. Clear only that
+        // P4/S31 software download requests survive a CPU reset. Clear only that
         // latch, verify all other live fields, then apply the host reset policy.
-        if (this.loader.chipFamily === 0x3280) {
-          const address = 0x50110008, mask = 4
+        if (image.chipFamily === 0x3280 || image.chipFamily === 0x3231) {
+          const address = image.chipFamily === 0x3280 ? 0x50110008 : 0x20700008, mask = 4
           const before = await this.stub.readRegister(address)
-          if (!Number.isInteger(before) || before < 0 || before > 0xffffffff) throw new Error('Invalid P4 system control register')
+          if (!Number.isInteger(before) || before < 0 || before > 0xffffffff) throw new Error('Invalid download system control register')
           if (before & mask) await this.stub.writeRegister(address, 0, mask)
           const after = await this.stub.readRegister(address)
-          if (after !== ((before & ~mask) >>> 0)) throw new Error('P4 normal boot latch verification failed')
+          if (after !== ((before & ~mask) >>> 0)) throw new Error('Normal boot latch verification failed')
         }
         await this.reset()
       }

package/src/firmware_partitions.js

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { romMd5 } from './rom_md5.js'
+
+const SECTOR_BYTES = 4096
+const invalid = message => Object.assign(new Error(`Invalid installation partition table: ${message}`), { code: 'FIRMWARE_PARTITION_INVALID' })
+const allFF = bytes => bytes.every(value => value === 0xff)
+
+// Call only after validateFirmwareImage has authenticated the complete image
+// and every declared segment. Never infer an erase range from a host/UI field.
+export function planInstallFilesystemErase(image, bytes) {
+  const table = image.partitionTable
+  if (table.offset % SECTOR_BYTES || table.bytes % 32 || table.bytes > 0xc00) throw invalid('unsupported table bounds')
+  const raw = bytes.subarray(table.offset, table.offset + table.bytes)
+  const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength)
+  const entries = [], labels = new Set()
+  let digestSeen = false, terminated = false
+  for (let cursor = 0; cursor < raw.length; cursor += 32) {
+    const entry = raw.subarray(cursor, cursor + 32)
+    if (allFF(entry)) {
+      if (!allFF(raw.subarray(cursor))) throw invalid('data after the end marker')
+      terminated = true
+      break
+    }
+    const magic = view.getUint16(cursor, true)
+    if (magic === 0xebeb && !digestSeen) {
+      if (!allFF(entry.subarray(2, 16))) throw invalid('malformed MD5 record')
+      const digest = romMd5(raw.subarray(0, cursor))
+      if (!digest.every((value, index) => value === entry[16 + index])) throw invalid('MD5 mismatch')
+      digestSeen = true
+      continue
+    }
+    if (magic !== 0x50aa || digestSeen) throw invalid('unexpected entry or data after MD5')
+    const offset = view.getUint32(cursor + 4, true), size = view.getUint32(cursor + 8, true)
+    const type = entry[2], subtype = entry[3], flags = view.getUint32(cursor + 28, true)
+    const labelBytes = entry.subarray(12, 28), end = labelBytes.indexOf(0)
+    const label = String.fromCharCode(...labelBytes.subarray(0, end < 0 ? 16 : end))
+    if (!label || labels.has(label) || (end >= 0 && labelBytes.subarray(end).some(value => value !== 0))) throw invalid('empty, duplicate or malformed label')
+    if (offset < table.offset + SECTOR_BYTES || offset % SECTOR_BYTES || !size
+        || offset + size > image.flashSize || (type === 0 && offset % 65536)) throw invalid('unsupported partition bounds')
+    labels.add(label)
+    entries.push({ label, type, subtype, offset, size, flags })
+  }
+  if (!terminated || !entries.length) throw invalid('missing entries or end marker')
+  entries.sort((a, b) => a.offset - b.offset)
+  for (let index = 1; index < entries.length; index++) {
+    if (entries[index].offset < entries[index - 1].offset + entries[index - 1].size) throw invalid('overlapping partitions')
+  }
+  const app = image.application
+  if (!entries.some(entry => entry.type === 0 && entry.offset === app.offset
+      && entry.size === app.partitionSize && app.bytes <= entry.size)) throw invalid('application does not match the approved layout')
+  const fat = entries.find(entry => entry.label === 'ffat')
+  if (!fat) throw Object.assign(new Error('Complete installation requires a declared internal ffat partition'), { code: 'FIRMWARE_FATFS_UNAVAILABLE' })
+  if (fat.type !== 1 || fat.subtype !== 0x81 || fat.flags !== 0 || fat.size % SECTOR_BYTES
+      || fat.offset < Math.ceil(bytes.byteLength / SECTOR_BYTES) * SECTOR_BYTES) throw invalid('ffat is not an unencrypted, writable FAT partition outside the firmware write range')
+  return Object.freeze({ label: fat.label, offset: fat.offset, size: fat.size })
+}