日本語 Guide

@gurezo/web-serial-rxjs の利用方法を説明する手書き Markdown Guide です。公開 API の型・引数・戻り値の網羅的な仕様は 英語 TypeDoc API Reference を参照してください。

canonical なドキュメント構成は ARCHITECTURE.ja.md を参照してください。

Getting Started（推奨する読み順）

1. 概要 — SerialSession の公開面、state$ / errors$ の位置付け、最小サンプル
2. クイックスタート — インストール、接続、受信・送信、切断・破棄、エラーハンドリング
3. Framework 別 session ライフサイクル — disconnect$ / dispose$ のタイミングと subscription 解除（Angular / React / Vue / Svelte / Vanilla TS）
4. ブラウザサポートと公式サポート方針 — Web Serial API 実装状況と公式サポートの分離
5. バージョンサポートとリリース方針 — SemVer、非推奨、サポート範囲（LTS なし）
6. Bundler / framework 互換性の検証方針 — CI と Example build の区別、ESM / RxJS / 型の最低要件（全 matrix なし）
7. Bundle size と tree-shaking — 再現可能な library-only サイズのスナップショットと測定手順
8. Verified environment 掲載基準 — 実機結果を掲載する場合の最低項目（デバイスカタログではない）
9. receive$ / lines$ / terminalText$ の選び方 — 用途から受信ストリームを選ぶ
10. 通信パターン別 Recipes — 通信目的から Guide / Recipe を探す（行プロトコル、コマンド／応答、タイムアウトなど）
11. 高度な使用方法 — 行フレーミング、派生ストリーム、リカバリ
12. Request / Response — lines$ / receive$ で応答待ち、コマンドの直列化
13. タイムアウト・キャンセル・再試行 — 期限、破棄時キャンセル、回数制限付き再試行（コア自動再試行なし）
14. API の概念と設計メモ — オプション表、SerialError、型の補足、差し替え可能な SerialSession 契約、対応範囲（テキスト / バイナリ / 文字コード）（TypeDoc の代替ではありません）
15. バイナリ受信 API — 設計判断 — 将来の receiveBytes$ の go / no-go（未実装）
16. 実機なしテスト — Fake SerialSession、Vitest 例、DI 注入（npm 非同梱）
17. トラブルシューティング — Web Serial / セッションのよくある問題、自己解決手順、エラー Recovery Matrix

既存コードから移行する場合:

• v3 → v4 マイグレーション — Phase 1+2 の削除（receiveReplay$、isBrowserSupported()、オプション整理）
• v2 → v3 マイグレーション — state$ discriminated union、SerialSessionStatus、context.cause
• v1 → v2 マイグレーション — 削除された v1 API の対応表

ドキュメント一覧

関連リンク

• モノレポ README.ja.md — サンプルアプリ索引、貢献、ブラウザサポート
• English Guide — English Guide 索引
• ドキュメントトップ — ../../index.html
• 英語 TypeDoc API Reference — ../../api/modules.html
• 親 Issue — #453（ドキュメント構成整備）

Canonical API の要点

• state$ — 接続ライフサイクルの canonical source。state.status と SerialSessionStatus で分岐し、connected 時は state.portInfo を利用する
• errors$ — fatal / non-fatal エラーの canonical event channel。SerialError.is(SerialErrorCode.*) で分岐する
• dispose$() — セッション破棄の唯一の API（購読により実行）
• isWebSerialSupported() — トップレベルの同期 feature detection（セッションメソッドではない。サポート保証ではない）— ブラウザサポート を参照
• Phase 1+2 で削除された API（destroy$、isConnected$、portInfo$、getPortInfo()、getCurrentPort()、receiveReplay$、isBrowserSupported()）は v4 への移行 を参照