# V1 Block 29 — Flutter UI Foundation

**Purpose**: Restart the V1 Flutter UI foundation after the SQLite-first backend
refresh, without moving scheduling or persistence rules into widgets.

> **Note for Codex**: Keep the scheduler core Flutter-free. UI code may depend
> on public package APIs and read models only.

## Chunk 29.1 — Flutter app shell and in-memory composition
Recommended level: **HIGH**

Status: Complete on 2026-06-26.

### Tasks
1. Add `apps/focus_flow_flutter` as a Flutter application outside the root Dart
   workspace for now.
2. Wire a minimal in-memory composition root using public scheduler packages.
3. Render provisional Today and Backlog shells from application/read-model data.
4. Add app startup, theme/token placeholders, and a widget test harness.
5. Document UI-specific analyze/test commands without changing `scripts/test.sh`
   until Flutter CI gating is intentionally added.

### Acceptance criteria
1. `cd apps/focus_flow_flutter && flutter analyze` passes.
2. `cd apps/focus_flow_flutter && flutter test` passes.
3. Core packages remain Flutter-free and `scripts/test.sh` still passes.
4. UI code does not import Drift, SQLite, platform notification APIs, or core
   `lib/src/` paths directly.
5. Today and Backlog screens render from read-model objects, not duplicated
   scheduling rules.

BREAKPOINT: Stop here. Confirm `high` before adding navigation/controllers and
component contracts.

### Completed implementation
1. Added `apps/focus_flow_flutter` as a Flutter desktop app outside the root
   Dart workspace.
2. Added a local path dependency on `packages/scheduler_core`.
3. Replaced the starter counter template with `FocusFlowApp`, a seeded
   `DemoSchedulerComposition`, and Today/Backlog tabs rendered from
   `TodayState` and `BacklogQueryResult`.
4. Added a widget test that verifies Today and Backlog read-model data renders
   through the Flutter shell.
5. Documented app-local Flutter analyze/test commands in the README.

### Verification
1. `flutter pub get` in `apps/focus_flow_flutter`: passed.
2. `dart format apps/focus_flow_flutter/lib/main.dart apps/focus_flow_flutter/test/widget_test.dart`: passed.
3. `cd apps/focus_flow_flutter && flutter analyze`: passed, no issues found.
4. `cd apps/focus_flow_flutter && flutter test`: passed, 1 widget test.

---

## Chunk 29.2 — UI controllers and component contracts
Recommended level: **HIGH**

Status: Complete on 2026-06-26.

### Tasks
1. Split seeded composition, read controllers, and widgets into focused files
   under `apps/focus_flow_flutter/lib/`.
2. Add controller states for loading, empty, typed failure, and retry paths for
   Today and Backlog.
3. Add provisional component contracts for timeline rows, compact panels,
   backlog rows, notice banners, and staleness markers.
4. Centralize token-to-visual mapping for project color, task type background,
   reward icon, and difficulty icon.
5. Add widget tests for compact rendering, backlog empty state, and typed failure
   state.

### Acceptance criteria
1. `cd apps/focus_flow_flutter && flutter analyze` passes.
2. `cd apps/focus_flow_flutter && flutter test` passes.
3. `scripts/test.sh` still passes.
4. Widgets import app controllers/read models, not persistence adapters or
   scheduler internals.
5. Component contracts satisfy the remaining MVP-AC-05 token-mapping gap without
   locking final visual design.

BREAKPOINT: Stop here. Confirm `high` before adding command flows and a vertical
quick-capture smoke slice.

### Completed implementation
1. Split `lib/main.dart` into app shell, seeded composition, read controllers,
   visual-token mapping, and focused widgets under `apps/focus_flow_flutter/lib/`.
2. Added `UiReadController<T>` and `ApplicationReadController<T>` with loading,
   data, empty, typed-failure, and retry states.
3. Added provisional component contracts for compact panels, timeline rows,
   backlog rows, notice banners, staleness markers, empty state, and failure
   state.
4. Centralized project color, task-type background, reward icon, difficulty
   icon, and staleness-marker visual mapping in `SchedulerVisualTokens`.
5. Added widget tests for seeded Today/Backlog rendering, compact rendering,
   Backlog empty state, and typed failure retry.

### Verification
1. `dart format lib test` in `apps/focus_flow_flutter`: passed.
2. `cd apps/focus_flow_flutter && flutter analyze`: passed, no issues found.
3. `cd apps/focus_flow_flutter && flutter test`: passed, 4 widget tests.
4. Forbidden-import scan for app `lib/` and `test/`: no persistence adapters,
   scheduler `src/` imports, Drift, or SQLite imports found.

---

## Chunk 29.3 — Command flows and vertical quick-capture slice
Recommended level: **HIGH**

Status: Open.

### Tasks
1. Add UI controllers for quick capture, schedule-from-backlog, and mark-done
   commands using public application command use cases.
2. Add forms/actions for title-only quick capture, duration entry, and done.
3. Refresh Today and Backlog controllers after successful commands.
4. Add typed conflict/failure states for command attempts.
5. Add a widget/integration smoke test for quick capture → Backlog → schedule →
   Today → done using in-memory composition.

### Acceptance criteria
1. `cd apps/focus_flow_flutter && flutter analyze` passes.
2. `cd apps/focus_flow_flutter && flutter test` passes.
3. `scripts/test.sh` still passes.
4. Widgets continue to call public app controllers/use cases only.
5. No scheduling rules are implemented in Flutter widgets.

BREAKPOINT: Stop here. Confirm `high` before adding persistent SQLite-backed UI
composition or broader screen expansion.

---

---