@esp-vision/device-core 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The `/node` export and bundled checks below require 0.1.1, the next patch release prepared by this source tree; 0.1.0 remains the published baseline until the release pipeline 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.1 --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.1
+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
@@ -220,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {

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.1",
+  "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/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 { 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'
@@ -48,7 +49,7 @@ try {
     console.log(`Npm publisher: ${publisher}`)
     const url = new URL(encodeURIComponent(manifest.name), registry)
     url.pathname += '/' + encodeURIComponent(manifest.version)
-    const response = await fetch(url, { signal: AbortSignal.timeout(15000) })
+    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,
@@ -57,8 +58,8 @@ try {
     } 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])
-      const verified = JSON.parse(npm(['view', `${manifest.name}@${manifest.version}`, 'dist.integrity', '--json', '--registry', registry]))
-      assert.equal(verified, packed.integrity, 'Published tarball integrity mismatch')
+      console.log('npm publish accepted; verifying registry metadata')
+      await verifyPublishedIntegrity(url, packed.integrity)
       console.log(`Published and verified ${packed.name}@${packed.version}`)
     }
   }

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 }) => {

package/src/device_session.js

@@ -47,6 +47,7 @@ const EV_MUX_USER_RPC_METHODS = new Set([
   'capabilities',
   'session.keepalive',
   'session.release',
+  'file.write',
   'script.write',
   'script.run',
   'device.control',
@@ -146,7 +147,7 @@ function isNetworkAction(method, payload) {
 }
 
 function isVmRpc(method, payload) {
-  if (method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
+  if (method === 'file.write' || method === 'script.write' || method === 'script.run' || method === 'debug.capture_frame' || method === 'debug.capture_screen') return true
   if (method === 'debug.info') return payload?.scope !== 'transport.stats'
   return false
 }
@@ -155,30 +156,6 @@ function payloadBytes(payload) {
   return payload instanceof Uint8Array ? payload : utf8Bytes(payload)
 }
 
-function maxScriptChunkBytes({ path, encoding, mode, runAfterWrite, rxPayloadMax, totalBytes }) {
-  let low = 1
-  let high = Math.max(1, Math.min(EV_MUX_SCRIPT_CHUNK_BYTES, rxPayloadMax))
-  while (low < high) {
-    const candidate = Math.ceil((low + high) / 2)
-    const payload = {
-      path, encoding, mode, offset: Math.max(0, totalBytes - 1), totalBytes,
-      contentBase64: 'A'.repeat(Math.ceil(candidate / 3) * 4), runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length <= rxPayloadMax) low = candidate
-    else high = candidate - 1
-  }
-  return low
-}
-
-function bytesToBase64(bytes) {
-  let binary = ''
-  const chunkSize = 0x8000
-  for (let i = 0; i < bytes.length; i += chunkSize) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize))
-  }
-  return btoa(binary)
-}
-
 function defaultSleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -262,6 +239,11 @@ export function validateEvmuxCapabilities(payload) {
   }
 
   for (const key of Object.keys(EV_MUX_DEFAULT_LIMITS)) validateLimit(payload.limits, key)
+  if (payload.features.includes('file.write.binary') && (!Number.isSafeInteger(payload.limits.fileWriteChunkMax)
+      || payload.limits.fileWriteChunkMax < 4096 || payload.limits.fileWriteChunkMax > 16384
+      || payload.limits.fileWriteChunkMax % 4096 !== 0)) {
+    throw new Error('EV-MUX v4 capabilities are missing a valid limits.fileWriteChunkMax')
+  }
   if (payload.session?.policy !== 'firstCome'
       || !Number.isSafeInteger(payload.session.leaseMs)
       || !Number.isSafeInteger(payload.session.keepaliveMs)
@@ -622,6 +604,7 @@ export class DeviceSession {
     redactSsid = true,
     forceNetwork = false,
   } = {}) {
+    if (payload instanceof Uint8Array) return { binaryBytes: payload.byteLength }
     if (!forceNetwork && !isNetworkAction(method, payload) && !isNetworkAction(method, requestPayload)) return payload
     const secrets = [requestPayload?.ssid, requestPayload?.password]
       .filter((value) => typeof value === 'string' && value.length > 0)
@@ -687,6 +670,7 @@ export class DeviceSession {
     seq: requestedSeq = null,
     signal = null,
     writeTimeout = null,
+    encoding = undefined,
   } = {}) {
     if (this.state === 'disconnected') {
       throw new Error('EV-MUX is not connected')
@@ -715,7 +699,9 @@ export class DeviceSession {
         && (payloadData.length !== 1 || payloadData[0] !== 0x03)) {
       throw new Error('EV-MUX repl.signal only accepts the single-byte Ctrl-C signal 0x03')
     }
-    if (this.capabilities && payloadData.length > this.limits.rxPayloadMax) {
+    const payloadLimit = method === 'file.write' && encoding === 'binary' && this.hasFeature('file.write.binary')
+      ? this.limits.fileWriteChunkMax + 20 : this.limits.rxPayloadMax
+    if (this.capabilities && payloadData.length > payloadLimit) {
       throw new Error(`EV-MUX payload is ${payloadData.length} bytes; device limit is ${this.limits.rxPayloadMax}`)
     }
     if ((channel === 'repl.stdin' || channel === 'repl.signal') && payloadData.length > this.limits.replInputMax) {
@@ -727,7 +713,7 @@ export class DeviceSession {
       seq,
       channel,
       type: frameType,
-      encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+      encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
       ...(method ? { method } : {}),
       ...(needsAuthorization ? { sessionId: this.sessionId } : {}),
       ...(usesVm && needsAuthorization ? { vmEpoch: this.vmEpoch } : {}),
@@ -738,6 +724,7 @@ export class DeviceSession {
     const frame = this.makeEvMuxFrame({
       channel,
       type: frameType,
+      encoding,
       method,
       payload,
       seq,
@@ -764,6 +751,7 @@ export class DeviceSession {
       throw new Error('EV-MUX is not connected')
     }
     if (signal?.aborted) throw abortError(signal)
+    if (payload instanceof Uint8Array && method !== 'file.write') throw new TypeError('Raw binary requests are only supported for file.write')
     if (method === 'script.write' || method === 'script.run') validateRpcPath(payload?.path)
     if (method === 'debug.info' && (payload?.scope === 'fs.list' || payload?.scope === 'fs.read')) {
       validateRpcPath(payload.path ?? (payload.scope === 'fs.list' ? '/' : undefined))
@@ -816,7 +804,8 @@ export class DeviceSession {
     this.handlers.rpcRequest?.({ channel: rpcChannel, method, seq, timeout, payload: safePayload })
     this._diagnostic('rpc.request', { channel: rpcChannel, method, seq })
     try {
-      await this.writeFrame(rpcChannel, 'req', method, JSON.stringify(payload), {
+      await this.writeFrame(rpcChannel, 'req', method, payload instanceof Uint8Array ? payload : JSON.stringify(payload), {
+        encoding: payload instanceof Uint8Array ? 'binary' : undefined,
         vmRequest,
         seq,
         signal,
@@ -1089,41 +1078,45 @@ export class DeviceSession {
       : content instanceof Uint8Array
         ? content
         : new Uint8Array(content)
-    const chunkBytes = maxScriptChunkBytes({
-      path, encoding, mode, runAfterWrite, rxPayloadMax: this.limits.rxPayloadMax, totalBytes: bytes.length,
-    })
-    if (this.hasFeature('script.write.chunked') && bytes.length > chunkBytes) {
-      let lastResponse = null
-      for (let offset = 0; offset < bytes.length; offset += chunkBytes) {
+    if (!this.hasFeature('file.write.binary')) {
+      throw Object.assign(new Error('File upload requires firmware with file.write.binary; update the device firmware'), { code: 'UNSUPPORTED_OPERATION' })
+    }
+    const limit = this.limits.fileWriteChunkMax
+    if (!Number.isSafeInteger(limit) || limit < 4096 || limit > 16384 || limit % 4096 !== 0 || bytes.length > 0xffffffff) {
+      throw new Error('Invalid negotiated binary file transfer limit or file size')
+    }
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes))
+    if (signal?.aborted) throw abortError(signal)
+    const sha256 = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('')
+    const uploadId = randomHex()
+    let committed = false
+    try {
+      const begin = await this.rpc('file.write', { action: 'begin', path, mode, totalBytes: bytes.length, sha256, uploadId }, { timeout: 8000, signal })
+      if (begin.uploadId !== uploadId || begin.chunkBytes !== limit) throw new Error('Invalid binary file transfer acknowledgement')
+      const token = Uint8Array.from(begin.uploadId.match(/../g), byte => parseInt(byte, 16))
+      for (let offset = 0; offset < bytes.length; offset += limit) {
         if (signal?.aborted) throw abortError(signal)
-        const chunk = bytes.subarray(offset, Math.min(offset + chunkBytes, bytes.length))
-        lastResponse = await this.rpc('script.write', {
-          path,
-          encoding,
-          mode,
-          offset,
-          totalBytes: bytes.length,
-          contentBase64: bytesToBase64(chunk),
-          runAfterWrite: runAfterWrite && offset + chunk.length >= bytes.length,
-        }, { timeout: 8000, signal })
+        const chunk = bytes.subarray(offset, Math.min(offset + limit, bytes.length))
+        const payload = new Uint8Array(20 + chunk.length)
+        payload.set(token)
+        new DataView(payload.buffer).setUint32(16, offset, true)
+        payload.set(chunk, 20)
+        const response = await this.rpc('file.write', payload, { timeout: 8000, signal })
+        if (response.writtenBytes !== offset + chunk.length) throw new Error('Incomplete binary file transfer acknowledgement')
         onProgress?.({ writtenBytes: offset + chunk.length, totalBytes: bytes.length })
       }
-      return lastResponse
-    }
-
-    const payload = {
-      path,
-      encoding,
-      mode,
-      contentBase64: bytesToBase64(bytes),
-      runAfterWrite,
-    }
-    if (utf8Bytes(JSON.stringify(payload)).length > this.limits.rxPayloadMax) {
-      throw new Error(`script.write payload exceeds the device RX limit ${this.limits.rxPayloadMax}; firmware must support script.write.chunked.`)
+      const result = await this.rpc('file.write', { action: 'commit', uploadId: begin.uploadId }, { timeout: 8000, signal })
+      if (result.complete !== true || result.bytes !== bytes.length) throw new Error('Incomplete binary file commit acknowledgement')
+      committed = true
+      if (bytes.length === 0) onProgress?.({ writtenBytes: 0, totalBytes: 0 })
+      if (runAfterWrite) await this.rpc('script.run', { path }, { timeout: 8000, signal })
+      return { ...result, path, runAfterWrite }
+    } finally {
+      if (!committed) {
+        // Cancellation does not cancel cleanup, and cleanup cannot mask the primary error.
+        await this.rpc('file.write', { action: 'abort', uploadId }, { timeout: 1500 }).catch(() => {})
+      }
     }
-    const response = await this.rpc('script.write', payload, { timeout: 8000, signal })
-    onProgress?.({ writtenBytes: bytes.length, totalBytes: bytes.length })
-    return response
   }
 
   async writeScript(path, content, { runAfterWrite = false, signal = null } = {}) {
@@ -1217,10 +1210,10 @@ export class DeviceSession {
     if (commandBytes <= inputLimit) {
       return this.repl.execPy(source, { timeout, signal })
     }
-    if (!this.hasFeature('script.write') || !this.hasFeature('script.run')) {
+    if (!this.hasFeature('file.write.binary') || !this.hasFeature('script.run')) {
       throw new Error(
         `Python source requires ${commandBytes} REPL bytes, above the firmware limit ${inputLimit}; ` +
-        'upgrade firmware with script.write and script.run support.',
+        'upgrade firmware with file.write.binary and script.run support.',
       )
     }
 
@@ -1365,8 +1358,8 @@ export class DeviceSession {
     if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
       throw new RangeError('Script timeout must be a positive number or null for an interactive run')
     }
-    if ((content !== undefined && !this.hasFeature('script.write')) || !this.hasFeature('script.run')) {
-      throw new Error('Running scripts requires script.run and uploading source also requires script.write')
+    if ((content !== undefined && !this.hasFeature('file.write.binary')) || !this.hasFeature('script.run')) {
+      throw new Error('Running scripts requires script.run and uploading source also requires file.write.binary')
     }
     if (this.runCapture || this.runStarting) {
       throw new Error('A script is already running')

package/src/evmux.js

@@ -389,14 +389,14 @@ export class EvMuxParser {
     }
 }
 
-export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined }) {
+export function makeEvMuxFrame({ channel, type = 'data', method = null, payload = '', seq = 0, sid = 'web-ide', sessionId = undefined, vmEpoch = undefined, contentType = undefined, width = undefined, height = undefined, route = undefined, encoding = undefined }) {
     const payloadBytes = payload instanceof Uint8Array ? payload : new TextEncoder().encode(payload)
     const metadata = {
         sid,
         seq,
         channel,
         type,
-    encoding: channel.endsWith('.rpc') ? 'json' : 'text',
+    encoding: encoding ?? (channel.endsWith('.rpc') ? 'json' : 'text'),
     ...(sessionId ? { sessionId } : {}),
     ...(vmEpoch !== undefined ? { vmEpoch } : {}),
     ...(contentType ? { contentType } : {}),
@@ -408,7 +408,8 @@ export function makeEvMuxFrame({ channel, type = 'data', method = null, payload
         metadata.method = method
     }
     const metadataBytes = new TextEncoder().encode(JSON.stringify(metadata))
-    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=00000000\r\n`)
+    const checksum = encoding === 'binary' ? crc32(payloadBytes).toString(16).padStart(8, '0') : '00000000'
+    const header = new TextEncoder().encode(`\x1eEVMUX/1 h=${metadataBytes.length} p=${payloadBytes.length} c=${checksum}\r\n`)
     const out = new Uint8Array(header.length + metadataBytes.length + payloadBytes.length + 1)
     out.set(header, 0)
     out.set(metadataBytes, header.length)

package/tests/test-device-execution.mjs

@@ -13,6 +13,7 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   let session
   let resetRequested = false
   let resetPolls = 0
+  let uploaded = 0
   const stdout = (payload) => session.feedBytes(makeEvMuxFrame({
     channel: 'repl.stdout', type: 'data', sessionId: session.sessionId, vmEpoch: session.vmEpoch, payload,
   }))
@@ -26,7 +27,7 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   const parser = new EvMuxParser({
     filterFrame: (metadata, bytes) => {
       const text = new TextDecoder().decode(bytes)
-      const payload = metadata.channel.endsWith('.rpc') ? JSON.parse(text) : text
+      const payload = metadata.encoding === 'binary' ? bytes : metadata.channel.endsWith('.rpc') ? JSON.parse(text) : text
       requests.push({ metadata, payload })
       if (metadata.channel === 'repl.signal') return
       if (metadata.channel === 'repl.stdin') {
@@ -51,7 +52,15 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
         response = { ok: true, sessionId: session.sessionId, vmEpoch: responseEpoch,
           vmReady: stalledReset || resetPolls === 1 || resetPolls >= 3 }
       }
-      if (metadata.method === 'script.write' && failWrite) {
+      if (metadata.method === 'file.write') {
+        if (payload instanceof Uint8Array) {
+          uploaded = new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getUint32(16, true) + payload.length - 20
+          response = { ok: true, writtenBytes: uploaded }
+        } else if (payload.action === 'begin') {
+          uploaded = 0; response = { ok: true, uploadId: payload.uploadId, chunkBytes: 16384 }
+        } else response = { ok: true, bytes: uploaded, complete: payload.action === 'commit' }
+      }
+      if (metadata.method === 'file.write' && failWrite) {
         response = { ok: false, error: { code: 'WRITE_FAILED', message: 'simulated write failure' } }
       } else if (metadata.method === 'script.run') {
         running = true
@@ -75,7 +84,8 @@ function executionFixture({ short = false, failWrite = false, failStop = false,
   session.sessionId = 'a'.repeat(32)
   session.vmEpoch = 1
   session.vmReady = true
-  session.capabilities = { features: ['script.write', 'script.run', 'device.control'] }
+  session.limits.fileWriteChunkMax = 16384
+  session.capabilities = { features: ['file.write.binary', 'script.run', 'device.control'] }
   return { session, requests, finish, get terminal() { return terminal }, get running() { return running } }
 }
 

package/tests/test-file-binary.mjs

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { DeviceSession } from '../src/device_session.js'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EvRepl } from '../src/evrepl.js'
+
+function fixture(options = {}) {
+  const requests = [], chunks = []; let session, began, finished
+  let token
+  const peer = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const payload = metadata.encoding === 'binary' ? bytes.slice() : JSON.parse(new TextDecoder().decode(bytes))
+    requests.push({ metadata, payload })
+    let reply = { ok: true }
+    if (payload instanceof Uint8Array) {
+      assert.equal(metadata.method, 'file.write'); assert.equal(metadata.encoding, 'binary')
+      assert.equal(metadata.vmEpoch, 7); assert.equal(metadata.sessionId, 'a'.repeat(32))
+      assert.equal(Buffer.from(payload.slice(0, 16)).toString('hex'), token)
+      const offset = new DataView(payload.buffer).getUint32(16, true)
+      assert.equal(offset, chunks.reduce((sum, chunk) => sum + chunk.length, 0))
+      chunks.push(payload.slice(20)); reply.writtenBytes = offset + payload.length - 20
+      if (options.badAck) reply.writtenBytes--
+      if (options.abort) options.abort.abort()
+    } else if (payload.action === 'begin') {
+      began = payload; token = payload.uploadId; reply.uploadId = token; reply.chunkBytes = 16384
+      if (options.abortBegin) options.abortBegin.abort()
+      if (options.failBegin) { options.failBegin = false; throw new Error('begin response lost') }
+    } else if (payload.action === 'commit') {
+      finished = true; reply.bytes = chunks.reduce((sum, chunk) => sum + chunk.length, 0); reply.complete = true
+      if (options.badCommit) reply.bytes++
+      if (options.failCommit) reply = { ok: false, error: { code: 'HASH_MISMATCH' } }
+    }
+    session.feedBytes(makeEvMuxFrame({ channel: 'user.rpc', type: 'rsp', method: metadata.method, seq: metadata.seq,
+      sessionId: 'a'.repeat(32), vmEpoch: 7, payload: JSON.stringify(reply) }))
+    return false
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { peer.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  Object.assign(session, { state: 'ready', sessionId: 'a'.repeat(32), vmEpoch: 7, vmReady: true,
+    capabilities: { features: ['file.write.binary', 'script.run'] } })
+  session.limits.fileWriteChunkMax = 16384
+  return { session, requests, chunks, get began() { return began }, get finished() { return finished } }
+}
+for (const size of [0, 1, 4096, 16384, 16385, 2 * 1024 * 1024]) {
+  test(`binary upload ${size} bytes is bounded, exact, hashed and committed`, async () => {
+    const f = fixture(), data = Uint8Array.from({ length: size }, (_, i) => i & 255), progress = []
+    try {
+      const result = await f.session.writeFile('/model.bin', data, { encoding: 'binary', onProgress: value => progress.push(value.writtenBytes) })
+      assert.equal(result.complete, true); assert.equal(result.bytes, size)
+      assert.deepEqual(Buffer.concat(f.chunks), Buffer.from(data)); assert.equal(f.finished, true)
+      assert.equal(f.began.sha256, Buffer.from(await crypto.subtle.digest('SHA-256', data)).toString('hex'))
+      assert.ok(f.chunks.every(chunk => chunk.length <= 16384)); assert.equal(f.chunks.length, Math.ceil(size / 16384))
+      assert.equal(progress.at(-1), size)
+      assert.ok(!f.requests.some(request => request.metadata.method === 'script.write'))
+    } finally { f.session.close() }
+  })
+}
+test('Python upload uses the same byte engine and requests execution only after commit', async () => {
+  const f = fixture()
+  try {
+    await f.session.writeScript('/script.py', "print('中文')", { runAfterWrite: true })
+    assert.deepEqual(Buffer.concat(f.chunks), Buffer.from("print('中文')"))
+    assert.equal(f.requests.at(-1).metadata.method, 'script.run')
+    assert.equal(f.requests.at(-2).payload.action, 'commit')
+  } finally { f.session.close() }
+})
+for (const setting of ['badAck', 'badCommit', 'failCommit']) {
+  test(`${setting} triggers abort cleanup without publishing success`, async () => {
+    const f = fixture({ [setting]: true })
+    try {
+      await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)))
+      assert.equal(f.requests.at(-1).payload.action, 'abort')
+    } finally { f.session.close() }
+  })
+}
+test('cancellation after begin still sends an independent abort', async () => {
+  const controller = new AbortController(), f = fixture({ abort: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(32768), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+  } finally { f.session.close() }
+})
+test('missing binary capability rejects without falling back to script.write', async () => {
+  const f = fixture(); f.session.capabilities.features = ['script.write']
+  try { await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(10)), { code: 'UNSUPPORTED_OPERATION' }); assert.equal(f.requests.length, 0) }
+  finally { f.session.close() }
+})
+test('corrupted binary frames fail CRC before dispatch', () => {
+  let calls = 0
+  const parser = new EvMuxParser({ filterFrame() { calls++; return false } })
+  const bytes = makeEvMuxFrame({ channel: 'user.rpc', type: 'req', method: 'file.write', encoding: 'binary', payload: new Uint8Array([0, 1, 0x1e, 0x1f, 255]) })
+  parser.feedBytes(bytes); assert.equal(calls, 1)
+  bytes[bytes.length - 2] ^= 1; parser.feedBytes(bytes); assert.equal(calls, 1)
+})
+
+test('cancellation during begin still aborts the client-known upload ID', async () => {
+  const controller = new AbortController(), f = fixture({ abortBegin: controller })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100), { signal: controller.signal }), { name: 'AbortError' })
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+    assert.equal(f.chunks.length, 0)
+  } finally { f.session.close() }
+})
+test('a lost begin response still allows abort without knowing a server-generated ID', async () => {
+  const f = fixture({ failBegin: true })
+  try {
+    await assert.rejects(f.session.writeFile('/x.bin', new Uint8Array(100)), /begin response lost/)
+    assert.equal(f.requests.at(-1).payload.action, 'abort')
+    assert.equal(f.requests.at(-1).payload.uploadId, f.began.uploadId)
+  } finally { f.session.close() }
+})

package/tests/test-release-verification.mjs

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { verifyPublishedIntegrity } from '../scripts/verify-registry.mjs'
+
+const integrity = 'sha512-test-content'
+const url = 'https://registry.npmjs.org/%40esp-vision%2Fdevice-core/0.2.0'
+const published = value => new Response(JSON.stringify({ dist: { integrity: value } }))
+function fixture(replies) {
+  const calls = [], waits = [], reports = []
+  return { calls, waits, reports, options: {
+    async fetcher(address, options) {
+      calls.push({ address, options })
+      const reply = replies.shift()
+      if (reply instanceof Error) throw reply
+      assert(reply, 'Unexpected verification request')
+      return reply
+    },
+    wait: async milliseconds => { waits.push(milliseconds) },
+    report: message => reports.push(message),
+  } }
+}
+test('new npm version becomes visible after stale 404 metadata; only uncached reads repeat', async () => {
+  const f = fixture([new Response('', { status: 404 }), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 2); assert.deepEqual(f.waits, [1000])
+  for (const call of f.calls) {
+    assert.equal(call.address, url); assert.equal(call.options.cache, 'no-store')
+    assert.equal(call.options.headers['Cache-Control'], 'no-cache')
+    assert.equal(call.options.method ?? 'GET', 'GET')
+  }
+})
+test('verification retries rate limits, temporary registry errors and network failures', async () => {
+  const f = fixture([new Response('', { status: 429 }), new Response('', { status: 503 }), new TypeError('network unavailable'), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.deepEqual(f.waits, [1000, 2000, 4000])
+})
+for (const status of [400, 401, 403]) test(`registry HTTP ${status} fails without retries`, async () => {
+  const f = fixture([new Response('', { status })])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), new RegExp(`HTTP ${status}`))
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('published integrity mismatch fails immediately', async () => {
+  const f = fixture([published('sha512-other-content')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.equal(f.calls.length, 1); assert.deepEqual(f.waits, [])
+})
+test('missing published integrity is not accepted', async () => {
+  const f = fixture([new Response('{}')])
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
+  assert.deepEqual(f.waits, [])
+})
+test('persistent propagation failures stop after six reads with bounded backoff', async () => {
+  const f = fixture(Array.from({ length: 6 }, () => new Response('', { status: 404 })))
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 6 reads/)
+  assert.equal(f.calls.length, 6); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000])
+})