* FocusTimerController is a Riverpod Notifier that manages the countdown timer state.
* The timer uses Timer.periodic with a 1-second tick interval to update the elapsed duration.
* Timer state includes: targetDuration, elapsedDuration, remainingDuration, and progressPercentage.
* FocusSessionController is a Riverpod AsyncNotifier that orchestrates the full session lifecycle: start (validate permissions → enable DND → start timer → start detection), pause, resume, cancel, and complete.
* On completion, the controller: stops the timer, disables DND, stops detection, calculates the completion score, persists the session to the database, and triggers a widget update.
* Distraction detection during focus mode uses the same UsageStats polling mechanism as social detection but with the focus session's blocked apps list.
* The completion score formula: max(0, (elapsedPercent * 100) - (distractionAttempts * 5)) — each distraction attempt deducts 5 points from the time-based score.
* The controller exposes a stream of FocusSessionState (sealed class) for the UI to react to.
* Tests mock the timer and platform APIs to verify state transitions without real-time delays.
gherkin
Given the FocusSessionController is in idle state
When startSession is called with a valid focus profile and all permissions are granted
Then the state transitions to active with the timer counting and DND enabled
Given a focus session is active with a 25-minute target
When 10 minutes have elapsed
Then the timer state shows 10 minutes elapsed, 15 minutes remaining, and 40% progress
Given a focus session is active
When the user pauses the session
Then the timer stops counting, the state transitions to paused with the current elapsed time, and DND remains active
Given a focus session is paused with 10 minutes elapsed
When the user resumes the session
Then the timer resumes from 10 minutes elapsed and the state transitions back to active
Given a focus session is active and the timer reaches the target duration
When the timer completes
Then the state transitions to completed with the full duration, distraction count, and calculated completion score
Given a focus session is active and 2 distraction attempts have been logged
When the session completes at 100% of target duration
Then the completion score is 90 because 2 attempts deducted 10 points from the 100% time score
Given a focus session is active and the user cancels it
When they confirm the cancellation
Then the timer stops, DND is disabled, the state transitions to completed with the partial elapsed time, and the session is persisted
Given the focus session controller is tested
When timer dependencies are mocked with instant ticks
Then all state transitions can be verified without waiting for real-time delays
Details and Assumptions
Acceptance Criteria