opencode/packages/mobile-voice/refactor.md

Mobile Voice Refactor Plan

Goals

• Reduce the surface area of src/app/index.tsx without changing product behavior.
• Make device, network, and monitoring flows easier to reason about.
• Move toward React Native / Expo best practices for state, effects, and file structure.
• Use the new lint warnings as refactor prompts, not as permanent background noise.

Current Pain Points

• DictationScreen currently owns onboarding, permissions, Whisper/model lifecycle, dictation, pairing, server/session sync, relay registration, notification handling, and most UI rendering.
• The screen mixes render-time derived state, imperative refs, polling, persistence, and native cleanup in one place.
• There are many nested conditionals and long derived blocks that are hard to scan.
• Best-effort async cleanup and silent catches make failures harder to understand.

Target Shape

• src/app/index.tsx
  • compose hooks and presentational sections
  • keep only screen-level orchestration
• src/features/onboarding/
  • onboarding step config
  • onboarding UI component
• src/features/dictation/
  • use-whisper-dictation
  • transcript helpers
• src/features/servers/
  • server/session refresh and pairing helpers
  • persisted server state helpers
• src/features/monitoring/
  • foreground SSE monitoring
  • notification payload handling
  • relay registration helpers
• src/lib/
  • parser/validation helpers
  • logger helper for dev-only diagnostics

Refactor Order

Phase 1: Extract pure helpers first

• Move onboarding step text/style selection into a config object or array.
• Move server/session payload parsing into dedicated helpers.
• Keep existing behavior and props the same.

Phase 2: Extract onboarding UI

• Create an OnboardingFlow component that receives explicit state and handlers.
• Keep onboarding persistence in the screen until the UI extraction is stable.

Phase 3: Extract dictation logic

• Move Whisper loading, recording, bulk/realtime transcription, and waveform state into a useWhisperDictation hook.
• Expose a small interface: recording state, transcript, actions, and model status.

Phase 4: Extract server/session management

• Move server restore/save, pairing, health refresh, and active server/session selection into a dedicated hook.
• Centralize server parsing and dedupe logic.

Phase 5: Extract monitoring and notifications

• Move SSE monitoring, push payload handling, and relay registration into a useMonitoring hook.
• Keep side effects close to the feature that owns them.

Phase 6: Lint burn-down

• Replace any with explicit parsed shapes.
• Reduce nested ternaries in favor of config tables.
• Replace ad hoc console.log calls with a logger helper or __DEV__-gated diagnostics.
• Audit bare .catch(() => {}) and convert non-trivial cases to explicit best-effort helpers or real error handling.

Guardrails During Refactor

• Keep one behavior-preserving slice per PR.
• Do not introduce more derived state in useEffect.
• Prefer explicit hook inputs/outputs over hidden cross-hook coupling.
• Only use refs for imperative APIs, subscriptions, and race control.
• Re-run lint after each slice.
• Validate app behavior in the dev client for microphone, notifications, pairing, and monitoring flows.

Exit Criteria

• src/app/index.tsx is mostly screen composition and stays under roughly 800-1200 lines.
• Feature logic lives in focused hooks/components with clearer ownership.
• New payload parsing does not rely on any.
• Lint warnings trend down instead of growing.