safe-design 0.0.1__tar.gz

safe_design-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC). There is no PYPI_API_TOKEN
+# secret in this repo, and there should never be one: GitHub mints a short-lived
+# token per run, scoped to this workflow in this repository. Nothing long-lived
+# exists to leak.
+#
+# One-time setup on pypi.org -> Your projects -> Publishing -> Add a pending publisher:
+#   PyPI project name: safe-design
+#   Owner:             rudi193-cmd
+#   Repository:        safe-design
+#   Workflow name:     release.yml
+#   Environment:       (leave blank)
+#
+# Then push a tag: git tag v0.0.1 && git push origin v0.0.1
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest tests/ -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # No `environment:` — the pending publisher on PyPI is configured with the
+    # environment field blank, and the OIDC claim must match it exactly.
+    permissions:
+      id-token: write   # OIDC — this is the entire credential story
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

safe_design-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest tests/ -q
+      - name: Tokens must not import a render engine
+        run: |
+          python - <<'EOF'
+          import sys
+          import safe_design.tokens, safe_design.color, safe_design.text
+          import safe_design.backends.css, safe_design.backends.textual
+          leaked = {"curses", "textual", "rich"} & set(sys.modules)
+          if leaked:
+              raise SystemExit(f"render engine leaked into the token layer: {sorted(leaked)}")
+          print("token layer is render-neutral")
+          EOF

safe_design-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/

safe_design-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Campbell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

safe_design-0.0.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: safe-design
+Version: 0.0.1
+Summary: One token set, many render targets — the SAFE fleet's shared design layer.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# safe-design
+
+One token set, many render targets — the SAFE fleet's shared design layer.
+
+```python
+from safe_design import GROVE, Skin
+from safe_design.backends import css, textual
+
+textual.color("degraded")        # '#ffaf00'
+css.resolve("degraded")          # '#ffaf00'   — same token, same color, by construction
+css.emit_skin(GROVE, selector=":root")
+```
+
+## Why it exists
+
+The palette was already right. It lived in `grove/theme.py`, which imported `curses`
+at module scope — so `grove/theme_textual.py` had to reach across a module boundary
+for a private name (`from grove.theme import _C`) and pay for a terminal library to
+read a dict of integers. Nothing outside Grove could import it at all.
+
+So twenty-one other terminal UIs in `safe-app-store` re-derived it by hand, and the
+fleet's own `tui-design` skill lists *"hardcoded colors clashing with user themes"*
+as pitfall #1 while `story-timeline/app.py` carries sixty of them.
+
+Tokens do not import render engines. Render engines import tokens.
+
+## Layout
+
+| Module | Imports | Role |
+|---|---|---|
+| `tokens.py` | stdlib | the palette, borders, glyphs, agent coloring |
+| `color.py` | stdlib | `xterm256()` — the single index→hex converter |
+| `text.py` | stdlib | cell-width-correct `truncate()` |
+| `backends/curses_backend.py` | `curses` | the only module that imports curses |
+| `backends/textual.py` | stdlib | Textual / Rich colors and markup |
+| `backends/css.py` | stdlib | CSS custom properties, per skin |
+
+## Parity is structural
+
+Both the Textual and CSS backends resolve a token through the same `xterm256()`.
+They cannot disagree, because neither one converts. `test_css_and_textual_agree_on_every_token`
+exists to catch anyone who breaks that.
+
+## Tokens
+
+Base palette lifted verbatim from `grove/theme.py`: `bg`, `input_bg`, `border`,
+`primary`, `secondary`, `accent`, `unread`, `online`, `idle`, `busy`, `healthy`,
+`degraded`, `down`.
+
+SCDS1 §0.4 asks the contract for `grant` / `deny` / `warn` / `meter-fill`. Three of
+those already existed under health names, so they are **aliases**, not new colors:
+
+```
+grant -> healthy    deny -> down    warn -> degraded    meter_fill -> accent
+```
+
+Aliases resolve at **lookup**, never at definition. A skin that repaints `healthy`
+moves `grant` with it. Setting an alias directly is refused:
+
+```python
+GROVE.derive("bbs", grant=10)
+# ValueError: skin 'bbs' overrides alias tokens: ['grant'].
+#             Override the canonical token instead (grant -> healthy).
+```
+
+## Skins
+
+A skin fills the contract; it never extends it. Every token resolves in every skin,
+so a consumer can rely on `--color-warn` existing forever.
+
+```python
+bbs = GROVE.derive("bbs", bg=0, primary=15, accent=14, healthy=10, down=9)
+css.emit_skin(bbs)          # [data-skin="bbs"] { --color-bg: #000000; ... }
+GROVE.ascii()               # same colors, +-| chrome, for TERM=dumb
+```
+
+## Agent identity colors
+
+Hash-derived and stable. The same agent gets the same color forever, and no one
+assigns it.
+
+```python
+textual.agent_color("willow")   # '#87ff87'
+textual.agent_color("hanuman")  # '#5fffff'
+```
+
+## Tests
+
+```
+python3 -m pytest tests/ -q
+```

safe_design-0.0.1/README.md

@@ -0,0 +1,91 @@
+# safe-design
+
+One token set, many render targets — the SAFE fleet's shared design layer.
+
+```python
+from safe_design import GROVE, Skin
+from safe_design.backends import css, textual
+
+textual.color("degraded")        # '#ffaf00'
+css.resolve("degraded")          # '#ffaf00'   — same token, same color, by construction
+css.emit_skin(GROVE, selector=":root")
+```
+
+## Why it exists
+
+The palette was already right. It lived in `grove/theme.py`, which imported `curses`
+at module scope — so `grove/theme_textual.py` had to reach across a module boundary
+for a private name (`from grove.theme import _C`) and pay for a terminal library to
+read a dict of integers. Nothing outside Grove could import it at all.
+
+So twenty-one other terminal UIs in `safe-app-store` re-derived it by hand, and the
+fleet's own `tui-design` skill lists *"hardcoded colors clashing with user themes"*
+as pitfall #1 while `story-timeline/app.py` carries sixty of them.
+
+Tokens do not import render engines. Render engines import tokens.
+
+## Layout
+
+| Module | Imports | Role |
+|---|---|---|
+| `tokens.py` | stdlib | the palette, borders, glyphs, agent coloring |
+| `color.py` | stdlib | `xterm256()` — the single index→hex converter |
+| `text.py` | stdlib | cell-width-correct `truncate()` |
+| `backends/curses_backend.py` | `curses` | the only module that imports curses |
+| `backends/textual.py` | stdlib | Textual / Rich colors and markup |
+| `backends/css.py` | stdlib | CSS custom properties, per skin |
+
+## Parity is structural
+
+Both the Textual and CSS backends resolve a token through the same `xterm256()`.
+They cannot disagree, because neither one converts. `test_css_and_textual_agree_on_every_token`
+exists to catch anyone who breaks that.
+
+## Tokens
+
+Base palette lifted verbatim from `grove/theme.py`: `bg`, `input_bg`, `border`,
+`primary`, `secondary`, `accent`, `unread`, `online`, `idle`, `busy`, `healthy`,
+`degraded`, `down`.
+
+SCDS1 §0.4 asks the contract for `grant` / `deny` / `warn` / `meter-fill`. Three of
+those already existed under health names, so they are **aliases**, not new colors:
+
+```
+grant -> healthy    deny -> down    warn -> degraded    meter_fill -> accent
+```
+
+Aliases resolve at **lookup**, never at definition. A skin that repaints `healthy`
+moves `grant` with it. Setting an alias directly is refused:
+
+```python
+GROVE.derive("bbs", grant=10)
+# ValueError: skin 'bbs' overrides alias tokens: ['grant'].
+#             Override the canonical token instead (grant -> healthy).
+```
+
+## Skins
+
+A skin fills the contract; it never extends it. Every token resolves in every skin,
+so a consumer can rely on `--color-warn` existing forever.
+
+```python
+bbs = GROVE.derive("bbs", bg=0, primary=15, accent=14, healthy=10, down=9)
+css.emit_skin(bbs)          # [data-skin="bbs"] { --color-bg: #000000; ... }
+GROVE.ascii()               # same colors, +-| chrome, for TERM=dumb
+```
+
+## Agent identity colors
+
+Hash-derived and stable. The same agent gets the same color forever, and no one
+assigns it.
+
+```python
+textual.agent_color("willow")   # '#87ff87'
+textual.agent_color("hanuman")  # '#5fffff'
+```
+
+## Tests
+
+```
+python3 -m pytest tests/ -q
+```

safe_design-0.0.1/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "safe-design"
+version = "0.0.1"
+description = "One token set, many render targets — the SAFE fleet's shared design layer."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/safe_design"]

safe_design-0.0.1/src/safe_design/__init__.py

@@ -0,0 +1,41 @@
+"""safe-design — one token set, many render targets.
+
+    from safe_design import GROVE, Skin
+    from safe_design.backends import css, textual
+
+The palette, the borders, the status glyphs, and stable agent coloring live in
+`safe_design.tokens` and import no render engine. Backends read tokens; tokens
+never read backends.
+
+Backends are imported explicitly rather than re-exported here: `curses_backend`
+imports curses, and a web build should not pay for that just by importing the
+package.
+"""
+from __future__ import annotations
+
+from .color import xterm256
+from .text import display_width, truncate
+from .tokens import (
+    GROVE,
+    TOKEN_NAMES,
+    Skin,
+    agent_color_index,
+    agent_fallback_16,
+    agent_slot,
+    status_glyph,
+)
+
+__all__ = [
+    "GROVE",
+    "Skin",
+    "TOKEN_NAMES",
+    "agent_color_index",
+    "agent_fallback_16",
+    "agent_slot",
+    "display_width",
+    "status_glyph",
+    "truncate",
+    "xterm256",
+]
+
+__version__ = "0.0.1"

safe_design-0.0.1/src/safe_design/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Render backends.
+
+Import the one you need. `curses_backend` imports curses; `css` and `textual`
+import nothing beyond the stdlib.
+"""

safe_design-0.0.1/src/safe_design/backends/css.py

@@ -0,0 +1,58 @@
+"""CSS backend — the third render target.
+
+This is the one grove/theme.py never had, and the reason the package exists.
+It emits the same tokens as the curses and Textual backends, converted through
+the same `xterm256()`, so a token cannot mean one color in the terminal and a
+different color on the web.
+
+Output matches the skin contract the Squirrel already ships: `base.css` holds
+structure and names no color; each skin fills `[data-skin="<name>"]` with
+custom properties. The difference is that these are generated, so a token added
+here appears in every skin at once, and cannot be forgotten in one of them.
+"""
+from __future__ import annotations
+
+from ..color import xterm256
+from ..tokens import GROVE, Skin, TOKEN_NAMES
+
+
+def _custom_property(token: str) -> str:
+    """`input_bg` -> `--color-input-bg`."""
+    return f"--color-{token.replace('_', '-')}"
+
+
+def emit_skin(skin: Skin = GROVE, *, selector: str | None = None) -> str:
+    """Emit one skin as a CSS rule of custom properties.
+
+    The default selector is `[data-skin="<name>"]`, matching the Squirrel's
+    inherited contract. Pass `selector=":root"` for the default skin.
+    """
+    sel = selector if selector is not None else f'[data-skin="{skin.name}"]'
+    lines = [f"{sel} {{"]
+    for token in TOKEN_NAMES:
+        lines.append(f"  {_custom_property(token)}: {xterm256(skin.palette[token])};")
+    for edge, glyph in sorted(skin.borders.items()):
+        lines.append(f'  --border-{edge}: "{glyph}";')
+    for state, glyph in sorted(skin.glyphs.items()):
+        lines.append(f'  --glyph-{state}: "{glyph}";')
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def emit_stylesheet(skins: list[Skin], *, default: Skin | None = None) -> str:
+    """Emit `:root` for the default skin plus one rule per named skin."""
+    default = default or (skins[0] if skins else GROVE)
+    parts = [
+        "/* Generated by safe-design. Do not edit by hand.",
+        " * Tokens come from safe_design.tokens; colors from safe_design.color.",
+        " */",
+        "",
+        emit_skin(default, selector=":root"),
+    ]
+    parts.extend(emit_skin(s) for s in skins)
+    return "\n".join(parts)
+
+
+def resolve(token: str, skin: Skin = GROVE) -> str:
+    """Hex string for one token under one skin."""
+    return xterm256(skin.palette[token])

safe_design-0.0.1/src/safe_design/backends/curses_backend.py

@@ -0,0 +1,103 @@
+"""curses backend.
+
+Everything from grove/theme.py that actually needed curses, and nothing else.
+`import curses` lives here, not beside the palette, so a web build never pays
+for a terminal library.
+
+Behaviour is preserved from the original, including the 16-color degradation:
+below 256 colors every semantic pair falls back to white, and the status glyphs
+carry the meaning instead. Color is never the only signal.
+"""
+from __future__ import annotations
+
+import curses
+
+from ..tokens import (
+    _AGENT_FALLBACK_16,
+    _AGENT_PALETTE,
+    GROVE,
+    Skin,
+    agent_slot,
+)
+
+_PAIR: dict[str, int] = {
+    "primary":   20,
+    "secondary": 21,
+    "accent":    22,
+    "unread":    23,
+    "online":    24,
+    "idle":      25,
+    "busy":      26,
+    "healthy":   27,
+    "degraded":  28,
+    "down":      29,
+    "border":    30,
+    "input":     31,
+}
+_AGENT_PAIR_BASE = 40
+
+_CURSES_16 = {
+    "cyan":    curses.COLOR_CYAN,
+    "magenta": curses.COLOR_MAGENTA,
+    "yellow":  curses.COLOR_YELLOW,
+    "green":   curses.COLOR_GREEN,
+    "blue":    curses.COLOR_BLUE,
+    "red":     curses.COLOR_RED,
+}
+
+
+def init_pairs(skin: Skin = GROVE) -> None:
+    if not curses.has_colors():
+        return
+    curses.start_color()
+    curses.use_default_colors()
+    use256 = curses.COLORS >= 256
+
+    for token, pair_id in _PAIR.items():
+        if token == "input":
+            continue
+        fg = skin.palette[token] if use256 else curses.COLOR_WHITE
+        curses.init_pair(pair_id, fg, -1)
+
+    curses.init_pair(
+        _PAIR["input"],
+        skin.palette["primary"] if use256 else curses.COLOR_WHITE,
+        skin.palette["input_bg"] if use256 else -1,
+    )
+
+    for i, idx in enumerate(_AGENT_PALETTE):
+        c = idx if use256 else _CURSES_16[_AGENT_FALLBACK_16[i]]
+        curses.init_pair(_AGENT_PAIR_BASE + i, c, -1)
+
+
+def pair(name: str) -> int:
+    return curses.color_pair(_PAIR.get(name, 0))
+
+
+def agent_pair(name: str) -> int:
+    return _AGENT_PAIR_BASE + agent_slot(name)
+
+
+def safe_addstr(win, y: int, x: int, text: str, attr: int = 0) -> None:
+    if win is None:
+        return
+    h, w = win.getmaxyx()
+    if y < 0 or y >= h or x < 0 or x >= w:
+        return
+    clipped = text[: max(0, w - x)]
+    if not clipped:
+        return
+    try:
+        win.addstr(y, x, clipped, attr)
+    except curses.error:
+        pass
+
+
+def draw_rounded_box(win, y: int, x: int, h: int, w: int, attr: int = 0,
+                     skin: Skin = GROVE) -> None:
+    b = skin.borders
+    safe_addstr(win, y,         x, b["tl"] + b["h"] * (w - 2) + b["tr"], attr)
+    safe_addstr(win, y + h - 1, x, b["bl"] + b["h"] * (w - 2) + b["br"], attr)
+    for row in range(1, h - 1):
+        safe_addstr(win, y + row, x,         b["v"], attr)
+        safe_addstr(win, y + row, x + w - 1, b["v"], attr)

safe_design-0.0.1/src/safe_design/backends/textual.py

@@ -0,0 +1,36 @@
+"""Textual / Rich backend.
+
+Replaces grove/theme_textual.py. Two changes from the original:
+
+1. It reads public tokens instead of reaching for `grove.theme._C`, so it no
+   longer transitively imports curses to look up a dict of integers.
+2. It is skin-aware. The original bound module-level constants at import time;
+   these are functions of a skin, because a fleet with a persona picker needs
+   more than one palette alive in one process.
+"""
+from __future__ import annotations
+
+from ..color import xterm256
+from ..tokens import GROVE, Skin, agent_color_index
+
+
+def color(token: str, skin: Skin = GROVE) -> str:
+    """Hex string for a token, e.g. `color("degraded")` -> `#d78700`."""
+    return xterm256(skin.palette[token])
+
+
+def agent_color(name: str) -> str:
+    """Hex string for an agent's stable identity color."""
+    return xterm256(agent_color_index(name))
+
+
+def markup_bold_accent(skin: Skin = GROVE) -> str:
+    return f"[bold {color('accent', skin)}]"
+
+
+def markup_dim(skin: Skin = GROVE) -> str:
+    return f"[dim {color('secondary', skin)}]"
+
+
+def markup_status_dot(on: bool, skin: Skin = GROVE) -> str:
+    return f"[{color('healthy' if on else 'down', skin)}]{skin.glyphs['online']}[/]"

safe_design-0.0.1/src/safe_design/color.py

@@ -0,0 +1,34 @@
+"""xterm-256 index -> sRGB hex.
+
+Every render backend that needs a hex string calls this. Parity between the
+Textual backend and the CSS backend is therefore structural, not maintained
+by hand: they cannot disagree because they do not each convert.
+
+Lifted verbatim from grove/theme_textual.py::xterm256.
+"""
+from __future__ import annotations
+
+_ANSI_16 = (
+    "#000000", "#800000", "#008000", "#808000", "#000080", "#800080",
+    "#008080", "#c0c0c0", "#808080", "#ff0000", "#00ff00", "#ffff00",
+    "#0000ff", "#ff00ff", "#00ffff", "#ffffff",
+)
+
+
+def xterm256(n: int) -> str:
+    """Convert an xterm-256 palette index to a `#rrggbb` string."""
+    n = int(n)
+    if not 0 <= n <= 255:
+        raise ValueError(f"xterm-256 index out of range: {n}")
+    if n < 16:
+        return _ANSI_16[n]
+    if n < 232:
+        n -= 16
+        r, g, b = n // 36, (n // 6) % 6, n % 6
+
+        def _v(x: int) -> int:
+            return 0 if x == 0 else 55 + x * 40
+
+        return f"#{_v(r):02x}{_v(g):02x}{_v(b):02x}"
+    grey = 8 + (n - 232) * 10
+    return f"#{grey:02x}{grey:02x}{grey:02x}"

safe_design-0.0.1/src/safe_design/text.py

@@ -0,0 +1,56 @@
+"""Cell-width-correct text helpers.
+
+The terminal measures cells, not codepoints. `len()` lies about CJK
+ideographs (width 2), combining marks (width 0), and most emoji (width 2).
+grove/theme.py::truncate used `len()`; this is the corrected form.
+
+stdlib only — `unicodedata` carries the East Asian Width property.
+"""
+from __future__ import annotations
+
+import unicodedata
+
+_WIDE = frozenset(("W", "F"))
+_ELLIPSIS = "..."
+
+
+def char_width(ch: str) -> int:
+    """Terminal cells occupied by a single character."""
+    if unicodedata.combining(ch):
+        return 0
+    if unicodedata.category(ch) == "Cf":  # format chars: ZWJ, RLM, ...
+        return 0
+    return 2 if unicodedata.east_asian_width(ch) in _WIDE else 1
+
+
+def display_width(text: str) -> int:
+    """Terminal cells occupied by a string."""
+    return sum(char_width(c) for c in text)
+
+
+def truncate(text: str, width: int) -> str:
+    """Truncate `text` to at most `width` terminal cells.
+
+    Reserves cells for an ellipsis when there is room for one, matching
+    grove/theme.py's contract (`width <= 5` truncates hard, no ellipsis).
+    Never splits a wide character across the boundary.
+    """
+    if width <= 0:
+        return ""
+    if display_width(text) <= width:
+        return text
+    if width <= 5:
+        return _clip(text, width)
+    return _clip(text, width - len(_ELLIPSIS)) + _ELLIPSIS
+
+
+def _clip(text: str, width: int) -> str:
+    out: list[str] = []
+    used = 0
+    for ch in text:
+        w = char_width(ch)
+        if used + w > width:
+            break
+        out.append(ch)
+        used += w
+    return "".join(out)

safe_design-0.0.1/src/safe_design/tokens.py

@@ -0,0 +1,235 @@
+"""Render-neutral design tokens for the SAFE fleet.
+
+Lifted from grove/theme.py (b17: WDASH). This module MUST NOT import a render
+engine. curses, Textual, and CSS all consume these tokens; none of them owns
+them. That inversion is the whole point of the package: grove/theme.py imported
+curses at module scope, so every consumer of the palette — including the Textual
+backend, which needs no curses at all — paid for a terminal library to read a
+dict of integers.
+
+Token values are xterm-256 palette indices. Two token names may resolve to the
+same index: that is correct. A token names a *meaning*, not a color, and two
+meanings can share a color without being the same token.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping
+
+# ---------------------------------------------------------------------------
+# Base palette — verbatim from grove/theme.py::_C
+# ---------------------------------------------------------------------------
+
+_BASE_PALETTE: dict[str, int] = {
+    # surfaces
+    "bg":        235,
+    "input_bg":  236,
+    "border":    238,
+    # text
+    "primary":   253,
+    "secondary": 245,
+    "accent":    99,
+    "unread":    220,
+    # presence
+    "online":    77,
+    "idle":      243,
+    "busy":      214,
+    # health
+    "healthy":   77,
+    "degraded":  214,
+    "down":      203,
+}
+
+# ---------------------------------------------------------------------------
+# Consent tokens (SCDS1 §0.4)
+#
+# The store console spec asks the contract to grow "status-semantic tokens the
+# console needs and genealogy never did (grant / deny / warn / meter-fill)".
+#
+# Three of the four already exist under presence/health names. They are aliased,
+# not invented — a gate that is granted is a thing that is healthy, and giving
+# it a second index would let the two drift apart for no reason. `meter_fill`
+# is the only genuinely new token; it takes `accent`, which is what the dev
+# sketch's sap-flow gauge already drew.
+# ---------------------------------------------------------------------------
+
+#: alias -> canonical token. Resolved at *lookup*, never baked into a palette:
+#: a skin that overrides `healthy` must move `grant` with it, or the two drift
+#: apart and the alias buys nothing. Overriding an alias directly is an error;
+#: override the canonical token it points at.
+ALIASES: Mapping[str, str] = MappingProxyType({
+    "grant":      "healthy",
+    "deny":       "down",
+    "warn":       "degraded",
+    "meter_fill": "accent",
+})
+
+CANONICAL_TOKENS: tuple[str, ...] = tuple(sorted(_BASE_PALETTE))
+
+# ---------------------------------------------------------------------------
+# Agent identity colors
+# ---------------------------------------------------------------------------
+
+_AGENT_PALETTE: tuple[int, ...] = (87, 213, 227, 120, 111, 209, 51)
+
+#: 16-color fallback, index-aligned with _AGENT_PALETTE. Slots 0 and 6 collide
+#: on cyan; on a 16-color terminal two agents may share a hue. Status glyphs
+#: carry the signal there, per the never-color-alone rule.
+_AGENT_FALLBACK_16: tuple[str, ...] = (
+    "cyan", "magenta", "yellow", "green", "blue", "red", "cyan",
+)
+
+# ---------------------------------------------------------------------------
+# Chrome
+# ---------------------------------------------------------------------------
+
+_BORDERS: dict[str, str] = {
+    "tl": "╭", "tr": "╮", "bl": "╰", "br": "╯", "h": "─", "v": "│",
+}
+
+#: ASCII fallback for TERM=dumb, legacy SSH, and Windows conhost.
+_BORDERS_ASCII: dict[str, str] = {
+    "tl": "+", "tr": "+", "bl": "+", "br": "+", "h": "-", "v": "|",
+}
+
+_STATUS_GLYPHS: dict[str, str] = {
+    "online": "●", "idle": "○", "busy": "◐", "unknown": "·",
+}
+
+_STATUS_GLYPHS_ASCII: dict[str, str] = {
+    "online": "*", "idle": "o", "busy": "+", "unknown": ".",
+}
+
+
+# ---------------------------------------------------------------------------
+# Skin
+# ---------------------------------------------------------------------------
+
+class _Palette(Mapping):
+    """Canonical token values, with aliases resolved on every lookup.
+
+    An alias can never drift from the token it names, because it is not stored.
+    """
+
+    __slots__ = ("_canonical",)
+
+    def __init__(self, canonical: Mapping[str, int]) -> None:
+        self._canonical = dict(canonical)
+
+    def __getitem__(self, token: str) -> int:
+        return self._canonical[ALIASES.get(token, token)]
+
+    def __iter__(self):
+        return iter(tuple(self._canonical) + tuple(ALIASES))
+
+    def __len__(self) -> int:
+        return len(self._canonical) + len(ALIASES)
+
+    def canonical(self) -> Mapping[str, int]:
+        return MappingProxyType(dict(self._canonical))
+
+
+@dataclass(frozen=True)
+class Skin:
+    """A named set of token values.
+
+    A skin does not add or remove tokens — it supplies values for the ones that
+    exist. That is what makes a skin swappable: every consumer can rely on every
+    token resolving, in every skin, forever.
+    """
+
+    name: str
+    palette: Mapping[str, int]
+    borders: Mapping[str, str]
+    glyphs: Mapping[str, str]
+
+    def __post_init__(self) -> None:
+        supplied = self.palette
+        if isinstance(supplied, _Palette):
+            supplied = supplied.canonical()
+        missing = set(CANONICAL_TOKENS) - set(supplied)
+        if missing:
+            raise ValueError(
+                f"skin {self.name!r} is missing tokens: {sorted(missing)}"
+            )
+        aliased = set(supplied) & set(ALIASES)
+        if aliased:
+            raise ValueError(
+                f"skin {self.name!r} sets alias tokens directly: {sorted(aliased)}. "
+                f"Set the canonical token instead ("
+                f"{', '.join(f'{a} -> {ALIASES[a]}' for a in sorted(aliased))})."
+            )
+        object.__setattr__(self, "palette", _Palette(supplied))
+        object.__setattr__(self, "borders", MappingProxyType(dict(self.borders)))
+        object.__setattr__(self, "glyphs", MappingProxyType(dict(self.glyphs)))
+
+    def derive(self, name: str, **overrides: int) -> "Skin":
+        """A new skin, same structure, some token values replaced.
+
+        Overriding a canonical token moves every alias that points at it.
+        """
+        unknown = set(overrides) - set(CANONICAL_TOKENS) - set(ALIASES)
+        if unknown:
+            raise ValueError(
+                f"skin {name!r} defines tokens that do not exist: {sorted(unknown)}. "
+                "A skin fills the contract; it does not extend it."
+            )
+        aliased = set(overrides) & set(ALIASES)
+        if aliased:
+            raise ValueError(
+                f"skin {name!r} overrides alias tokens: {sorted(aliased)}. "
+                f"Override the canonical token instead ("
+                f"{', '.join(f'{a} -> {ALIASES[a]}' for a in sorted(aliased))})."
+            )
+        return Skin(
+            name=name,
+            palette={**self.palette.canonical(), **overrides},
+            borders=self.borders,
+            glyphs=self.glyphs,
+        )
+
+    def ascii(self) -> "Skin":
+        """The same skin with ASCII chrome, for terminals without box drawing."""
+        return Skin(
+            name=f"{self.name}-ascii",
+            palette=self.palette,
+            borders=_BORDERS_ASCII,
+            glyphs=_STATUS_GLYPHS_ASCII,
+        )
+
+
+#: The palette Grove has shipped since April. Every other skin derives from it.
+GROVE = Skin(
+    name="grove",
+    palette=_BASE_PALETTE,
+    borders=_BORDERS,
+    glyphs=_STATUS_GLYPHS,
+)
+
+#: Every token a consumer may resolve — canonical tokens plus their aliases.
+TOKEN_NAMES: tuple[str, ...] = tuple(sorted(set(CANONICAL_TOKENS) | set(ALIASES)))
+
+
+# ---------------------------------------------------------------------------
+# Helpers — render-neutral, no curses
+# ---------------------------------------------------------------------------
+
+def status_glyph(state: str, skin: Skin = GROVE) -> str:
+    return skin.glyphs.get(state, skin.glyphs["unknown"])
+
+
+def agent_slot(name: str) -> int:
+    """Stable slot for an agent name. Same agent, same color, forever."""
+    return int(hashlib.md5(name.encode()).hexdigest(), 16) % len(_AGENT_PALETTE)
+
+
+def agent_color_index(name: str) -> int:
+    """xterm-256 index for an agent's identity color."""
+    return _AGENT_PALETTE[agent_slot(name)]
+
+
+def agent_fallback_16(name: str) -> str:
+    """Named 16-color fallback for an agent, for terminals below 256 colors."""
+    return _AGENT_FALLBACK_16[agent_slot(name)]

safe_design-0.0.1/tests/test_safe_design.py

@@ -0,0 +1,177 @@
+"""safe-design test suite.
+
+Run: python3 -m pytest tests/ -q
+"""
+from __future__ import annotations
+
+import pytest
+
+from safe_design import GROVE, agent_color_index, display_width, truncate, xterm256
+from safe_design.backends import css, textual
+from safe_design.tokens import TOKEN_NAMES, Skin
+
+
+# --------------------------------------------------------------------------
+# Parity — the reason the package exists
+# --------------------------------------------------------------------------
+
+def test_css_and_textual_agree_on_every_token():
+    """A token cannot mean one color in the terminal and another on the web."""
+    for token in TOKEN_NAMES:
+        assert css.resolve(token, GROVE) == textual.color(token, GROVE), token
+
+
+def test_every_token_reaches_the_stylesheet():
+    sheet = css.emit_skin(GROVE)
+    for token in TOKEN_NAMES:
+        assert f"--color-{token.replace('_', '-')}:" in sheet, token
+
+
+# --------------------------------------------------------------------------
+# Values lifted from grove/theme.py must not drift
+# --------------------------------------------------------------------------
+
+@pytest.mark.parametrize("token,index", [
+    ("bg", 235), ("border", 238), ("secondary", 245), ("primary", 253),
+    ("accent", 99), ("unread", 220), ("online", 77), ("idle", 243),
+    ("busy", 214), ("healthy", 77), ("degraded", 214), ("down", 203),
+    ("input_bg", 236),
+])
+def test_base_palette_matches_grove(token, index):
+    assert GROVE.palette[token] == index
+
+
+def test_xterm256_known_conversions():
+    assert xterm256(0) == "#000000"
+    assert xterm256(15) == "#ffffff"
+    assert xterm256(232) == "#080808"
+    assert xterm256(255) == "#eeeeee"
+
+
+def test_xterm256_rejects_out_of_range():
+    with pytest.raises(ValueError):
+        xterm256(256)
+
+
+# --------------------------------------------------------------------------
+# Consent tokens (SCDS1 §0.4) are aliases, not new colors
+# --------------------------------------------------------------------------
+
+def test_consent_tokens_alias_existing_health_tokens():
+    assert GROVE.palette["grant"] == GROVE.palette["healthy"]
+    assert GROVE.palette["deny"] == GROVE.palette["down"]
+    assert GROVE.palette["warn"] == GROVE.palette["degraded"]
+    assert GROVE.palette["meter_fill"] == GROVE.palette["accent"]
+
+
+def test_aliases_follow_the_canonical_token_through_a_derive():
+    """The bug this package was written to prevent, asserted.
+
+    A skin that repaints `healthy` must move `grant` with it. Resolving aliases
+    at definition time silently left `grant` on the parent skin's green.
+    """
+    bbs = GROVE.derive("bbs", healthy=10, down=9, degraded=11, accent=14)
+    assert bbs.palette["grant"] == bbs.palette["healthy"] == 10
+    assert bbs.palette["deny"] == bbs.palette["down"] == 9
+    assert bbs.palette["warn"] == bbs.palette["degraded"] == 11
+    assert bbs.palette["meter_fill"] == bbs.palette["accent"] == 14
+
+
+def test_aliases_stay_in_sync_in_emitted_css():
+    sheet = css.emit_skin(GROVE.derive("bbs", healthy=10))
+    assert "--color-healthy: #00ff00;" in sheet
+    assert "--color-grant: #00ff00;" in sheet
+
+
+def test_overriding_an_alias_directly_is_refused():
+    with pytest.raises(ValueError, match="overrides alias tokens"):
+        GROVE.derive("bad", grant=10)
+
+
+# --------------------------------------------------------------------------
+# Agent identity coloring is stable
+# --------------------------------------------------------------------------
+
+def test_agent_color_is_stable_across_calls():
+    assert agent_color_index("hanuman") == agent_color_index("hanuman")
+
+
+def test_agent_color_index_is_in_the_palette():
+    for name in ("willow", "hanuman", "loki", "skirnir", "jeles", "ada"):
+        assert agent_color_index(name) in (87, 213, 227, 120, 111, 209, 51)
+
+
+# --------------------------------------------------------------------------
+# Skin contract: a skin fills tokens, it never invents them
+# --------------------------------------------------------------------------
+
+def test_derive_overrides_a_token():
+    dos = GROVE.derive("dos", bg=17, accent=11)
+    assert dos.palette["bg"] == 17
+    assert dos.palette["accent"] == 11
+    assert dos.palette["primary"] == GROVE.palette["primary"]
+
+
+def test_derive_rejects_unknown_tokens():
+    with pytest.raises(ValueError, match="do not exist"):
+        GROVE.derive("bad", chartreuse=42)
+
+
+def test_skin_must_supply_every_token():
+    with pytest.raises(ValueError, match="missing tokens"):
+        Skin(name="partial", palette={"bg": 0}, borders=GROVE.borders, glyphs=GROVE.glyphs)
+
+
+def test_skin_palette_is_immutable():
+    with pytest.raises(TypeError):
+        GROVE.palette["bg"] = 1  # type: ignore[index]
+
+
+def test_ascii_skin_swaps_chrome_not_color():
+    a = GROVE.ascii()
+    assert a.borders["tl"] == "+"
+    assert a.glyphs["online"] == "*"
+    assert a.palette["accent"] == GROVE.palette["accent"]
+
+
+def test_derived_skin_emits_its_own_selector():
+    sheet = css.emit_skin(GROVE.derive("bbs", bg=0))
+    assert '[data-skin="bbs"]' in sheet
+    assert "--color-bg: #000000;" in sheet
+
+
+def test_stylesheet_has_root_plus_named_skins():
+    sheet = css.emit_stylesheet([GROVE.derive("dos", bg=17)], default=GROVE)
+    assert ":root {" in sheet
+    assert '[data-skin="dos"]' in sheet
+
+
+# --------------------------------------------------------------------------
+# Cell width — grove/theme.py::truncate used len(); this is the fix
+# --------------------------------------------------------------------------
+
+def test_display_width_counts_cells_not_codepoints():
+    assert display_width("abc") == 3
+    assert display_width("日本語") == 6          # wide: 2 cells each
+    assert display_width("é") == 1          # e + combining acute
+
+
+def test_truncate_never_exceeds_the_cell_budget():
+    assert display_width(truncate("日本語テキスト", 8)) <= 8
+
+
+def test_truncate_does_not_split_a_wide_character():
+    # budget 7 -> "..." (3) + 4 cells -> two wide chars, not two-and-a-half
+    out = truncate("日本語テキスト", 7)
+    assert out.endswith("...")
+    assert display_width(out) <= 7
+
+
+def test_truncate_preserves_grove_contract():
+    assert truncate("abc", 10) == "abc"
+    assert truncate("abcdefgh", 5) == "abcde"     # width <= 5: hard clip
+    assert truncate("abcdefgh", 6) == "abc..."
+
+
+def test_truncate_zero_width():
+    assert truncate("abc", 0) == ""