focus-flow/Codex Documentation/Archived plans/V1_BLOCK_08_Today_Timeline_State_UPDATED.md

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:

feat(timeline): add today timeline view state models