swbt-python 0.4.0__tar.gz → 0.5.1__tar.gz

swbt_python-0.5.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: swbt-python
+Version: 0.5.1
+Summary: Python library for presenting an NX-compatible virtual Bluetooth HID input device.
+Keywords: bluetooth,bluetooth-hid,controller,gamepad,hid,nx
+Author: niart120
+Author-email: niart120 <38847256+niart120@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: bumble>=0.0.230,<0.0.231
+Maintainer: niart120
+Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# swbt-python
+
+NX 向けの仮想 Bluetooth HID 入力デバイスを Python から扱うためのライブラリです。
+
+本ライブラリは pre-alpha 版です。実機での動作は Bluetooth ドングル、ドライバー、対象機器の FW バージョンに依存します。
+
+## 必要なもの
+
+- Python 3.12 以降
+- uv
+- Bumble が利用可能な専用 USB Bluetooth ドングル
+
+## インストール
+
+```powershell
+pip install swbt-python
+```
+
+ソースから動かす場合は次を使います。
+
+```powershell
+uv sync --dev
+```
+
+## ドキュメント
+
+[公開ドキュメント](https://niart120.github.io/swbt-python/) には API、利用例、実機準備手順、AI エージェント向け要約があります。
+
+- [API リファレンス](https://niart120.github.io/swbt-python/api/)
+- [利用例](https://niart120.github.io/swbt-python/usage/)
+- [実機準備手順](https://niart120.github.io/swbt-python/hardware/)
+- [AI エージェント向け要約](https://niart120.github.io/swbt-python/agent-brief/)
+
+同じ内容は `docs/` 配下でも確認できます。
+
+## 利用例
+### Pro Controller
+```python
+import asyncio
+from swbt import Button, ProController
+
+
+async def main() -> None:
+    async with ProController(adapter="usb:0") as pad:
+        await pad.connect(
+            timeout=30.0,
+            allow_pairing=True,
+        )
+        await pad.tap(Button.A)
+        await pad.neutral()
+
+
+asyncio.run(main())
+```
+
+Pro Controller 相当の一時的な仮想デバイスを作成し、ペアリング後に A ボタン入力を送信するコードの例です。接続情報を永続化する場合は `ProController.create_profile()` を使います。`local_address` を省略するとアダプタが現在報告する Bluetooth アドレスを維持し、揮発領域へ書き込みません。利用者管理のローカルアドレスへ切り替える手順は[利用例](docs/usage.md)、対応する専用 USB Bluetooth ドングルと復旧手順は[実機準備手順](docs/hardware.md)を参照してください。
+
+### Joy-Con L/R
+
+Joy-Con 相当の仮想デバイスは `JoyConL(...)` または `JoyConR(...)` で作成します。以下の例は `JoyConL.create_profile()` で作成済みのプロファイルを再利用します。接続と入力の扱い方は `ProController` と同じです。
+
+```python
+import asyncio
+from swbt import Button, JoyConL, Stick
+
+
+async def main() -> None:
+    async with JoyConL(
+        adapter="usb:0",
+        profile_path="switch-left-joycon-profile.json",
+    ) as left:
+        await left.connect(timeout=30.0, allow_pairing=True)
+        await left.tap(Button.L)
+        await left.lstick(Stick.left())
+        await left.neutral()
+
+
+asyncio.run(main())
+```
+
+「持ちかた/順番を変える」画面で Joy-Con としてペアリングする場合も、接続後に登録用の SR+SL 入力を追加送信する必要はありません。ライブラリは Joy-Con 用の初期化応答を返し、0 以外のプレイヤーライトが設定されるまで `connect()` を完了しません。Joy-Con L/R の `Button.SL` と `Button.SR` は、接続後に利用者が送る通常のボタン入力として引き続き利用できます。
+
+Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetooth アドレスの選択方法とペアリングキーをまとめる `profile_path` を使います。新規プロファイルは各具象クラスの `create_profile()` で作成し、コントローラー形状と対象機器ごとに保存先を分けてください。v0.4.0 の `key_store_path` で使用していた JSON 形式のペアリング情報との互換経路はありません。Joy-Con L で右スティックや A/B/X/Y、Joy-Con R で左スティックや十字キーを入力すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
+
+## 接続方法
+
+実機接続には、PC の通常 Bluetooth 機能と共有しない専用 USB Bluetooth ドングルと、OS ごとのドライバー準備が必要です。Windows では、[Zadig](https://zadig.akeo.ie/) などで専用ドングルに WinUSB / libwdi ドライバーを入れてからアダプタ名を確認します。
+
+ドライバー準備、アダプタ名の確認、トラブルシューティングの詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
+
+### 確認済み構成
+
+2026-07-24 時点では、Windows 11 / CSR8510 A10 / WinUSB / `usb:0` で、Pro Controller、Joy-Con L、Joy-Con R の初回ペアリング、保存済みプロファイルを使う再接続、初期化完了後のオブジェクト返却を確認済みです。Joy-Con L/R は、登録用の SR+SL 入力を追加送信せずに初期化を完了しました。
+
+同じ Windows 構成で、Pro Controller の主要なボタン / スティック入力、ニュートラル復帰と、Joy-Con L/R の対応ボタン / スティック入力も確認しています。確認済み範囲と未確認範囲の詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
+
+macOS 15.7.7 / CSR8510 A10 では、Pro Controller のペアリング、保存済みペアリング情報を使う再接続、ボタン入力、ニュートラル復帰を記録しています。
+
+### 実験的構成
+
+Linux は experimental です。手順は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)に整備されていますが、専用 USB Bluetooth ドングルにアクセスできるか、ペアリングできるか、入力が反映されるかは未確認です。macOS は Pro Controller の一部挙動のみ検証済みです。Joy-Con、別ドングル、別ファームウェアでの互換性は未確認です。
+
+## 開発
+
+```powershell
+uv sync --dev
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check --no-progress
+uv run pytest tests/unit
+uv run pytest tests/integration
+```
+
+## ライセンス
+
+MIT ライセンスです。全文は [LICENSE](https://github.com/niart120/swbt-python/blob/main/LICENSE) にあります。
+
+## 注記
+
+このプロジェクトは、対象機器や関連商標の権利者から承認、後援、提携を受けたものではありません。

swbt_python-0.5.1/README.md

@@ -0,0 +1,120 @@
+# swbt-python
+
+NX 向けの仮想 Bluetooth HID 入力デバイスを Python から扱うためのライブラリです。
+
+本ライブラリは pre-alpha 版です。実機での動作は Bluetooth ドングル、ドライバー、対象機器の FW バージョンに依存します。
+
+## 必要なもの
+
+- Python 3.12 以降
+- uv
+- Bumble が利用可能な専用 USB Bluetooth ドングル
+
+## インストール
+
+```powershell
+pip install swbt-python
+```
+
+ソースから動かす場合は次を使います。
+
+```powershell
+uv sync --dev
+```
+
+## ドキュメント
+
+[公開ドキュメント](https://niart120.github.io/swbt-python/) には API、利用例、実機準備手順、AI エージェント向け要約があります。
+
+- [API リファレンス](https://niart120.github.io/swbt-python/api/)
+- [利用例](https://niart120.github.io/swbt-python/usage/)
+- [実機準備手順](https://niart120.github.io/swbt-python/hardware/)
+- [AI エージェント向け要約](https://niart120.github.io/swbt-python/agent-brief/)
+
+同じ内容は `docs/` 配下でも確認できます。
+
+## 利用例
+### Pro Controller
+```python
+import asyncio
+from swbt import Button, ProController
+
+
+async def main() -> None:
+    async with ProController(adapter="usb:0") as pad:
+        await pad.connect(
+            timeout=30.0,
+            allow_pairing=True,
+        )
+        await pad.tap(Button.A)
+        await pad.neutral()
+
+
+asyncio.run(main())
+```
+
+Pro Controller 相当の一時的な仮想デバイスを作成し、ペアリング後に A ボタン入力を送信するコードの例です。接続情報を永続化する場合は `ProController.create_profile()` を使います。`local_address` を省略するとアダプタが現在報告する Bluetooth アドレスを維持し、揮発領域へ書き込みません。利用者管理のローカルアドレスへ切り替える手順は[利用例](docs/usage.md)、対応する専用 USB Bluetooth ドングルと復旧手順は[実機準備手順](docs/hardware.md)を参照してください。
+
+### Joy-Con L/R
+
+Joy-Con 相当の仮想デバイスは `JoyConL(...)` または `JoyConR(...)` で作成します。以下の例は `JoyConL.create_profile()` で作成済みのプロファイルを再利用します。接続と入力の扱い方は `ProController` と同じです。
+
+```python
+import asyncio
+from swbt import Button, JoyConL, Stick
+
+
+async def main() -> None:
+    async with JoyConL(
+        adapter="usb:0",
+        profile_path="switch-left-joycon-profile.json",
+    ) as left:
+        await left.connect(timeout=30.0, allow_pairing=True)
+        await left.tap(Button.L)
+        await left.lstick(Stick.left())
+        await left.neutral()
+
+
+asyncio.run(main())
+```
+
+「持ちかた/順番を変える」画面で Joy-Con としてペアリングする場合も、接続後に登録用の SR+SL 入力を追加送信する必要はありません。ライブラリは Joy-Con 用の初期化応答を返し、0 以外のプレイヤーライトが設定されるまで `connect()` を完了しません。Joy-Con L/R の `Button.SL` と `Button.SR` は、接続後に利用者が送る通常のボタン入力として引き続き利用できます。
+
+Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetooth アドレスの選択方法とペアリングキーをまとめる `profile_path` を使います。新規プロファイルは各具象クラスの `create_profile()` で作成し、コントローラー形状と対象機器ごとに保存先を分けてください。v0.4.0 の `key_store_path` で使用していた JSON 形式のペアリング情報との互換経路はありません。Joy-Con L で右スティックや A/B/X/Y、Joy-Con R で左スティックや十字キーを入力すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
+
+## 接続方法
+
+実機接続には、PC の通常 Bluetooth 機能と共有しない専用 USB Bluetooth ドングルと、OS ごとのドライバー準備が必要です。Windows では、[Zadig](https://zadig.akeo.ie/) などで専用ドングルに WinUSB / libwdi ドライバーを入れてからアダプタ名を確認します。
+
+ドライバー準備、アダプタ名の確認、トラブルシューティングの詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
+
+### 確認済み構成
+
+2026-07-24 時点では、Windows 11 / CSR8510 A10 / WinUSB / `usb:0` で、Pro Controller、Joy-Con L、Joy-Con R の初回ペアリング、保存済みプロファイルを使う再接続、初期化完了後のオブジェクト返却を確認済みです。Joy-Con L/R は、登録用の SR+SL 入力を追加送信せずに初期化を完了しました。
+
+同じ Windows 構成で、Pro Controller の主要なボタン / スティック入力、ニュートラル復帰と、Joy-Con L/R の対応ボタン / スティック入力も確認しています。確認済み範囲と未確認範囲の詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
+
+macOS 15.7.7 / CSR8510 A10 では、Pro Controller のペアリング、保存済みペアリング情報を使う再接続、ボタン入力、ニュートラル復帰を記録しています。
+
+### 実験的構成
+
+Linux は experimental です。手順は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)に整備されていますが、専用 USB Bluetooth ドングルにアクセスできるか、ペアリングできるか、入力が反映されるかは未確認です。macOS は Pro Controller の一部挙動のみ検証済みです。Joy-Con、別ドングル、別ファームウェアでの互換性は未確認です。
+
+## 開発
+
+```powershell
+uv sync --dev
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check --no-progress
+uv run pytest tests/unit
+uv run pytest tests/integration
+```
+
+## ライセンス
+
+MIT ライセンスです。全文は [LICENSE](https://github.com/niart120/swbt-python/blob/main/LICENSE) にあります。
+
+## 注記
+
+このプロジェクトは、対象機器や関連商標の権利者から承認、後援、提携を受けたものではありません。

{swbt_python-0.4.0 → swbt_python-0.5.1}/examples/hardware_bringup.py

@@ -17,7 +17,7 @@ from swbt import Button, DiagnosticsConfig, ProController
 async def run(
     *,
     adapter: str,
-    key_store_path: str | None,
+    profile_path: str,
     trace_path: Path,
     connect_timeout: float,
     tap_duration: float,
@@ -26,7 +26,7 @@ async def run(
 
     Args:
         adapter: Bumble adapter moniker, such as ``"usb:0"``.
-        key_store_path: Optional pairing key store path.
+        profile_path: Existing swbt profile path.
         trace_path: JSON Lines diagnostics trace output path.
         connect_timeout: Seconds to wait for reconnect or pairing.
         tap_duration: Seconds to keep Button A pressed.
@@ -35,7 +35,7 @@ async def run(
     with trace_path.open("w", encoding="utf-8") as trace_writer:
         await _bring_up_with_trace(
             adapter=adapter,
-            key_store_path=key_store_path,
+            profile_path=profile_path,
             connect_timeout=connect_timeout,
             tap_duration=tap_duration,
             trace_writer=trace_writer,
@@ -45,7 +45,7 @@ async def run(
 async def _bring_up_with_trace(
     *,
     adapter: str,
-    key_store_path: str | None,
+    profile_path: str,
     connect_timeout: float,
     tap_duration: float,
     trace_writer: TextIO,
@@ -53,7 +53,7 @@ async def _bring_up_with_trace(
     diagnostics = DiagnosticsConfig(trace_writer=trace_writer)
     async with ProController(
         adapter=adapter,
-        key_store_path=key_store_path,
+        profile_path=profile_path,
         diagnostics=diagnostics,
     ) as pad:
         await pad.connect(
@@ -77,7 +77,9 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
     parser.add_argument("--adapter", default="usb:0", help="Bumble adapter moniker")
-    parser.add_argument("--key-store", dest="key_store_path", help="pairing key store path")
+    parser.add_argument(
+        "--profile", dest="profile_path", required=True, help="existing swbt profile path"
+    )
     parser.add_argument("--trace", required=True, type=Path, help="JSON Lines trace output path")
     parser.add_argument("--timeout", default=30.0, type=float, help="connection timeout seconds")
     parser.add_argument(
@@ -102,7 +104,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     asyncio.run(
         run(
             adapter=args.adapter,
-            key_store_path=args.key_store_path,
+            profile_path=args.profile_path,
             trace_path=args.trace,
             connect_timeout=args.timeout,
             tap_duration=args.tap_duration,

swbt_python-0.5.1/examples/pairing_probe.py

@@ -0,0 +1,73 @@
+"""Create one Pro Controller profile after explicit hardware approval."""
+
+import argparse
+import asyncio
+from collections.abc import Sequence
+from pathlib import Path
+
+from swbt import DiagnosticsConfig, ProController
+
+
+async def run(
+    *,
+    adapter: str,
+    profile_path: str,
+    local_address: str,
+    trace_path: Path,
+    pair_timeout: float,
+) -> None:
+    """Create a profile and run its first approved pairing.
+
+    Args:
+        adapter: Bumble adapter moniker, such as ``"usb:0"``.
+        profile_path: New swbt profile path. It must not already exist.
+        local_address: Individual locally administered Bluetooth address.
+        trace_path: JSON Lines diagnostics trace output path.
+        pair_timeout: Seconds to wait for a host connection.
+    """
+    trace_path.parent.mkdir(parents=True, exist_ok=True)
+    with trace_path.open("w", encoding="utf-8") as trace_writer:
+        pad = await ProController.create_profile(
+            adapter=adapter,
+            profile_path=profile_path,
+            local_address=local_address,
+            pair_timeout=pair_timeout,
+            diagnostics=DiagnosticsConfig(trace_writer=trace_writer),
+        )
+        await pad.close()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the example argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Create a profile and pair after explicit approval with cleanup.",
+    )
+    parser.add_argument("--adapter", default="usb:0", help="Bumble adapter moniker")
+    parser.add_argument("--profile", required=True, help="new swbt profile path")
+    parser.add_argument(
+        "--local-address",
+        required=True,
+        help="individual locally administered Bluetooth address",
+    )
+    parser.add_argument("--trace", required=True, type=Path, help="JSON Lines trace output path")
+    parser.add_argument("--timeout", default=30.0, type=float, help="pairing timeout seconds")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the example."""
+    args = build_parser().parse_args(argv)
+    asyncio.run(
+        run(
+            adapter=args.adapter,
+            profile_path=args.profile,
+            local_address=args.local_address,
+            trace_path=args.trace,
+            pair_timeout=args.timeout,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{swbt_python-0.4.0 → swbt_python-0.5.1}/examples/tap_a.py

@@ -29,7 +29,7 @@ async def tap_a_once(pad: SwitchGamepad, *, duration: float = 0.08) -> None:
 async def run(
     *,
     adapter: str,
-    key_store_path: str | None,
+    profile_path: str,
     connect_timeout: float,
     duration: float,
     allow_pairing: bool,
@@ -38,12 +38,12 @@ async def run(
 
     Args:
         adapter: Bumble adapter moniker, such as ``"usb:0"``.
-        key_store_path: Optional pairing key store path.
+        profile_path: Existing swbt profile path.
         connect_timeout: Seconds to wait for each connection attempt.
         duration: Seconds to keep Button A pressed.
         allow_pairing: If ``True``, allow first-time pairing when no bond exists.
     """
-    async with ProController(adapter=adapter, key_store_path=key_store_path) as pad:
+    async with ProController(adapter=adapter, profile_path=profile_path) as pad:
         await pad.connect(
             timeout=connect_timeout,
             allow_pairing=allow_pairing,
@@ -61,7 +61,9 @@ def build_parser() -> argparse.ArgumentParser:
         description="Tap Button A once through swbt-python.",
     )
     parser.add_argument("--adapter", default="usb:0", help="Bumble adapter moniker")
-    parser.add_argument("--key-store", dest="key_store_path", help="pairing key store path")
+    parser.add_argument(
+        "--profile", dest="profile_path", required=True, help="existing swbt profile path"
+    )
     parser.add_argument("--timeout", default=30.0, type=float, help="connection timeout seconds")
     parser.add_argument(
         "--duration",
@@ -90,7 +92,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     asyncio.run(
         run(
             adapter=args.adapter,
-            key_store_path=args.key_store_path,
+            profile_path=args.profile_path,
             connect_timeout=args.timeout,
             duration=args.duration,
             allow_pairing=args.allow_pairing,

{swbt_python-0.4.0 → swbt_python-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "swbt-python"
-version = "0.4.0"
+version = "0.5.1"
 description = "Python library for presenting an NX-compatible virtual Bluetooth HID input device."
 readme = "README.md"
 authors = [
@@ -141,7 +141,7 @@ error-on-warning = true
 output-format = "concise"
 
 [tool.pytest.ini_options]
-addopts = "-ra --strict-config --strict-markers"
+addopts = "-ra --strict-config --strict-markers --basetemp=tmp/pytest"
 testpaths = ["tests"]
 markers = [
     "bumble: requires a dedicated USB Bluetooth dongle opened through Bumble",

{swbt_python-0.4.0 → swbt_python-0.5.1}/spec/complete/unit_005/M4_SUBCOMMAND_RESPONDER_HARDWARE.md

@@ -60,7 +60,7 @@ Switch から受け取る output report と subcommand sequence を実機 trace
 | 項目 | 要否 | 状態 | 根拠 / 理由 |
 |---|---|---|---|
 | Switch HID / report bytes | required | done | `tests/unit/fixtures/source_audit/switch_protocol_values.toml` の `output_report_parser_layout`、`subcommand_reply_0x21_layout`、`subcommand_reply_payloads`、`spi_flash_boundary_and_seed_map`、`raw_rumble_payload` を source fact / implementation fact として使う |
-| Bumble / transport | required | done | `bumble_hid_device_api`、`bumble_hidp_output_report_boundary`、`btstack_reference_hid_sdp_policy`、`bumble_reference_classic_link_policy`、`bumble_acl_packet_queue_drain_boundary` を使う。Bumble `0.0.230` の DATA / SET_REPORT callback 境界、参照実装の HID SDP policy、service name / language base 属性、daemon production の default link policy `ROLE_SWITCH|SNIFF_MODE` = `0x0005`、HID interrupt write 後の ACL queue drain 境界は根拠化済み。実機 sequence の callback timing は M4 実行時の hardware observation として別記録にする |
+| Bumble / transport | required | done | `bumble_hid_device_api`、`bumble_hidp_output_report_boundary`、`btstack_reference_hid_sdp_policy`、`bumble_reference_classic_link_policy`、`bumble_acl_packet_queue_drain_boundary` を使う。Bumble `0.0.230` の DATA / SET_REPORT callback 境界、参照実装の HID SDP policy、service name / language base 属性、daemon production の default link policy `ROLE_SWITCH|SNIFF_MODE` = `0x0005`、ACL queue の投入・drain 境界は根拠化済み。通常送信をenqueue受理、明示切断をdrain境界とする現行方針は unit_064 で更新した。実機 sequence の callback timing は M4 実行時の hardware observation として別記録にする |
 | OS / driver / adapter | required | done | `swbt_daemon_csr8510_winusb_observation` は既存 daemon の条件付き観測であり、Bumble / 別 firmware へ一般化しない。M4 実機 trace は adapter、driver、Bumble version、Switch firmware 付きで `docs/hardware-test-log.md` に記録する |
 
 ## 6. 振る舞い仕様

{swbt_python-0.4.0 → swbt_python-0.5.1}/spec/complete/unit_050/DIRECT_REPORTING_TYPES.md

@@ -20,8 +20,8 @@
 | actor / boundary | 入力または状態 | 期待する観測結果 | 制約 |
 |---|---|---|---|
 | 周期送信の利用者 | `ProController.apply(state)` または意味的入力操作 | local current state が更新され、後続の周期 report がその時点の状態を送る | 接続と即時送信を要求しない |
-| Direct 送信の利用者 | `DirectProController.send(state)` | 指定状態の `0x30` をちょうど1件送り、送信完了後だけ current state を更新する | 接続済みを要求し、周期 task を開始しない |
-| Direct 送信の利用者 | `press()` / `release()` / `sticks()` / `imu()` / `neutral()` | last successfully sent state から候補を作り、1件送信して成功後だけ確定する | 同時操作を直列化する |
+| Direct 送信の利用者 | `DirectProController.send(state)` | 指定状態の `0x30` をちょうど1件 transport に受理させ、受理後だけ current state を更新する | 接続済みを要求し、周期 task を開始しない |
+| Direct 送信の利用者 | `press()` / `release()` / `sticks()` / `imu()` / `neutral()` | 最後にtransportが受理したstateから候補を作り、1件受理された後だけ確定する | 同時操作を直列化する |
 | Switch host | output report / subcommand | reporting type に関係なく reply を受け取る | input report と同じ送信直列化境界を通す |
 | lifecycle | `close(neutral=True/False)` | `True` は trailing neutral を試み、`False` は通常 input report を追加しない | Direct の `True` は利用者所有の送信契機に対する明示的な例外 |
 
@@ -33,7 +33,7 @@
 - 既存 `ProController` / `JoyConL` / `JoyConR` を `PeriodicSwitchGamepad` の具象型として維持する。
 - `DirectProController` / `DirectJoyConL` / `DirectJoyConR` を追加する。
 - input report と subcommand reply に共通する timer、IMU encoding、送信 lock、diagnostics を共通 sender に集約する。
-- Direct の完全状態送信と意味的入力操作を、送信成功後 commit のトランザクションとして実装する。
+- Direct の完全状態送信と意味的入力操作を、transport受理後commitのトランザクションとして実装する。
 - Direct の input operation を直列化し、`tap()` は押下から解放まで同じ操作 lock を保持する。
 - `snapshot()`、`tap()`、`close()` の reporting type ごとの意味を test と公開文書で固定する。
 - public root exports、API docs、usage、agent brief、initial design を新しい型境界へ追従させる。
@@ -68,7 +68,7 @@
 | 項目 | 要否 | 状態 | 根拠 / 理由 |
 |---|---|---|---|
 | Switch HID / report bytes | not applicable | not applicable | 既存 `0x30` builder、`0x21` reply、timer、IMU encoding を再利用し、ID、layout、定数を変更しない |
-| Bumble / transport | not applicable | not applicable | `HidDeviceTransport.send_interrupt()` は完了まで待つ既存境界を利用する。Bumble object、SDP、L2CAP、adapter 仮定は追加しない |
+| Bumble / transport | not applicable | not applicable | `HidDeviceTransport.send_interrupt()` の受理まで待つ既存境界を利用する。受理は controller flow-control completion や Switch への反映完了を意味しない。Bumble object、SDP、L2CAP、adapter 仮定は追加しない |
 | OS / driver / adapter | not applicable | not applicable | fake transport の unit / integration test だけで公開型と送信契約を検証する |
 
 ## 6. 振る舞い仕様
@@ -78,16 +78,16 @@
 | 公開型の分離 | root import と class hierarchy を調べる | Periodic / Direct の抽象型と6具象型が import でき、既存3型は Periodic に属する | mode object は公開しない |
 | API の排他性 | method と constructor signature を調べる | Periodic は `apply(state)` を持ち `send(state)` を持たない。Direct は逆で、`report_period_us` を受け取らない | 共通意味操作は両型にある |
 | Periodic 状態更新 | 未接続または接続中に状態操作する | local state を commit し、即時送信しない。接続中は後続周期 report が観測する | 現行後方互換 |
-| Direct 完全状態送信 | 接続中に `send(state)` を await する | 指定状態の `0x30` を1件送り、transport 完了後に current state を更新する | background queue を作らない |
+| Direct 完全状態送信 | 接続中に `send(state)` を await する | 指定状態の `0x30` を1件 transport に受理させ、受理後に current state を更新する | background queue を作らない |
 | Direct 非周期性 | Direct を接続し待機する | 自動 `0x30` を送らない | subcommand reply は自動処理する |
 | Direct rollback | 未接続または送信失敗 | `ClosedError` または transport error を返し、report 成功前の current state を維持する | profile validation 失敗も commit しない |
-| Direct 意味操作 | press / release / sticks / imu / neutral | last successfully sent state から候補を作り、各正常終了につき1件送り、成功後だけ commit する | `lstick` / `rstick` は `sticks` と同じ規則 |
-| Direct 同時操作 | 複数 input operation を同時に開始する | operation lock の取得順に送信と commit が完了し、候補状態が失われない | transport completion の backpressure を返す |
+| Direct 意味操作 | press / release / sticks / imu / neutral | 最後にtransportが受理したstateから候補を作り、各正常終了につき1件受理させ、受理後だけcommitする | `lstick` / `rstick` は `sticks` と同じ規則 |
+| Direct 同時操作 | 複数 input operation を同時に開始する | operation lock の取得順に transport 受理と commit が完了し、候補状態が失われない | transport 受理までの backpressure を返す |
 | tap | held input がある状態で `tap()` | 両型とも押下と解放を送り、対象 button だけを解除する。Direct は押下から解放まで操作 lock を保持する | release 失敗時は最後に送信できた押下状態を維持する |
 | subcommand 自動応答 | Direct 接続中に host output を注入する | `0x21` を自動送信し、prefix は送信順上の current state を使う | input と共通 sender lock / timer を使う |
 | close | Direct で `neutral=True` / `False` | `True` は接続中に neutral 1件を試み、成功後 commit。`False` は input report を追加しない | transport cleanup は両型共通 |
 | profile validation | Pro / Joy-Con L / Joy-Con R の Direct 操作 | Periodic と同じ capability を使い、不正候補を送信・commit しない | profile 実装を複製しない |
-| snapshot | Periodic / Direct の current state を読む | Periodic は最新 local committed state、Direct は最後に正常送信した state を返す | 新しい接続 session は neutral baseline から始める |
+| snapshot | Periodic / Direct の current state を読む | Periodic は最新 local committed state、Direct は最後にtransportが受理したstateを返す | 新しい接続 session は neutral baseline から始める |
 
 ## 7. TDD Test List
 
@@ -99,12 +99,12 @@
 | refactor-done | Direct の `send(state)` が送信完了まで待ち、指定状態の `0x30` をちょうど1件送ってから snapshot を更新する | new | integration | no | 共通 `ReportSender` を抽出し、制御可能な fake transport で完了前後の snapshot と1件送信を確認 |
 | refactor-skipped | Direct は接続後に周期 `0x30` を開始せず、host output には自動応答する | new | integration | no | send transaction の runtime 分岐で expected-green。待機中0件と `0x21` reply のみを確認 |
 | refactor-skipped | Direct の未接続、送信失敗、profile validation 失敗が current state を変更しない | edge | integration | no | send transaction 実装で expected-green。full send と press の transport error、未接続、Joy-Con L unsupported state を固定 |
-| refactor-done | Direct の press / release / sticks / imu / neutral が各1件送信し、成功後だけ状態を確定する | new | integration | no | candidate 生成、profile validation、送信成功後 commit を `_send_direct_update()` に集約 |
+| refactor-done | Direct の press / release / sticks / imu / neutral が各1件受理され、受理後だけ状態を確定する | new | integration | no | candidate生成、profile validation、transport受理後commitを `_send_direct_update()` に集約 |
 | refactor-skipped | Direct の同時入力操作が直列化され、開始順の候補状態と送信順を失わない | edge | integration | no | input operation lock 実装で expected-green。blocking fake transport で2操作目が1操作目完了まで送信開始しないことを固定 |
 | refactor-done | `tap()` が両 reporting type で held input を維持し、Direct の押下・解放を直列化する | regression | integration | no | Direct 専用2段 transaction を追加し、押下から解放まで operation lock を保持 |
 | refactor-skipped | Direct の tap release 失敗時に押下済み current state を維持し、release 再試行で neutral へ戻せる | edge | integration | no | Direct tap transaction で expected-green。最後に成功送信した押下stateと明示release再試行を固定 |
 | refactor-done | Direct input と subcommand reply が共通 timer / send lock を通り、prefix と送信順が一致する | new | unit | no | reply builder 内の state snapshot を共通 sender lock の内側へ移し、timerとprefixを送信順へ一致させた |
-| refactor-done | Direct の `close(neutral=True/False)` が trailing neutral の有無、commit、cleanup を契約どおり処理する | new | integration | no | Direct close を operation lock と共通 sender に接続し、`True` だけが送信成功後 neutral を commit |
+| refactor-done | Direct の `close(neutral=True/False)` が trailing neutral の有無、commit、cleanup を契約どおり処理する | new | integration | no | Direct close を operation lock と共通 sender に接続し、`True` だけがtransport受理後にneutralをcommit |
 | refactor-skipped | Direct Pro / Joy-Con L / Joy-Con R が同じ runtime と profile validation を共有する | new | integration | no | `_ControllerSpec` と共通runtime実装で expected-green。3 profile の正常入力と unsupported input を確認 |
 | refactor-skipped | API docs、usage、agent brief、initial design が送信所有者、完了条件、snapshot、close の違いを説明する | new | unit | no | public docs test に完了条件、送信頻度所有者、subcommand、close の必須語を追加。文書だけの変更で追加 refactor は不要 |
 
@@ -124,7 +124,7 @@ SwitchGamepad
     └── DirectJoyConR
 ```
 
-`SwitchGamepad` の共通意味操作は「現在の論理入力状態を遷移させる」ことを表す。正常終了の意味は、Periodic では local commit、Direct では1件の送信完了と commit である。
+`SwitchGamepad` の共通意味操作は「現在の論理入力状態を遷移させる」ことを表す。正常終了の意味は、Periodic では local commit、Direct では1件の transport 受理と commit である。
 
 ### 8.2 共通 sender
 
@@ -142,15 +142,15 @@ Periodic だけが scheduler と current state snapshot を所有する。Direct
 
 ```text
 input operation lock
-  -> last successfully sent state から candidate を構築
+  -> 最後にtransportが受理したstateからcandidateを構築
   -> profile validation
   -> common sender lock
        -> 0x30 build
-       -> transport.send_interrupt() 完了
+       -> transport.send_interrupt() が受理
        -> candidate commit
 ```
 
-送信失敗では commit しない。`tap()` の release 送信失敗時は、押下 report が最後の成功送信なので押下状態を current state として維持する。
+transport の受理前に失敗した場合は commit しない。`tap()` の release 送信失敗時は、押下 report が最後に受理された report なので押下状態を current state として維持する。
 
 ### 8.4 Tidy decision
 
@@ -170,7 +170,7 @@ Tidy decision:
 | `src/swbt/gamepad/core.py` | modify | reporting type 別 runtime-backed base と6具象型 |
 | `src/swbt/gamepad/runtime.py` | modify | reporting type ごとの状態操作、scheduler、close |
 | `src/swbt/report_loop.py` | modify | 共通 sender 抽出と Periodic scheduler |
-| `src/swbt/state_store.py` | modify | Direct の送信成功後 commit を支える内部境界 |
+| `src/swbt/state_store.py` | modify | Direct のtransport受理後commitを支える内部境界 |
 | `src/swbt/gamepad/output.py` | modify | sender lock 内で current state を使う reply builder |
 | `src/swbt/gamepad/__init__.py`, `src/swbt/__init__.py` | modify | public exports |
 | `src/swbt/_testing/gamepad.py` | modify | Direct fake transport constructor |
@@ -191,11 +191,11 @@ Tidy decision:
 | `uv run pytest tests/unit/test_public_api_boundary.py::test_reporting_types_expose_only_their_owned_full_state_operation tests/unit/test_package_import.py -q` | pass | 5 passed。`apply` / `send` と `report_period_us` の排他性、root export 一覧を確認 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_press_buttons_are_reflected_in_periodic_report tests/integration/test_switch_gamepad_fake_transport.py::test_apply_updates_snapshot_and_next_periodic_report tests/integration/test_switch_gamepad_fake_transport.py::test_state_update_apis_do_not_send_immediate_interrupt_reports tests/integration/test_switch_gamepad_fake_transport.py::test_tap_releases_only_tapped_button_and_preserves_held_buttons -q` | pass | 4 passed。Periodic の周期送信、snapshot、非即時送信、held input を確認 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_waits_for_transport_and_commits_exactly_one_report -q` | red | Direct send が transport へ到達せず、送信開始待ち timeout になる未実装状態を確認 |
-| `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_waits_for_transport_and_commits_exactly_one_report -q` | pass | 1 passed。transport 完了前は未完了かつ neutral、完了後は指定 `0x30` 1件と state commit を確認 |
+| `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_waits_for_transport_and_commits_exactly_one_report -q` | pass | 1 passed。transport 受理前は未完了かつ neutral、受理後は指定 `0x30` 1件と state commit を確認 |
 | `uv run pytest tests/unit/test_report_loop.py tests/integration/test_switch_gamepad_fake_transport.py::test_press_buttons_are_reflected_in_periodic_report tests/integration/test_switch_gamepad_fake_transport.py::test_output_report_injection_sends_subcommand_reply -q` | red | sender 抽出直後に snapshot が lock 外となり `0x21` が周期 `0x30` より先行する回帰を検出 |
 | `uv run pytest tests/unit/test_report_loop.py tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_waits_for_transport_and_commits_exactly_one_report tests/integration/test_switch_gamepad_fake_transport.py::test_press_buttons_are_reflected_in_periodic_report tests/integration/test_switch_gamepad_fake_transport.py::test_output_report_injection_sends_subcommand_reply -q` | pass | 7 passed。snapshot から送信までの周期 lock、Direct commit、subcommand 回帰を確認 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_connection_is_non_periodic_and_still_replies_to_subcommands -q` | pass | 1 passed。接続後60msに自動 `0x30` がなく、Device Info に `0x21` だけを返すことを確認 |
-| `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_failures_do_not_change_last_successfully_sent_state tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_rejects_unsupported_profile_state_without_sending -q` | pass | 2 passed。未接続、transport error、profile validation error で last successfully sent state を維持 |
+| `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_failures_do_not_change_last_successfully_sent_state tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_rejects_unsupported_profile_state_without_sending -q` | pass | 2 passed。未接続、transport error、profile validation errorで最後にtransportが受理したstateを維持 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_semantic_operations_send_once_and_commit_after_success -q` | red | 未接続 `press()` が `ClosedError` を出さず local state を更新する Periodic 挙動を確認 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_semantic_operations_send_once_and_commit_after_success tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_waits_for_transport_and_commits_exactly_one_report tests/integration/test_switch_gamepad_fake_transport.py::test_direct_send_failures_do_not_change_last_successfully_sent_state -q` | pass | 3 passed。7意味操作の1操作1送信、未接続拒否、full send / press failure rollback を確認 |
 | `uv run pytest tests/integration/test_switch_gamepad_fake_transport.py::test_direct_concurrent_operations_are_serialized_without_lost_state -q` | pass | 1 passed。A送信完了前はB送信を開始せず、送信列A、A+Bと最終stateを確認 |
@@ -252,7 +252,7 @@ Tidy decision:
 |---|---|---|
 | scope | pass | 公開 reporting type、共通 sender、Direct transaction、文書更新に限定。raw report API、mode 切替、scheduler 精度、macro は追加していない |
 | 公開 API | pass | unit test で2抽象型、6具象型、`apply` / `send`、`report_period_us` の排他性と root export を固定 |
-| transaction | pass | fake transport で transport 完了後 commit、未接続・入力型・profile・送信失敗 rollback、1操作1送信を確認 |
+| transaction | pass | fake transport で transport 受理後 commit、未接続・入力型・profile・送信失敗 rollback、1操作1送信を確認 |
 | concurrency | pass | input operation lock と sender lock の順序を確認。concurrent operation、Direct `tap()`、input / subcommand 競合テストが pass |
 | lifecycle | pass | Direct の非周期性、subcommand 自動応答、`close(neutral=True/False)`、新 session の neutral baseline を確認 |
 | Periodic 回帰 | pass | 既存状態更新の非即時送信、周期 report、held input、close、全 unit / integration gate が pass |