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))