Date: 2025-05-19

This document outlines and validates the behavior of existing Wod.Wiki runtime blocks concerning timer display, UI button changes, and information output. It is based on the core architectural paradigm:

• Blocks: Manage internal state, determine necessary operations based on their type and the workout definition, and emit Actions during their lifecycle events (onEnter, onNext, onLeave) to trigger these operations.
• Actions: Serve as explicit commands that instruct other parts of the system (e.g., the UI, timer module, metrics collector) to update their state or perform specific functions.

The purpose of this document is to ensure a shared understanding and to confirm that current block implementations align with these principles for a consistent and predictable user experience.

The interaction between blocks and the UI (timer, buttons, display text) is governed by the following principles:

1. Explicit Control via Actions: Blocks do not directly manipulate UI components. Instead, they emit specific Actions (e.g., SetClockAction, ShowButtonsAction) that the UI layer interprets and acts upon.
2. Contextual Information: Blocks provide necessary text and context for display (e.g., "Rest", "Push-ups 10 reps", "Round 1/3") through Actions like UpdateDisplayAction.
3. User Agency & Feedback: Buttons displayed are relevant to the current block's state. User interactions with these buttons generate events that the runtime translates into block lifecycle progressions (typically triggering onNext or specific event handlers on the current block), providing clear feedback.

This section details the expected behavior of primary block types based on the paradigm above.

• Role: Manages pauses, pre-start phases, or transitions between distinct workout segments.
• Timer Interaction:
  • onEnter: Emits SetClockAction (e.g., to display 00:00, a pre-start countdown, or paused time). Emits SetTimerStateAction (e.g., PAUSED, STOPPED, COUNTDOWN_PENDING).
• Button Changes:
  • onEnter: Emits ShowButtonsAction with context-appropriate buttons:
    • Pre-start: ['startWorkout']
    • Paused: ['resumeWorkout', 'endWorkout', 'resetWorkout']
    • Between segments: ['startNextSegment']
• Output Reflection:
  • onEnter: Emits UpdateDisplayAction with messages like "Ready?", "Paused", or instructions for the next segment.

• Role: Handles fixed-duration events like rests, timed holds, or segments timed independently (e.g., "For Time" sections).
• Timer Interaction:
  • onEnter: Emits SetClockAction with its defined duration. Emits SetTimerStateAction (e.g., RUNNING_COUNTDOWN or RUNNING_COUNTUP).
  • onLeave (or when timer expires/is skipped): May emit SetTimerStateAction(PAUSED) before transitioning.
• Button Changes:
  • onEnter: Emits ShowButtonsAction, often including ['skipTimer', 'pauseWorkout'].
• Output Reflection:
  • onEnter: Emits UpdateDisplayAction (e.g., "Rest", "Hold: Plank"). The UI will show the live timer based on SetClockAction and SetTimerStateAction.

• Role: Represents tasks completed by user effort, like repetitions of an exercise or covering a distance.
• Timer Interaction:
  • Typically does not emit SetClockAction for its own duration. Relies on the global timer state (e.g., RUNNING_COUNTUP if part of a "For Time" workout, or PAUSED/STOPPED if untimed).
• Button Changes:
  • onEnter: Emits ShowButtonsAction, usually with ['completeEffort', 'pauseWorkout']. The completeEffort button label might vary (e.g., "Next", "Done").
• Output Reflection:
  • onEnter: Emits UpdateDisplayAction with effort details (e.g., "15 Push-ups", "Run 400m").

• Role: Manages complex timed structures like AMRAPs (As Many Rounds/Reps As Possible) or EMOMs (Every Minute On the Minute).
• Timer Interaction:
  • onEnter: Emits SetClockAction for the total duration (AMRAP) or the first interval's duration (EMOM). Emits SetTimerStateAction(RUNNING_COUNTDOWN).
  • onNext (cycling through children or EMOM intervals):
    • For EMOMs, at the start of each new interval: Emits SetClockAction to reset the timer for the interval's duration and SetTimerStateAction(RUNNING_COUNTDOWN).
• Button Changes:
  • onEnter: Emits ShowButtonsAction, typically with ['pauseWorkout']. May also show child-specific buttons or "Next Interval" (for EMOMs if manual advance is an option).
• Output Reflection:
  • onEnter / onNext: Emits UpdateDisplayAction with group information ("AMRAP 20:00", "EMOM - Interval 2/10") and details of the current child block's task.

• Role: Handles structures that involve rounds or repetitions of child blocks.
• Timer Interaction:
  • Generally does not directly control the timer with SetClockAction unless managing explicit timed rests between its rounds (in which case, it might instantiate a child TimerBlock or behave like one for that rest period).
  • Relies on its active child blocks for their specific timer interactions.
• Button Changes:
  • Defers to its current child block for primary action buttons. Consistently allows ['pauseWorkout'].
• Output Reflection:
  • onEnter / onNext (when a new round starts or the active child changes): Emits UpdateDisplayAction (e.g., "Round 3/5") combined with the current child's display information.

• Role: Orchestrates the overall workout from start to finish.
• Timer Interaction:
  • onEnter (often via an initial child IdleBlock): If the workout is designated "For Time" and starts immediately, it might emit SetClockAction(0) and SetTimerStateAction(RUNNING_COUNTUP).
• Button Changes:
  • Delegates to child blocks, typically starting with an IdleBlock that shows ['startWorkout'].
• Output Reflection:
  • Sets up the initial display, then defers to active child blocks for ongoing display updates.

• Role: Manages the workout completion phase.
• Timer Interaction:
  • onEnter: Emits SetTimerStateAction(STOPPED). May also emit SetClockAction to display the final workout time prominently.
• Button Changes:
  • onEnter: Emits ShowButtonsAction with options like ['viewResults', 'resetWorkout', 'newWorkout'].
• Output Reflection:
  • onEnter: Emits UpdateDisplayAction with a completion message (e.g., "Workout Complete!") and potentially a summary of key metrics.

This block-action-UI paradigm ensures the Wod.Wiki timer and interface effectively support the user by providing:

• Clear State Indication: The timer's value and running state (countdown, countup, paused, stopped) directly reflect the current block's requirements and the overall workout phase.
• Contextual Controls: Buttons displayed are always relevant to the current task or state, minimizing confusion and guiding user interaction.
• Guided Progression: UpdateDisplayAction provides clear instructions and information, while the available buttons offer the means to progress through the workout or manage its state.
• Predictability & Consistency: The behavior of each block type is consistent, leading to a learnable and predictable user experience.

The behaviors described above are primarily mediated by the following Action types:

• SetClockAction: Sets the timer's displayed value and potentially its starting point for counting.
• SetTimerStateAction: Controls the timer's operational state (e.g., RUNNING_COUNTDOWN, RUNNING_COUNTUP, PAUSED, STOPPED).
• ShowButtonsAction: Dictates which buttons are visible and active in the UI's button ribbon.
• UpdateDisplayAction: Provides text and contextual information for the main display area (e.g., current exercise, instructions, round count).
• WriteResultAction: Emits a completed ResultSpan (containing metrics and duration) for logging and aggregation, typically triggered by onLeave.

The current architecture and described behaviors of Wod.Wiki's runtime blocks largely align with the robust "Block -> Action -> UI" paradigm. This separation of concerns facilitates clear logic within blocks and allows the UI to react dynamically to state changes commanded by the runtime.

This document serves as a baseline for understanding these interactions. Future work may involve further deep dives into specific complex scenarios or identifying areas for potential refinement or extension.