EdisonJwa
2511b24982
Five user-reported defects + one auto-test regression-catcher.
== TC-2.3: capability badge stuck at L0Focused on Korean Win 11 ==
Root cause: in WindowsRawInputBackend::start() (and the parallel
WindowsHookBackend), the worker thread's armed.store(ok, ...) only
ran AFTER GetMessageW returned (i.e. on WM_QUIT). During normal
arming the message pump runs forever, so armed stayed at its
initial false value, and descriptor() reported L0Focused even
though RegisterRawInputDevices had succeeded.
Fix: run_raw_input_loop and run_hook_loop now take armed as a
parameter and flip it to true inside the loop right after the
successful registration, before blocking on GetMessageW. The
outer setter is kept as a belt-and-braces clear-on-failure path.
Also drops the redundant outer 'Raw Input armed' / 'low-level
hook armed' log lines — the in-loop 'Raw Input devices
registered' / 'low-level hooks installed' messages already
convey arming success with full context.
New tests raw_input_backend_start_flips_armed_to_l2 and
hook_backend_start_flips_armed_to_l2 call real start(), sleep
80 ms, assert descriptor().level == L2GlobalHoldToTalk. Replaces
the previous #[ignore]'d real-start smoke test which never
asserted on the descriptor.
== TC-10: no-permission channel rejection invisible ==
Root cause 1: chanora_protocol::adapter::move_self_to used the
fire-and-forget send() on the client_move command. TS3 server
replies with a typed error event the adapter discarded, and
move_to_channel returned Ok regardless.
Root cause 2: even when chanora_core::voice_join detected the
non-confirmation via snapshot polling, the rolled-back error
flowed into the connect-form-area _error string which is hidden
post-connect. The user saw no feedback.
Fix:
* New ProtocolError::ServerRejected { code: u32, message: String }
carries the canonical TS3 error code per the official catalogue
at https://github.com/ReSpeak/tsdeclarations (Errors.csv).
* move_self_to now uses send_with_result, returns a MessageHandle.
The connection-task loop holds a pending_moves HashMap keyed by
MessageHandle, services StreamItem::MessageResult by looking up
and resolving the reply with either Ok or the typed
ServerRejected.
* Pending entries have a 3 s deadline so a server that never
replies doesn't leak the reply channel — expired entries fall
back to Ok and let the snapshot poll handle confirmation.
* voice_join short-circuits on ServerRejected (no need for the
full snapshot poll), still polls for confirmation as a
belt-and-braces fallback for legacy servers; on poll failure
emits ServerRejected with sentinel code 0x0001 (undefined).
* New BridgeError::ServerRejected mirror with the same fields;
CoreError → BridgeError mapping preserves the typed variant.
* Flutter _onJoinChannel shows a floating SnackBar with a
localised message selected by error code (channelJoinFailed*
l10n entries). 6 known codes mapped to specific messages
(insufficient permission, wrong password, channel full,
family limit, private channel, timeout); everything else
falls back to the server-supplied generic message.
== TC-13: mouse side-button capture only works on text field ==
The _PttBindingCaptureDialog wrapped its Column with a Listener
using the default HitTestBehavior.deferToChild. Pointer events
landing on the dialog's empty padding regions weren't claimed by
any child and so were never delivered to the Listener.
Fix: explicit HitTestBehavior.opaque so the entire dialog area
catches PointerDown events regardless of where the cursor sits.
== Channel tree hierarchy ==
Reported issue: tree rendered as flat list, no indication of
parent-child nesting. The bridge already carries the
field; the renderer just ignored it.
Fix in _SnapshotView: walk the (already DFS-sorted) channel list
and compute each row's depth from its parent's depth. Render
left-padding of depth * 18 dp. Cap depth at 6 to keep deep
hierarchies visually bounded; the cap plateaus silently (no
glyph, channel still tappable, data carries the real depth).
== Responsive layout ==
Connected layout is now LayoutBuilder-driven. Below 840 dp wide
(Material's tablet/desktop breakpoint) the original stacked
column layout is used (Voice Bar on top, channel tree below).
At 840 dp and above the layout becomes a side-by-side Row with
the Voice Bar pinned at 320 dp on the left and the channel tree
Expanded on the right.
Verification
- cargo check --workspace: clean.
- cargo test --workspace --lib: 80 / 0 / 1 (unchanged Linux total;
+2 new Windows-only tests not counted here).
- flutter analyze: clean (6 pre-existing Radio.groupValue infos).
- FRB bindings regenerated to expose BridgeError_ServerRejected.
Chanora
Chanora is a cross-platform voice communication client for TeamSpeak-compatible servers.
It is built with a shared Flutter UI and a Rust core, with TeamSpeak-compatible protocol integration isolated behind tsclientlib.
Flutter UI + Rust Core + tsclientlib
Chanora is an independent project and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak.
Status
Chanora is currently in early planning and baseline-candidate design.
Current documentation baseline: v0.9.2
Current status: Baseline Candidate
Implementation status: Not production-ready
The current engineering focus is:
- defining the system and software architecture;
- preparing the Flutter + Rust application structure;
- validating TeamSpeak-compatible protocol integration through
tsclientlib; - defining cross-platform audio behavior;
- preparing release, verification, security, privacy, and legal gates.
Target Platforms
Chanora is intended to support:
- Windows
- macOS
- Linux
- Android
- iOS / iPadOS
Current platform policy:
| Platform | Baseline |
|---|---|
| iOS / iPadOS runtime target | iOS 13+ unless Flutter, plugin, audio, or product constraints require raising it |
| App Store Connect upload gate | Xcode 26+ with iOS 26 / iPadOS 26 SDK+ for upload on or after 2026-04-28 |
| Android runtime target | Android API 24+ unless Flutter, plugin, audio, or product constraints require raising it |
| Google Play target API | Target the Google Play-required API level on upload date |
The App Store / Play Store upload gates are release requirements. They are separate from local development and internal testing requirements.
Architecture Overview
Chanora separates UI, protocol logic, state synchronization, audio processing, diagnostics, and platform services.
Flutter Application
├─ App Shell
├─ Material 3 / Chanora Design System
├─ Feature Modules
├─ View Models / State
└─ Typed Flutter/Rust Bridge
Rust Core
├─ Connection Manager
├─ State Synchronization
├─ Protocol Adapter
├─ Audio Subsystem
├─ Storage Services
└─ Diagnostics
Protocol Layer
└─ tsclientlib
└─ TeamSpeak-compatible server
Key architecture rules:
- Flutter does not call
tsclientlibdirectly. - Protocol-specific types do not leak into the Flutter UI layer.
- Rust Core owns protocol coordination, state synchronization, audio logic, storage services, diagnostics, and bridge-facing DTOs.
- Flutter owns presentation, navigation, Material 3 theming, accessibility, localization presentation, and platform UI behavior.
- Product localization and server-provided content are separated.
- UTF-8 is the internal cross-layer text representation.
- Non-UTF-8 conversion, if needed, occurs only at explicit protocol or platform boundaries.
MVP Direction
The current recommended MVP scope is:
| Area | MVP decision |
|---|---|
| Active server connections | One active server connection per client instance |
| UI baseline | Material 3 + Chanora Design System |
| Product language | English UI first, i18n-ready architecture |
| Server content | Preserve Unicode and do not translate server-provided content |
| Audio processing defaults | Echo Canceller, Automatic Gain Control, Noise Suppression, and High-Pass Filter enabled where supported and stable |
| Audio implementation path | Platform-native first; fallback isolated behind the audio subsystem |
| Local non-secret storage | SQLite or equivalent embedded database |
| Secret storage | Platform secure storage |
| Flutter/Rust bridge | Stable typed bridge with generated or schema-controlled DTOs |
| Diagnostics | Local, user-initiated export only |
| Telemetry | None in MVP |
| Crash reporting | Disabled unless explicitly approved later |
Desktop Push-to-Talk
Chanora's desktop Push-to-Talk (PTT) follows a capability-based design (see
docs/architecture/desktop-ptt-architecture.md).
Focused PTT — the user holds a bound key or mouse button inside the
focused Chanora window — is mandatory on Windows, macOS, and Linux.
Global PTT (recognised while the application is not focused) is
capability-dependent: it requires the operating system, the
user-granted permission set, the display server, and the available
input backend to all permit it.
The application reports a PttCapabilityLevel (L0Focused,
L1GlobalShortcut, L2GlobalHoldToTalk, L3GlobalWithMouseButtons)
that matches actual runtime behaviour, not the platform's theoretical
maximum. The UI capability badge shows the live value.
Per-platform strategy (resolved by owner rulings 2026-05-15, see
docs/governance/product-decision-register.md DEC-023 through
DEC-028):
- Windows — Raw Input first, low-level keyboard hook fallback, Focused PTT terminal fallback. Mouse side buttons supported. P0 / MVP.
- macOS — permission-aware Event Tap with Focused PTT fallback; Global PTT upgrades asynchronously when the user grants Input Monitoring / Accessibility. P0 / MVP.
- Linux — officially tested on GNOME on Wayland using the
org.freedesktop.portal.GlobalShortcutsinterface; every other Linux environment falls back to Focused PTT. Release notes do not claim Global PTT support outside the tested compositor. - Raw key codes, scan codes, virtual-key values, keysyms, and key-press timing sequences are never logged or included in the user-initiated diagnostic export. The diagnostic export carries only capability level, backend identifier, and bound input class.
A missed-key-up watchdog (default 30 s) clears transmit_active
when the OS suppresses a key-up event so a stuck-PTT bug class is
ruled out by construction.
Repository Layout
The repository documentation is expected to live under docs/.
docs/
requirements/
sysrs.md
srs.md
architecture/
sysdes.md
sad.md
sdd.md
verification/
verification-master-plan.md
swe4-unit-verification-plan.md
swe5-software-integration-verification-plan.md
swe6-software-verification-plan.md
sys4-system-integration-verification-plan.md
release/
release-readiness-go-nogo-record.md
platform-release-policy.md
security/
security-privacy-legal-guideline.md
threat-model.md
secure-storage-audit-report.md
diagnostic-redaction-audit-report.md
dependency-and-supply-chain-report.md
privacy/
privacy-policy.md
legal/
trademark-and-attribution-review.md
ui-ux/
material3-guideline.md
material3-design-tokens.md
material3-component-catalog.md
adaptive-layout-platform-guide.md
i18n/
localization-architecture.md
governance/
document-index.md
document-naming-convention.md
traceability-matrix.md
baseline-approval-record.md
baseline-candidate-validation-report.md
document-review-report.md
product-decision-register.md
decision-impact-assessment.md
git-commit-message-convention.md
repo-format-validation-report.md
path-migration-map.md
references/
external-references.md
aspice-swe2-swe3-integration-note.md
Implementation source folders may be added later. A likely structure is:
apps/
chanora_flutter/
core/
chanora_core/
crates/
chanora_protocol/
chanora_audio/
chanora_state/
chanora_storage/
chanora_diagnostics/
chanora_bridge/
The exact implementation layout should be finalized when the repository scaffold is created.
Documentation Entry Points
Start here:
| Topic | Document |
|---|---|
| System requirements | docs/requirements/sysrs.md |
| Software requirements | docs/requirements/srs.md |
| System architecture | docs/architecture/sysdes.md |
| Software architecture | docs/architecture/sad.md |
| Software detailed design | docs/architecture/sdd.md |
| Verification strategy | docs/verification/verification-master-plan.md |
| Release readiness | docs/release/release-readiness-go-nogo-record.md |
| Platform release policy | docs/release/platform-release-policy.md |
| Product decisions | docs/governance/product-decision-register.md |
| Traceability | docs/governance/traceability-matrix.md |
| Security/privacy/legal gates | docs/security/security-privacy-legal-guideline.md |
Engineering Process
Chanora follows this documentation hierarchy:
SysRS -> SysDes -> SRS -> SAD -> SDD
Direct traceability rules:
| Document | Direct upstream source |
|---|---|
| SysDes | SysRS |
| SRS | SysDes only |
| SAD | SRS only |
| SDD | SAD only |
Verification mapping:
SDD -> SWE.4 Unit Verification
SAD + SDD -> SWE.5 Software Integration Verification
SRS -> SWE.6 Software Verification
SysDes -> SYS.4 System Integration Verification
Release readiness is tracked separately through the Go/No-Go record.
Release Readiness
A release is not approved by design documents alone.
Before an external or public release, the project must complete:
docs/release/release-readiness-go-nogo-record.md
The release decision must explicitly state:
Go
Conditional Go
No-Go
Release readiness must include:
- release scope;
- build number;
- commit SHA;
- Git tag;
- artifact hashes;
- satisfied P0/MVP requirements;
- deferred requirements;
- verification results;
- waivers;
- security review status;
- platform readiness;
- legal and OSS review status;
- privacy policy status;
- approval decision and approvers.
Security, Privacy, and Legal Gates
Security, privacy, and legal evidence are required before public or store release.
Required documents include:
docs/security/threat-model.md
docs/security/secure-storage-audit-report.md
docs/security/diagnostic-redaction-audit-report.md
docs/security/dependency-and-supply-chain-report.md
docs/privacy/privacy-policy.md
docs/legal/trademark-and-attribution-review.md
Important gates:
- identity secrets and server passwords must use platform secure storage;
- logs and diagnostic exports must redact secrets;
- diagnostic export must be user-initiated unless a later approved policy changes this;
- dependency licenses and vulnerabilities must be reviewed;
- OSS notices must be prepared where required;
- public wording must not imply official TeamSpeak affiliation;
- privacy policy must describe local storage, diagnostics, permissions, and data handling.
Git Commit Convention
Chanora uses a Conventional Commits style format:
<type>(<scope>): <summary>
Examples:
feat(voice): add push-to-talk state handling
fix(protocol): recover channel tree after reconnect snapshot
docs(sad): add interface catalog and performance view
i18n(ui): add fallback behavior for missing localization keys
sec(diagnostics): redact server password from export bundle
release(android): prepare internal alpha build metadata
See:
docs/governance/git-commit-message-convention.md
Development
Implementation commands will be added after the repository scaffold is finalized.
Expected future commands may include:
flutter pub get
flutter test
cargo test
cargo clippy
cargo fmt
Do not treat these as authoritative until the actual Flutter/Rust workspace has been created.
Contributing
Before making a change:
- Check the affected requirement/design document.
- Confirm the correct traceability layer.
- Use the Git commit convention.
- Update docs and verification plans when the change affects requirements, architecture, detailed design, release behavior, security, privacy, or legal gates.
License
Chanora is dual-licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option. This dual-license model was Accepted on 2026-05-14
as decision DEC-020 in
docs/governance/product-decision-register.md.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Chanora by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.
Third-party software bundled or linked by Chanora is listed in
NOTICE with its own licenses. The complete legal review of
the dependency tree (DEC-012) must complete before any public/store
release. See:
docs/governance/product-decision-register.md
docs/security/dependency-and-supply-chain-report.md
docs/legal/trademark-and-attribution-review.md