2.1 KiB
2.1 KiB
Chanora Desktop Push-to-Talk Architecture
Document status: DV meeting baseline candidate
Date: 2026-05-29
Related documents: docs/architecture/sad.md, docs/architecture/sdd.md, docs/release/dv-waiver-register.md
1. Purpose
This document records the desktop push-to-talk architecture advertised by the README and connects it to the SWE.2/SWE.3 baselines.
2. Architecture Summary
Desktop PTT is implemented as a platform-capability feature. The application must detect the active backend, expose the resulting PttCapabilityLevel, and avoid claiming global PTT support when the runtime falls back to focused-input behavior.
3. Platform Backends
| Platform | Backend strategy | Release claim rule |
|---|---|---|
| Windows | Raw Input first, low-level keyboard hook fallback, focused fallback if unavailable | Claim only the detected runtime capability |
| macOS | Event Tap where permission and OS policy allow; focused fallback otherwise | Claim Global PTT only with permission/backend evidence |
| Linux | Freedesktop GlobalShortcuts portal where available; focused fallback otherwise | State portal/fallback behavior clearly |
4. Safety Rules
| Rule | Purpose |
|---|---|
| Missed-key-up watchdog clears transmit after timeout | Prevents stuck transmit when an OS suppresses key-up |
| Capability is surfaced to UI and release record | Prevents over-claiming platform support |
| Mouse side-button support is platform-dependent | Avoids blocking release on Linux portal limitations |
| Focused fallback remains available | Preserves usable PTT when global backends are unavailable |
5. Verification Handoff
| Evidence | Required result |
|---|---|
| Per-platform smoke | Active backend and fallback behavior recorded |
| UI inspection | PTT capability badge matches runtime backend |
| Release readiness | Release notes mirror actual capability per platform |
| Safety test | Watchdog prevents stuck transmit after missed key-up |
6. DV Conclusion
The desktop PTT architecture is documented for DV navigation. Public release claims still require per-platform PTT evidence attached to the release-readiness record.