Two days, fifteen tasks, one state machine — building a radar widget the TDD way

The setup

The existing radar widget had three problems we kept hitting:

1. One layer at a time. Users saw radar, clouds, or temperature, but never two at once. Real meteorologists routinely overlay them.
2. The play button froze the UI. A frame load failure during playback would lock the scrubber. Issue #22 had been open for weeks.
3. No diagnostic surface. When a tile provider was slow or refused, users got a generic "couldn't load." We had no way to capture what had actually happened.

The replacement needed to fix all three without rewriting the world. Three open issues, one milestone (#91), and a fresh xl-weatherwidget#26 thread to anchor the work.

The brainstorm pattern

Before any code, the project tried something new — a structured xl-npm-dev-brainstorm pattern. Five questions (Q1 through Q5), each with three to five concrete options, locked one at a time before moving on. The point is to make the design space visible before any implementation pulls you toward an answer.

The five locks:

• Q1: scope — Phase 1 + Phase 2 in a single spec, or staged? We picked the single-spec answer because the layer mechanics, scrubber semantics, and state-machine wiring all need to compose cleanly. Splitting them invites two incompatible designs.
• Q2: layer composition — Free-form layer toggles vs. curated preset views? We picked C: hybrid preset tabs (All Layers / Radar / Clouds / Temperature). Free-form gives users every combination but most combinations are visually noisy; preset tabs encode meteorologically meaningful stacks. The free-form version can land later if anyone asks.
• Q3: scrubber treatment — Slim slider vs. frame-tick visualization? We picked B+C: frame ticks + gradient coloring + absolute timestamps. Twelve ticks (8 past + 1 now + 3 forecast), white→amber→blue gradient, per-frame status icons (✓ ⏳ ✗ —), and absolute-time labels. The scrubber tells you the entire state of the data load, not just where you're scrubbing.
• Q4: state machine semantics — Boolean flags vs. real state machine? We picked the state machine. Specifically a master + per-frame layered design — one machine governs the user-visible lifecycle (Idle → Active → Diagnostic → Closed), and one machine instance per loaded frame handles preload, retry, partial failure. They communicate via events. The freeze-on-play bug was a boolean flag that should have been a transition.
• Q5: diagnostic surface — How does the error report convey the current state of a complex machine? We picked C: hierarchical mermaid snapshot. The error payload includes a mermaid diagram of the master + per-frame machines with the currently active states highlighted. The user sees a literal picture of where the system is when they hit the report button.

Each Q lock took about an hour of back-and-forth. The total brainstorm time was a half-day. None of it was wasted — every option discussed-and-rejected became a single line of justification in the spec, which means no future agent (or future-me) re-litigates the decision without context.

This was the first real run of this brainstorm pattern in our codebase. The thing it taught us: when a brainstorm is structured around explicit option sets (and the rejected options are recorded), the design spec writes itself. The spec doc is just the brainstorm transcript with the rejections moved to a footer.

Pure TypeScript reducers, no xstate

The architectural decision that gets re-argued in every state-machine project: do you take a dependency on xstate (or similar), or do you hand-roll a reducer?

We hand-rolled. Three reasons:

1. Bundle size. xstate is excellent, but it's ~30KB minified for a widget that already lives in a third-party site's HTML. The state machine is small enough — eight master states, four per-frame states — that a (state, event) → state reducer is fewer lines than the imports xstate would need.
2. Test determinism. A pure reducer is just (prevState, event) → nextState. Tests are expect(reducer(s, e)).toEqual(s'). There's no runtime, no actor, no async — just a function. The freeze-on-play regression test (issue #22) is one assertion: expect(reducer({state: "Playing"}, {type: "FRAME_FAILED", frame: 3})).toEqual({state: "Playing", failedFrames: [3]}) — not {state: "Idle"}. The boolean-flag version had been freezing on FRAME_FAILED for weeks; the reducer version refuses to.
3. The diagram generator is just a function over the same machine description. Because the state structure is plain TypeScript types, the same source generates: the reducer, the test fixtures, and the mermaid diagram. There's no separate "render the machine to diagram" step that could drift.

If the machine grows past, say, 20 states or starts needing real concurrency primitives (parallel regions, history states), we'd reconsider. For 8+4 states with one event channel, the reducer is the right tool.

The 15-task plan

Once the spec was locked, the work decomposed into 15 TDD tasks:

T1: package scaffold + types
T2: per-frame state machine (reducer + tests)
T3: master state machine (reducer + tests)
T4: composition test — master observes per-frame events; freeze-on-play regression
T5: useFrameTimeline + materializeTimeline helper
T6: useRadarMachine hook + snapshot()
T7: full hierarchical mermaid snapshot generator
T8: FrameTickScrubber primitive (frame ticks + gradient + abs ts)
T9: PresetTabs + presets.ts (the Q2 hybrid view)
T10: RadarLayer (RainViewer adapter)
T11: CloudsLayer + TemperatureLayer (stubs + Phase 2 provider eval)
T12: temperature-scale-bar component
T13: ErrorReport modal with mermaid snapshot
T14: TelemetryReview gate (mandatory user-confirm)
T15: wire into apps/demo, replace existing radar route

Each task ships in a single commit, with tests, with a code-review pass before the next one starts. The pattern that's emerging:

• Implementer agent writes the task — code first, then tests, then the review applies.
• Review pass catches edge cases the implementer missed — DST handling, the freeze-on-play regression, dead memo dependencies, double-DST golden-hour calculation.
• The fix is a separate commit (refactor(radar-v2): apply T6 review nit — export STATES_INSIDE_ACTIVE).

Two days into the plan, T1 through T9 are done. The visible artifact: a RadarMap component that loads tiles into a layered Leaflet map, drives every layer from a shared FrameTimeline, and renders a frame-tick scrubber whose ticks are styled by per-frame status. Click a frame-tick, the map jumps. Hold a frame-tick, the playback resumes from there. A failed frame shows a red ✗ in the scrubber but doesn't stop playback — the master machine treats per-frame failures as data, not as state transitions, until 33% of frames fail (then the master enters Diagnostic).

The remaining six tasks are layer adapters, scale bar, error report modal, telemetry review gate, and the route swap.

The diagram-snapshot trick

The most fun part of the design is Q5 — the mermaid snapshot.

When the diagnostic modal opens, it calls useRadarMachine().snapshot(). That returns a frozen object describing the entire current world. Inside that object is a mermaid field — a string containing a hierarchical mermaid diagram of the master and per-frame machines. The currently-active states have a :::active style class, so the rendered diagram literally shows where the system is.

stateDiagram-v2
  [*] --> Idle
  Idle --> Active
  state Active {
    LoadingPlaying:::active
    LoadingPaused
    Stable
  }
  Active --> Diagnostic
  Diagnostic --> Active
  Active --> Closed
  Closed --> [*]

  classDef active fill:#fbbf24,stroke:#fbbf24

When a user files an error report, the report includes the mermaid string, the master state JSON, and the per-frame status array. A developer reading the report opens it, sees a literal diagram of where the machine was when the user got frustrated, and can replay the path. What looked like the hardest part of the design turned out to be the cheapest — because the mermaid string is just a function over the machine definition, generating it is a 30-line file.

The sleeper benefit: the same generator drives the documentation. The README's machine diagram and the runtime error-report diagram come from the same source. They cannot drift.

What's been worth saying out loud

• Brainstorm with explicit option sets, lock one at a time. You won't be tempted to relitigate later, and the spec writes itself.
• Reducer beats library for small machines. Until proven otherwise, a (state, event) → state function is cheaper than any state-management dependency you'd reach for, AND it makes tests boringly deterministic.
• Make your machine introspect itself. A diagnostic surface that draws the current state from the same source as the runtime is the cheapest documentation you'll ever maintain.
• TDD with mid-task review is the cadence that works for human + AI pair. The implementer moves fast, the reviewer (today an agent, increasingly a human as the team grows) catches the things the implementer was confidently wrong about. DST math, dead memos, freeze-on-play. None of these found themselves.

Next

T10 onward — the layer adapters and the diagnostic modal. After that, the route swap, and then the radar widget you see at weather.kraftware.dev becomes radar-v2. The existing one-layer-at-a-time radar gets retired without ceremony.

The companion skill in our Claude Code plugin marketplace documents the brainstorm-then-15-task-TDD pattern so the next agent who builds a widget like this gets the playbook on first query. If you want to try the brainstorm structure on something you're building, the spec and plan templates are in xl-weatherwidget/docs/superpowers/.