codefig 0.17.0__py3-none-any.whl

codefig/styles.py

@@ -0,0 +1,893 @@
+"""Themes: visual defaults, the active-theme context and size/stroke roles.
+
+Two built-in themes ship (see :mod:`codefig.themes`):
+
+* ``"paper"`` (the default since 0.6.0) — print-size research-figure look: units are
+  **pt at final print size**, three font-size roles (6 / 7 / 8 pt), strokes
+  0.6 / 0.75 / 1.2 pt, Okabe-Ito-derived fills (``oi_fill4``), stealth arrowheads.
+* ``"classic"`` — the pre-0.6 screen look (13 px text, 2 px strokes); ``Theme()``
+  with no arguments is the classic theme, so old code that builds ``Theme(...)``
+  or ``replace(DEFAULT_THEME, ...)`` keeps its look.
+
+Nodes do not freeze a theme at construction: ``node.theme`` is the explicitly passed
+theme, else the *active* theme (:func:`use_theme`, entered by ``Figure`` around layout
+and rendering), else the global default (:func:`set_theme`).
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Any, Dict, Iterator, List, Mapping, Optional, Sequence, Tuple, Union
+
+PadSpec = Union[float, int, Sequence[float]]
+
+
+@dataclass(frozen=True)
+class Theme:
+    box_rounded: bool = False
+    category_stroke: Optional[float] = None
+    stroke: str = "#111111"
+    stroke_width: float = 2.0
+    font_family: str = "'Noto Sans CJK SC', 'Noto Sans CJK JP', DejaVu Sans, Helvetica, Arial, sans-serif"
+    mono_family: str = "DejaVu Sans Mono, Menlo, Consolas, monospace"
+    font_size: float = 13.0
+    typeface: str = "sans"  # sans | serif — drives measurement *and* SVG font-family
+    title_size: float = 16.0
+    panel_title_size: float = 13.0
+    caption_size: float = 12.0
+    fill_default: str = "#ffffff"
+    fill_prompt: str = "#cfe8cf"
+    fill_response: str = "#f5e6a8"
+    fill_block: str = "#e8e8e8"
+    fill_attn: str = "#f5c48a"
+    fill_ffn: str = "#7eb6e8"
+    fill_q: str = "#c9b3e6"
+    fill_k: str = "#f0b080"
+    fill_v: str = "#7eb6e8"
+    highlight: str = "#c0392b"
+    # Spacing (roomier defaults — text/labels were too tight at 8)
+    pad: float = 10.0
+    fit_font_scale: float = 1.0
+    gap_scale: float = 1.0
+    pad_scale: float = 1.0
+    gap: float = 12.0
+    label_gap: float = 8.0  # Matrix/Group external label ↔ shape
+    title_gap: float = 8.0  # Container title ↔ children / border
+    text_margin: float = 2.0  # extra inset for text inside Box (on top of pad)
+    edge_label_gap: float = 6.0
+    corner_radius: float = 8.0
+    panel_gap: float = 14.0
+    panel_pad: float = 14.0
+    frame_stroke: float = 2.5
+    # Connector defaults (Edge / Arrow / LoopArrow)
+    edge_color: str = "#111111"
+    edge_opacity: float = 1.0
+    edge_width: float = 1.5
+    edge_head_size: float = 8.0
+    edge_style: str = "solid"  # solid | dashed | dotted
+    edge_overlap: str = "avoid"  # allow | avoid
+    edge_head: str = "triangle"  # triangle|stealth|vee|open|circle|diamond|bar|square|none
+    edge_lane_gap: float = 7.0
+    # v0.7.0: how bundle= groups draw — lanes (parallel, crossing-minimised) | merge | bus
+    edge_bundle_style: str = "lanes"
+    # Arrowhead geometry defaults (None → derived from edge_head_size)
+    edge_tail: str = "none"  # start-of-edge head shape
+    edge_head_length: Optional[float] = None  # tip → back distance (default = head_size)
+    edge_head_width: Optional[float] = None  # across the head (default = 0.9 × head_size)
+    edge_head_hollow: bool = False  # outline heads filled with edge_head_fill
+    edge_head_fill: str = "#ffffff"  # interior colour of hollow heads
+    # Layering policy: soft text knocks edges out; role overrides per class name
+    knockout: bool = True
+    knockout_pad: float = 1.5
+    roles: Tuple[Tuple[str, str], ...] = ()  # e.g. (("Text", "hard"),)
+    # ---- 0.6.0 -------------------------------------------------------------
+    name: str = "classic"
+    # Preferred sans families, first installed wins (measurement *and* SVG family).
+    # Empty → legacy DejaVu Sans behaviour.
+    font_stack: Tuple[str, ...] = ()
+    # Font-size roles; when non-empty every requested size snaps to the nearest role.
+    font_sizes: Tuple[float, ...] = ()
+    annotation_size: Optional[float] = None  # small text (legend, dims, ticks); None → 0.85 × font_size
+    text_color: str = "#111111"
+    muted_color: str = "#555555"
+    # Internal default lengths (stubs, cell sizes, offsets …) are written in classic
+    # design units and multiplied by ``unit`` (classic 1.0; paper ≈ 7 pt / 13 px).
+    unit: float = 1.0
+    stroke_emph: Optional[float] = None  # emphasis stroke role (highlight borders)
+    group_stroke: Optional[float] = None  # dashed group / frame role
+    dash: Optional[Tuple[float, ...]] = None  # "dashed" pattern; None → legacy (scaled)
+    dot: Optional[Tuple[float, ...]] = None  # "dotted" pattern; None → legacy
+    box_pad: Optional[Tuple[float, float]] = None  # Box (vertical, horizontal) pad; None → pad + text_margin
+    box_min_h: float = 0.0  # min height of a labelled Box
+    script_scale: float = 0.75  # sub/superscript size factor
+    script_min: float = 0.0  # sub/superscripts never smaller than this
+    palette: Tuple[str, ...] = ("#7eb6e8", "#f5c48a", "#cfe8cf", "#c9b3e6", "#f5e6a8", "#f0b080")
+    accents: Tuple[str, ...] = ("#c0392b", "#2c7fb8", "#2ca02c")
+    hatch_cycle: Tuple[str, ...] = ("", "////", "....", "xxxx", "\\\\")
+    hatch_width: float = 0.8
+    hatch_spacing: float = 5.0
+    neutral_fill: str = "#e8e8e8"
+    group_fill: str = "#f3f3f3"
+    grid_color: str = "#bdbdbd"  # chart gridlines (v0.8.0): light, theme stroke width
+    # v0.9.0 chart error bars (design units, × unit): cap half-width floor and how far
+    # caps stick out beyond a line-chart marker so tight errors stay visible
+    align_max_offset: float = 60.0  # v0.11.0 edge alignment: max port offset (L units)
+    align_max_shift: float = 24.0  # … and max node move (L units)
+    align_max_grow: float = 12.0  # … and how much a panel's content may grow (L units)
+    track_grow_max: float = 1.4  # v0.10.0: align_columns(fit="auto") grows fixed cells ≤ this ×
+    stack_gap: float = 3.3  # v0.10.0: gap inside an aligned Col / Row stack (pt, paper)
+    chart_zero: Any = "auto"  # v0.10.0: LineChart y axis includes 0: "auto" | True | False
+    err_cap: float = 2.2
+    err_cap_out: float = 1.4
+    band_opacity: float = 0.18  # LineChart error bands
+    max_panel_scale: float = 1.8
+    panel_frame: bool = True
+    panel_caption: str = "bottom"
+    min_stroke: float = 0.0  # floor for internal decorative strokes (pt)
+    physical: bool = False  # True → units are pt at final size (no panel zoom)
+    edge_min_stroke: float = 0.8  # arrowhead outline floor (classic px)
+
+    named_accents: Tuple[Tuple[str, str], ...] = ()
+
+    def accent_names(self) -> tuple[str, ...]:
+        """Return registered accent names in stable order."""
+        base = ("blue", "orange", "green") if self.name == "paper" else ("red", "blue", "green")
+        return tuple(dict.fromkeys((*base, *(k for k, _ in self.named_accents))))
+
+    def with_accents(self, **named_hex: str) -> "Theme":
+        """Return a theme with additional named hexadecimal accents."""
+        import re
+        names = dict(self.named_accents)
+        for name, value in named_hex.items():
+            if not name.strip() or not isinstance(value, str) or not re.fullmatch(r"#[0-9a-fA-F]{6}", value):
+                raise ValueError(f"invalid accent {name!r}: {value!r}; expected #RRGGBB")
+            names[name.strip().lower()] = value
+        return replace(self, named_accents=tuple(names.items()))
+
+    # ---- helpers -------------------------------------------------------------
+    def accent(self, which: "int | str", *, nearest: bool = False) -> str:
+        """An accent colour by index or by name (v0.12.0).
+
+        ``which`` is an index into :attr:`accents` (cycled) or a colour name:
+        ``"blue"`` / ``"orange"`` (vermillion) / ``"green"`` / ``"red"`` … — the accent whose
+        hue is nearest to that name. ``PAPER_THEME.accents`` is
+        ``0 blue #0072B2, 1 orange #D55E00, 2 green #009E73`` (Okabe–Ito);
+        ``CLASSIC_THEME.accents`` is ``0 red #c0392b, 1 blue #2c7fb8, 2 green #2ca02c``.
+        """
+        import colorsys
+        import difflib
+        import warnings
+        if nearest:
+            warnings.warn("nearest=True is deprecated", DeprecationWarning, stacklevel=2)
+        elif isinstance(which, str):
+            names = dict(zip(("blue", "orange", "green") if self.name == "paper" else ("red", "blue", "green"), self.accents))
+            names.update(self.named_accents)
+            key = which.strip().lower()
+            if key in names:
+                return names[key]
+            close = difflib.get_close_matches(key, names, n=1, cutoff=0.3)
+            hint = f"; did you mean {close[0]!r}?" if close else ""
+            raise ValueError(f"unknown accent name {which!r} for theme {self.name!r}; valid names: {', '.join(names)}{hint} To add a colour use Theme.with_accents(purple='#RRGGBB') or pass a hex colour.")
+
+        acc = list(self.accents) or ["#555555"]
+        if isinstance(which, int):
+            return acc[which % len(acc)]
+        hues = {"red": 0.0, "vermillion": 0.05, "orange": 0.07, "yellow": 0.14, "green": 0.4,
+                "teal": 0.47, "cyan": 0.5, "sky": 0.55, "blue": 0.6, "purple": 0.78,
+                "magenta": 0.85, "pink": 0.92}
+        key = str(which).lower().replace("_", "").replace(" ", "")
+        if key not in hues:
+            raise ValueError(f"unknown accent name {which!r}; use an index or one of "
+                             f"{sorted(hues)}")
+        want = hues[key]
+
+        def hue(c: str) -> float:
+            c = c.lstrip("#")
+            r, g, b = (int(c[i:i + 2], 16) / 255 for i in (0, 2, 4))
+            return colorsys.rgb_to_hsv(r, g, b)[0]
+
+        def dist(c: str) -> float:
+            d = abs(hue(c) - want)
+            return min(d, 1 - d)
+        return min(acc, key=dist)
+
+    def L(self, v: float) -> float:
+        """Scale an internal design-unit length by ``unit`` (identity for classic)."""
+        return float(v) if self.unit == 1.0 else float(v) * self.unit
+
+    def F(self, v: float) -> float:
+        """An internal font-size literal (classic px, designed against 13 px text)
+        mapped to this theme (identity for classic; snapped to a size role)."""
+        if self.unit == 1.0 and not self.font_sizes:
+            return float(v)
+        return self.snap(float(v) * self.font_size / 13.0)
+
+    def SW(self, v: float) -> float:
+        """An internal stroke-width literal (classic px) mapped to a stroke role:
+        thin → ``stroke_width``, medium → ``edge_width``, heavy → ``emph_stroke``."""
+        if self.unit == 1.0:
+            return float(v)
+        v = float(v)
+        if v <= 0:
+            return 0.0
+        if v <= 1.05:
+            return self.stroke_width
+        if v <= 1.7:
+            return self.edge_width
+        return self.emph_stroke
+
+    @property
+    def small_size(self) -> float:
+        """Annotation / legend / tick text size."""
+        return float(self.annotation_size if self.annotation_size is not None
+                     else self.font_size * 0.85)
+
+    @property
+    def emph_stroke(self) -> float:
+        return float(self.stroke_emph if self.stroke_emph is not None else self.stroke_width * 1.25)
+
+    def head_dims(self, length: float, width: float) -> Tuple[float, float]:
+        """An internal arrowhead literal (classic px) → (length, width): identity for
+        classic, the theme's one head size (CF-ARR-001) otherwise."""
+        if self.unit == 1.0:
+            return float(length), float(width)
+        hl = self.edge_head_length if self.edge_head_length is not None else self.edge_head_size
+        hw = self.edge_head_width if self.edge_head_width is not None else 0.9 * hl
+        return float(hl), float(hw)
+
+    def snap(self, size: float) -> float:
+        """Snap a requested font size to the nearest size role (no-op without roles)."""
+        roles = self.font_sizes
+        if not roles:
+            return size
+        try:
+            v = float(size)
+        except (TypeError, ValueError):
+            return size
+        best = min(roles, key=lambda r: (abs(r - v * self.fit_font_scale), -r))
+        return float(best) / self.fit_font_scale
+
+    def script_size(self, size: float) -> float:
+        """Sub/superscript size for body text of ``size``.
+
+        v0.12.0 (A14): ``script_min`` is a floor at the *printed* size — while a
+        physical figure is shrunk ×s to fit its venue width, scripts are drawn at
+        least ``script_min / s`` design units, so a shrink never pushes them under
+        the legibility floor (5.5 pt in the paper theme)."""
+        floor = self.script_min
+        k = _OUT_SCALE.get()
+        if floor > 0 and k < 0.9999:
+            # never larger than the body text itself
+            floor = min(floor * 1.02 / max(k, 0.05), max(float(size), self.script_min))
+        return max(float(size) * self.script_scale, floor)
+
+
+DEFAULT_THEME = Theme()  # the classic theme (kept for backward compatibility)
+CLASSIC_THEME = DEFAULT_THEME
+
+PAPER_THEME = Theme(
+    name="paper",
+    stroke="#333333",
+    stroke_width=0.6,
+    font_family="'Liberation Sans', Helvetica, Arial, sans-serif",
+    mono_family="DejaVu Sans Mono, Menlo, Consolas, monospace",
+    font_size=7.0,
+    title_size=8.0,
+    panel_title_size=8.0,
+    caption_size=7.0,
+    annotation_size=6.0,
+    fill_default="#ffffff",
+    fill_prompt="#80CEB9",
+    fill_response="#F5D999",
+    fill_block="#F2F2F2",
+    fill_attn="#F5D999",
+    fill_ffn="#66AAD1",
+    fill_q="#66AAD1",
+    fill_k="#F5D999",
+    fill_v="#80CEB9",
+    highlight="#D55E00",
+    pad=4.0,
+    gap=10.5,
+    label_gap=3.5,
+    title_gap=3.5,
+    text_margin=0.0,
+    edge_label_gap=2.5,
+    corner_radius=2.5,
+    panel_gap=10.5,
+    panel_pad=4.0,
+    frame_stroke=0.6,
+    edge_color="#333333",
+    edge_width=0.75,
+    edge_head_size=4.0,
+    edge_head="stealth",
+    edge_lane_gap=3.5,
+    edge_head_length=4.0,
+    edge_head_width=3.0,
+    knockout_pad=1.0,
+    font_stack=("Helvetica", "Arial", "TeX Gyre Heros", "Liberation Sans", "Nimbus Sans",
+                "DejaVu Sans"),
+    font_sizes=(6.0, 7.0, 8.0),
+    text_color="#000000",
+    muted_color="#555555",
+    unit=0.55,
+    stroke_emph=1.2,
+    group_stroke=0.6,
+    dash=(3.0, 2.0),
+    dot=(0.75, 1.5),
+    box_pad=(3.15, 5.6),
+    box_min_h=13.3,
+    script_scale=0.8,
+    script_min=5.5,
+    palette=("#66AAD1", "#F5D999", "#80CEB9", "#FCFAD9", "#C37D41", "#B45F69"),
+    accents=("#0072B2", "#D55E00", "#009E73"),
+    hatch_width=0.5,
+    hatch_spacing=2.8,
+    neutral_fill="#F2F2F2",
+    group_fill="#FAFAFA",
+    grid_color="#BDBDBD",
+    max_panel_scale=1.0,
+    panel_frame=False,
+    panel_caption="top",
+    min_stroke=0.5,
+    physical=True,
+    edge_min_stroke=0.5,
+)
+
+PAPER_THEME_015 = PAPER_THEME
+PAPER_PALETTE = ("#4DB1F2", "#FCD188", "#8FCCA7", "#AE87A9", "#EDF6C3", "#A67167")
+PAPER_THEME = replace(
+    PAPER_THEME_015, palette=PAPER_PALETTE,
+    fill_q=PAPER_PALETTE[0], fill_k=PAPER_PALETTE[1], fill_v=PAPER_PALETTE[2],
+    fill_attn=PAPER_PALETTE[1], fill_ffn=PAPER_PALETTE[0],
+    fill_prompt=PAPER_PALETTE[2], fill_response=PAPER_PALETTE[1],
+    box_rounded=True, category_stroke=0.45, corner_radius=3.0,
+    box_pad=(3.4, 6.0), box_min_h=14.0, group_fill="#F6F7F9",
+)
+THEMES: Dict[str, Theme] = {"paper": PAPER_THEME, "paper-0.15": PAPER_THEME_015, "classic": CLASSIC_THEME}
+
+ThemeLike = Union[None, str, Theme, Mapping[str, Any]]
+
+_OUT_SCALE: "contextvars.ContextVar[float]" = contextvars.ContextVar("codefig_out_scale",
+                                                                    default=1.0)
+
+
+def use_output_scale(k: float):
+    """Context manager: the figure-wide print scale (``Figure.global_scale``) that
+    :meth:`Theme.script_size` compensates for. Set by Figure; rarely needed directly."""
+    from contextlib import contextmanager
+
+    @contextmanager
+    def _cm():
+        tok = _OUT_SCALE.set(float(k))
+        try:
+            yield
+        finally:
+            _OUT_SCALE.reset(tok)
+
+    return _cm()
+
+
+_ACTIVE: "contextvars.ContextVar[Optional[Theme]]" = contextvars.ContextVar(
+    "codefig_active_theme", default=None)
+_GLOBAL = [PAPER_THEME]
+
+
+def register_theme(name: str, theme: Theme) -> Theme:
+    """Register a named theme so ``Figure(theme=name)`` / ``use_theme(name)`` find it."""
+    THEMES[str(name)] = theme
+    return theme
+
+
+def get_theme(spec: ThemeLike = None) -> Theme:
+    """Resolve ``None`` (active) | name | Theme | dict-of-overrides (over the active theme)."""
+    if spec is None:
+        return current_theme()
+    if isinstance(spec, Theme):
+        return spec
+    if isinstance(spec, str):
+        try:
+            return THEMES[spec]
+        except KeyError:
+            raise ValueError(f"unknown theme {spec!r}; known: {sorted(THEMES)}") from None
+    if isinstance(spec, Mapping):
+        d = dict(spec)
+        base = get_theme(d.pop("base", None))
+        return replace(base, **d)
+    raise TypeError(f"theme must be a name, Theme or dict, got {spec!r}")
+
+
+def current_theme() -> Theme:
+    """The active theme: innermost :func:`use_theme`, else the global default."""
+    t = _ACTIVE.get()
+    return t if t is not None else _GLOBAL[0]
+
+
+def set_theme(spec: ThemeLike) -> Theme:
+    """Set the global default theme (``"paper"`` unless changed).
+
+    Returns the *previous* global theme, so ``old = set_theme("classic")`` …
+    ``set_theme(old)`` restores it. Prefer ``with use_theme(...)`` for scoped use.
+    """
+    t = get_theme(spec)
+    prev = _GLOBAL[0]
+    _GLOBAL[0] = t
+    return prev
+
+
+@contextmanager
+def use_theme(spec: ThemeLike) -> Iterator[Theme]:
+    """``with use_theme("classic"): ...`` — nodes without an explicit theme use it."""
+    t = get_theme(spec)
+    tok = _ACTIVE.set(t)
+    try:
+        yield t
+    finally:
+        _ACTIVE.reset(tok)
+
+
+class theme_default:
+    """Descriptor: instance value if set (not None), else ``theme.<attr>`` (lazy).
+
+    ``attr`` may be a field name or a callable ``theme -> value``.
+    """
+
+    def __init__(self, attr: Any) -> None:
+        self.attr = attr
+        self.slot = ""
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        self.slot = "_td_" + name
+
+    def __get__(self, obj: Any, owner: Any = None) -> Any:
+        if obj is None:
+            return self
+        v = obj.__dict__.get(self.slot)
+        if v is not None:
+            return v
+        th = obj.theme
+        value = self.attr(th) if callable(self.attr) else getattr(th, self.attr)
+        if isinstance(self.attr, str):
+            factor = th.pad_scale if self.attr == "pad" else th.gap_scale if "gap" in self.attr else 1.0
+            if isinstance(value, (int, float)):
+                value *= factor
+        return value
+
+    def __set__(self, obj: Any, value: Any) -> None:
+        obj.__dict__[self.slot] = value
+
+_EDGE_KEYS = {
+    "color": "edge_color",
+    "stroke": "edge_color",
+    "opacity": "edge_opacity",
+    "alpha": "edge_opacity",
+    "width": "edge_width",
+    "stroke_width": "edge_width",
+    "head_size": "edge_head_size",
+    "style": "edge_style",
+    "overlap": "edge_overlap",
+    "head": "edge_head",
+    "lane_gap": "edge_lane_gap",
+    "tail": "edge_tail",
+    "head_length": "edge_head_length",
+    "head_width": "edge_head_width",
+    "hollow": "edge_head_hollow",
+    "head_hollow": "edge_head_hollow",
+    "head_fill": "edge_head_fill",
+}
+
+_SPACING_KEYS = {
+    "pad": "pad",
+    "padding": "pad",
+    "gap": "gap",
+    "label_gap": "label_gap",
+    "text_margin": "text_margin",  # Box inner text inset (on top of pad)
+    "title_gap": "title_gap",
+    "edge_label_gap": "edge_label_gap",
+    "panel_gap": "panel_gap",
+    "panel_pad": "panel_pad",
+}
+
+
+def normalize_pad(pad: PadSpec) -> Tuple[float, float, float, float]:
+    """CSS-like padding → (top, right, bottom, left)."""
+    if isinstance(pad, (int, float)):
+        v = float(pad)
+        return (v, v, v, v)
+    vals = [float(x) for x in pad]
+    if len(vals) == 1:
+        v = vals[0]
+        return (v, v, v, v)
+    if len(vals) == 2:
+        v, h = vals
+        return (v, h, v, h)
+    if len(vals) == 3:
+        t, h, b = vals
+        return (t, h, b, h)
+    if len(vals) == 4:
+        return (vals[0], vals[1], vals[2], vals[3])
+    raise TypeError(f"pad must be scalar or 1/2/3/4-tuple, got {pad!r}")
+
+
+def apply_edge_overrides(theme: Theme, edge: Optional[Mapping[str, Any]]) -> Theme:
+    if not edge:
+        return theme
+    updates: Dict[str, Any] = {}
+    for k, v in edge.items():
+        field = _EDGE_KEYS.get(k, k if k.startswith("edge_") else None)
+        if field is None:
+            raise TypeError(
+                f"Unknown edge style key {k!r}; expected one of {sorted(_EDGE_KEYS)}"
+            )
+        updates[field] = v
+    return replace(theme, **updates)
+
+
+def apply_spacing_overrides(theme: Theme, spacing: Optional[Mapping[str, Any]]) -> Theme:
+    """Figure(..., spacing={pad, gap, label_gap, title_gap, ...})."""
+    if not spacing:
+        return theme
+    updates: Dict[str, Any] = {}
+    for k, v in spacing.items():
+        field = _SPACING_KEYS.get(k)
+        if field is None:
+            raise TypeError(
+                f"Unknown spacing key {k!r}; expected one of {sorted(_SPACING_KEYS)}"
+            )
+        updates[field] = float(v) if not isinstance(v, (tuple, list)) else v
+    # If pad is a sequence, store the uniform average as theme.pad (scalar theme field)
+    if "pad" in updates and isinstance(updates["pad"], (tuple, list)):
+        pts = normalize_pad(updates["pad"])
+        updates["pad"] = sum(pts) / 4.0
+    return replace(theme, **updates)
+
+
+HEAD_SHAPES = ("triangle", "stealth", "vee", "open", "circle", "diamond", "bar", "square",
+               "none")
+
+
+@dataclass(frozen=True)
+class Head:
+    """Arrowhead spec for one end of an Edge / Arrow.
+
+    shape: triangle | stealth (notched) | vee (two open strokes) | open (hollow
+    triangle) | circle | diamond | bar (perpendicular tick) | square | none.
+    size scales the whole head; length / width set it explicitly (px);
+    hollow=True draws an outline filled with ``fill`` (default white).
+    """
+
+    shape: str = "triangle"
+    size: Optional[float] = None
+    length: Optional[float] = None
+    width: Optional[float] = None
+    hollow: Optional[bool] = None
+    fill: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.shape not in HEAD_SHAPES:
+            raise ValueError(f"head shape must be one of {HEAD_SHAPES}, got {self.shape!r}")
+
+
+@dataclass(frozen=True)
+class ResolvedHead:
+    shape: str
+    length: float
+    width: float
+    hollow: bool
+    fill: str
+
+    @property
+    def visible(self) -> bool:
+        return self.shape != "none" and self.length > 0
+
+    def setback(self, stroke_width: float = 1.5) -> float:
+        """How far the shaft stops short of the tip so it never pokes through."""
+        if not self.visible:
+            return 0.0
+        L = self.length
+        if self.shape == "vee":
+            return stroke_width * 0.6
+        if self.shape == "bar":
+            return 0.0
+        if self.shape == "stealth":
+            return L * (0.95 if self.hollow else 0.55)
+        if self.hollow:
+            return L
+        return L * 0.6
+
+
+HeadLike = Union[None, str, Head, Mapping[str, Any]]
+
+
+def as_head(spec: HeadLike) -> Optional[Head]:
+    if spec is None:
+        return None
+    if isinstance(spec, Head):
+        return spec
+    if isinstance(spec, str):
+        return Head(shape=spec)
+    if isinstance(spec, Mapping):
+        return Head(**dict(spec))
+    raise TypeError(f"head must be a shape name, Head(...) or dict, got {spec!r}")
+
+
+def resolve_head(
+    spec: HeadLike,
+    theme: "Theme",
+    *,
+    default_shape: str,
+    size: Optional[float] = None,
+    length: Optional[float] = None,
+    width: Optional[float] = None,
+    hollow: Optional[bool] = None,
+    fill: Optional[str] = None,
+) -> ResolvedHead:
+    """Merge a per-end spec over edge-level knobs over theme defaults."""
+    h = as_head(spec) or Head(shape=default_shape)
+    sz = h.size if h.size is not None else (size if size is not None else theme.edge_head_size)
+    sz = float(sz)
+    base_len = theme.edge_head_length if theme.edge_head_length is not None else sz
+    base_wid = theme.edge_head_width if theme.edge_head_width is not None else 0.9 * sz
+    if h.size is not None or size is not None:  # explicit scale wins over theme lengths
+        base_len, base_wid = sz, 0.9 * sz
+    L = h.length if h.length is not None else (length if length is not None else base_len)
+    W = h.width if h.width is not None else (width if width is not None else base_wid)
+    shape = h.shape
+    hol = h.hollow if h.hollow is not None else (hollow if hollow is not None else theme.edge_head_hollow)
+    if shape == "open":
+        shape, hol = "triangle", True
+    if shape == "circle" and h.width is None and width is None:
+        W = L
+    return ResolvedHead(shape=shape, length=float(L), width=float(W), hollow=bool(hol),
+                        fill=h.fill or fill or theme.edge_head_fill)
+
+
+# ---- borders ---------------------------------------------------------------
+
+BORDER_STYLES = ("solid", "dashed", "dotted", "dashdot", "none")
+BorderLike = Union[None, str, Sequence[float]]
+
+
+def border_dasharray(border: BorderLike, stroke_width: float = 1.0) -> Optional[str]:
+    """``border=`` value → SVG stroke-dasharray (None = solid line).
+
+    'solid' | 'dashed' | 'dotted' | 'dashdot' | custom "4 2" / (4, 2) pattern.
+    Named patterns scale with the stroke width so thick borders stay legible.
+    """
+    if border is None or border == "solid" or border == "none":
+        return None
+    k = max(1.0, float(stroke_width or 1.0))
+    th = current_theme()
+    if border == "dashed" and th.dash is not None:
+        return " ".join(f"{v:g}" for v in th.dash)
+    if border == "dotted" and th.dot is not None:
+        return " ".join(f"{v:g}" for v in th.dot)
+    if border == "dashed":
+        return f"{4.5 * k:.2f} {3 * k:.2f}"
+    if border == "dotted":
+        return f"{1 * k:.2f} {2 * k:.2f}"
+    if border == "dashdot":
+        return f"{6 * k:.2f} {2.5 * k:.2f} {1 * k:.2f} {2.5 * k:.2f}"
+    if isinstance(border, str):
+        parts = border.replace(",", " ").split()
+        try:
+            [float(p) for p in parts]
+        except ValueError:
+            raise ValueError(
+                f"border must be one of {BORDER_STYLES} or a dash pattern like '4 2', got {border!r}"
+            ) from None
+        return " ".join(parts)
+    vals = [float(v) for v in border]
+    if not vals:
+        return None
+    return " ".join(f"{v:g}" for v in vals)
+
+
+def border_visible(border: BorderLike) -> bool:
+    return border != "none"
+
+
+def validate_border(border: BorderLike) -> BorderLike:
+    border_dasharray(border, 1.0)
+    return border
+
+
+@dataclass
+class ResolvedEdgeStyle:
+    color: str
+    opacity: float
+    width: float
+    head_size: float
+    style: str
+    overlap: str
+    head: str
+    lane_gap: float
+    end_head: Optional[ResolvedHead] = None
+    start_head: Optional[ResolvedHead] = None
+    dash: Optional[str] = None  # custom dash pattern (style=(4, 2) or "4 2")
+
+    def dasharray(self) -> Optional[str]:
+        if self.dash:
+            return self.dash
+        th = current_theme()
+        if self.style == "dashed" and th.dash is not None:
+            return " ".join(f"{v:g}" for v in th.dash)
+        if self.style == "dotted" and th.dot is not None:
+            return " ".join(f"{v:g}" for v in th.dot)
+        if self.style == "dashed":
+            return "7 4"
+        if self.style == "dotted":
+            return "1.5 3.5"
+        return None
+
+
+def resolve_edge_style(
+    theme: Theme,
+    *,
+    color: Optional[str] = None,
+    stroke: Optional[str] = None,
+    opacity: Optional[float] = None,
+    alpha: Optional[float] = None,
+    width: Optional[float] = None,
+    stroke_width: Optional[float] = None,
+    head_size: Optional[float] = None,
+    style: Optional[str] = None,
+    overlap: Optional[str] = None,
+    head: HeadLike = None,
+    tail: HeadLike = None,
+    head_length: Optional[float] = None,
+    head_width: Optional[float] = None,
+    hollow: Optional[bool] = None,
+    head_fill: Optional[str] = None,
+) -> ResolvedEdgeStyle:
+    col = color if color is not None else stroke
+    op = opacity if opacity is not None else alpha
+    w = width if width is not None else stroke_width
+    dash = None
+    if style is not None and style not in ("solid", "dashed", "dotted"):
+        dash = border_dasharray(style, 1.0)
+        style = "custom"
+    hd = as_head(head)
+    end_head = resolve_head(hd, theme, default_shape=theme.edge_head, size=head_size,
+                            length=head_length, width=head_width, hollow=hollow, fill=head_fill)
+    start_head = resolve_head(as_head(tail), theme, default_shape=theme.edge_tail,
+                              size=head_size, length=head_length, width=head_width,
+                              hollow=hollow, fill=head_fill)
+    rs = ResolvedEdgeStyle(
+        color=col if col is not None else theme.edge_color,
+        opacity=float(op if op is not None else theme.edge_opacity),
+        width=float(w if w is not None else theme.edge_width),
+        head_size=float(head_size if head_size is not None else theme.edge_head_size),
+        style=(style if style is not None else theme.edge_style),
+        overlap=(overlap if overlap is not None else theme.edge_overlap),
+        head=(hd.shape if hd is not None else theme.edge_head),
+        lane_gap=float(theme.edge_lane_gap),
+        end_head=end_head,
+        start_head=start_head,
+        dash=dash,
+    )
+    return rs
+
+
+def normalize_justify(justify: str) -> str:
+    return justify.replace("-", "_")
+
+
+class themed:
+    """Descriptor for an internal literal default resolved against the node's theme.
+
+    ``themed(24.0)`` → a length (``theme.L``); ``themed(1.0, "SW")`` → a stroke
+    role; ``themed(11.0, "F")`` → a font size. Assigning ``None`` restores the
+    default; any number set explicitly is used verbatim (in the theme's units).
+    """
+
+    def __init__(self, default: Any, kind: str = "L") -> None:
+        self.default = default
+        self.kind = kind
+        self.slot = ""
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        self.slot = "_th_" + name
+
+    def __get__(self, obj: Any, owner: Any = None) -> Any:
+        if obj is None:
+            return self
+        v = obj.__dict__.get(self.slot)
+        if v is not None:
+            return v
+        th = getattr(obj, "theme", None) or current_theme()
+        f = getattr(th, self.kind)
+        if isinstance(self.default, tuple):
+            return tuple(f(d) for d in self.default)
+        return f(self.default)
+
+    def __set__(self, obj: Any, value: Any) -> None:
+        if value is not None and isinstance(value, (int, float)) and not isinstance(value, bool):
+            value = float(value)
+        obj.__dict__[self.slot] = value
+
+
+# ---- categories (0.6.0) ---------------------------------------------------------
+# ``Box(..., category="cache")``: the n-th distinct category of a figure gets
+# ``theme.palette[n % len]``; past the palette, ``theme.hatch_cycle`` adds hatching
+# so ≥ 5 categories stay distinguishable in grey-scale (CF-COL-003).
+_CATS: "contextvars.ContextVar[Optional[dict]]" = contextvars.ContextVar("codefig_categories",
+                                                                         default=None)
+_GLOBAL_CATS: dict = {}
+
+
+@contextmanager
+def use_categories(order: Sequence[str]) -> Iterator[dict]:
+    """Fix the category → index map (Figure does this in panel order)."""
+    d: dict = {}
+    for c in order:
+        d.setdefault(c, len(d))
+    tok = _CATS.set(d)
+    try:
+        yield d
+    finally:
+        _CATS.reset(tok)
+
+
+def category_index(name: str) -> int:
+    d = _CATS.get()
+    if d is None:
+        d = _GLOBAL_CATS
+    if name not in d:
+        d[name] = len(d)
+    return d[name]
+
+
+def category_style(name: str, theme: Optional["Theme"] = None) -> Tuple[str, Optional[str]]:
+    """(fill colour, hatch spec or None) for category ``name`` under ``theme``."""
+    th = theme or current_theme()
+    i = category_index(name)
+    pal = list(th.palette) or ["#e8e8e8"]
+    fill = pal[i % len(pal)]
+    cyc = list(th.hatch_cycle) or [""]
+    hatch = cyc[(i // len(pal)) % len(cyc)] if i >= len(pal) else ""
+    return fill, (hatch or None)
+
+
+def length_unit(theme: Optional["Theme"] = None) -> str:
+    """``"pt"`` for physical themes (paper), ``"px"`` for the classic pixel theme — used in
+    warning / lint messages."""
+    th = theme or current_theme()
+    return "px" if getattr(th, "unit", 1.0) == 1.0 else "pt"
+
+
+def shade(color: str, amount: float = 0.2) -> str:
+    """Mix ``color`` with black: ``shade("#66AAD1", 0.2)`` → a darker fill of the same hue
+    (the side face of a :class:`~codefig.solids.Cuboid`)."""
+    c = color.lstrip("#")
+    if len(c) == 3:
+        c = "".join(ch * 2 for ch in c)
+    r, g, b = (int(c[i:i + 2], 16) for i in (0, 2, 4))
+    a = min(1.0, max(0.0, float(amount)))
+    return "#" + "".join(f"{round(v * (1 - a)):02X}" for v in (r, g, b))
+
+
+def tint(color: str, amount: float = 0.5) -> str:
+    """Mix ``color`` with white: ``tint("#66AAD1", 0.6)`` → a lighter fill of the same hue
+    (for highlight bands behind text, e.g. ``CodeBlock(highlight_lines=...)``)."""
+    c = color.lstrip("#")
+    if len(c) == 3:
+        c = "".join(ch * 2 for ch in c)
+    r, g, b = (int(c[i:i + 2], 16) for i in (0, 2, 4))
+    a = min(1.0, max(0.0, float(amount)))
+    mix = (round(v + (255 - v) * a) for v in (r, g, b))
+    return "#" + "".join(f"{v:02X}" for v in mix)
+
+
+def resolve_color(spec, theme, *, where: str):
+    """Validate drawing colours and resolve registered accents."""
+    from .lint import parse_color
+    if spec is None or not isinstance(spec, str):
+        return spec
+    value = spec.strip().lower()
+    if value in {"none", "transparent"} or value.startswith("url(") or parse_color(value) is not None:
+        return spec
+    if value in theme.accent_names():
+        return theme.accent(value)
+    raise ValueError(f"{where}: invalid colour {spec!r}; use hex, a supported colour name, or a registered theme accent")