Skip to content

Put the dial's landing rules, Format values and link paths in one place each - #17

Merged
ericchernuka merged 5 commits into
masterfrom
ec/deepen-architecture
Nov 10, 2026
Merged

ericchernuka merged 5 commits into
masterfrom
ec/deepen-architecture

Conversation

@ericchernuka

Copy link
Copy Markdown
Owner

Summary

Three changes from an architecture review. Each one puts a rule in a single place.

The dial lands its own choices. Picker's useCommits decided what a choice does to the link, and world.ts in the verify harness kept a hand-written copy of that logic. Both now call nextLink in motion.ts. The store runs the landing loop itself through a small port, and Picker only plugs the router into it.

 Picker
-  useCommits(dial, color)            # alreadyInUrl, carry pick, announce, navigate().then(landed)
+  useLinkedDial(dial, color)         # router adapter: link, navigate, onTraverse, announce
 dial-motion.ts
   send(event)
     transition(...)                  # pure, unchanged
-    onCommit(commit)  -> Picker
+    nextLink(commit, page.link())    # shared with world.ts deliver
+    page.navigate(next).then(landed)

Announcements moved too. Picks and an agent's choice now set announce on their commit like every other choice, so Picker doesn't decide when to speak.

A colour's Format values leave the Card. The agent tools imported valuesOf and textContrast from color-card/formats.ts, next to the localStorage code.

 src/picker/
+├── formats.ts                 # FORMATS, valuesOf, textContrast
 ├── color-card/
-│   └── formats.ts
+│   └── stored-format.ts       # readFormat, saveFormat
 └── agent/                     # imports ../formats, not the card

A colour's link path is written once. linkPath(color) in color.ts replaces a hand-written route pattern in the agent tools and the page head's template strings. The agent tools no longer need the router. That code only built the link text an agent reads back. Navigation still goes through the dial's jump event.

I looked at a fourth idea and dropped it: giving each dial part intent methods instead of send(event). ADR-0002 already makes the event union the interface. Wrapping it would add a layer without making anything deeper.

There's also a fix to the verify-huebo doctor. It looked for <title>Huebo</title>, which #16 changed, so it failed on master too.

Evidence

  • Before (master): pnpm verify explores 3,700,770 states and fails only on the known open finding ("+, −, router finishes loading → 200° chosen, 205° on screen").
    After: the same 3,700,770 states and the same single finding. Where a commit takes the link is now checked by the real nextLink, not a copy.

  • After: pnpm check passes, with 135 tests. New unit tests cover nextLink (hue already in the link, hue-only keeps the pick, a cleared pick drops it) and linkPath.

  • Browser (agent-browser at 1280×900):

    Action URL history.length Live region
    pick 62/75 on /200 /200/62/75 2 → 3 Picked #4998BF
    same square again /200 4 Selection cleared
    + /205 5 Hue 205 degrees, azure
    Back, Back /200, then /200/62/75
    RGB, then Copy clipboard 73,152,191, stored format RGB
  • Codex review found no actionable defects.

Merge Danger

Door: two-way

It's a refactor with no stored data or URL changes, so a revert is clean.

Blast Radius: announcements

Two screen reader messages change at the edges. If an agent clears the pick at the same hue, it now hears "Selection cleared" instead of "Hue …". If the grid's pick is cleared during a coast, it now hears "Hue …", the hue it lands on. Everything else announces as before. The landing loop moved, so the verify-dial-motion coverage table now points at dial-motion.ts and useLinkedDial.

The rules for what a choice does to the link lived in Picker's
useCommits, and the verify world kept a hand-written copy of them.
Now motion.ts has destination(commit, link), which both the store and
the verify world call. The store runs the landing loop itself through a
small DialPage port, and Picker only plugs the router into it.

Announcements moved with it. A pick and an agent's choice now set
announce on their commit like every other choice, so Picker no longer
decides when to speak.
valuesOf and textContrast describe a colour, not the card, but they
lived in color-card/formats.ts next to the localStorage code. The agent
tools imported them from there, so they depended on the card's
internals and pulled storage in with the maths.

They now live in src/picker/formats.ts, which the card, the agent tools
and anything else can share. The card keeps only the remembered format,
in stored-format.ts. Hex is now built from the RGB already in hand
instead of converting the colour twice.
The agent tools built links through router.buildLocation with the route
pattern written out by hand, and the page head built the same paths
with its own template strings. linkPath in color.ts now writes /hue or
/hue/saturation/brightness, next to the code that parses it, and both
use it. The agent tools no longer need the router at all.
The doctor looked for <title>Huebo</title>, but the home page title is
now "Huebo: Dial in your colour (HSB/HSV picker)", so every doctor run
said the page didn't serve Huebo. It now checks that the title starts
with Huebo.
Comments that only restated the code are gone. destination is now
nextLink, and the port's go is now navigate, so the names say what the
comments did. The verify skill's notes follow the new names.
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
huebo Ready Ready Preview Nov 10, 2026 3:39am UTC

@ericchernuka
ericchernuka merged commit 5342f40 into master Nov 10, 2026
3 checks passed
@ericchernuka
ericchernuka deleted the ec/deepen-architecture branch November 12, 2026 04:01

This branch was successfully deployed

1 active deployment
Preview — dacdbaae Deployed Nov 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant