@gurezo/web-serial-rxjs 2.4.0 → 3.1.0

package/README.ja.md

@@ -4,7 +4,7 @@
   <img src="https://raw.githubusercontent.com/gurezo/web-serial-rxjs/main/packages/web-serial-rxjs/web-serial-rxjs-icon.png" alt="web-serial-rxjs プロジェクトアイコン" width="512" />
 </p>
 
-Web Serial API を最小限の Session 指向 RxJS 表面でラップする TypeScript ライブラリです。v2 では単一の `SerialSession` を公開し、`state$` / `isConnected$` / `receive$` / `lines$` / `errors$` を購読するだけで UI を駆動できます。read loop や送信キューの自前実装は不要です。
+Web Serial API を最小限の Session 指向 RxJS 表面でラップする TypeScript ライブラリです。公開 API は単一の `SerialSession` を提供し、`state$`（canonical lifecycle state）/ `errors$`（error event channel）/ `receive$` / `lines$` を購読するだけで UI を駆動できます。read loop や送信キューの自前実装は不要です。
 
 ## ブラウザサポート
 
@@ -21,9 +21,13 @@ Web Serial API は**デスクトップ**ブラウザでのみサポートされ
 
 `connect$` の前の feature detection には `SerialSession.isBrowserSupported()`（同期的に `boolean`）を使います。
 
+## 接続状態（ライフサイクル UI）
+
+ライフサイクル UI には **`state$`** の `state.status` narrowing を canonical API として使用してください。boolean だけ必要な場合は `state$` から derive してください。`isConnected$` は v3.x では引き続き利用可能ですが **非推奨** です。詳細は [v3 移行ガイド](./docs/guide/ja/migration-v3.md#6-isconnected-の非推奨化) を参照してください。
+
 ## 接続中のポート情報（デバイス識別）
 
-`connect$` 成功後は `getPortInfo()` または `portInfo$` で `SerialPort.getInfo()` と同じスナップショット（例: 利用可能な場合の USB ベンダ/プロダクト ID）を取得できます。未接続時は `null` です。`getCurrentPort()` は接続中のみ内部の `SerialPort` を返します。`close()` は直接呼ばず、ライフサイクルは `disconnect$` に任せてください。
+`connect$` 成功後、`state$` を `state.status === SerialSessionStatus.Connected` で handling する場合は **`state.portInfo`** を canonical API として使用してください。`getPortInfo()` と `portInfo$` は v3.x では引き続き利用可能ですが **非推奨** です。`state$` の narrowing へ移行してください。`getCurrentPort()` は削除されました。詳細は [v3 移行ガイド](./docs/guide/ja/migration-v3.md#7-getcurrentport-の削除) を参照してください。
 
 ## 受信の replay（`receive$` と `receiveReplay$`）
 
@@ -31,7 +35,7 @@ Web Serial API は**デスクトップ**ブラウザでのみサポートされ
 
 ## `receive$` と `lines$`
 
-購読するストリームはユースケースに合わせて選んでください。**`lines$`** をターミナル表示に使うと `\r` が失われ再描画できず、シェル出力（例: `ls -la` の整形）が崩れます。詳細は [概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md) を参照してください。
+購読するストリームはユースケースに合わせて選んでください。**`lines$`** をターミナル表示に使うと `\r` が失われ再描画できず、シェル出力（例: `ls -la` の整形）が崩れます。詳細は [概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/overview.md) を参照してください。
 
 ### `receive$`（raw ストリーム）
 
@@ -83,18 +87,21 @@ pnpm add rxjs
 
 ## 次に読むもの
 
-- **v2 の全体像**（機能一覧、`SerialSession` 早見表、`SerialSessionState`、最小サンプル）: [SerialSession（v2）の概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md)（[English](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md)）
-- 最短でポートを開く手順: [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md)
+- **API の全体像**（機能一覧、`SerialSession` 早見表、`SerialSessionState`、最小サンプル）: [SerialSession の概要](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/overview.md)（[English](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/overview.md)）
+- 最短でポートを開く手順: [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/quick-start.md)
 
 ## ドキュメント
 
 | ドキュメント | 用途 |
 | --- | --- |
-| [全体像](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md) | 機能と v2 `SerialSession` / `SerialSessionState` の対応表 |
-| [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.ja.md) | ポートを開いて購読までを最短で |
-| [高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.ja.md) | 行フレーミング、擬似リクエスト/レス、リカバリ |
-| [API リファレンス](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.ja.md) | オプション、`SerialError`、型の詳細 |
-| [v1 → v2 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.ja.md) | 廃止された v1 API の置き換え |
+| [日本語 Guide 索引](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/README.md) | Getting Started の読み順と一覧 |
+| [English Guide 索引](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/README.md) | Getting Started reading order and full index |
+| [全体像](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/overview.md) | 機能と `SerialSession` / `SerialSessionState` の対応表 |
+| [クイックスタート](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/quick-start.md) | ポートを開いて購読までを最短で |
+| [高度な使用方法](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/advanced-usage.md) | 行フレーミング、擬似リクエスト/レス、リカバリ |
+| [API の概念と設計メモ](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/concepts.md) | オプション、`SerialError`、型の表形式補足 |
+| [v2 → v3 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v3.md) | `state$` discriminated union、`SerialSessionStatus`、`context.cause` |
+| [v1 → v2 マイグレーション](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/migration-v2.md) | 廃止された v1 API の置き換え |
 | **リポジトリ [README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.ja.md)** | モノレポ構成、**`apps/` のサンプル**、貢献、MCP、プロジェクトアイコン |
 
 ## ライセンス

package/README.md

@@ -4,7 +4,7 @@
   <img src="https://raw.githubusercontent.com/gurezo/web-serial-rxjs/main/packages/web-serial-rxjs/web-serial-rxjs-icon.png" alt="@gurezo/web-serial-rxjs project icon" width="512" />
 </p>
 
-A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The v2 API exposes a single `SerialSession` so applications can drive their UI from `state$` + `isConnected$` + `receive$` + `lines$` + `errors$`, without rebuilding read loops or send queues themselves.
+A TypeScript library that wraps the Web Serial API with a minimal, session-oriented RxJS surface. The public API exposes a single `SerialSession` so applications can drive their UI from `state$` (canonical lifecycle state) + `errors$` (error event channel) + `receive$` + `lines$`, without rebuilding read loops or send queues themselves.
 
 ## Browser support
 
@@ -21,9 +21,13 @@ Supported desktop browsers:
 
 `SerialSession.isBrowserSupported()` returns a synchronous `boolean` for feature detection before `connect$`.
 
+## Connection state (lifecycle UI)
+
+Prefer **`state$`** with `state.status` narrowing as the canonical API for lifecycle UI. Derive a boolean from `state$` when you only need a connected flag. `isConnected$` remains available in v3.x but is **deprecated** — see [Migrating to v3](./docs/guide/en/migration-v3.md#6-isconnected-deprecation).
+
 ## Port info (device identification)
 
-After a successful `connect$`, use `getPortInfo()` or subscribe to `portInfo$` for the `SerialPort.getInfo()` snapshot (e.g. USB vendor/product IDs when the device exposes them). Both yield `null` when disconnected. `getCurrentPort()` returns the underlying `SerialPort` while connected; do not call `close()` on it—use `disconnect$` for lifecycle.
+After a successful `connect$`, use `state.portInfo` when handling `state$` with `state.status === SerialSessionStatus.Connected` — this is the canonical API. `getPortInfo()` and `portInfo$` remain available in v3.x but are **deprecated**; migrate to `state$` narrowing. `getCurrentPort()` has been removed; see [Migrating to v3 – getCurrentPort() removal](./docs/guide/en/migration-v3.md#7-getcurrentport-removal).
 
 ## Receive replay (`receive$` vs `receiveReplay$`)
 
@@ -31,7 +35,7 @@ After a successful `connect$`, use `getPortInfo()` or subscribe to `portInfo$` f
 
 ## `receive$` vs `lines$`
 
-Pick the stream that matches your use case. Using **`lines$`** for a terminal mirror drops `\r` and redraw behaviour, which breaks shells and tools that rely on carriage-return updates ([overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md)).
+Pick the stream that matches your use case. Using **`lines$`** for a terminal mirror drops `\r` and redraw behaviour, which breaks shells and tools that rely on carriage-return updates ([overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/overview.md)).
 
 ### `receive$` (raw stream)
 
@@ -83,20 +87,25 @@ pnpm add rxjs
 
 ## Where to go next
 
-- Full **v2 API map** (features, `SerialSession` table, `SerialSessionState`, minimal example): [SerialSession (v2) overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md) ([日本語](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.ja.md))
-- Shortest path to an open port: [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md)
-- Browse as one integrated site (TypeDoc): [web-serial-rxjs API Documentation](https://gurezo.github.io/web-serial-rxjs/)
+- Full **API map** (features, `SerialSession` table, `SerialSessionState`, minimal example): [SerialSession overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/overview.md) ([日本語](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/ja/overview.md))
+- Shortest path to an open port: [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/quick-start.md)
+- Browse the published documentation site: [web-serial-rxjs Documentation](https://gurezo.github.io/web-serial-rxjs/)
+- Browse API Reference (TypeDoc): [web-serial-rxjs API Documentation](https://gurezo.github.io/web-serial-rxjs/api/)
 
 ## Documentation
 
 | Doc | Use it for |
 | --- | --- |
-| [TypeDoc top page](https://gurezo.github.io/web-serial-rxjs/) | Start from OVERVIEW and move to guides/API in one site |
-| [Overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/OVERVIEW.md) | Features and the v2 `SerialSession` / `SerialSessionState` map |
-| [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/QUICK_START.md) | Open a port and wire subscriptions end-to-end |
-| [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/ADVANCED_USAGE.md) | Line framing, request/response-style flows, recovery |
-| [API Reference](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/API_REFERENCE.md) | `SerialSessionOptions`, `SerialError`, and formal details |
-| [v1 → v2 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/MIGRATION_V2.md) | Replacing the removed v1 `SerialClient` / `ShellClient` API |
+| [Documentation home](https://gurezo.github.io/web-serial-rxjs/) | Site landing with Guide (ja/en) and API Reference |
+| [English Guide (site)](https://gurezo.github.io/web-serial-rxjs/guide/en/README.html) | Getting Started reading order on the published site |
+| [API Reference (site)](https://gurezo.github.io/web-serial-rxjs/api/index.html) | English TypeDoc API Reference |
+| [English Guide index](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/README.md) | Getting Started reading order and full index |
+| [Overview](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/overview.md) | Features and the `SerialSession` / `SerialSessionState` map |
+| [Quick Start](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/quick-start.md) | Open a port and wire subscriptions end-to-end |
+| [Advanced Usage](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/advanced-usage.md) | Line framing, request/response-style flows, recovery |
+| [API concepts and design notes](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/concepts.md) | `SerialSessionOptions`, `SerialError`, and formal details |
+| [v2 → v3 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v3.md) | `state$` discriminated union, `SerialSessionStatus`, `context.cause` |
+| [v1 → v2 migration](https://github.com/gurezo/web-serial-rxjs/blob/main/packages/web-serial-rxjs/docs/guide/en/migration-v2.md) | Replacing the removed v1 `SerialClient` / `ShellClient` API |
 | [Repository README](https://github.com/gurezo/web-serial-rxjs/blob/main/README.md) | Monorepo layout, **examples** under `apps/`, contributing, MCP, and project icon |
 
 ## License

package/dist/errors/serial-error-code.d.ts

@@ -24,54 +24,58 @@
  * }
  * ```
  */
-export declare enum SerialErrorCode {
+export declare const SerialErrorCode: {
     /**
      * Browser does not support the Web Serial API.
      *
-     * This error occurs when attempting to use serial port functionality in a browser
-     * that doesn't support the Web Serial API. Supported desktop browsers are Chrome,
-     * Edge, Opera, and Firefox 151+. Safari and mobile browsers are not supported.
+     * Emitted on `connect$` when `navigator.serial` is unavailable.
      *
      * **Suggested action**: Inform the user to use a supported browser.
+     *
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
      */
-    BROWSER_NOT_SUPPORTED = "BROWSER_NOT_SUPPORTED",
+    readonly BROWSER_NOT_SUPPORTED: "BROWSER_NOT_SUPPORTED";
     /**
      * Serial port is not available.
      *
-     * This error occurs when a requested port cannot be accessed, such as when
-     * getting previously granted ports fails or when the port is already in use
-     * by another application.
+     * **Reserved — not emitted in v3.x.** The current implementation uses only
+     * `navigator.serial.requestPort`; there is no `getPorts` API path. Scheduled
+     * for removal in the next major version.
+     *
+     * **Suggested action**: Handle port acquisition failures with
+     * {@link SerialErrorCode.PORT_OPEN_FAILED} or
+     * {@link SerialErrorCode.OPERATION_CANCELLED} instead.
      *
-     * **Suggested action**: Check if the port is available or being used by another application.
+     * @deprecated Not emitted at runtime in v3.x. Will be removed in the next major version.
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
      */
-    PORT_NOT_AVAILABLE = "PORT_NOT_AVAILABLE",
+    readonly PORT_NOT_AVAILABLE: "PORT_NOT_AVAILABLE";
     /**
      * Failed to open the serial port.
      *
-     * This error occurs when the port cannot be opened, typically due to incorrect
-     * connection parameters, hardware issues, or permission problems.
+     * Emitted on `connect$` when `port.open()` rejects.
      *
      * **Suggested action**: Verify connection parameters and check hardware connections.
      */
-    PORT_OPEN_FAILED = "PORT_OPEN_FAILED",
+    readonly PORT_OPEN_FAILED: "PORT_OPEN_FAILED";
     /**
      * Serial port is already open.
      *
-     * This error occurs when attempting to open a port that is already connected.
-     * Only one connection can be active at a time per SerialClient instance.
+     * Emitted on `connect$` when the session is not in `'idle'` or `'error'`
+     * (non-fatal; session state is unchanged).
      *
      * **Suggested action**: Disconnect the current port before connecting a new one.
      */
-    PORT_ALREADY_OPEN = "PORT_ALREADY_OPEN",
+    readonly PORT_ALREADY_OPEN: "PORT_ALREADY_OPEN";
     /**
      * Serial port is not open.
      *
-     * This error occurs when attempting to read from or write to a port that hasn't
-     * been opened yet. The port must be connected before performing I/O operations.
+     * Emitted when `send$` or `disconnect$` is called in an invalid session
+     * state (for example before `connect$` completes).
      *
-     * **Suggested action**: Call {@link SerialClient.connect} before reading or writing.
+     * **Suggested action**: Call {@link SerialSession.connect$} before sending data.
      */
-    PORT_NOT_OPEN = "PORT_NOT_OPEN",
+    readonly PORT_NOT_OPEN: "PORT_NOT_OPEN";
     /**
      * Failed to read from the serial port.
      *
@@ -80,7 +84,7 @@ export declare enum SerialErrorCode {
      *
      * **Suggested action**: Check the connection and hardware, then retry the read operation.
      */
-    READ_FAILED = "READ_FAILED",
+    readonly READ_FAILED: "READ_FAILED";
     /**
      * Failed to write to the serial port.
      *
@@ -89,7 +93,7 @@ export declare enum SerialErrorCode {
      *
      * **Suggested action**: Check the connection and hardware, then retry the write operation.
      */
-    WRITE_FAILED = "WRITE_FAILED",
+    readonly WRITE_FAILED: "WRITE_FAILED";
     /**
      * Serial port connection was lost.
      *
@@ -99,7 +103,7 @@ export declare enum SerialErrorCode {
      *
      * **Suggested action**: Check the physical connection and reconnect if needed.
      */
-    CONNECTION_LOST = "CONNECTION_LOST",
+    readonly CONNECTION_LOST: "CONNECTION_LOST";
     /**
      * Invalid filter options provided.
      *
@@ -108,7 +112,7 @@ export declare enum SerialErrorCode {
      *
      * **Suggested action**: Verify filter options match the expected format and value ranges.
      */
-    INVALID_FILTER_OPTIONS = "INVALID_FILTER_OPTIONS",
+    readonly INVALID_FILTER_OPTIONS: "INVALID_FILTER_OPTIONS";
     /**
      * Operation was cancelled by the user.
      *
@@ -118,14 +122,18 @@ export declare enum SerialErrorCode {
      * **Suggested action**: This is a normal condition - no action required, but you may want
      * to inform the user that the operation was cancelled.
      */
-    OPERATION_CANCELLED = "OPERATION_CANCELLED",
+    readonly OPERATION_CANCELLED: "OPERATION_CANCELLED";
     /**
      * Operation timed out before completion.
      *
-     * This error occurs when an operation waits for a condition (for example, prompt
-     * detection) and the timeout period elapses first.
+     * **Reserved — not emitted in v3.x.** No timeout / prompt detection /
+     * transaction API exists yet. Scheduled for removal in the next major version
+     * unless a future API adopts this code.
+     *
+     * @deprecated Not emitted at runtime in v3.x. Will be removed in the next major version.
+     * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
      */
-    OPERATION_TIMEOUT = "OPERATION_TIMEOUT",
+    readonly OPERATION_TIMEOUT: "OPERATION_TIMEOUT";
     /**
      * Internal line buffer exceeded its configured size limit.
      *
@@ -136,7 +144,7 @@ export declare enum SerialErrorCode {
      * **Suggested action**: Increase `lineBuffer.maxChars`, handle framing on `receive$`,
      * or ensure the device sends line terminators.
      */
-    LINE_BUFFER_OVERFLOW = "LINE_BUFFER_OVERFLOW",
+    readonly LINE_BUFFER_OVERFLOW: "LINE_BUFFER_OVERFLOW";
     /**
      * Invalid receive replay options provided.
      *
@@ -146,7 +154,37 @@ export declare enum SerialErrorCode {
      * **Suggested action**: Verify `receiveReplay` options match the documented
      * ranges and value types.
      */
-    INVALID_RECEIVE_REPLAY_OPTIONS = "INVALID_RECEIVE_REPLAY_OPTIONS",
+    readonly INVALID_RECEIVE_REPLAY_OPTIONS: "INVALID_RECEIVE_REPLAY_OPTIONS";
+    /**
+     * Invalid terminal buffer options provided.
+     *
+     * This error occurs when {@link SerialSessionOptions.terminalBuffer} values are
+     * out of range, such as a negative or non-integer `maxLines` or `maxChars`.
+     *
+     * **Suggested action**: Verify `terminalBuffer` options match the documented
+     * ranges and value types.
+     */
+    readonly INVALID_TERMINAL_BUFFER_OPTIONS: "INVALID_TERMINAL_BUFFER_OPTIONS";
+    /**
+     * Invalid line buffer options provided.
+     *
+     * This error occurs when {@link SerialSessionOptions.lineBuffer} values are
+     * out of range, such as a negative or non-integer `maxChars`.
+     *
+     * **Suggested action**: Verify `lineBuffer` options match the documented
+     * ranges and value types.
+     */
+    readonly INVALID_LINE_BUFFER_OPTIONS: "INVALID_LINE_BUFFER_OPTIONS";
+    /**
+     * Invalid connection options provided.
+     *
+     * This error occurs when connection fields such as `baudRate` are out of
+     * range at session creation time.
+     *
+     * **Suggested action**: Verify connection options match the documented
+     * ranges and value types.
+     */
+    readonly INVALID_CONNECTION_OPTIONS: "INVALID_CONNECTION_OPTIONS";
     /**
      * Receive replay buffer exceeded its configured character limit.
      *
@@ -157,7 +195,7 @@ export declare enum SerialErrorCode {
      * **Suggested action**: Increase `receiveReplay.maxChars`, reduce chunk size at
      * the source, or subscribe earlier to avoid relying on a large replay buffer.
      */
-    RECEIVE_REPLAY_BUFFER_OVERFLOW = "RECEIVE_REPLAY_BUFFER_OVERFLOW",
+    readonly RECEIVE_REPLAY_BUFFER_OVERFLOW: "RECEIVE_REPLAY_BUFFER_OVERFLOW";
     /**
      * Session has been disposed and can no longer be used.
      *
@@ -168,15 +206,21 @@ export declare enum SerialErrorCode {
      * **Suggested action**: Call {@link SerialSession.dispose$} only when
      * permanently tearing down a session, then create a new one if needed.
      */
-    SESSION_DISPOSED = "SESSION_DISPOSED",
+    readonly SESSION_DISPOSED: "SESSION_DISPOSED";
     /**
      * Unknown error occurred.
      *
-     * This error code is used for errors that don't fit into any other category.
-     * The original error details may be available in the error's message or originalError property.
+     * Emitted as a fallback when dispose or disconnect encounters an error that
+     * cannot be classified more specifically. The underlying failure is on
+     * {@link SerialError.context | context.cause}.
      *
-     * **Suggested action**: Check the error message and originalError for more details.
+     * **Suggested action**: Check the error message and `context.cause` for more details.
      */
-    UNKNOWN = "UNKNOWN"
-}
+    readonly UNKNOWN: "UNKNOWN";
+};
+/**
+ * String union of allowed {@link SerialErrorCode} runtime values
+ * (same set as the values on the {@link SerialErrorCode} object).
+ */
+export type SerialErrorCode = (typeof SerialErrorCode)[keyof typeof SerialErrorCode];
 //# sourceMappingURL=serial-error-code.d.ts.map

package/dist/errors/serial-error-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-error-code.d.ts","sourceRoot":"","sources":["../../src/errors/serial-error-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,oBAAY,eAAe;IACzB;;;;;;;;OAQG;IACH,qBAAqB,0BAA0B;IAE/C;;;;;;;;OAQG;IACH,kBAAkB,uBAAuB;IAEzC;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IAErC;;;;;;;OAOG;IACH,iBAAiB,sBAAsB;IAEvC;;;;;;;OAOG;IACH,aAAa,kBAAkB;IAE/B;;;;;;;OAOG;IACH,WAAW,gBAAgB;IAE3B;;;;;;;OAOG;IACH,YAAY,iBAAiB;IAE7B;;;;;;;;OAQG;IACH,eAAe,oBAAoB;IAEnC;;;;;;;OAOG;IACH,sBAAsB,2BAA2B;IAEjD;;;;;;;;OAQG;IACH,mBAAmB,wBAAwB;IAE3C;;;;;OAKG;IACH,iBAAiB,sBAAsB;IAEvC;;;;;;;;;OASG;IACH,oBAAoB,yBAAyB;IAE7C;;;;;;;;OAQG;IACH,8BAA8B,mCAAmC;IAEjE;;;;;;;;;OASG;IACH,8BAA8B,mCAAmC;IAEjE;;;;;;;;;OASG;IACH,gBAAgB,qBAAqB;IAErC;;;;;;;OAOG;IACH,OAAO,YAAY;CACpB"}
+{"version":3,"file":"serial-error-code.d.ts","sourceRoot":"","sources":["../../src/errors/serial-error-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;;;;;OAQG;;IAGH;;;;;;;;;;;;;OAaG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;CAEK,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC"}

package/dist/errors/serial-error-context.d.ts

@@ -0,0 +1,61 @@
+import { SerialErrorCode } from './serial-error-code';
+/**
+ * Context payload for errors that wrap an underlying failure.
+ */
+export type SerialErrorCauseContext = {
+    readonly cause: unknown;
+};
+/**
+ * Machine-readable constraint identifiers for factory-time validation errors.
+ */
+export type ValidationErrorConstraint = 'at-least-one-usb-id' | 'usb-id-0-65535' | 'positive-safe-integer' | 'receive-replay-buffer-size-range' | 'receive-replay-max-chars-range' | 'non-negative-safe-integer';
+/**
+ * Structured metadata for `INVALID_*` validation errors thrown at session
+ * factory time. {@link SerialError.message} remains human-readable.
+ */
+export type ValidationErrorContext = {
+    readonly field: string;
+    readonly value: unknown;
+    readonly constraint: ValidationErrorConstraint;
+    readonly filterIndex?: number;
+};
+/**
+ * Maps each {@link SerialErrorCode} to its structured context shape.
+ *
+ * Codes mapped to `undefined` have no machine-readable metadata beyond
+ * {@link SerialError.message}. Overflow and validation codes expose structured
+ * metadata so callers do not need to parse error messages.
+ */
+export interface SerialErrorContextMap {
+    [SerialErrorCode.BROWSER_NOT_SUPPORTED]: undefined;
+    [SerialErrorCode.PORT_NOT_AVAILABLE]: SerialErrorCauseContext;
+    [SerialErrorCode.PORT_OPEN_FAILED]: SerialErrorCauseContext;
+    [SerialErrorCode.PORT_ALREADY_OPEN]: undefined;
+    [SerialErrorCode.PORT_NOT_OPEN]: undefined;
+    [SerialErrorCode.READ_FAILED]: SerialErrorCauseContext;
+    [SerialErrorCode.WRITE_FAILED]: SerialErrorCauseContext;
+    [SerialErrorCode.CONNECTION_LOST]: SerialErrorCauseContext;
+    [SerialErrorCode.INVALID_FILTER_OPTIONS]: ValidationErrorContext;
+    [SerialErrorCode.OPERATION_CANCELLED]: SerialErrorCauseContext;
+    [SerialErrorCode.OPERATION_TIMEOUT]: undefined;
+    [SerialErrorCode.LINE_BUFFER_OVERFLOW]: {
+        readonly maxChars: number;
+    };
+    [SerialErrorCode.INVALID_RECEIVE_REPLAY_OPTIONS]: ValidationErrorContext;
+    [SerialErrorCode.INVALID_TERMINAL_BUFFER_OPTIONS]: ValidationErrorContext;
+    [SerialErrorCode.INVALID_LINE_BUFFER_OPTIONS]: ValidationErrorContext;
+    [SerialErrorCode.INVALID_CONNECTION_OPTIONS]: ValidationErrorContext;
+    [SerialErrorCode.RECEIVE_REPLAY_BUFFER_OVERFLOW]: {
+        readonly maxChars: number;
+        readonly bufferSize: number;
+    };
+    [SerialErrorCode.SESSION_DISPOSED]: undefined;
+    [SerialErrorCode.UNKNOWN]: SerialErrorCauseContext;
+}
+/**
+ * @internal
+ */
+export declare function isCauseContextCode(code: SerialErrorCode): code is keyof {
+    [K in keyof SerialErrorContextMap as SerialErrorContextMap[K] extends SerialErrorCauseContext ? K : never]: SerialErrorContextMap[K];
+};
+//# sourceMappingURL=serial-error-context.d.ts.map

package/dist/errors/serial-error-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-error-context.d.ts","sourceRoot":"","sources":["../../src/errors/serial-error-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,qBAAqB,GACrB,gBAAgB,GAChB,uBAAuB,GACvB,kCAAkC,GAClC,gCAAgC,GAChC,2BAA2B,CAAC;AAEhC;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,CAAC,eAAe,CAAC,qBAAqB,CAAC,EAAE,SAAS,CAAC;IACnD,CAAC,eAAe,CAAC,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAC9D,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC5D,CAAC,eAAe,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC/C,CAAC,eAAe,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IAC3C,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACvD,CAAC,eAAe,CAAC,YAAY,CAAC,EAAE,uBAAuB,CAAC;IACxD,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC3D,CAAC,eAAe,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;IACjE,CAAC,eAAe,CAAC,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC/D,CAAC,eAAe,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC;IAC/C,CAAC,eAAe,CAAC,oBAAoB,CAAC,EAAE;QACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,CAAC,eAAe,CAAC,8BAA8B,CAAC,EAAE,sBAAsB,CAAC;IACzE,CAAC,eAAe,CAAC,+BAA+B,CAAC,EAAE,sBAAsB,CAAC;IAC1E,CAAC,eAAe,CAAC,2BAA2B,CAAC,EAAE,sBAAsB,CAAC;IACtE,CAAC,eAAe,CAAC,0BAA0B,CAAC,EAAE,sBAAsB,CAAC;IACrE,CAAC,eAAe,CAAC,8BAA8B,CAAC,EAAE;QAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC9C,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;CACpD;AAYD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,IAAI,IAAI,MAAM;KACd,CAAC,IAAI,MAAM,qBAAqB,IAAI,qBAAqB,CAAC,CAAC,CAAC,SAAS,uBAAuB,GACzF,CAAC,GACD,KAAK,GAAG,qBAAqB,CAAC,CAAC,CAAC;CACrC,CAEA"}

package/dist/errors/serial-error.d.ts

@@ -1,5 +1,7 @@
 import { SerialErrorCode } from './serial-error-code';
+import { type SerialErrorCauseContext, type SerialErrorContextMap, type ValidationErrorConstraint, type ValidationErrorContext } from './serial-error-context';
 export { SerialErrorCode };
+export type { SerialErrorCauseContext, SerialErrorContextMap, ValidationErrorConstraint, ValidationErrorContext, };
 /**
  * Custom error class for serial port operations.
  *
@@ -9,25 +11,24 @@ export { SerialErrorCode };
  *
  * @example
  * ```typescript
- * try {
- *   await client.connect().toPromise();
- * } catch (error) {
- *   if (error instanceof SerialError) {
+ * session.errors$.subscribe((error) => {
+ *   if (error.is(SerialErrorCode.READ_FAILED)) {
  *     console.error(`Error code: ${error.code}`);
  *     console.error(`Message: ${error.message}`);
- *     if (error.originalError) {
- *       console.error(`Original error:`, error.originalError);
- *     }
+ *     console.error(`Cause:`, error.context.cause);
+ *   }
+ *
+ *   if (error.is(SerialErrorCode.LINE_BUFFER_OVERFLOW)) {
+ *     console.error(`maxChars: ${error.context.maxChars}`);
+ *   }
  *
- *     // Check specific error code
- *     if (error.is(SerialErrorCode.BROWSER_NOT_SUPPORTED)) {
- *       // Handle browser not supported
- *     }
+ *   if (error.is(SerialErrorCode.BROWSER_NOT_SUPPORTED)) {
+ *     // Handle browser not supported
  *   }
- * }
+ * });
  * ```
  */
-export declare class SerialError extends Error {
+export declare class SerialError<TCode extends SerialErrorCode = SerialErrorCode> extends Error {
     /**
      * The error code identifying the type of error that occurred.
      *
@@ -35,12 +36,23 @@ export declare class SerialError extends Error {
      *
      * @see {@link SerialErrorCode} for all available error codes
      */
-    readonly code: SerialErrorCode;
+    readonly code: TCode;
+    /**
+     * Structured metadata associated with {@link code}.
+     *
+     * When {@link is} returns `true`, TypeScript narrows this property to the
+     * context shape defined in {@link SerialErrorContextMap} for that code.
+     */
+    readonly context: SerialErrorContextMap[TCode];
     /**
      * The original error that caused this SerialError, if available.
      *
      * This property contains the underlying error (e.g., DOMException, TypeError)
      * that was wrapped in this SerialError. It may be undefined if no original error exists.
+     *
+     * @deprecated Prefer {@link context} for cause-bearing codes. This property is
+     *   retained for backward compatibility and is kept in sync when a cause is
+     *   provided.
      */
     readonly originalError?: Error;
     /**
@@ -48,25 +60,34 @@ export declare class SerialError extends Error {
      *
      * @param code - The error code identifying the type of error
      * @param message - A human-readable error message
-     * @param originalError - The original error that caused this SerialError, if any
+     * @param originalError - The original error that caused this SerialError, if any.
+     *   @deprecated Prefer passing `{ cause }` via {@link context}. When omitted,
+     *   cause-bearing codes derive `{ cause }` from this argument for backward
+     *   compatibility.
+     * @param context - Structured metadata for the error code. For cause-bearing
+     *   codes, pass `{ cause }` here. When omitted, cause-bearing codes derive
+     *   `{ cause }` from the legacy {@link originalError} argument.
      */
-    constructor(code: SerialErrorCode, message: string, originalError?: Error);
+    constructor(code: TCode, message: string, originalError?: Error, context?: SerialErrorContextMap[TCode]);
     /**
      * Check if the error matches a specific error code.
      *
      * This is a convenience method for checking the error code without directly
-     * comparing the code property.
+     * comparing the code property. When this method returns `true`, TypeScript
+     * narrows `this.code` and `this.context` to the shapes defined for the
+     * provided `code` argument.
      *
      * @param code - The error code to check against
-     * @returns `true` if this error's code matches the provided code, `false` otherwise
+     * @returns Type predicate: `true` if this error's code matches the provided
+     *   code (and `this.code` / `this.context` are narrowed), `false` otherwise
      *
      * @example
      * ```typescript
-     * if (error.is(SerialErrorCode.PORT_NOT_OPEN)) {
-     *   // Handle port not open error
+     * if (error.is(SerialErrorCode.LINE_BUFFER_OVERFLOW)) {
+     *   // error.code and error.context.maxChars are narrowed
      * }
      * ```
      */
-    is(code: SerialErrorCode): boolean;
+    is<C extends SerialErrorCode>(code: C): this is SerialError<C>;
 }
 //# sourceMappingURL=serial-error.d.ts.map

package/dist/errors/serial-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serial-error.d.ts","sourceRoot":"","sources":["../../src/errors/serial-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC;;;;;;OAMG;IACH,SAAgB,IAAI,EAAE,eAAe,CAAC;IAEtC;;;;;OAKG;IACH,SAAgB,aAAa,CAAC,EAAE,KAAK,CAAC;IAEtC;;;;;;OAMG;gBACS,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,KAAK;IAczE;;;;;;;;;;;;;;;OAeG;IACI,EAAE,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO;CAG1C"}
+{"version":3,"file":"serial-error.d.ts","sourceRoot":"","sources":["../../src/errors/serial-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EACV,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,GACvB,CAAC;AAYF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,WAAW,CACtB,KAAK,SAAS,eAAe,GAAG,eAAe,CAC/C,SAAQ,KAAK;IACb;;;;;;OAMG;IACH,SAAgB,IAAI,EAAE,KAAK,CAAC;IAE5B;;;;;OAKG;IACH,SAAgB,OAAO,EAAE,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAEtD;;;;;;;;;OASG;IACH,SAAgB,aAAa,CAAC,EAAE,KAAK,CAAC;IAEtC;;;;;;;;;;;;OAYG;gBAED,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,KAAK,EACrB,OAAO,CAAC,EAAE,qBAAqB,CAAC,KAAK,CAAC;IAgCxC;;;;;;;;;;;;;;;;;;OAkBG;IACI,EAAE,CAAC,CAAC,SAAS,eAAe,EACjC,IAAI,EAAE,CAAC,GACN,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC;CAG1B"}