@esp-vision/device-core 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- Negotiate runtime UART speed through the shared session, trying 2,000,000 → 1,500,000 → 921,600 → 460,800 → 115,200 bps until the first verified result; preserve legacy firmware and native USB behavior.
+- Expose a shared browser serial transport with safe internal reopen and preserve subscriptions; support live Node serial retuning through a binary-safe adapter control channel.
+- Require the firmware's versioned `debug.capture_frame.observed.v1` capability for camera observation. Camera capture observes the last successfully published independent camera frame; older unsafe implementations reject locally with `UNSUPPORTED_OPERATION` and a firmware-upgrade message, without issuing a capture RPC. Screen capture remains independent.
+
+### Changed
+
+- Declare this release as a minor version after 0.5.1. Device Core, CLI and Plugin retain independent publication lifecycles; a new Core release does not update existing CLI/Plugin bundles or authorize changing their registry locks.
+
+### Fixed
+
+- Rebind an explicitly selected native USB runtime to its matching ROM only after EV-MUX MAC/interface verification and one bootloader request. Wait for path readiness, preserve uncertain control/cleanup outcomes, and verify the actual ROM MAC before accepting writes; never replay initialization on the same loader.
+- Serialize bootloader handoff with session cleanup, drain Node serial output before closing its bridge, and discard obsolete leases without claiming an unobserved ROM acknowledgement. Preserve bounded ROM method/error details in CLI JSON diagnostics.
+- Identify existing ROM/stub connections without reset before a bounded reset fallback on descriptor-qualified UART bridges or USB Serial/JTAG; suppress reset fallback on native/unknown USB and close failed handles.
+
+- Validate binary capture and preview JPEG structure, table references, dimensions, scans and final EOI before delivery, after existing CRC and response correlation checks. Reject malformed or JPEG-less capture success with `INVALID_IMAGE`; drop invalid previews with diagnostics and counters, while preserving unrelated requests and recovery on the next good frame. This is bounded structural validation, without entropy decoding.
+- Return each `frame.capture` action's correlated image so concurrent, out-of-order responses cannot exchange images through shared state. Use self-created, independently decoded JPEG fixtures in source and installed-package regressions.
+- Replace the browser flashing backend with pinned official esptool-js, compressed writes, qualified pre-write speed fallback, direct USB-OTG ROM synchronization and bounded readback with validated trailing MD5 plus full SHA-256 verification.
+- Normalize signed SPI register responses to 24-bit JEDEC flash IDs and preserve chip/security, installation bounds, partition-layout and reset checks.
+
+- Invalidate the old lease after acknowledged or uncertain hard reset, block concurrent renegotiation, and serialize cleanup with reset so stale release failures cannot mask its result. Retain live leases after confirmed reset denials and discard explicit ownership rejections.
+
 ## 0.5.1
 
 ### Fixed

package/NOTICE

@@ -30,3 +30,11 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+Browser ROM flashing uses the separately installed esptool-js 0.7.1 package,
+Copyright (c) 2023 Espressif Systems (Shanghai) Co. Ltd., Apache License 2.0.
+The package's esp-flasher-stub v1.2.2 set-2 binaries retain their upstream
+dual Apache-2.0/MIT terms. Its pako (MIT/Zlib) and atob-lite (MIT) dependencies
+retain their own notices. No upstream source or stub binary is vendored here.
+The S31 native-USB watchdog reset adapter uses the register sequence also
+implemented by Apache-2.0 esptool-js P4 watchdog support.

package/README.md

@@ -19,12 +19,15 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The **0.5.x** package line is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Pin the exact package version and verify it exists in the public registry before installing. For unpublished source changes, 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.
+This source targets **0.6.0**, a minor release after 0.5.1. The **0.6.x** package line is SDK-only: the management CLI lives in `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Declare a minor-locked dependency and use a lockfile to record the resolved patch and integrity; verify the chosen version exists in the public registry before installing. For unpublished source changes, 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.5.1 --registry=https://registry.npmjs.org/
+npm view @esp-vision/device-core@0.6.0 version dist.integrity
+npm install '@esp-vision/device-core@~0.6.0' --registry=https://registry.npmjs.org/
 ```
 
+A source version, dry run or open merge request does not publish a package. CLI and Plugin bundles keep their own versions and embedded Core bytes; publishing Core alone does not update those installed tools.
+
 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.
 
 ## Documentation
@@ -112,6 +115,10 @@ try {
 
 `connect()` sends Ctrl-C and a short REPL liveness probe by default for compatibility. Pass `probeRepl: false` when a detached application may be running: Core still acquires the EV-MUX session and reads identity/capabilities, but leaves the REPL untouched. In this mode a reported `vmReady: false` stays false; Python operations that require a ready VM fail with a readiness error.
 
+UART connections start at 115200 bps. With compatible firmware and a transport exposing `setBaudRate(baudRate, { signal })`, Core tests 2000000, 1500000, 921600, 460800 and 115200 bps in order and stops at the first verified rate. `connect({ autoBaud: false })` skips this optional negotiation for bounded identity-only probes; `autoBaud` defaults to `true`. Native USB and legacy firmware skip UART negotiation. The connection deadline defaults to 60000 ms to allow bounded fallback. Runtime speeds and ROM/stub flashing speeds are negotiated independently.
+
+The browser subpath exports a passive `serialTransport({ port, signals?, bufferSize? })` adapter. Request and authorize the selected `SerialPort` in the UI click handler, then pass it to this adapter. Core manages opening, internal retuning and closing; internal reopen preserves subscriptions and permission. The default stream buffer is 256 KiB. An unexpected board reset still requires protocol recovery; reopening a port alone does not establish a session.
+
 ### Immutable release snapshots and a single firmware BIN
 
 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.
@@ -134,7 +141,13 @@ To validate before npm publication, check out an exact reviewed commit, run `npm
 
 ### Browser ROM flashing
 
-`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal? })`. 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.
+`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal?, interface?, baudRate?, onStatus? })`. Construction is passive; `initialize()` lazily loads the official `esptool-js@0.7.1` backend and synchronizes at 115200. Use a browser bundler such as webpack, Vite or esbuild to include the chip stubs. The root and `/node` entry points do not load browser modules. No Python installation or consumer-side dependency patch is needed.
+
+`interface` accepts `auto` (default), `uart`, `usb-otg` and `usb-jtag`. Auto detection distinguishes known USB-UART bridge descriptors from Espressif OTG and Serial/JTAG; ambiguous custom descriptors stay conservative and can be identified explicitly. A ready OTG ROM is synchronized without toggling DTR/RTS. A detached or re-enumerated device requires selecting its current download port again; the SDK never treats a stale port object as a recovered session.
+
+For UART, `baudRate: 'auto'` (default) tests **2000000 → 1500000 → 921600 → 460800 → 115200** after validating ROM security and starting the stub, then stops at the first speed that passes register and digest-checked read-only traffic. A numeric value from this list tests only that speed. A failed prewrite candidate resets, synchronizes at 115200, rechecks chip identity/security and reloads the stub before the next candidate. Native USB skips UART speed negotiation; the adapter's `baudRate` is `null` there. `onStatus(event)` reports ROM connection, speed testing/failure/selection, detected flash ID and compressed writing. Firmware writes are compressed and retain the complete SHA-256 readback and protected update bounds. Interrupted writes invalidate the session and require a fresh operation; the SDK never blindly resumes a compressed stream.
+
+The bounded readback adapter for upstream issue [esptool-js #273](https://github.com/espressif/esptool-js/issues/273) uses 1 KiB packets, one outstanding packet and a checked trailing MD5 digest. This addresses protocol completeness without claiming a proven cause for the investigated read-after-write timing failures. Remove the adapter only after a pinned upstream replacement passes the same pre-read → complete write → complete readback tests. SHA-256 of the full approved image remains the final verification requirement.
 
 ```js
 import { createDevice } from '@esp-vision/device-core';
@@ -271,7 +284,9 @@ Paths are absolute device paths. `files.list({ path: '/', recursive: false })` r
 
 **Binary uploads (SDK 0.3.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
 
-`capture({ source: 'screen', format: 'jpeg' })` uses the dedicated `debug.capture_screen` RPC to encode the LCD's last submitted RGB565 framebuffer, including the display's scaling and letterboxing. It does not read the panel electronics or capture the camera. Camera capture uses `debug.capture_frame`. Both return binary JPEG responses correlated to the request; optional `quality` is an integer from 1 to 100. Missing firmware capabilities reject with `UNSUPPORTED_OPERATION`; an uninitialized display returns `DISPLAY_NOT_READY`, and a board without an LCD returns `NOT_SUPPORTED`. Preview is a separate real-time stream and may drop frames under congestion.
+`capture({ source: 'screen', format: 'jpeg' })` uses the dedicated `debug.capture_screen` RPC to encode the LCD's last submitted RGB565 framebuffer, including the display's scaling and letterboxing. It does not read the panel electronics or capture the camera. Camera capture uses `debug.capture_frame` only when firmware also advertises `debug.capture_frame.observed.v1`. It observes the independent frame published after the application's last successful camera snapshot; it never initializes the sensor, acquires another physical frame or overwrites an application-held `Image`. Later application processing is not reflected in that independent observation. Missing safety support rejects locally with `UNSUPPORTED_OPERATION` and a firmware-upgrade message, without issuing the older capture RPC. No valid published frame, camera reconfiguration, shutdown or VM reset returns `CAMERA_FRAME_NOT_READY`; an observer allocation failure returns `NO_MEM` while the application snapshot remains successful. Use `connect({ probeRepl: false })` to observe a running application without the default REPL interruption. Both return binary JPEG responses correlated to the request; optional `quality` is an integer from 1 to 100. Missing firmware capabilities reject with `UNSUPPORTED_OPERATION`; an uninitialized display returns `DISPLAY_NOT_READY`, and a board without an LCD returns `NOT_SUPPORTED`. Preview is a separate real-time stream and may drop frames under congestion.
+
+Capture and preview delivery require a binary, self-contained 8-bit Huffman JPEG (SOF0/1/2). After EV-MUX length/CRC and session correlation checks, Core checks marker and segment bounds, quantization and Huffman table structure/references, SOF dimensions against metadata, scan component coverage, nonempty scan/restart segments and a final EOI with no trailing bytes. This is structural validation without entropy decoding; it does not establish that every compressed coefficient can be decoded. Invalid capture responses reject immediately with `INVALID_IMAGE`; explicit firmware errors retain their original codes. Invalid preview frames are discarded before any image callback. Both emit a diagnostic `{ event: 'image.invalid', channel, method, seq, code: 'INVALID_IMAGE', reason }`; the parser's `invalidImageFrames` and `droppedFrames` counters increase. A stale response is filtered before validation and cannot reject another request.
 
 ## Discovery and transport adapters
 
@@ -331,7 +346,9 @@ IDE and Agent adapters that construct sessions or call `session.repl` must migra
 
 ## Firmware flashing
 
-ROM flashing remains a separate lifecycle under `@esp-vision/device-core/firmware`. Hosts inject the ROM loader, approved image manifest and reset policy. The adapter validates image integrity, chip/revision, security and partitions, verifies complete readback, and clears the P4 download latch before reset. It does not distribute firmware, open a browser picker or provide a flashing UI. EV-MUX `control({ action: 'bootloader' })` only requests entry into the downloader; it does not flash an image.
+ROM flashing remains a separate lifecycle under `@esp-vision/device-core/firmware`. Hosts inject the ROM loader, approved image manifest and reset policy. The adapter validates image integrity, chip/revision, security and partitions, verifies complete readback, and clears the P4 download latch before reset. It does not distribute firmware, open a browser picker or provide a flashing UI. EV-MUX `control({ action: 'bootloader' })` only requests entry into the downloader; it does not flash an image. Its framed REPL path has no device acknowledgement: `{ acknowledged: false, outcome: 'unknown' }` reports submission, and the next ROM connection must identify the chip before any write. Core invalidates the old EV-MUX lease after submitting a reset command or when that write has an uncertain outcome; disconnect does not send a stale `session.release`. A failure before the reset command is attempted retains the live lease for ordinary cleanup. The Node serial bridge drains its queued output before returning from a successful reset submission.
+
+The Node loader resolves only the explicitly selected serial path and waits briefly for that path to become available. A selected ESP-VISION native USB runtime (`303a:4003`, or UVC composite `303a:4023`) must establish the active EV-MUX USB owner and match its device ID (or a legacy runtime's short `machine.unique_id()` probe) to its USB MAC serial before Core requests bootloader once. Core then accepts only one ROM interface with the same USB MAC and physical location, and verifies the ROM-reported factory MAC before allowing writes. Existing ROM, UART and USB Serial/JTAG ports are not probed as EV-MUX runtimes. If the first read-only ROM initialization fails before any handoff or write, Core may recover once only after freshly observing that same device back in its runtime and verifying the runtime again. It does not retry writes or repeat an already submitted bootloader request. `loader.usbTransition` records command acknowledgement, observed ROM enumeration and cleanup separately; `loader.port` is the qualified current OS path. Failed or cancelled initialization closes that loader and must not be replayed on the same instance. A missing old by-id path never authorizes guessing a different device.
 
 Agent workflows, MCP tool mappings, model providers and plugin packaging belong to their own integration packages and are not included here.
 
@@ -352,7 +369,7 @@ Device Core is maintained alongside the firmware at `host/device-core` in [espre
 
 Run `npm run release:check` from this directory for unit tests, schema validation, an isolated package install and a publication dry run. SDK-only changes run these Node.js checks without compiling firmware. `ESP_VISION_DEVICE_CORE_ONLY=1` selects SDK checks in an API/web pipeline; `ESP_VISION_BUILD_FIRMWARE=1` requests the final firmware matrix when needed. SDK versions are tracked in `package.json` and npm; do not create SDK Git tags in this firmware repository, because firmware/documentation version discovery uses Git tags. CI defensively excludes accidental `device-core-v*` tags from firmware jobs, but creating these tags is not part of the SDK release workflow.
 
-Only a protected default-branch push (`master` in this firmware repository) with matching SDK changes can publish, using the masked/protected `NPM_PUBLISH_TOKEN`. The account must be `esp-vision` with scope write access. This variable must be configured in the firmware project before its first publication; moving source does not transfer CI credentials. MR, feature-branch, local and SDK-tag runs never publish. The release job verifies registry metadata and integrity: identical content is skipped; different content under an existing version requires a version bump.
+A protected default-branch push (`master` in this firmware repository) with SDK changes automatically publishes a version not yet present in npm, using the masked/protected `NPM_PUBLISH_TOKEN`. The account must be `esp-vision` with scope write access. MR, feature-branch, local and SDK-tag runs never publish. An existing version is skipped even if source has changed; bump `package.json` before releasing those changes. Publication verifies newly published registry integrity.
 
 Before enabling this publisher, disable the old IDE-project package release job so there is only one authoritative publisher. Migration is staged: qualify this in-repository SDK and its publication pipeline, publish and verify its registry integrity, then update the IDE/Agent adapters to the fixed package version and remove the old IDE source copy. Until that consumer migration is complete the old worktree is preserved as a backup, not an additional source of future SDK changes. No npm publication is performed by local migration tests.
 
@@ -381,7 +398,7 @@ npm run test:hardware -- --serial /dev/serial/by-id/YOUR_DEVICE --role usj --che
 npm run test:hardware -- --tcp 192.168.1.100 --checks display --display-hold 2 --screen-output screen.jpg
 ```
 
-`--write` explicitly opts into creating a randomly named 1 KiB binary file, verifying every byte by readback, and deleting that file and its temporary upload sibling. Existing matching paths are refused; cleanup failures are reported with the test path and make the command fail. `--capture` opts into a camera JPEG check; `--output` optionally saves that JPEG. SIGINT/SIGTERM cancel the operation; cleanup has a separate bounded deadline. Output excludes network credentials, arbitrary device logs and Python tracebacks. A failing check exits nonzero.
+`--write` explicitly opts into creating a randomly named 1 KiB binary file, verifying every byte by readback, and deleting that file and its temporary upload sibling. Existing matching paths are refused; cleanup failures are reported with the test path and make the command fail. `--capture` explicitly prepares an application snapshot before checking passive camera observation; `--output` optionally saves that JPEG. SIGINT/SIGTERM cancel the operation; cleanup has a separate bounded deadline. Output excludes network credentials, arbitrary device logs and Python tracebacks. A failing check exits nonzero.
 
 `--checks all` runs the shared firmware/SDK hardware suite: `identity`, `memory`, `camera`, `framesizes`, `pixformats`, `orientation`, `ipa_stats`, `snapshot_rate`, `preview`, `image_ops`, `display`, and `display_stream`. Select a comma-separated subset with `--checks memory,camera,preview`. Timing controls are `--frames` (default 30), `--frame-timeout` (seconds, default 25), and `--display-hold` (seconds per backlight state, default zero). Sensor defaults are `--framesize QVGA --pixformat RGB565`; `--quality` defaults to 60. Functional checks default to a 600000 ms overall deadline; an explicit `--timeout` overrides it. Each result is a JSON line with PASS/FAIL/SKIP, measurements and duration, followed by a summary. Unsupported hardware is skipped; IPA absence remains a failure on boards whose camera requires IPA.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -73,9 +73,10 @@
   },
   "dependencies": {
     "smol-toml": "^1.7.0",
-    "tasmota-webserial-esptool": "9.4.2"
+    "esptool-js": "0.7.1"
   },
   "devDependencies": {
     "esbuild": "0.25.12"
-  }
+  },
+  "espVisionReleaseType": "minor"
 }

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

package/scripts/release-npm.mjs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
 // SPDX-License-Identifier: Apache-2.0
 import assert from 'node:assert/strict'
+import { highestStableVersion, validateVersionStep } from './version-policy.mjs'
 import { verifyPublishedIntegrity } from './verify-registry.mjs'
 import { spawnSync } from 'node:child_process'
 import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
@@ -18,6 +19,7 @@ assert.match(manifest.version, /^\d+\.\d+\.\d+$/)
 assert.equal(manifest.publishConfig?.registry, registry)
 assert.equal(manifest.publishConfig?.access, 'public')
 assert.equal(manifest.license, 'Apache-2.0')
+assert.ok(['patch', 'minor', 'major'].includes(manifest.espVisionReleaseType), 'Release type must be patch, minor or major')
 if (!dryRun) {
   assert.equal(process.env.CI_PIPELINE_SOURCE, 'push', 'Publish only from the merged default-branch pipeline')
   assert.ok(process.env.CI_DEFAULT_BRANCH && process.env.CI_COMMIT_BRANCH === process.env.CI_DEFAULT_BRANCH,
@@ -25,6 +27,20 @@ if (!dryRun) {
   assert.equal(process.env.CI_COMMIT_REF_PROTECTED, 'true', 'Publishing requires a protected branch')
   assert.ok(process.env.NPM_PUBLISH_TOKEN, 'Protected NPM_PUBLISH_TOKEN is missing')
 }
+if (!dryRun) {
+  const url = new URL(`${encodeURIComponent(manifest.name)}/${encodeURIComponent(manifest.version)}`, registry)
+  const response = await fetch(url, { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
+  if (response.ok) {
+    console.log(`${manifest.name}@${manifest.version} already exists; no new version to publish.`)
+    process.exit(0)
+  }
+  assert.equal(response.status, 404, 'Registry lookup failed; do not attempt publication')
+  const allResponse = await fetch(new URL(encodeURIComponent(manifest.name), registry), { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
+  assert.equal(allResponse.status, 200, 'Cannot validate prior releases; do not attempt publication')
+  const previous = highestStableVersion(Object.keys((await allResponse.json()).versions ?? {}))
+  assert.ok(previous, 'A prior stable release is required to validate version progression')
+  validateVersionStep(previous, manifest.version, manifest.espVisionReleaseType)
+}
 const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-core-release-'))
 try {
   // Store an environment reference, never the token value, outside the package.

package/scripts/version-policy.mjs

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+
+const stablePattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+const minorPattern = /^~(0|[1-9]\d*)\.(0|[1-9]\d*)\.0$/
+
+export function stableVersion(value) {
+  const match = stablePattern.exec(value ?? '')
+  assert.ok(match, `Expected an exact stable major.minor.patch version: ${value}`)
+  const numbers = match.slice(1).map(Number)
+  assert.ok(numbers.every(Number.isSafeInteger), 'Version components must be safe integers')
+  return numbers
+}
+
+export function minorRange(value) {
+  const match = minorPattern.exec(value ?? '')
+  assert.ok(match, `Expected a minor-locked range such as ~0.5.0: ${value}`)
+  const numbers = match.slice(1).map(Number)
+  assert.ok(numbers.every(Number.isSafeInteger), 'Version components must be safe integers')
+  return numbers
+}
+
+export function inMinorRange(range, version) {
+  const [major, minor] = minorRange(range)
+  const [candidateMajor, candidateMinor] = stableVersion(version)
+  return candidateMajor === major && candidateMinor === minor
+}
+
+// Published older CLI releases may declare an exact Core version; newer
+// releases must declare a minor range, enforced at the CLI publisher.
+export function declaredCoreSupports(declaration, version) {
+  if (typeof declaration !== 'string') return false
+  if (stablePattern.test(declaration)) return declaration === version
+  return inMinorRange(declaration, version)
+}
+
+// The CLI bundles Core. A compatible range describes allowed inputs; the
+// resolved version identifies the actual bytes in a published CLI archive.
+export function cliBundlesCore(manifest, version) {
+  const declaration = manifest.devDependencies?.['@esp-vision/device-core']
+  if (!declaredCoreSupports(declaration, version)) return false
+  const resolved = manifest.espVision?.resolved?.deviceCore
+  if (resolved !== undefined) return resolved === version
+  // Older CLI packages used an exact build dependency as their only record.
+  return stablePattern.test(declaration ?? '') && declaration === version
+}
+
+export function highestStableVersion(versions) {
+  let best
+  for (const candidate of versions) {
+    if (!stablePattern.test(candidate)) continue
+    const parts = stableVersion(candidate)
+    if (!best || parts.some((value, index) => value !== best.parts[index] &&
+      parts.slice(0, index).every((prior, i) => prior === best.parts[i]) && value > best.parts[index])) {
+      best = { version: candidate, parts }
+    }
+  }
+  return best?.version
+}
+
+export function validateVersionStep(previous, next, change) {
+  const [major, minor, patch] = stableVersion(previous)
+  const expected = {
+    patch: `${major}.${minor}.${patch + 1}`,
+    minor: `${major}.${minor + 1}.0`,
+    major: `${major + 1}.0.0`,
+  }
+  assert.ok(Object.hasOwn(expected, change), 'Release type must be patch, minor or major')
+  assert.equal(next, expected[change], `A ${change} release after ${previous} must be ${expected[change]}`)
+}

package/src/browser.js

@@ -1,8 +1,10 @@
 // SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
 // SPDX-License-Identifier: Apache-2.0
 
+export { serialTransport } from './browser_serial.js'
+
 /** Passive browser ROM adapter. Request the SerialPort in the UI's click handler. */
-export function openBrowserRom({ port, logger = {}, signal } = {}) {
+export function openBrowserRom({ port, logger = {}, signal, interface: romInterface = 'auto', baudRate = 'auto', onStatus = () => {} } = {}) {
   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
@@ -23,6 +25,8 @@ export function openBrowserRom({ port, logger = {}, signal } = {}) {
     get chipName() { return raw?.chipName ?? null },
     get chipFamily() { return raw?.chipFamily ?? null },
     get chipRevision() { return raw?.chipRevision ?? null },
+    get interface() { return raw?.interface ?? romInterface },
+    get baudRate() { return raw?.baudRate ?? null },
     initialize() {
       if (closing) return Promise.reject(closed())
       if (initialized) return initialized
@@ -39,7 +43,7 @@ export function openBrowserRom({ port, logger = {}, signal } = {}) {
             log: (...args) => logger.log?.(...args),
             error: (...args) => logger.error?.(...args),
             debug: (...args) => logger.debug?.(...args),
-          })
+          }, { interface: romInterface, baudRate, onStatus })
           if (closing || signal?.aborted) { await disconnect(); check() }
           await raw.initialize()
           check()

package/src/browser_rom.js

@@ -1,9 +1,213 @@
 // 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'
+import { ESPLoader, Transport } from 'esptool-js'
+import { browserRomCompatibility, browserTransportCompatibility, readBrowserFlash, romError, romWords } from './browser_rom_compat.js'
 
-export async function createBrowserLoader(port, logger) {
-  return browserRomCompatibility(await connectWithPort(port, logger))
+export const ROM_UART_BAUD_RATES = Object.freeze([2000000, 1500000, 921600, 460800, 115200])
+const families = { 'ESP32-S3': 0x3253, 'ESP32-P4': 0x3280, 'ESP32-S31': 0x3231 }
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+const securityAllowed = security => Number.isSafeInteger(security?.flags) && Number.isSafeInteger(security?.flashCryptCnt)
+  && (security.flags & 5) === 0 && security.flashCryptCnt.toString(2).replace(/0/g, '').length % 2 === 0
+
+export function browserRomInterface(port, requested = 'auto') {
+  if (!['auto', 'uart', 'usb-otg', 'usb-jtag'].includes(requested)) throw new TypeError('ROM interface must be auto, uart, usb-otg or usb-jtag')
+  if (requested !== 'auto') return requested
+  const { usbVendorId: vid, usbProductId: pid } = port.getInfo?.() ?? {}
+  if (vid === 0x303a && pid === 0x1001) return 'usb-jtag'
+  if (vid === 0x303a && [2, 9, 18, 32].includes(pid)) return 'usb-otg'
+  if ([0x10c4, 0x1a86, 0x0403, 0x067b].includes(vid)) return 'uart'
+  // Custom descriptors are ambiguous. Probe without reset, then use the chip's
+  // connection registers; callers may explicitly identify an external bridge.
+  return 'unknown'
+}
+
+export function createBrowserLoader(port, logger = {}, options = {}) {
+  return createOfficialBrowserLoader({ ESPLoader, Transport }, port, logger, options)
+}
+
+// Dependency injection is internal to the package and permits lifecycle/error
+// testing against fake official-loader dependencies without browser globals.
+export function createOfficialBrowserLoader({ ESPLoader: Loader, Transport: SerialTransport }, port, logger = {}, {
+  interface: requestedInterface = 'auto', baudRate = 'auto', onStatus = () => {},
+} = {}) {
+  let kind = browserRomInterface(port, requestedInterface)
+  if (baudRate !== 'auto' && !ROM_UART_BAUD_RATES.includes(baudRate)) throw new RangeError('Unsupported ROM UART baudRate')
+  let loader, transport, identity, initialized = false, active = false, fault, writing = false, disconnected = false
+  const status = event => { logger.log?.(`[ROM] ${JSON.stringify(event)}`); onStatus(event) }
+  const assertReady = () => {
+    if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
+    if (fault) throw fault
+    if (!initialized) throw romError('ROM_NOT_INITIALIZED', 'ROM synchronization and chip qualification are required')
+  }
+  async function closeTransport() {
+    if (transport && (transport.device?.readable || transport.device?.writable)) await transport.disconnect()
+  }
+  async function detect(mode) {
+    transport = browserTransportCompatibility(new SerialTransport(port, false))
+    loader = browserRomCompatibility(new Loader({ transport, baudrate: 115200, romBaudrate: 115200, serialOptions: { bufferSize: 256 * 1024 },
+      terminal: { clean() {}, write: value => logger.log?.(value), writeLine: value => logger.log?.(value) },
+    }), { nativeUsb: kind === 'usb-otg' || kind === 'usb-jtag' })
+    // The stub replies once to SYNC; the ROM replies eight times. In 0.7.1 the
+    // unconditional eight-reply wait prevents reconnecting to a running stub.
+    loader.sync = async function () {
+      const request = new Uint8Array(36).fill(0x55); request.set([7, 7, 18, 32])
+      let response = await this.command(8, request, 0, true, 500)
+      this.syncStubDetected = response[0] === 0
+      if (!this.syncStubDetected) for (let i = 0; i < 7; i++) response = await this.readPacket(8, 500)
+      return response
+    }
+    try {
+      await loader.detectChip(mode, 3)
+      if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed')
+      if (!loader.chip || !families[loader.chip.CHIP_NAME]) throw romError('ROM_CHIP_UNSUPPORTED', 'Browser flashing supports ESP32-S3, ESP32-P4 and ESP32-S31')
+      const current = { name: loader.chip.CHIP_NAME, family: families[loader.chip.CHIP_NAME], revision: await loader.chip.getChipRevision(loader) }
+      if (identity && (identity.family !== current.family || identity.revision !== current.revision)) throw romError('ROM_IDENTITY_CHANGED', 'Chip identity changed while recovering the download session')
+      identity = current
+      if (kind === 'unknown') {
+        if (await loader.usesUsbOtg()) kind = 'usb-otg'
+        // Without descriptor/register evidence, retain the conservative mode.
+      }
+      initialized = true
+      status({ phase: 'rom-connected', interface: kind, baudRate: transport.baudrate })
+    } catch (error) {
+      initialized = false
+      await closeTransport().catch(() => {})
+      const lost = /device.*lost|disconnected|setSignals|networkerror/i.test(`${error.name} ${error.message}`)
+      if (lost) throw romError('ROM_PORT_LOST', 'Download port detached or re-enumerated; select its current ROM port again', error)
+      if (kind === 'usb-otg') throw romError('ROM_MANUAL_DOWNLOAD', 'USB-OTG ROM is not ready. Hold BOOT, press RESET, release BOOT, then select the ROM port again', error)
+      throw error
+    }
+  }
+  async function qualifyAndStartStub() {
+    const security = await loader.getSecurityInfo(false)
+    if (!securityAllowed(security)) throw romError('ROM_SECURITY', 'Secure boot, secure download or encrypted devices require their signed flashing workflow')
+    if (typeof loader.chip.postConnect === 'function') await loader.chip.postConnect(loader)
+    await loader.runStub()
+    if (!loader.IS_STUB) throw romError('ROM_STUB_REQUIRED', 'This device has no supported browser flash stub')
+    active = true
+  }
+  async function recover() {
+    initialized = active = false
+    await closeTransport()
+    // A reopen alone is never recovery. Reset/sync at 115200, identify the chip,
+    // recheck security and start a validated stub before another candidate.
+    await detect('default_reset')
+    await qualifyAndStartStub()
+  }
+  async function preflight() {
+    const register = loader.chip.EFUSE_BLOCK1_ADDR ?? loader.CHIP_DETECT_MAGIC_REG_ADDR
+    const expected = await loader.readReg(register, 1000)
+    for (let count = 0; count < 3; count++) if (await loader.readReg(register, 1000) !== expected) throw romError('ROM_BAUD_PROBE', 'Register response changed during UART speed verification')
+    // Read-only bulk traffic checks SLIP, acknowledgements and a device digest.
+    await readBrowserFlash(loader, 0, 4096)
+  }
+  async function chooseBaud() {
+    if (kind !== 'uart') {
+      status({ phase: 'baud-ready', interface: kind, baudRate: null })
+      return
+    }
+    const candidates = baudRate === 'auto' ? ROM_UART_BAUD_RATES : [baudRate]
+    for (let index = 0; index < candidates.length; index++) {
+      const candidate = candidates[index]
+      try {
+        if (index) await recover()
+        status({ phase: 'baud-testing', interface: kind, baudRate: candidate })
+        if (candidate !== 115200) {
+          // Use the official checked command and transport retune primitives.
+          // The upstream changeBaud silently falls back to 115200; Core needs
+          // each candidate's actual result to obey its ordered selection policy.
+          await loader.checkCommand('change baud rate', loader.ESP_CHANGE_BAUDRATE, romWords(candidate, transport.baudrate), 0, 0, 1000)
+          await sleep(50)
+          await transport.changeBaudrate(candidate, loader.serialOptions)
+          loader.baudrate = candidate
+          transport.flushInput()
+        }
+        await preflight()
+        status({ phase: 'baud-ready', interface: kind, baudRate: candidate })
+        return
+      } catch (error) {
+        status({ phase: 'baud-failed', interface: kind, baudRate: candidate, code: error.code ?? 'ROM_BAUD_FAILED', message: error.message })
+        if (error.code === 'ROM_IDENTITY_CHANGED' || error.code === 'ROM_SECURITY' || error.code === 'ROM_PORT_LOST') throw error
+        if (index === candidates.length - 1) throw romError('ROM_BAUD_FAILED', 'No requested UART download speed passed verification', error)
+      }
+    }
+  }
+  async function operation(callback) {
+    assertReady()
+    if (!active || !loader.IS_STUB) throw romError('ROM_STUB_REQUIRED', 'A validated flasher stub is required')
+    try { return await callback() }
+    catch (error) {
+      // Neither failed reads nor compressed writes can be resumed on a merely
+      // reopened port. Invalidate the session; the caller must start afresh.
+      fault = error
+      initialized = active = false
+      await closeTransport().catch(() => {})
+      throw error
+    }
+  }
+  const stub = {
+    get IS_STUB() { return active && !!loader?.IS_STUB },
+    flashId: () => operation(async () => {
+      // RDID requests 24 bits, while readFlashId exposes the entire signed
+      // SPI_W0 register. Upper unused bits may be set on real S31 hardware.
+      const raw = await loader.readFlashId()
+      if (!Number.isInteger(raw) || raw < -0x80000000 || raw > 0xffffffff) throw romError('ROM_FLASH_ID', 'Invalid SPI flash ID register response')
+      const id = raw & 0xffffff
+      status({ phase: 'flash-id', id })
+      return id
+    }),
+    readRegister: address => operation(() => loader.readReg(address)),
+    writeRegister: (address, value, mask = 0xffffffff) => operation(() => loader.writeReg(address, value, mask)),
+    readFlash: (address, size, progress, options) => operation(() => readBrowserFlash(loader, address, size, progress, options)),
+    flashData(data, progress, address, _compress) {
+      return operation(async () => {
+        if (writing) throw romError('ROM_WRITE_REUSE', 'Start a fresh download session before another firmware write')
+        writing = true
+        status({ phase: 'writing', interface: kind, baudRate: kind === 'uart' ? transport.baudrate : null, compress: true })
+        await loader.writeFlash({ fileArray: [{ data: new Uint8Array(data), address }], flashMode: 'keep', flashFreq: 'keep', flashSize: 'keep', eraseAll: false, compress: true,
+          reportProgress: (_file, written, total) => progress?.(written, total),
+        })
+      })
+    },
+  }
+  const adapter = {
+    get chipName() { return identity?.name ?? null },
+    get chipFamily() { return identity?.family ?? null },
+    get chipRevision() { return identity?.revision ?? null },
+    get interface() { return kind },
+    get baudRate() { return kind === 'uart' ? transport?.baudrate ?? 115200 : null },
+    async initialize() { if (disconnected) throw romError('ROM_CLOSED', 'Browser ROM adapter is closed'); await detect(kind === 'uart' || kind === 'usb-jtag' ? 'default_reset' : 'no_reset') },
+    async getSecurityInfo() { assertReady(); return loader.getSecurityInfo() },
+    async runStub() {
+      assertReady()
+      try { await qualifyAndStartStub(); await chooseBaud(); return stub }
+      catch (error) { fault = error; initialized = active = false; await closeTransport().catch(() => {}); throw error }
+    },
+    async hardReset() {
+      assertReady()
+      if (kind === 'usb-otg' && identity.family === 0x3231) {
+        // S31's LP_WDT register layout (ESP-IDF soc/rtc_wdt_reg.h). The generic
+        // watchdog sequence also appears in Apache-2.0 esptool-js P4 support;
+        // 0.7.1's S31 inherits an unimplemented C5 watchdog method.
+        const base = 0x20801000
+        await loader.writeReg(base + 0x18, 0x50d83aa1)
+        await loader.writeReg(base + 4, 2000)
+        await loader.writeReg(base, 0xd0000102)
+        await loader.writeReg(base + 0x18, 0)
+        await sleep(500)
+        return
+      }
+      if (kind !== 'uart' && typeof loader.chip.watchdogReset === 'function' && identity.family === 0x3280) return loader.chip.watchdogReset(loader)
+      if (kind === 'usb-otg' || kind === 'unknown') throw romError('ROM_RESET_UNSUPPORTED', 'Firmware verified; press RESET to start the application on this interface')
+      // esptool-js 0.7.1 HardReset only deasserts RTS. Pulse it explicitly so
+      // bridge-connected devices actually restart after verified flashing.
+      await transport.setDTR(false)
+      await transport.setRTS(true)
+      await sleep(100)
+      await transport.setRTS(false)
+    },
+    async disconnect() { disconnected = true; initialized = active = false; await closeTransport() },
+  }
+  return adapter
 }