@esp-vision/device-core 0.3.0 → 0.4.0

package/src/firmware_updates.js

@@ -3,6 +3,8 @@
  */
 import { loadOfficialFirmware } from './firmware_feed.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,38 +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, 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
-    }
-  }
-  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')
@@ -64,7 +35,7 @@ export async function checkFirmware(request = {}, connectedIdentity) {
   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.
@@ -88,15 +59,25 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   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 mode = firmwareMode(request.mode)
   const target = release(request.release, mode)
-  const image = mode === 'install' ? {
+  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,
-  } : target.image
+  } : 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(image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  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.

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 { 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');

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

package/tests/test-firmware-source.mjs

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware.js'
+
+async function fixture() {
+  const full = new Uint8Array(0x11000).fill(0xff), appOffset = 0x10000, appLength = 4, calls = []
+  full.set([0xe9, 1, 2, 3], 0x2000); full.set([0xaa, 0x50, 4, 5], 0x8000); full.set([0xe9, 6, 7, 8], appOffset)
+  const segment = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(full.subarray(offset, offset + 4)) })
+  const source = { url: 'https://example.test/full.bin', bytes: full.length, sha256: await firmwareSha256(full), offset: appOffset }
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await segment(appOffset)), partitionSize: 4096,
+    partitionTable: await segment(0x8000), url: source.url, source,
+  }, install: { url: source.url, offset: 0, bytes: full.length, sha256: source.sha256, flashSize: 0x1000000,
+    chipRevisionMin: 302, chipRevisionMax: 302, bootloader: await segment(0x2000) } }
+  const flash = new Uint8Array(full.length).fill(0x5a)
+  flash.set(full.subarray(0x8000, 0x8004), 0x8000)
+  const before = flash.slice()
+  const loader = {
+    chipFamily: 0x3280, chipRevision: 302,
+    async initialize() { calls.push('initialize') },
+    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
+    async runStub() { calls.push('stub'); return loader },
+    async flashId() { return 0x1840ef },
+    async flashData(buffer, progress, offset) { calls.push(['write', offset, buffer.byteLength]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
+    async readFlash(offset, bytes) { return flash.slice(offset, offset + bytes) },
+    async readRegister() { return 0 },
+    async hardReset() { calls.push('reset') },
+    async disconnect() { calls.push('close') },
+  }
+  const request = { release, board: 'BOARD', openLoader: async () => { calls.push('open'); return loader }, fetch: async (url, options) => {
+    calls.push(['download', url]); assert.equal(options.redirect, 'error'); assert.equal(options.headers, undefined)
+    return new Response(full)
+  } }
+  return { device: createDevice(), release, request, full, flash, before, loader, calls, appOffset, appLength }
+}
+test('single BIN update verifies the container then writes only the application, preserving all other bytes', async () => {
+  const f = await fixture()
+  const result = await f.device.firmware.update(f.request)
+  assert.equal(result.verified, true)
+  assert.deepEqual(f.calls.filter(call => Array.isArray(call)), [['download', f.release.image.source.url], ['write', f.appOffset, f.appLength]])
+  assert.deepEqual(f.flash.slice(0, f.appOffset), f.before.slice(0, f.appOffset))
+  assert.deepEqual(f.flash.slice(f.appOffset + f.appLength), f.before.slice(f.appOffset + f.appLength))
+  assert.deepEqual(f.flash.slice(f.appOffset, f.appOffset + f.appLength), f.full.slice(f.appOffset, f.appOffset + f.appLength))
+})
+test('provided data means the complete BIN when image.source exists; application bytes alone are rejected', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full.slice(f.appOffset, f.appOffset + f.appLength) }), /source size/)
+  assert.deepEqual(f.calls, [])
+  assert.equal((await f.device.firmware.update({ ...f.request, data: f.full })).verified, true)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'download'))
+})
+test('old application-only descriptors still download and verify a raw application BIN', async () => {
+  const f = await fixture(); delete f.release.image.source; f.release.image.url = 'https://example.test/app.bin'
+  let downloads = 0
+  const result = await f.device.firmware.update({ ...f.request, fetch: async url => {
+    downloads++; assert.equal(url, f.release.image.url); return new Response(f.full.slice(f.appOffset, f.appOffset + f.appLength))
+  } })
+  assert.equal(result.verified, true); assert.equal(downloads, 1)
+})
+for (const mutation of ['outside-app-corruption', 'source-truncated', 'source-long', 'app-hash', 'source-offset', 'source-bounds', 'source-size-limit', 'source-install-hash', 'source-install-url', 'image-source-url', 'source-http', 'bootloader-descriptor', 'table-descriptor']) {
+  test(`invalid source ${mutation} rejects before any ROM acquisition`, async () => {
+    const f = await fixture(), source = f.release.image.source
+    let bytes = f.full
+    if (mutation === 'outside-app-corruption') bytes[1] ^= 1
+    if (mutation === 'source-truncated') bytes = bytes.slice(0, -1)
+    if (mutation === 'source-long') bytes = new Uint8Array(bytes.length + 1)
+    if (mutation === 'app-hash') f.release.image.sha256 = '0'.repeat(64)
+    if (mutation === 'source-offset') source.offset++
+    if (mutation === 'source-bounds') source.bytes = 1
+    if (mutation === 'source-size-limit') source.bytes = 257 * 1024 * 1024
+    if (mutation === 'source-install-hash') source.sha256 = '0'.repeat(64)
+    if (mutation === 'source-install-url') f.release.install.url = 'https://example.test/other.bin'
+    if (mutation === 'image-source-url') f.release.image.url = 'https://example.test/app.bin'
+    if (mutation === 'bootloader-descriptor') f.release.install.bootloader.sha256 = '0'.repeat(64)
+    if (mutation === 'table-descriptor') f.release.image.partitionTable.sha256 = '0'.repeat(64)
+    if (mutation === 'source-http') source.url = f.release.image.url = f.release.install.url = 'http://example.test/full.bin'
+    await assert.rejects(f.device.firmware.update({ ...f.request, data: bytes }))
+    assert.deepEqual(f.calls, [])
+  })
+}
+test('downloaded full BIN enforces approved length during streaming before opening ROM', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async () => new Response(new Uint8Array(f.full.length + 1)) }), /byte limit/)
+  assert.deepEqual(f.calls, [])
+})
+test('single BIN explicit install writes the complete container without slicing it', async () => {
+  const f = await fixture()
+  assert.equal((await f.device.firmware.update({ ...f.request, data: f.full, mode: 'install' })).verified, true)
+  assert.deepEqual(f.flash, f.full)
+  assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', 0, f.full.length])
+})
+test('single BIN application update still refuses changed partition layouts with no install fallback', async () => {
+  const f = await fixture(); f.flash[0x8000] ^= 1
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full }), /Partition layout/)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.equal(f.calls.at(-1), 'close')
+})
+test('source extraction retains complete application readback verification and does not reset on corruption', async () => {
+  const f = await fixture(), read = f.loader.readFlash
+  f.loader.readFlash = async (offset, count) => offset === 0x8000 ? read(offset, count) : new Uint8Array(count)
+  await assert.rejects(f.device.firmware.update({ ...f.request, data: f.full }), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+
+test('single BIN update and explicit installation reuse hash-pinned browser-cache responses', async () => {
+  for (const mode of ['update', 'install']) {
+    const f = await fixture(), caches = []
+    const result = await f.device.firmware.update({ ...f.request, mode, fetch: async (_url, options) => {
+      caches.push(options.cache)
+      return new Response(f.full)
+    } })
+    assert.equal(result.verified, true)
+    assert.deepEqual(caches, ['default'])
+  }
+})
+test('single BIN cached CORS failure retries once and retains application-only verification', async () => {
+  const f = await fixture(), caches = []
+  const result = await f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache)
+    if (caches.length === 1) throw new TypeError('Cached response lacks CORS permission')
+    return new Response(f.full)
+  } })
+  assert.equal(result.verified, true)
+  assert.deepEqual(caches, ['default', 'no-store'])
+  assert.deepEqual(f.calls.find(call => Array.isArray(call) && call[0] === 'write'), ['write', f.appOffset, f.appLength])
+})
+test('single BIN hash mismatch never retries cache or opens ROM; legacy app BIN stays no-store', async () => {
+  const f = await fixture(), caches = []
+  f.full[0] ^= 1
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache); return new Response(f.full)
+  } }), /SHA-256/)
+  assert.deepEqual(caches, ['default']); assert.deepEqual(f.calls, [])
+  delete f.release.image.source
+  caches.length = 0
+  await assert.rejects(f.device.firmware.update({ ...f.request, fetch: async (_url, options) => {
+    caches.push(options.cache); throw new TypeError('Network failure')
+  } }), /Network failure/)
+  assert.deepEqual(caches, ['no-store']); assert.deepEqual(f.calls, [])
+})