focus-flow/Codex Documentation/Current Software Plan/V1_BLOCK_29_Flutter_UI_Foundation.md

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.

---

---