staticfx 2.0.0__py3-none-any.whl

staticfx/core/color.py

@@ -0,0 +1,89 @@
+"""24-bit colour value and the handful of operations effects actually use."""
+
+from __future__ import annotations
+
+import colorsys
+from itertools import pairwise
+from typing import NamedTuple
+
+
+class RGB(NamedTuple):
+    """An sRGB colour with 0-255 channels.
+
+    A NamedTuple rather than a dataclass: colours are created per cell per
+    frame, and tuples are the cheapest immutable, hashable value in CPython.
+    Callers are expected to pass in-range ints; use :func:`rgb` to clamp.
+    """
+
+    r: int
+    g: int
+    b: int
+
+
+BLACK = RGB(0, 0, 0)
+WHITE = RGB(255, 255, 255)
+
+
+def clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
+    return low if value < low else high if value > high else value
+
+
+def rgb(r: float, g: float, b: float) -> RGB:
+    """Build a colour from arbitrary numbers, rounding and clamping to 0-255."""
+    return RGB(
+        int(clamp(round(r), 0, 255)), int(clamp(round(g), 0, 255)), int(clamp(round(b), 0, 255))
+    )
+
+
+def lerp(a: RGB, b: RGB, t: float) -> RGB:
+    t = clamp(t)
+    return RGB(
+        int(a.r + (b.r - a.r) * t + 0.5),
+        int(a.g + (b.g - a.g) * t + 0.5),
+        int(a.b + (b.b - a.b) * t + 0.5),
+    )
+
+
+def scale(color: RGB, factor: float) -> RGB:
+    """Darken (factor < 1) or brighten (factor > 1) by multiplying each channel."""
+    return rgb(color.r * factor, color.g * factor, color.b * factor)
+
+
+def tint(color: RGB, amount: float) -> RGB:
+    """Mix towards white by ``amount`` (0 = unchanged, 1 = white)."""
+    return lerp(color, WHITE, amount)
+
+
+def hsv(h: float, s: float = 1.0, v: float = 1.0) -> RGB:
+    r, g, b = colorsys.hsv_to_rgb(h % 1.0, clamp(s), clamp(v))
+    return RGB(int(r * 255 + 0.5), int(g * 255 + 0.5), int(b * 255 + 0.5))
+
+
+def hue_of(color: RGB) -> float:
+    return colorsys.rgb_to_hsv(color.r / 255, color.g / 255, color.b / 255)[0]
+
+
+def gradient(stops: list[tuple[float, RGB]], t: float) -> RGB:
+    """Sample a piecewise-linear gradient given ``(position, colour)`` stops."""
+    t = clamp(t)
+    for (p0, c0), (p1, c1) in pairwise(stops):
+        if t <= p1:
+            return c0 if p1 == p0 else lerp(c0, c1, (t - p0) / (p1 - p0))
+    return stops[-1][1]
+
+
+def parse_hex(text: str) -> RGB:
+    """Parse ``#rgb`` or ``#rrggbb`` (the ``#`` is optional)."""
+    value = text.strip().lstrip("#")
+    if len(value) == 3:
+        value = "".join(ch * 2 for ch in value)
+    if len(value) != 6:
+        raise ValueError(f"not a hex colour: {text!r}")
+    try:
+        return RGB(int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16))
+    except ValueError:
+        raise ValueError(f"not a hex colour: {text!r}") from None
+
+
+def to_hex(color: RGB) -> str:
+    return f"#{color.r:02x}{color.g:02x}{color.b:02x}"

staticfx/core/frame.py

@@ -0,0 +1,85 @@
+"""The drawing surface: a grid of coloured characters."""
+
+from __future__ import annotations
+
+from staticfx.core.color import BLACK, RGB
+
+
+class Cell:
+    __slots__ = ("char", "color")
+
+    def __init__(self, char: str = " ", color: RGB = BLACK) -> None:
+        self.char = char
+        self.color = color
+
+    def __repr__(self) -> str:
+        return f"Cell({self.char!r}, {self.color})"
+
+
+class Frame:
+    """A ``width`` x ``height`` grid of :class:`Cell`.
+
+    A space is "empty": the renderer skips its colour, and effects treat it as
+    transparent. Effects write to ``cells`` directly in hot loops; everything
+    else should use :meth:`put` and :meth:`text`, which clip to the frame.
+    """
+
+    def __init__(self, width: int, height: int) -> None:
+        self.width = max(1, int(width))
+        self.height = max(1, int(height))
+        self.cells = self._blank()
+
+    def _blank(self) -> list[list[Cell]]:
+        return [[Cell() for _ in range(self.width)] for _ in range(self.height)]
+
+    def resize(self, width: int, height: int) -> None:
+        width, height = max(1, int(width)), max(1, int(height))
+        if (width, height) != (self.width, self.height):
+            self.width, self.height = width, height
+            self.cells = self._blank()
+
+    def clear(self) -> None:
+        for row in self.cells:
+            for cell in row:
+                cell.char = " "
+                cell.color = BLACK
+
+    def put(self, x: int, y: int, char: str, color: RGB) -> None:
+        if 0 <= x < self.width and 0 <= y < self.height:
+            cell = self.cells[y][x]
+            cell.char = char
+            cell.color = color
+
+    def char_at(self, x: int, y: int) -> str:
+        if 0 <= x < self.width and 0 <= y < self.height:
+            return self.cells[y][x].char
+        return " "
+
+    def text(self, x: int, y: int, text: str, color: RGB) -> None:
+        """Write ``text`` starting at ``(x, y)``, clipped to the frame."""
+        if not 0 <= y < self.height or x >= self.width:
+            return
+        row = self.cells[y]
+        start = max(0, -x)
+        for offset, char in enumerate(text[start : self.width - x], start):
+            cell = row[x + offset]
+            cell.char = char
+            cell.color = color
+
+    def fill(self, x: int, y: int, width: int, height: int, char: str = " ") -> None:
+        """Fill a rectangle (clipped) with ``char``; used to blank panel backgrounds."""
+        for row in self.cells[max(0, y) : max(0, y + height)]:
+            for cell in row[max(0, x) : max(0, x + width)]:
+                cell.char = char
+
+    def dim(self, factor: float) -> None:
+        """Darken everything already drawn; used behind modal panels."""
+        for row in self.cells:
+            for cell in row:
+                if cell.char != " ":
+                    c = cell.color
+                    cell.color = RGB(int(c.r * factor), int(c.g * factor), int(c.b * factor))
+
+    def lines(self) -> list[str]:
+        """Plain text of each row, for tests and ``staticfx render``."""
+        return ["".join(cell.char for cell in row) for row in self.cells]

staticfx/core/glyphs.py

@@ -0,0 +1,15 @@
+"""Character pools shared by several effects."""
+
+from __future__ import annotations
+
+import string
+
+TECH = string.ascii_uppercase + string.digits + "!@#$%^&*<>/\\|=+-_~"
+KATAKANA = "".join(chr(code) for code in range(0xFF66, 0xFF9E)) + string.digits
+BINARY = "01"
+HEX = "0123456789ABCDEF"
+
+
+def tech_glyphs(unicode: bool) -> str:
+    """The "terminal noise" pool: half-width katakana when Unicode is enabled."""
+    return KATAKANA if unicode else TECH

staticfx/core/keys.py

@@ -0,0 +1,116 @@
+"""Keyboard input: raw bytes from the terminal -> key names.
+
+Printable characters come back as themselves (``"a"``, ``"?"``). Everything
+else gets a name: ``up``, ``down``, ``left``, ``right``, ``home``, ``end``,
+``pageup``, ``pagedown``, ``delete``, ``enter``, ``tab``, ``shift-tab``,
+``backspace``, ``escape``, ``space`` and ``ctrl-a`` .. ``ctrl-z``.
+"""
+
+from __future__ import annotations
+
+import os
+import select
+
+_CSI_LETTER = {
+    "A": "up",
+    "B": "down",
+    "C": "right",
+    "D": "left",
+    "H": "home",
+    "F": "end",
+    "Z": "shift-tab",
+}
+_CSI_TILDE = {
+    "1": "home",
+    "2": "insert",
+    "3": "delete",
+    "4": "end",
+    "5": "pageup",
+    "6": "pagedown",
+    "7": "home",
+    "8": "end",
+}
+_CONTROL = {"\r": "enter", "\n": "enter", "\t": "tab", "\x7f": "backspace", "\x08": "backspace"}
+
+# How long to wait for the rest of an escape sequence before deciding the
+# user pressed Esc on its own. Terminals send sequences in one write, so this
+# only matters on very slow links.
+ESCAPE_TIMEOUT = 0.03
+
+
+def decode(data: str) -> tuple[list[str], str]:
+    """Split ``data`` into key names.
+
+    Returns ``(keys, rest)`` where ``rest`` is an incomplete escape sequence
+    at the end of ``data`` that should be prepended to the next read.
+    """
+    keys: list[str] = []
+    i, size = 0, len(data)
+    while i < size:
+        char = data[i]
+        if char == "\x1b":
+            if i + 1 == size:
+                return keys, data[i:]
+            if data[i + 1] in "[O":
+                end = i + 2
+                while end < size and (data[end].isdigit() or data[end] == ";"):
+                    end += 1
+                if end == size:
+                    return keys, data[i:]
+                final, params = data[end], data[i + 2 : end].split(";", maxsplit=1)[0]
+                if final == "~":
+                    keys.append(_CSI_TILDE.get(params, "unknown"))
+                else:
+                    keys.append(_CSI_LETTER.get(final, "unknown"))
+                i = end + 1
+                continue
+            keys.append("escape")  # Esc, or Alt+key: the key follows separately
+        elif char in _CONTROL:
+            keys.append(_CONTROL[char])
+        elif char == " ":
+            keys.append("space")
+        elif "\x01" <= char <= "\x1a":
+            keys.append("ctrl-" + chr(ord(char) + 96))
+        elif char.isprintable():
+            keys.append(char)
+        i += 1
+    return keys, ""
+
+
+class KeyReader:
+    """Non-blocking reads from a terminal file descriptor."""
+
+    def __init__(self, fd: int) -> None:
+        self.fd = fd
+
+    def _ready(self, timeout: float) -> bool:
+        try:
+            return bool(select.select([self.fd], [], [], timeout)[0])
+        except (OSError, ValueError):
+            return False
+
+    def _read(self) -> str:
+        try:
+            return os.read(self.fd, 1024).decode("utf-8", errors="ignore")
+        except OSError:
+            return ""
+
+    def read(self) -> list[str]:
+        """All keys pressed since the last call (possibly none)."""
+        data = ""
+        while self._ready(0):
+            chunk = self._read()
+            if not chunk:
+                break
+            data += chunk
+        if not data:
+            return []
+        keys, rest = decode(data)
+        if rest and self._ready(ESCAPE_TIMEOUT):
+            more, rest = decode(rest + self._read())
+            keys += more
+        if rest == "\x1b":  # a lone Esc that nothing followed
+            keys.append("escape")
+        # Anything else left over is a sequence that never completed; dropping
+        # it is better than letting it swallow the next key press.
+        return keys

staticfx/core/renderer.py

@@ -0,0 +1,84 @@
+"""Frame -> ANSI escape sequences.
+
+Each frame is encoded row by row and only rows that changed since the last
+frame are written. Busy effects change nearly every row, so the saving there
+is small (under 10% across the built-ins), but paused effects, slow ones and
+still parts of the screen cost almost nothing to redraw.
+"""
+
+from __future__ import annotations
+
+from staticfx.core.color import RGB
+from staticfx.core.frame import Cell, Frame
+
+ESC = "\x1b"
+RESET = f"{ESC}[0m"
+CLEAR_EOL = f"{ESC}[K"
+
+_CUBE = (0, 95, 135, 175, 215, 255)
+
+
+def _cube_index(value: int) -> int:
+    return min(range(6), key=lambda i: abs(_CUBE[i] - value))
+
+
+def xterm256(color: RGB) -> int:
+    """Nearest xterm-256 palette index (6x6x6 cube or the grey ramp)."""
+    r, g, b = color
+    if r == g == b:
+        if r < 8:
+            return 16
+        if r > 248:
+            return 231
+        return 232 + (r - 8) * 24 // 247
+    return 16 + 36 * _cube_index(r) + 6 * _cube_index(g) + _cube_index(b)
+
+
+class Renderer:
+    def __init__(self, truecolor: bool = True) -> None:
+        self.truecolor = truecolor
+        self._sgr: dict[RGB, str] = {}
+        self._previous: list[str] = []
+
+    def invalidate(self) -> None:
+        """Forget what is on screen; the next frame is written in full."""
+        self._previous = []
+
+    def _color(self, color: RGB) -> str:
+        sequence = self._sgr.get(color)
+        if sequence is None:
+            if len(self._sgr) > 20_000:  # animated palettes produce endless new colours
+                self._sgr.clear()
+            if self.truecolor:
+                sequence = f"{ESC}[38;2;{color.r};{color.g};{color.b}m"
+            else:
+                sequence = f"{ESC}[38;5;{xterm256(color)}m"
+            self._sgr[color] = sequence
+        return sequence
+
+    def encode_row(self, row: list[Cell]) -> str:
+        parts: list[str] = []
+        current: RGB | None = None
+        for cell in row:
+            char = cell.char
+            if char != " " and cell.color != current:
+                current = cell.color
+                parts.append(self._color(current))
+            parts.append(char)
+        parts.append(RESET)
+        parts.append(CLEAR_EOL)
+        return "".join(parts)
+
+    def full(self, frame: Frame) -> str:
+        """The whole frame as one string, with no cursor positioning."""
+        return "\n".join(self.encode_row(row) for row in frame.cells)
+
+    def diff(self, frame: Frame) -> str:
+        """Only the rows that changed since the previous call, with cursor moves."""
+        rows = [self.encode_row(row) for row in frame.cells]
+        previous = self._previous
+        if len(previous) != len(rows):
+            previous = [""] * len(rows)
+        out = [f"{ESC}[{y + 1};1H{line}" for y, line in enumerate(rows) if line != previous[y]]
+        self._previous = rows
+        return "".join(out)

staticfx/core/terminal.py

@@ -0,0 +1,148 @@
+"""Owning the terminal while the app runs.
+
+:class:`Terminal` switches to the alternate screen, hides the cursor and puts
+the tty in a raw-ish mode, and guarantees all of that is undone however the
+program exits - normal quit, exception, ``SIGTERM`` - and around a Ctrl-Z
+suspend.
+
+Signal generation (ISIG) is turned off, so Ctrl-C and Ctrl-Z arrive as
+ordinary keys. That lets each screen decide what they mean: Ctrl-C in the
+Studio asks before discarding work instead of killing the process.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import sys
+from types import FrameType
+from typing import Any, TextIO
+
+try:
+    import termios
+except ImportError:  # Windows
+    termios = None  # type: ignore[assignment]
+
+ESC = "\x1b"
+ALT_SCREEN_ON = f"{ESC}[?1049h"
+ALT_SCREEN_OFF = f"{ESC}[?1049l"
+CURSOR_HIDE = f"{ESC}[?25l"
+CURSOR_SHOW = f"{ESC}[?25h"
+WRAP_OFF = f"{ESC}[?7l"
+WRAP_ON = f"{ESC}[?7h"
+CLEAR = f"{ESC}[2J{ESC}[H"
+RESET = f"{ESC}[0m"
+
+# Indexes into the list returned by termios.tcgetattr().
+_IFLAG, _LFLAG, _CC = 0, 3, 6
+
+
+def terminal_size() -> tuple[int, int]:
+    """Current ``(columns, lines)``.
+
+    Asks the tty directly: ``shutil.get_terminal_size`` prefers the
+    ``COLUMNS``/``LINES`` environment variables, which go stale on resize.
+    """
+    for stream in (sys.stdout, sys.stderr, sys.stdin):
+        try:
+            size = os.get_terminal_size(stream.fileno())
+        except (OSError, ValueError, AttributeError):
+            continue
+        if size.columns > 0 and size.lines > 0:
+            return size.columns, size.lines
+    size = shutil.get_terminal_size((80, 24))
+    return max(1, size.columns), max(1, size.lines)
+
+
+def is_interactive() -> bool:
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def supported() -> bool:
+    """Interactive mode needs POSIX terminal control (Linux, macOS, WSL)."""
+    return termios is not None
+
+
+class Terminal:
+    def __init__(self, out: TextIO | None = None, fd: int | None = None) -> None:
+        self.out = out or sys.stdout
+        self.fd = sys.stdin.fileno() if fd is None else fd
+        self.resized = True  # the screen needs a full redraw (set on start and after fg)
+        self._saved_mode: list | None = None
+        self._saved_handlers: dict[int, Any] = {}
+        self._active = False
+
+    def __enter__(self) -> Terminal:
+        self._saved_mode = termios.tcgetattr(self.fd)
+        self._install_handlers()
+        self._activate()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._deactivate()
+        for signum, handler in self._saved_handlers.items():
+            signal.signal(signum, handler)
+        self._saved_handlers.clear()
+
+    def _activate(self) -> None:
+        mode = termios.tcgetattr(self.fd)
+        mode[_IFLAG] &= ~(termios.IXON | termios.ICRNL)
+        mode[_LFLAG] &= ~(termios.ECHO | termios.ICANON | termios.ISIG | termios.IEXTEN)
+        mode[_CC][termios.VMIN] = 1
+        mode[_CC][termios.VTIME] = 0
+        termios.tcsetattr(self.fd, termios.TCSAFLUSH, mode)
+        self.write(ALT_SCREEN_ON + CURSOR_HIDE + WRAP_OFF + CLEAR)
+        self._active = True
+        self.resized = True
+
+    def _deactivate(self) -> None:
+        if not self._active:
+            return
+        self._active = False
+        self.write(RESET + WRAP_ON + CURSOR_SHOW + ALT_SCREEN_OFF)
+        if self._saved_mode is not None:
+            termios.tcsetattr(self.fd, termios.TCSADRAIN, self._saved_mode)
+
+    def _install_handlers(self) -> None:
+        wanted = {
+            signal.SIGTERM: self._on_terminate,
+            signal.SIGHUP: self._on_terminate,
+            signal.SIGTSTP: self._on_stop,
+            signal.SIGCONT: self._on_continue,
+        }
+        for signum, handler in wanted.items():
+            self._saved_handlers[signum] = signal.signal(signum, handler)
+
+    def _on_terminate(self, signum: int, _frame: FrameType | None) -> None:
+        raise SystemExit(128 + signum)
+
+    def _on_stop(self, _signum: int, _frame: FrameType | None) -> None:
+        self.suspend()
+
+    def _on_continue(self, _signum: int, _frame: FrameType | None) -> None:
+        if not self._active:
+            self._activate()
+
+    def suspend(self) -> None:
+        """Hand the terminal back to the shell and stop, like Ctrl-Z in any TUI.
+
+        Execution continues here after ``fg``; the SIGCONT handler has
+        restored the screen by then.
+        """
+        self._deactivate()
+        signal.signal(signal.SIGTSTP, signal.SIG_DFL)
+        os.kill(os.getpid(), signal.SIGTSTP)
+        signal.signal(signal.SIGTSTP, self._on_stop)
+        if not self._active:  # SIGCONT can arrive before the handler is reinstalled
+            self._activate()
+
+    def write(self, data: str) -> None:
+        self.out.write(data)
+        self.out.flush()
+
+    def size(self) -> tuple[int, int]:
+        return terminal_size()

staticfx/effects/__init__.py

@@ -0,0 +1 @@
+"""Effects: the base class, the hand-written built-ins, the procedural engine and the registry."""

staticfx/effects/base.py

@@ -0,0 +1,88 @@
+"""The interface every effect implements."""
+
+from __future__ import annotations
+
+import random
+
+from staticfx.core.color import RGB
+from staticfx.core.frame import Frame
+from staticfx.themes import Theme
+
+PALETTE_STEPS = 48
+
+
+class Effect:
+    """Base class for all effects.
+
+    Subclasses override any of:
+
+    * :meth:`on_resize` - rebuild size-dependent state (``width``/``height``
+      are already set). Also called by the default :meth:`on_reset`.
+    * :meth:`on_reset` - restart the animation from scratch.
+    * :meth:`advance` - move the simulation forward ``dt`` seconds.
+    * :meth:`render` - draw into the frame. Spaces are transparent, so draw
+      only what is visible.
+
+    The app calls the public :meth:`resize`, :meth:`reset`, :meth:`update`
+    and :meth:`draw`, which guarantee ``advance`` and ``render`` are never
+    called before the first resize or with a non-positive ``dt``.
+    """
+
+    #: Restrict output to 7-bit ASCII. Set by the registry after construction.
+    ascii_only = False
+    #: May trade resolution for frame rate. Set by the interactive app; effects
+    #: that have nothing to trade ignore it.
+    adaptive = False
+
+    def __init__(self, rng: random.Random, unicode: bool = False) -> None:
+        self.rng = rng
+        self.unicode = unicode  # allow katakana and other non-ASCII glyphs
+        self.width = 0
+        self.height = 0
+        self._palette_theme: Theme | None = None
+        self._palette: list[RGB] = []
+
+    def resize(self, width: int, height: int) -> None:
+        self.width, self.height = max(1, int(width)), max(1, int(height))
+        self.on_resize()
+
+    def reset(self) -> None:
+        self.on_reset()
+
+    def update(self, dt: float) -> None:
+        if dt > 0.0 and self.width:
+            self.advance(dt)
+
+    def draw(self, frame: Frame, theme: Theme) -> None:
+        if self.width:
+            self.render(frame, theme)
+
+    def on_resize(self) -> None:
+        pass
+
+    def on_reset(self) -> None:
+        if self.width:
+            self.on_resize()
+
+    def advance(self, dt: float) -> None:
+        pass
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        raise NotImplementedError
+
+    def palette(self, theme: Theme) -> list[RGB]:
+        """``PALETTE_STEPS`` colours sampled along the theme ramp (cached)."""
+        if theme is not self._palette_theme:
+            last = PALETTE_STEPS - 1
+            self._palette = [theme.ramp(i / last) for i in range(PALETTE_STEPS)]
+            self._palette_theme = theme
+        return self._palette
+
+    def color_at(self, theme: Theme, value: float) -> RGB:
+        """Theme colour for a brightness in 0..1."""
+        palette = self.palette(theme)
+        if value <= 0.0:
+            return palette[0]
+        if value >= 1.0:
+            return palette[-1]
+        return palette[int(value * (PALETTE_STEPS - 1) + 0.5)]