Date: 2025-05-12

Modernise src/core/runtime/blocks by separating state, behaviour, and UI concerns so that each responsibility is independently testable and extensible. The end-goal is to:

• Remove duplicated logic (logging, result spans, button management).
• Align blocks with the strategy pattern already used elsewhere in the runtime.
• Improve SOLID-ness and unit-test coverage.

A newcomer should be able to follow the sections below, walk through the Kanban board, and complete the refactor.

Note: Move tasks between columns as work progresses. Use ▶️ timestamps in Doing / ✅ timestamps in Closed.

• Potential – Replace console logging with a structured logger (e.g., pino)
• Potential – Auto-generate block metrics via decorators
• Step 8 – Add unit tests for each strategy - Waiting for more strategies to be implemented
• Step 9 – Update runtime & developer docs - Will be done last

• ✅ 2025-05-12T21:30 - Step 1 – Create BlockContext object
• ✅ 2025-05-12T21:35 - Step 2 – Create AbstractBlockLifecycle with template methods
• ✅ 2025-05-12T21:39 - Step 7 – Introduce ResultBuilder utility

Summary: Groups all per-block mutable state so lifecycle methods are stateless and easier to test.

// src/core/runtime/blocks/BlockContext.ts
export interface BlockContext {
  runtime: ITimerRuntime;
  index: number;
  childIndex?: number;
  lastLap?: string;
  spans: ITimeSpan[];
}

Tasks

• Introduce BlockContext type & create instance in each concrete block constructor.
• Replace direct property mutations (this.index++) with ctx.index++.

Tasks

• Mark sources, parent, spans as protected.
• Provide read-only getters where needed.

Summary: Consistent creation of ResultSpan objects.

const span = ResultBuilder
  .forBlock(block)
  .withMetrics(block.sources[0].metrics())
  .build();

Tasks

• Utility under runtime/results/ResultBuilder.ts.
• Replace manual new ResultSpan() constructions.

Tasks

• Update docs/Components/Runtime.md with new class diagram.
• Add migration notes for plugin developers.

• Adhere to SOLID principles at each step.
• Keep PRs small; one major step per PR.
• Ensure CI tests pass after every step.