# V1 Block 08 — Today Timeline State

Status: Complete

Purpose: Prepare domain/view-state data for the Today timeline without building full Flutter UI yet unless explicitly requested.

## Chunk 8.1 — Timeline item view model

Recommended Codex level: medium

Tasks:

Create a UI-independent timeline item model with fields for:

- display title
- start/end or duration
- task type
- project color token
- background type token
- reward icon token
- difficulty icon token
- explicit time display flag
- quick actions available
- item category that distinguishes task cards from overlays

Rules:

- Thick border color is project class.
- Translucent background is task type.
- Name is text.
- Icon 1 is reward.
- Icon 2 is difficulty.
- Flexible task cards show duration; timeline position shows start/stop.
- Inflexible, critical, and locked show explicit start/end times.
- Timeline state must remain UI-framework-independent.

Acceptance criteria:

- Tests or snapshots can verify field mapping from task to timeline item.
- Tests cover flexible duration display.
- Tests cover explicit time display for inflexible, critical, and locked items.

Completed:

- Added UI-independent timeline item and mapper models in `lib/src/timeline_state.dart`.
- Exported timeline state through `lib/scheduler_core.dart`.
- Added tests for task field/token mapping, flexible duration display, explicit time display, and locked overlay category/no-actions behavior.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

## Chunk 8.2 — Hidden locked block overlay state

Recommended Codex level: medium

Tasks:

Create overlay state for locked blocks:

- hidden by default
- temporary reveal mode
- named blocked-time overlay
- not a normal task block
- overlay item category distinct from task-card category

Acceptance criteria:

- Locked block can produce an overlay item only when reveal mode is active.
- Overlay item is distinguishable from task card item.
- Overlay item shows a name and explicit start/end times.
- Locked overlay does not expose normal task quick actions.

Completed:

- Added locked occurrence overlay mapping behind an explicit `revealHiddenLockedBlocks` flag.
- Hidden locked occurrences return no overlay unless reveal mode is active.
- Visible locked occurrences produce named overlay items with explicit times.
- Locked overlays remain distinct from task cards and expose no normal task quick actions.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

BREAKPOINT: Stop here. Confirm `low` mode before implementing compact mode state.

## Chunk 8.3 — Compact mode state

Recommended Codex level: low

Tasks:

Add domain/app state for manual compact mode:

- Manual toggle only.
- Show current task.
- Show next required task.
- Optionally show next flexible task.
- Hide full timeline unless expanded.

Rules:

- The app must not automatically switch into compact mode after missed/pushed tasks.
- Locked blocks stay hidden in compact mode unless explicitly revealed by a separate overlay action.
- Compact mode should use existing timeline item mapping instead of duplicate display logic where practical.

Acceptance criteria:

- Compact mode flag controls compact output selection.
- Tests cover manual toggle behavior.
- Tests cover compact mode not activating automatically after pushed/missed tasks.
- Tests cover compact mode showing the next required item when one exists.

Completed:

- Added `CompactTimelineState` with a manual compact-mode flag and full-timeline expansion state.
- Added compact selection for current item, next required item, and optional next flexible item using existing timeline item mapping.
- Kept locked items out of compact selection unless separately revealed through overlay state.
- Added tests for manual toggle behavior, pushed/missed tasks not auto-enabling compact mode, next required selection, optional next flexible selection, and locked exclusion.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

BREAKPOINT: Stop here. Confirm `medium` mode before implementing the timeline regression test suite.

## Chunk 8.4 — Timeline state regression test suite

Recommended Codex level: medium

Tasks:

Add or expand tests that protect the timeline mapping rules before Flutter UI work begins.

Cover these cases:

- flexible task card exposes duration, not forced explicit start/end text
- inflexible task card exposes explicit start/end text
- critical task card exposes explicit start/end text
- locked block overlay exposes explicit start/end text only when reveal mode is active
- locked block overlay is not treated as a task card
- project color token maps from project class/border token
- background token maps from task type
- reward icon token handles all five reward levels plus `not set`
- difficulty icon token handles all five difficulty levels
- quick actions map correctly for flexible tasks
- compact mode returns only the intended reduced item set

Rules:

- Do not implement Flutter widgets in this block unless explicitly requested later.
- Timeline models should be easy for Flutter to consume but must not import Flutter.
- Do not mark this chunk complete unless `dart analyze` and `dart test` pass.

Acceptance criteria:

- Timeline test group exists.
- Mapping rules are tested without depending on a UI framework.
- Existing scheduling, backlog, locked-block, and task-action tests still pass.

Completed:

- Expanded timeline regression coverage for all task-type background tokens.
- Added exhaustive reward icon token coverage for every reward level plus `notSet`.
- Added exhaustive difficulty icon token coverage for every difficulty level plus `notSet`.
- Added focused compact-mode reduced-output regression coverage.
- Confirmed existing timeline tests cover flexible duration display, required explicit time display, reveal-gated locked overlays, locked overlay category, project color tokens, and flexible quick actions.
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.

Commit suggestion:

```text
feat(timeline): add today timeline view state models
```
