@esp-vision/device-core 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.1 (unreleased)
+
+### Fixed
+
+- Fail camera mode checks on allocation, timeout and unexpected errors instead of silently classifying those modes as unsupported; inspect optional storage state only when advertised.
+- Keep hardware-check fixtures in bounded RAM-only Python calls, independent of filesystem availability. Add expected board/firmware and required-check validation, report storage mount state, and reject explicit file acceptance on unmounted Flash without formatting.
+
+## 0.4.0
+
+### 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

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` 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.
+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.3.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.
@@ -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.3.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
@@ -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.
@@ -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.3.0",
+  "version": "0.4.1",
   "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.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.3.0",
+  "deviceCoreVersion": "0.4.1",
   "schemaVersion": 1,
   "actions": [
     {

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/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.
@@ -34,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 })
+}

package/src/firmware_io.js

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+export const MAX_FIRMWARE_BYTES = 256 * 1024 * 1024
+export const MAX_MANIFEST_BYTES = 4 * 1024 * 1024
+export const OFFICIAL_ROOT = 'https://dl.espressif.com/AE/esp-vision/'
+export const SHA256 = /^[a-f0-9]{64}$/
+export const SOURCE_COMMIT = /^[a-f0-9]{40}$/
+
+export function firmwareUrl(value, { official = false } = {}) {
+  if (typeof value !== 'string') throw new TypeError('Firmware URLs must use HTTPS')
+  let url
+  try { url = new URL(value) } catch { throw new TypeError('Firmware URLs must use HTTPS') }
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash
+      || (official && (!url.href.startsWith(OFFICIAL_ROOT) || url.search || /%2f|%5c|%2e/i.test(url.pathname)))) throw new TypeError('Invalid firmware HTTPS URL or official source')
+  return url
+}
+
+export async function responseBytes(response, { maxBytes, expectedBytes, signal } = {}) {
+  const limit = Math.min(maxBytes, expectedBytes ?? maxBytes)
+  const advertised = response.headers?.get?.('content-length')
+  if (advertised !== null && advertised !== undefined && (!/^\d+$/.test(advertised) || Number(advertised) > limit)) throw new RangeError('Firmware response exceeds approved byte limit')
+  let bytes
+  if (response.body?.getReader) {
+    const reader = response.body.getReader(), chunks = []
+    let length = 0
+    const abort = () => { void reader.cancel().catch(() => {}) }
+    signal?.addEventListener('abort', abort, { once: true })
+    try {
+      for (;;) {
+        signal?.throwIfAborted()
+        const { done, value } = await reader.read()
+        if (done) break
+        length += value.byteLength
+        if (length > limit) throw new RangeError('Firmware response exceeds approved byte limit')
+        chunks.push(value)
+      }
+      bytes = new Uint8Array(length)
+      let offset = 0
+      for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength }
+    } catch (error) { await reader.cancel().catch(() => {}); throw error }
+    finally { signal?.removeEventListener('abort', abort); reader.releaseLock() }
+  } else if (response.arrayBuffer) bytes = new Uint8Array(await response.arrayBuffer())
+  else if (response.text) bytes = new TextEncoder().encode(await response.text())
+  else throw new TypeError('Firmware response must expose bytes')
+  signal?.throwIfAborted()
+  if (bytes.byteLength > limit) throw new RangeError('Firmware response exceeds approved byte limit')
+  if (expectedBytes !== undefined && bytes.byteLength !== expectedBytes) throw new Error('Firmware response size does not match the approved build')
+  return bytes
+}
+
+export async function downloadBytes(url, { fetch: fetcher = globalThis.fetch, signal, maxBytes, expectedBytes, official = false, immutable = false } = {}) {
+  firmwareUrl(url, { official })
+  if (typeof fetcher !== 'function') throw new TypeError('Provide fetch or in-memory firmware bytes')
+  signal?.throwIfAborted()
+  const request = cache => fetcher(url, { signal, cache, redirect: 'error' })
+  let response
+  try { response = await request(immutable ? 'default' : 'no-store') }
+  catch (error) {
+    // An older navigation/download response may be cached without CORS headers.
+    // Retry only a fetch-stage TypeError once, never HTTP, body, hash or metadata
+    // failures. Every successful response still undergoes the same hash checks.
+    if (!immutable || signal?.aborted || error?.name !== 'TypeError') throw error
+    response = await request('no-store')
+  }
+  if (!response.ok) throw Object.assign(new Error(`Firmware download failed: HTTP ${response.status}`), { code: 'FIRMWARE_DOWNLOAD_FAILED' })
+  if (response.url) firmwareUrl(response.url, { official })
+  return responseBytes(response, { maxBytes, expectedBytes, signal })
+}

package/src/firmware_release.js

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { MAX_FIRMWARE_BYTES, firmwareUrl } from './firmware_io.js'
+
+export function validateFirmwareRelease(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
+    ? Number.isSafeInteger(image.chipRevision) && image.chipRevision >= 0
+    : Number.isSafeInteger(image?.chipRevisionMin) && image.chipRevisionMin >= 0
+      && Number.isSafeInteger(image?.chipRevisionMax) && image.chipRevisionMax >= image.chipRevisionMin
+  if (!image || image.evMuxVersion !== 4 || !Number.isSafeInteger(image.chipFamily)
+      || image.chipFamily < 0 || !revisionValid || !Number.isSafeInteger(image.offset) || image.offset < 0
+      || !Number.isSafeInteger(image.bytes) || image.bytes <= 0 || !Number.isSafeInteger(image.partitionSize) || image.bytes > image.partitionSize
+      || !/^[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
+    }
+  }
+  if (image.source !== undefined) {
+    const source = image.source, install = value.install
+    if (!source || typeof source !== 'object' || Array.isArray(source)
+        || !Number.isSafeInteger(source.bytes) || source.bytes <= 0 || source.bytes > MAX_FIRMWARE_BYTES
+        || !Number.isSafeInteger(source.offset) || source.offset < 0 || source.offset !== image.offset
+        || !Number.isSafeInteger(source.offset + image.bytes) || source.offset + image.bytes > source.bytes
+        || !/^[a-f0-9]{64}$/.test(source.sha256 ?? '') || source.url !== image.url
+        || !install || source.url !== install.url || source.bytes !== install.bytes || source.sha256 !== install.sha256) throw new TypeError('Invalid complete BIN source bounds or install consistency')
+    firmwareUrl(source.url)
+    if (mode !== 'install') validateFirmwareRelease(value, 'install')
+  }
+  return structuredClone(value)
+}