# V1 Block 08 — Today Timeline State

Status: Planned

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.

## 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.

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.

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.

Commit suggestion:

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