44 lines
2.1 KiB
Markdown
44 lines
2.1 KiB
Markdown
# 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.
|