chore: release 2.22.0

- Android: bytesToRead from BufferedEmitter while listening; KDoc; BufferedEmitterTest
- guest-js: JSDoc bytesToRead/bytesToWrite; stricter SerialportOptions/Options; Record<PortInfo>
- CHANGELOG 2.22.0; android/README table/tests list
- Bump Cargo/npm versions and lockfiles

Made-with: Cursor

Author: s00d

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+For **Android/USB-focused** details (behavior, limits, testing), see also [`android/README.md`](android/README.md).
+
+## [2.22.0](https://github.com/s00d/tauri-plugin-serialplugin/compare/v2.21.1...v2.22.0) (2026-03-21)
+
+### Android / USB
+
+* **Lifecycle:** `SerialPlugin` registers `Application.ActivityLifecycleCallbacks` and runs `SerialPortManager.cleanup()` when the host `Activity` is destroyed (close USB ports, unregister permission receiver, shut down IO executor).
+* **Listening:** Incoming data is coalesced in `BufferedEmitter` / `SerialByteAccumulator` before `serialData` events; flush interval via `serialDataFlushIntervalMs` (native clamp typically 10–2000 ms).
+* **USB serial (usb-serial-for-android):** Read/write use configured timeouts; `clearBuffer` maps to `purgeHwBuffers` when supported; `setFlowControl` (RTS/CTS, XON/XOFF); `SerialInputOutputManager` errors trigger `serialError` and port cleanup.
+* **`bytesToRead` / `bytesToWrite` (Android):** `bytesToRead` returns bytes buffered **in the plugin** only while `startListening` is active (not the kernel queue — not exposed by `UsbSerialPort`). `bytesToWrite` is `0` (writes complete synchronously from the app’s perspective). Documented in JSDoc on the JS API.
+* **Tooling:** Gradle wrapper and `android/` settings for local `./gradlew test`; JVM unit tests use a real `org.json` artifact (Android JSON stubs break `JSONObject.put` in tests). Kotlin tests cover models, JSON helpers, emit pipeline, `BufferedEmitter`.
+
+### Features
+
+* **guest-js:** Stricter `SerialportOptions` / `Options` typing (removed open index signatures); `Record<string, PortInfo>` for `available_ports` maps.
+
 ### [2.21.1](https://github.com/s00d/tauri-plugin-serialplugin/compare/v2.21.0...v2.21.1) (2025-11-05)
 
 ## [2.21.0](https://github.com/s00d/tauri-plugin-serialplugin/compare/v2.20.0...v2.21.0) (2025-10-11)

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "tauri-plugin-serialplugin"
-version = "2.21.1"
+version = "2.22.0"
 description = "Access the current process of your Tauri application."
 edition = "2021"
 authors = ["Tauri Programme within The Commons Conservancy"]

Cargo.toml

@@ -16,6 +16,7 @@ Tests live under `src/test/kotlin/`. Pure JVM tests (no Robolectric required):
 - `SerialByteAccumulatorTest` — thread-safe byte coalescing for `BufferedEmitter`
 - `SerialDataEmitFieldsTest` — `serialDataPayloadFromChunk` / `flushAccumulatorToEmit` / `applyToJSObject` (binary + UTF-8)
 - `SerialPluginConversionTest` — `Map.toJSObject` / `List.toJSArray` helpers from `SerialPlugin.kt`
+- `BufferedEmitterTest` — `pendingByteCount()` before flush
 
 JVM unit tests use **`testImplementation("org.json:json:…")`** so `JSONObject.put` is not the Android stub that throws (“Method … not mocked”).
 
@@ -38,4 +39,5 @@ This repo includes a Gradle wrapper (`gradlew`, `gradle/wrapper/`). The module d
 | `setTimeout` | Stored in `SerialPortConfig.timeout` and used for `write()` and as a fallback for `read()` when the call passes `timeout == 0`. |
 | `clearBuffer` | `UsbSerialPort.purgeHwBuffers()` (when supported by the driver). |
 | `setFlowControl` | `UsbSerialPort.setFlowControl(RTS_CTS / XON_XOFF / NONE)`. |
-| `bytesToRead` / `bytesToWrite` | Not exposed by usb-serial — returns `0`. |
+| `bytesToRead` | With **listening** (`startListening`): bytes in the plugin’s [BufferedEmitter] before the next `serialData` flush (not the kernel queue). Without listening: `0`. |
+| `bytesToWrite` | Always `0`: writes are synchronous; usb-serial exposes no TX backlog. |

android/README.md

@@ -49,6 +49,12 @@ internal class BufferedEmitter(
         accumulator.append(data)
     }
 
+    /**
+     * Bytes received via [addData] but not yet emitted to JS (waiting for the next flush).
+     * Does not include data still inside the USB/driver stack — only this plugin buffer.
+     */
+    fun pendingByteCount(): Int = accumulator.pendingByteCount()
+
     fun stop() {
         scheduled.cancel(false)
         scheduler.shutdown()

android/src/main/kotlin/app/tauri/serialplugin/manager/BufferedEmitter.kt

@@ -626,17 +626,25 @@ class SerialPortManager(
         }
     }
 
+    /**
+     * When [startListening] is active, returns bytes accumulated in [BufferedEmitter] before the next
+     * `serialData` flush — **not** the OS/driver queue (UsbSerialPort exposes no such API).
+     * Without an active listener, returns `0`.
+     */
     fun bytesToRead(path: String): Int {
-        // UsbSerialPort (mik3y) has no incoming-queue length API — kernel buffer is opaque.
         return try {
             if (!portMap.containsKey(path)) throw IOException("Port not found")
-            0
+            emitters[path]?.pendingByteCount() ?: 0
         } catch (e: Exception) {
             Log.e("SerialPortManager", "Failed to get bytes to read: ${e.message}", e)
             0
         }
     }
 
+    /**
+     * [UsbSerialPort] does not expose a pending TX queue; [writeToPort] is synchronous, so there is
+     * nothing application-level queued after a successful write — always `0` here.
+     */
     fun bytesToWrite(path: String): Int {
         return try {
             if (!portMap.containsKey(path)) throw IOException("Port not found")

android/src/main/kotlin/app/tauri/serialplugin/manager/SerialPortManager.kt

@@ -0,0 +1,19 @@
+package app.tauri.serialplugin.manager
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class BufferedEmitterTest {
+    @Test
+    fun pendingByteCount_tracks_data_before_flush() {
+        // Max flush interval (2000 ms) so the first scheduled flush is late; we only assert immediately.
+        val emitter = BufferedEmitter("/dev/usbX", 2000L) { _ -> }
+        try {
+            assertEquals(0, emitter.pendingByteCount())
+            emitter.addData(byteArrayOf(10, 20, 30))
+            assertEquals(3, emitter.pendingByteCount())
+        } finally {
+            emitter.stop()
+        }
+    }
+}

android/src/test/kotlin/app/tauri/serialplugin/manager/BufferedEmitterTest.kt

@@ -33,9 +33,9 @@ export interface SerialportOptions {
   size?: number;
   /** Android: batch interval (ms) for `serialData` events when listening (native default 100). */
   serialDataFlushIntervalMs?: number;
-  [key: string]: any;
 }
 
+/** Normalized port settings used after construction (see {@link SerialportOptions}). */
 export interface Options {
   path?: string;
   baudRate?: number;
@@ -46,7 +46,6 @@ export interface Options {
   size?: number;
   timeout: number;
   serialDataFlushIntervalMs?: number;
-  [key: string]: any;
 }
 
 export interface ReadOptions {
@@ -141,11 +140,11 @@ class SerialPort {
 
   /**
    * @description Lists all available serial ports
-   * @returns {Promise<{ [key: string]: PortInfo }>} A promise that resolves to a map of port names to port information
+   * @returns {Promise<Record<string, PortInfo>>} A promise that resolves to a map of port names to port information
    */
-  static async available_ports(): Promise<{ [key: string]: PortInfo }> {
+  static async available_ports(): Promise<Record<string, PortInfo>> {
     try {
-      const result = await invoke<{ [key: string]: PortInfo }>('plugin:serialplugin|available_ports');
+      const result = await invoke<Record<string, PortInfo>>('plugin:serialplugin|available_ports');
       return Promise.resolve(result)
     } catch (error) {
       return Promise.reject(error);
@@ -154,11 +153,11 @@ class SerialPort {
 
   /**
    * @description Lists all available serial ports using platform-specific commands
-   * @returns {Promise<{ [key: string]: PortInfo }>} A promise that resolves to a map of port names to port information
+   * @returns {Promise<Record<string, PortInfo>>} A promise that resolves to a map of port names to port information
    */
-  static async available_ports_direct(): Promise<{ [key: string]: PortInfo }> {
+  static async available_ports_direct(): Promise<Record<string, PortInfo>> {
     try {
-      const result = await invoke<{ [key: string]: PortInfo }>('plugin:serialplugin|available_ports_direct');
+      const result = await invoke<Record<string, PortInfo>>('plugin:serialplugin|available_ports_direct');
       return Promise.resolve(result)
     } catch (error) {
       return Promise.reject(error);
@@ -1004,8 +1003,12 @@ class SerialPort {
   }
 
   /**
-   * @description Gets the number of bytes available to read
-   * @returns {Promise<number>} A promise that resolves to the number of bytes
+   * @description Gets an estimate of bytes ready to read.
+   * **Desktop:** driver/OS input queue (same idea as POSIX `FIONREAD` / `ioctl`).
+   * **Android:** only while `startListening` is active — bytes already received by the native
+   * listener but not yet flushed to JS as `serialData` (plugin-side buffer). Otherwise `0`.
+   * This is **not** the same as desktop when listening is off or on other platforms.
+   * @returns {Promise<number>} Byte count (platform-specific semantics above).
    */
   async bytesToRead(): Promise<number> {
     try {
@@ -1018,8 +1021,10 @@ class SerialPort {
   }
 
   /**
-   * @description Gets the number of bytes waiting to be written
-   * @returns {Promise<number>} A promise that resolves to the number of bytes
+   * @description Gets the number of bytes waiting to be written (output queue).
+   * **Android:** typically always `0` after a successful `write` — the USB stack does not expose
+   * a pending-TX count and writes complete synchronously from the app’s perspective.
+   * @returns {Promise<number>} Pending output bytes (often `0` on Android).
    */
   async bytesToWrite(): Promise<number> {
     try {