From 13c7648a65d96d5f13361f49f45c4e8f3679f736 Mon Sep 17 00:00:00 2001 From: Edison Jwa Date: Thu, 11 Jun 2026 09:40:08 +0900 Subject: [PATCH] docs: link orphaned superpowers docs and track Flutter bugs (TODO-033,087) Add docs/superpowers/README.md as index for plans and specs. Add docs/references/flutter-upstream-bugs.md tracking 4 known Flutter framework workarounds. --- docs/references/flutter-upstream-bugs.md | 79 ++++++++++++++++++++++++ docs/superpowers/README.md | 28 +++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/references/flutter-upstream-bugs.md create mode 100644 docs/superpowers/README.md diff --git a/docs/references/flutter-upstream-bugs.md b/docs/references/flutter-upstream-bugs.md new file mode 100644 index 0000000..c53de6d --- /dev/null +++ b/docs/references/flutter-upstream-bugs.md @@ -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. diff --git a/docs/superpowers/README.md b/docs/superpowers/README.md new file mode 100644 index 0000000..84142f3 --- /dev/null +++ b/docs/superpowers/README.md @@ -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. |