Skip to content

dwgx/SmartCLI / skills/tui-ui

tui-ui

Verified

Design web-like user interfaces in the terminal and inside tmux with a cell-grid Canvas, CSS-like box model, flexbox/grid layout, and 17 reusable widgets such as Panel, Table, Card, ProgressBar, Meter, Tabs, Tree, Badge, Banner, and a braille line chart. Use when an agent needs a dashboard, panel, table, status page, TUI layout, tmux dashboard, screenshot-driven CLI/TUI replica, ANSI frame, truecolor render, pyte PNG screenshot smoke test, wide-character alignment, or a new terminal widget.

ui/raster.py

View on GitHub
"""raster.py — SubcellRaster: sub-cell resolution (primitive #2).

A terminal cell is the smallest unit the grid can address, so a plain
``cols x rows`` Canvas is forever blocky. The escape hatch is *sub-cell*
glyphs: a single character whose interior is subdivided into fixed pixel
regions, coloured via fg/bg. This module is a tiny off-screen pixel engine
that draws into a real pixel buffer, then downsamples each cell's pixels to
the best matching sub-cell glyph + colours and writes back into a Canvas.
See references/RENDERING-MODEL.md §2. This is "the smooth part" — images,
anti-aliased curves, sparklines, round discs all route through here.

Three densities, and THE load-bearing fact is that in every one of them a
sub-cell pixel comes out SCREEN-SQUARE, because the pixel subdivision cancels
ASPECT=2 (cell height : width):

  * ``half``    -> cols x (rows*2)   1x2 px/cell  -> ▀ (fg=top px, bg=bottom px)
  * ``quad``    -> (cols*2) x (rows*2) 2x2 px/cell -> ▘▝▖▗▀▄▌▐▚▞▛▜▙▟█ + space
  * ``braille`` -> (cols*2) x (rows*4) 2x4 px/cell -> U+2800 + 8-dot mask (densest)

Because the buffer pixels are square, ``circle``/``disc`` take a plain
Euclidean radius and still read round on screen — no per-call ASPECT term
(unlike field.py, where cells ARE the pixels and y must be scaled by ASPECT).
"""
from __future__ import annotations

import sys
from typing import List, Optional, Sequence, Tuple

from .core import RGB, Canvas, parse_color

# ==========================================================================
# Sub-cell glyph tables — the whole "smoothness" trick is these lookups.
# ==========================================================================
# half: 1 col x 2 rows of pixels per cell. Upper-half block ▀ carries the top
# pixel as fg and the bottom pixel as bg, so one cell shows two colours.
HALF_TOP = "▀"      # U+2580 upper half block  (fg = top pixel)
HALF_BOT = "▄"      # U+2584 lower half block  (fg = bottom pixel)
HALF_FULL = "█"     # U+2588 full block        (both pixels same colour)

# quad: 2x2 pixels per cell, indexed by a 4-bit mask (bit0=TL,1=TR,2=BL,3=BR).
QUAD_GLYPHS = [
    " ", "▘", "▝", "▀", "▖", "▌", "▞", "▛",
    "▗", "▚", "▐", "▜", "▄", "▙", "▟", "█",
]

# braille: 2x4 pixels per cell. Dot bit values per (col, row) sub-position —
# the historical 2x4 Braille layout (dots 1-6 then 7-8 on the bottom row).
BRAILLE_BITS = {
    (0, 0): 0x01, (0, 1): 0x02, (0, 2): 0x04, (0, 3): 0x40,
    (1, 0): 0x08, (1, 1): 0x10, (1, 2): 0x20, (1, 3): 0x80,
}
BRAILLE_BASE = 0x2800

# Cells to pixels for each mode: (px_per_col, px_per_row).
#   sextant: 2x3 px/cell via the Unicode 13 "Symbols for Legacy Computing" block
#   (U+1FB00..). +50% vertical resolution over quad, with two-color support.
_MODE_DIMS = {"half": (1, 2), "quad": (2, 2), "braille": (2, 4), "sextant": (2, 3)}

# sextant: 6-pixel mask -> glyph. Bit i of the mask = sextant position i+1 in
# Unicode's numbering (1=TL,2=TR,3=ML,4=MR,5=BL,6=BR), so bit0=TL .. bit5=BR.
#
# The U+1FB00 block is NOT a dense mask+offset: it OMITS the two patterns that
# already exist as half blocks (left column -> U+258C, right column -> U+2590),
# so a naive `0x1FB00 + (mask-1)` misaligns 42 of 62 glyphs and overruns into
# non-sextant diagonals. Build the table by READING each block glyph's
# "BLOCK SEXTANT-<digits>" name and reconstructing its mask — this can't drift.
def _build_sextant_glyphs():
    import unicodedata
    glyphs = [" "] * 64
    glyphs[0] = " "
    glyphs[63] = "█"       # full block
    glyphs[0b010101] = "▌"  # left column (TL+ML+BL = sextants 1,3,5, bits 0,2,4) = left half
    glyphs[0b101010] = "▐"  # right column (TR+MR+BR = sextants 2,4,6, bits 1,3,5) = right half
    for cp in range(0x1FB00, 0x1FB3C):   # the sextant range (before the diagonals)
        try:
            name = unicodedata.name(chr(cp))
        except ValueError:
            continue
        prefix = "BLOCK SEXTANT-"
        if not name.startswith(prefix):
            continue
        mask = 0
        for d in name[len(prefix):]:
            if d.isdigit():
                mask |= 1 << (int(d) - 1)   # sextant N -> bit N-1
        if 0 < mask < 63:
            glyphs[mask] = chr(cp)
    return glyphs


SEXTANT_GLYPHS = _build_sextant_glyphs()
# (col, row) -> bit for the 2x3 grid.
SEXTANT_BITS = {
    (0, 0): 0x01, (1, 0): 0x02,
    (0, 1): 0x04, (1, 1): 0x08,
    (0, 2): 0x10, (1, 2): 0x20,
}

# Two colours in a cell closer than this are treated as one. NOTE: _dist2 now
# measures in OKLab (scaled by 255^2), which is perceptually uniform — so at a
# fixed threshold two-color splitting is MORE sensitive in dark tones and LESS
# in bright tones than the old raw-RGB metric. That's the intended OKLab
# behavior (perceptual, not linear), not an equivalent of the old RGB split.
_SPLIT_THRESHOLD = 48 * 48


def _srgb_to_oklab(c: RGB):
    """sRGB (0..255) -> OKLab (L,a,b). OKLab is a perceptual space where
    Euclidean distance tracks perceived color difference far better than raw
    RGB — the quality lever chafa uses for its color matching. Ottosson 2020."""
    def lin(u):
        # Clamp to the sRGB domain first: parse_color/set_pixel don't clip, so an
        # out-of-range or negative channel could reach here, and a negative base
        # to the **2.4 power would return a COMPLEX number that then crashes the
        # <= threshold comparison. Clamp = correct sRGB behavior AND crash-safe.
        u = 0.0 if u < 0 else (255.0 if u > 255 else u)
        u /= 255.0
        return u / 12.92 if u <= 0.04045 else ((u + 0.055) / 1.055) ** 2.4
    r, g, b = lin(c[0]), lin(c[1]), lin(c[2])
    l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
    m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
    s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
    l_, m_, s_ = l ** (1 / 3), m ** (1 / 3), s ** (1 / 3)
    return (0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
            1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
            0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_)


# Cache OKLab conversions — the raster resolves the same colors many times.
_OKLAB_CACHE: dict = {}


def _oklab(c: RGB):
    v = _OKLAB_CACHE.get(c)
    if v is None:
        v = _srgb_to_oklab(c)
        if len(_OKLAB_CACHE) < 8192:
            _OKLAB_CACHE[c] = v
    return v


def _dist2(a: RGB, b: RGB) -> float:
    """Perceptual squared distance in OKLab (scaled to ~RGB-squared range so the
    existing _SPLIT_THRESHOLD stays meaningful). Falls back gracefully."""
    la, aa, ba = _oklab(a)
    lb, ab, bb = _oklab(b)
    # OKLab deltas are ~[0,1]; scale by 255^2 so thresholds tuned in RGB² still apply.
    return ((la - lb) ** 2 + (aa - ab) ** 2 + (ba - bb) ** 2) * (255.0 ** 2)


def _avg(colors: Sequence[RGB]) -> RGB:
    """Mean of a list of RGB triples (black if empty)."""
    n = len(colors)
    if n == 0:
        return (0, 0, 0)
    r = g = b = 0
    for c in colors:
        r += c[0]; g += c[1]; b += c[2]
    return (r // n, g // n, b // n)


# ==========================================================================
# SubcellRaster — the off-screen pixel buffer
# ==========================================================================
class SubcellRaster:
    """An off-screen pixel buffer at sub-cell resolution for one ``cols x rows``
    region, resolvable to Canvas cells via a mode-specific glyph mapping.

    The buffer is ``pw x ph`` *square* pixels where ``pw = cols * px_per_col``
    and ``ph = rows * px_per_row`` for the chosen mode. Each pixel is either a
    lit RGB colour or ``None`` (transparent — the cell keeps its Canvas value
    there). Draw with :meth:`set_pixel`/:meth:`line`/:meth:`disc`, then
    :meth:`to_canvas` or :meth:`blit_into` to resolve pixels to glyphs+colours.

    Because a pixel is square, all geometry (circles, isotropic distance) uses a
    plain Euclidean metric — the ASPECT=2 correction is already baked into the
    subdivision (2x taller cell split into 2 or 4 rows of pixels).
    """

    def __init__(self, cols: int, rows: int, mode: str = "half"):
        if mode not in _MODE_DIMS:
            raise ValueError(f"unknown mode {mode!r}; want one of {sorted(_MODE_DIMS)}")
        self.cols = max(0, int(cols))
        self.rows = max(0, int(rows))
        self.mode = mode
        self.pxc, self.pxr = _MODE_DIMS[mode]
        self.pw = self.cols * self.pxc
        self.ph = self.rows * self.pxr
        # None = transparent pixel; RGB tuple = lit.
        self.px: List[List[Optional[RGB]]] = [
            [None] * self.pw for _ in range(self.ph)
        ]

    # -- pixel primitives --------------------------------------------------
    def in_bounds(self, x: int, y: int) -> bool:
        return 0 <= x < self.pw and 0 <= y < self.ph

    def set_pixel(self, px: int, py: int, rgb: Optional[RGB]) -> None:
        """Light (or clear, if ``rgb is None``) one pixel. Clipped if OOB."""
        x, y = int(px), int(py)
        if 0 <= x < self.pw and 0 <= y < self.ph:
            self.px[y][x] = None if rgb is None else parse_color(rgb)

    def get_pixel(self, px: int, py: int) -> Optional[RGB]:
        if 0 <= px < self.pw and 0 <= py < self.ph:
            return self.px[py][px]
        return None

    def fill(self, rgb: Optional[RGB]) -> None:
        """Set every pixel to *rgb* (or clear all with ``None``)."""
        c = None if rgb is None else parse_color(rgb)
        for row in self.px:
            for x in range(self.pw):
                row[x] = c

    def fill_rect(self, x0: int, y0: int, w: int, h: int, rgb: Optional[RGB]) -> None:
        c = None if rgb is None else parse_color(rgb)
        for y in range(int(y0), int(y0) + int(h)):
            if 0 <= y < self.ph:
                row = self.px[y]
                for x in range(int(x0), int(x0) + int(w)):
                    if 0 <= x < self.pw:
                        row[x] = c

    def line(self, x0: int, y0: int, x1: int, y1: int, rgb: RGB) -> None:
        """Bresenham line from (x0,y0) to (x1,y1) in pixel space."""
        c = parse_color(rgb)
        x0, y0, x1, y1 = int(x0), int(y0), int(x1), int(y1)
        dx = abs(x1 - x0)
        dy = -abs(y1 - y0)
        sx = 1 if x0 < x1 else -1
        sy = 1 if y0 < y1 else -1
        err = dx + dy
        while True:
            self.set_pixel(x0, y0, c)
            if x0 == x1 and y0 == y1:
                break
            e2 = 2 * err
            if e2 >= dy:
                err += dy
                x0 += sx
            if e2 <= dx:
                err += dx
                y0 += sy

    def circle(self, cx: float, cy: float, r: float, rgb: RGB) -> None:
        """Midpoint circle outline (radius in square pixels)."""
        c = parse_color(rgb)
        x = int(round(r))
        y = 0
        err = 1 - x
        cxi, cyi = int(round(cx)), int(round(cy))
        while x >= y:
            for sx, sy in ((x, y), (y, x), (-x, y), (-y, x),
                           (-x, -y), (-y, -x), (x, -y), (y, -x)):
                self.set_pixel(cxi + sx, cyi + sy, c)
            y += 1
            if err < 0:
                err += 2 * y + 1
            else:
                x -= 1
                err += 2 * (y - x) + 1

    def disc(self, cx: float, cy: float, r: float, rgb: RGB) -> None:
        """Filled disc (radius in square pixels). Euclidean => round on screen."""
        c = parse_color(rgb)
        r2 = r * r
        y0 = int(cy - r) - 1
        y1 = int(cy + r) + 1
        x0 = int(cx - r) - 1
        x1 = int(cx + r) + 1
        for py in range(y0, y1 + 1):
            if not (0 <= py < self.ph):
                continue
            dy = py - cy
            for px in range(x0, x1 + 1):
                if not (0 <= px < self.pw):
                    continue
                dx = px - cx
                if dx * dx + dy * dy <= r2:
                    self.px[py][px] = c

    # -- resolve one cell's pixels -> (glyph, fg, bg) ----------------------
    def _cell_pixels(self, cx: int, cy: int) -> List[List[Optional[RGB]]]:
        """The ``pxr x pxc`` block of pixels backing Canvas cell (cx, cy)."""
        bx, by = cx * self.pxc, cy * self.pxr
        return [[self.px[by + j][bx + i] for i in range(self.pxc)]
                for j in range(self.pxr)]

    def _resolve_half(self, block) -> Tuple[Optional[str], Optional[RGB], Optional[RGB]]:
        """1x2 pixels -> ▀/▄/█/space. fg=top px, bg=bottom px (RENDERING-MODEL §2)."""
        top = block[0][0]
        bot = block[1][0]
        if top is None and bot is None:
            return (None, None, None)          # transparent: leave the cell
        if top is not None and bot is not None:
            if top == bot:
                return (HALF_FULL, top, None)
            return (HALF_TOP, top, bot)        # upper block: fg top, bg bottom
        if top is not None:
            return (HALF_TOP, top, None)       # only top lit
        return (HALF_BOT, bot, None)           # only bottom lit

    def _resolve_quad(self, block) -> Tuple[Optional[str], Optional[RGB], Optional[RGB]]:
        """2x2 pixels -> quadrant glyph. Two-colour majority split: lit pixels are
        clustered into (up to) two colours; the larger cluster is fg, the glyph's
        mask marks fg pixels, the minority cluster becomes bg."""
        flat = [block[0][0], block[0][1], block[1][0], block[1][1]]  # TL,TR,BL,BR
        lit = [(i, c) for i, c in enumerate(flat) if c is not None]
        if not lit:
            return (None, None, None)
        colors = [c for _, c in lit]
        # Pick the two most separated colours as cluster seeds.
        seed_a = colors[0]
        seed_b = max(colors, key=lambda c: _dist2(c, seed_a))
        if _dist2(seed_a, seed_b) <= _SPLIT_THRESHOLD:
            # Effectively one colour: mask = lit pixels, single fg, no bg.
            mask = 0
            for i, _ in lit:
                mask |= 1 << i
            return (QUAD_GLYPHS[mask], _avg(colors), None)
        # Two-colour split: assign each lit pixel to nearest seed.
        grp_a: List[RGB] = []
        grp_b: List[RGB] = []
        mask = 0
        for i, c in lit:
            if _dist2(c, seed_a) <= _dist2(c, seed_b):
                grp_a.append(c)
                mask |= 1 << i         # group A = fg pixels
            else:
                grp_b.append(c)
        # Majority colour is fg (its mask bits set); minority fills bg.
        if len(grp_a) >= len(grp_b):
            return (QUAD_GLYPHS[mask], _avg(grp_a), _avg(grp_b))
        # Flip: make the bigger group fg by inverting the mask over lit pixels.
        lit_mask = 0
        for i, _ in lit:
            lit_mask |= 1 << i
        return (QUAD_GLYPHS[lit_mask ^ mask], _avg(grp_b), _avg(grp_a))

    def _resolve_sextant(self, block) -> Tuple[Optional[str], Optional[RGB], Optional[RGB]]:
        """2x3 pixels -> U+1FB00 sextant glyph. Same two-colour majority split as
        quad (bigger cluster = fg + mask bits, minority = bg), but over 6 pixels
        for +50% vertical resolution."""
        # flatten in bit order: (0,0),(1,0),(0,1),(1,1),(0,2),(1,2)
        cells = [(SEXTANT_BITS[(i, j)], block[j][i])
                 for j in range(3) for i in range(2)]
        lit = [(bit, c) for bit, c in cells if c is not None]
        if not lit:
            return (None, None, None)
        colors = [c for _, c in lit]
        seed_a = colors[0]
        seed_b = max(colors, key=lambda c: _dist2(c, seed_a))
        if _dist2(seed_a, seed_b) <= _SPLIT_THRESHOLD:
            mask = 0
            for bit, _ in lit:
                mask |= bit
            return (SEXTANT_GLYPHS[mask], _avg(colors), None)
        grp_a: List[RGB] = []
        grp_b: List[RGB] = []
        mask = 0
        for bit, c in lit:
            if _dist2(c, seed_a) <= _dist2(c, seed_b):
                grp_a.append(c)
                mask |= bit
            else:
                grp_b.append(c)
        if len(grp_a) >= len(grp_b):
            return (SEXTANT_GLYPHS[mask], _avg(grp_a), _avg(grp_b))
        lit_mask = 0
        for bit, _ in lit:
            lit_mask |= bit
        return (SEXTANT_GLYPHS[lit_mask ^ mask], _avg(grp_b), _avg(grp_a))

    def _resolve_braille(self, block) -> Tuple[Optional[str], Optional[RGB], Optional[RGB]]:
        """2x4 pixels -> U+2800 + 8-dot mask. fg = average of lit pixels, no bg."""
        mask = 0
        lit: List[RGB] = []
        for j in range(4):
            for i in range(2):
                c = block[j][i]
                if c is not None:
                    mask |= BRAILLE_BITS[(i, j)]
                    lit.append(c)
        if mask == 0:
            return (None, None, None)
        return (chr(BRAILLE_BASE + mask), _avg(lit), None)

    def resolve_cell(self, cx: int, cy: int) -> Tuple[Optional[str], Optional[RGB], Optional[RGB]]:
        """Resolve Canvas cell (cx, cy) to ``(glyph, fg, bg)``. ``glyph is None``
        means every backing pixel was transparent — leave the cell untouched."""
        block = self._cell_pixels(cx, cy)
        if self.mode == "half":
            return self._resolve_half(block)
        if self.mode == "quad":
            return self._resolve_quad(block)
        if self.mode == "sextant":
            return self._resolve_sextant(block)
        return self._resolve_braille(block)

    # -- write resolved pixels into a Canvas -------------------------------
    def blit_into(self, canvas: Canvas, ox: int = 0, oy: int = 0,
                  attrs: int = 0) -> None:
        """Resolve every cell and composite onto *canvas* at offset (ox, oy).

        Transparent cells (all backing pixels ``None``) are skipped so the
        raster overlays cleanly on whatever the Canvas already holds. Where a
        mode gives no bg (braille / single-colour cells) the Canvas bg is kept.
        """
        for cy in range(self.rows):
            for cx in range(self.cols):
                glyph, fg, bg = self.resolve_cell(cx, cy)
                if glyph is None:
                    continue
                tx, ty = ox + cx, oy + cy
                cell = canvas.cell(tx, ty)
                if cell is None:
                    continue
                cell.char = glyph
                cell.cont = False
                cell.attrs = attrs
                if fg is not None:
                    cell.fg = fg
                if bg is not None:
                    cell.bg = bg

    def to_canvas(self, bg: Optional[RGB] = None, attrs: int = 0) -> Canvas:
        """Resolve into a fresh ``cols x rows`` Canvas (transparent cells = *bg*)."""
        cv = Canvas(self.cols, self.rows, bg=bg)
        self.blit_into(cv, 0, 0, attrs)
        return cv


# ==========================================================================
# Image loading (optional PIL) — resize to pixel res, map into a raster
# ==========================================================================
def from_image(path: str, cols: int, rows: int, mode: str = "half",
               alpha_threshold: int = 128) -> "SubcellRaster":
    """Load an image into a :class:`SubcellRaster` at ``cols x rows`` cells.

    Requires Pillow (PIL). The image is resized to the mode's pixel resolution
    (``cols*px_per_col x rows*px_per_row``) and each pixel copied into the
    buffer; fully/mostly-transparent pixels (alpha < *alpha_threshold*) stay
    transparent so PNGs with cut-outs composite cleanly. Raises a clear
    ``RuntimeError`` (not an obscure ImportError) when PIL is missing.
    """
    try:
        from PIL import Image  # type: ignore
    except Exception as exc:  # pragma: no cover - depends on optional dep
        raise RuntimeError(
            "from_image needs Pillow (PIL): pip install pillow. "
            "Everything else in raster.py is pure stdlib."
        ) from exc

    r = SubcellRaster(cols, rows, mode)
    if r.pw == 0 or r.ph == 0:
        return r
    img = Image.open(path).convert("RGBA").resize((r.pw, r.ph))
    data = img.load()
    for py in range(r.ph):
        for px in range(r.pw):
            pr, pg, pb, pa = data[px, py]
            if pa >= alpha_threshold:
                r.px[py][px] = (pr, pg, pb)
    return r


# ==========================================================================
# Self-test — run as a module: python -m ui.raster
# ==========================================================================
def _selftest() -> None:
    def ok(name: str, cond: bool, detail: str = "") -> None:
        mark = "PASS" if cond else "FAIL"
        print(f"[{mark}] {name}" + (f"  {detail}" if detail else ""))
        if not cond:
            _selftest.failed = True  # type: ignore[attr-defined]

    # Windows consoles default to a legacy codepage (GBK/CP936) that can't encode
    # block/braille glyphs — force UTF-8 so the proof dump prints.
    try:
        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
    except Exception:
        pass

    _selftest.failed = False  # type: ignore[attr-defined]
    WHITE = (255, 255, 255)
    ASPECT = 2.0  # cell height : width (from field.py) — the roundness yardstick.

    def cell_bbox(lines):
        xs, ys = [], []
        for y, row in enumerate(lines):
            for x, ch in enumerate(row):
                if ch != " ":
                    xs.append(x); ys.append(y)
        return (min(xs), min(ys), max(xs), max(ys)) if xs else (0, 0, 0, 0)

    def px_bbox(r: SubcellRaster):
        xs, ys = [], []
        for y in range(r.ph):
            for x in range(r.pw):
                if r.px[y][x] is not None:
                    xs.append(x); ys.append(y)
        return (max(xs) - min(xs) + 1, max(ys) - min(ys) + 1) if xs else (0, 0)

    # --- half mode: filled disc uses block glyphs, and is a SQUARE in pixels-
    # Square pixel buffer (24 x 24) so a radius-10 disc fits without clipping.
    rh = SubcellRaster(24, 12, "half")  # pw=24, ph=24 square px
    cxp, cyp, rpx = rh.pw / 2 - 0.5, rh.ph / 2 - 0.5, 10.0
    rh.disc(cxp, cyp, rpx, WHITE)
    cvh = rh.to_canvas(bg=(0, 0, 0))
    lines_h = cvh.to_lines()
    used_blocks = any(ch in set("▀▄█") for row in lines_h for ch in row)
    ok("half: disc rasterizes to block glyphs", used_blocks)

    # THE roundness proof: the lit pixels form a square (w_px ≈ h_px). Square
    # pixels => a square pixel-region displays as a round disc on screen.
    pwid, phgt = px_bbox(rh)
    ok("half: disc is round (pixel bbox square)", abs(pwid - phgt) <= 1,
       f"px w={pwid} h={phgt}")

    # And in CELLS that square reads as w ≈ ASPECT*h (a 2:1 wide block), because
    # each half-mode cell is 2 px tall. That 2:1 cell block IS the round disc.
    hx0, hy0, hx1, hy1 = cell_bbox(lines_h)
    wc, hc = hx1 - hx0 + 1, hy1 - hy0 + 1
    ok("half: cells w≈ASPECT*h (round given cell 2:1)", abs(wc - ASPECT * hc) <= 2,
       f"w={wc} h={hc}  ASPECT*h={ASPECT * hc:.0f}")

    # --- braille mode: same disc, densest glyphs in U+2800 block ------------
    rb = SubcellRaster(12, 6, "braille")  # pw=24, ph=24 square px
    cxp2, cyp2, rpx2 = rb.pw / 2 - 0.5, rb.ph / 2 - 0.5, 10.0
    rb.disc(cxp2, cyp2, rpx2, WHITE)
    cvb = rb.to_canvas(bg=(0, 0, 0))
    lines_b = cvb.to_lines()
    braille_used = any(0x2800 <= ord(ch) <= 0x28FF and ch != chr(0x2800)
                       for row in lines_b for ch in row)
    ok("braille: disc rasterizes to U+2800 dot glyphs", braille_used)
    bwid, bhgt = px_bbox(rb)
    ok("braille: disc is round (pixel bbox square)", abs(bwid - bhgt) <= 1,
       f"px w={bwid} h={bhgt}")

    # --- braille mode: a diagonal line lights dots -------------------------
    rl = SubcellRaster(8, 4, "braille")
    rl.line(0, 0, rl.pw - 1, rl.ph - 1, WHITE)
    cvl = rl.to_canvas()
    diag_dots = sum(1 for row in cvl.to_lines() for ch in row
                    if 0x2801 <= ord(ch) <= 0x28FF)
    ok("braille: diagonal line lights dots", diag_dots >= 4, f"dot cells={diag_dots}")

    # --- half glyph mapping: fg=top px, bg=bottom px -----------------------
    rm = SubcellRaster(1, 1, "half")
    rm.set_pixel(0, 0, (10, 20, 30))     # top
    rm.set_pixel(0, 1, (200, 210, 220))  # bottom
    g, fg, bg = rm.resolve_cell(0, 0)
    ok("half: fg=top px, bg=bottom px", g == HALF_TOP and fg == (10, 20, 30)
       and bg == (200, 210, 220), f"glyph={g!r} fg={fg} bg={bg}")

    # --- quad glyph mapping: 2x2 mask -> quadrant glyph --------------------
    rq = SubcellRaster(1, 1, "quad")
    rq.set_pixel(0, 0, WHITE)  # TL only -> ▘
    gq, _, _ = rq.resolve_cell(0, 0)
    ok("quad: TL pixel -> ▘", gq == "▘", f"glyph={gq!r}")
    rq.set_pixel(1, 1, WHITE)  # + BR -> ▚ (TL+BR)
    gq2, _, _ = rq.resolve_cell(0, 0)
    ok("quad: TL+BR pixels -> ▚", gq2 == "▚", f"glyph={gq2!r}")

    # --- sextant mode: 2x3 pixels -> U+1FB00 block, +50% vertical res -------
    rs = SubcellRaster(6, 2, "sextant")   # pw=12, ph=6 -> 2x3 px per cell
    ok("sextant: cell is 2x3 px", rs.pxc == 2 and rs.pxr == 3,
       f"pxc={rs.pxc} pxr={rs.pxr}")
    rs1 = SubcellRaster(1, 1, "sextant")
    rs1.set_pixel(0, 0, WHITE)            # top-left px -> bit0 -> glyphs[1]
    gs, _, _ = rs1.resolve_cell(0, 0)
    ok("sextant: TL pixel -> U+1FB00", gs == SEXTANT_GLYPHS[1], f"glyph={gs!r}")
    for i in range(2):                    # all 6 px lit -> full block
        for j in range(3):
            rs1.set_pixel(i, j, WHITE)
    gsf, _, _ = rs1.resolve_cell(0, 0)
    ok("sextant: all 6 px -> full block █", gsf == "█", f"glyph={gsf!r}")
    # two-color split: top row red, bottom row blue -> fg/bg both set
    rs2 = SubcellRaster(1, 1, "sextant")
    for i in range(2):
        rs2.set_pixel(i, 0, (255, 0, 0))
        rs2.set_pixel(i, 2, (0, 0, 255))
    g2, fg2, bg2 = rs2.resolve_cell(0, 0)
    ok("sextant: two-color split gives fg+bg", fg2 is not None and bg2 is not None,
       f"glyph={g2!r} fg={fg2} bg={bg2}")

    # --- sextant GLYPH MAPPING: the U+1FB00 block omits left/right columns
    # (they're the half blocks U+258C/U+2590), so a naive offset misaligns 42 of
    # 62 glyphs. Assert the exact mapping so a regression can't slip through
    # (the earlier test only checked mask=1 and 63, which happened to be right).
    import unicodedata as _ud
    ok("sextant: mask 21 (left column) -> ▌ U+258C", SEXTANT_GLYPHS[21] == "▌",
       f"got {SEXTANT_GLYPHS[21]!r}")
    ok("sextant: mask 42 (right column) -> ▐ U+2590", SEXTANT_GLYPHS[42] == "▐",
       f"got {SEXTANT_GLYPHS[42]!r}")
    _sx_ok = True
    for _m in range(1, 63):
        _g = SEXTANT_GLYPHS[_m]
        if _g == " " or "DIAGONAL" in _ud.name(_g, ""):
            _sx_ok = False
    ok("sextant: all 62 masks map to a real sextant/half glyph (no gaps/diagonals)",
       _sx_ok)
    ok("sextant: mask 3 (TL+TR) is BLOCK SEXTANT-12",
       _ud.name(SEXTANT_GLYPHS[3], "") == "BLOCK SEXTANT-12", f"got {SEXTANT_GLYPHS[3]!r}")

    # --- OKLab perceptual distance sanity: near reds < threshold < red/blue -
    ok("oklab: near colors < split threshold < far colors",
       _dist2((255, 0, 0), (210, 10, 10)) < _SPLIT_THRESHOLD < _dist2((255, 0, 0), (0, 0, 255)),
       f"near={_dist2((255,0,0),(210,10,10)):.0f} far={_dist2((255,0,0),(0,0,255)):.0f}")

    # --- OKLab must not crash on out-of-range / negative channels (no complex) -
    _neg_ok = True
    try:
        _dist2((-5, 0, 0), (300, 128, 64))   # negative + over-255
    except Exception:
        _neg_ok = False
    ok("oklab: out-of-range/negative channels don't crash", _neg_ok)

    # --- transparent cell is left untouched --------------------------------
    rt = SubcellRaster(2, 1, "half")
    rt.set_pixel(0, 0, WHITE)             # only cell 0 lit
    cvt = Canvas(2, 1, bg=(0, 0, 0))
    cvt.set(1, 0, "Z", fg=(1, 2, 3))
    rt.blit_into(cvt, 0, 0)
    ok("blit: transparent cell preserved", cvt.cell(1, 0).char == "Z",
       f"char={cvt.cell(1, 0).char!r}")

    # --- ascii dump: SHOW the round disc (proof, not a square) -------------
    print("\n  half-mode disc (11x11 cells, from an 11x22 square-pixel buffer):")
    for row in lines_h:
        print("    " + row.rstrip())
    print("\n  braille-mode disc (same geometry, 2x4 px/cell):")
    for row in lines_b:
        print("    " + row.rstrip())

    print()
    if getattr(_selftest, "failed"):
        print("SELF-TEST FAILED")
        sys.exit(1)
    print("SELF-TEST OK")


if __name__ == "__main__":
    _selftest()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall