Files
MeshTerm/scripts/ladders/README.md
T
Jean-Pierre MartineauandClaude Opus 5.5 a493a6a5eb Keep the calibration ladders in scripts/ladders, with the method
A ladder draws the candidates for a visual value side by side through
MeshTerm's own renderer and live constants, so JP can choose by eye.
The two that set constants are kept: hue_ladder.py (the node wheel's
lightness, 0.72 on 2026-10-29) and seam_ladder.py (SEAM_BLUR, rebuilt
from the 2026-09-16 tool), with contrast.py for the measurement that
comes first and ladderkit.py for what they share.

launch.ps1 opens a ladder in a new Windows Terminal window and waits
for the ladder's marker file; -Snap also takes a screenshot through
snap.ps1. It avoids the three traps that broke the launches this week:
wt quoting a forwarded command line as one file name, the tab
inheriting Claude Code's NO_COLOR=1, and Rich falling back to the
16-colour console API when virtual terminal processing is off. The
README explains the method and the traps.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 01:10:16 -04:00

114 lines
6.4 KiB
Markdown

# Ladders
A ladder is a small script that draws the candidates for a visual value side by side, in
the user's own terminal, with MeshTerm's own renderer. JP looks at the ladder and chooses
the value. Then the value goes into the code, with the date and a reference to the ladder.
## Why we use ladders
Some values of the visual language are a decision of the eye. Two examples: how far apart
two chip fills must be before the seam between them is solid, and how light the hue of a
node is. A calculation cannot choose such a value. The measures (the OKLab distance, the
APCA contrast) only put limits on it. Also, two terminals with different fonts and colour
settings show the same value differently. Thus the eye of the user, on the user's own
terminal, is the authority.
A ladder makes this decision fast. One look at all the candidates replaces many rounds of
"change it to X and run the app again".
## The method
1. **Measure the problem first.** Find a number that shows the problem, for example the
contrast of each chip (`contrast.py`). The number tells you which values to put on the
ladder. Later, it goes into the comment of the constant and into the commit message.
2. **Draw with the real renderer.** A ladder imports `meshterm` from this checkout and
draws through the same functions as the app (`PathLine`, `node_style`, `_chip_fill`).
It never copies a colour or a rule. Thus the ladder shows what the app will show.
3. **Read the live constants.** Each ladder prints the value that the code has now, and
draws it as one of the rows. An argument moves the value, so that the user can compare
values without an edit.
4. **Draw each candidate in each form that the app draws.** A hue is a chip, a name in a
route, and a name on the page. A seam is solid or thin. Put the difficult cases on the
ladder: the weakest and the strongest hues, and the nearest neighbours.
5. **Put one line of numbers on each candidate.** The numbers do not decide. But they
show what the eye sees, and they let you write the reason in the code.
6. **Let the user choose, in rounds.** The first ladder is wide (for example, a lightness
from 0.70 to 0.85). The next ones are narrower, around the value that the user names.
7. **Write the decision where it is used.** The constant gets the value, the date, "JP on
a ladder", and the path of the ladder. Add the decision to the table below.
## The ladders
| Script | What it draws | Constant | Decisions |
|---|---|---|---|
| `hue_ladder.py` | The node wheel: the HSV wheel of before, the live spectrum, and candidate wheels at one OKLab lightness each, as chips and as names | `theme._NODE_LIGHTNESS` | 0.72 (JP, 2026-10-29) |
| `seam_ladder.py` | Pairs of chips sorted by the OKLab distance of their fills, each with a solid and a thin seam, and a line at the threshold | `pathline.SEAM_BLUR` | 0.06 (JP, 2026-09-16) |
| `contrast.py` | Not a ladder: a table of the contrast between the label and the fill of each node chip (OKLab, WCAG 2, APCA) | | |
`ladderkit.py` holds the parts that all the ladders share: the console that keeps its
colour, and the two contrast measures.
## Run a ladder
In your own terminal, from the root of the repository:
```
python scripts/ladders/hue_ladder.py --L 0.70 0.75
python scripts/ladders/seam_ladder.py --blur 0.08
python scripts/ladders/contrast.py --hsv
```
Each script has `--help`. The terminal must have truecolor and a font with the powerline
glyphs, as for the chips of the app.
## When Claude opens the window
On Windows, Claude Code can open a ladder in a new Windows Terminal window for JP:
```
scripts\ladders\launch.ps1 hue_ladder --L 0.70 0.75
scripts\ladders\launch.ps1 -Snap seam_ladder
```
`launch.ps1` opens the window and waits until the ladder writes its marker file. Then it
prints what the ladder found: the colour system, virtual terminal processing, and if
stdout is the console. With `-Snap`, it also takes a screenshot of the window
(`snap.ps1`). Claude examines that picture before it tells JP that the ladder is ready. In
the new window, `ladder <arguments>` runs the same ladder again with other values. The
path of the checkout must have no spaces (refer to trap 1).
Three traps made the first launches fail. Two sessions met all three on the same night
(2026-10-28 and 2026-10-29), and the second session did not know that the first had solved
them. This folder keeps the solution in one place. The launcher stops each trap:
1. **Windows Terminal gives the command line as one name.** When `wt.exe` sends a new tab
to a window that is already open, it puts quotes around the whole command line. Then
Windows looks for one file whose name is the whole line, and the tab shows the error
0x80070002 ("The system cannot find the file specified"). Thus the tab runs `run.cmd`,
whose path has no spaces, with no arguments. The name of the ladder and its arguments
go in environment variables (`LADDER_NAME`, `LADDER_ARGS`), because the tab gets the
environment of the process that runs `wt.exe`.
2. **The new tab gets the environment of Claude Code.** Claude Code runs its commands with
`NO_COLOR=1`, and Rich removes all colour when it sees that variable. The tab got it
too, so the first ladder was black and white. `run.cmd` and `run.ps1` remove it, and
the console of the ladder sets `no_color=False`.
3. **Rich uses the console API of Windows.** On Windows, Rich examines the console mode
of stdout. When virtual terminal processing is off, Rich does not write ANSI codes. It
uses the console API of Windows, which has 16 colours, and which writes no colour at
all into a capture. `ladderkit.console` turns the processing on and sets
`legacy_windows=False`. Also, `run.ps1` starts Python with `Start-Process
-NoNewWindow`, so that Python writes to the console itself and not to a PowerShell pipe.
The most important lesson is not a trap: **do not tell the user that a window is ready
before you check it.** A launch that fails prints nothing in the shell that started it, and
a ladder with no colour runs with no error. Only the marker file and the screenshot show
the result. On 2026-10-29, Claude told JP two times that the ladder was ready, and each
time it was not.
## Keep them working
The ladders use private names of the package (`_chip_fill`, `_spectrum_colours`,
`_NODE_HUE_SAT`). When the code changes, a ladder can break, and the tests do not run the
ladders. Correct a ladder when you use it again, and keep it in this folder. A new ladder
also goes here, with a row in the table above.