@esp-vision/device-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,9 +1,33 @@
 # Changelog
 
-## Unreleased
+## 0.2.0
+
+### Changed
+
+- File and large-script uploads use one reliable binary `file.write` engine with 16 KiB blocks, integrity validation and cancellation cleanup; no Base64/JSON or REPL upload fallback. Public `files.write` and Python API signatures stay unchanged. Uploads require matching firmware capability `file.write.binary`; older v4 devices can still be inspected but must update firmware before upload.
+
+### Fixed
+
+- Verify newly published tarballs using bounded uncached registry reads instead of a single immediate npm view; retry transient metadata propagation/network failures without repeating publication, while failing immediately on access denial or integrity mismatch.
+
+## 0.1.1
+
+### Fixed
+
+- Expose `tcpTransport` and `serialTransport` through `@esp-vision/device-core/node`.
+- Include unit tests, hardware checks, fixtures and npm script targets in the tarball. Fail when no unit tests are found; validate imports, discovery and runnable checks from an isolated installed package.
+- Clarify `device.discover()` versus the provider's `list()` contract and document the shipped Node adapters and installed test commands.
+
+## 0.1.0 — Initial public release
 
 ### Added
 
+- Added browser-safe and optional Node LAN discovery interfaces, TTL-aware DNS-SD collection, and selection-time device identity validation before EV-MUX acquisition.
+
+- Standalone, UI-independent EV-MUX v4 sessions, strict ownership/epoch filtering, framed REPL, files, execution, Wi-Fi controls and device-action contracts.
+- Verified firmware-flash adapter with injected ROM loader, image/security/partition checks, complete readback and masked P4 download-latch reset.
+- Public npm metadata, protected default-branch publishing, isolated tarball checks and verified/idempotent release retries. The package has no Agent/IDE runtime dependency or bundle; the official firmware index uses a small TOML parser, and Node discovery optionally uses multicast-dns.
+
 - Default official firmware discovery reads dl.espressif.com config and per-version metadata; legacy unqualified releases remain visible without enabling unsafe writes. CLI uses --port and a built-in esptool process adapter, removing the user-supplied JavaScript loader requirement.
 
 - Ship `esp-vision-device` management CLI: unified `inspect` passive/probed wired/LAN queries matching the SDK method name, platform-aware USB serial filtering with `--all-ports` for native UART/Bluetooth, numbered/grouped endpoints, strict configuration/control and catalog/version firmware commands. Reuse Core facade and one cross-platform Python serial/TCP adapter in both CLI and hardware checks.
@@ -23,26 +47,14 @@
 
 ### Fixed
 
+- Preserve split mDNS address announcements during cache flush, reclaim expired cache entries, bound packet retention, and close discovery sockets when cancellation occurs during setup.
+- Soft reset requires a newer ready epoch and a real REPL barrier within one deadline; caller cancellation reaches all stages and device-action adapters.
+- Bounded file reads reject incomplete/changing content; serial startup drain, TCP frame deadlines and keepalive recovery follow the v4 contract.
+
 - Align discovery output by Unicode display width instead of tabs; fall back to aligned, wrapped device blocks on narrow terminals without truncating identifiers.
 
 - Generate script completion inside the executing statement so `input()` receives only user input; retain output arriving in the same frame as completion.
 - Return binary image results correlated to the requesting sequence instead of a shared last-image slot. LCD capture uses the dedicated `debug.capture_screen` capability and never falls back to the camera; this refactor does not implement the planned high-throughput binary firmware protocol.
 - Clean up subscriptions, pending work and transports on connection failure or session loss, and isolate event-listener exceptions from protocol delivery.
 
-## 0.1.0 — Initial public release
-
-### Added
-
-- Added browser-safe and optional Node LAN discovery interfaces, TTL-aware DNS-SD collection, and selection-time device identity validation before EV-MUX acquisition.
-
-- Standalone, UI-independent EV-MUX v4 sessions, strict ownership/epoch filtering, framed REPL, files, execution, Wi-Fi controls and device-action contracts.
-- Verified firmware-flash adapter with injected ROM loader, image/security/partition checks, complete readback and masked P4 download-latch reset.
-- Public npm metadata, protected default-branch publishing, isolated tarball checks and verified/idempotent release retries. The package has no Agent/IDE runtime dependency or bundle; the official firmware index uses a small TOML parser, and Node discovery optionally uses multicast-dns.
-
-### Fixed
-
-- Preserve split mDNS address announcements during cache flush, reclaim expired cache entries, bound packet retention, and close discovery sockets when cancellation occurs during setup.
-- Soft reset requires a newer ready epoch and a real REPL barrier within one deadline; caller cancellation reaches all stages and device-action adapters.
-- Bounded file reads reject incomplete/changing content; serial startup drain, TCP frame deadlines and keepalive recovery follow the v4 contract.
-
 The earlier v3 extraction existed only inside repository development history; it was not an npm release of this package. Version 0.1.0 is the first public v4-only package.

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The npm page and installation become available only after the first publication succeeds. 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.
+The `/node` export and bundled checks were introduced in 0.1.1. This source prepares 0.2.0 with reliable binary uploads; confirm registry publication before installing it. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm install --save-exact @esp-vision/device-core@0.1.0 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.2.0 --registry=https://registry.npmjs.org/
 ```
 
 EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`; applications should ask the user to update firmware. Core has no runtime dependency on the IDE, Agent, DOM or Node serial libraries. The host supplies the physical byte transport and discovery adapter; Core owns protocol parsing, session negotiation, REPL coordination and device operations.
@@ -41,7 +41,7 @@ Documentation source lives in this repository under `docs/en/device-core/` and `
 The npm package installs `esp-vision-device`. `inspect` combines passive wired/LAN enumeration and targeted queries. By default it lists USB serial candidates; `--all-ports` also includes native UART/Bluetooth ports. Explicit `--port` bypasses discovery filtering; `configure`, `control`, and `firmware check/update` cover management. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
 
 ```sh
-npm install -g @esp-vision/device-core@0.1.0
+npm install -g @esp-vision/device-core@0.2.0
 esp-vision-device inspect
 esp-vision-device inspect --all-ports
 esp-vision-device inspect --interface usj,usb --probe --json
@@ -49,7 +49,7 @@ esp-vision-device inspect --port COM3 --fields identity,capabilities
 esp-vision-device inspect --tcp 192.168.1.100:3232 --fields network,storage --json
 ```
 
-Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Installation becomes available after first npm publication.
+Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
 
 ## Public device API
 
@@ -110,14 +110,39 @@ try {
 }
 ```
 
+### Official Node adapters
+
+The Node-only `@esp-vision/device-core/node` subpath exports `tcpTransport({ host, port })` and `serialTransport({ serial, python })`. Constructors are passive; Core opens/closes the link during `connect()`/`disconnect()`. Serial needs pyserial in the selected Python interpreter, and uses role `usj`, `usb` or `uart` for the actual interface. The root/browser entry points do not load Node networking/process modules.
+
+```js
+import { createDevice } from '@esp-vision/device-core';
+import { tcpTransport, serialTransport } from '@esp-vision/device-core/node';
+
+const tcpDevice = createDevice({ transport: tcpTransport({ host: '192.168.1.100', port: 3232 }) });
+const usbDevice = createDevice({ transport: serialTransport({ serial: '/dev/ttyACM0', python: 'python3' }) });
+// Connect only the selected device, and always disconnect() in finally.
+```
+
 A discovery-only instance can receive a transport later:
 
 ```js
-const [selected] = await device.discover({ timeout: 3000 });
-await device.connect({ transport: tcpAdapter, role: 'tcp', expectedDevice: selected });
+import { createDevice } from '@esp-vision/device-core';
+import { tcpTransport } from '@esp-vision/device-core/node';
+import { createNodeDiscovery } from '@esp-vision/device-core/discovery/node';
+
+const provider = createNodeDiscovery();
+const device = createDevice({ discovery: provider });
+const selected = (await device.discover({ timeout: 3000 })).find(item => item.compatible && item.addresses.length);
+if (!selected) throw new Error('No compatible device found');
+try {
+  await device.connect({ transport: tcpTransport({ host: selected.addresses[0], port: selected.port }), role: 'tcp', expectedDevice: selected });
+  console.log(await device.inspect({ fields: ['identity'] }));
+} finally { await device.disconnect(); }
 ```
 
-Opening `tcpAdapter` from the selected address/bridge URL remains the host's responsibility. Supported query fields are `identity`, `capabilities`, `runtime`, `network` and `storage`. The default is identity/capabilities/runtime; `inspect` reads only the requested fields and does not change configuration. Network/storage queries require the corresponding firmware capabilities. `connect()` returns that default inspection result after negotiation.
+Application discovery is `device.discover()`. `createNodeDiscovery()` and `createBridgeDiscovery()` return providers whose adapter contract is `list({ timeout, signal })`; they do not expose `discover()`. Inject a provider into `createDevice({ discovery: provider })` rather than calling `provider.discover()`. `list()` is the lower-level integration method, not another device API.
+
+Supported query fields are `identity`, `capabilities`, `runtime`, `network` and `storage`. The default is identity/capabilities/runtime; `inspect` reads only the requested fields and does not change configuration. Network/storage queries require the corresponding firmware capabilities. `connect()` returns that default inspection result after negotiation.
 
 ### Events
 
@@ -195,7 +220,7 @@ const image = await device.capture({ source: 'camera', format: 'jpeg', timeout:
 
 Paths are absolute device paths. `files.list({ path: '/', recursive: false })` returns entries `{ name, path, type, size }`. `files.read({ path })` returns a `Uint8Array`; use `encoding: 'utf-8'` to return text, and `maxBytes` to bound a read. Writes default to `overwrite: true`; set it to `false` to require a new destination. Uploading and executing are separate operations; create an empty file with `files.write({ path, data: new Uint8Array() })` rather than a second touch API. Remove an empty directory with `files.remove({ path: '/models', type: 'directory' })`; there is no implicit recursive deletion. `files.mkdir({ path, recursive: true })` creates missing parents.
 
-**Current firmware limits:** file upload still uses the existing `script.write` chunked RPC, including Base64/JSON overhead. This API cleanup does not implement the proposed high-throughput raw binary protocol or promise improved model-upload throughput. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
+**Binary uploads (SDK 0.2.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
 
 `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.
 
@@ -284,14 +309,24 @@ The package includes library source, schemas, license and documentation, with no
 
 ## Hardware acceptance
 
-Run the checked-out SDK against one idle device using Node.js 22. These checks use the public `createDevice()` API and release the session and transport afterwards. The default check reads identity/capabilities/runtime and executes a short `print()` without creating a device file. Connecting negotiates the REPL, so use a device whose running Python application may safely be interrupted. The check does not configure Wi-Fi, reset the board or erase storage.
+The package ships its unit suite and hardware runner. From your application directory, target the installed dependency explicitly:
+
+```sh
+npm --prefix node_modules/@esp-vision/device-core test
+npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --help
+npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --tcp 192.168.1.100:3232
+```
+
+Inside the source or installed package directory, use `npm test` and `npm run test:hardware -- ...`. Unit tests require no device. The runner explicitly enumerates tests and fails when the suite is absent or empty, rather than passing zero cases. The management CLI uses `--port`; the dedicated hardware runner uses `--serial`, as shown in its help.
+
+Run the source or installed SDK against one idle device using Node.js 22. These checks use the public `createDevice()` API and release the session and transport afterwards. The default check reads identity/capabilities/runtime and executes a short `print()` without creating a device file. Connecting negotiates the REPL, so use a device whose running Python application may safely be interrupted. The check does not configure Wi-Fi, reset the board or erase storage.
 
 ```sh
 npm run test:hardware -- --tcp 192.168.1.100:3232
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_DEVICE --role usj
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_USB_OTG_DEVICE --role usb --write
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_DEVICE --role usj
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_USB_OTG_DEVICE --role usb --write
 npm run test:hardware -- --tcp 192.168.1.100 --write --capture --timeout 90000
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_DEVICE --role usj --checks all --frames 30 --output camera.jpg
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_DEVICE --role usj --checks all --frames 30 --output camera.jpg
 npm run test:hardware -- --tcp 192.168.1.100 --checks display --display-hold 2 --screen-output screen.jpg
 ```
 
@@ -303,7 +338,7 @@ These functional checks intentionally exercise sensor settings, image processing
 
 `--screen-output PATH` explicitly requests an LCD screenshot: it adds the `display` check when needed, draws red/green/blue/white bars with `ESP-VISION CI` text, validates backlight changes, captures that same display with `capture({ source: 'screen' })`, verifies JPEG completeness and panel dimensions, and writes the JPEG on the host before releasing the display. Missing LCD or screen capture support makes this explicit request fail instead of skip. Camera capture stays a separate source. Output images and logs should be placed under your project-local artifact directory when running this suite.
 
-TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with `--python /path/to/python`. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the CLI and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. Hardware-check scripts and their tests stay in the source tree and are excluded from the published package.
+TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with `--python /path/to/python`. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the CLI and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. The same hardware runner, unit tests and Python fixture ship in the source tree and npm tarball; no firmware/build outputs or device credentials are included.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -12,7 +12,8 @@
     "./bindings": "./src/device_bindings.js",
     "./firmware": "./src/firmware_flash.js",
     "./discovery": "./src/network_discovery.js",
-    "./discovery/node": "./src/network_discovery_node.js"
+    "./discovery/node": "./src/network_discovery_node.js",
+    "./node": "./src/node_transport.js"
   },
   "files": [
     "src/*.js",
@@ -21,11 +22,14 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "tests/*.mjs",
+    "tests/fixtures/*.py",
+    "scripts/*.mjs"
   ],
   "license": "Apache-2.0",
   "scripts": {
-    "test": "node --test tests/test-device-*.mjs tests/test-cli*.mjs tests/test-firmware-flash.mjs tests/test-network-discovery.mjs",
+    "test": "node scripts/run-tests.mjs",
     "check:schema": "node scripts/generate-action-schema.mjs --check",
     "schema:actions": "node scripts/generate-action-schema.mjs",
     "check:package": "node tests/check-package.mjs",

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.1.0",
+  "deviceCoreVersion": "0.2.0",
   "schemaVersion": 1,
   "actions": [
     {
@@ -169,7 +169,7 @@
     },
     {
       "name": "python.execute",
-      "description": "Execute MicroPython through the shared interpreter using bounded REPL or chunked script transport.",
+      "description": "Execute MicroPython through the shared interpreter using bounded REPL or binary file staging.",
       "inputSchema": {
         "type": "object",
         "properties": {

package/scripts/generate-action-schema.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert/strict'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+import {
+  DEVICE_ACTION_DESCRIPTORS,
+  DEVICE_ACTION_SCHEMA_VERSION,
+} from '../src/device_actions.js'
+
+const coreRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const corePackage = JSON.parse(await readFile(resolve(coreRoot, 'package.json'), 'utf8'))
+const outputPath = resolve(coreRoot, `schemas/device-actions-v${DEVICE_ACTION_SCHEMA_VERSION}.json`)
+const document = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'ESP Vision Device Actions',
+  deviceCoreVersion: corePackage.version,
+  schemaVersion: DEVICE_ACTION_SCHEMA_VERSION,
+  actions: DEVICE_ACTION_DESCRIPTORS,
+}
+const serialized = `${JSON.stringify(document, null, 2)}\n`
+
+if (process.argv.includes('--check')) {
+  assert.equal(await readFile(outputPath, 'utf8'), serialized, 'Device Action schema artifact is stale; regenerate it')
+  console.log(`Device Action Schema ${DEVICE_ACTION_SCHEMA_VERSION} is current`)
+} else {
+  await mkdir(dirname(outputPath), { recursive: true })
+  await writeFile(outputPath, serialized)
+  console.log(`Generated ${outputPath}`)
+}

package/scripts/release-npm.mjs

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { verifyPublishedIntegrity } from './verify-registry.mjs'
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const registry = 'https://registry.npmjs.org/'
+const dryRun = process.argv.includes('--dry-run')
+assert.ok(process.argv.slice(2).every(arg => arg === '--dry-run'), 'Unknown release argument')
+const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+assert.equal(manifest.name, '@esp-vision/device-core')
+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')
+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,
+    'Publish only after manual merge to the default branch')
+  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')
+}
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-core-release-'))
+try {
+  // Store an environment reference, never the token value, outside the package.
+  const config = join(temporary, 'npmrc')
+  await writeFile(config, `registry=${registry}\n//registry.npmjs.org/:_authToken=\${NPM_PUBLISH_TOKEN}\n`, { mode: 0o600 })
+  const env = dryRun ? { ...process.env } : { ...process.env, NPM_CONFIG_USERCONFIG: config }
+  function npm(args) {
+    const result = spawnSync('npm', args, { cwd: root, env, encoding: 'utf8' })
+    if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.error?.message}`)
+    return result.stdout
+  }
+  const [packed] = JSON.parse(npm(['pack', '--json', '--ignore-scripts', '--pack-destination', temporary]))
+  for (const required of ['LICENSE', 'NOTICE']) assert.ok(packed.files.some(({ path }) => path === required), `Missing ${required}`)
+  assert.ok(packed.files.every(({ path }) => /^(src\/|schemas\/|tests\/|scripts\/|package\.json$|README\.md$|LICENSE$|NOTICE$|CHANGELOG\.md$)/.test(path)),
+    'Only the standalone library may be published')
+  if (dryRun) {
+    npm(['publish', join(temporary, packed.filename), '--dry-run', '--ignore-scripts', '--access', 'public', '--registry', registry])
+    console.log(`Dry run: ${packed.name}@${packed.version}; ${packed.files.length} files; no registry write`)
+  } else {
+    const publisher = npm(['whoami', '--registry', registry]).trim()
+    assert.equal(publisher, 'esp-vision', 'Npm publisher account must be esp-vision')
+    console.log(`Npm publisher: ${publisher}`)
+    const url = new URL(encodeURIComponent(manifest.name), registry)
+    url.pathname += '/' + encodeURIComponent(manifest.version)
+    const response = await fetch(url, { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
+    if (response.ok) {
+      const existing = await response.json()
+      assert.equal(existing.dist?.integrity, packed.integrity,
+        'This version already exists with different content; bump the package version')
+      console.log(`${packed.name}@${packed.version} already published with identical content; skipped`)
+    } else {
+      assert.equal(response.status, 404, 'Registry lookup failed; do not attempt publication')
+      npm(['publish', join(temporary, packed.filename), '--ignore-scripts', '--access', 'public', '--registry', registry])
+      console.log('npm publish accepted; verifying registry metadata')
+      await verifyPublishedIntegrity(url, packed.integrity)
+      console.log(`Published and verified ${packed.name}@${packed.version}`)
+    }
+  }
+} finally {
+  await rm(temporary, { recursive: true, force: true })
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { readdir } from 'node:fs/promises'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+const tests = (await readdir(new URL('../tests/', import.meta.url)))
+  .filter(name => /^test-.*\.mjs$/.test(name)).sort()
+if (!tests.length) throw new Error('No Device Core unit tests found; the package is incomplete')
+const result = spawnSync(process.execPath, ['--test', ...process.argv.slice(2), ...tests.map(name => `tests/${name}`)], {
+  cwd: root, stdio: 'inherit',
+})
+if (result.error) throw result.error
+process.exitCode = result.status ?? 1

package/scripts/verify-registry.mjs

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+
+// Publication is one write. Only reads are retried while registry metadata propagates.
+export async function verifyPublishedIntegrity(url, integrity, {
+  fetcher = globalThis.fetch,
+  wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+  report = message => console.log(message),
+} = {}) {
+  const attempts = 6
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let response, transient
+    try {
+      response = await fetcher(url, { cache: 'no-store', headers: { 'Cache-Control': 'no-cache' }, signal: AbortSignal.timeout(15000) })
+    } catch (error) {
+      if (!(error instanceof TypeError) && !['TimeoutError', 'AbortError'].includes(error.name)) throw error
+      transient = 'network timeout or unavailable'
+    }
+    if (response?.ok) {
+      const metadata = await response.json()
+      assert.equal(metadata.dist?.integrity, integrity, 'Published tarball integrity mismatch')
+      return
+    }
+    if (response) {
+      const retryable = response.status === 404 || response.status === 429 || response.status >= 500 && response.status <= 599
+      await response.body?.cancel()
+      assert.ok(retryable, `Registry verification failed: HTTP ${response.status}`)
+      transient = `HTTP ${response.status}`
+    }
+    assert.ok(attempt + 1 < attempts, `Published metadata verification unavailable after ${attempts} reads (${transient}); retry the CI job, not publication manually`)
+    const delay = 1000 * 2 ** attempt
+    report(`Registry verification ${transient}; retrying read ${attempt + 2}/${attempts} in ${delay}ms`)
+    await wait(delay)
+  }
+}

package/src/device_actions.js

@@ -74,7 +74,7 @@ export const DEVICE_ACTION_DESCRIPTORS = Object.freeze([
     includeFiles: { type: 'boolean', default: true },
     logLimit: { type: 'integer', minimum: 0, maximum: 500, default: 100 },
   }), { readOnly: true, concurrency: 'shared-read' }),
-  action('python.execute', 'Execute MicroPython through the shared interpreter using bounded REPL or chunked script transport.', objectSchema({
+  action('python.execute', 'Execute MicroPython through the shared interpreter using bounded REPL or binary file staging.', objectSchema({
     code: { type: 'string' },
     timeoutMs: { type: 'integer', minimum: 100, maximum: 120000, default: 8000 },
   }, ['code']), { destructive: true, openWorld: true }),

package/src/device_bindings.js

@@ -3,7 +3,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { EV_REPL_FILE_CHUNK_BYTES } from './evrepl.js'
 
 export const EPHEMERAL_PYTHON_PATH = '/.espvision_agent_run.py'
 
@@ -306,17 +305,9 @@ export function bindSessionDeviceActions(registry, {
   registry.bind('deviceFile.write', async (input, { session, signal }) => {
     const path = validateDevicePath(input.path)
     const bytes = input.encoding === 'base64' ? base64ToBytes(input.content) : null
-    if (bytes) {
-      if (session.hasFeature('script.write')) {
-        await session.writeFile(path, bytes, { encoding: 'binary', signal })
-      } else {
-        await session.repl.writeFile(path, bytes, EV_REPL_FILE_CHUNK_BYTES, false, { signal })
-      }
-    } else if (session.hasFeature('script.write')) {
-      await session.writeScript(path, input.content, { runAfterWrite: input.runAfterWrite, signal })
-    } else {
-      await session.repl.writeFile(path, input.content, EV_REPL_FILE_CHUNK_BYTES, false, { signal })
-    }
+    await session.writeFile(path, bytes ?? input.content, {
+      encoding: bytes ? 'binary' : 'utf-8', runAfterWrite: input.runAfterWrite, signal,
+    })
     return { ok: true, path, bytes: bytes?.length ?? new TextEncoder().encode(input.content).length }
   })
   registry.bind('deviceFile.remove', async (input, { session, signal }) => {