edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: link orphaned superpowers docs and track Flutter bugs (TODO-033,087)

Browse Source 
Add docs/superpowers/README.md as index for plans and specs.
Add docs/references/flutter-upstream-bugs.md tracking 4 known
Flutter framework workarounds.
This commit is contained in:
Edison Jwa
2026-06-11 09:40:08 +09:00
parent 328776622f
commit 13c7648a65
2 changed files with 107 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/references/flutter-upstream-bugs.md
+79
View File
@@ -0,0 +1,79 @@
# Flutter Framework Upstream Bugs and Workarounds
Tracking document for Flutter framework issues that require Chanora-specific workarounds.
---
## 1. Flutter AdaptiveScaffold Discontinued
**Flutter issue:** [flutter/flutter#162965](https://github.com/flutter/flutter/issues/162965)
**Impact:** Chanora's adaptive 3-panel layout cannot use the built-in `AdaptiveScaffold` widget because it has been discontinued by the Flutter team. A custom breakpoint-based layout system was required.
**Workaround:** Chanora implements its own centralized breakpoint system with three layout classes (compact, medium, expanded) using a custom `LayoutBuilder` approach. The breakpoint constants and layout policy are documented in [docs/ui-ux/adaptive-layout-platform-guide.md](../ui-ux/adaptive-layout-platform-guide.md).
**Relevant code:**
- Design spec: `docs/superpowers/specs/2026-06-05-adaptive-3-panel-layout-design.md`
- Breakpoint thresholds follow Material 3 canonical breakpoints (600dp compact, 840dp medium, ≥1024dp expanded).
**Status:** Workaround in place. No Flutter fix expected; this is a permanent design divergence.
---
## 2. Flutter Lacks Native Audio Session Management
**Flutter issue:** No unified Flutter issue; this is a fundamental platform abstraction gap. Flutter's `audioplayers` and similar packages do not expose per-platform audio session lifecycle (iOS `AVAudioSession`, Android `AudioFocus`, macOS Core Audio).
**Impact:** Chanora must manage audio focus, interruption handling, and route changes natively on each platform and bridge them to Dart via `MethodChannel`.
**Workaround:** Chanora implements platform-specific audio lifecycle management:
| Platform | Native Implementation | Dart Bridge |
|----------|-----------------------|-------------|
| iOS | `AppDelegate.swift` — AVAudioSession category/route/interruption observers | `chanora/ios_audio_lifecycle` MethodChannel |
| Android | `AndroidAudioFocusController.kt` — AudioFocus request/abandon with `OnAudioFocusChangeListener` | `chanora/android_audio_lifecycle` MethodChannel |
| macOS | `MacOSAudioLifecycle` — Core Audio HAL default-device and stream-format change observers | `chanora/macos_audio_lifecycle` MethodChannel |
**Relevant code:**
- Dart dispatcher: `apps/chanora_flutter/lib/services/audio_lifecycle_service.dart`
- iOS native: `apps/chanora_flutter/ios/Runner/AppDelegate.swift`
- Android native: `apps/chanora_flutter/android/app/src/main/kotlin/app/chanora/chanora_flutter/AndroidAudioFocusController.kt`
- macOS native: `apps/chanora_flutter/macos/`
**Status:** Ongoing. Each platform's MethodChannel handler catches and swallows errors from the Rust side to prevent exception propagation back through the platform framework (a Flutter restriction on `MethodChannel` handlers).
---
## 3. macOS Default-Device Change Not Exposed to Flutter
**Flutter issue:** No Flutter issue filed. Flutter's desktop audio support does not expose Core Audio HAL default-input/output device change notifications.
**Impact:** When the user changes the default audio device on macOS (e.g., plugging in headphones), the Chanora audio engine does not automatically rebind to the new device.
**Workaround:** The macOS `MethodChannel` (`chanora/macos_audio_lifecycle`) receives `handleDefaultDeviceChange` and `handleConfigurationChange` events from native Swift code, but the corresponding Rust-side FRB bridge function (`macosDefaultDeviceChanged`) is not yet exposed via `flutter_rust_bridge`. Events are captured and logged for observability only.
**Relevant code:**
- `apps/chanora_flutter/lib/services/audio_lifecycle_service.dart:150-157` — macOS handler with TODO markers
- `apps/chanora_flutter/lib/services/audio_lifecycle_service.dart:151` — `// TODO: call rust.macosDefaultDeviceChanged() once exposed`
**Status:** Partial workaround. Requires `flutter_rust_bridge` update to expose the Rust function.
---
## 4. iOS Audio Session Activation Ordering
**Flutter issue:** No Flutter issue filed. Flutter does not provide a mechanism to coordinate audio session activation with network connection establishment.
**Impact:** On iOS, the `AVAudioSession` must be activated before the voice channel join RPC, and deactivated on failure. Without careful ordering, audio may be left in an active state after a failed join, or the session may not be active when the audio engine starts.
**Workaround:** Chanora implements an explicit ordering function `joinVoiceChannelWithIosAudioSession` that activates the iOS audio session, attempts the voice join, and deactivates on failure. A `VoiceJoinSuccessPredicate` allows callers to treat certain errors (e.g., "already in channel") as successful joins, keeping the audio session active.
**Relevant code:**
- `apps/chanora_flutter/lib/services/voice_join_ordering.dart` — Full implementation
- The `activateIosAudioSession`/`deactivateIosAudioSession` callbacks are provided by the iOS native side via `AppDelegate.swift`.
**Status:** Workaround in place. This is an inherent platform design requirement rather than a Flutter bug.
docs/superpowers/README.md
+28
View File
@@ -0,0 +1,28 @@
# Superpowers — Plans and Specs Index
Implementation plans and design specifications produced during Chanora development.
## Plans
| Plan | Date | Summary |
|------|------|---------|
| [Server Resolution Prefetch](plans/2026-05-28-server-resolution-prefetch.md) | 2026-05-28 | Add invisible server-address resolution prefetch so the active host field can warm Rust resolver state before Connect. |
| [Chanora Server Prefetch Crate](plans/2026-05-28-chanora-server-prefetch-crate.md) | 2026-05-28 | Move server-resolution prefetch policy from `chanora_core` into a focused `chanora_prefetch` crate. |
| [Finish DV Document Tree](plans/2026-05-29-finish-dv-document-tree.md) | 2026-05-29 | Fill the README-advertised document tree with baseline candidate documents for DV reviewers. |
| [DV Evidence Pack](plans/2026-05-29-dv-evidence-pack.md) | 2026-05-29 | Create a document set for DV meeting review of verification posture, traceability, release blockers, and waivers. |
| [SWE.2/SWE.3 Baselines](plans/2026-05-29-swe2-swe3-baselines.md) | 2026-05-29 | Add reviewable SWE.2/SAD and SWE.3/SDD baselines for the DV document chain. |
| [State Sync and UI Settings Validation](plans/2026-05-29-state-sync-ui-settings-validation.md) | 2026-05-29 | Complete validation-backed state-sync evidence and UI settings persistence. |
| [Chat Panel Switching](plans/2026-06-06-chat-panel-switching.md) | 2026-06-06 | Enable in-place conversation switching in the 3-panel layout with per-conversation draft persistence and unread awareness. |
| [Core Internal Split](plans/2026-06-08-core-internal-split.md) | 2026-06-08 | Move stable event DTOs and network diagnostic state out of the oversized `chanora_core/lib.rs`. |
| [Maintainability Continuation](plans/2026-06-08-maintainability-continuation.md) | 2026-06-08 | Continue maintainability review with safe simplifications, code-review remediation, documentation, and fail-safe evidence. |
## Specs
| Spec | Date | Summary |
|------|------|---------|
| [Server Resolution Prefetch Design](specs/2026-05-28-server-resolution-prefetch-design.md) | 2026-05-28 | Design for invisible server-address resolution prefetch. |
| [Chanora Server Prefetch Crate Design](specs/2026-05-28-chanora-server-prefetch-crate-design.md) | 2026-05-28 | Design for extracting prefetch policy into `chanora_prefetch` crate. |
| [State Sync and UI Settings Validation Design](specs/2026-05-29-state-sync-ui-settings-validation-design.md) | 2026-05-29 | P0/P1 validation-based completion for state-sync evidence and UI settings persistence. |
| [Adaptive 3-Panel Layout Design](specs/2026-06-05-adaptive-3-panel-layout-design.md) | 2026-06-05 | Desktop adaptive layout for ≥1024dp three-panel mode with centralized breakpoint system. |
| [Maintainability Continuation Design](specs/2026-06-08-maintainability-continuation-design.md) | 2026-06-08 | Design for continued maintainability pass, code-review remediation, and high-risk bug fixes. |
| [Poke Without Message Design](specs/2026-06-09-poke-without-message-design.md) | 2026-06-09 | Allow TeamSpeak-compatible pokes without message text while blocking empty messages for normal chat. |