feat(mindmachine): implement Android MVP app scaffold, session flows, safety gating, and tests

ANDROID_MVP_SPEC.md

@@ -0,0 +1,741 @@
+# MindMachine Android MVP Product Specification
+
+## 1. Product Summary
+MindMachine Android MVP is a native Android app that turns a phone into a simple audiovisual session device. The MVP must let a user safely start a short session using built-in presets, deliver synchronized full-screen visual stimulation plus binaural stereo audio, and allow immediate pause/stop at any time.
+
+This is a prototype for safe, reliable core experience. It is **not** a medical product and must not make medical or therapeutic claims.
+
+---
+
+## 2. MVP Scope
+
+### 2.1 Goals
+The MVP must prove that Android can reliably:
+1. present required safety information before use,
+2. guide the user through headphone + holder setup,
+3. let the user choose a built-in preset,
+4. run a timed session with synchronized visual + audio output,
+5. handle pause, resume, stop, completion, and interruptions safely,
+6. remain usable in low-light, near-eye conditions.
+
+### 2.2 In Scope
+- Android-only native app
+- First-run onboarding and mandatory safety acknowledgment
+- Home screen with built-in presets: **Relax, Focus, Sleep Prep**
+- Session setup screen with limited edits to preset values
+- Active session full-screen experience
+- Pause/resume/stop controls
+- Session completion screen
+- Simple settings screen
+- Audio-only and visual-only toggles
+- Headphone guidance and runtime handling for output changes
+- Keep-screen-awake behavior during session
+- Persistence of acknowledgment state, last selected preset, and basic settings
+
+### 2.3 Explicit Non-Goals for MVP
+- Accounts, sync, cloud backup
+- Custom preset creation/editor
+- Ambient sounds
+- Guided voice narration
+- Printable holder templates
+- Advanced visual editor
+- Session history/analytics
+- Medical/therapeutic workflows
+- iOS version
+- Social/community features
+
+### 2.4 Product Decisions for Ambiguities
+To make MVP implementation-ready, the following are fixed decisions:
+- **Platform:** Android only
+- **Presets shipped:** Relax, Focus, Sleep Prep only
+- **Custom sessions:** Not in MVP
+- **Visual patterns in MVP:** Flash and Pulse/Fade only
+- **Alternating patterns:** Nice-to-have, not MVP
+- **Color use:** Monochrome white-on-black only for MVP to reduce complexity and risk
+- **Brightness control:** App shows recommendation + optional in-app screen-intensity slider that affects in-app render intensity only; app does **not** force system brightness to max
+- **Volume control:** App provides guidance to use device volume; no separate app-owned media mixer UI required for MVP
+- **Headphone requirement:** Stereo headphones strongly required for binaural mode; if no wired/Bluetooth headset route is detected, app blocks starting audio-enabled session and offers Visual-only fallback
+- **Countdown:** Default 5 seconds, user-adjustable in Settings: Off / 5 / 10 seconds
+- **Default session durations:** Relax 10 min, Focus 15 min, Sleep Prep 20 min
+- **Interruption handling:** Any call, audio focus loss, or headphone disconnect pauses session and shows recovery sheet
+
+---
+
+## 3. Information Architecture
+
+### 3.1 Primary Screens
+1. Welcome / Intro
+2. Safety Acknowledgment
+3. Home / Preset List
+4. Session Setup
+5. Active Session
+6. Session Paused Overlay
+7. Interruption / Headphone Warning Sheet
+8. Session Complete
+9. Settings
+10. Holder Guidance
+11. About / Disclaimer (can live inside Settings)
+
+### 3.2 Navigation Model
+- Root stack navigation
+- Default landing after first-run completion: **Home**
+- Main forward path: `Welcome -> Safety -> Home -> Setup -> Active Session -> Complete`
+- Settings and Holder Guidance reachable from Home and Setup
+- During Active Session, user should not navigate elsewhere except via pause/stop/OS interruption handling
+
+### 3.3 Back Navigation Rules
+- Welcome/Safety: Back exits app or returns to previous onboarding step
+- Home: Back exits app
+- Setup: Back returns to Home
+- Active Session: system back disabled or mapped to Pause sheet; must not silently exit session
+- Complete: Back returns Home
+- Settings/Holder Guidance: Back returns to prior screen
+
+---
+
+## 4. User Flows
+
+### 4.1 First-Run Flow
+1. User opens app
+2. Welcome explains what the app does in plain language
+3. User taps Continue
+4. Safety screen shows warnings and disclaimers
+5. User must check acknowledgment box and tap **I Understand**
+6. App stores acknowledgment timestamp/version locally
+7. User lands on Home
+
+If user declines acknowledgment, app remains unusable for sessions and can only show info screens.
+
+### 4.2 Returning User Quick Start
+1. User opens app to Home
+2. User selects preset card
+3. Setup screen opens with preset defaults
+4. User confirms mode and duration
+5. User taps Start
+6. If preflight passes, countdown begins
+7. Active Session starts full-screen
+
+### 4.3 Preflight Check Flow
+Triggered when user taps Start.
+Checks:
+- safety acknowledgment completed
+- at least one stimulation mode enabled (audio or visual)
+- if audio enabled, stereo headphone route available
+- session duration valid
+- app not already in active session
+
+Outcomes:
+- Pass -> countdown
+- Recoverable issue -> inline warning or modal with action
+- Blocking issue -> Start disabled until fixed
+
+### 4.4 Session Flow
+1. Countdown shows 5..1 or selected duration
+2. Session enters full-screen mode
+3. Visual pattern runs if enabled
+4. Audio runs if enabled
+5. Time remaining updates once per second
+6. User may tap screen to reveal controls
+7. User may Pause or Stop any time
+8. If timer reaches zero, session ends automatically and safely
+
+### 4.5 Pause / Resume Flow
+1. User taps screen during session
+2. Minimal controls appear
+3. User taps Pause
+4. Audio and visual engines pause immediately
+5. Paused overlay appears with remaining time
+6. User taps Resume -> 3-second resume countdown -> session restarts
+7. User taps Stop -> confirmation sheet
+
+### 4.6 Stop Flow
+1. User taps Stop from controls or paused state
+2. Confirmation sheet: Stop Session / Cancel
+3. If confirmed, audio stops, visuals stop, wake behavior released, completion screen shown as “Session ended early”
+
+### 4.7 Interruption Flow
+Triggers include call, alarm takeover, audio focus loss, app backgrounding, screen off intent, headphone disconnect.
+1. Session auto-pauses
+2. Stimulation stops immediately
+3. Interruption sheet explains reason
+4. User options:
+   - Resume when safe
+   - End session
+   - Switch to Visual-only if headphone route lost
+5. Session never continues silently after interruption
+
+### 4.8 Completion Flow
+1. Timer reaches zero
+2. Audio/visual output stop immediately
+3. Completion screen shows preset name and session status
+4. Actions: Repeat Session / Return Home
+
+### 4.9 Settings Flow
+User can modify:
+- countdown preference (Off/5/10)
+- default mode preference (Audio+Visual, Audio-only, Visual-only)
+- keep screen on during session (default on, locked on for session regardless)
+- show holder guidance before every session (default off)
+- theme behavior if needed (dark only for MVP preferred)
+- about/disclaimer access
+
+---
+
+## 5. Screen-by-Screen Requirements
+
+## 5.1 Welcome / Intro
+Purpose: orient first-time user.
+
+Content:
+- app name
+- one-sentence explanation
+- short bullet list: blinking light, binaural audio, stereo headphones, not medical
+- Continue button
+
+Behavior:
+- shown only before safety acknowledgment
+- dark theme
+- no session actions available
+
+States:
+- default only
+
+Acceptance notes:
+- readable at standard phone sizes
+- content fits without scroll on common devices where possible
+
+## 5.2 Safety Acknowledgment
+Purpose: mandatory risk disclosure.
+
+Required warnings:
+- flashing lights may be unsafe for people with epilepsy, seizure sensitivity, or migraine triggers
+- do not use while driving, walking, cycling, or operating machinery
+- stop immediately if discomfort, dizziness, headache, nausea, anxiety, or eye strain occurs
+- binaural mode requires stereo headphones
+- app is not a medical device
+
+Components:
+- scrollable warning text
+- acknowledgment checkbox: “I understand the risks and will stop if I feel discomfort.”
+- primary button: I Understand
+- secondary link: Holder Guidance
+
+Behavior:
+- primary button disabled until checkbox checked
+- acknowledgment persisted locally with content version
+
+States:
+- unchecked
+- checked/enabled
+
+## 5.3 Home / Preset Selection
+Purpose: launch point for returning users.
+
+Components:
+- top app bar: title + Settings
+- optional info action: Holder Guidance
+- three preset cards: Relax, Focus, Sleep Prep
+- each card shows duration, pattern type, beat frequency summary, short description
+- optional footer disclaimer: not medical / use safely
+
+Preset copy guidance:
+- Relax: gentle pulse, slower beat
+- Focus: steady flash, alert but conservative beat
+- Sleep Prep: slow pulse, longest duration, low intensity
+
+Behavior:
+- tap card -> Session Setup for selected preset
+- last used preset may show subtle “Last used” badge
+
+States:
+- default loaded
+- empty state not applicable
+- error state only if preset load fails: inline retry + fallback to bundled defaults
+
+## 5.4 Session Setup
+Purpose: confirm and lightly customize before start.
+
+Components:
+- selected preset header
+- editable duration control
+- visual mode section
+- audio mode section
+- headphone status row
+- brightness recommendation row
+- holder guidance link
+- Start button
+
+Editable fields for MVP:
+- duration: preset default, editable within safe range
+- mode toggle: Audio+Visual / Audio-only / Visual-only
+- visual pattern: only if visual enabled and only within preset-supported options
+- blink frequency: adjustable within limited safe range
+- carrier frequency: adjustable within limited range
+- binaural beat difference: adjustable within limited range
+
+Validation ranges (product-level; engineering may refine but must enforce equivalent guardrails):
+- duration: 1 to 30 minutes
+- blink frequency: 1.0 to 20.0 Hz
+- carrier frequency: 80 to 400 Hz
+- binaural beat difference: 0.5 to 20 Hz
+
+Recommended preset defaults:
+- Relax: 10 min, Pulse, 6 Hz visual, 200 Hz carrier, 6 Hz binaural difference
+- Focus: 15 min, Flash, 10 Hz visual, 220 Hz carrier, 10 Hz binaural difference
+- Sleep Prep: 20 min, Pulse, 3 Hz visual, 180 Hz carrier, 3 Hz binaural difference
+
+Behavior:
+- Start disabled if invalid config or no enabled mode
+- if audio is enabled and no headset detected, show blocking warning and CTA: Continue as Visual-only
+- brightness row is advisory text, not a system-permission flow
+- optional “Show holder guidance” interstitial before countdown if setting enabled
+
+Field interaction details:
+- use sliders or stepper controls rather than free-form numeric input where possible
+- if text input is used, numeric keyboard only
+- invalid edits revert or clamp on blur with helper text
+
+States:
+- default
+- invalid field state
+- blocked by missing headphones
+- loading not needed beyond quick preset load
+
+## 5.5 Holder Guidance
+Purpose: give practical safe setup help.
+
+Content blocks:
+- use a simple cardboard visor/holder
+- keep phone stable and hands-free
+- do not press device against eyes/face
+- allow airflow and comfort
+- test fit before session
+- sit or lie down in a safe place
+
+Behavior:
+- accessible from onboarding, Home, Setup
+- dismiss returns to previous screen
+
+## 5.6 Countdown
+Purpose: prepare user before stimulation starts.
+
+Components:
+- full-screen dark background
+- large numeric countdown
+- short text: “Get comfortable. Session starting…”
+- Cancel action
+
+Behavior:
+- start only after preflight passes
+- cancellation returns to Setup
+- audio/visual stimulation does not start until countdown completes
+
+## 5.7 Active Session
+Purpose: core session experience.
+
+Default UI:
+- full-screen stimulation surface
+- overlay hidden by default
+- tapping anywhere reveals controls for 3 seconds, then auto-hides
+
+Overlay controls:
+- Pause/Resume
+- Stop
+- remaining time
+- preset/session name
+
+Visual requirements:
+- black background baseline
+- white flash or white pulse/fade full-screen
+- no extra text while overlay hidden
+- no decorative animation unrelated to session timing
+
+Audio requirements:
+- continuous stereo tone generation when audio enabled
+- no speaker fallback for binaural mode
+
+Behavior:
+- keep screen awake
+- enter immersive full-screen mode
+- prevent accidental exit
+- stop means immediate cessation of stimulation
+- if user locks screen or app backgrounds, auto-pause
+
+States:
+- running with overlay hidden
+- running with overlay shown
+- paused
+- interrupted
+- ending/completing
+
+## 5.8 Paused Overlay
+Components:
+- Paused title
+- remaining time
+- Resume button
+- Stop button
+
+Behavior:
+- stimulation off while paused
+- resume uses 3-second countdown
+
+## 5.9 Interruption / Headphone Warning Sheet
+Triggers:
+- headphones disconnected
+- audio route changed from stereo headset to speaker/unknown
+- incoming call / audio focus loss
+- app backgrounded
+
+Copy must explain exactly what happened and what session modes remain safe.
+
+Actions:
+- Resume Audio+Visual (only if requirements restored)
+- Resume Visual-only
+- End Session
+
+## 5.10 Session Complete
+Components:
+- completion title
+- preset name
+- status message: Completed or Ended early
+- Repeat Session button
+- Return Home button
+
+Behavior:
+- Repeat restarts from Setup with prior values preserved
+- no autoplay into another session
+
+## 5.11 Settings
+MVP contents:
+- countdown preference
+- default session mode
+- show holder guidance before session
+- re-open safety information
+- about/disclaimer
+
+Out of scope in Settings for MVP:
+- account
+- analytics
+- session history
+- downloadable presets
+
+---
+
+## 6. UI Component Specifications
+
+### 6.1 Buttons
+- Minimum touch target: 48x48 dp
+- Primary buttons high contrast
+- Disabled state clearly visible but readable
+- Dangerous action button style for Stop/End Session
+
+### 6.2 Preset Cards
+- Entire card tappable
+- Show title, short description, duration, mode summary
+- Pressed state visible
+- Support accessibility focus order and spoken summary
+
+### 6.3 Toggles / Segmented Controls
+Used for mode selection.
+- Exactly one of: Audio+Visual / Audio-only / Visual-only
+- state change updates dependent controls immediately
+- disabling audio hides or disables headphone validation row
+
+### 6.4 Sliders / Steppers
+Used for duration and frequency values.
+- live value label always visible
+- changes preview in text only, not active stimulation
+- values snap to safe increments
+
+### 6.5 Warnings / Inline Errors
+- concise, direct language
+- use inline messaging near affected control
+- blocking warnings also summarized above Start button
+
+### 6.6 Confirmation Sheets
+Used for Stop and risky state transitions.
+- must not obscure primary action meaning
+- destructive choice clearly labeled
+
+---
+
+## 7. States, Validation, Empty/Error/Loading
+
+### 7.1 Global Loading
+MVP should avoid heavy loading states. All built-in presets ship locally.
+Only acceptable loaders:
+- app startup while loading local preferences
+- brief transition while preparing session engines
+
+### 7.2 Validation Rules
+- at least one stimulation mode must be on
+- duration must be within 1–30 min
+- blink frequency must remain within allowed range
+- carrier frequency and beat difference must remain in allowed range
+- if audio enabled, stereo headset route required before Start and Resume
+- safety acknowledgment required before any session start
+
+### 7.3 Empty States
+- none for Home in normal operation because presets are bundled
+- if preset load fails, show fallback state with Retry and use embedded defaults automatically
+
+### 7.4 Error States
+Handle explicitly:
+- audio engine init failure -> cannot start audio-enabled session; offer Visual-only
+- visual renderer failure -> cannot start visual-enabled session; offer Audio-only
+- headphone disconnect during session -> auto-pause + warning sheet
+- interruption / focus loss -> auto-pause + recovery sheet
+- unexpected session engine failure -> stop safely + show non-technical error message and return options
+
+### 7.5 Recovery Behavior
+- users should always have a safe path to end session
+- app should never continue flashing or playing audio after fatal error
+
+---
+
+## 8. Accessibility Requirements
+1. All non-stimulation screens must support Android screen readers.
+2. Interactive elements must have descriptive labels, roles, and state announcements.
+3. Minimum touch target: 48 dp.
+4. Text contrast must meet WCAG AA on non-session UI.
+5. Text should support dynamic type/font scaling up to at least 200% without loss of critical actions.
+6. Motion outside the stimulation experience should be minimal.
+7. The app must provide **Audio-only** and **Visual-only** session modes.
+8. Safety content must use plain language and short sentences.
+9. Active session controls must remain discoverable and operable with screen reader focus when overlay is shown.
+10. Session must never rely on color alone for meaning.
+11. Any icon-only controls must include accessible text labels.
+12. For users unable to tolerate flashing, app must make Visual-only off-state easy to find before session start.
+
+Note: the stimulation content itself is intentionally flashing/pulsing; accessibility work applies to surrounding UI and availability of safe alternatives.
+
+---
+
+## 9. Data Model and Data Needs
+
+## 9.1 Core Product Models
+
+### SessionPreset
+- id
+- name
+- description
+- defaultDurationSec
+- visualEnabledByDefault
+- audioEnabledByDefault
+- visualPatternType
+- blinkFrequencyHz
+- recommendedIntensityPercent
+- carrierFrequencyHz
+- binauralDifferenceHz
+- cautionNote
+- isBuiltIn
+- sortOrder
+
+### SessionConfig
+- presetId
+- durationSec
+- mode (audioVisual | audioOnly | visualOnly)
+- visualPatternType
+- blinkFrequencyHz
+- intensityPercent
+- carrierFrequencyHz
+- binauralDifferenceHz
+
+### SessionRuntimeState
+- sessionId
+- presetId
+- state (idle | countdown | running | paused | interrupted | completed | stopped | error)
+- startTimeMonotonic
+- elapsedSec
+- remainingSec
+- interruptionReason
+- audioRouteState
+
+### AppSettings
+- safetyAcknowledged
+- safetyAcknowledgedVersion
+- safetyAcknowledgedAt
+- countdownPreference
+- defaultModePreference
+- showHolderGuidanceBeforeSession
+- lastPresetId
+
+## 9.2 Local Data Storage
+Persist locally only:
+- safety acknowledgment state/version
+- app settings
+- last selected preset
+- last-used session values for quick repeat
+- built-in presets (bundled in app, optionally mirrored into local DB/preferences)
+
+No remote backend required for MVP.
+
+## 9.3 Remote Data Needs
+None for MVP.
+If crash reporting or analytics is later added, it must be explicitly reviewed and must not block MVP.
+
+---
+
+## 10. Must-Have vs Nice-to-Have
+
+### 10.1 Must-Have for MVP
+- Android native app
+- first-run intro + mandatory safety acknowledgment
+- built-in presets: Relax, Focus, Sleep Prep
+- Home, Setup, Active Session, Completion, Settings, Holder Guidance
+- audio+visual synchronized session engine
+- pause/resume/stop
+- countdown
+- remaining time display
+- full-screen flash and pulse patterns
+- stereo binaural audio generation
+- headphone-required handling for audio mode
+- interruption-safe auto-pause behavior
+- keep-screen-awake during session
+- local persistence for acknowledgment + settings + last preset
+- audio-only and visual-only modes
+
+### 10.2 Nice-to-Have After MVP
+- alternating visual pattern
+- custom preset editor
+- ambient sound layer
+- session history
+- printable holder template
+- advanced color patterns
+- spoken guidance
+- richer brightness calibration
+
+---
+
+## 11. Risks and Concrete Mitigations
+
+### 11.1 Audio Latency / Instability
+Risk: glitches or startup delay.
+Decision: prioritize stable continuous generation over complex audio features; no ambient mixing in MVP.
+
+### 11.2 Timing Drift Between Audio and Visual
+Risk: UI-driven timing may drift.
+Decision: session timing derived from monotonic clock; visual/audio consume same session timeline.
+
+### 11.3 Device Brightness Variability
+Risk: inconsistent perceived intensity.
+Decision: do not promise exact brightness; expose conservative recommendation and in-app intensity only.
+
+### 11.4 Unsafe Use Without Headphones
+Risk: speaker playback breaks binaural assumptions.
+Decision: block start/resume for audio-enabled session unless stereo headset route is detected; offer Visual-only fallback.
+
+### 11.5 Interruptions
+Risk: call/notification/backgrounding may leave stimulation running.
+Decision: any significant interruption forces immediate pause and explicit resume.
+
+### 11.6 User Comfort / Holder Confusion
+Risk: uncomfortable or unsafe placement.
+Decision: ship concise holder guidance accessible in onboarding and setup; no printable template in MVP.
+
+### 11.7 Scope Creep
+Risk: custom sessions and advanced patterns delay MVP.
+Decision: lock MVP to built-in presets plus limited per-session edits.
+
+---
+
+## 12. Technical Acceptance Criteria
+Engineering should be able to test these directly.
+
+### 12.1 Onboarding / Safety
+1. On first launch, app shows Welcome then Safety before Home.
+2. User cannot access session start flow until safety acknowledgment is completed.
+3. Safety acknowledgment persists across app relaunch.
+4. If safety content version changes, user is asked to acknowledge again.
+
+### 12.2 Presets / Setup
+5. Home displays exactly 3 built-in presets: Relax, Focus, Sleep Prep.
+6. Tapping a preset opens Setup with correct default values.
+7. Setup prevents Start when all stimulation modes are off.
+8. Setup prevents Start when values are outside allowed ranges.
+9. Setup allows duration changes only within 1–30 minutes.
+
+### 12.3 Audio / Headphones
+10. If audio mode is selected and no supported headset route is detected, Start is blocked.
+11. If user chooses Visual-only, session can start without headphones.
+12. During an audio-enabled session, headset disconnect causes session to pause within 1 second and shows recovery UI.
+13. Resuming Audio+Visual is blocked until a valid headset route is restored.
+
+### 12.4 Session Runtime
+14. Starting a valid session enters countdown, then active full-screen mode.
+15. Active session keeps screen awake until pause/stop/completion.
+16. Remaining time updates correctly and reaches zero without negative values.
+17. Pause stops stimulation and preserves remaining time.
+18. Resume restarts from paused remaining time after resume countdown.
+19. Stop ends stimulation immediately and does not resume automatically.
+20. On natural completion, app shows completion screen with Repeat and Return Home.
+
+### 12.5 Interruptions / Safety
+21. App backgrounding during session pauses stimulation immediately.
+22. Incoming call or audio focus loss pauses session immediately.
+23. After interruption, session never resumes without user action.
+24. Fatal engine error stops all stimulation and presents user-safe recovery messaging.
+
+### 12.6 Accessibility / UI
+25. All interactive controls outside active stimulation have accessible labels.
+26. Primary controls meet 48 dp minimum target size.
+27. Non-session text supports system font scaling without clipping primary actions.
+28. Audio-only and Visual-only are available from Setup.
+
+### 12.7 Persistence
+29. Last selected preset persists across app relaunch.
+30. Settings persist across app relaunch.
+31. Completion -> Repeat preloads the just-finished config.
+
+---
+
+## 13. Recommended Content Defaults
+Use concise, plain copy. Avoid wellness hype and all medical claims.
+
+### 13.1 Safety Screen Headline
+“Read before using MindMachine”
+
+### 13.2 Safety Checkbox Copy
+“I understand the risks and will stop immediately if I feel discomfort.”
+
+### 13.3 Headphone Warning
+“Stereo headphones are required for binaural audio. Connect headphones or switch to Visual-only.”
+
+### 13.4 Completion Copy
+- Completed: “Session complete.”
+- Ended early: “Session ended.”
+
+---
+
+## 14. Implementation Notes for Product/UX Alignment
+- Keep non-session UI dark, minimal, and calm.
+- Prefer step-based controls over free text.
+- Avoid deep customization in MVP.
+- During active session, every interaction should reduce cognitive load, not add it.
+- Safety text should be direct, not alarmist.
+- The fastest valid path for a returning user should be: Home -> preset tap -> Start.
+
+---
+
+## 15. Handoff for Andy
+
+### Explicit Implementation Checklist
+- [ ] Build Android-only MVP with screens: Welcome, Safety, Home, Setup, Active Session, Completion, Settings, Holder Guidance
+- [ ] Implement bundled presets: Relax, Focus, Sleep Prep with defaults from this spec
+- [ ] Persist safety acknowledgment version, settings, last preset, and repeat-session config locally
+- [ ] Implement preflight validation for mode selection, parameter ranges, and headphone route
+- [ ] Implement session countdown (Off/5/10 setting; default 5)
+- [ ] Implement full-screen Active Session with hidden overlay controls and tap-to-reveal behavior
+- [ ] Implement Flash and Pulse/Fade monochrome visual patterns only
+- [ ] Implement stereo binaural tone engine with carrier + binaural difference config
+- [ ] Use shared session timeline / monotonic timing source for audio + visual coordination
+- [ ] Implement pause, resume, stop, and natural completion flows
+- [ ] Auto-pause on backgrounding, call/audio focus loss, and headphone disconnect
+- [ ] Block/resume Audio+Visual only when valid stereo headset route is present
+- [ ] Offer Visual-only fallback when audio requirements fail
+- [ ] Keep screen awake during active session and release correctly afterward
+- [ ] Add accessibility labels, minimum touch targets, scalable text, and safe alternative modes
+- [ ] Add test coverage for onboarding gating, setup validation, session transitions, interruption handling, and persistence
+- [ ] Keep all copy non-medical and aligned to the safety wording in this spec
+
+If engineering must cut scope further, preserve in this order: safety gating -> stable session timing -> reliable audio -> full-screen visuals -> interruption handling -> polish.