# NXBT Async Refactor Plan (Checklist)

## Phase 1 – Adapter & Utilities
- [x] Build a first-class `AsyncBleakAdapter` mirroring Bleak’s async API surface (scanner contexts, client connect/disconnect, GATT helpers).
- [x] Provide thin, clearly marked synchronous shims for legacy imports (current `BlueZ` now wraps `AsyncBleakAdapter`).
- [x] Audit helper functions (`find_objects`, `find_devices_by_alias`, discovery utilities) and offer async primitives with safe sync wrappers (`asyncio.run`).
- [ ] Validate helpers with demo scripts (`scripts/testbt.py`, `scanner.py`) across supported OSes.

## Phase 2 – Controller & Bluetooth Stack
- [x] Convert controller modules (`controller.py`, `server.py`, protocol helpers) to async functions end-to-end. (`AsyncController` and `ControllerServer` now run entirely via asyncio, with sync shims retained for backwards compatibility.)
- [x] Introduce an `AsyncController` and ensure `ControllerServer` consumes it for setup.
- [x] Add an `AsyncControllerServer` facade so higher layers can await controller lifecycles.
- [x] Expose `run_async`/`connect_async`/`reconnect_async`/`mainloop_async` wrappers (no more thread offloading) to unblock higher-level async orchestration.
- [x] Replace blocking socket/BLE operations with `asyncio` sockets/tasks and cancellation-friendly loops (connect, reconnect, and mainloop now awaitable).
- [x] Document SDP/profile limitations: Bleak does not expose cross-platform profile registration, so `AsyncController` logs a warning and Phase 4 docs will direct Linux users to BlueZ if they need SDP features.

## Phase 3 – Core Nxbt Process & IPC
- [x] Introduce an `AsyncNxbt` manager that spawns controller servers as asyncio tasks (`nxbt/async_nxbt.py`).
- [x] Provide a bridge in `Nxbt` (`use_async=True`) that routes controller creation, macro queues, and state tracking through the async manager.
- [x] Replace the legacy multiprocessing `Nxbt` manager entirely (or make async the default) so controllers run as tasks inside a single event loop.
- [x] Replace multiprocessing Queue/Lock coordination with `asyncio.Queue`, `asyncio.Lock`, or `TaskGroup` equivalents.
- [x] Ensure graceful shutdown awaits outstanding tasks and closes BLE clients cleanly in both modes.

## Phase 4 – CLI, Scripts, and External APIs
- [ ] Update CLI commands, demo scripts, and web/tui entry points to drive the async core (wrap in `asyncio.run`).
    - [x] CLI macros/test/demo and `scripts/demo_loop.py` now run under `asyncio` via `AsyncNxbtClient`.
    - [x] Web app entry point now routes through a shared `AsyncNxbtClientBridge`.
    - [x] `tui.py` uses the async bridge for controller management/input updates.
- [x] Revise public APIs in `nxbt/__init__.py` to expose async entry points (or clearly documented sync wrappers).
- [x] Provide migration notes guiding downstream users on awaiting the new APIs.
- [ ] Exercise async CLI/demo/TUI flows on real BLE hardware to catch regressions (blocked on hardware availability).

## Phase 5 – Testing, Tooling, and Documentation
- [ ] Add async-aware tests (e.g., `pytest-asyncio`) covering discovery, controller lifecycles, and failure scenarios.
- [ ] Integrate async tests into CI with BLE-aware skips/mocks where hardware is unavailable.
- [ ] Update README/docs to emphasize the async model, environment requirements, and Bleak-based examples.
- [ ] Final cleanup: remove obsolete BlueZ-only utilities, ensure lint/type tools understand async interfaces, and tag a release with migration guidance.