polly-tui git:20260921.f94744aA

Immutable. This exact content never changes and is served at /api/v1/blob/9c5e206c77f0dc00.

---
name: polly-tui
description: Capture the polly TUI as PNGs — play a scenario of typed input, keys and shots through polly's own off-screen renderer, then read the images
---

# Capturing the polly TUI

`driver.sh` builds `./polly` and plays a scenario through polly's own
off-screen renderer, so a frame can be captured with no terminal, pty
host, window or screen-recording permission. Runs use an isolated `HOME`
(`~/.cache/polly-tui-home`) and leave PNGs in `/tmp/polly-shots/`
(override with `POLLY_SHOT_DIR`).

```bash
D=.agents/skills/polly-tui/driver.sh   # run from the repo root
$D hshot scenario.txt                  # prints each PNG path it writes
$D hshot scenario.txt 160x50           # at a wider virtual terminal
```

```text
# scenario.txt — :shot paths are $VAR- and ~-expanded
:shot $POLLY_SHOT_DIR/splash.png
/help
:wait "Navigate" 5
:shot $POLLY_SHOT_DIR/help.png
:size 160x50
:settle
:shot $POLLY_SHOT_DIR/help-wide.png
```

A bare line is typed and submitted; `:` lines are steps: `:key <name>`,
`:type <text>`, `:submit <text>`, `:shot <path>`, `:size WxH`,
`:wait <pattern> [sec]`, `:settle [sec]`, `:ready [sec]`, `:sleep <ms>`,
`:quit`. Key names: `enter`, `esc`, `tab`, `up`, `down`, `left`, `right`,
`pgup`, `pgdn`, `home`, `end`, `insert`, `delete`, `backspace`, `space`,
`c-a`…`c-z`. The full reference is
[docs/CLI.md § Headless screenshots](../../../docs/CLI.md#headless-screenshots).

Read the PNGs with the Read tool. A capture is the frame painted after
the step before it, so no shot contains the step that asked for it, and a
step that never happens (a `:wait` pattern that never appears, a path that
cannot be written) fails the run with its script line instead of silently
capturing something else.

A capture is polly's own frame: cells in theme colors, plus every image
polly placed (thumbnails, the masthead logo) at one pixel per screen
pixel. What a terminal would then do with those pixels — image scaling or
palette quantization, the hardware cursor, window chrome — is not
reproduced. A scenario makes a real API call only if it types a prompt and
a provider key is exported; commands, keys and `/attach` are free.

## Gotchas

- The transcript is bottom-pinned: a long output (`/help`) scrolls its first
  lines out of a 40-row frame. `:wait` for a pattern that is visible, or use
  a taller size.
- The first typed line waits out the startup workspace baseline (the Git diff
  behind the first frame) so it runs instead of queueing. Input typed while a
  turn runs still queues, exactly as for a fast typist — that is what `:wait`,
  `:settle` and `:ready` are for.
- `git` must be on `PATH`, cwd must not be the real `$HOME`, and `HOME` must
  not be under `/tmp` (a gitconfig inside a writable sandbox path). The
  driver's isolated HOME and the repo root satisfy both.