From 598e53b48892cac366eac8461cc72c8350dfcaeb Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Thu, 29 Oct 2026 01:05:13 -0400 Subject: [PATCH] Node hues share one OKLab lightness, so every name and chip reads alike The spectrum was an HSV wheel at one saturation and value, which is not one lightness to the eye: blue names sat at OKLab L 0.55 and yellow at 0.93. A chip's fill is its label at CHIP_LIGHTNESS of that lightness, so chip contrast followed the label, from APCA Lc 19 on blue to 64 on yellow. Each byte now keeps its HSV hue angle and chroma at OKLab L 0.72, with the chroma fitted where the gamut cannot hold it. JP chose 0.72 on a ladder of wheels from 0.70 to 0.85. Every name reads equally light and every chip lands at Lc 34 to 41. The 256 colours are written out as _NODE_SPECTRUM, because computing them costs about 14 ms here and _IDENTITY_STYLES needs all of them at import, which would slow every start on the handhelds. A test holds the table to _spectrum_hex, and checks one lightness, 256 distinct hues, no console-slot collision, and that each hue angle is kept. Co-Authored-By: Claude Opus 5.5 (1M context) --- CLAUDE.md | 5 ++ meshterm/ui/pathline.py | 10 +++- meshterm/ui/theme.py | 96 +++++++++++++++++++++++++++++++------ tests/test_node_spectrum.py | 47 ++++++++++++++++++ tests/test_oklab.py | 7 ++- 5 files changed, 147 insertions(+), 18 deletions(-) create mode 100644 tests/test_node_spectrum.py diff --git a/CLAUDE.md b/CLAUDE.md index d9456c5..dc2db5d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -556,6 +556,11 @@ as a grouped list does. Filling a page in is editing its `.md`; no Python follow colour that carries no meaning is on its way out. - Node names are always coloured: `name_style(name, key)` palette hue, derived from the node's key (its first byte — any known prefix agrees) so a rename keeps the colour. + The truecolor wheel keeps the old HSV wheel's hue angles at **one OKLab lightness** + (`theme._NODE_LIGHTNESS` 0.72, JP on a ladder, 2026-10-29): HSV ran blue names at L 0.55 + and yellow at 0.93, so chip contrast ran APCA 19–64; now every name reads equally light + and every chip ~34–41. `_NODE_SPECTRUM` is the written-out table (import cost on the + handhelds); `tests/test_node_spectrum.py` holds it to `_spectrum_hex`. One rule on **every** platform; only the resolution changes (see **Platforms**). A surface holding only a name resolves it first (`make_name_key_resolver`); a node no key can place — an unresolved sender, a name two keys used within `name_overlap_days` diff --git a/meshterm/ui/pathline.py b/meshterm/ui/pathline.py index 461f86f..5fcef3f 100644 --- a/meshterm/ui/pathline.py +++ b/meshterm/ui/pathline.py @@ -178,6 +178,10 @@ PATH_INK = "pathline" #: the darker colour leaves the sRGB gamut, because the chroma comes down (refer to #: :func:`~meshterm.ui.oklab.fitted`). A clip there made the greens near ``0x50`` one #: colour. +#: +#: Since 2026-10-29, each hue of the spectrum has the same lightness +#: (:data:`~meshterm.ui.theme._NODE_LIGHTNESS`, ``0.72``). Thus each fill of a node has the +#: same lightness too (``0.43``), and each chip has approximately the same contrast. CHIP_LIGHTNESS = 0.60 @@ -390,8 +394,10 @@ def _style_hex(style: str) -> str | None: #: only visible at one cell, but the user *finds* it without a search: ``0.06``, which is #: three differences that the user can see. A tighter value (``0.035``) left wedges that #: the user must search for. A looser value (``0.10``) blurred pairs whose point still read -#: clearly. ``0.05`` was a little too tight. ``0x10`` of green is ``0.026`` and blurs. -#: ``0x10`` of red is ``0.124`` and does not blur. The two greys, which are ``0.18`` apart, +#: clearly. ``0.05`` was a little too tight. On the HSV wheel of that time, ``0x10`` of +#: green was ``0.026`` and blurred, and ``0x10`` of red was ``0.124`` and did not blur. On +#: the spectrum of one lightness (2026-10-29), they are ``0.016`` and ``0.088``, with the +#: same result. JP set the value on the HSV wheel. The two greys, which are ``0.18`` apart, #: keep their interlock by the metric alone. SEAM_BLUR = 0.06 diff --git a/meshterm/ui/theme.py b/meshterm/ui/theme.py index f8ca044..e7c9f9f 100644 --- a/meshterm/ui/theme.py +++ b/meshterm/ui/theme.py @@ -23,6 +23,7 @@ from rich.console import Console from rich.theme import Theme from ..platforms import Platform, on_platform +from . import oklab from .fontset import FONT_CODEPOINTS, FONTS MESH_THEME = Theme( @@ -585,11 +586,10 @@ def hint_style(border_style: str) -> str: return name if name in MESH_THEME.styles else "muted" -#: The per-node hue *spectrum*. The first key byte of a node maps directly onto the HSV -#: colour wheel. ``0x00`` is red, and the full spectrum goes round to ``0xff``. The -#: saturation and the value are fixed, and they are tuned to stay vivid and readable on -#: the dark theme in all hues. Thus the 256 values of the first byte give 256 different -#: hues on a truecolor terminal. The rule of the whole app is the same on each platform: +#: The per-node hue *spectrum*. The first key byte of a node maps directly onto a colour +#: wheel. ``0x00`` is red, and the full spectrum goes round to ``0xff``. Thus the 256 +#: values of the first byte give 256 different hues on a truecolor terminal (refer to +#: :data:`_NODE_SPECTRUM`). The rule of the whole app is the same on each platform: #: the *name* of a node always has a colour. The colour comes from this wheel, and the key #: of the node selects it (refer to :func:`node_style`). Thus the colour is the identity #: of the node. It stays the same after a rename, and it is the same on each surface that @@ -597,9 +597,78 @@ def hint_style(border_style: str) -> str: #: so "us" never merges into the crowd. The node lists, the chat transcript, the feed of #: the dashboard, and the packet viewer share this wheel. Thus one node has one colour #: everywhere. +#: +#: The hue angle and the chroma of each byte come from the HSV wheel at this saturation +#: and value. Before 2026-10-29, the spectrum was this HSV wheel itself. _NODE_HUE_SAT = 0.65 _NODE_HUE_VAL = 0.95 +#: The lightness of each hue of the spectrum, in OKLab ``L`` (JP, 2026-10-29). The HSV +#: wheel has one saturation and one value, but not one lightness to the eye. Its labels went +#: from ``L`` 0.55 (blue) to 0.93 (yellow). The fill of a path chip is the label at +#: :data:`~meshterm.ui.pathline.CHIP_LIGHTNESS` of its lightness. Thus the contrast of a chip +#: followed the lightness of its label: APCA ``Lc`` 19 for blue and 64 for yellow. With one +#: lightness, each name has the same lightness to the eye, and each chip has approximately +#: the same contrast (``Lc`` 34 to 41). JP chose the value on a ladder of wheels at 0.70 to +#: 0.85 (``scripts/ladders/hue_ladder.py``). +_NODE_LIGHTNESS = 0.72 + + +def _spectrum_hex(byte: int) -> str: + """Calculate the hue of one first key byte. :data:`_NODE_SPECTRUM` holds the results. + + The hue angle and the chroma come from the HSV wheel (:data:`_NODE_HUE_SAT`, + :data:`_NODE_HUE_VAL`). Thus a node keeps the hue that it had on that wheel. The + lightness is :data:`_NODE_LIGHTNESS`. Where the sRGB gamut cannot hold that chroma at + that lightness, :func:`~meshterm.ui.oklab.fitted` lowers the chroma and keeps the hue. + """ + r, g, b = colorsys.hsv_to_rgb(byte / 256, _NODE_HUE_SAT, _NODE_HUE_VAL) + _, a, b_ = oklab.from_hex(f"#{round(r * 255):02x}{round(g * 255):02x}{round(b * 255):02x}") + return oklab.to_hex(oklab.fitted((_NODE_LIGHTNESS, a, b_))) + + +#: The spectrum: :func:`_spectrum_hex` for each first key byte, written out. The +#: calculation takes approximately 14 ms on a desktop, and much more on a handheld, and +#: :data:`_IDENTITY_STYLES` needs all 256 hues at import. Thus the values are fixed here, +#: and ``tests/test_node_spectrum.py`` makes sure that they agree with the calculation. If +#: you change a constant of the spectrum, write the table again from :func:`_spectrum_hex`. +# fmt: off +_NODE_SPECTRUM: tuple[str, ...] = ( + "#ff716d", "#ff716b", "#ff7269", "#ff7266", "#ff7263", "#ff7360", "#fd755e", "#fb775d", # 00 + "#fa795b", "#f77b5a", "#f57d58", "#f47f57", "#f28155", "#ef8353", "#ee8451", "#eb864f", # 08 + "#e9884d", "#e78a4b", "#e58b49", "#e38d46", "#e08f44", "#df9042", "#dc923f", "#da933c", # 10 + "#d8953a", "#d69637", "#d39834", "#d29931", "#cf9b2d", "#cd9c29", "#ca9d25", "#c89f21", # 18 + "#c6a01b", "#c3a114", "#c2a20d", "#bfa400", "#bca500", "#baa600", "#b7a700", "#b5a800", # 20 + "#b3a900", "#b0aa00", "#aeab00", "#acac00", "#a9ad00", "#a8ad00", "#a5ae00", "#a2af00", # 28 + "#a1b000", "#9eb100", "#9bb200", "#98b300", "#96b300", "#93b400", "#90b500", "#8eb600", # 30 + "#8bb700", "#88b700", "#86b800", "#82b900", "#7fba00", "#7cba00", "#79bb00", "#76bc00", # 38 + "#73bc00", "#6fbd00", "#6bbe00", "#68bf00", "#65bf01", "#61c004", "#5dc007", "#5ac10a", # 40 + "#56c10c", "#52c20f", "#4fc210", "#4bc312", "#46c314", "#43c415", "#3ec416", "#39c518", # 48 + "#33c519", "#2fc51a", "#28c61b", "#21c61c", "#1bc61c", "#0fc71d", "#0bc721", "#0ac728", # 50 + "#09c72e", "#08c732", "#07c638", "#06c63d", "#05c640", "#03c645", "#02c64a", "#01c64d", # 58 + "#00c651", "#00c556", "#00c55a", "#00c55d", "#00c561", "#00c565", "#00c468", "#00c46c", # 60 + "#00c470", "#00c473", "#00c377", "#00c37b", "#00c37d", "#00c381", "#00c285", "#00c288", # 68 + "#00c28b", "#00c18e", "#00c192", "#00c195", "#00c098", "#00c09c", "#00c09e", "#00bfa1", # 70 + "#00bfa5", "#00bfa7", "#00beab", "#00beae", "#00beb0", "#00bdb4", "#00bdb7", "#00bcba", # 78 + "#00bcbc", "#00bcbf", "#00bbc2", "#00bbc6", "#0fbac9", "#18b9cb", "#21b8ce", "#28b7d1", # 80 + "#2db7d3", "#32b6d6", "#37b5d9", "#3ab4db", "#3fb3de", "#43b2e1", "#45b1e4", "#49b0e7", # 88 + "#4cafea", "#4faeec", "#52adef", "#55acf2", "#58abf5", "#5aaaf7", "#5ca9fa", "#5fa7fd", # 90 + "#61a6ff", "#66a5ff", "#6ba4ff", "#6ea4ff", "#71a3ff", "#75a2ff", "#77a1ff", "#7aa1ff", # 98 + "#7ca0ff", "#7e9fff", "#809fff", "#829eff", "#849eff", "#859dff", "#879dff", "#889cff", # a0 + "#899cff", "#8a9bff", "#8c9bff", "#8d9bff", "#8f9aff", "#9099ff", "#9398ff", "#9598ff", # a8 + "#9797ff", "#9996ff", "#9b95ff", "#9e94ff", "#9f93ff", "#a292ff", "#a491ff", "#a690ff", # b0 + "#a98fff", "#ab8eff", "#ad8dff", "#b08bff", "#b38aff", "#b589ff", "#b787ff", "#ba86ff", # b8 + "#bd84ff", "#bf83ff", "#c281ff", "#c57fff", "#c77dff", "#ca7bff", "#cd79ff", "#cf77ff", # c0 + "#d275ff", "#d572ff", "#d770ff", "#db6dff", "#de6aff", "#e167ff", "#e464ff", "#e761fe", # c8 + "#e95ffc", "#eb5efb", "#ed5cf9", "#ef5af7", "#f159f6", "#f357f4", "#f457f2", "#f558ee", # d0 + "#f558eb", "#f659e9", "#f75ae5", "#f75ae2", "#f85bdf", "#f85bdc", "#f95cd9", "#fa5cd6", # d8 + "#fa5dd3", "#fb5ecf", "#fb5ecc", "#fc5fc9", "#fd5fc5", "#fd60c2", "#fe60bf", "#fe60bc", # e0 + "#ff61b8", "#ff61b5", "#ff62b2", "#ff64ae", "#ff64ab", "#ff65a8", "#ff66a4", "#ff67a1", # e8 + "#ff689e", "#ff699a", "#ff6a97", "#ff6a94", "#ff6b91", "#ff6c8e", "#ff6c8b", "#ff6d88", # f0 + "#ff6d84", "#ff6e82", "#ff6e7f", "#ff6f7b", "#ff6f79", "#ff7076", "#ff7073", "#ff716f", # f8 +) +# fmt: on + #: The same wheel at the resolution of the PicoCalc console: the six *chromatic bright* #: palette slots. They are in hue order, from red. Thus the index ``round(byte / 256 * 6) #: % 6`` is the sector in which the hue of the byte is. The sectors are 60° apart, and @@ -623,8 +692,8 @@ _NODE_SLOT_HEXES: tuple[str, ...] = ( def node_style(key: str) -> str: """The stable spectrum hue that the *key* of a node selects: the node colour from its hash. - The first key byte of the node maps directly onto the HSV colour wheel (``0x00`` is - red, and the wheel goes round to ``0xff``). Thus the colour is the identity of the + The first key byte of the node maps directly onto a colour wheel (``0x00`` is red, and + the wheel goes round to ``0xff``). Thus the colour is the identity of the node. It stays the same after a rename. Only the first byte selects it, so each prefix that a surface has gives the same hue. A prefix can be a 2-hex path hop, the stored 12-hex id, or the full 64-hex public key. One node has one colour, in whatever way @@ -632,7 +701,7 @@ def node_style(key: str) -> str: The *rule* is the only constant of the platform here, but the resolution is not. The regular platform uses the full spectrum (:func:`_node_style_spectrum`, 256 different - hues at a fixed saturation and value). The PicoCalc snaps the same hue to the nearest + hues at one lightness). The PicoCalc snaps the same hue to the nearest of the six chromatic slots of the console (:func:`_node_style_quantized`). The heat scale of the heard age quantizes its gradient in the same way there. MeshTerm binds this function when the platform switches. @@ -657,9 +726,8 @@ def _key_byte(key: str) -> int: def _node_style_spectrum(key: str) -> str: - """The regular platform: the full 256-hue wheel at :data:`_NODE_HUE_SAT`/``_VAL``.""" - r, g, b = colorsys.hsv_to_rgb(_key_byte(key) / 256, _NODE_HUE_SAT, _NODE_HUE_VAL) - return f"bold #{round(r * 255):02x}{round(g * 255):02x}{round(b * 255):02x}" + """The regular platform: the full 256-hue wheel at one lightness (:data:`_NODE_SPECTRUM`).""" + return f"bold {_NODE_SPECTRUM[_key_byte(key)]}" def _node_style_quantized(key: str) -> str: @@ -679,9 +747,9 @@ def _node_style_quantized(key: str) -> str: #: spectrum and the six chromatic slots of the console. A surface that must *recognize* #: identity ink, and does not make it, matches against this set. Today this is the cursor #: row, where a name gives way to the white of the highlight. Both vocabularies are in the -#: one set. Thus the answer does not depend on the platform that is bound, and the two -#: vocabularies cannot collide: the channels of the spectrum have a maximum of ``0xf2`` -#: (value 0.95), and each console slot has ``0xff``. +#: one set. Thus the answer does not depend on the platform that is bound. The two +#: vocabularies do not collide: no hue of the spectrum is a console slot +#: (``tests/test_node_spectrum.py`` makes sure of it). _IDENTITY_STYLES: frozenset[str] = frozenset( [_node_style_spectrum(f"{byte:02x}") for byte in range(256)] + [f"bold {hex_}" for hex_ in _NODE_SLOT_HEXES] diff --git a/tests/test_node_spectrum.py b/tests/test_node_spectrum.py new file mode 100644 index 0000000..70bd660 --- /dev/null +++ b/tests/test_node_spectrum.py @@ -0,0 +1,47 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Tests for the spectrum of node hues in ``ui/theme.py``: one lightness for each hue.""" + +from __future__ import annotations + +import pytest + +from meshterm.ui import oklab, theme + + +def test_the_written_spectrum_is_the_calculated_one() -> None: + """The fixed table agrees with :func:`theme._spectrum_hex` for each first key byte. + + If this test fails, a constant of the spectrum changed and the table did not. Write the + table again from ``_spectrum_hex``. + """ + assert len(theme._NODE_SPECTRUM) == 256 + assert list(theme._NODE_SPECTRUM) == [theme._spectrum_hex(byte) for byte in range(256)] + + +def test_every_hue_has_the_same_lightness() -> None: + """Each hue has :data:`theme._NODE_LIGHTNESS` to the eye, within the rounding to 8 bits.""" + for colour in theme._NODE_SPECTRUM: + assert oklab.from_hex(colour)[0] == pytest.approx(theme._NODE_LIGHTNESS, abs=0.005) + + +def test_every_hue_is_its_own_and_none_is_a_console_slot() -> None: + """The 256 hues are different, and the spectrum never makes a colour of the console. + + ``is_identity_style`` holds both vocabularies in one set. Thus a spectrum hue that is + also a console slot would make the two vocabularies collide. + """ + assert len(set(theme._NODE_SPECTRUM)) == 256 + assert not set(theme._NODE_SPECTRUM) & set(theme._NODE_SLOT_HEXES) + + +def test_a_node_keeps_the_hue_angle_of_the_hsv_wheel() -> None: + """Only the lightness and the chroma change. The hue angle of each byte is as before.""" + import colorsys + import math + + for byte in range(0, 256, 8): + r, g, b = colorsys.hsv_to_rgb(byte / 256, theme._NODE_HUE_SAT, theme._NODE_HUE_VAL) + _, a0, b0 = oklab.from_hex(f"#{round(r * 255):02x}{round(g * 255):02x}{round(b * 255):02x}") + _, a1, b1 = oklab.from_hex(theme._NODE_SPECTRUM[byte]) + turn = math.remainder(math.atan2(b1, a1) - math.atan2(b0, a0), math.tau) + assert abs(math.degrees(turn)) < 3, f"{byte:02x}" diff --git a/tests/test_oklab.py b/tests/test_oklab.py index c8788d1..fe29ef4 100644 --- a/tests/test_oklab.py +++ b/tests/test_oklab.py @@ -35,7 +35,7 @@ def test_the_wheel_is_not_uniform_to_the_eye() -> None: """One hue step is small in green and large in cyan. This is why the module exists.""" green = oklab.distance(_fill("4c"), _fill("5c")) cyan = oklab.distance(_fill("80"), _fill("90")) - assert green < 0.03 < 0.15 < cyan + assert green < 0.03 < 0.08 < cyan # also on the spectrum of one lightness (2026-10-29) def test_shaded_moves_lightness_alone_away_from_the_nearer_end() -> None: @@ -66,10 +66,13 @@ def test_fitted_lowers_chroma_alone_and_keeps_near_hues_apart() -> None: A colour in the gamut is returned unchanged. The clip in ``to_hex`` made two dark greens near ``0x50`` almost one colour. After the fit, they are clearly two colours. + The two greens are ``0x4c`` and ``0x5c`` of the HSV wheel that the spectrum used before + 2026-10-29. The spectrum of one lightness has less chroma in the greens, so its own + greens leave the gamut less when they are darker. """ inside = oklab.from_hex(_fill("80")) assert oklab.fitted(inside) == inside - darker = [oklab.from_hex(_fill(key)) for key in ("4c", "5c")] + darker = [oklab.from_hex(green) for green in ("#77f255", "#55f26d")] outside = [(lab[0] * 0.6, lab[1], lab[2]) for lab in darker] fits = [oklab.fitted(lab) for lab in outside] clipped = oklab.distance(*(oklab.to_hex(lab) for lab in outside))