Metadata-Version: 2.5
Name: cligui-engine
Version: 1.0.0
Summary: Modern high-performance terminal graphics, 2D canvas and TUI engine in pure Python
Project-URL: Homepage, https://github.com/adstont-cmd/cligui
Project-URL: Repository, https://github.com/adstont-cmd/cligui
Project-URL: Issues, https://github.com/adstont-cmd/cligui/issues
Author: The CLIguiEngine contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ansi,braille,canvas,charts,cli,graphics,half-block,kitty,mouse,sixel,terminal,truecolor,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: pillow>=10.0.0; extra == 'all'
Provides-Extra: ttf
Requires-Dist: pillow>=10.0.0; extra == 'ttf'
Description-Content-Type: text/markdown

# cligui

🇷🇺 [Читать документацию на русском языке](https://github.com/adstont-cmd/cligui/blob/main/README.ru.md)

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/adstont-cmd/cligui/blob/main/LICENSE)
[![60 FPS](https://img.shields.io/badge/render-60%20FPS-58A6FF)](#performance)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](#installation)

**Modern high-performance terminal graphics, 2D canvas and TUI engine in pure Python.**

`cligui` turns any modern terminal into a pixel display: draw anti-aliased vector shapes,
gradients, TTF text and live charts on an in-memory RGBA canvas, then show it as
subpixel Braille, TrueColor half-blocks, quadrants — or as **real HD pixels** through the
Kitty and Sixel graphics protocols. On top sits a component TUI (flex layout, panels,
inputs, mouse, focus) driven by a diffing renderer that sends only the cells that changed,
inside synchronized-output frames: smooth 60 FPS, no flicker.

The core is **standard library only** — `pip install cligui-engine` pulls in nothing else.
Pillow is an optional extra for TTF/OTF fonts.

## Features

| Feature | What you get |
|---|---|
| **Subpixel Braille** | 2×4 dots per cell (`U+2800…`) — 8× the resolution of plain text, ideal for line charts |
| **TrueColor Half-block** | `▀`/`▄` with 24-bit fg/bg — two square pixels per cell, full color everywhere |
| **Quadrant & pixel-art** | 2×2 block mosaics with best two-color split; 1 pixel = 2 cells for retro art |
| **Kitty HD / Sixel** | True monitor-resolution pixels (Kitty graphics protocol, DEC Sixel) with strip diffing, auto-detected, graceful fallback |
| **60 FPS DiffRenderer** | Cell-level diff, minimal cursor moves, cached SGR, DEC 2026 synchronized output |
| **Vector primitives** | Bresenham & Xiaolin Wu lines, thick strokes with round caps, (rounded) rects, circles, ellipses, polygons, stars — with anti-aliasing and Porter-Duff alpha |
| **Gradients** | Linear (any angle) and radial gradients as "paints" for any shape or text |
| **TTF fonts** | Any system or file font via Pillow (lazy import), plus a built-in 5×7 bitmap font |
| **Charts** | Line (monotone/Catmull-Rom smoothing, fading fills), bar (grouped/stacked), sparklines, rolling real-time buffers, nice 1-2-5 ticks |
| **2D camera** | Infinite canvas: pan, cursor-pivot zoom, smooth zoom, viewport culling |
| **TUI framework** | Flex `VStack`/`HStack`, `Panel`, `Label`, `Button`, `Tabs`, `PromptInput`, `StatusBar`, `CanvasWidget`, `ChartWidget`, themes |
| **SGR 1006 mouse** | Press/drag/release/wheel/hover with modifiers, bracketed paste, full keyboard |
| **Safe by default** | Untrusted text cannot inject escape sequences; the terminal is always restored |

## Installation

```bash
pip install cligui-engine          # core: zero dependencies
pip install "cligui-engine[ttf]"   # + Pillow for TTF/OTF fonts
```

The distribution is named `cligui-engine`; the import name is `cligui` (`import cligui`).

Requires Python 3.10+. Works on Windows 10/11 (Windows Terminal, conhost), Linux and macOS
terminals with VT support. Best experienced in Windows Terminal, WezTerm, kitty, Ghostty,
iTerm2, foot or Alacritty.

## Quick start

```python
from cligui import Canvas2D, CellBuffer, HalfBlockRasterizer, LinearGradient, TerminalDriver

with TerminalDriver() as term:                       # raw mode + alt screen, always restored
    cols, rows = term.size()
    canvas = Canvas2D(cols, rows * 2)                 # half-block: 2 square pixels per cell
    canvas.fill_circle(cols // 2, rows, rows - 4, LinearGradient([0xFF5F6D, 0xFFC371]), aa=True)
    canvas.draw_text(2, 2, "Hello, cligui!", paint=0xFFFFFF)
    buf = CellBuffer(cols, rows)
    canvas.render(HalfBlockRasterizer(background=0x0D1117), buf)
    term.present(buf)                                 # one diffed, flicker-free frame
    term.read(timeout=5)                              # wait for a key
```

A full interactive app — a live chart with hover, a panel and a status bar:

```python
import math
from cligui import App, Label, Panel, StatusBar, VStack
from cligui.charts import LineChart, Series
from cligui.ui import ChartWidget

data = [50 + 40 * math.sin(i / 6) for i in range(120)]
chart = ChartWidget(LineChart([Series(data, "cpu", fill=True, smooth="monotone")], ymin=0, ymax=100), mode="auto")
app = App(VStack([Label(" cligui demo"), Panel(chart, title="CPU", flex=1), StatusBar("q to quit", "60 FPS")], align="stretch"))
app.bind(lambda ev: ev.key == "q" and (app.quit() or True))
app.run()
```

`mode="auto"` picks Kitty or Sixel when the terminal supports them and falls back to
character rendering otherwise (`CLIGUI_GRAPHICS=kitty|sixel|none` overrides detection).

## Rendering modes

| Mode | Pixels per cell | Colors | Best for |
|---|---|---|---|
| `braille` | 2×4 | 1 fg per cell | line charts, plots, wireframes |
| `half-block` | 1×2 | 2 per cell (24-bit) | images, fills, gradients |
| `quadrant` | 2×2 | 2 per cell | sharper shapes with color |
| `pixel-art` | ½×1 | 1 per pixel | retro sprites, logos |
| `kitty` | monitor pixels | 24-bit + alpha | HD canvases (kitty, WezTerm, Ghostty) |
| `sixel` | monitor pixels | 255-color palette | HD canvases (Windows Terminal 1.22+, foot, xterm) |

## Examples

```bash
python examples/00_bench.py               # renderer benchmark
python examples/01_shapes.py              # primitives, anti-aliasing, gradients
python examples/01_chat_dashboard.py      # dashboard: logo, live chart, input, status bar
python examples/02_fonts_demo.py          # TTF typography on the canvas
python examples/03_charts_demo.py         # line/bar charts, sparklines, real-time data
python examples/04_whiteboard.py          # infinite whiteboard: pan, zoom, pen, Kitty/Sixel
```

Every demo supports `--headless` (benchmark without a terminal); most accept `--mode`.

## Performance

Measured with `--headless` at 120×34 cells, CPython 3.14 (time per frame, including layout and drawing):

| Scene | Mode | Frame |
|---|---|---:|
| Dashboard (logo, chart, input) | Braille / Half-block | 2.8 / 2.3 ms |
| Charts demo (2 smoothed series, fills) | Half-block | 3–4.5 ms |
| Whiteboard pan, 1200×600 px canvas | Kitty | 15 ms |
| Whiteboard pan | Half-block | 1.2 ms |

Unchanged frames cost 0 bytes; a typical animated dashboard frame is 3–8 KiB.
Sixel is heavier (palette quantization in Python): ~16–40 FPS while panning a full HD canvas.

## Security

`cligui` is designed to display untrusted data (logs, network output) safely:

* **No escape injection.** `CellBuffer`, `Canvas2D.draw_text`, window titles and — as a last
  line of defense — the `DiffRenderer` strip C0/DEL/C1 control characters, so a string such as
  `"\x1b]52;c;…\x07"` cannot rewrite your clipboard, clear the screen or retitle the window.
  `cligui.core.strip_controls()` is public.
* **Bounded input.** Escape sequences, terminal replies and bracketed paste are length-limited.
* **Safe font loading.** Explicit font paths must be font files, cannot escape the working
  directory (or a `root=` you pass) via `..`, and are size-limited; glyph masks are capped
  to prevent memory blow-ups from malformed fonts.
* **Terminal always restored** on normal exit, exceptions, Ctrl+C, SIGTERM/SIGHUP or a failed
  start-up: cursor shown, mouse tracking off, alternate screen left, console modes, code page
  and timer resolution restored on Windows, `termios` on POSIX.

## Development

```bash
python -m unittest discover tests     # 270+ tests, < 1 s, no terminal needed
python scripts/verify_clean.py        # pre-release privacy check (exit code 0 = clean)
python -m build && twine check dist/*
```

Architecture decisions (ADR-1 … ADR-15) are documented in [ARCHITECTURE.md](https://github.com/adstont-cmd/cligui/blob/main/ARCHITECTURE.md)
(in Russian).

## License

[MIT](https://github.com/adstont-cmd/cligui/blob/main/LICENSE)
