@kud/cli-shot 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  <img src="https://img.shields.io/badge/licence-MIT-blue?style=flat-square" alt="MIT licence" />
7
7
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="Node >=20" />
8
8
 
9
- **Automatic screenshots of interactive CLIs — pty capture, terminal emulation, PNG out.**
9
+ **Automatic screenshots and recordings of interactive CLIs — pty capture, terminal emulation, PNG, asciicast, a web player, GIF or MP4 out.**
10
10
 
11
11
  [Website](https://kud.io/projects/cli-shot) ·
12
12
  [Documentation](https://kud.io/projects/cli-shot/docs) ·
@@ -25,6 +25,7 @@ window captures that go stale the next time the UI moves.
25
25
  - **Fixtures by default** — `--mock` is on unless you opt out, because a screenshot outlives the moment it was taken
26
26
  - **Deterministic and headless** — fixed size, fixed data, no window manager, runnable in CI
27
27
  - **Scriptable last mile** — `--keys` reaches state a screen name can't address
28
+ - **Recordings too** — `--format cast` writes asciicast v2, `--format web` a static replay page ready for Vercel, and `--format gif` / `mp4` that page's window as a moving image
28
29
 
29
30
  ## Install
30
31
 
@@ -42,11 +43,16 @@ cli-shot --out assets/screenshots -- pcloud
42
43
  Everything after `--` is the command being driven, so its own flags stay clear
43
44
  of cli-shot's.
44
45
 
45
- Two exceptions: cli-shot appends `--mock` and `--screen` to that command itself.
46
- Passing either one yourself leaves two in argv — the app reads the first while
47
- the filename comes from the second, which is how you get a `files.png` holding
48
- the Sync screen. cli-shot refuses rather than guessing, and points you at
49
- `--only` or `--no-mock`.
46
+ cli-shot adds `--mock` and `--screen` to that command, but only where you
47
+ haven't. Anything you pass wins:
48
+
49
+ ```sh
50
+ cli-shot --out shots -- pcloud --screen sync # shoots Sync, writes sync.png
51
+ cli-shot --out shots --only sync -- pcloud # the same thing, said from here
52
+ ```
53
+
54
+ Naming a screen yourself is already an answer to "which one", so cli-shot skips
55
+ the discovery loop and takes the filename from your value.
50
56
 
51
57
  ```sh
52
58
  cli-shot --out shots --only sync -- pcloud # one screen
@@ -55,17 +61,113 @@ cli-shot --out shots --keys $'jjj\r' -- pcloud # drive deeper first
55
61
  cli-shot --out shots --no-mock -- pcloud # real data (careful)
56
62
  ```
57
63
 
58
- | flag | |
59
- | ------------------- | ------------------------------------------------- |
60
- | `-o, --out <dir>` | directory to write PNGs into |
61
- | `--only <screen>` | shoot one screen instead of every screen |
62
- | `--list` | print the screens the command offers, and stop |
63
- | `--cols` / `--rows` | terminal size (default 110×32) |
64
- | `--settle <ms>` | how long the screen must hold still (default 350) |
65
- | `--jobs <n>` | screens shot at once; defaults to the core count |
66
- | `--keys <sequence>` | keystrokes sent once the screen has drawn |
67
- | `--font <family>` | font to render with; defaults to a Nerd Font |
68
- | `--no-mock` | drive real data instead of fixtures |
64
+ | flag | |
65
+ | -------------------- | --------------------------------------------------- |
66
+ | `-o, --out <dir>` | directory to write into |
67
+ | `--format <list>` | `png`, `cast`, `web`, `gif`, `mp4`, comma-separated |
68
+ | `--only <screen>` | shoot one screen instead of every screen |
69
+ | `--list` | print the screens the command offers, and stop |
70
+ | `--cols` / `--rows` | terminal size (default 110×32) |
71
+ | `--settle <ms>` | how long the screen must hold still (default 350) |
72
+ | `--jobs <n>` | screens shot at once; defaults to the core count |
73
+ | `--keys <sequence>` | keystrokes sent once the screen has drawn |
74
+ | `--font <family>` | font to render with; defaults to a Nerd Font |
75
+ | `--title <text>` | page title for `web`, window title for `gif`/`mp4` |
76
+ | `--base <path>` | `<base href>` for the web page, see below |
77
+ | `--fps <n>` | `gif`/`mp4` frames per second (default 15) |
78
+ | `--speed <n>` | `gif`/`mp4` playback speed (default 1) |
79
+ | `--max-duration <s>` | `gif`/`mp4` longest replay; sped up to fit |
80
+ | `--loop <n>` | `gif` plays, 0 for forever (default 0) |
81
+ | `--scale <n>` | `gif`/`mp4` pixel density, 2 for retina (default 1) |
82
+ | `--no-mock` | drive real data instead of fixtures |
83
+
84
+ ## Recordings and the web player
85
+
86
+ The same capture that becomes a PNG can be kept as a recording. The pty
87
+ stream is written as it arrived, timed, up to the moment the screen settled —
88
+ so a cast always ends on the frame its PNG shows.
89
+
90
+ ```sh
91
+ cli-shot --out demo --format cast -- pcloud # demo/<screen>.cast
92
+ cli-shot --out demo --format png,cast -- pcloud # both, from one capture
93
+ cli-shot --out demo --format web -- pcloud # casts + a replay page
94
+ ```
95
+
96
+ `.cast` files are [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/),
97
+ so `asciinema play demo/sync.cast` and any asciicast player read them.
98
+
99
+ `--format web` writes the casts plus a static page that replays them, one
100
+ window per screen, into the same folder:
101
+
102
+ ```
103
+ demo/
104
+ ├── index.html
105
+ ├── vercel.json
106
+ ├── <screen>.cast
107
+ └── assets/ player.js · chrome.css · xterm.js · Symbols Nerd Font
108
+ ```
109
+
110
+ The folder deploys as it stands — `vercel deploy demo` — with no build step.
111
+ The page replays through xterm.js, the browser build of the emulator that
112
+ resolved the capture, and bundles the Symbols Nerd Font so icons draw as they
113
+ do in a real terminal. Each recording sits in a dark macOS-style window,
114
+ whatever the page's light or dark mode (pin one with `?theme=light` or
115
+ `?theme=dark`). A window shows its final frame first, plays once when it
116
+ scrolls into view (never on its own under `prefers-reduced-motion`), and has
117
+ play/pause, restart and 1×/2× speed controls. On a narrow screen the terminal is scaled down
118
+ rather than re-wrapped, so a phone sees the same layout, smaller. Replay only:
119
+ nothing on the page accepts input.
120
+
121
+ The look lives in one file, `assets/chrome.css` (`player/chrome.css` in this
122
+ repository): page, window frame and the terminal palette, all as CSS custom
123
+ properties that the player reads.
124
+
125
+ When a site serves the page under another path — a rewrite from
126
+ `kud.io/projects/<name>/demo` to the deployment, say — pass that path so the
127
+ page's relative URLs resolve against it:
128
+
129
+ ```sh
130
+ cli-shot --out demo --format web --base /projects/pcloud/demo/ -- pcloud
131
+ ```
132
+
133
+ To try it locally, from a clone:
134
+
135
+ ```sh
136
+ npm install && npm run build
137
+ npm run example:web # drives examples/harbour.mjs, an invented TUI
138
+ npx serve examples/web # or any static server
139
+ ```
140
+
141
+ `examples/casts/` holds recordings of the same fixture, made with
142
+ `npm run example:casts`.
143
+
144
+ ## GIF and MP4
145
+
146
+ Where a moving image has to travel on its own — a social post, a slide, a
147
+ README — the same capture can be filmed as a GIF or an MP4:
148
+
149
+ ```sh
150
+ cli-shot --out demo --format gif -- pcloud # demo/<screen>.gif
151
+ cli-shot --out demo --format png,web,gif,mp4 -- pcloud # all from one capture
152
+ cli-shot --out demo --format gif --speed 2 --max-duration 6 -- pcloud
153
+ ```
154
+
155
+ The frames are the web player's own window — the macOS chrome from
156
+ `chrome.css`, the bundled Symbols Nerd Font, xterm.js — rendered in headless
157
+ Chromium and encoded with ffmpeg, so a GIF looks like the web demo it sits
158
+ beside. The recording is stepped on its own clock rather than played in real
159
+ time, and only frames where something changed are kept, so the output is
160
+ identical on a slow machine and a fast one, and small: a single palette, no
161
+ dithering, only the changed rectangle stored per frame. The last frame, the
162
+ one the PNG shows, holds for two seconds before the loop.
163
+
164
+ `--max-duration` speeds a long recording up to fit rather than cutting it,
165
+ so a GIF still ends on the settled screen. `--loop` counts plays, `0` meaning
166
+ forever; an MP4 ignores it.
167
+
168
+ Filming needs two things the PNG path does not: `ffmpeg` on `PATH`, and
169
+ Playwright with its Chromium (`npm install playwright && npx playwright install chromium`).
170
+ Both are only looked for when `gif` or `mp4` is asked for.
69
171
 
70
172
  ## The contract
71
173
 
@@ -89,6 +191,7 @@ than they usually intend, and a screenshot outlives the moment it was taken.
89
191
 
90
192
  ```
91
193
  node-pty → @xterm/headless → serialize → freeze → png
194
+ └────────────── timed stream ──────────────────→ cast → web page
92
195
  ```
93
196
 
94
197
  The middle step is the one that isn't obvious. A pty hands back **every redraw