# katui

> katui is a terminal UI library for Rust, Python, Node.js, Go and C that draws real pixels through the kitty graphics protocol, with sixel or quarter-block characters on other terminals.

- Pick the entry point by what you build: `katui::app::run` with a `UiApp` (a `view` and an `update`) for pixel UI apps, `katui::game::play` with a `Game` (`step` and `render`) for games, `katui::content::html` and `markdown_view` for documents inside a view, `katui::ratatui` to add images to a ratatui app, and `katui::rt::media::VideoStream` for video.
- Rust features: `app` (runner and widgets), `game`, `html`, `ratatui`. Python: `pip install katui`. Node.js: `npm install @mattfillipe/katui`. Go: `go get github.com/h4ks-com/katui/bindings/go`.
- Every binding has a headless `Screen` and a game `frame` for tests without a terminal.
- `KATUI_GRAPHICS=kitty|sixel|blocks` overrides the detected backend. Inside tmux, set `allow-passthrough on` and the true color terminal feature, as the README shows.
- An agent skill for katui lives in [skills/katui](https://github.com/h4ks-com/katui/blob/main/skills/katui/SKILL.md).

## Guides

- [Getting started](https://github.com/h4ks-com/katui/blob/main/docs/getting-started.md): install katui, run a first app, and learn what happens when it starts.
- [Pixel UI apps](https://github.com/h4ks-com/katui/blob/main/docs/ui-apps.md): views, messages, widgets, layout, keyboard input and background work.
- [Games](https://github.com/h4ks-com/katui/blob/main/docs/games.md): a fixed-step game loop, drawing with light, and held keys.
- [Video](https://github.com/h4ks-com/katui/blob/main/docs/video.md): play a file or a stream inside your app.
- [HTML and markdown](https://github.com/h4ks-com/katui/blob/main/docs/html-and-markdown.md): render documents as part of your view.
- [Images in ratatui apps](https://github.com/h4ks-com/katui/blob/main/docs/ratatui.md): keep your ratatui widgets and add pixels next to them.
- [Python](https://github.com/h4ks-com/katui/blob/main/docs/python.md): the same apps, documents and games from Python.
- [C](https://github.com/h4ks-com/katui/blob/main/docs/c.md): the same apps, documents and games from C.
- [Go](https://github.com/h4ks-com/katui/blob/main/docs/go.md): the same apps, documents and games from Go.
- [Node.js](https://github.com/h4ks-com/katui/blob/main/docs/node.md): the same apps, documents and games from JavaScript and TypeScript.
- [How katui works](https://github.com/h4ks-com/katui/blob/main/docs/architecture.md): the layers, and what happens between your `view` and the terminal.
- [Building, testing and publishing](https://github.com/h4ks-com/katui/blob/main/docs/publishing.md): the checks that keep the Rust, Python, C, Go and Node packages in step, and how a release ships.

## API reference

- [`katui`](https://h4ks-com.github.io/katui/katui/): Re-exports everything below under one name, with features
- [`katui-app`](https://h4ks-com.github.io/katui/katui_app/): `run(app)`: the runner for pixel UI apps
- [`katui-game`](https://h4ks-com.github.io/katui/katui_game/): `play(game)`: the fixed-step game runner and the light canvas
- [`katui-ratatui`](https://h4ks-com.github.io/katui/katui_ratatui/): The ratatui backend and image helpers
- [`katui-content`](https://h4ks-com.github.io/katui/katui_content/): Markdown, and the HTML and CSS subset
- [`katui-widgets`](https://h4ks-com.github.io/katui/katui_widgets/): The theme, widgets and their state
- [`katui-ui`](https://h4ks-com.github.io/katui/katui_ui/): Element trees, flexbox layout and hit testing
- [`katui-layout`](https://h4ks-com.github.io/katui/katui_layout/): Splitting cell rectangles by constraints
- [`katui-draw`](https://h4ks-com.github.io/katui/katui_draw/): Text shaping, shapes and pixel blending
- [`katui-rt`](https://h4ks-com.github.io/katui/katui_rt/): The terminal: raw mode, the event loop, probing, video streams
- [`katui-present`](https://h4ks-com.github.io/katui/katui_present/): Presenters that turn scenes into terminal bytes
- [`katui-scene`](https://h4ks-com.github.io/katui/katui_scene/): Cells, pixel surfaces, placements and what changed
- [`katui-proto`](https://h4ks-com.github.io/katui/katui_proto/): The kitty, sixel and input protocols, and capability parsing

## Bindings

- [Python](https://github.com/h4ks-com/katui/blob/main/bindings/python/README.md): the `katui` package on PyPI
- [Node.js](https://github.com/h4ks-com/katui/blob/main/bindings/node/README.md): the `@mattfillipe/katui` package on npm
- [Go](https://github.com/h4ks-com/katui/blob/main/bindings/go/README.md): the Go module over the C library
- [C](https://github.com/h4ks-com/katui/blob/main/bindings/c/README.md): the C library behind `katui.h`

## Optional

- [Full text](https://h4ks-com.github.io/katui/llms-full.txt): the README, every guide and the API
- [README](https://github.com/h4ks-com/katui/blob/main/README.md): install, a first program, terminals, demos
- [Rust app examples](https://github.com/h4ks-com/katui/blob/main/crates/katui-app/examples): the to-do list, the widget tour
- [Rust game examples](https://github.com/h4ks-com/katui/blob/main/crates/katui-game/examples): the games and the video player
- [Python examples](https://github.com/h4ks-com/katui/blob/main/bindings/python/examples): the same apps and a game in Python
- [Node.js examples](https://github.com/h4ks-com/katui/blob/main/bindings/node/examples): the same apps and a game in TypeScript
- [Go examples](https://github.com/h4ks-com/katui/blob/main/bindings/go/examples): a counter, a to-do list, a help screen, a game
- [C examples](https://github.com/h4ks-com/katui/blob/main/bindings/c/examples): a counter, a to-do list and a game