tappty 0.1.0__tar.gz

tappty-0.1.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 2026-06-17 — And so it begins...
+
+- **13:10** — Started: the fixed-size VT52 `Terminal` grid
+- **14:29** — the first pygame renderer
+- **22:51** — First end-to-end run of observe/control core
+
+## 2026-06-18 — standalone
+
+- **23:30** — Extracted to a standalone package
+- **23:35** — round-tripped a real subprocess through the pty into the grid.
+
+## 2026-06-19 — renderers, color, bus, packaging
+
+- **10:54** — Runtime hardening
+- **11:06** — Consolidated the byte-source reader loop into `Source._pump`.
+- **12:08** — The detailed docs: `DESIGN.md`, `REFERENCE.md`, the `tapterm` guide.
+- **13:14** — Windows: the `win` extra bundles `windows-curses` (curses CUI on Windows).
+- **13:32** — `arcade_ui` renderer — the pyglet/OpenGL twin of `pygame_ui`.
+- **14:23** — SGR **color** in the GUI, then in the curses CUI too.
+- **14:55** — Raw-mode full-screen TUI input (`--raw`), so vim/htop work.
+- **15:30** — `web_ui` renderer — the terminal in a browser over a websocket.
+- **20:33** — Bold/italic/underline as real attributes; then strikethrough and blink.
+- **20:46** — Packaging: `MANIFEST.in` + a validated (non-publishing) build.
+- **21:10** — SGR color over the bus (styled snapshot + colored compositor panels).
+- **21:37** — Wide CJK and single-code-point emoji at their true two columns.
+- **22:44** — A GitHub Pages docs site: `docs/` sources, a `gh-pages/` builder, Actions deploy.
+- **23:05** — Published a `tapterm` alias distribution alongside `tappty`.
+- **23:50** — Docs-site nav and hero polish.
+
+## 2026-06-20 — recording formats, video, demos, the terminal
+
+- **10:52** — A **gallery** of runnable demos (screenshots + source).
+- **11:15** — `.ttyrec` read/write, and recording any live session to `.cast`/`.ttyrec`
+- **11:47** — Host & record real ANSI programs; bundle `nyancat`/`cbonsai` recordings
+- **12:01** — Play and export ANSI/BBS art `.ans` (CP437 + SAUCE) and animated `.3a`
+- **12:27** — **Render to video** — any recording to mp4/webm/gif via ffmpeg
+- **12:41** — render of a live command (record + render in one step).
+- **13:14** — Split `demos/` (runnable showpieces) from `examples/` (API coding examples).
+- **13:50** — Gallery goes visual: an embedded movie, a looping GIF, a digital-rain mp4.
+- **14:06** — `tapterm` is a **regular terminal** by default 
+- **14:12** — `tapterm` takes xterm like arguments where useful
+- **14:26** — Observe-and-control demos: an autopilot driving live `vim` (open loop)
+- **14:35** — reactive bot demo that reads the stream and decides what to type (closed loop).
+- **14:55** — A web-renderer demo with a real-browser (Playwright) screenshot.
+- **15:42** — Named the GUI extras by graphics layer — `sdl` (pygame-ce) and `gl` (arcade).
+- **16:40** — Docs-site polish
+- **17:28** — Runtime hardening
+- **17:33** — Fixed race conditions
+- **17:40** — pypy packaging prep
+- **18:11** — Bus/control hardening
+- **18:16** — Improve replay/render robustness
+- **18:19** — The CUI honors `--exit-when-done` / `-hold`
+- **18:28** — Applied `ruff format`
+- **18:29** — Across the tree; CI installs the `web` extra so the WebSocket/CSWSH tests run.

tappty-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas J. Kisseberth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tappty-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# Files to include in the source distribution (sdist) beyond the defaults
+# (pyproject.toml, README.md, and the LICENSE are included automatically).
+include LICENSE CHANGELOG.md
+recursive-include docs *.md
+recursive-include docs/media *.png *.gif *.mp4
+recursive-include demos *.py *.md *.cast
+recursive-include examples *.py *.md
+recursive-include tests *.py

tappty-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: tappty
+Version: 0.1.0
+Summary: Host a program on a pseudo-terminal, then observe/control/render it (CUI or GUI)
+Author: Nicholas J. Kisseberth
+License: MIT
+Project-URL: Homepage, https://github.com/nyxcraft/tappty
+Project-URL: Documentation, https://nyxcraft.github.io/tappty/
+Project-URL: Source, https://github.com/nyxcraft/tappty
+Project-URL: Changelog, https://github.com/nyxcraft/tappty/blob/main/CHANGELOG.md
+Keywords: terminal,pty,curses,pygame,tui,vt52,emulator,instrumentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Environment :: X11 Applications
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sdl
+Requires-Dist: pygame-ce; extra == "sdl"
+Provides-Extra: gl
+Requires-Dist: arcade; extra == "gl"
+Provides-Extra: web
+Requires-Dist: websockets; extra == "web"
+Provides-Extra: video
+Requires-Dist: imageio-ffmpeg; extra == "video"
+Provides-Extra: ansi
+Requires-Dist: pyte; extra == "ansi"
+Provides-Extra: win
+Requires-Dist: pywinpty; platform_system == "Windows" and extra == "win"
+Requires-Dist: windows-curses; platform_system == "Windows" and extra == "win"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# tappty
+
+**Host a program on a pseudo-terminal, then observe, control, and render it** — in a
+plain terminal (curses, CUI) or a green-phosphor window (GUI).
+
+Software Architecture, Design & Engineering by Nicholas J. Kisseberth.  
+Code Synthesized via Anthropic Claude Code / Opus 4.8.  
+Code Review by OpenAI Codex / ChatGPT 5.5.
+
+`tappty` is a small instrumented-terminal toolkit. A program's bytes (a subprocess on a
+PTY, or any in-process runner) flow into a fixed-size character `Terminal`; a `Session`
+fans that output out to any number of observers and routes input back. A renderer is just
+one more observer/controller — which is what lets a human *and* an automated client watch
+and drive the very same session. Several sessions tile into one window via the compositor.
+
+## Install
+
+```sh
+pip install tappty          # core (CUI works out of the box)
+pip install 'tappty[sdl]'   # add the SDL/GUI window (installs pygame-ce)
+pip install 'tappty[gl]' # add the OpenGL window (arcade; an alternative GUI backend)
+pip install 'tappty[web]'    # add the browser renderer for --web (websockets)
+pip install 'tappty[video]'  # render recordings to mp4/gif via --render (bundles ffmpeg)
+pip install 'tappty[ansi]'  # add the full-ANSI/VT100+ backend (pyte) for --ansi
+pip install 'tappty[win]'   # Windows: add the ConPTY source (pywinpty)
+# from a checkout:
+pip install -e '.[sdl,ansi,dev]'
+```
+
+`pip install tapterm` works too — it's a convenience alias that just pulls in `tappty` (which
+provides the `tapterm` command). The library, the extras, and the docs all live under `tappty`.
+
+## The `tapterm` program
+
+```sh
+tapterm                    # a regular terminal: your $SHELL, full-ANSI + raw keys
+tapterm -e vim file        # run a command instead of the shell, xterm-style (or: -- vim file)
+tapterm -geometry 100x30   # xterm-style size; -T/-title sets the title, -cd DIR the working dir
+tapterm --cui -- bash      # force the curses character UI (takes over this terminal)
+tapterm --gui -- bash      # force the SDL green-phosphor window (the 'sdl' extra)
+tapterm --arcade -- bash   # same, on the arcade/OpenGL stack (the 'gl' extra)
+tapterm --web -- bash      # serve it in a browser (the 'web' extra); open http://127.0.0.1:8023/
+tapterm --headless -- ls   # run to completion, print the final screen (scripting/CI)
+tapterm --cooked -- bash   # line-oriented instrument mode (local echo on the VT52 grid)
+tapterm --play rec.cast    # replay a .cast / .ttyrec / .ans / .3a recording (--speed N, --loop)
+tapterm --record out.cast -- bash       # record a session as you use it
+tapterm --play rec.cast --render rec.mp4 # render a recording to a video (mp4/webm/gif)
+tapterm --render rain.mp4 --seconds 5 -- cmatrix  # render a live program straight to video
+tapterm --no-pty -- ls     # host over plain pipes, no pty (cross-platform, incl. Windows)
+```
+
+An interactive session behaves like a **real terminal** — full-ANSI rendering (the `ansi` extra,
+pyte) plus raw keys, so colors, line-editing, arrows, and full-screen apps work, and the window
+closes when the program exits, like xterm. Pass `--cooked` for the line-oriented instrument
+default instead (local echo on the dependency-free VT52 grid) — what the observe taps and the bus
+`CMD` capture expect. xterm-style flags are accepted where they fit: `-e`, `-T`/`-title`,
+`-geometry`, `-cd`, `-hold`.
+
+`--cui` works anywhere; `--gui` needs the `sdl` extra. With no mode flag, `tapterm` picks GUI when
+the `sdl` extra is installed *and a display is available* (else CUI) — so it won't try to open a
+window over SSH/cron. On Windows the pty path uses ConPTY (the `win` extra), which emits VT100+.
+
+Every flag, the modes, recordings, snapshots, recipes, and troubleshooting are in the
+[tapterm user's guide](docs/TAPTERM.md).
+
+## Library
+
+```python
+from tappty import Session, Terminal, PtySource, curses_ui
+
+sess = Session(Terminal(cols=80, rows=24))
+sess.source = PtySource(["bash"])
+sess.claim_control("local", "human")
+curses_ui.run(sess, None, title="bash")
+```
+
+Full API — classes, signatures, the observe/control contract, and worked examples — is in
+[docs/REFERENCE.md](docs/REFERENCE.md).
+
+The pieces:
+
+- **`Terminal` / `PyteTerminal`** — the screen model. `Terminal` is a fixed-size character
+  grid (VT52 spirit: wrap/scroll, the common control chars, a handful of VT52 escapes), with
+  scrollback and no deps. `PyteTerminal` is a drop-in full-ANSI/VT100+ backend (wraps `pyte`,
+  the `ansi` extra) for programs that speak modern ANSI; same read interface (plus a `cells()`
+  view of per-cell SGR color), so the GUI renderers show color while the rest is unchanged.
+- **`Source` / `PtySource` / `EngineSource` / `CastSource` / `TtyrecSource` / `AnsSource` /
+  `ThreeASource` / `PipeSource` / `ConPtySource`** — byte producers. `PtySource` runs an external
+  command on a real pty (POSIX); `EngineSource` wraps any in-process `runner(emit, readline)`
+  callable; `CastSource` / `TtyrecSource` replay a recorded `.cast` / `.ttyrec` session, and
+  `AnsSource` / `ThreeASource` play `.ans` / `.3a` art, through the same pipeline (original
+  timing, `speed`/`loop`; `replay_source(path)` picks by extension); `PipeSource` hosts a command
+  over plain pipes (no pty, any OS); `ConPtySource` hosts one on a Windows pseudo-console (ConPTY,
+  the `win` extra).
+- **`Session`** — hosts a Source, drives the Terminal, and exposes **observe taps**
+  (`on_stream`, `on_frame`, `on_event`) and **control** (`send_input`, `feed_key`) plus a
+  talking-stick arbitration so exactly one controller types at a time.
+- **`Recorder` / `render_video`** — `Recorder` writes the session's output stream to a `.cast`
+  or `.ttyrec` recording as it runs (the inverse of the replay sources; `tapterm --record`);
+  `render_video` encodes a recording to a real video file (mp4/webm/gif) via ffmpeg, with
+  size/zoom/font/speed and an area-of-interest crop (`tapterm --play X --render out.mp4`).
+- **`BusServer` / `BusClient`** — the same observe/control contract over a Unix-domain
+  socket *or* TCP (a `(host, port)` tuple — works on Windows too), so an out-of-process
+  client (a logger, an automated driver, a remote renderer) can attach to a session. It's a
+  terminal control plane — **trusted-local**: the Unix socket is owner-only, TCP is
+  loopback-only unless `allow_remote=True`, and a `token=` adds an optional shared-secret
+  gate. Not a substitute for a tunnel on an untrusted network (no TLS).
+- **`curses_ui` / `pygame_ui` / `arcade_ui` / `web_ui`** — renderers; each exposes
+  `run(session, runner, title=…)`. `pygame_ui` and `arcade_ui` are two backends for the same
+  green-phosphor window (SDL, or arcade/OpenGL); `web_ui` serves it in a browser over a
+  WebSocket (the `web` extra).
+- **`compositor`** — tile several panels (`SessionBacking` for in-process, `BusBacking`
+  for remote) in one GUI window, with per-tile pan/zoom and focus.
+
+## Demos & examples
+
+`demos/` holds runnable showpieces — the SGR color chart, the green digital rain, the compositor
+"mission control", `drive_vim` (a program driving a live `vim` over the control tap), and
+`web_demo` (the browser renderer). `examples/` holds short, commented API examples — the observe
+taps, writing a custom `Source`, driving a session over the bus, and `watch_and_drive` (a bot that
+reads the output stream and types its decisions back). The [gallery](docs/GALLERY.md) has
+screenshots and a clip of each.
+
+## Platform
+
+The core (Terminal/Session/taps/talking-stick), `EngineSource`, `CastSource`, `PipeSource`,
+the renderers, and the TCP bus are cross-platform. `PtySource` uses `pty`/`termios`
+(POSIX-only); on Windows, host via `ConPtySource` (the `win` extra, ConPTY — paired with
+`--ansi`) or `PipeSource` (`--no-pty`), and use the TCP bus rather than a Unix socket. The
+Windows ConPTY path is implemented but not yet exercised on real Windows — finishing it is
+open work (see [docs/DESIGN.md](docs/DESIGN.md) §11). The GUI needs a display; the CUI needs a
+terminal (and, on Windows, the `win` extra's `windows-curses`); `--headless` needs neither.
+
+## Documentation
+
+The rendered docs site is at **[nyxcraft.github.io/tappty](https://nyxcraft.github.io/tappty/)**
+(built from `docs/` by `gh-pages/build_site.py` and published via GitHub Actions). The sources:
+
+- **[docs/TAPTERM.md](docs/TAPTERM.md)** — the `tapterm` command in depth: every flag,
+  the CUI / GUI / headless modes, the terminal model, recordings, snapshots, recipes, and
+  troubleshooting. For *using* tapterm.
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — the programming/API reference: every public
+  class and method with signatures, the observe/control contracts (snapshot dict, events,
+  roles), and worked examples. For *building on* the library.
+- **[docs/DESIGN.md](docs/DESIGN.md)** — the architecture: the Source → Terminal → Session →
+  renderer/bus pipeline, the concurrency and security/trust models, and the design rationale.
+  For *modifying* tappty.
+- **[CHANGELOG.md](CHANGELOG.md)** — dated history, newest first: when tappty started, when
+  it first worked, and what's changed since. The remaining open work (publish to PyPI; verify
+  Windows) is in [docs/DESIGN.md](docs/DESIGN.md) §11.
+
+## Tests & tooling
+
+```sh
+pip install -e '.[dev]'            # quick: core suite (pyte + GUI tests skip)
+pytest
+
+pip install -e '.[dev,ansi,sdl]'   # full: also the ANSI backend + headless GUI smoke
+pytest
+
+ruff check src tests               # lint (E,F,W,I,B,UP); must be clean
+ruff format src tests              # format (line-length 99, black-style)
+
+# no install needed, straight from a checkout:
+PYTHONPATH=src python3 -m tappty.cli --headless -- echo hello
+```
+
+Without the `ansi`/`sdl` extras, `pytest` skips the pyte and GUI tests (so it reports
+fewer passes plus a couple of skips); install `.[dev,ansi,sdl]` to run the whole suite. CI
+runs ruff + the full matrix on Python 3.9–3.13.
+
+## License
+
+MIT © Nicholas J. Kisseberth. See [LICENSE](LICENSE).

tappty-0.1.0/README.md

@@ -0,0 +1,174 @@
+# tappty
+
+**Host a program on a pseudo-terminal, then observe, control, and render it** — in a
+plain terminal (curses, CUI) or a green-phosphor window (GUI).
+
+Software Architecture, Design & Engineering by Nicholas J. Kisseberth.  
+Code Synthesized via Anthropic Claude Code / Opus 4.8.  
+Code Review by OpenAI Codex / ChatGPT 5.5.
+
+`tappty` is a small instrumented-terminal toolkit. A program's bytes (a subprocess on a
+PTY, or any in-process runner) flow into a fixed-size character `Terminal`; a `Session`
+fans that output out to any number of observers and routes input back. A renderer is just
+one more observer/controller — which is what lets a human *and* an automated client watch
+and drive the very same session. Several sessions tile into one window via the compositor.
+
+## Install
+
+```sh
+pip install tappty          # core (CUI works out of the box)
+pip install 'tappty[sdl]'   # add the SDL/GUI window (installs pygame-ce)
+pip install 'tappty[gl]' # add the OpenGL window (arcade; an alternative GUI backend)
+pip install 'tappty[web]'    # add the browser renderer for --web (websockets)
+pip install 'tappty[video]'  # render recordings to mp4/gif via --render (bundles ffmpeg)
+pip install 'tappty[ansi]'  # add the full-ANSI/VT100+ backend (pyte) for --ansi
+pip install 'tappty[win]'   # Windows: add the ConPTY source (pywinpty)
+# from a checkout:
+pip install -e '.[sdl,ansi,dev]'
+```
+
+`pip install tapterm` works too — it's a convenience alias that just pulls in `tappty` (which
+provides the `tapterm` command). The library, the extras, and the docs all live under `tappty`.
+
+## The `tapterm` program
+
+```sh
+tapterm                    # a regular terminal: your $SHELL, full-ANSI + raw keys
+tapterm -e vim file        # run a command instead of the shell, xterm-style (or: -- vim file)
+tapterm -geometry 100x30   # xterm-style size; -T/-title sets the title, -cd DIR the working dir
+tapterm --cui -- bash      # force the curses character UI (takes over this terminal)
+tapterm --gui -- bash      # force the SDL green-phosphor window (the 'sdl' extra)
+tapterm --arcade -- bash   # same, on the arcade/OpenGL stack (the 'gl' extra)
+tapterm --web -- bash      # serve it in a browser (the 'web' extra); open http://127.0.0.1:8023/
+tapterm --headless -- ls   # run to completion, print the final screen (scripting/CI)
+tapterm --cooked -- bash   # line-oriented instrument mode (local echo on the VT52 grid)
+tapterm --play rec.cast    # replay a .cast / .ttyrec / .ans / .3a recording (--speed N, --loop)
+tapterm --record out.cast -- bash       # record a session as you use it
+tapterm --play rec.cast --render rec.mp4 # render a recording to a video (mp4/webm/gif)
+tapterm --render rain.mp4 --seconds 5 -- cmatrix  # render a live program straight to video
+tapterm --no-pty -- ls     # host over plain pipes, no pty (cross-platform, incl. Windows)
+```
+
+An interactive session behaves like a **real terminal** — full-ANSI rendering (the `ansi` extra,
+pyte) plus raw keys, so colors, line-editing, arrows, and full-screen apps work, and the window
+closes when the program exits, like xterm. Pass `--cooked` for the line-oriented instrument
+default instead (local echo on the dependency-free VT52 grid) — what the observe taps and the bus
+`CMD` capture expect. xterm-style flags are accepted where they fit: `-e`, `-T`/`-title`,
+`-geometry`, `-cd`, `-hold`.
+
+`--cui` works anywhere; `--gui` needs the `sdl` extra. With no mode flag, `tapterm` picks GUI when
+the `sdl` extra is installed *and a display is available* (else CUI) — so it won't try to open a
+window over SSH/cron. On Windows the pty path uses ConPTY (the `win` extra), which emits VT100+.
+
+Every flag, the modes, recordings, snapshots, recipes, and troubleshooting are in the
+[tapterm user's guide](docs/TAPTERM.md).
+
+## Library
+
+```python
+from tappty import Session, Terminal, PtySource, curses_ui
+
+sess = Session(Terminal(cols=80, rows=24))
+sess.source = PtySource(["bash"])
+sess.claim_control("local", "human")
+curses_ui.run(sess, None, title="bash")
+```
+
+Full API — classes, signatures, the observe/control contract, and worked examples — is in
+[docs/REFERENCE.md](docs/REFERENCE.md).
+
+The pieces:
+
+- **`Terminal` / `PyteTerminal`** — the screen model. `Terminal` is a fixed-size character
+  grid (VT52 spirit: wrap/scroll, the common control chars, a handful of VT52 escapes), with
+  scrollback and no deps. `PyteTerminal` is a drop-in full-ANSI/VT100+ backend (wraps `pyte`,
+  the `ansi` extra) for programs that speak modern ANSI; same read interface (plus a `cells()`
+  view of per-cell SGR color), so the GUI renderers show color while the rest is unchanged.
+- **`Source` / `PtySource` / `EngineSource` / `CastSource` / `TtyrecSource` / `AnsSource` /
+  `ThreeASource` / `PipeSource` / `ConPtySource`** — byte producers. `PtySource` runs an external
+  command on a real pty (POSIX); `EngineSource` wraps any in-process `runner(emit, readline)`
+  callable; `CastSource` / `TtyrecSource` replay a recorded `.cast` / `.ttyrec` session, and
+  `AnsSource` / `ThreeASource` play `.ans` / `.3a` art, through the same pipeline (original
+  timing, `speed`/`loop`; `replay_source(path)` picks by extension); `PipeSource` hosts a command
+  over plain pipes (no pty, any OS); `ConPtySource` hosts one on a Windows pseudo-console (ConPTY,
+  the `win` extra).
+- **`Session`** — hosts a Source, drives the Terminal, and exposes **observe taps**
+  (`on_stream`, `on_frame`, `on_event`) and **control** (`send_input`, `feed_key`) plus a
+  talking-stick arbitration so exactly one controller types at a time.
+- **`Recorder` / `render_video`** — `Recorder` writes the session's output stream to a `.cast`
+  or `.ttyrec` recording as it runs (the inverse of the replay sources; `tapterm --record`);
+  `render_video` encodes a recording to a real video file (mp4/webm/gif) via ffmpeg, with
+  size/zoom/font/speed and an area-of-interest crop (`tapterm --play X --render out.mp4`).
+- **`BusServer` / `BusClient`** — the same observe/control contract over a Unix-domain
+  socket *or* TCP (a `(host, port)` tuple — works on Windows too), so an out-of-process
+  client (a logger, an automated driver, a remote renderer) can attach to a session. It's a
+  terminal control plane — **trusted-local**: the Unix socket is owner-only, TCP is
+  loopback-only unless `allow_remote=True`, and a `token=` adds an optional shared-secret
+  gate. Not a substitute for a tunnel on an untrusted network (no TLS).
+- **`curses_ui` / `pygame_ui` / `arcade_ui` / `web_ui`** — renderers; each exposes
+  `run(session, runner, title=…)`. `pygame_ui` and `arcade_ui` are two backends for the same
+  green-phosphor window (SDL, or arcade/OpenGL); `web_ui` serves it in a browser over a
+  WebSocket (the `web` extra).
+- **`compositor`** — tile several panels (`SessionBacking` for in-process, `BusBacking`
+  for remote) in one GUI window, with per-tile pan/zoom and focus.
+
+## Demos & examples
+
+`demos/` holds runnable showpieces — the SGR color chart, the green digital rain, the compositor
+"mission control", `drive_vim` (a program driving a live `vim` over the control tap), and
+`web_demo` (the browser renderer). `examples/` holds short, commented API examples — the observe
+taps, writing a custom `Source`, driving a session over the bus, and `watch_and_drive` (a bot that
+reads the output stream and types its decisions back). The [gallery](docs/GALLERY.md) has
+screenshots and a clip of each.
+
+## Platform
+
+The core (Terminal/Session/taps/talking-stick), `EngineSource`, `CastSource`, `PipeSource`,
+the renderers, and the TCP bus are cross-platform. `PtySource` uses `pty`/`termios`
+(POSIX-only); on Windows, host via `ConPtySource` (the `win` extra, ConPTY — paired with
+`--ansi`) or `PipeSource` (`--no-pty`), and use the TCP bus rather than a Unix socket. The
+Windows ConPTY path is implemented but not yet exercised on real Windows — finishing it is
+open work (see [docs/DESIGN.md](docs/DESIGN.md) §11). The GUI needs a display; the CUI needs a
+terminal (and, on Windows, the `win` extra's `windows-curses`); `--headless` needs neither.
+
+## Documentation
+
+The rendered docs site is at **[nyxcraft.github.io/tappty](https://nyxcraft.github.io/tappty/)**
+(built from `docs/` by `gh-pages/build_site.py` and published via GitHub Actions). The sources:
+
+- **[docs/TAPTERM.md](docs/TAPTERM.md)** — the `tapterm` command in depth: every flag,
+  the CUI / GUI / headless modes, the terminal model, recordings, snapshots, recipes, and
+  troubleshooting. For *using* tapterm.
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — the programming/API reference: every public
+  class and method with signatures, the observe/control contracts (snapshot dict, events,
+  roles), and worked examples. For *building on* the library.
+- **[docs/DESIGN.md](docs/DESIGN.md)** — the architecture: the Source → Terminal → Session →
+  renderer/bus pipeline, the concurrency and security/trust models, and the design rationale.
+  For *modifying* tappty.
+- **[CHANGELOG.md](CHANGELOG.md)** — dated history, newest first: when tappty started, when
+  it first worked, and what's changed since. The remaining open work (publish to PyPI; verify
+  Windows) is in [docs/DESIGN.md](docs/DESIGN.md) §11.
+
+## Tests & tooling
+
+```sh
+pip install -e '.[dev]'            # quick: core suite (pyte + GUI tests skip)
+pytest
+
+pip install -e '.[dev,ansi,sdl]'   # full: also the ANSI backend + headless GUI smoke
+pytest
+
+ruff check src tests               # lint (E,F,W,I,B,UP); must be clean
+ruff format src tests              # format (line-length 99, black-style)
+
+# no install needed, straight from a checkout:
+PYTHONPATH=src python3 -m tappty.cli --headless -- echo hello
+```
+
+Without the `ansi`/`sdl` extras, `pytest` skips the pyte and GUI tests (so it reports
+fewer passes plus a couple of skips); install `.[dev,ansi,sdl]` to run the whole suite. CI
+runs ruff + the full matrix on Python 3.9–3.13.
+
+## License
+
+MIT © Nicholas J. Kisseberth. See [LICENSE](LICENSE).

tappty-0.1.0/demos/README.md

@@ -0,0 +1,41 @@
+# tappty demos
+
+Runnable showpieces — single-file apps you run to *see* a feature in action. Most are
+**in-process** (an `EngineSource`), so they need no external program; `drive_vim` hosts a real
+`vim` to show off observe-and-control. (For coding-level examples of how to build on the API,
+see [`../examples/`](../examples/).)
+
+| Demo | What it shows | Run |
+|---|---|---|
+| [color_chart.py](color_chart.py) | SGR color + attributes — bold/italic/underline/strike/blink/reverse and a 256-color strip | `python demos/color_chart.py` |
+| [matrix_rain.py](matrix_rain.py) | green-phosphor "digital rain" on the dependency-free VT52 backend | `python demos/matrix_rain.py` |
+| [mission_control.py](mission_control.py) | the compositor — four live sessions tiled in one window | `python demos/mission_control.py` |
+| [drive_vim.py](drive_vim.py) | a program driving a real terminal app — an autopilot types into live `vim` over the control tap | `python demos/drive_vim.py` |
+| [web_demo.py](web_demo.py) | the **web renderer** — the live terminal served as an HTML canvas, painted in a browser tab | `python demos/web_demo.py` |
+
+Install the matching extra first:
+
+```sh
+pip install 'tappty[sdl,ansi]'   # color_chart / mission_control / drive_vim (pygame + pyte)
+pip install 'tappty[sdl]'        # matrix_rain (pygame only; no color backend needed)
+pip install 'tappty[web,ansi]'   # web_demo (websockets + pyte); --shot also needs playwright
+```
+
+`drive_vim` also needs `vim` (or `vi`) on your PATH; `web_demo --shot` needs Playwright +
+Chromium (`pip install playwright && playwright install chromium`). To watch a closed loop that
+**reads the screen and decides what to type**, see
+[`../examples/watch_and_drive.py`](../examples/watch_and_drive.py).
+
+Each demo also takes `--snapshot PATH`: instead of opening a window it renders
+headless (SDL dummy driver) and writes a PNG. That's exactly how the
+[documentation gallery](../docs/GALLERY.md) images are produced —
+`gh-pages/screenshots.py` runs these same files with `--snapshot`.
+
+`recordings/` holds short `.cast` sessions — real ANSI programs (`nyancat`, `cbonsai`) and the
+autopilot-driven `vim` (`drive_vim.cast`) — recorded with `tapterm --record` and replayable with
+**zero dependencies**:
+
+```sh
+tapterm --play demos/recordings/nyancat.cast
+tapterm --play demos/recordings/drive_vim.cast
+```

tappty-0.1.0/demos/color_chart.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""tappty demo — an ANSI color & SGR-attribute chart.
+
+Hosts a tiny in-process program (an EngineSource) that prints a color and
+attribute chart, so you can watch tappty render SGR. No external program needed.
+
+    pip install 'tappty[sdl,ansi]'
+    python demos/color_chart.py                  # open the green-phosphor window
+    python demos/color_chart.py --snapshot c.png # render headless, write c.png instead
+"""
+
+from __future__ import annotations
+
+import argparse
+
+CSI = "\x1b["
+
+
+def runner(emit, readline):
+    """An EngineSource program: print the chart, then wait for a keypress."""
+    emit(CSI + "2J" + CSI + "H")
+    emit("  tappty — SGR color & attributes\r\n\r\n")
+
+    emit("  foreground   ")
+    for c in range(8):
+        emit(f"{CSI}3{c}m ██ {CSI}0m")
+    emit("\r\n  (bold)       ")
+    for c in range(8):
+        emit(f"{CSI}1;3{c}m ██ {CSI}0m")
+    emit("\r\n\r\n")
+
+    emit("  background   ")
+    for c in range(8):
+        emit(f"{CSI}4{c}m    {CSI}0m")
+    emit("\r\n\r\n")
+
+    emit("  attributes   ")
+    emit(f"{CSI}1mbold{CSI}0m  {CSI}3mitalic{CSI}0m  {CSI}4munderline{CSI}0m  ")
+    emit(f"{CSI}9mstrike{CSI}0m  {CSI}5mblink{CSI}0m  {CSI}7m reverse {CSI}0m\r\n\r\n")
+
+    emit("  256-color    ")
+    for i in range(16, 16 + 42):  # a slice of the 6x6x6 cube
+        emit(f"{CSI}48;5;{i}m {CSI}0m")
+    emit("\r\n\r\n")
+
+    emit("  Uncolored text stays phosphor green — color appears only\r\n")
+    emit("  where the program asks for it.\r\n\r\n  press a key to exit › ")
+    readline()
+
+
+def main():
+    ap = argparse.ArgumentParser(description="tappty color/SGR chart demo")
+    ap.add_argument("--snapshot", metavar="PNG", help="render headless and write a PNG")
+    ap.add_argument("--seconds", type=float, default=2.0, help="snapshot render-time cap")
+    args = ap.parse_args()
+
+    if args.snapshot:  # must precede the pygame import
+        import os
+
+        os.environ.setdefault("SDL_VIDEODRIVER", "dummy")
+        os.environ.setdefault("SDL_AUDIODRIVER", "dummy")
+        os.environ.setdefault("PYGAME_HIDE_SUPPORT_PROMPT", "1")
+
+    from tappty import Session, pygame_ui
+    from tappty.pyte_terminal import PyteTerminal
+    from tappty.source import EngineSource
+
+    session = Session(PyteTerminal(64, 22), source=EngineSource(runner))
+    if args.snapshot:
+        base = args.snapshot[:-4] if args.snapshot.endswith(".png") else args.snapshot
+        pygame_ui.run(
+            session, None, title="tappty color chart", snapshot_path=base, max_seconds=args.seconds
+        )
+    else:
+        pygame_ui.run(session, None, title="tappty color chart")
+
+
+if __name__ == "__main__":
+    main()