@esp-vision/device-core 0.2.0 → 0.4.0

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_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)
+}

package/src/firmware_updates.js

@@ -2,7 +2,9 @@
  * 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'
+import { validateFirmwareRelease as release } from './firmware_release.js'
+import { downloadBytes, MAX_FIRMWARE_BYTES } from './firmware_io.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -16,21 +18,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) {
-  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')
-  return structuredClone(value)
-}
+
 async function download(url, fetcher, signal) {
   if (typeof url !== 'string' || new URL(url).protocol !== 'https:') throw new TypeError('Firmware URLs must use HTTPS')
   if (typeof fetcher !== 'function') throw new TypeError('Provide fetch or an in-memory catalog/image')
@@ -41,12 +29,13 @@ 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)
+  const catalog = request.catalog === undefined ? await loadOfficialFirmware({ board: current.board, version: request.version, fetch: fetcher, signal }) : typeof request.catalog === 'string' ? await (await download(request.catalog, fetcher, signal)).json() : structuredClone(request.catalog)
   abort(signal)
   if (catalog?.schemaVersion !== 1 || !Array.isArray(catalog.releases)) throw new TypeError('Catalog requires schemaVersion 1 and releases ordered newest first')
   // Feed ordering is authoritative: firmware versions may be calendar/git labels.
@@ -56,22 +45,40 @@ 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 installation = target.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,
+  } : null
+  const image = mode === 'install' ? installation : 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 source = mode === 'update' ? image.source : undefined
+  const descriptor = source ?? image
+  let bytes = request.data === undefined
+    ? await downloadBytes(descriptor.url, { fetch: fetcher, signal, maxBytes: MAX_FIRMWARE_BYTES, expectedBytes: descriptor.bytes, immutable: target.image.source !== undefined })
+    : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  if (source) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength !== source.bytes) throw new Error('Complete BIN source size does not match the approved build')
+    await validateFirmwareImage(installation, bytes, { mode: 'install' })
+    bytes = bytes.slice(source.offset, source.offset + image.bytes)
+  }
+  await validateFirmwareImage(image, bytes, { mode })
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.
   await disconnect()
@@ -80,7 +87,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-browser.mjs

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import vm from 'node:vm'
+import { webcrypto } from 'node:crypto'
+import { build } from 'esbuild'
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-browser-'))
+try {
+  // Bundle the actual pinned dependency and its dynamic JSON stubs for browsers.
+  const result = await build({
+    stdin: { contents: `export { createDevice } from './src/index.js'; export { openBrowserRom } from './src/browser.js'; export { loadReleaseManifest } from './src/firmware.js'; export { ESPLoader as TestLoader } from 'tasmota-webserial-esptool'; export { browserRomCompatibility as testCompatibility } from './src/browser_rom_compat.js';`, resolveDir: root },
+    bundle: true, platform: 'browser', format: 'iife', globalName: 'DeviceCore',
+    write: false, metafile: true,
+  })
+  const code = result.outputFiles[0].text
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('tasmota-webserial-esptool/dist/esp_loader.js')))
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32p4.json')))
+  assert.ok(Object.keys(result.metafile.inputs).some(path => path.includes('stubs/esp32s31.json')))
+  assert.ok(!Object.keys(result.metafile.inputs).some(path => /src\/(node|cli)/.test(path)))
+  const context = vm.createContext({ EventTarget, URL, TextDecoder, TextEncoder, Uint8Array, AbortController, setTimeout, clearTimeout, console, crypto: webcrypto, structuredClone })
+  vm.runInContext(code, context)
+  let opens = 0, closes = 0
+  const adapter = context.DeviceCore.openBrowserRom({ port: {
+    async open() { opens++; throw new Error('real dependency reached SerialPort.open') },
+    async close() { closes++ },
+  } })
+  assert.equal(opens, 0, 'import and construction must not open/reset the port')
+  await assert.rejects(adapter.initialize(), /real dependency reached SerialPort.open/)
+  assert.equal(opens, 1)
+  // Run upstream's actual SLIP parser in both CDC and UART modes. A blank board
+  // may emit a boot log before the stub greeting; invalid escapes must still fail.
+  for (const cdc of [false, true]) {
+    const raw = new context.DeviceCore.TestLoader({}, { log() {}, error() {}, debug() {} })
+    context.DeviceCore.testCompatibility(raw)
+    raw._isCDCDevice = cdc
+    raw.__inputBuffer = []
+    raw._inputBuffer.push(71, 97, 114, 0xc0, 79, 72, 65, 73, 0xc0)
+    assert.deepEqual(Array.from(await raw.readPacket(100)), [79, 72, 65, 73])
+    raw._clearInputBuffer()
+    raw._inputBuffer.push(0xc0, 0xdb, 0x47, 0xc0)
+    await assert.rejects(raw.readPacket(100), /Invalid SLIP escape/)
+  }
+  const prototype = context.DeviceCore.TestLoader.prototype
+  const originals = Object.fromEntries(['initialize', 'disconnect', 'getSecurityInfo', 'runStub', 'hardReset'].map(key => [key, prototype[key]]))
+  let initializeCalls = 0, disconnectCalls = 0
+  prototype.disconnect = async function () { disconnectCalls++; await this.port.close() }
+  const fakePort = () => ({
+    async open() { this.readable = {}; this.writable = {} },
+    async close() { this.readable = null; this.writable = null },
+  })
+  try {
+    prototype.initialize = async () => { initializeCalls++ }
+    const controller = new AbortController()
+    const loader = context.DeviceCore.openBrowserRom({ port: fakePort(), signal: controller.signal })
+    const first = loader.initialize()
+    assert.equal(loader.initialize(), first, 'initialize must share one ROM connection')
+    await first
+    controller.abort()
+    assert.equal(disconnectCalls, 0, 'abort after initialization must not interrupt flash/readback')
+    await loader.disconnect(); await loader.disconnect()
+    assert.equal(disconnectCalls, 1)
+    assert.equal(initializeCalls, 1)
+    prototype.initialize = async () => { throw new Error('sync failed') }
+    await assert.rejects(context.DeviceCore.openBrowserRom({ port: fakePort() }).initialize(), /sync failed/)
+    assert.equal(disconnectCalls, 2, 'failed ROM sync must release the acquired port')
+    let finishOpen
+    const waitingPort = fakePort()
+    const open = waitingPort.open
+    waitingPort.open = async function () {
+      await new Promise(resolve => { finishOpen = resolve })
+      await open.call(this)
+    }
+    const cancelled = new AbortController()
+    const late = context.DeviceCore.openBrowserRom({ port: waitingPort, signal: cancelled.signal })
+    const starting = late.initialize()
+    while (!finishOpen) await new Promise(resolve => setTimeout(resolve, 1))
+    cancelled.abort()
+    await assert.rejects(starting, { name: 'AbortError' })
+    finishOpen()
+    await new Promise(resolve => setTimeout(resolve, 5))
+    assert.equal(disconnectCalls, 3, 'an open completing after cancellation must close')
+    assert.equal(waitingPort.readable, null)
+    const data = new Uint8Array([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5])
+    const hash = async bytes => Array.from(new Uint8Array(await webcrypto.subtle.digest('SHA-256', bytes)), byte => byte.toString(16).padStart(2, '0')).join('')
+    const release = { board: 'BOARD', version: 'browser-test', image: {
+      evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302,
+      offset: 65536, bytes: data.byteLength, partitionSize: 4096,
+      sha256: await hash(data), partitionTable: { offset: 32768, bytes: table.byteLength, sha256: await hash(table) },
+    } }
+    let stubs = 0, writes = 0, resets = 0
+    prototype.initialize = async function () { this.chipFamily = 0x3280; this.chipRevision = 302 }
+    prototype.getSecurityInfo = async () => ({ flags: 1, flashCryptCnt: 0 })
+    prototype.runStub = async () => { stubs++; throw new Error('must not launch') }
+    const device = context.DeviceCore.createDevice()
+    const request = {
+      release, board: 'BOARD', data,
+      openLoader: ({ signal }) => context.DeviceCore.openBrowserRom({ port: fakePort(), signal }),
+    }
+    await assert.rejects(device.firmware.update(request), /Secure boot/)
+    assert.equal(stubs, 0, 'ROM security must be checked before the browser launches a stub')
+    await assert.rejects(device.firmware.update({ ...request, data: new Uint8Array(4) }), /SHA-256/)
+    assert.equal(stubs, 0)
+    prototype.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 0 })
+    const writing = new AbortController()
+    prototype.runStub = async () => {
+      stubs++
+      return {
+        IS_STUB: true,
+        async flashData() { writes++; writing.abort() },
+        async readFlash(offset) { return offset === 32768 ? table : data },
+        async readRegister() { return 0 },
+      }
+    }
+    prototype.hardReset = async () => { resets++ }
+    const beforeUpdateCloses = disconnectCalls
+    const updated = await device.firmware.update({ ...request, signal: writing.signal })
+    assert.equal(updated.verified, true)
+    assert.equal(updated.needsReset, false)
+    assert.equal(stubs, 1); assert.equal(writes, 1); assert.equal(resets, 1)
+    assert.equal(disconnectCalls, beforeUpdateCloses + 1, 'write-time abort must preserve complete readback, reset and one cleanup')
+    const manifest = { schemaVersion: 1, version: 'browser-test', sourceCommit: 'a'.repeat(40), pipelineId: 1, layout: 'legacy',
+      releases: [{ ...release, image: { ...release.image, url: 'https://dl.espressif.com/AE/esp-vision/bin/app.bin' } }],
+      website: { schemaVersion: '1.0.0', release: 'browser-test', releases: ['browser-test'], binaryNameTemplate: '{board}-{tag}.bin',
+        boards: [{ board: 'BOARD', name: 'Board', slug: 'board', flashable: true }], models: [] }, mcp: null }
+    const rawManifest = new TextEncoder().encode(JSON.stringify(manifest)), caches = []
+    const snapshot = await context.DeviceCore.loadReleaseManifest({ url: 'https://dl.espressif.com/AE/esp-vision/releases/browser-test/manifest.json', sha256: await hash(rawManifest),
+      async fetch(_url, options) {
+        caches.push(options.cache)
+        if (caches.length === 1) throw new TypeError('Cached response CORS failure from the host realm')
+        return new Response(rawManifest)
+      } })
+    assert.equal(snapshot.version, 'browser-test')
+    assert.deepEqual(caches, ['default', 'no-store'], 'real browser bundle must recover a fetch TypeError from host-provided fetch')
+
+  } finally { Object.assign(prototype, originals) }
+  // Node import must not eagerly resolve tasmota's browser-only, extensionless ESM.
+  const { openBrowserRom } = await import(pathToFileURL(join(root, 'src/browser.js')))
+  assert.equal(typeof openBrowserRom, 'function')
+  const dependency = JSON.parse(await readFile(join(root, 'node_modules/tasmota-webserial-esptool/package.json'), 'utf8'))
+  assert.equal(dependency.version, '9.4.2')
+  const stubsLicense = await readFile(join(root, 'node_modules/tasmota-webserial-esptool/src/stubs/README.md'), 'utf8')
+  assert.match(stubsLicense, /dual licensed.*Apache License Version 2.0 or the MIT license/s)
+  await writeFile(join(temporary, 'browser.js'), code)
+  console.log(JSON.stringify({ browserBundle: true, dependency: dependency.version, bytes: code.length, passiveImports: true, p4AndS31Stubs: true, cleanupAndCancellation: true, coreSafetyChecks: true }))
+} finally { await rm(temporary, { recursive: true, force: true }) }

package/tests/check-package.mjs

@@ -37,8 +37,11 @@ try {
   const api = await import('@esp-vision/device-core');
   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 { FirmwareFlashSession, loadOfficialFirmware, loadReleaseManifest } = await import('@esp-vision/device-core/firmware');
+  if (typeof loadOfficialFirmware !== 'function' || typeof loadReleaseManifest !== 'function') throw new Error('Missing public release manifest readers');
+  const { tcpTransport, serialTransport, openNodeRom } = await import('@esp-vision/device-core/node');
+  const { openBrowserRom } = await import('@esp-vision/device-core/browser');
+  if (typeof openBrowserRom !== 'function' || typeof openBrowserRom({ port: { open() { throw new Error('Not opened'); }, close() {} } }).initialize !== 'function') throw new Error('Missing passive browser ROM adapter');
   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 +52,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-browser-rom.mjs

@@ -0,0 +1,85 @@
+// 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 { openBrowserRom } from '../src/browser.js'
+import { browserRomCompatibility } from '../src/browser_rom_compat.js'
+
+const port = () => ({ open() { throw new Error('Port must remain passive') }, close() {} })
+test('browser ROM construction and disconnect are passive without browser globals', async () => {
+  const adapter = openBrowserRom({ port: port() })
+  assert.equal(adapter.chipFamily, null)
+  assert.equal(adapter.chipRevision, null)
+  assert.equal(adapter.chipName, null)
+  await adapter.disconnect(); await adapter.disconnect()
+  await assert.rejects(adapter.initialize(), { code: 'ROM_CLOSED' })
+})
+test('browser ROM validates its port and cancellation before loading the browser dependency', async () => {
+  assert.throws(() => openBrowserRom(), /SerialPort/)
+  assert.throws(() => openBrowserRom({ port: port(), signal: {} }), /AbortSignal/)
+  const controller = new AbortController()
+  controller.abort(new Error('cancelled before open'))
+  await assert.rejects(openBrowserRom({ port: port(), signal: controller.signal }).initialize(), /cancelled before open/)
+})
+test('SLIP prefix compatibility retries only pre-header bytes within the original deadline', async () => {
+  let count = 0
+  const loader = browserRomCompatibility({ async readPacket() {
+    if (++count < 3) throw new Error('Invalid head of packet (0x47)')
+    return [79, 72, 65, 73]
+  } })
+  assert.deepEqual(await loader.readPacket(100), [79, 72, 65, 73])
+  loader.readPacket = browserRomCompatibility({ readPacket: async () => { throw new Error('Invalid SLIP escape (0xdb, 0x47)') } }).readPacket
+  await assert.rejects(loader.readPacket(100), /Invalid SLIP escape/)
+})
+test('SLIP log noise cannot extend the operation deadline indefinitely', async () => {
+  let count = 0
+  const loader = browserRomCompatibility({ async readPacket() {
+    count++
+    await new Promise(resolve => setTimeout(resolve, 5))
+    throw new Error('Invalid head of packet (0x47)')
+  } })
+  await assert.rejects(loader.readPacket(15), /Invalid head/)
+  assert.ok(count <= 4)
+})
+function stubFixture({ native = true, error = 'Timed out waiting for packet header', handshake = true } = {}) {
+  let timeout, reads = 0
+  const stub = { IS_STUB: true, readPacket: async () => [], checkCommand: (...args) => { timeout = args[3] } }
+  const raw = {
+    isUsbJtagOrOtg: native,
+    memFinish: async () => { if (error) throw new Error(error) },
+    readPacket: async () => { reads++; return handshake ? [79, 72, 65, 73] : [] },
+    async runStub(skip) {
+      assert.equal(skip, true)
+      await this.memFinish()
+      assert.deepEqual(await this.readPacket(2500), [79, 72, 65, 73], 'OHAI required')
+      return stub
+    },
+  }
+  return { loader: browserRomCompatibility(raw), stub, timeout: () => timeout, reads: () => reads }
+}
+test('native USB may miss MEM_END acknowledgement but still requires OHAI', async () => {
+  const fixture = stubFixture()
+  assert.equal(await fixture.loader.runStub(true), fixture.stub)
+  assert.equal(fixture.reads(), 1)
+  await assert.rejects(stubFixture({ handshake: false }).loader.runStub(true), /OHAI required/)
+})
+test('UART timeouts and native USB non-timeout errors retain their failures', async () => {
+  await assert.rejects(stubFixture({ native: false }).loader.runStub(true), /Timed out/)
+  await assert.rejects(stubFixture({ error: 'Port disconnected' }).loader.runStub(true), /Port disconnected/)
+})
+test('stub launch restores temporary hooks on failure and rejects ROM fallback', async () => {
+  const fixture = stubFixture({ handshake: false })
+  const finish = fixture.loader.memFinish, packet = fixture.loader.readPacket
+  await assert.rejects(fixture.loader.runStub(true))
+  assert.equal(fixture.loader.memFinish, finish)
+  assert.equal(fixture.loader.readPacket, packet)
+  await assert.rejects(browserRomCompatibility({ runStub: async () => ({ IS_STUB: false }) }).runStub(true), /no supported browser flash stub/)
+})
+test('stub FLASH_BEGIN timeout scales with uncompressed erase size and preserves other commands', async () => {
+  const fixture = stubFixture()
+  const stub = await fixture.loader.runStub(true)
+  await stub.checkCommand(2, [0, 0, 128, 0], 0, 3000)
+  assert.ok(fixture.timeout() > 240000)
+  await stub.checkCommand(3, [], 0, 1234)
+  assert.equal(fixture.timeout(), 1234)
+})