pixel-widget 0.1.0__py3-none-any.whl

pixel_widget/lib.py

@@ -0,0 +1,1220 @@
+from __future__ import annotations
+
+import asyncio
+import colorsys
+import contextlib
+import ctypes
+import ctypes.wintypes as wt
+import functools
+import math
+import os
+import textwrap
+import threading
+import time
+import traceback
+from typing import Literal
+
+import numpy as np
+import pygame
+
+__all__ = ["PixelWidget", "Image", "Layer", "text_width", "hsv", "mix"]
+
+Mode = Literal["set", "clear", "xor"]
+Blend = Literal["or", "xor"]
+Anchor = Literal["top_left", "top_right", "bottom_left", "bottom_right"]
+
+_MODES = ("set", "clear", "xor")
+_BLENDS = ("or", "xor")
+_ANCHORS = ("top_left", "top_right", "bottom_left", "bottom_right")
+_DIRECTIONS = ("horizontal", "vertical")
+_PIN_INTERVAL = 0.5
+_READY_TIMEOUT = 10.0
+
+_WHITE = (255, 255, 255)
+_BLACK = (0, 0, 0)
+_COLORS = {
+    "black": _BLACK, "white": _WHITE, "red": (255, 0, 0), "green": (0, 255, 0), "blue": (0, 0, 255),
+    "yellow": (255, 255, 0), "cyan": (0, 255, 255), "magenta": (255, 0, 255), "orange": (255, 165, 0),
+    "purple": (128, 0, 128), "pink": (255, 105, 180), "gray": (128, 128, 128), "grey": (128, 128, 128),
+    "brown": (139, 69, 19), "teal": (0, 128, 128), "navy": (0, 0, 128), "lime": (0, 255, 0),
+}
+
+
+class _Win32:
+    ENABLED = os.name == "nt"
+
+    GWL_EXSTYLE = -20
+    WS_EX_TOOLWINDOW = 0x00000080
+    WS_EX_APPWINDOW = 0x00040000
+    SWP_NOSIZE = 0x0001
+    SWP_NOACTIVATE = 0x0010
+    SWP_FRAMECHANGED = 0x0020
+    SWP_SHOWWINDOW = 0x0040
+    HWND_TOPMOST = -1
+    HWND_NOTOPMOST = -2
+    SW_HIDE = 0
+    SW_SHOWNOACTIVATE = 4
+    MONITOR_DEFAULTTONULL = 0
+
+    _user32 = None
+
+    @classmethod
+    def user32(cls):
+        if cls._user32 is None:
+            dll = ctypes.WinDLL("user32", use_last_error=True)
+            dll.MonitorFromPoint.argtypes = [wt.POINT, wt.DWORD]
+            dll.MonitorFromPoint.restype = ctypes.c_void_p
+            dll.SetWindowPos.argtypes = [ctypes.c_void_p, ctypes.c_void_p, ctypes.c_int, ctypes.c_int,
+                                         ctypes.c_int, ctypes.c_int, wt.UINT]
+            dll.SetWindowPos.restype = wt.BOOL
+            dll.ShowWindow.argtypes = [ctypes.c_void_p, ctypes.c_int]
+            dll.ShowWindow.restype = wt.BOOL
+            dll.IsIconic.argtypes = [ctypes.c_void_p]
+            dll.IsIconic.restype = wt.BOOL
+            dll.GetWindowLongW.argtypes = [ctypes.c_void_p, ctypes.c_int]
+            dll.GetWindowLongW.restype = ctypes.c_long
+            dll.SetWindowLongW.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_long]
+            dll.SetWindowLongW.restype = ctypes.c_long
+            cls._user32 = dll
+        return cls._user32
+
+    @classmethod
+    def enable_dpi_awareness(cls) -> None:
+        if not cls.ENABLED:
+            return
+        try:
+            ctypes.WinDLL("shcore").SetProcessDpiAwareness(2)
+        except Exception:
+            with contextlib.suppress(Exception):
+                cls.user32().SetProcessDPIAware()
+
+    @classmethod
+    def point_visible(cls, x: int, y: int) -> bool:
+        if not cls.ENABLED:
+            return True
+        point = wt.POINT(int(x), int(y))
+        return bool(cls.user32().MonitorFromPoint(point, cls.MONITOR_DEFAULTTONULL))
+
+    @classmethod
+    def rect_visible(cls, x: int, y: int, width: int, height: int) -> bool:
+        return cls.point_visible(x, y) and cls.point_visible(x + width - 1, y + height - 1)
+
+    @classmethod
+    def hide_from_taskbar(cls, hwnd: int) -> None:
+        if not cls.ENABLED:
+            return
+        user32 = cls.user32()
+        user32.ShowWindow(hwnd, cls.SW_HIDE)
+        style = user32.GetWindowLongW(hwnd, cls.GWL_EXSTYLE)
+        user32.SetWindowLongW(hwnd, cls.GWL_EXSTYLE, (style | cls.WS_EX_TOOLWINDOW) & ~cls.WS_EX_APPWINDOW)
+
+    @classmethod
+    def pin(cls, hwnd: int, x: int, y: int, topmost: bool, frame_changed: bool = False) -> None:
+        if not cls.ENABLED:
+            return
+        user32 = cls.user32()
+        if user32.IsIconic(hwnd):
+            user32.ShowWindow(hwnd, cls.SW_SHOWNOACTIVATE)
+        flags = cls.SWP_NOSIZE | cls.SWP_NOACTIVATE | cls.SWP_SHOWWINDOW
+        if frame_changed:
+            flags |= cls.SWP_FRAMECHANGED
+        order = cls.HWND_TOPMOST if topmost else cls.HWND_NOTOPMOST
+        user32.SetWindowPos(hwnd, order, x, y, 0, 0, flags)
+
+
+_FONT_SOURCE = {
+    "0": "###/#.#/#.#/#.#/###", "1": ".#./##./.#./.#./###", "2": "###/..#/###/#../###",
+    "3": "###/..#/###/..#/###", "4": "#.#/#.#/###/..#/..#", "5": "###/#../###/..#/###",
+    "6": "###/#../###/#.#/###", "7": "###/..#/.#./.#./.#.", "8": "###/#.#/###/#.#/###",
+    "9": "###/#.#/###/..#/###",
+    "A": ".#./#.#/###/#.#/#.#", "B": "##./#.#/##./#.#/##.", "C": ".##/#../#../#../.##",
+    "D": "##./#.#/#.#/#.#/##.", "E": "###/#../##./#../###", "F": "###/#../##./#../#..",
+    "G": ".##/#../#.#/#.#/.##", "H": "#.#/#.#/###/#.#/#.#", "I": "###/.#./.#./.#./###",
+    "J": "..#/..#/..#/#.#/.#.", "K": "#.#/#.#/##./#.#/#.#", "L": "#../#../#../#../###",
+    "M": "#.#/###/###/#.#/#.#", "N": "##./#.#/#.#/#.#/#.#", "O": ".#./#.#/#.#/#.#/.#.",
+    "P": "###/#.#/###/#../#..", "Q": "###/#.#/#.#/###/..#", "R": "###/#.#/##./#.#/#.#",
+    "S": ".##/#../.#./..#/##.", "T": "###/.#./.#./.#./.#.", "U": "#.#/#.#/#.#/#.#/###",
+    "V": "#.#/#.#/#.#/#.#/.#.", "W": "#.#/#.#/###/###/#.#", "X": "#.#/#.#/.#./#.#/#.#",
+    "Y": "#.#/#.#/.#./.#./.#.", "Z": "###/..#/.#./#../###",
+    " ": ".../.../.../.../...", ":": ".../.#./.../.#./...", ".": ".../.../.../.../.#.",
+    ",": ".../.../.../.#./#..", "-": ".../.../###/.../...", "+": ".../.#./###/.#./...",
+    "!": ".#./.#./.#./.../.#.", "?": "###/..#/.##/.../.#.", "/": "..#/..#/.#./#../#..",
+    "%": "#.#/..#/.#./#../#.#", "=": ".../###/.../###/...", "_": ".../.../.../.../###",
+    "(": ".#./#../#../#../.#.", ")": ".#./..#/..#/..#/.#.", "*": ".../#.#/.#./#.#/...",
+    "'": ".#./.#./.../.../...",
+}
+_GLYPHS = {
+    char: np.array([[cell == "#" for cell in row] for row in source.split("/")], dtype=np.uint8)
+    for char, source in _FONT_SOURCE.items()
+}
+_GLYPH_WIDTH = 3
+_GLYPH_HEIGHT = 5
+
+
+def _as_int(value, name: str) -> int:
+    if isinstance(value, bool):
+        raise TypeError(f"{name} must be an integer, got {value!r}")
+    if isinstance(value, (int, np.integer)):
+        return int(value)
+    if isinstance(value, (float, np.floating)) and float(value).is_integer():
+        return int(value)
+    raise TypeError(f"{name} must be an integer, got {value!r}")
+
+
+def _non_negative(value, name: str) -> int:
+    number = _as_int(value, name)
+    if number < 0:
+        raise ValueError(f"{name} must be >= 0, got {number}")
+    return number
+
+
+def _positive(value, name: str) -> int:
+    number = _as_int(value, name)
+    if number <= 0:
+        raise ValueError(f"{name} must be > 0, got {number}")
+    return number
+
+
+def _number(value, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float, np.integer, np.floating)):
+        raise TypeError(f"{name} must be a number, got {value!r}")
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError(f"{name} must be finite, got {value!r}")
+    return number
+
+
+def _unit_float(value, name: str) -> float:
+    number = _number(value, name)
+    if not 0.0 <= number <= 1.0:
+        raise ValueError(f"{name} must be between 0 and 1, got {value!r}")
+    return number
+
+
+def _size_pair(value, name: str) -> tuple[int, int]:
+    if isinstance(value, (tuple, list)):
+        if len(value) != 2:
+            raise ValueError(f"{name} must be an int or a (width, height) pair, got {value!r}")
+        return _positive(value[0], f"{name}[0]"), _positive(value[1], f"{name}[1]")
+    size = _positive(value, name)
+    return size, size
+
+
+def _check_mode(mode: str) -> None:
+    if mode not in _MODES:
+        raise ValueError(f"mode must be one of {_MODES}, got {mode!r}")
+
+
+def _check_blend(blend: str) -> None:
+    if blend not in _BLENDS:
+        raise ValueError(f"blend must be one of {_BLENDS}, got {blend!r}")
+
+
+def _check_anchor(anchor: str) -> None:
+    if anchor not in _ANCHORS:
+        raise ValueError(f"anchor must be one of {_ANCHORS}, got {anchor!r}")
+
+
+def _top_left(point, size: tuple[int, int], anchor: str) -> tuple[int, int]:
+    if not isinstance(point, (tuple, list)) or len(point) != 2:
+        raise ValueError(f"a position must be an (x, y) pair, got {point!r}")
+    x, y = _as_int(point[0], "x"), _as_int(point[1], "y")
+    if "right" in anchor:
+        x -= size[0]
+    if "bottom" in anchor:
+        y -= size[1]
+    return x, y
+
+
+def _parse_color(value) -> tuple[int, int, int]:
+    if isinstance(value, str):
+        text = value.strip().lower()
+        if text in _COLORS:
+            return _COLORS[text]
+        digits = text[1:] if text.startswith("#") else text
+        if len(digits) in (3, 6) and all(char in "0123456789abcdef" for char in digits):
+            if len(digits) == 3:
+                digits = "".join(char * 2 for char in digits)
+            return tuple(int(digits[i:i + 2], 16) for i in (0, 2, 4))
+        raise ValueError(f"unknown color {value!r}: use a name {sorted(_COLORS)}, '#rrggbb' or (r, g, b)")
+    if isinstance(value, bool):
+        raise TypeError(f"color must be a name, '#rrggbb', (r, g, b) or 0xRRGGBB, got {value!r}")
+    if isinstance(value, (int, np.integer)):
+        number = int(value)
+        if not 0 <= number <= 0xFFFFFF:
+            raise ValueError(f"an integer color must be in 0..0xFFFFFF, got {value!r}")
+        return (number >> 16) & 255, (number >> 8) & 255, number & 255
+    if isinstance(value, (tuple, list)) or (isinstance(value, np.ndarray) and value.ndim == 1):
+        if len(value) != 3:
+            raise ValueError(f"a color tuple must have 3 channels (r, g, b), got {value!r}")
+        channels = tuple(_as_int(channel, "color channel") for channel in value)
+        if any(not 0 <= channel <= 255 for channel in channels):
+            raise ValueError(f"color channels must be in 0..255, got {value!r}")
+        return channels
+    raise TypeError(f"color must be a name, '#rrggbb', (r, g, b) or 0xRRGGBB, got {type(value).__name__}")
+
+
+def hsv(h: float, s: float = 1.0, v: float = 1.0) -> tuple[int, int, int]:
+    hue = _number(h, "h")
+    r, g, b = colorsys.hsv_to_rgb((hue / 360.0) % 1.0, _unit_float(s, "s"), _unit_float(v, "v"))
+    return round(r * 255), round(g * 255), round(b * 255)
+
+
+def mix(color1, color2, t: float) -> tuple[int, int, int]:
+    start, end = _parse_color(color1), _parse_color(color2)
+    ratio = _unit_float(t, "t")
+    return tuple(round(a + (b - a) * ratio) for a, b in zip(start, end))
+
+
+def _color_array(color: tuple[int, int, int]) -> np.ndarray:
+    return np.array(color, dtype=np.uint8)
+
+
+def _normalize(value) -> tuple[np.ndarray, bool]:
+    if isinstance(value, Image):
+        return value.array, value.rgb
+    try:
+        array = np.asarray(value)
+    except Exception as exc:
+        raise TypeError(f"cannot convert {type(value).__name__} to a matrix") from exc
+    if array.ndim not in (2, 3):
+        raise ValueError(f"expected a 2D matrix (H, W) or an RGB matrix (H, W, 3), got {array.ndim} dimension(s)")
+    if array.size == 0:
+        raise ValueError("the matrix is empty")
+    if array.ndim == 2:
+        if array.dtype.kind not in "biuf":
+            raise TypeError(f"the matrix must be numeric or boolean, got dtype {array.dtype}")
+        if array.dtype.kind == "f" and np.isnan(array).any():
+            raise ValueError("the matrix contains NaN")
+        return (array != 0).astype(np.uint8), False
+    if array.shape[2] != 3:
+        raise ValueError(f"an RGB matrix must have shape (H, W, 3), got {array.shape}")
+    if array.dtype.kind not in "iu":
+        raise TypeError(f"an RGB matrix must contain integers 0..255, got dtype {array.dtype}")
+    if array.min() < 0 or array.max() > 255:
+        raise ValueError("an RGB matrix must contain values in 0..255")
+    return array.astype(np.uint8), True
+
+
+def _ascii_lines(art: str) -> list[str]:
+    if not isinstance(art, str):
+        raise TypeError(f"ASCII art must be a string, got {type(art).__name__}")
+    lines = textwrap.dedent(art).split("\n")
+    while lines and not lines[0].strip():
+        lines.pop(0)
+    while lines and not lines[-1].strip():
+        lines.pop()
+    if not lines:
+        raise ValueError("ASCII art is empty")
+    return lines
+
+
+def _parse_ascii(art: str, on: str) -> np.ndarray:
+    lines = _ascii_lines(art)
+    width = max(len(line) for line in lines)
+    result = np.zeros((len(lines), width), dtype=np.uint8)
+    for row, line in enumerate(lines):
+        for col, char in enumerate(line):
+            if char in on:
+                result[row, col] = 1
+    return result
+
+
+def _source(value) -> tuple[np.ndarray, bool]:
+    if isinstance(value, str):
+        return _parse_ascii(value, "#X1@"), False
+    return _normalize(value)
+
+
+def _lit(array: np.ndarray) -> np.ndarray:
+    return (array != 0).any(axis=2)
+
+
+def _public(array: np.ndarray, rgb: bool) -> np.ndarray:
+    return array.copy() if rgb else _lit(array).astype(np.uint8)
+
+
+def _to_ascii(lit: np.ndarray, on: str = "#", off: str = ".") -> str:
+    return "\n".join("".join(on if cell else off for cell in row) for row in lit)
+
+
+def _save_png(display: np.ndarray, path, scale: int) -> None:
+    height, width = display.shape[:2]
+    surface = pygame.Surface((width, height), 0, 32)
+    pygame.surfarray.blit_array(surface, np.ascontiguousarray(display.transpose(1, 0, 2)))
+    if scale != 1:
+        surface = pygame.transform.scale(surface, (width * scale, height * scale))
+    pygame.image.save(surface, str(path))
+
+
+def text_width(text: str, spacing: int = 1) -> int:
+    if not isinstance(text, str):
+        raise TypeError(f"text must be a string, got {type(text).__name__}")
+    spacing = _non_negative(spacing, "spacing")
+    lines = text.split("\n")
+    return max((len(line) * (_GLYPH_WIDTH + spacing) - spacing if line else 0) for line in lines)
+
+
+def _draws(method):
+    @functools.wraps(method)
+    def wrapper(self, *args, **kwargs):
+        self._before()
+        with self._guard:
+            result = method(self, *args, **kwargs)
+            self._touch()
+        return result
+
+    return wrapper
+
+
+class _Drawing:
+    width: int
+    height: int
+    rgb: bool
+    strict: bool
+    _guard = contextlib.nullcontext()
+    __iter__ = None
+
+    def _before(self) -> None:
+        pass
+
+    def _touch(self) -> None:
+        pass
+
+    def _visible_array(self) -> np.ndarray:
+        return self._a
+
+    def _resolve(self, color) -> np.ndarray:
+        if color is None:
+            return _color_array(self.color)
+        if not self.rgb:
+            raise ValueError("color= is available only with rgb=True")
+        return _color_array(_parse_color(color))
+
+    def _write(self, y0: int, y1: int, x0: int, x1: int, mode: str, color: np.ndarray) -> None:
+        region = self._a[y0:y1, x0:x1]
+        if mode == "set":
+            region[...] = color
+        elif mode == "clear":
+            region[...] = 0
+        else:
+            region ^= color
+
+    def _fill_rect(self, x: int, y: int, w: int, h: int, mode: str, color: np.ndarray) -> None:
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(self.width, x + w), min(self.height, y + h)
+        if x1 > x0 and y1 > y0:
+            self._write(y0, y1, x0, x1, mode, color)
+
+    def _plot(self, x: int, y: int, mode: str, color: np.ndarray, strict: bool = False) -> None:
+        if 0 <= x < self.width and 0 <= y < self.height:
+            self._write(y, y + 1, x, x + 1, mode, color)
+        elif strict:
+            raise IndexError(f"pixel ({x}, {y}) is outside the {self.width}x{self.height} grid")
+
+    def _blit(self, source: np.ndarray, is_rgb: bool, x: int, y: int, mode: str, transparent: bool,
+              color: np.ndarray) -> None:
+        source_h, source_w = source.shape[:2]
+        x0, y0 = max(0, x), max(0, y)
+        x1, y1 = min(self.width, x + source_w), min(self.height, y + source_h)
+        if x1 <= x0 or y1 <= y0:
+            return
+        part = source[y0 - y:y1 - y, x0 - x:x1 - x]
+        region = self._a[y0:y1, x0:x1]
+        lit = part.any(axis=2) if is_rgb else part.astype(bool)
+        if not transparent:
+            region[...] = part if is_rgb else np.where(lit[..., None], color, 0)
+            return
+        if mode == "clear":
+            region[lit] = 0
+            return
+        values = part[lit] if is_rgb else color
+        if mode == "set":
+            region[lit] = values
+        else:
+            region[lit] ^= values
+
+    def _match(self, value) -> tuple[np.ndarray, bool]:
+        array, is_rgb = _normalize(value)
+        if is_rgb and not self.rgb:
+            raise ValueError("RGB matrices (H, W, 3) need rgb=True")
+        if array.shape[:2] != (self.height, self.width):
+            expected = f"({self.height}, {self.width}" + (", 3)" if is_rgb else ")")
+            raise ValueError(
+                f"matrix shape {array.shape} does not match the grid: expected {expected} = (rows, columns)"
+            )
+        return array, is_rgb
+
+    def _pixels(self, mode: str, x, y, color) -> None:
+        color = self._resolve(color)
+        if x is None and y is None:
+            self._write(0, self.height, 0, self.width, mode, color)
+        elif y is None:
+            if isinstance(x, (int, float, np.number)):
+                raise TypeError("a single pixel needs both coordinates: (x, y)")
+            array, is_rgb = self._match(x)
+            self._blit(array, is_rgb, 0, 0, mode, True, color)
+        elif x is None:
+            raise TypeError("a single pixel needs both coordinates: (x, y)")
+        else:
+            self._plot(_as_int(x, "x"), _as_int(y, "y"), mode, color, strict=self.strict)
+
+    @_draws
+    def set_pixel(self, x=None, y=None, *, color=None) -> None:
+        self._pixels("set", x, y, color)
+
+    @_draws
+    def clear_pixel(self, x=None, y=None) -> None:
+        self._pixels("clear", x, y, None)
+
+    @_draws
+    def xor_pixel(self, x=None, y=None, *, color=None) -> None:
+        self._pixels("xor", x, y, color)
+
+    @_draws
+    def replace(self, matrix, *, color=None) -> None:
+        color = self._resolve(color)
+        array, is_rgb = self._match(matrix)
+        self._a[...] = array if is_rgb else np.where(array[..., None] != 0, color, 0)
+
+    def get_pixel(self, x: int, y: int):
+        self._before()
+        x, y = _as_int(x, "x"), _as_int(y, "y")
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            raise IndexError(f"pixel ({x}, {y}) is outside the {self.width}x{self.height} grid")
+        with self._guard:
+            pixel = self._visible_array()[y, x].copy()
+        if self.rgb:
+            return int(pixel[0]), int(pixel[1]), int(pixel[2])
+        return int(pixel.any())
+
+    def _span(self, key):
+        if not isinstance(key, tuple) or len(key) != 2:
+            raise TypeError("use two indices: obj[x, y] (x goes first, like everywhere in this library)")
+        spans = []
+        single = True
+        for part, limit, name in ((key[0], self.width, "x"), (key[1], self.height, "y")):
+            if isinstance(part, slice):
+                if part.step not in (None, 1):
+                    raise ValueError("slices with a step are not supported")
+                start = 0 if part.start is None else _as_int(part.start, name)
+                stop = limit if part.stop is None else _as_int(part.stop, name)
+                spans.append((start, stop))
+                single = False
+            else:
+                value = _as_int(part, name)
+                spans.append((value, value + 1))
+        return spans[0], spans[1], single
+
+    def __getitem__(self, key):
+        self._before()
+        (x0, x1), (y0, y1), single = self._span(key)
+        if single:
+            return self.get_pixel(x0, y0)
+        x0, x1 = max(0, x0), min(self.width, x1)
+        y0, y1 = max(0, y0), min(self.height, y1)
+        with self._guard:
+            region = self._visible_array()[y0:y1, x0:x1]
+            return _public(region, self.rgb)
+
+    def _index_color(self, value) -> np.ndarray:
+        if isinstance(value, (bool, np.bool_)):
+            return _color_array(_WHITE if value else _BLACK)
+        if not self.rgb:
+            if isinstance(value, (int, np.integer)) and value in (0, 1):
+                return _color_array(_WHITE if value else _BLACK)
+            raise ValueError("in black-and-white mode assign True/False (or 1/0)")
+        return _color_array(_parse_color(value))
+
+    @_draws
+    def __setitem__(self, key, value) -> None:
+        (x0, x1), (y0, y1), single = self._span(key)
+        color = self._index_color(value)
+        if single:
+            self._plot(x0, y0, "set", color, strict=self.strict)
+        else:
+            self._fill_rect(x0, y0, x1 - x0, y1 - y0, "set", color)
+
+    @_draws
+    def rect(self, x: int, y: int, w: int, h: int, fill: bool = True, mode: Mode = "set", *, color=None) -> None:
+        _check_mode(mode)
+        x, y = _as_int(x, "x"), _as_int(y, "y")
+        w, h = _non_negative(w, "w"), _non_negative(h, "h")
+        color = self._resolve(color)
+        if w == 0 or h == 0:
+            return
+        if fill or w <= 2 or h <= 2:
+            self._fill_rect(x, y, w, h, mode, color)
+            return
+        self._fill_rect(x, y, w, 1, mode, color)
+        self._fill_rect(x, y + h - 1, w, 1, mode, color)
+        self._fill_rect(x, y + 1, 1, h - 2, mode, color)
+        self._fill_rect(x + w - 1, y + 1, 1, h - 2, mode, color)
+
+    @_draws
+    def line(self, x0: int, y0: int, x1: int, y1: int, mode: Mode = "set", *, color=None) -> None:
+        _check_mode(mode)
+        x0, y0 = _as_int(x0, "x0"), _as_int(y0, "y0")
+        x1, y1 = _as_int(x1, "x1"), _as_int(y1, "y1")
+        color = self._resolve(color)
+        dx, dy = abs(x1 - x0), -abs(y1 - y0)
+        step_x = 1 if x0 < x1 else -1
+        step_y = 1 if y0 < y1 else -1
+        error = dx + dy
+        while True:
+            self._plot(x0, y0, mode, color)
+            if x0 == x1 and y0 == y1:
+                break
+            doubled = 2 * error
+            if doubled >= dy:
+                error += dy
+                x0 += step_x
+            if doubled <= dx:
+                error += dx
+                y0 += step_y
+
+    @_draws
+    def circle(self, cx: int, cy: int, r: int, fill: bool = False, mode: Mode = "set", *, color=None) -> None:
+        _check_mode(mode)
+        cx, cy = _as_int(cx, "cx"), _as_int(cy, "cy")
+        r = _non_negative(r, "r")
+        color = self._resolve(color)
+        if fill:
+            for dy in range(-r, r + 1):
+                dx = math.isqrt(r * r - dy * dy)
+                self._fill_rect(cx - dx, cy + dy, 2 * dx + 1, 1, mode, color)
+            return
+        points = set()
+        x, y, error = r, 0, 1 - r
+        while x >= y:
+            for px, py in ((x, y), (y, x), (-x, y), (-y, x), (x, -y), (y, -x), (-x, -y), (-y, -x)):
+                points.add((cx + px, cy + py))
+            y += 1
+            if error < 0:
+                error += 2 * y + 1
+            else:
+                x -= 1
+                error += 2 * (y - x) + 1
+        for px, py in points:
+            self._plot(px, py, mode, color)
+
+    @_draws
+    def text(self, x: int, y: int, text: str, mode: Mode = "set", spacing: int = 1, *, color=None) -> int:
+        _check_mode(mode)
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a string, got {type(text).__name__}")
+        left = cursor_x = _as_int(x, "x")
+        cursor_y = _as_int(y, "y")
+        spacing = _non_negative(spacing, "spacing")
+        color = self._resolve(color)
+        for char in text:
+            if char == "\n":
+                cursor_x, cursor_y = left, cursor_y + _GLYPH_HEIGHT + 1
+                continue
+            self._blit(_GLYPHS.get(char.upper(), _GLYPHS["?"]), False, cursor_x, cursor_y, mode, True, color)
+            cursor_x += _GLYPH_WIDTH + spacing
+        return cursor_x
+
+    @_draws
+    def paste(self, source, x: int = 0, y: int = 0, mode: Mode = "set", transparent: bool = True,
+              *, color=None) -> None:
+        _check_mode(mode)
+        if not transparent and mode != "set":
+            raise ValueError("transparent=False works only with mode='set'")
+        array, is_rgb = _source(source)
+        if is_rgb and not self.rgb:
+            raise ValueError("RGB pictures need rgb=True")
+        self._blit(array, is_rgb, _as_int(x, "x"), _as_int(y, "y"), mode, bool(transparent), self._resolve(color))
+
+    @_draws
+    def gradient(self, x: int, y: int, w: int, h: int, color1, color2, direction: str = "horizontal",
+                 mode: Mode = "set") -> None:
+        if not self.rgb:
+            raise ValueError("gradient() needs rgb=True")
+        _check_mode(mode)
+        if direction not in _DIRECTIONS:
+            raise ValueError(f"direction must be one of {_DIRECTIONS}, got {direction!r}")
+        x, y = _as_int(x, "x"), _as_int(y, "y")
+        w, h = _non_negative(w, "w"), _non_negative(h, "h")
+        start = np.array(_parse_color(color1), dtype=float)
+        end = np.array(_parse_color(color2), dtype=float)
+        if w == 0 or h == 0:
+            return
+        if mode == "clear":
+            self._fill_rect(x, y, w, h, "clear", _color_array(_BLACK))
+            return
+        horizontal = direction == "horizontal"
+        steps = w if horizontal else h
+        t = np.linspace(0.0, 1.0, steps) if steps > 1 else np.zeros(1)
+        ramp = np.rint(start + (end - start) * t[:, None]).astype(np.uint8)
+        patch = np.broadcast_to(ramp[None, :, :], (h, w, 3)) if horizontal else np.broadcast_to(ramp[:, None, :], (h, w, 3))
+        self._blit(patch, True, x, y, mode, mode == "xor", _color_array(_BLACK))
+
+    @_draws
+    def scroll(self, dx: int = 0, dy: int = 0, wrap: bool = False) -> None:
+        dx, dy = _as_int(dx, "dx"), _as_int(dy, "dy")
+        if wrap:
+            self._a[...] = np.roll(self._a, (dy, dx), axis=(0, 1))
+            return
+        height, width = self._a.shape[:2]
+        shifted = np.zeros_like(self._a)
+        src_y0, src_y1 = max(0, -dy), min(height, height - dy)
+        src_x0, src_x1 = max(0, -dx), min(width, width - dx)
+        if src_y1 > src_y0 and src_x1 > src_x0:
+            shifted[src_y0 + dy:src_y1 + dy, src_x0 + dx:src_x1 + dx] = self._a[src_y0:src_y1, src_x0:src_x1]
+        self._a[...] = shifted
+
+
+class Image(_Drawing):
+    def __init__(self, width: int, height: int, rgb: bool = False, strict: bool = False):
+        self.width = _positive(width, "width")
+        self.height = _positive(height, "height")
+        self.rgb = bool(rgb)
+        self.strict = strict
+        self._color = _WHITE
+        self._a = np.zeros((self.height, self.width, 3), dtype=np.uint8)
+
+    @staticmethod
+    def from_matrix(matrix, strict: bool = False) -> Image:
+        array, is_rgb = _normalize(matrix)
+        image = Image(array.shape[1], array.shape[0], rgb=is_rgb, strict=strict)
+        image._a[...] = array if is_rgb else (array[..., None] * 255).astype(np.uint8)
+        return image
+
+    @staticmethod
+    def from_ascii(art: str, palette: dict | None = None, on: str = "#X1@", strict: bool = False) -> Image:
+        if palette is None:
+            return Image.from_matrix(_parse_ascii(art, on), strict)
+        if not isinstance(palette, dict) or not palette:
+            raise ValueError("palette must be a non-empty dict like {'#': 'red', 'o': (0, 0, 255)}")
+        colors = {}
+        for char, color in palette.items():
+            if not isinstance(char, str) or len(char) != 1:
+                raise ValueError(f"palette keys must be single characters, got {char!r}")
+            colors[char] = _parse_color(color)
+        lines = _ascii_lines(art)
+        image = Image(max(len(line) for line in lines), len(lines), rgb=True, strict=strict)
+        for row, line in enumerate(lines):
+            for col, char in enumerate(line):
+                if char in colors:
+                    image._a[row, col] = colors[char]
+        return image
+
+    @property
+    def color(self) -> tuple[int, int, int]:
+        return self._color
+
+    @color.setter
+    def color(self, value) -> None:
+        if not self.rgb:
+            raise ValueError("color is available only with rgb=True")
+        self._color = _parse_color(value)
+
+    @property
+    def array(self) -> np.ndarray:
+        with self._guard:
+            return _public(self._a, self.rgb)
+
+    def to_ascii(self, on: str = "#", off: str = ".") -> str:
+        with self._guard:
+            lit = _lit(self._a)
+        return _to_ascii(lit, on, off)
+
+    def save_png(self, path, scale: int = 10) -> None:
+        with self._guard:
+            display = self._a.copy()
+        _save_png(display, path, _positive(scale, "scale"))
+
+    def __str__(self) -> str:
+        return self.to_ascii()
+
+    def __repr__(self) -> str:
+        mode = "rgb" if self.rgb else "mono"
+        return f"<{type(self).__name__} {self.width}x{self.height} {mode}>"
+
+
+class _FrameImage(Image):
+    def __init__(self, width: int, height: int, rgb: bool, strict: bool, color, initial: np.ndarray | None,
+                 publish):
+        super().__init__(width, height, rgb=rgb, strict=strict)
+        self._color = color
+        if initial is not None:
+            self._a[...] = initial
+        self._publish = publish
+
+    def show(self) -> None:
+        self._publish(self._a)
+
+
+class Layer(Image):
+    def __init__(self, widget: PixelWidget, name: str, blend: Blend = "or"):
+        super().__init__(widget.width, widget.height, rgb=widget.rgb, strict=widget.strict)
+        _check_blend(blend)
+        self._widget = widget
+        self._guard = widget._lock
+        self.name = name
+        self.blend = blend
+        self._visible = True
+
+    def _before(self) -> None:
+        self._widget._check()
+
+    def _touch(self) -> None:
+        self._widget._version += 1
+
+    @property
+    def visible(self) -> bool:
+        return self._visible
+
+    @visible.setter
+    def visible(self, value: bool) -> None:
+        with self._guard:
+            self._visible = bool(value)
+            self._widget._version += 1
+
+    def __repr__(self) -> str:
+        return f"<Layer {self.name!r} blend={self.blend} visible={self._visible}>"
+
+
+class _Frame:
+    def __init__(self, widget: PixelWidget, layer: str | Layer, keep: bool):
+        self._widget = widget
+        self._layer_ref = layer
+        self._keep = keep
+        self._image: _FrameImage | None = None
+
+    def open(self) -> _FrameImage:
+        widget = self._widget
+        widget._check()
+        layer = self._layer_ref if isinstance(self._layer_ref, Layer) else widget.layer(self._layer_ref)
+        with widget._lock:
+            initial = layer._a.copy() if self._keep else None
+            color = layer.color
+
+        def publish(array: np.ndarray) -> None:
+            with widget._lock:
+                layer._a[...] = array
+                widget._version += 1
+
+        self._image = _FrameImage(widget.width, widget.height, widget.rgb, widget.strict, color, initial, publish)
+        return self._image
+
+    def __enter__(self) -> _FrameImage:
+        return self.open()
+
+    def __exit__(self, exc_type, exc, traceback_) -> bool:
+        if exc_type is None and self._image is not None:
+            self._image.show()
+        return False
+
+    async def __aenter__(self) -> _FrameImage:
+        return self.open()
+
+    async def __aexit__(self, exc_type, exc, traceback_) -> bool:
+        self.__exit__(exc_type, exc, traceback_)
+        await asyncio.sleep(0)
+        return False
+
+
+class _Pacer:
+    def __init__(self, fps: float):
+        if isinstance(fps, bool) or not isinstance(fps, (int, float)) or fps <= 0:
+            raise ValueError(f"fps must be a positive number, got {fps!r}")
+        self._period = 1.0 / fps
+        self._next = time.monotonic()
+
+    def delay(self) -> float:
+        self._next += self._period
+        now = time.monotonic()
+        remaining = self._next - now
+        if remaining < 0:
+            self._next = now
+            return 0.0
+        return remaining
+
+
+class PixelWidget(_Drawing):
+    def __init__(
+        self,
+        width: int = 32,
+        height: int = 32,
+        window_size: int | tuple[int, int] = 320,
+        title: str = "Pinned Widget",
+        position: tuple[int, int] = (3840, 1032),
+        fallback_position: tuple[int, int] = (1920, 1008),
+        anchor: Anchor = "bottom_right",
+        fps: int = 30,
+        always_on_top: bool = True,
+        hide_from_taskbar: bool = True,
+        strict: bool = False,
+        rgb: bool = False,
+        on_color=None,
+        off_color=None,
+        brightness: float = 1.0,
+    ):
+        self.width = _positive(width, "width")
+        self.height = _positive(height, "height")
+        self.window_width, self.window_height = _size_pair(window_size, "window_size")
+        _check_anchor(anchor)
+        if isinstance(fps, bool) or not isinstance(fps, (int, float)) or fps <= 0:
+            raise ValueError(f"fps must be a positive number, got {fps!r}")
+        if rgb and (on_color is not None or off_color is not None):
+            raise ValueError("on_color/off_color are for the black-and-white mode; they cannot be used with rgb=True")
+
+        self.title = title
+        self.anchor = anchor
+        self.fps = fps
+        self.always_on_top = always_on_top
+        self.hide_from_taskbar = hide_from_taskbar
+        self.strict = strict
+        self.rgb = bool(rgb)
+        self._on = None if rgb else _parse_color("white" if on_color is None else on_color)
+        self._off = None if rgb else _parse_color("black" if off_color is None else off_color)
+        self._brightness = _unit_float(brightness, "brightness")
+
+        _Win32.enable_dpi_awareness()
+        window = (self.window_width, self.window_height)
+        preferred = _top_left(position, window, anchor)
+        fallback = _top_left(fallback_position, window, anchor)
+        self.position = preferred if _Win32.rect_visible(*preferred, *window) else fallback
+
+        self._lock = threading.RLock()
+        self._guard = self._lock
+        self._cond = threading.Condition(self._lock)
+        self._version = 0
+        self._presented = -1
+        self._layers: dict[str, Layer] = {}
+        self._base = self._new_layer("main", "or")
+
+        self._running = True
+        self._error: BaseException | None = None
+        self._ready = threading.Event()
+        self._closed = threading.Event()
+
+        os.environ["SDL_VIDEO_WINDOW_POS"] = f"{self.position[0]},{self.position[1]}"
+        self._thread = threading.Thread(target=self._run, name="PixelWidget-render", daemon=True)
+        self._thread.start()
+
+        if not self._ready.wait(timeout=_READY_TIMEOUT):
+            raise RuntimeError(f"PixelWidget: the window was not created within {_READY_TIMEOUT:.0f} seconds")
+        self._check()
+
+    @property
+    def _a(self) -> np.ndarray:
+        return self._base._a
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+    @property
+    def layers(self) -> list[str]:
+        with self._lock:
+            return list(self._layers)
+
+    @property
+    def color(self) -> tuple[int, int, int]:
+        return self._base.color
+
+    @color.setter
+    def color(self, value) -> None:
+        self._base.color = value
+
+    @property
+    def on_color(self):
+        return self._on
+
+    @on_color.setter
+    def on_color(self, value) -> None:
+        self._set_mono_color("_on", value)
+
+    @property
+    def off_color(self):
+        return self._off
+
+    @off_color.setter
+    def off_color(self, value) -> None:
+        self._set_mono_color("_off", value)
+
+    @property
+    def brightness(self) -> float:
+        return self._brightness
+
+    @brightness.setter
+    def brightness(self, value: float) -> None:
+        value = _unit_float(value, "brightness")
+        with self._lock:
+            self._brightness = value
+            self._version += 1
+
+    def _set_mono_color(self, attribute: str, value) -> None:
+        if self.rgb:
+            raise ValueError("on_color/off_color are for the black-and-white mode")
+        color = _parse_color(value)
+        with self._lock:
+            setattr(self, attribute, color)
+            self._version += 1
+
+    def _before(self) -> None:
+        self._check()
+
+    def _touch(self) -> None:
+        self._version += 1
+
+    def _check(self) -> None:
+        if self._error is not None:
+            raise RuntimeError("PixelWidget: the window thread has crashed") from self._error
+
+    def _new_layer(self, name: str, blend: Blend) -> Layer:
+        layer = Layer(self, name, blend)
+        self._layers[name] = layer
+        return layer
+
+    def layer(self, name: str = "main", blend: Blend | None = None) -> Layer:
+        if not isinstance(name, str) or not name:
+            raise ValueError(f"a layer name must be a non-empty string, got {name!r}")
+        if blend is not None:
+            _check_blend(blend)
+        with self._lock:
+            layer = self._layers.get(name)
+            if layer is None:
+                layer = self._new_layer(name, blend or "or")
+                self._version += 1
+            elif blend is not None and blend != layer.blend:
+                layer.blend = blend
+                self._version += 1
+            return layer
+
+    def remove_layer(self, name: str) -> None:
+        if name == "main":
+            raise ValueError("the 'main' layer cannot be removed")
+        with self._lock:
+            if self._layers.pop(name, None) is not None:
+                self._version += 1
+
+    def reset(self) -> None:
+        self._check()
+        with self._lock:
+            for name in list(self._layers):
+                if name != "main":
+                    del self._layers[name]
+            self._base._a[...] = 0
+            self._base._visible = True
+            self._base.blend = "or"
+            self._base._color = _WHITE
+            self._version += 1
+
+    def _compose_locked(self) -> np.ndarray:
+        image = np.zeros((self.height, self.width, 3), dtype=np.uint8)
+        for layer in self._layers.values():
+            if not layer._visible:
+                continue
+            if layer.blend == "xor":
+                image ^= layer._a
+            else:
+                lit = layer._a.any(axis=2)
+                image[lit] = layer._a[lit]
+        return image
+
+    def _visible_array(self) -> np.ndarray:
+        return self._compose_locked()
+
+    def _display_locked(self) -> np.ndarray:
+        image = self._compose_locked()
+        if not self.rgb:
+            image = np.where(_lit(image)[..., None], _color_array(self._on), _color_array(self._off))
+        if self._brightness < 1.0:
+            image = (image * self._brightness).astype(np.uint8)
+        return image.astype(np.uint8)
+
+    def frame(self, layer: str | Layer = "main", keep: bool = False) -> _Frame:
+        return _Frame(self, layer, keep)
+
+    def loop(self, fps: float = 25, layer: str | Layer = "main", keep: bool = False, frames: int | None = None):
+        pacer = _Pacer(fps)
+        limit = None if frames is None else _non_negative(frames, "frames")
+        count = 0
+        while self._running and (limit is None or count < limit):
+            image = self.frame(layer, keep).open()
+            try:
+                yield image
+            finally:
+                image.show()
+            count += 1
+            time.sleep(pacer.delay())
+        self._check()
+
+    async def aloop(self, fps: float = 25, layer: str | Layer = "main", keep: bool = False,
+                    frames: int | None = None):
+        pacer = _Pacer(fps)
+        limit = None if frames is None else _non_negative(frames, "frames")
+        count = 0
+        while self._running and (limit is None or count < limit):
+            image = self.frame(layer, keep).open()
+            try:
+                yield image
+            finally:
+                image.show()
+            count += 1
+            await asyncio.sleep(pacer.delay())
+        self._check()
+
+    def play(self, frames, fps: float = 10, repeat: int | None = 1, layer: str | Layer = "main") -> None:
+        pictures = [_source(item)[0] for item in frames]
+        pacer = _Pacer(fps)
+        limit = None if repeat is None else _non_negative(repeat, "repeat")
+        count = 0
+        while self._running and (limit is None or count < limit):
+            for picture in pictures:
+                if not self._running:
+                    return
+                with self.frame(layer) as image:
+                    image.paste(picture, 0, 0, transparent=False)
+                time.sleep(pacer.delay())
+            count += 1
+        self._check()
+
+    async def aplay(self, frames, fps: float = 10, repeat: int | None = 1, layer: str | Layer = "main") -> None:
+        pictures = [_source(item)[0] for item in frames]
+        pacer = _Pacer(fps)
+        limit = None if repeat is None else _non_negative(repeat, "repeat")
+        count = 0
+        while self._running and (limit is None or count < limit):
+            for picture in pictures:
+                if not self._running:
+                    return
+                async with self.frame(layer) as image:
+                    image.paste(picture, 0, 0, transparent=False)
+                await asyncio.sleep(pacer.delay())
+            count += 1
+        self._check()
+
+    def flush(self, timeout: float = 1.0) -> bool:
+        with self._cond:
+            target = self._version
+            self._cond.wait_for(lambda: self._presented >= target or not self._running, timeout)
+            return self._presented >= target or not self._running
+
+    async def aflush(self, timeout: float = 1.0) -> bool:
+        return await asyncio.get_running_loop().run_in_executor(None, self.flush, timeout)
+
+    def wait(self, timeout: float | None = None) -> bool:
+        return self._closed.wait(timeout)
+
+    def close(self) -> None:
+        self._running = False
+        if threading.current_thread() is not self._thread:
+            self._thread.join(timeout=2)
+
+    def __enter__(self) -> PixelWidget:
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+    def get_frame(self) -> np.ndarray:
+        with self._lock:
+            return _public(self._compose_locked(), self.rgb)
+
+    def to_ascii(self, on: str = "#", off: str = ".") -> str:
+        with self._lock:
+            lit = _lit(self._compose_locked())
+        return _to_ascii(lit, on, off)
+
+    def save_png(self, path, scale: int | None = None) -> None:
+        scale = max(1, self.window_width // self.width) if scale is None else _positive(scale, "scale")
+        with self._lock:
+            display = self._display_locked()
+        _save_png(display, path, scale)
+
+    def snapshot(self) -> dict[str, tuple[np.ndarray, bool, str, tuple[int, int, int]]]:
+        with self._lock:
+            return {
+                name: (layer._a.copy(), layer._visible, layer.blend, layer._color)
+                for name, layer in self._layers.items()
+            }
+
+    def restore(self, snapshot: dict[str, tuple[np.ndarray, bool, str, tuple[int, int, int]]]) -> None:
+        self._check()
+        with self._lock:
+            for name in list(self._layers):
+                if name != "main" and name not in snapshot:
+                    del self._layers[name]
+            for name, (array, visible, blend, color) in snapshot.items():
+                layer = self._layers.get(name) or self._new_layer(name, blend)
+                layer._a[...] = array
+                layer._visible = visible
+                layer.blend = blend
+                layer._color = color
+            self._version += 1
+
+    def __str__(self) -> str:
+        return self.to_ascii()
+
+    def __repr__(self) -> str:
+        state = "running" if self._running else "closed"
+        mode = "rgb" if self.rgb else "mono"
+        return (f"<PixelWidget {self.width}x{self.height} {mode} window={self.window_width}x{self.window_height} "
+                f"at {self.position} {state} layers={self.layers}>")
+
+    def _pin(self, hwnd: int, first: bool = False) -> None:
+        _Win32.pin(hwnd, *self.position, self.always_on_top, frame_changed=first)
+
+    def _open_window(self):
+        pygame.display.init()
+        screen = pygame.display.set_mode((self.window_width, self.window_height), pygame.NOFRAME)
+        pygame.display.set_caption(self.title)
+        small = pygame.Surface((self.width, self.height))
+        hwnd = pygame.display.get_wm_info()["window"] if _Win32.ENABLED else None
+        if hwnd is not None:
+            if self.hide_from_taskbar:
+                _Win32.hide_from_taskbar(hwnd)
+            self._pin(hwnd, first=True)
+        return screen, small, hwnd
+
+    def _poll_events(self) -> None:
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                self._running = False
+            elif event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
+                self._running = False
+
+    def _render_loop(self, screen, small, hwnd) -> None:
+        size = (self.window_width, self.window_height)
+        clock = pygame.time.Clock()
+        last_pin = time.monotonic()
+        rendered = -1
+        while self._running:
+            self._poll_events()
+            if hwnd is not None and time.monotonic() - last_pin > _PIN_INTERVAL:
+                self._pin(hwnd)
+                last_pin = time.monotonic()
+            with self._lock:
+                version = self._version
+                image = self._display_locked() if version != rendered else None
+            if image is not None:
+                pygame.surfarray.blit_array(small, np.ascontiguousarray(image.transpose(1, 0, 2)))
+                screen.blit(pygame.transform.scale(small, size), (0, 0))
+                pygame.display.flip()
+                rendered = version
+                with self._cond:
+                    self._presented = version
+                    self._cond.notify_all()
+            clock.tick(self.fps)
+
+    def _run(self) -> None:
+        try:
+            screen, small, hwnd = self._open_window()
+            self._ready.set()
+            self._render_loop(screen, small, hwnd)
+        except BaseException as exc:
+            self._error = exc
+            traceback.print_exc()
+        finally:
+            self._running = False
+            with contextlib.suppress(Exception):
+                pygame.display.quit()
+            self._ready.set()
+            with self._cond:
+                self._cond.notify_all()
+            self._closed.set()