@esp-vision/device-core 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.3.0
+
+### Added
+
+- Export the passive built-in `openNodeRom({ port, python?, signal? })` adapter from `/node` so Node SDK hosts and the CLI share the same ROM implementation.
+
+- Explicit `mode: 'install'` on firmware check/update and CLI `--mode install` for blank-device ROM installation over USJ/UART, using qualified complete images with bootloader/partition/application hashes and flash-capacity checks. Default application-only updates retain their existing data-preservation contract; no automatic fallback or TCP OTA is introduced.
+
+### Fixed
+
+- Allow up to 151 seconds of bounded metadata propagation backoff after npm accepts publication, with ten uncached verification reads and no repeated publish.
+
+## 0.2.0
+
+### Changed
+
+- File and large-script uploads use one reliable binary `file.write` engine with 16 KiB blocks, integrity validation and cancellation cleanup; no Base64/JSON or REPL upload fallback. Public `files.write` and Python API signatures stay unchanged. Uploads require matching firmware capability `file.write.binary`; older v4 devices can still be inspected but must update firmware before upload.
+
+### Fixed
+
+- Verify newly published tarballs using bounded uncached registry reads instead of a single immediate npm view; retry transient metadata propagation/network failures without repeating publication, while failing immediately on access denial or integrity mismatch.
+
 ## 0.1.1
 
 ### Fixed

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The `/node` export and bundled checks below require 0.1.1, the next patch release prepared by this source tree; 0.1.0 remains the published baseline until the release pipeline succeeds. 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.
+The `/node` byte transports and bundled checks require 0.1.1; complete installation and `/node` `openNodeRom` are introduced in 0.3.0. Check the registry for the published version. 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 install --save-exact @esp-vision/device-core@0.1.1 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.3.0 --registry=https://registry.npmjs.org/
 ```
 
 EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`; applications should ask the user to update firmware. Core has no runtime dependency on the IDE, Agent, DOM or Node serial libraries. The host supplies the physical byte transport and discovery adapter; Core owns protocol parsing, session negotiation, REPL coordination and device operations.
@@ -31,7 +31,7 @@ EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`;
 
 Read the Device Core guide in the **ESP-VISION Documentation Center**: [English](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/index.html) | [简体中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/index.html).
 
-- [All application APIs](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/api.html), including firmware version checks and updates.
+- [All application APIs](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/api.html), including firmware version checks, application updates and blank-device installation.
 - [Advanced exports](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/advanced.html) and [TCP/Web Serial integration](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/integration.html).
 
 Documentation source lives in this repository under `docs/en/device-core/` and `docs/zh_CN/device-core/` and changes alongside SDK APIs in the same MR. The documentation site renders the RST as HTML; it does not redirect readers to npm or require downloading documentation. The npm package contains the runtime library and this README, not a second RST documentation distribution. Use the documentation center's version selector when reading a published firmware/documentation version; `latest` follows the current development documentation. These new chapter links become available after the corresponding documentation is deployed.
@@ -41,7 +41,7 @@ Documentation source lives in this repository under `docs/en/device-core/` and `
 The npm package installs `esp-vision-device`. `inspect` combines passive wired/LAN enumeration and targeted queries. By default it lists USB serial candidates; `--all-ports` also includes native UART/Bluetooth ports. Explicit `--port` bypasses discovery filtering; `configure`, `control`, and `firmware check/update` cover management. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
 
 ```sh
-npm install -g @esp-vision/device-core@0.1.1
+npm install -g @esp-vision/device-core@0.3.0
 esp-vision-device inspect
 esp-vision-device inspect --all-ports
 esp-vision-device inspect --interface usj,usb --probe --json
@@ -49,7 +49,7 @@ esp-vision-device inspect --port COM3 --fields identity,capabilities
 esp-vision-device inspect --tcp 192.168.1.100:3232 --fields network,storage --json
 ```
 
-Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
+Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Use `firmware update --mode install --board BOARD --port PORT --version VERSION` for blank-device installation over a ROM-capable USJ/UART port. Install replaces data within the complete image range; default updates preserve the existing layout. Historical releases without qualified metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
 
 ## Public device API
 
@@ -65,7 +65,7 @@ Import `createDevice` from the package root. Application code uses one device in
 | Interactive Python | `python.input(data)` | Send terminal input without uploading a file |
 | Python execution | `python.execute({ source, path, completion })` | Execute source or a device-side script |
 | Files | `files.list/read/write/remove/mkdir(request)` | File and directory operations, with one object argument |
-| Firmware | `firmware.check(request)`, `firmware.update(request)` | List board firmware versions, select an exact version and perform verified ROM application updates |
+| Firmware | `firmware.check(request)`, `firmware.update(request)` | List board firmware versions, select an exact version and perform verified ROM application updates or explicit complete installation on blank devices |
 | Capture | `capture({ source, format, quality })` | Capture an image from a supported source |
 | Events | `on(event, handler)` | Subscribe; returns an unsubscribe function |
 
@@ -220,7 +220,7 @@ const image = await device.capture({ source: 'camera', format: 'jpeg', timeout:
 
 Paths are absolute device paths. `files.list({ path: '/', recursive: false })` returns entries `{ name, path, type, size }`. `files.read({ path })` returns a `Uint8Array`; use `encoding: 'utf-8'` to return text, and `maxBytes` to bound a read. Writes default to `overwrite: true`; set it to `false` to require a new destination. Uploading and executing are separate operations; create an empty file with `files.write({ path, data: new Uint8Array() })` rather than a second touch API. Remove an empty directory with `files.remove({ path: '/models', type: 'directory' })`; there is no implicit recursive deletion. `files.mkdir({ path, recursive: true })` creates missing parents.
 
-**Current firmware limits:** file upload still uses the existing `script.write` chunked RPC, including Base64/JSON overhead. This API cleanup does not implement the proposed high-throughput raw binary protocol or promise improved model-upload throughput. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
+**Binary uploads (SDK 0.3.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
 
 `capture({ source: 'screen', format: 'jpeg' })` uses the dedicated `debug.capture_screen` RPC to encode the LCD's last submitted RGB565 framebuffer, including the display's scaling and letterboxing. It does not read the panel electronics or capture the camera. Camera capture uses `debug.capture_frame`. Both return binary JPEG responses correlated to the request; optional `quality` is an integer from 1 to 100. Missing firmware capabilities reject with `UNSUPPORTED_OPERATION`; an uninitialized display returns `DISPLAY_NOT_READY`, and a board without an LCD returns `NOT_SUPPORTED`. Preview is a separate real-time stream and may drop frames under congestion.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -13,7 +13,7 @@
     "./firmware": "./src/firmware_flash.js",
     "./discovery": "./src/network_discovery.js",
     "./discovery/node": "./src/network_discovery_node.js",
-    "./node": "./src/node_transport.js"
+    "./node": "./src/node.js"
   },
   "files": [
     "src/*.js",

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.1.1",
+  "deviceCoreVersion": "0.3.0",
   "schemaVersion": 1,
   "actions": [
     {
@@ -169,7 +169,7 @@
     },
     {
       "name": "python.execute",
-      "description": "Execute MicroPython through the shared interpreter using bounded REPL or chunked script transport.",
+      "description": "Execute MicroPython through the shared interpreter using bounded REPL or binary file staging.",
       "inputSchema": {
         "type": "object",
         "properties": {

package/scripts/release-npm.mjs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
 // SPDX-License-Identifier: Apache-2.0
 import assert from 'node:assert/strict'
+import { verifyPublishedIntegrity } from './verify-registry.mjs'
 import { spawnSync } from 'node:child_process'
 import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
@@ -48,7 +49,7 @@ try {
     console.log(`Npm publisher: ${publisher}`)
     const url = new URL(encodeURIComponent(manifest.name), registry)
     url.pathname += '/' + encodeURIComponent(manifest.version)
-    const response = await fetch(url, { signal: AbortSignal.timeout(15000) })
+    const response = await fetch(url, { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
     if (response.ok) {
       const existing = await response.json()
       assert.equal(existing.dist?.integrity, packed.integrity,
@@ -57,8 +58,8 @@ try {
     } else {
       assert.equal(response.status, 404, 'Registry lookup failed; do not attempt publication')
       npm(['publish', join(temporary, packed.filename), '--ignore-scripts', '--access', 'public', '--registry', registry])
-      const verified = JSON.parse(npm(['view', `${manifest.name}@${manifest.version}`, 'dist.integrity', '--json', '--registry', registry]))
-      assert.equal(verified, packed.integrity, 'Published tarball integrity mismatch')
+      console.log('npm publish accepted; verifying registry metadata')
+      await verifyPublishedIntegrity(url, packed.integrity)
       console.log(`Published and verified ${packed.name}@${packed.version}`)
     }
   }

package/scripts/verify-registry.mjs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+
+// Publication is one write. Only reads are retried while registry metadata propagates.
+export async function verifyPublishedIntegrity(url, integrity, {
+  fetcher = globalThis.fetch,
+  wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+  report = message => console.log(message),
+} = {}) {
+  const attempts = 10
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let response, transient
+    try {
+      response = await fetcher(url, { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
+    } catch (error) {
+      if (!(error instanceof TypeError) && !['TimeoutError', 'AbortError'].includes(error.name)) throw error
+      transient = 'network timeout or unavailable'
+    }
+    if (response?.ok) {
+      const metadata = await response.json()
+      assert.equal(metadata.dist?.integrity, integrity, 'Published tarball integrity mismatch')
+      return
+    }
+    if (response) {
+      const retryable = response.status === 404 || response.status === 429 || response.status >= 500 && response.status <= 599
+      await response.body?.cancel()
+      assert.ok(retryable, `Registry verification failed: HTTP ${response.status}`)
+      transient = `HTTP ${response.status}`
+    }
+    assert.ok(attempt + 1 < attempts, `Published metadata verification unavailable after ${attempts} reads (${transient}); retry the CI job, not publication manually`)
+    const delay = Math.min(30000, 1000 * 2 ** attempt)
+    report(`Registry verification ${transient}; retrying read ${attempt + 2}/${attempts} in ${delay}ms`)
+    await wait(delay)
+  }
+}

package/src/cli.js

@@ -21,9 +21,9 @@ esp-vision-device configure (--port PATH | --tcp HOST[:PORT])
 esp-vision-device control (--port PATH | --tcp HOST[:PORT])
   --action stop|reset|bootloader [--mode soft|hard]
 esp-vision-device firmware check [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] [--board BOARD --current-version VERSION] [--version VERSION]
+  [--catalog FILE|HTTPS_URL] [--board BOARD --current-version VERSION] [--version VERSION] [--mode update|install]
 esp-vision-device firmware update [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] --version VERSION [--image APPLICATION.bin]
+  [--catalog FILE|HTTPS_URL] --version VERSION [--image FIRMWARE.bin] [--mode update|install]
   [--board BOARD --current-version VERSION]
 Common: --timeout MS (default 3000 enumeration, 30000 command),
   --probe-timeout MS (default 5000 per device), --role usb|usj|uart|unknown,
@@ -33,7 +33,10 @@ also includes native UART/Bluetooth ports. No serial
 port is opened. --probe and targeted commands acquire a session and can interrupt
 Python. Rows with unknown firmware remain visible; numbering is per invocation.
 Firmware versions come from dl.espressif.com by default; local catalogs are advanced overrides.
-Firmware update uses the built-in serial flasher (Python esptool>=5.3,<6). TCP is not OTA.`
+Firmware update uses the built-in serial flasher (Python esptool>=5.3,<6). TCP is not OTA.
+Default mode update preserves the existing layout/data; explicit mode install writes
+a complete image, replacing data in its written range. Blank boards require --board
+and a ROM-capable USJ/UART port, not an application USB-OTG interface.`
 const error = (code, message) => Object.assign(new Error(message), { code })
 const fields = ['identity', 'capabilities', 'runtime', 'network', 'storage']
 export function parseCli(args) {
@@ -43,7 +46,7 @@ export function parseCli(args) {
   if (v.help) return { help: true }
   const command = p[0] ?? 'inspect', action = command === 'firmware' ? p[1] : null
   if (!['inspect', 'configure', 'control', 'firmware'].includes(command) || p.length > (command === 'firmware' ? 2 : 1) || (command === 'firmware' && !['check', 'update'].includes(action))) throw error('ARGUMENT', 'Unknown command; use --help')
-  const allowed = { inspect: ['all-ports', 'select', 'fields', 'interface', 'probe', 'probe-timeout'], configure: ['ssid', 'forget-wifi', 'password-stdin', 'network-enabled'], control: ['action', 'mode'], firmware: ['catalog', 'board', 'current-version', 'version', 'image'] }[command]
+  const allowed = { inspect: ['all-ports', 'select', 'fields', 'interface', 'probe', 'probe-timeout'], configure: ['ssid', 'forget-wifi', 'password-stdin', 'network-enabled'], control: ['action', 'mode'], firmware: ['mode', 'catalog', 'board', 'current-version', 'version', 'image'] }[command]
   for (const key of Object.keys(v)) if (!['json', 'port', 'tcp', 'python', 'timeout', 'role', ...allowed].includes(key)) throw error('ARGUMENT', `Option --${key} is not valid for ${command}`)
   if ([v.port, v.tcp, v.select].filter(value => value !== undefined).length > 1) throw error('ARGUMENT', 'Select exactly one device address or number')
   if (v.role && !['usb', 'usj', 'uart', 'unknown'].includes(v.role)) throw error('ARGUMENT', 'Invalid serial role')
@@ -74,6 +77,8 @@ export function parseCli(args) {
   }
   if (command === 'control' && (!['stop', 'reset', 'bootloader'].includes(v.action) || (v.action === 'reset' ? !['soft', 'hard'].includes(v.mode) : v.mode !== undefined))) throw error('ARGUMENT', 'Control requires action; reset requires mode soft or hard')
   if (command === 'firmware') {
+    if (v.mode !== undefined && !['update', 'install'].includes(v.mode)) throw error('ARGUMENT', 'Firmware mode must be update or install')
+    if (v.mode === 'install' && !v.board) throw error('ARGUMENT', 'Firmware installation requires explicit --board')
     if (!endpoint && !v.board) throw error('ARGUMENT', 'Firmware requires a connected device or --board')
     if (action === 'update' && (!v.port || !v.version)) throw error('ARGUMENT', 'Firmware update requires local --port and explicit --version')
     if (action === 'check' && v.image) throw error('ARGUMENT', 'Image applies only to firmware update')
@@ -108,9 +113,9 @@ export async function runCli(options, dependencies = {}) {
     endpoint = listing.devices.find(row => row.number === options.select)
     if (!endpoint) throw error('DEVICE_NOT_FOUND', 'Selected result number is unavailable in this enumeration')
   }
-  const device = makeDevice(endpoint ? { transport: (dependencies.transportFor ?? transportFor)(endpoint, options) } : {})
+  const offline = options.command === 'firmware' && options.board
+  const device = makeDevice(endpoint && !offline ? { transport: (dependencies.transportFor ?? transportFor)(endpoint, options) } : {})
   try {
-    const offline = options.command === 'firmware' && options.board
     if (endpoint && !offline) await device.connect({ role: endpoint.interface === 'serial' ? 'unknown' : endpoint.interface, timeout: options.timeout, signal, ...(endpoint.advertisement ? { expectedDevice: endpoint.advertisement } : {}) })
     if (options.command === 'inspect') return await device.inspect({ fields: options.fields, timeout: options.timeout, signal })
     if (options.command === 'configure') {
@@ -123,10 +128,11 @@ export async function runCli(options, dependencies = {}) {
     }
     if (options.command === 'control') return await device.control({ action: options.action, ...(options.mode ? { mode: options.mode } : {}), timeout: options.timeout, signal })
     let catalog = options.catalog
+    const mode = options.mode ?? 'update'
     if (catalog !== undefined && !/^https:\/\//.test(catalog)) catalog = JSON.parse(await (dependencies.readFile ?? readFile)(catalog, 'utf8'))
-    const checked = await device.firmware.check({ catalog, ...(endpoint && !offline ? {} : { identity: { board: options.board, firmwareVersion: options['current-version'] ?? 'unknown' } }), ...(options.version ? { version: options.version } : {}), signal })
+    const checked = await device.firmware.check({ catalog, mode, ...(endpoint && !offline ? {} : { identity: { board: options.board, firmwareVersion: options['current-version'] ?? 'unknown' } }), ...(options.version ? { version: options.version } : {}), signal })
     if (options.action === 'check') return checked
-    return await device.firmware.update({ release: checked.release, board: options.board, ...(options.image ? { data: new Uint8Array(await (dependencies.readFile ?? readFile)(options.image)) } : {}), openLoader: ({ signal }) => (dependencies.openLoader ?? openNodeRom)({ port: options.port, python: options.python, signal }), onPhase: dependencies.onPhase ?? (() => {}), signal })
+    return await device.firmware.update({ mode, release: checked.release, board: options.board, ...(options.image ? { data: new Uint8Array(await (dependencies.readFile ?? readFile)(options.image)) } : {}), openLoader: ({ signal }) => (dependencies.openLoader ?? openNodeRom)({ port: options.port, python: options.python, signal }), onPhase: dependencies.onPhase ?? (() => {}), signal })
   } finally { await device.disconnect() }
 }
 const safe = value => String(value ?? '—').replace(/[\x00-\x1f\x7f-\x9f]/g, '?')

package/src/device_actions.js

@@ -74,7 +74,7 @@ export const DEVICE_ACTION_DESCRIPTORS = Object.freeze([
     includeFiles: { type: 'boolean', default: true },
     logLimit: { type: 'integer', minimum: 0, maximum: 500, default: 100 },
   }), { readOnly: true, concurrency: 'shared-read' }),
-  action('python.execute', 'Execute MicroPython through the shared interpreter using bounded REPL or chunked script transport.', objectSchema({
+  action('python.execute', 'Execute MicroPython through the shared interpreter using bounded REPL or binary file staging.', objectSchema({
     code: { type: 'string' },
     timeoutMs: { type: 'integer', minimum: 100, maximum: 120000, default: 8000 },
   }, ['code']), { destructive: true, openWorld: true }),

package/src/device_bindings.js

@@ -3,7 +3,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { EV_REPL_FILE_CHUNK_BYTES } from './evrepl.js'
 
 export const EPHEMERAL_PYTHON_PATH = '/.espvision_agent_run.py'
 
@@ -306,17 +305,9 @@ export function bindSessionDeviceActions(registry, {
   registry.bind('deviceFile.write', async (input, { session, signal }) => {
     const path = validateDevicePath(input.path)
     const bytes = input.encoding === 'base64' ? base64ToBytes(input.content) : null
-    if (bytes) {
-      if (session.hasFeature('script.write')) {
-        await session.writeFile(path, bytes, { encoding: 'binary', signal })
-      } else {
-        await session.repl.writeFile(path, bytes, EV_REPL_FILE_CHUNK_BYTES, false, { signal })
-      }
-    } else if (session.hasFeature('script.write')) {
-      await session.writeScript(path, input.content, { runAfterWrite: input.runAfterWrite, signal })
-    } else {
-      await session.repl.writeFile(path, input.content, EV_REPL_FILE_CHUNK_BYTES, false, { signal })
-    }
+    await session.writeFile(path, bytes ?? input.content, {
+      encoding: bytes ? 'binary' : 'utf-8', runAfterWrite: input.runAfterWrite, signal,
+    })
     return { ok: true, path, bytes: bytes?.length ?? new TextEncoder().encode(input.content).length }
   })
   registry.bind('deviceFile.remove', async (input, { session, signal }) => {

package/src/device_session.js

@@ -47,6 +47,7 @@ const EV_MUX_USER_RPC_METHODS = new Set([
   'capabilities',
   'session.keepalive',
   'session.release',
+  'file.write',
   'script.write',
   'script.run',
   'device.control',
@@ -146,7 +147,7 @@ function isNetworkAction(method, payload) {
 }
 
 function isVmRpc(method, payload) {
-  if (method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
+  if (method === 'file.write' || method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
   if (method === 'debug.info') return payload?.scope !== 'transport.stats'
   return false
 }
@@ -155,30 +156,6 @@ function payloadBytes(payload) {
   return payload instanceof Uint8Array ? payload : utf8Bytes(payload)
 }
 
-function maxScriptChunkBytes({ path, encoding, mode, runAfterWrite, rxPayloadMax, totalBytes }) {
-  let low = 1
-  let high = Math.max(1, Math.min(EV_MUX_SCRIPT_CHUNK_BYTES, rxPayloadMax))
-  while (low < high) {
-    const candidate = Math.ceil((low + high) / 2)
-    const payload = {
-      path, encoding, mode, offset: Math.max(0, totalBytes - 1), totalBytes,
-      contentBase64: 'A'.repeat(Math.ceil(candidate / 3) * 4), runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length <= rxPayloadMax) low = candidate
-    else high = candidate - 1
-  }
-  return low
-}
-
-function bytesToBase64(bytes) {
-  let binary = ''
-  const chunkSize = 0x8000
-  for (let i = 0; i < bytes.length; i += chunkSize) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize))
-  }
-  return btoa(binary)
-}
-
 function defaultSleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -262,6 +239,11 @@ export function validateEvmuxCapabilities(payload) {
   }
 
   for (const key of Object.keys(EV_MUX_DEFAULT_LIMITS)) validateLimit(payload.limits, key)
+  if (payload.features.includes('file.write.binary') && (!Number.isSafeInteger(payload.limits.fileWriteChunkMax)
+      || payload.limits.fileWriteChunkMax < 4096 || payload.limits.fileWriteChunkMax > 16384
+      || payload.limits.fileWriteChunkMax % 4096 !== 0)) {
+    throw new Error('EV-MUX v4 capabilities are missing a valid limits.fileWriteChunkMax')
+  }
   if (payload.session?.policy !== 'firstCome'
       || !Number.isSafeInteger(payload.session.leaseMs)
       || !Number.isSafeInteger(payload.session.keepaliveMs)
@@ -622,6 +604,7 @@ export class DeviceSession {
     redactSsid = true,
     forceNetwork = false,
   } = {}) {
+    if (payload instanceof Uint8Array) return { binaryBytes: payload.byteLength }
     if (!forceNetwork && !isNetworkAction(method, payload) && !isNetworkAction(method, requestPayload)) return payload
     const secrets = [requestPayload?.ssid, requestPayload?.password]
       .filter((value) => typeof value === 'string' && value.length > 0)
@@ -687,6 +670,7 @@ export class DeviceSession {
     seq: requestedSeq = null,
     signal = null,
     writeTimeout = null,
+    encoding = undefined,
   } = {}) {
     if (this.state === 'disconnected') {
       throw new Error('EV-MUX is not connected')
@@ -715,7 +699,9 @@ export class DeviceSession {
         && (payloadData.length !== 1 || payloadData[0] !== 0x03)) {
       throw new Error('EV-MUX repl.signal only accepts the single-byte Ctrl-C signal 0x03')
     }
-    if (this.capabilities && payloadData.length > this.limits.rxPayloadMax) {
+    const payloadLimit = method === 'file.write' && encoding === 'binary' && this.hasFeature('file.write.binary')
+      ? this.limits.fileWriteChunkMax + 20 : this.limits.rxPayloadMax
+    if (this.capabilities && payloadData.length > payloadLimit) {
       throw new Error(`EV-MUX payload is ${payloadData.length} bytes; device limit is ${this.limits.rxPayloadMax}`)
     }
     if ((channel === 'repl.stdin' || channel === 'repl.signal') && payloadData.length > this.limits.replInputMax) {
@@ -727,7 +713,7 @@ export class DeviceSession {
       seq,
       channel,
       type: frameType,
-      encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+      encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
       ...(method ? { method } : {}),
       ...(needsAuthorization ? { sessionId: this.sessionId } : {}),
       ...(usesVm && needsAuthorization ? { vmEpoch: this.vmEpoch } : {}),
@@ -738,6 +724,7 @@ export class DeviceSession {
     const frame = this.makeEvMuxFrame({
       channel,
       type: frameType,
+      encoding,
       method,
       payload,
       seq,
@@ -764,6 +751,7 @@ export class DeviceSession {
       throw new Error('EV-MUX is not connected')
     }
     if (signal?.aborted) throw abortError(signal)
+    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')) {
       validateRpcPath(payload.path ?? (payload.scope === 'fs.list' ? '/' : undefined))
@@ -816,7 +804,8 @@ export class DeviceSession {
     this.handlers.rpcRequest?.({ channel: rpcChannel, method, seq, timeout, payload: safePayload })
     this._diagnostic('rpc.request', { channel: rpcChannel, method, seq })
     try {
-      await this.writeFrame(rpcChannel, 'req', method, JSON.stringify(payload), {
+      await this.writeFrame(rpcChannel, 'req', method, payload instanceof Uint8Array ? payload : JSON.stringify(payload), {
+        encoding: payload instanceof Uint8Array ? 'binary' : undefined,
         vmRequest,
         seq,
         signal,
@@ -1089,41 +1078,45 @@ export class DeviceSession {
       : content instanceof Uint8Array
         ? content
         : new Uint8Array(content)
-    const chunkBytes = maxScriptChunkBytes({
-      path, encoding, mode, runAfterWrite, rxPayloadMax: this.limits.rxPayloadMax, totalBytes: bytes.length,
-    })
-    if (this.hasFeature('script.write.chunked') && bytes.length > chunkBytes) {
-      let lastResponse = null
-      for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+    if (!this.hasFeature('file.write.binary')) {
+      throw Object.assign(new Error('File upload requires firmware with file.write.binary; update the device firmware'), { code: 'UNSUPPORTED_OPERATION' })
+    }
+    const limit = this.limits.fileWriteChunkMax
+    if (!Number.isSafeInteger(limit) || limit < 4096 || limit > 16384 || limit % 4096 !== 0 || bytes.length > 0xffffffff) {
+      throw new Error('Invalid negotiated binary file transfer limit or file size')
+    }
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes))
+    if (signal?.aborted) throw abortError(signal)
+    const sha256 = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('')
+    const uploadId = randomHex()
+    let committed = false
+    try {
+      const begin = await this.rpc('file.write', { action: 'begin', path, mode, totalBytes: bytes.length, sha256, uploadId }, { timeout: 8000, signal })
+      if (begin.uploadId !== uploadId || begin.chunkBytes !== limit) throw new Error('Invalid binary file transfer acknowledgement')
+      const token = Uint8Array.from(begin.uploadId.match(/../g), byte => parseInt(byte, 16))
+      for (let offset = 0; offset < bytes.length; offset += limit) {
         if (signal?.aborted) throw abortError(signal)
-        const chunk = bytes.subarray(offset, Math.min(offset + chunkBytes, bytes.length))
-        lastResponse = await this.rpc('script.write', {
-          path,
-          encoding,
-          mode,
-          offset,
-          totalBytes: bytes.length,
-          contentBase64: bytesToBase64(chunk),
-          runAfterWrite: runAfterWrite && offset + chunk.length >= bytes.length,
-        }, { timeout: 8000, signal })
+        const chunk = bytes.subarray(offset, Math.min(offset + limit, bytes.length))
+        const payload = new Uint8Array(20 + chunk.length)
+        payload.set(token)
+        new DataView(payload.buffer).setUint32(16, offset, true)
+        payload.set(chunk, 20)
+        const response = await this.rpc('file.write', payload, { timeout: 8000, signal })
+        if (response.writtenBytes !== offset + chunk.length) throw new Error('Incomplete binary file transfer acknowledgement')
         onProgress?.({ writtenBytes: offset + chunk.length, totalBytes: bytes.length })
       }
-      return lastResponse
-    }
-
-    const payload = {
-      path,
-      encoding,
-      mode,
-      contentBase64: bytesToBase64(bytes),
-      runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length > this.limits.rxPayloadMax) {
-      throw new Error(`script.write payload exceeds the device RX limit ${this.limits.rxPayloadMax}; firmware must support script.write.chunked.`)
+      const result = await this.rpc('file.write', { action: 'commit', uploadId: begin.uploadId }, { timeout: 8000, signal })
+      if (result.complete !== true || result.bytes !== bytes.length) throw new Error('Incomplete binary file commit acknowledgement')
+      committed = true
+      if (bytes.length === 0) onProgress?.({ writtenBytes: 0, totalBytes: 0 })
+      if (runAfterWrite) await this.rpc('script.run', { path }, { timeout: 8000, signal })
+      return { ...result, path, runAfterWrite }
+    } finally {
+      if (!committed) {
+        // Cancellation does not cancel cleanup, and cleanup cannot mask the primary error.
+        await this.rpc('file.write', { action: 'abort', uploadId }, { timeout: 1500 }).catch(() => {})
+      }
     }
-    const response = await this.rpc('script.write', payload, { timeout: 8000, signal })
-    onProgress?.({ writtenBytes: bytes.length, totalBytes: bytes.length })
-    return response
   }
 
   async writeScript(path, content, { runAfterWrite = false, signal = null } = {}) {
@@ -1217,10 +1210,10 @@ export class DeviceSession {
     if (commandBytes <= inputLimit) {
       return this.repl.execPy(source, { timeout, signal })
     }
-    if (!this.hasFeature('script.write') || !this.hasFeature('script.run')) {
+    if (!this.hasFeature('file.write.binary') || !this.hasFeature('script.run')) {
       throw new Error(
         `Python source requires ${commandBytes} REPL bytes, above the firmware limit ${inputLimit}; ` +
-        'upgrade firmware with script.write and script.run support.',
+        'upgrade firmware with file.write.binary and script.run support.',
       )
     }
 
@@ -1365,8 +1358,8 @@ export class DeviceSession {
     if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
       throw new RangeError('Script timeout must be a positive number or null for an interactive run')
     }
-    if ((content !== undefined && !this.hasFeature('script.write')) || !this.hasFeature('script.run')) {
-      throw new Error('Running scripts requires script.run and uploading source also requires script.write')
+    if ((content !== undefined && !this.hasFeature('file.write.binary')) || !this.hasFeature('script.run')) {
+      throw new Error('Running scripts requires script.run and uploading source also requires file.write.binary')
     }
     if (this.runCapture || this.runStarting) {
       throw new Error('A script is already running')

package/src/evmux.js

@@ -389,14 +389,14 @@ export class EvMuxParser {
     }
 }
 
-export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined }) {
+export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined, encoding = undefined }) {
     const payloadBytes = payload instanceof Uint8Array ? payload : new TextEncoder().encode(payload)
     const metadata = {
         sid,
         seq,
         channel,
         type,
-    encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+    encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
     ...(sessionId ? { sessionId } : {}),
     ...(vmEpoch !== undefined ? { vmEpoch } : {}),
     ...(contentType ? { contentType } : {}),
@@ -408,7 +408,8 @@ export function makeEvMuxFrame({ channel, type = 'data', method = null, payload
         metadata.method = method
     }
     const metadataBytes = new TextEncoder().encode(JSON.stringify(metadata))
-    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=00000000\r\n`)
+    const checksum = encoding === 'binary' ? crc32(payloadBytes).toString(16).padStart(8, '0') : '00000000'
+    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=${checksum}\r\n`)
     const out = new Uint8Array(header.length + metadataBytes.length + payloadBytes.length + 1)
     out.set(header, 0)
     out.set(metadataBytes, header.length)

package/src/firmware_feed.js

@@ -23,6 +23,7 @@ export async function loadOfficialFirmware({ board, fetch: fetcher = globalThis.
     if (metadata) {
       const entry = await metadata.json()
       if (entry.board !== name || entry.version !== version || new URL(entry.image?.url).origin !== 'https://dl.espressif.com') throw new TypeError('Official firmware metadata identity/URL mismatch')
+      if (entry.install && new URL(entry.install.url).origin !== 'https://dl.espressif.com') throw new TypeError('Official install URL mismatch')
       releases.push(entry)
     } else {
       const file = web.binaryNameTemplate.replace('{board}', name).replace('{tag}', version)

package/src/firmware_flash.js

@@ -6,18 +6,37 @@ export async function firmwareSha256(bytes) {
   return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')
 }
 
-export async function validateFirmwareImage(image, bytes) {
+export function firmwareMode(mode = 'update') {
+  if (!['update', 'install'].includes(mode)) throw new TypeError('Firmware mode must be update or install')
+  return mode
+}
+
+export async function validateFirmwareImage(image, bytes, { mode = 'update' } = {}) {
+  firmwareMode(mode)
   if (image.evMuxVersion !== 4) throw new Error('Only approved EV-MUX v4 firmware can be installed')
   if (!(bytes instanceof Uint8Array) || bytes.byteLength !== image.bytes) throw new Error('Firmware image size does not match the approved build')
-  if (!Number.isSafeInteger(image.offset) || !Number.isSafeInteger(image.partitionSize)
-      || image.offset < 0 || image.bytes <= 0 || image.bytes > image.partitionSize) throw new Error('Invalid application partition bounds')
+  const limit = mode === 'install' ? image.flashSize : image.partitionSize
+  if (!Number.isSafeInteger(image.offset) || !Number.isSafeInteger(limit)
+      || image.offset < 0 || image.bytes <= 0 || image.bytes > limit || (mode === 'install' && image.offset !== 0)) throw new Error('Invalid firmware image bounds')
   if (await firmwareSha256(bytes) !== image.sha256) throw new Error('Firmware SHA-256 does not match the approved build')
+  if (mode === 'install') {
+    const segments = [image.bootloader, image.partitionTable, image.application]
+    let end = 0
+    for (const segment of segments) {
+      if (!segment || !Number.isSafeInteger(segment.offset) || !Number.isSafeInteger(segment.bytes)
+          || segment.offset < end || segment.bytes <= 0 || segment.offset + segment.bytes > bytes.byteLength
+          || !/^[a-f0-9]{64}$/.test(segment.sha256 ?? '')) throw new Error('Complete image requires ordered, non-overlapping bootloader, partition table and application metadata')
+      if (await firmwareSha256(bytes.subarray(segment.offset, segment.offset + segment.bytes)) !== segment.sha256) throw new Error('Complete image does not contain the approved bootloader, partition table and application')
+      end = segment.offset + segment.bytes
+    }
+  }
   return bytes
 }
 
 /** Loader injected by the browser host; no Web Serial or ROM protocol duplicated. */
 export class FirmwareFlashSession {
-  constructor(loader, image, { reset = () => loader.hardReset() } = {}) {
+  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update' } = {}) {
+    this.mode = firmwareMode(mode)
     this.loader = loader
     this.reset = reset
     this.image = image
@@ -29,7 +48,7 @@ export class FirmwareFlashSession {
     if (this.state !== 'idle') throw new Error('Firmware loader is already in use')
     this.state = 'connecting'
     try {
-      await validateFirmwareImage(this.image, bytes)
+      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
       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
@@ -43,9 +62,18 @@ export class FirmwareFlashSession {
       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')
       this.stub = await this.loader.runStub(true)
-      const table = this.image.partitionTable
-      const existing = await this.stub.readFlash(table.offset, table.bytes)
-      if (await firmwareSha256(existing) !== table.sha256) throw new Error('Partition layout differs; use the board migration instructions instead')
+      if (this.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()
+        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')
+      } else {
+        const table = this.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')
+      }
       this.state = 'connected'
     } catch (error) { await this.disconnect(); throw error }
   }
@@ -54,11 +82,11 @@ 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)
-      onPhase('Writing application; bootloader, partition table, NVS and user files are preserved')
+      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)
-      onPhase('Verifying the complete application image')
+      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)
       for (let offset = 0; offset < bytes.byteLength; offset += 65536) {

package/src/firmware_updates.js

@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { loadOfficialFirmware } from './firmware_feed.js'
-import { FirmwareFlashSession, validateFirmwareImage } from './firmware_flash.js'
+import { FirmwareFlashSession, validateFirmwareImage, firmwareMode } from './firmware_flash.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -16,7 +16,7 @@ function identity(value) {
   if (!value || typeof value.board !== 'string' || !value.board || typeof value.firmwareVersion !== 'string' || !value.firmwareVersion) throw new TypeError('An inspected identity with board and firmwareVersion is required')
   return structuredClone(value)
 }
-function release(value) {
+function release(value, mode = 'update') {
   if (!value || typeof value.board !== 'string' || !value.board || typeof value.version !== 'string' || !value.version) throw new TypeError('Release requires board and version')
   const image = value.image
   const revisionValid = image?.chipRevision !== undefined
@@ -29,6 +29,23 @@ function release(value) {
       || !/^[a-f0-9]{64}$/.test(image.sha256 ?? '') || !Number.isSafeInteger(image.partitionTable?.offset) || image.partitionTable.offset < 0
       || !Number.isSafeInteger(image.partitionTable?.bytes) || image.partitionTable.bytes <= 0
       || !/^[a-f0-9]{64}$/.test(image.partitionTable?.sha256 ?? '')) throw new TypeError('Release requires complete EV-MUX v4 application/chip/partition/SHA-256 metadata')
+  if (mode === 'install') {
+    const install = value.install
+    if (!install || install.offset !== 0 || !Number.isSafeInteger(install.bytes) || install.bytes <= 0
+        || !Number.isSafeInteger(install.flashSize) || install.flashSize < install.bytes || install.flashSize > 2 ** 30
+        || !Number.isInteger(Math.log2(install.flashSize)) || install.flashSize < 2 ** 18
+        || !/^[a-f0-9]{64}$/.test(install.sha256 ?? '') || !install.bootloader
+        || !Number.isSafeInteger(install.chipRevisionMin) || !Number.isSafeInteger(install.chipRevisionMax)
+        || install.chipRevisionMin < (image.chipRevision ?? image.chipRevisionMin) || install.chipRevisionMax > (image.chipRevision ?? image.chipRevisionMax)
+        || install.chipRevisionMin < 0 || install.chipRevisionMax < install.chipRevisionMin) throw Object.assign(new TypeError('Release lacks qualified complete-install metadata'), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
+    let end = 0
+    for (const part of [install.bootloader, image.partitionTable, image]) {
+      if (!Number.isSafeInteger(part.offset) || !Number.isSafeInteger(part.bytes) || part.bytes <= 0
+          || part.offset < end || part.offset + part.bytes > install.bytes
+          || !/^[a-f0-9]{64}$/.test(part.sha256 ?? '')) throw new TypeError('Invalid complete-install segment bounds or hashes')
+      end = part.offset + part.bytes
+    }
+  }
   return structuredClone(value)
 }
 async function download(url, fetcher, signal) {
@@ -41,10 +58,11 @@ async function download(url, fetcher, signal) {
 }
 
 export async function checkFirmware(request = {}, connectedIdentity) {
-  record(request, ['catalog', 'identity', 'version', 'fetch', 'signal'], 'firmware.check')
+  record(request, ['catalog', 'identity', 'version', 'mode', 'fetch', 'signal'], 'firmware.check')
   const { signal, fetch: fetcher = globalThis.fetch } = request
   abort(signal)
   if (request.version !== undefined && (typeof request.version !== 'string' || !request.version.trim())) throw new TypeError('version must be a non-empty firmware version string')
+  const mode = firmwareMode(request.mode)
   const current = identity(connectedIdentity ?? request.identity)
   const catalog = request.catalog === undefined ? await loadOfficialFirmware({ board: current.board, fetch: fetcher, signal }) : typeof request.catalog === 'string' ? await (await download(request.catalog, fetcher, signal)).json() : structuredClone(request.catalog)
   abort(signal)
@@ -56,22 +74,30 @@ export async function checkFirmware(request = {}, connectedIdentity) {
     return structuredClone(item)
   })
   if (new Set(candidates.map(item => item.version)).size !== candidates.length) throw new TypeError('Catalog must not contain duplicate versions for one board')
-  const selected = request.version === undefined ? candidates.find(item => item.compatible !== false) ?? null : candidates.find(item => item.version === request.version)
+  const selected = request.version === undefined ? candidates.find(item => item.compatible !== false && (mode !== 'install' || item.install)) ?? null : candidates.find(item => item.version === request.version)
   if (request.version !== undefined && !selected) throw Object.assign(new Error('Requested firmware version is unavailable for this board'), { code: 'FIRMWARE_VERSION_UNAVAILABLE' })
   if (selected?.compatible === false) throw Object.assign(new Error('This published version lacks approved v4 update metadata'), { code: 'FIRMWARE_INCOMPATIBLE' })
+  if (selected) release(selected, mode)
   return { available: selected !== null && (selected.firmwareVersion ?? selected.version) !== current.firmwareVersion, currentVersion: current.firmwareVersion, release: selected, releases: candidates }
 }
 
 export async function updateFirmware(request, connectedIdentity, disconnect) {
-  record(request, ['release', 'board', 'data', 'fetch', 'openLoader', 'reset', 'onProgress', 'onPhase', 'signal'], 'firmware.update')
+  record(request, ['release', 'board', 'mode', 'data', 'fetch', 'openLoader', 'reset', 'onProgress', 'onPhase', 'signal'], 'firmware.update')
   const { signal, fetch: fetcher = globalThis.fetch, openLoader, reset, onProgress = () => {}, onPhase = () => {} } = request
   abort(signal)
   if (typeof openLoader !== 'function' || typeof onProgress !== 'function' || typeof onPhase !== 'function' || (reset !== undefined && typeof reset !== 'function')) throw new TypeError('Firmware update requires openLoader and valid callbacks')
-  const target = release(request.release)
+  const mode = firmwareMode(request.mode)
+  const target = release(request.release, mode)
+  const image = mode === 'install' ? {
+    ...target.image, offset: target.install.offset, bytes: target.install.bytes,
+    flashSize: target.install.flashSize, sha256: target.install.sha256, url: target.install.url,
+    bootloader: target.install.bootloader, application: target.image,
+    chipRevision: undefined, chipRevisionMin: target.install.chipRevisionMin, chipRevisionMax: target.install.chipRevisionMax,
+  } : target.image
   const board = connectedIdentity?.board ?? request.board
   if (!board || board !== target.board || (request.board !== undefined && request.board !== board)) throw new TypeError('Firmware release does not match the connected or explicitly selected board')
-  const bytes = request.data === undefined ? new Uint8Array(await (await download(target.image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
-  await validateFirmwareImage(target.image, bytes)
+  const bytes = request.data === undefined ? new Uint8Array(await (await download(image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  await validateFirmwareImage(image, bytes, { mode })
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.
   await disconnect()
@@ -80,7 +106,7 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   let session
   try {
     abort(signal)
-    session = new FirmwareFlashSession(loader, target.image, { reset: reset ? () => reset(loader) : undefined })
+    session = new FirmwareFlashSession(loader, image, { mode, reset: reset ? () => reset(loader) : undefined })
     await session.connect(bytes)
     abort(signal)
     // No interruption after writing starts: finish verification and reset policy.

package/src/node.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+// Node-only adapters. Creating them does not acquire a session or serial port.
+export { tcpTransport, serialTransport } from './node_transport.js'
+export { openNodeRom } from './node_rom.js'

package/src/node_rom.js

@@ -41,6 +41,7 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}) {
       try { Object.assign(loader, await rpc('initialize')) }
       finally { signal?.removeEventListener('abort', cancelled) }
     },
+    flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
     async runStub() { await rpc('stub'); return loader },
     async readFlash(offset, bytes) { return new Uint8Array(Buffer.from(await rpc('read', [offset, bytes]), 'base64')) },

package/src/node_rom.py

@@ -32,6 +32,8 @@ def main():
                         esp = esptool.run_stub(esp)
                         esptool.attach_flash(esp)
                         esp.change_baud(460800)
+                    elif method == 'flashId':
+                        result = esp.flash_id()
                     elif method == 'read':
                         result = base64.b64encode(esp.read_flash(*args)).decode('ascii')
                     elif method == 'write':

package/tests/check-package.mjs

@@ -38,7 +38,7 @@ try {
   if (Object.keys(api).sort().join(',') !== 'createDevice') throw new Error('Root must expose only the application API');
   const { DeviceSession } = await import('@esp-vision/device-core/session');
   const { FirmwareFlashSession } = await import('@esp-vision/device-core/firmware');
-  const { tcpTransport, serialTransport } = await import('@esp-vision/device-core/node');
+  const { tcpTransport, serialTransport, openNodeRom } = await import('@esp-vision/device-core/node');
   if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
   const { createNodeDiscovery } = await import('@esp-vision/device-core/discovery/node');
   const { EventEmitter } = await import('node:events');
@@ -49,6 +49,7 @@ try {
   const device = api.createDevice({ discovery: provider });
   if (typeof provider.list !== 'function') throw new Error('Discovery providers must expose list()');
   if ((await device.discover({ timeout: 50 })).length !== 0 || !queries) throw new Error('Device discovery did not call its provider');
+  if (typeof openNodeRom !== 'function' || typeof openNodeRom({ port: 'not-opened' }).initialize !== 'function') throw new Error('Missing passive Node ROM adapter');
   // Constructors must be passive: these endpoints need not exist to create adapters.
   api.createDevice({ transport: tcpTransport({ host: '127.0.0.1', port: 1 }) });
   api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });

package/tests/test-device-execution.mjs

@@ -13,6 +13,7 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   let session
   let resetRequested = false
   let resetPolls = 0
+  let uploaded = 0
   const stdout = (payload) => session.feedBytes(makeEvMuxFrame({
     channel: 'repl.stdout', type: 'data', sessionId: session.sessionId, vmEpoch: session.vmEpoch, payload,
   }))
@@ -26,7 +27,7 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   const parser = new EvMuxParser({
     filterFrame: (metadata, bytes) => {
       const text = new TextDecoder().decode(bytes)
-      const payload = metadata.channel.endsWith('.rpc') ? JSON.parse(text) : text
+      const payload = metadata.encoding === 'binary' ? bytes : metadata.channel.endsWith('.rpc') ? JSON.parse(text) : text
       requests.push({ metadata, payload })
       if (metadata.channel === 'repl.signal') return
       if (metadata.channel === 'repl.stdin') {
@@ -51,7 +52,15 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
         response = { ok: true, sessionId: session.sessionId, vmEpoch: responseEpoch,
           vmReady: stalledReset || resetPolls === 1 || resetPolls >= 3 }
       }
-      if (metadata.method === 'script.write' && failWrite) {
+      if (metadata.method === 'file.write') {
+        if (payload instanceof Uint8Array) {
+          uploaded = new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint32(16, true) + payload.length - 20
+          response = { ok: true, writtenBytes: uploaded }
+        } else if (payload.action === 'begin') {
+          uploaded = 0; response = { ok: true, uploadId: payload.uploadId, chunkBytes: 16384 }
+        } else response = { ok: true, bytes: uploaded, complete: payload.action === 'commit' }
+      }
+      if (metadata.method === 'file.write' && failWrite) {
         response = { ok: false, error: { code: 'WRITE_FAILED', message: 'simulated write failure' } }
       } else if (metadata.method === 'script.run') {
         running = true
@@ -75,7 +84,8 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   session.sessionId = 'a'.repeat(32)
   session.vmEpoch = 1
   session.vmReady = true
-  session.capabilities = { features: ['script.write', 'script.run', 'device.control'] }
+  session.limits.fileWriteChunkMax = 16384
+  session.capabilities = { features: ['file.write.binary', 'script.run', 'device.control'] }
   return { session, requests, finish, get terminal() { return terminal }, get running() { return running } }
 }
 

package/tests/test-file-binary.mjs

@@ -0,0 +1,112 @@
+// 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 { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function fixture(options = {}) {
+  const requests = [], chunks = []; let session, began, finished
+  let token
+  const peer = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const payload = metadata.encoding === 'binary' ? bytes.slice() : JSON.parse(new TextDecoder().decode(bytes))
+    requests.push({ metadata, payload })
+    let reply = { ok: true }
+    if (payload instanceof Uint8Array) {
+      assert.equal(metadata.method, 'file.write'); assert.equal(metadata.encoding, 'binary')
+      assert.equal(metadata.vmEpoch, 7); assert.equal(metadata.sessionId, 'a'.repeat(32))
+      assert.equal(Buffer.from(payload.slice(0, 16)).toString('hex'), token)
+      const offset = new DataView(payload.buffer).getUint32(16, true)
+      assert.equal(offset, chunks.reduce((sum, chunk) => sum + chunk.length, 0))
+      chunks.push(payload.slice(20)); reply.writtenBytes = offset + payload.length - 20
+      if (options.badAck) reply.writtenBytes--
+      if (options.abort) options.abort.abort()
+    } else if (payload.action === 'begin') {
+      began = payload; token = payload.uploadId; reply.uploadId = token; reply.chunkBytes = 16384
+      if (options.abortBegin) options.abortBegin.abort()
+      if (options.failBegin) { options.failBegin = false; throw new Error('begin response lost') }
+    } else if (payload.action === 'commit') {
+      finished = true; reply.bytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0); reply.complete = true
+      if (options.badCommit) reply.bytes++
+      if (options.failCommit) reply = { ok: false, error: { code: 'HASH_MISMATCH' } }
+    }
+    session.feedBytes(makeEvMuxFrame({ channel: 'user.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq,
+      sessionId: 'a'.repeat(32), vmEpoch: 7, payload: JSON.stringify(reply) }))
+    return false
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { peer.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  Object.assign(session, { state: 'ready', sessionId: 'a'.repeat(32), vmEpoch: 7, vmReady: true,
+    capabilities: { features: ['file.write.binary', 'script.run'] } })
+  session.limits.fileWriteChunkMax = 16384
+  return { session, requests, chunks, get began() { return began }, get finished() { return finished } }
+}
+for (const size of [0, 1, 4096, 16384, 16385, 2 * 1024 * 1024]) {
+  test(`binary upload ${size} bytes is bounded, exact, hashed and committed`, async () => {
+    const f = fixture(), data = Uint8Array.from({ length: size }, (_, i) => i & 255), progress = []
+    try {
+      const result = await f.session.writeFile('/model.bin', data, { encoding: 'binary', onProgress: value => progress.push(value.writtenBytes) })
+      assert.equal(result.complete, true); assert.equal(result.bytes, size)
+      assert.deepEqual(Buffer.concat(f.chunks), Buffer.from(data)); assert.equal(f.finished, true)
+      assert.equal(f.began.sha256, Buffer.from(await crypto.subtle.digest('SHA-256', data)).toString('hex'))
+      assert.ok(f.chunks.every(chunk => chunk.length <= 16384)); assert.equal(f.chunks.length, Math.ceil(size / 16384))
+      assert.equal(progress.at(-1), size)
+      assert.ok(!f.requests.some(request => request.metadata.method === 'script.write'))
+    } finally { f.session.close() }
+  })
+}
+test('Python upload uses the same byte engine and requests execution only after commit', async () => {
+  const f = fixture()
+  try {
+    await f.session.writeScript('/script.py', "print('中文')", { runAfterWrite: true })
+    assert.deepEqual(Buffer.concat(f.chunks), Buffer.from("print('中文')"))
+    assert.equal(f.requests.at(-1).metadata.method, 'script.run')
+    assert.equal(f.requests.at(-2).payload.action, 'commit')
+  } finally { f.session.close() }
+})
+for (const setting of ['badAck', 'badCommit', 'failCommit']) {
+  test(`${setting} triggers abort cleanup without publishing success`, async () => {
+    const f = fixture({ [setting]: true })
+    try {
+      await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)))
+      assert.equal(f.requests.at(-1).payload.action, 'abort')
+    } finally { f.session.close() }
+  })
+}
+test('cancellation after begin still sends an independent abort', async () => {
+  const controller = new AbortController(), f = fixture({ abort: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(32768), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+  } finally { f.session.close() }
+})
+test('missing binary capability rejects without falling back to script.write', async () => {
+  const f = fixture(); f.session.capabilities.features = ['script.write']
+  try { await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(10)), { code: 'UNSUPPORTED_OPERATION' }); assert.equal(f.requests.length, 0) }
+  finally { f.session.close() }
+})
+test('corrupted binary frames fail CRC before dispatch', () => {
+  let calls = 0
+  const parser = new EvMuxParser({ filterFrame() { calls++; return false } })
+  const bytes = makeEvMuxFrame({ channel: 'user.rpc', type: 'req', method: 'file.write', encoding: 'binary', payload: new Uint8Array([0, 1, 0x1e, 0x1f, 255]) })
+  parser.feedBytes(bytes); assert.equal(calls, 1)
+  bytes[bytes.length - 2] ^= 1; parser.feedBytes(bytes); assert.equal(calls, 1)
+})
+
+test('cancellation during begin still aborts the client-known upload ID', async () => {
+  const controller = new AbortController(), f = fixture({ abortBegin: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+    assert.equal(f.chunks.length, 0)
+  } finally { f.session.close() }
+})
+test('a lost begin response still allows abort without knowing a server-generated ID', async () => {
+  const f = fixture({ failBegin: true })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)), /begin response lost/)
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+  } finally { f.session.close() }
+})

package/tests/test-firmware-install.mjs

@@ -0,0 +1,126 @@
+// 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 { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware_flash.js'
+import { parseCli, runCli } from '../src/cli.js'
+
+async function fixture() {
+  const data = new Uint8Array(0x11000).fill(0xff), calls = []
+  data.set([0xe9, 1, 2, 3], 0x2000)
+  data.set([0xaa, 0x50, 4, 5], 0x8000)
+  data.set([0xe9, 6, 7, 8], 0x10000)
+  const part = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(data.subarray(offset, offset + 4)) })
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await part(0x10000)),
+    partitionSize: 4096, partitionTable: await part(0x8000), url: 'https://example.test/app.bin',
+  }, install: { offset: 0, bytes: data.length, flashSize: 0x1000000, chipRevisionMin: 302, chipRevisionMax: 302,
+    sha256: await firmwareSha256(data), bootloader: await part(0x2000), url: 'https://example.test/full.bin' } }
+  const flash = new Uint8Array(data.length).fill(0xff)
+  const loader = {
+    chipFamily: 0x3280, chipRevision: 302,
+    async initialize() { calls.push('initialize') },
+    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
+    async runStub() { calls.push('stub'); return loader },
+    async flashId() { calls.push('capacity'); return 0x1840ef },
+    async flashData(buffer, progress, offset) { calls.push(['write', offset]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
+    async readFlash(offset, count) { calls.push(['read', offset]); return flash.slice(offset, offset + count) },
+    async readRegister() { return 0 },
+    async hardReset() { calls.push('reset') },
+    async disconnect() { calls.push('close') },
+  }
+  const device = createDevice(), request = { mode: 'install', release, board: 'BOARD', data, async openLoader() { calls.push('open'); return loader } }
+  return { data, calls, release, loader, device, request, flash }
+}
+
+test('blank device installs through ROM without an EV-MUX transport or existing partition table', async () => {
+  const f = await fixture(), progress = []
+  const result = await f.device.firmware.update({ ...f.request, onProgress: value => progress.push(value) })
+  assert.equal(result.verified, true); assert.equal(result.reconnected, false)
+  assert.deepEqual(f.flash, f.data)
+  assert.deepEqual(f.calls, ['open', 'initialize', 'stub', 'capacity', ['write', 0], ['read', 0], ['read', 65536], 'reset', 'close'])
+  assert.equal(progress.at(-1), 100)
+})
+
+test('default application update refuses blank layout and never falls back to installing', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, mode: undefined, data: f.data.slice(65536, 65540) }), /Partition layout/)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.ok(!f.calls.includes('capacity'))
+})
+
+test('complete image is downloaded from install URL with the requested cancellation signal', async () => {
+  const f = await fixture(), controller = new AbortController()
+  await f.device.firmware.update({ ...f.request, data: undefined, signal: controller.signal,
+    async fetch(url, options) { assert.equal(url, f.release.install.url); assert.equal(options.signal, controller.signal); return { ok: true, arrayBuffer: async () => f.data.buffer } },
+  })
+  assert.deepEqual(f.flash, f.data)
+})
+
+test('install selection skips app-only releases and rejects explicit unqualified versions', async () => {
+  const f = await fixture(), appOnly = { ...f.release, version: 'app-only', install: undefined }
+  const request = { mode: 'install', identity: { board: 'BOARD', firmwareVersion: 'unknown' }, catalog: { schemaVersion: 1, releases: [appOnly, f.release] } }
+  const result = await f.device.firmware.check(request)
+  assert.equal(result.release.version, 'new'); assert.equal(result.releases.length, 2)
+  await assert.rejects(f.device.firmware.check({ ...request, version: 'app-only' }), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
+  const updates = await f.device.firmware.check({ ...request, mode: 'update' })
+  assert.equal(updates.release.version, 'app-only')
+  assert.deepEqual(f.calls, [])
+})
+
+for (const change of ['hash', 'bootloader', 'table', 'application', 'overlap', 'bounds', 'revision-range', 'missing-metadata', 'mode', 'board']) {
+  test(`invalid ${change} rejects installation before opening or releasing a port`, async () => {
+    const f = await fixture()
+    if (change === 'hash') f.data[1] = 0
+    if (change === 'bootloader') f.release.install.bootloader.sha256 = '0'.repeat(64)
+    if (change === 'table') f.release.image.partitionTable.sha256 = '0'.repeat(64)
+    if (change === 'application') f.release.image.sha256 = '0'.repeat(64)
+    if (change === 'overlap') f.release.install.bootloader.bytes = 0x8000
+    if (change === 'bounds') f.release.install.offset = 0x1000
+    if (change === 'revision-range') f.release.install.chipRevisionMin = 301
+    if (change === 'missing-metadata') delete f.release.install
+    if (change === 'mode') f.request.mode = 'auto'
+    if (change === 'board') f.request.board = 'WRONG'
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.deepEqual(f.calls, [])
+  })
+}
+
+for (const change of ['wrong-chip', 'wrong-revision', 'secure-boot', 'encryption', 'small-flash', 'unknown-flash', 'missing-capacity']) {
+  test(`physical ${change} refuses installation before any write`, async () => {
+    const f = await fixture()
+    if (change === 'wrong-chip') f.loader.chipFamily = 0x3253
+    if (change === 'wrong-revision') f.loader.chipRevision = 301
+    if (change === 'secure-boot') f.loader.getSecurityInfo = async () => ({ flags: 1, flashCryptCnt: 0 })
+    if (change === 'encryption') f.loader.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 1 })
+    if (change === 'small-flash') f.loader.flashId = async () => 0x1740ef
+    if (change === 'unknown-flash') f.loader.flashId = async () => 0xffffff
+    if (change === 'missing-capacity') delete f.loader.flashId
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+    assert.equal(f.calls.at(-1), 'close')
+  })
+}
+
+test('installation with damaged readback does not reset or report success', async () => {
+  const f = await fixture(); f.loader.readFlash = async (_offset, count) => new Uint8Array(count)
+  await assert.rejects(f.device.firmware.update(f.request), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+
+test('CLI install uses ROM directly and passes mode through both check and update', async () => {
+  const f = await fixture(), checked = []
+  const options = parseCli(['firmware', 'update', '--mode', 'install', '--board', 'BOARD', '--port', '/dev/ttyACM0', '--version', 'new'])
+  const result = await runCli(options, {
+    transportFor: () => { throw new Error('No application transport should be acquired') },
+    async readFile() { throw new Error('No user catalog required') },
+    createDevice: () => ({ firmware: {
+      async check(request) { checked.push(request.mode); return { release: f.release } },
+      async update(request) { assert.equal(request.mode, 'install'); return { verified: true } },
+    }, async disconnect() {} }),
+  })
+  assert.equal(result.verified, true); assert.deepEqual(checked, ['install'])
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--port', 'COM3', '--version', 'new']), /explicit --board/)
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--tcp', 'host', '--board', 'BOARD', '--version', 'new']), /local --port/)
+})

package/tests/test-release-verification.mjs

@@ -0,0 +1,66 @@
+// 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 { verifyPublishedIntegrity } from '../scripts/verify-registry.mjs'
+
+const integrity = 'sha512-test-content'
+const url = 'https://registry.npmjs.org/%40esp-vision%2Fdevice-core/0.2.0'
+const published = value => new Response(JSON.stringify({ dist: { integrity: value } }))
+function fixture(replies) {
+  const calls = [], waits = [], reports = []
+  return { calls, waits, reports, options: {
+    async fetcher(address, options) {
+      calls.push({ address, options })
+      const reply = replies.shift()
+      if (reply instanceof Error) throw reply
+      assert(reply, 'Unexpected verification request')
+      return reply
+    },
+    wait: async milliseconds => { waits.push(milliseconds) },
+    report: message => reports.push(message),
+  } }
+}
+test('new npm version becomes visible after stale 404 metadata; only uncached reads repeat', async () => {
+  const f = fixture([new Response('', { status: 404 }), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 2); assert.deepEqual(f.waits, [1000])
+  for (const call of f.calls) {
+    assert.equal(call.address, url); assert.equal(call.options.cache, 'no-store')
+    assert.equal(call.options.headers['Cache-Control'], 'no-cache')
+    assert.equal(call.options.method ?? 'GET', 'GET')
+  }
+})
+test('verification retries rate limits, temporary registry errors and network failures', async () => {
+  const f = fixture([new Response('', { status: 429 }), new Response('', { status: 503 }), new TypeError('network unavailable'), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.deepEqual(f.waits, [1000, 2000, 4000])
+})
+for (const status of [400, 401, 403]) test(`registry HTTP ${status} fails without retries`, async () => {
+  const f = fixture([new Response('', { status })])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), new RegExp(`HTTP ${status}`))
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('published integrity mismatch fails immediately', async () => {
+  const f = fixture([published('sha512-other-content')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('missing published integrity is not accepted', async () => {
+  const f = fixture([new Response('{}')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.deepEqual(f.waits, [])
+})
+test('persistent propagation failures stop after ten reads with bounded backoff', async () => {
+  const f = fixture(Array.from({ length: 10 }, () => new Response('', { status: 404 })))
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 10 reads/)
+  assert.equal(f.calls.length, 10); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000, 30000])
+})
+
+test('registry visibility delayed beyond the original 31-second window is verified without another publish', async () => {
+  const f = fixture([...Array.from({ length: 7 }, () => new Response('', { status: 404 })), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 8)
+  assert.ok(f.waits.reduce((total, delay) => total + delay, 0) > 31000)
+  assert.ok(f.waits.every(delay => delay <= 30000))
+})