@esp-vision/device-core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.0 (unreleased)
+
+### Added
+
+- Reuse browser cache only for hash-pinned release manifests and complete-BIN sources; retry a fetch-stage TypeError once with no-store for cached CORS recovery, while hash/HTTP/metadata failures and legacy app-only downloads retain strict failure/cache behavior.
+
+- Export immutable official release-manifest readers with publication/version/board/hash pinning and bounded, source-constrained validation of firmware, website, models and MCP snapshots; model files are unique by path while a group may share one slug, and normalized paths cannot escape the pinned source commit.
+- Support application updates from the qualified complete BIN through `image.source`, verifying the whole container and embedded segments before extracting the application; preserve explicit full installation and legacy app-only descriptors.
+
+- Export passive `openBrowserRom({ port, logger?, signal? })` at `/browser` with a lazily loaded, pinned tasmota browser backend; share verified Core firmware install/update workflows without host-maintained ROM patches.
+- Validate the real browser bundle, P4/S31 stub assets, adapter cleanup/cancellation and isolated package imports.
+
+## 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

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 were introduced in 0.1.1. This source prepares 0.2.0 with reliable binary uploads; confirm registry publication before installing it. 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 prepares **0.4.0 (not published by this change)** with browser ROM flashing, immutable release-manifest readers and application updates from a single complete BIN. npm 0.3.0 does not contain these APIs. 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 before using the 0.4.0 install examples; until publication, 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 install --save-exact @esp-vision/device-core@0.2.0 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.4.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.2.0
+npm install -g @esp-vision/device-core@0.4.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 |
 
@@ -110,6 +110,47 @@ try {
 }
 ```
 
+### Immutable release snapshots and a single firmware BIN (0.4.0, unpublished)
+
+The `/firmware` entry exports `loadOfficialFirmware({ board?, version?, fetch?, signal? })` and `loadReleaseManifest({ url, sha256, version?, sourceCommit?, boards?, fetch?, signal? })`. The official reader prioritizes `[publication]` in `config.toml`, selects exactly one version reference and verifies its raw manifest SHA-256 before returning `{ schemaVersion: 1, version, sourceCommit, pipelineId, layout, releases, website, mcp?, publication }`. History references include exact board sets; unsupported board/version combinations and malformed explicit publication data reject without falling back to guessed URLs or old metadata. Configs without `[publication]` keep the legacy feed; an explicit version limits old metadata requests too.
+
+For a website built from a verified snapshot, keep its selected publication reference rather than re-reading mutable `config.toml` when the user clicks:
+
+```js
+import { loadReleaseManifest } from '@esp-vision/device-core/firmware';
+const snapshot = await loadReleaseManifest({
+  url: reference.manifestUrl, sha256: reference.manifestSha256,
+  version: reference.version, boards: reference.boards,
+});
+const release = snapshot.releases.find(entry => entry.board === selectedBoard);
+// Pass release to createDevice().firmware.update(); the website never slices BINs.
+```
+
+In `layout: 'single-bin'`, `image.source = { url, bytes, sha256, offset }` describes the complete BIN; `image.url` equals its URL, while `image.bytes/sha256` still describe only the application. The source URL/length/hash must match `install`, and its offset must equal the application's flash offset. Core downloads the full container once (no Range request), validates its whole hash and embedded bootloader/partition/application hashes, then extracts and writes only the application in default update mode. Existing partition checks and full application readback remain mandatory; `mode: 'install'` writes the qualified complete BIN. With `image.source`, supplied `data` must also be the complete BIN; old application-only metadata keeps its existing raw-app `data` semantics. Manifests are bounded at 4 MiB, firmware downloads at 256 MiB and their approved exact size. Official manifest/artifact sources are confined to the ESP-VISION CDN root; model URLs use their full source commit and MCP has a version/commit/hash descriptor. No npm, firmware tag or CDN publication is performed by preparing this source version.
+
+To validate before npm publication, check out an exact reviewed commit, run `npm install --ignore-scripts --no-audit --no-fund --package-lock=false` and `npm run release:check` in `host/device-core`, then `npm pack --ignore-scripts --pack-destination <project-local-output>`. Install that locally produced tarball or use a source archive pinned to that exact commit. Do not claim that an unpublished 0.4.0 is available in the registry.
+
+### Browser ROM flashing (unreleased)
+
+`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal? })`. Build from this branch until a new SDK release is published; installing 0.3.0 does not enable this API. The constructor is passive, and `initialize()` lazily loads the pinned `tasmota-webserial-esptool` browser backend. Use a browser bundler such as webpack, Vite or esbuild; direct native ESM loading of the upstream backend is not supported. No Python installation or consumer-side tasmota patch is needed. The root and `/node` entry points do not load browser modules.
+
+```js
+import { createDevice } from '@esp-vision/device-core';
+import { openBrowserRom } from '@esp-vision/device-core/browser';
+
+// Request permission directly in the user's click handler (HTTPS or localhost).
+const port = await navigator.serial.requestPort();
+// release comes from firmware.check(), selected for the physical board.
+const result = await createDevice().firmware.update({
+  release, board: release.board, mode: 'update', // Explicit 'install' for complete images.
+  openLoader: ({ signal }) => openBrowserRom({ port, signal, logger: console }),
+  onProgress: percent => updateProgress(percent),
+});
+if (result.needsReset) showManualReset();
+```
+
+Core owns downloads, chip/revision/security and partition/capacity checks, write, full readback and reset. The adapter owns the selected port until Core disconnects it; the UI must first release any runtime serial connection. It starts no stub during construction or chip initialization: Core checks the approved image and ROM security before calling `runStub`. P4 revision 301/302 flash power and S31 support come from pinned upstream 9.4.2; Core retains bounded SLIP-prefix tolerance, native USB stub startup confirmation and size-scaled erase timeouts. Unsupported stubs fail explicitly. Keep the page and port alive until the update Promise settles; cancellation is accepted before writing, never used to interrupt a started write/readback. This ROM adapter does not provide runtime EV-MUX serial transport or Wi-Fi/TCP OTA.
+
 ### Official Node adapters
 
 The Node-only `@esp-vision/device-core/node` subpath exports `tcpTransport({ host, port })` and `serialTransport({ serial, python })`. Constructors are passive; Core opens/closes the link during `connect()`/`disconnect()`. Serial needs pyserial in the selected Python interpreter, and uses role `usj`, `usb` or `uart` for the actual interface. The root/browser entry points do not load Node networking/process modules.
@@ -220,7 +261,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.
 
-**Binary uploads (SDK 0.2.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.
+**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.
 
@@ -343,3 +384,5 @@ TCP needs only Node.js. Serial additionally needs a Python interpreter with the
 ## License
 
 The npm package and ESP-VISION contributions use [Apache-2.0](LICENSE), matching the firmware. [NOTICE](NOTICE) retains the original copyright and MIT permission text for historical and upstream-derived portions. Third-party dependencies retain their own licenses; neither package metadata nor the project license overrides them.
+
+Hash-pinned manifests and complete-BIN sources use the browser HTTP cache (`cache: default`); mutable config and legacy app-only BINs retain `no-store`. A fetch-stage TypeError on a pinned asset gets one `no-store` retry to recover from an older cached response lacking CORS headers. HTTP, body-read, SHA-256 and metadata failures are not retried or downgraded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -10,10 +10,11 @@
     "./session": "./src/device_session.js",
     "./actions": "./src/device_actions.js",
     "./bindings": "./src/device_bindings.js",
-    "./firmware": "./src/firmware_flash.js",
+    "./firmware": "./src/firmware.js",
     "./discovery": "./src/network_discovery.js",
     "./discovery/node": "./src/network_discovery_node.js",
-    "./node": "./src/node_transport.js"
+    "./node": "./src/node.js",
+    "./browser": "./src/browser.js"
   },
   "files": [
     "src/*.js",
@@ -33,10 +34,11 @@
     "check:schema": "node scripts/generate-action-schema.mjs --check",
     "schema:actions": "node scripts/generate-action-schema.mjs",
     "check:package": "node tests/check-package.mjs",
-    "release:check": "npm test && npm run check:schema && npm run check:package && node scripts/release-npm.mjs --dry-run",
+    "release:check": "npm test && npm run check:schema && npm run check:browser && npm run check:package && node scripts/release-npm.mjs --dry-run",
     "release:npm": "node scripts/release-npm.mjs",
     "prepublishOnly": "npm run release:check",
-    "test:hardware": "node tests/hardware-check.mjs"
+    "test:hardware": "node tests/hardware-check.mjs",
+    "check:browser": "node tests/check-browser.mjs"
   },
   "repository": {
     "type": "git",
@@ -74,6 +76,10 @@
   },
   "dependencies": {
     "smol-toml": "^1.7.0",
-    "string-width": "^7.2.0"
+    "string-width": "^7.2.0",
+    "tasmota-webserial-esptool": "9.4.2"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.12"
   }
 }

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.2.0",
+  "deviceCoreVersion": "0.4.0",
   "schemaVersion": 1,
   "actions": [
     {

package/scripts/verify-registry.mjs

@@ -8,7 +8,7 @@ export async function verifyPublishedIntegrity(url, integrity, {
   wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
   report = message => console.log(message),
 } = {}) {
-  const attempts = 6
+  const attempts = 10
   for (let attempt = 0; attempt < attempts; attempt++) {
     let response, transient
     try {
@@ -29,7 +29,7 @@ export async function verifyPublishedIntegrity(url, integrity, {
       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 = 1000 * 2 ** attempt
+    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/browser.js

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/** Passive browser ROM adapter. Request the SerialPort in the UI's click handler. */
+export function openBrowserRom({ port, logger = {}, signal } = {}) {
+  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')
+  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' })
+  const check = () => { if (closing) throw closed(); if (signal?.aborted) throw cancelled() }
+  const disconnect = () => {
+    closing = true
+    // Opening may still be in flight. initialize closes again after acquiring it.
+    if (!raw) return Promise.resolve()
+    return cleanup ??= raw.disconnect()
+  }
+  const ready = () => {
+    if (closing || !raw) throw closed()
+    return raw
+  }
+  const adapter = {
+    get chipName() { return raw?.chipName ?? null },
+    get chipFamily() { return raw?.chipFamily ?? null },
+    get chipRevision() { return raw?.chipRevision ?? null },
+    initialize() {
+      if (closing) return Promise.reject(closed())
+      if (initialized) return initialized
+      initialized = (async () => {
+        check()
+        const { createBrowserLoader } = await import('./browser_rom.js')
+        check()
+        let rejectAbort
+        const aborted = new Promise((_, reject) => { rejectAbort = reject })
+        const abort = () => { rejectAbort(cancelled()); void disconnect().catch(() => {}) }
+        signal?.addEventListener('abort', abort, { once: true })
+        const opening = (async () => {
+          raw = await createBrowserLoader(port, {
+            log: (...args) => logger.log?.(...args),
+            error: (...args) => logger.error?.(...args),
+            debug: (...args) => logger.debug?.(...args),
+          })
+          if (closing || signal?.aborted) { await disconnect(); check() }
+          await raw.initialize()
+          check()
+        })()
+        try {
+          if (signal?.aborted) abort()
+          await Promise.race([opening, aborted])
+        } catch (error) { await disconnect().catch(() => {}); throw error }
+        finally { signal?.removeEventListener('abort', abort) }
+      })()
+      return initialized
+    },
+    getSecurityInfo: () => ready().getSecurityInfo(),
+    runStub: skip => ready().runStub(skip),
+    hardReset: () => ready().hardReset(),
+    disconnect,
+  }
+  return adapter
+}

package/src/browser_rom.js

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+// Loaded only by openBrowserRom.initialize(), never by the root/Node entry point.
+import { connectWithPort } from 'tasmota-webserial-esptool'
+import { browserRomCompatibility } from './browser_rom_compat.js'
+
+export async function createBrowserLoader(port, logger) {
+  return browserRomCompatibility(await connectWithPort(port, logger))
+}

package/src/browser_rom_compat.js

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+// Compatibility for pinned tasmota-webserial-esptool 9.4.2. Keep changes per
+// instance: consumers need neither package-manager patches nor global prototypes.
+export function browserRomCompatibility(loader) {
+  const readPacket = loader.readPacket
+  loader.readPacket = async function (timeout) {
+    const deadline = Date.now() + timeout
+    for (;;) {
+      try { return await readPacket.call(this, Math.max(1, deadline - Date.now())) }
+      catch (error) {
+        // Only a byte before the SLIP header is safe to discard. Preserve invalid
+        // escapes, mid-packet errors, I/O failures and the overall timeout.
+        if (!/^Invalid head of packet \(/.test(error.message) || Date.now() >= deadline) throw error
+      }
+    }
+  }
+  const runStub = loader.runStub
+  loader.runStub = async function (skipFlashDetection = false) {
+    const memFinish = this.memFinish, packet = this.readPacket
+    const nativeUsb = this.isUsbJtagOrOtg === true
+    if (nativeUsb) {
+      // USB can reset before ROM sends MEM_END's reply. Do not claim success:
+      // upstream must still receive and validate OHAI from the running stub.
+      this.memFinish = async (...args) => {
+        try { return await memFinish.apply(this, args) }
+        catch (error) {
+          if (!/timed?\s*out|timeout/i.test(error.message)) throw error
+        }
+      }
+      this.readPacket = timeout => packet.call(this, Math.max(timeout, 5000))
+    }
+    try {
+      const stub = await runStub.call(this, skipFlashDetection)
+      if (!stub.IS_STUB) throw new Error('This device has no supported browser flash stub')
+      browserStubCompatibility(stub)
+      return stub
+    } finally { this.memFinish = memFinish; this.readPacket = packet }
+  }
+  return loader
+}
+
+function browserStubCompatibility(stub) {
+  // Official esp-flasher-stub erases the entire region in FLASH_BEGIN. Its erase
+  // duration must scale with image size rather than the short command timeout.
+  const command = stub.checkCommand
+  stub.checkCommand = function (opcode, buffer, checksum, timeout) {
+    if (opcode === 0x02 && buffer?.length >= 4) {
+      const size = (buffer[0] | buffer[1] << 8 | buffer[2] << 16 | buffer[3] << 24) >>> 0
+      timeout = Math.max(timeout ?? 0, 3000, 30000 * size / 1000000)
+    }
+    return command.call(this, opcode, buffer, checksum, timeout)
+  }
+  // Stub commands use their own loader instance and inherit the same SLIP issue.
+  const readPacket = stub.readPacket
+  stub.readPacket = async function (timeout) {
+    const deadline = Date.now() + timeout
+    for (;;) {
+      try { return await readPacket.call(this, Math.max(1, deadline - Date.now())) }
+      catch (error) {
+        if (!/^Invalid head of packet \(/.test(error.message) || Date.now() >= deadline) throw error
+      }
+    }
+  }
+}

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/firmware.js

@@ -0,0 +1,4 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+export * from './firmware_flash.js'
+export { loadOfficialFirmware, loadReleaseManifest } from './firmware_feed.js'

package/src/firmware_feed.js

@@ -1,7 +1,11 @@
 // SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
 // SPDX-License-Identifier: Apache-2.0
-const base = 'https://dl.espressif.com/AE/esp-vision/'
-export async function loadOfficialFirmware({ board, fetch: fetcher = globalThis.fetch, signal } = {}) {
+import { firmwareSha256 } from './firmware_flash.js'
+import { validateFirmwareRelease } from './firmware_release.js'
+import { OFFICIAL_ROOT as base, MAX_MANIFEST_BYTES, MAX_FIRMWARE_BYTES, SHA256, SOURCE_COMMIT, firmwareUrl, downloadBytes } from './firmware_io.js'
+export async function loadOfficialFirmware({ board, version, fetch: fetcher = globalThis.fetch, signal } = {}) {
+  if (board !== undefined && !validName(board, 96)) throw new TypeError('board must be a non-empty board string')
+  if (version !== undefined && !validName(version)) throw new TypeError('version must be a non-empty firmware version string')
   const { parse } = await import('smol-toml')
   const get = async (url, optional = false) => {
     signal?.throwIfAborted()
@@ -11,10 +15,23 @@ export async function loadOfficialFirmware({ board, fetch: fetcher = globalThis.
     return response
   }
   const config = parse(await (await get(base + 'config.toml')).text())
+  if (Object.hasOwn(config, 'publication')) {
+    const publication = validatePublication(config.publication)
+    const selected = publication.releases.find(entry => entry.version === (version ?? publication.version))
+    if (!selected || (board && !selected.boards.includes(board))) throw unavailable()
+    const manifest = await loadReleaseManifest({
+      url: selected.manifestUrl, sha256: selected.manifestSha256,
+      version: selected.version, boards: selected.boards, sourceCommit: selected.version === publication.version ? publication.sourceCommit : undefined,
+      fetch: fetcher, signal,
+    })
+    return { ...manifest, releases: manifest.releases.filter(entry => !board || entry.board === board), publication }
+  }
   const app = config['esp-vision'], web = config.website
   if (!app?.image || !Array.isArray(web?.releases) || typeof web.binaryNameTemplate !== 'string') throw new TypeError('Invalid official firmware index')
   const boards = Object.keys(app.image).filter(name => !board || name === board)
-  const versions = [...new Set([web.release, ...web.releases].filter(value => typeof value === 'string' && value))]
+  const knownVersions = [...new Set([web.release, ...web.releases].filter(value => typeof value === 'string' && value))]
+  if (version !== undefined && !knownVersions.includes(version)) throw unavailable()
+  const versions = version === undefined ? knownVersions : [version]
   if (versions.length > 256 || boards.length > 64) throw new RangeError('Official firmware index exceeds limits')
   const releases = []
   // Sequential metadata requests keep the official server load bounded.
@@ -23,6 +40,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)
@@ -33,3 +51,99 @@ export async function loadOfficialFirmware({ board, fetch: fetcher = globalThis.
   }
   return { schemaVersion: 1, releases }
 }
+
+function validName(value, max = 255) { return typeof value === 'string' && value.length > 0 && value.length <= max && value.trim() === value }
+function unavailable() { return Object.assign(new Error('Requested firmware version is unavailable'), { code: 'FIRMWARE_VERSION_UNAVAILABLE' }) }
+function descriptor(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || !validName(value.version) || !SHA256.test(value.manifestSha256 ?? '')
+      || !Array.isArray(value.boards) || !value.boards.length || value.boards.length > 64
+      || value.boards.some(board => !validName(board, 96)) || new Set(value.boards).size !== value.boards.length) throw new TypeError('Invalid publication manifest reference')
+  firmwareUrl(value.manifestUrl, { official: true })
+}
+function validatePublication(value) {
+  if (!value || value.schemaVersion !== 1 || !SOURCE_COMMIT.test(value.sourceCommit ?? '')
+      || !Array.isArray(value.releases) || !value.releases.length || value.releases.length > 256) throw new TypeError('Invalid official publication index')
+  if (!validName(value.version) || !SHA256.test(value.manifestSha256 ?? '')) throw new TypeError('Invalid publication current manifest reference')
+  firmwareUrl(value.manifestUrl, { official: true })
+  const seen = new Set()
+  for (const item of value.releases) {
+    descriptor(item)
+    if (seen.has(item.version)) throw new TypeError('Duplicate publication version')
+    seen.add(item.version)
+  }
+  const current = value.releases.find(item => item.version === value.version)
+  if (!current || current.manifestUrl !== value.manifestUrl || current.manifestSha256 !== value.manifestSha256) throw new TypeError('Publication current manifest reference differs from its history')
+  return structuredClone(value)
+}
+function validateWebsite(website, version, sourceCommit) {
+  if (!website || typeof website !== 'object' || Array.isArray(website)
+      || typeof website.schemaVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(website.schemaVersion)
+      || website.release !== version || !Array.isArray(website.releases) || website.releases.length > 256
+      || !website.releases.includes(version) || website.releases.some(item => !validName(item))
+      || typeof website.binaryNameTemplate !== 'string' || website.binaryNameTemplate.length > 255
+      || !website.binaryNameTemplate.includes('{board}') || !website.binaryNameTemplate.includes('{tag}')
+      || !Array.isArray(website.boards) || website.boards.length > 64
+      || !Array.isArray(website.models) || website.models.length > 256) throw new TypeError('Invalid release manifest website snapshot')
+  const boards = new Set(), models = new Set()
+  for (const board of website.boards) {
+    if (!board || !validName(board.board, 96) || !validName(board.slug, 96) || !validName(board.name)
+        || typeof board.flashable !== 'boolean' || boards.has(board.board)) throw new TypeError('Invalid or duplicate manifest website board')
+    if (board.docsUrl !== undefined) firmwareUrl(board.docsUrl)
+    boards.add(board.board)
+  }
+  for (const model of website.models) {
+    if (!model || !validName(model.slug, 96) || models.has(model.path)
+        || !Number.isSafeInteger(model.sizeBytes) || model.sizeBytes <= 0 || model.sizeBytes > MAX_FIRMWARE_BYTES
+        || typeof model.path !== 'string' || !model.path.startsWith('models/') || model.path.length > 512
+        || model.path.split('/').some(part => !part || part === '.' || part === '..')
+        || model.downloadUrl !== `https://raw.githubusercontent.com/espressif/esp-vision/${sourceCommit}/${model.path}`) throw new TypeError('Invalid manifest model or unpinned model URL')
+    const modelUrl = firmwareUrl(model.downloadUrl)
+    if (modelUrl.search || !modelUrl.pathname.startsWith(`/espressif/esp-vision/${sourceCommit}/models/`)
+        || /%2f|%5c|%2e/i.test(modelUrl.pathname)) throw new TypeError('Invalid manifest model path or source commit boundary')
+    models.add(model.path)
+  }
+}
+function validateManifest(value, { version, sourceCommit, boards } = {}) {
+  if (!value || value.schemaVersion !== 1 || !validName(value.version)
+      || !['legacy', 'single-bin'].includes(value.layout)
+      || !SOURCE_COMMIT.test(value.sourceCommit ?? '') || !Number.isSafeInteger(value.pipelineId) || value.pipelineId <= 0
+      || (version !== undefined && value.version !== version) || (sourceCommit !== undefined && value.sourceCommit !== sourceCommit)
+      || !Array.isArray(value.releases) || !value.releases.length || value.releases.length > 64) throw new TypeError('Invalid release manifest identity or bounds')
+  const seen = new Set()
+  for (const entry of value.releases) {
+    validateFirmwareRelease(entry)
+    if (entry.image.bytes > MAX_FIRMWARE_BYTES || (entry.install && entry.install.bytes > MAX_FIRMWARE_BYTES)) throw new RangeError('Manifest firmware image exceeds byte limit')
+    if (entry.version !== value.version || (entry.sourceCommit !== undefined && entry.sourceCommit !== value.sourceCommit) || seen.has(entry.board)) throw new TypeError('Release manifest board/version mismatch or duplicate board')
+    seen.add(entry.board)
+    if ((value.layout === 'single-bin') !== (entry.image.source !== undefined)) throw new TypeError('Release manifest BIN layout/source mismatch')
+    firmwareUrl(entry.image.url, { official: true })
+    if (entry.image.source) firmwareUrl(entry.image.source.url, { official: true })
+    if (entry.install) { validateFirmwareRelease(entry, 'install'); firmwareUrl(entry.install.url, { official: true }) }
+  }
+  if (boards !== undefined && (boards.length !== seen.size || boards.some(board => !seen.has(board)))) throw new TypeError('Release manifest board set differs from publication reference')
+  validateWebsite(value.website, value.version, value.sourceCommit)
+  if (value.website.boards.some(board => board.flashable && !seen.has(board.board))) throw new TypeError('Manifest website advertises an unqualified board')
+  if (value.mcp !== undefined && value.mcp !== null) {
+    const mcp = value.mcp
+    if (!mcp || typeof mcp !== 'object' || Array.isArray(mcp)
+        || !Number.isSafeInteger(mcp.bytes) || mcp.bytes <= 0 || mcp.bytes > 16 * 1024 * 1024
+        || !SHA256.test(mcp.sha256 ?? '') || mcp.version !== value.version || mcp.sourceCommit !== value.sourceCommit) throw new TypeError('Invalid release manifest MCP descriptor')
+    firmwareUrl(mcp.url, { official: true })
+    const mcpPath = new URL(mcp.url).pathname
+    if (!mcpPath.startsWith('/AE/esp-vision/bin/mcp/') || decodeURIComponent(mcpPath.slice(mcpPath.lastIndexOf('/') + 1)) !== `mcp-pack-${value.version}.json`) throw new TypeError('Invalid release manifest MCP source')
+  }
+  return value
+}
+
+/** Read exactly one immutable official release snapshot, verified over raw bytes. */
+export async function loadReleaseManifest({ url, sha256, version, sourceCommit, boards, fetch: fetcher = globalThis.fetch, signal } = {}) {
+  if (!SHA256.test(sha256 ?? '') || (version !== undefined && !validName(version))
+      || (sourceCommit !== undefined && !SOURCE_COMMIT.test(sourceCommit))
+      || (boards !== undefined && (!Array.isArray(boards) || !boards.length || boards.length > 64 || boards.some(board => !validName(board, 96)) || new Set(boards).size !== boards.length))) throw new TypeError('Manifest requires a qualified SHA-256, version and source commit')
+  const bytes = await downloadBytes(url, { fetch: fetcher, signal, maxBytes: MAX_MANIFEST_BYTES, official: true, immutable: true })
+  if (await firmwareSha256(bytes) !== sha256) throw new Error('Release manifest SHA-256 does not match publication')
+  signal?.throwIfAborted()
+  const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+  return validateManifest(value, { version, sourceCommit, boards })
+}