tui-cap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Foxly
+
+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.

package/README.md

@@ -0,0 +1,213 @@
+# tui-cap
+
+<img width="1623" height="1005" alt="tui-cap GUI screenshot" src="https://github.com/user-attachments/assets/886a413b-8123-4358-b8dd-3c20233b60e5" />
+
+**Turn GitHub Copilot CLI (or any terminal program) into a clean, editable,
+brand-correct image.**
+
+`tui-cap` records a terminal session and turns it into an **SVG with real, editable
+text** — the exact GitHub colors, ready to drop straight into Figma or Illustrator
+for slides, docs, and marketing shots. It can also export a **PNG** or a **timed
+MP4** of the whole session.
+
+Screenshots give you the look but flatten everything to pixels. Copy/paste gives
+you the text but throws the colors away. `tui-cap` keeps **both**.
+
+> Currently supported on **macOS**.
+
+---
+
+## What you need
+
+1. **macOS.**
+2. **Node.js 20 or newer.** To check, open Terminal and run:
+   ```bash
+   node --version
+   ```
+   If you see `v20` (or higher), you're set. If the command isn't found or the
+   number is lower, install the **LTS** version from
+   **[nodejs.org](https://nodejs.org/)** — download the macOS installer and
+   double-click it, no terminal needed.
+3. **(Only to record the Copilot CLI)** the `copilot` command, installed and
+   signed in. Everything else works without it.
+
+That's the entire setup. There's nothing to compile and no other tools to install.
+
+---
+
+## Install
+
+You don't have to install anything — run it on demand with `npx`:
+
+```bash
+npx tui-cap --help
+```
+
+The first run downloads the tool automatically (answer **yes** if prompted). If
+you'll use it often, install it once so the `tui-cap` command is always available:
+
+```bash
+npm install -g tui-cap
+```
+
+To update later, run `tui-cap update` — or `npm install -g tui-cap@latest`.
+
+> **Stay current automatically.** Every time you open the app, `tui-cap` checks
+> npm for a newer release. When one is available, a banner appears at the top with
+> an **Update now** button — one click upgrades you in place (just restart the app
+> afterward). Prefer the terminal? Run `tui-cap update`.
+
+> The rest of this guide writes commands as `tui-cap …`. If you didn't install
+> globally, just put `npx ` in front, e.g. `npx tui-cap record …`.
+
+---
+
+## Quick start — capture the Copilot CLI
+
+**1. Record a session.** This launches the Copilot CLI inside a recorder:
+
+```bash
+tui-cap record -o my-shot.ans -- copilot
+```
+
+Use Copilot normally — type a prompt, let it answer. When you're happy, **quit
+Copilot** (e.g. `/exit`, or press `Ctrl+C`) to stop recording.
+
+**2. The app opens automatically.** When recording stops, `tui-cap` opens a small
+app in your browser showing your recording.
+
+**3. Pick a frame and export.** Scrub the timeline to the moment you want, tweak
+the look if you like (window title, size, spacing), then click:
+
+- **Save SVG…** — editable text + colors, perfect for Figma/Illustrator.
+- **Save PNG…** — a flat image at 1×–4× size.
+- **Export MP4…** — a timed video of the whole session.
+
+Your recording and exports are saved in a **`captures` folder in your home
+directory** (`~/captures`). That's it.
+
+> **Want to record something other than Copilot?** Put any command after `--`,
+> e.g. `tui-cap record -o demo.ans -- git log --oneline`.
+
+---
+
+## Commands
+
+Run `tui-cap --help` (or `tui-cap <command> --help`) any time for the full list.
+
+| Command | What it does |
+| --- | --- |
+| **`tui-cap record -o <file> -- <command>`** | Record a live terminal session (e.g. `copilot`) to a capture file, then open the app to review and export it. |
+| **`tui-cap gui`** | Open the app to browse your captures, pick frames, tweak the look, and export SVG / PNG / MP4. |
+| **`tui-cap render <file.ans>`** | Turn a capture into an editable **SVG** straight from the command line (no app). |
+| **`tui-cap asciinema <file.cast>`** | Turn an existing [asciinema](https://asciinema.org) recording into an SVG. |
+| **`tui-cap update`** | Update to the latest published version (`npm install -g tui-cap@latest`). |
+| **`tui-cap --version`** | Print the installed version. |
+
+### Handy options
+
+**`record`**
+- `-o <file>` — name for the capture. Omit it and recordings are auto-numbered
+  (`copilot-capture_01.ans`, `_02`, …) in your captures folder.
+- `--no-gui` — don't auto-open the app when recording finishes.
+
+**`gui`**
+- `--port <n>` — pick a port (default `4787`; it auto-picks the next free one).
+- `--no-open` — start the server but don't open a browser; just print the URL.
+
+**`render`**
+- `-o <file.svg>` — output path (defaults to your captures folder).
+- `--theme dark|light` — color theme (default `dark`).
+- `--title "<text>"` — the window title bar text (default "GitHub Copilot CLI").
+- `--no-chrome` — drop the window frame / title bar.
+- `--list-frames` — list the frames in a capture so you can pick one with
+  `--frame <n>`.
+
+**`asciinema`**
+- `--at <seconds>` — render the frame at that time (default: the end).
+
+---
+
+## Using the app (GUI)
+
+`tui-cap gui` opens a local app (it runs only on your machine) that turns your
+captures folder into a visual library:
+
+- **Browse captures** — every recording, newest first; it refreshes on its own
+  when a new recording lands.
+- **Scrub the timeline** — drag through the session and watch the big preview
+  update; play it back with the space bar.
+- **Tweak the look** — window title, window style (macOS / Windows), show/hide the
+  window frame, font size, and line spacing all update the preview live.
+- **Edit the content (non-destructively)** — recolor or rewrite text right on the
+  canvas, or add/remove blank lines for spacing. Your edits follow the text across
+  every frame and never change the original recording.
+- **Export** — Save SVG, Save PNG (1×–4×), or Export a timed **MP4** of the
+  animation.
+
+> **MP4 export needs a modern browser** with a built-in H.264 encoder — **Chrome,
+> Edge, or Safari 16.4+**. (Firefox can't export MP4 yet.) SVG and PNG export work
+> everywhere. The video is made entirely on your machine — nothing is uploaded.
+
+---
+
+## Where your files are saved
+
+Everything lands in one **captures folder** so shots don't scatter across whatever
+project you recorded from:
+
+- By default that's **`~/captures`** (created automatically).
+- Bare filenames (`-o my-shot.ans`) and outputs go there.
+- Want a specific location? Pass a path with a slash (`-o ./shot.ans` or
+  `-o /tmp/shot.ans`) and it's written there instead.
+- Prefer a different default folder? Set the `GHCP_CAPTURE_DIR` environment
+  variable.
+
+`render` also looks in the captures folder, so `record -o shot.ans -- copilot`
+followed by `render shot.ans` works from any directory.
+
+---
+
+## Tips & troubleshooting
+
+- **`command not found: copilot`** — install and sign in to the Copilot CLI first,
+  then try the `record` command again.
+- **My recording only shows the shell prompt.** Full-screen tools (like Copilot)
+  wipe their screen when they exit. `tui-cap` handles this for you — it keeps the
+  live frame by default. Use the app's timeline, or `render … --list-frames` and
+  `--frame <n>`, to pick a different moment.
+- **The "Do you trust this folder?" prompt.** Answer it inside the recorded
+  session (it's part of Copilot's startup), then continue.
+- **MP4 export is greyed out.** Open the app in Chrome, Edge, or Safari 16.4+ (see
+  above).
+- **A capture keystroke cursor / typing effect (advanced).** The optional
+  `--backend pty` records keystrokes for a typing-cursor effect. It needs the
+  optional native `node-pty` package and is intended for people running from a
+  source checkout; the default recorder already captures timing for MP4 export.
+
+---
+
+## How it works (the short version)
+
+The colors never actually leave the terminal — your *clipboard* strips them. The
+escape codes for color, bold, italic, and underline are right there in the bytes
+the program prints. `tui-cap`:
+
+1. **Records** the raw output through a real terminal, so the program behaves
+   exactly as it would for you.
+2. **Replays** it through the same engine that powers xterm.js, snapshotting the
+   screen so it recovers real *frames* (important for full-screen tools that
+   repaint constantly).
+3. **Draws** each frame as an SVG where every run of same-styled text is genuine,
+   editable `<text>` with an exact hex color.
+
+For the full architecture, timing model, Figma details, and contributor docs, see
+**[DEVELOPMENT.md](DEVELOPMENT.md)**.
+
+---
+
+## License
+
+[MIT](LICENSE) © Cameron Foxly
+
+Contributions and development setup: see **[DEVELOPMENT.md](DEVELOPMENT.md)**.

package/dist/anim.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TYPING_CPS = exports.DEFAULT_SPEED = exports.DEFAULT_SCALE = exports.DEFAULT_FPS = exports.ANIM_SCHEMA_VERSION = void 0;
+exports.defaultAnimationSettings = defaultAnimationSettings;
+exports.animPathFor = animPathFor;
+exports.normalizeSettings = normalizeSettings;
+exports.readAnimation = readAnimation;
+exports.writeAnimation = writeAnimation;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const animation_1 = require("./animation");
+exports.ANIM_SCHEMA_VERSION = 1;
+exports.DEFAULT_FPS = 30;
+exports.DEFAULT_SCALE = 2;
+exports.DEFAULT_SPEED = 1;
+exports.DEFAULT_TYPING_CPS = 30;
+const FPS_RANGE = [1, 120];
+const SCALE_RANGE = [1, 4];
+const IDLE_CAP_RANGE = [0, 600_000];
+const SPEED_RANGE = [0.1, 100];
+const OVERRIDE_RANGE = [0, 600_000];
+const TYPING_CPS_RANGE = [10, 60];
+/** Default settings used when a recording has no sidecar yet. */
+function defaultAnimationSettings() {
+    return {
+        schemaVersion: exports.ANIM_SCHEMA_VERSION,
+        fps: exports.DEFAULT_FPS,
+        scale: exports.DEFAULT_SCALE,
+        idleCapMs: animation_1.DEFAULT_IDLE_CAP_MS,
+        speed: exports.DEFAULT_SPEED,
+        overrides: {},
+        skipped: [],
+        smoothTyping: false,
+        typingCps: exports.DEFAULT_TYPING_CPS,
+    };
+}
+/** Sibling sidecar path for a capture: `foo.ans` -> `foo.anim.json`. */
+function animPathFor(captureFile) {
+    const dir = node_path_1.default.dirname(captureFile);
+    const base = node_path_1.default.basename(captureFile, node_path_1.default.extname(captureFile));
+    return node_path_1.default.join(dir, `${base}.anim.json`);
+}
+function clamp(n, [min, max]) {
+    return Math.max(min, Math.min(max, n));
+}
+function num(value, fallback, range) {
+    return typeof value === 'number' && Number.isFinite(value) ? clamp(value, range) : fallback;
+}
+/**
+ * Coerce arbitrary input (e.g. a request body) into valid settings, clamping
+ * every field to a sane range and dropping malformed overrides. Always returns
+ * a complete, safe object — never throws.
+ */
+function normalizeSettings(input) {
+    const src = (input && typeof input === 'object' ? input : {});
+    const base = defaultAnimationSettings();
+    const overrides = {};
+    if (src.overrides && typeof src.overrides === 'object') {
+        for (const [key, value] of Object.entries(src.overrides)) {
+            if (!/^\d+$/.test(key))
+                continue; // frame index keys only
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                continue;
+            overrides[key] = clamp(value, OVERRIDE_RANGE);
+        }
+    }
+    const skipped = Array.isArray(src.skipped)
+        ? Array.from(new Set(src.skipped.filter((n) => typeof n === 'number' && Number.isInteger(n) && n >= 0))).sort((a, b) => a - b)
+        : [];
+    return {
+        schemaVersion: exports.ANIM_SCHEMA_VERSION,
+        fps: num(src.fps, base.fps, FPS_RANGE),
+        scale: num(src.scale, base.scale, SCALE_RANGE),
+        idleCapMs: num(src.idleCapMs, base.idleCapMs, IDLE_CAP_RANGE),
+        speed: num(src.speed, base.speed, SPEED_RANGE),
+        overrides,
+        skipped,
+        smoothTyping: typeof src.smoothTyping === 'boolean' ? src.smoothTyping : base.smoothTyping,
+        typingCps: num(src.typingCps, base.typingCps, TYPING_CPS_RANGE),
+    };
+}
+/**
+ * Read a recording's animation settings, or null when there's no sidecar yet.
+ * Never throws — a garbled file is treated as absent so the GUI falls back to
+ * defaults.
+ */
+async function readAnimation(captureFile) {
+    try {
+        const raw = await (0, promises_1.readFile)(animPathFor(captureFile), 'utf8');
+        return normalizeSettings(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a recording's animation settings sidecar. Returns the sidecar path. */
+async function writeAnimation(captureFile, settings) {
+    const out = animPathFor(captureFile);
+    await (0, promises_1.writeFile)(out, `${JSON.stringify(normalizeSettings(settings), null, 2)}\n`, 'utf8');
+    return out;
+}

package/dist/animation.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Pure timeline math for turning captured frame timing into an animation.
+ *
+ * Kept free of any I/O or DOM dependency so the exact same logic runs on the
+ * server (annotating `/frames` with durations) and in the browser (previewing
+ * and encoding the export). Everything here is deterministic and unit-tested.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TAIL_MS = exports.DEFAULT_IDLE_CAP_MS = void 0;
+exports.frameDurations = frameDurations;
+exports.applyTimeline = applyTimeline;
+exports.cfrCounts = cfrCounts;
+exports.cfrTotalFrames = cfrTotalFrames;
+exports.totalDurationMs = totalDurationMs;
+/**
+ * Default cap on how long any single frame is held (ms). A real session often
+ * pauses for many seconds on one screen; without a cap that idle time would
+ * dominate the animation, so gaps longer than this are clamped. Adjustable per
+ * recording and overridable per frame.
+ */
+exports.DEFAULT_IDLE_CAP_MS = 1500;
+/**
+ * Default hold (ms) for the final frame when the capture ends the instant it
+ * appears (a clean exit), so the animation doesn't end on a 0ms flash.
+ */
+exports.DEFAULT_TAIL_MS = 1200;
+/**
+ * Raw per-frame durations derived from each kept frame's appearance time.
+ * `startsMs[i]` is when frame *i* first appeared (ms since capture start) and
+ * `endMs` is the total capture length. Frame *i* is held until frame *i+1*
+ * appears; the last frame is held to `endMs`, floored to `tailMs` so a clean
+ * final paint still lingers instead of vanishing instantly.
+ */
+function frameDurations(startsMs, endMs, tailMs = exports.DEFAULT_TAIL_MS) {
+    const n = startsMs.length;
+    if (n === 0)
+        return [];
+    const out = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const next = i + 1 < n ? startsMs[i + 1] : endMs;
+        out[i] = Math.max(0, next - startsMs[i]);
+    }
+    out[n - 1] = Math.max(out[n - 1], Math.max(0, tailMs));
+    return out;
+}
+/**
+ * Apply user timeline tweaks to raw durations. Overrides win outright (no cap,
+ * no speed); smooth-typing then retimes flagged typing frames to a constant
+ * rate (no cap, no speed); otherwise each duration is capped to `idleCapMs`,
+ * divided by `speed`, then floored to `minMs`. Returns a new array the same
+ * length as `raw`.
+ */
+function applyTimeline(raw, opts = {}) {
+    const cap = opts.idleCapMs ?? exports.DEFAULT_IDLE_CAP_MS;
+    const speed = opts.speed && opts.speed > 0 ? opts.speed : 1;
+    const min = Math.max(0, opts.minMs ?? 0);
+    const overrides = opts.overrides ?? {};
+    const smoothTyping = opts.smoothTyping ?? false;
+    const cps = opts.typingCps && opts.typingCps > 0 ? opts.typingCps : 30;
+    const isTyping = opts.isTyping;
+    const typedChars = opts.typedChars;
+    return raw.map((d, i) => {
+        if (Object.prototype.hasOwnProperty.call(overrides, i) && Number.isFinite(overrides[i])) {
+            return Math.max(min, overrides[i]);
+        }
+        if (smoothTyping && isTyping?.[i] && (typedChars?.[i] ?? 0) > 0) {
+            // Absolute hold for a typing frame: one beat per character at `cps`.
+            return Math.max(min, (typedChars[i] / cps) * 1000);
+        }
+        let v = Math.max(0, d);
+        if (cap > 0)
+            v = Math.min(v, cap);
+        v = v / speed;
+        if (min > 0)
+            v = Math.max(v, min);
+        return v;
+    });
+}
+/**
+ * Map variable per-frame durations to constant-frame-rate repeat counts. At
+ * `fps`, frame *i* is shown for `round(durationMs / 1000 * fps)` output frames,
+ * at least 1 so every frame stays visible. Returns the per-frame counts.
+ */
+function cfrCounts(durationsMs, fps) {
+    const f = fps > 0 ? fps : 1;
+    return durationsMs.map((ms) => Math.max(1, Math.round((Math.max(0, ms) / 1000) * f)));
+}
+/** Total output-frame count for a constant-frame-rate render at `fps`. */
+function cfrTotalFrames(durationsMs, fps) {
+    return cfrCounts(durationsMs, fps).reduce((a, b) => a + b, 0);
+}
+/** Sum of a duration list (ms) — the animation's total wall-clock length. */
+function totalDurationMs(durationsMs) {
+    return durationsMs.reduce((a, b) => a + Math.max(0, b), 0);
+}

package/dist/asciinema.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Minimal asciinema v2 cast ingest. The format is a JSON header line followed by
+ * one JSON array per event:
+ *
+ *   {"version": 2, "width": 120, "height": 40, "timestamp": 1718000000}
+ *   [0.123, "o", "raw bytes with \u001b[... escapes"]
+ *   [0.456, "r", "120x40"]
+ *   [0.789, "o", "more bytes"]
+ *
+ * Only "o" (output) and "r" (resize) events affect the rendered frame. We
+ * concatenate output up to a chosen time and report the terminal size in effect
+ * at that moment, so the cast header solves the PTY-size problem without a
+ * sidecar. See https://docs.asciinema.org/manual/asciicast/v2/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHeader = parseHeader;
+exports.extractFrame = extractFrame;
+exports.extractTiming = extractTiming;
+const timing_1 = require("./timing");
+/** Parse and validate the cast header (first non-empty line). */
+function parseHeader(raw) {
+    const line = raw.split('\n').find((l) => l.trim().length > 0);
+    if (!line)
+        throw new Error('asciinema: empty cast (no header line)');
+    let header;
+    try {
+        header = JSON.parse(line);
+    }
+    catch {
+        throw new Error('asciinema: header is not valid JSON');
+    }
+    const h = header;
+    if (h.version !== 2) {
+        throw new Error(`asciinema: unsupported version ${h.version ?? '(none)'}; only v2 is supported`);
+    }
+    if (typeof h.width !== 'number' || typeof h.height !== 'number') {
+        throw new Error('asciinema: header missing numeric width/height');
+    }
+    return {
+        version: 2,
+        width: h.width,
+        height: h.height,
+        timestamp: typeof h.timestamp === 'number' ? h.timestamp : undefined,
+    };
+}
+/**
+ * Concatenate all output events up to and including `atTime` (seconds). When
+ * `atTime` is undefined, all output is included. Resize events update the
+ * reported dimensions, so the returned cols/rows reflect the size at `atTime`.
+ */
+function extractFrame(raw, atTime) {
+    const header = parseHeader(raw);
+    let cols = header.width;
+    let rows = header.height;
+    const out = [];
+    const lines = raw.split('\n');
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue; // tolerate malformed/partial trailing lines
+        }
+        if (!Array.isArray(event) || event.length < 3)
+            continue;
+        const [time, code, data] = event;
+        if (typeof time !== 'number')
+            continue;
+        if (atTime !== undefined && time > atTime)
+            break;
+        if (code === 'o') {
+            out.push(data);
+        }
+        else if (code === 'r') {
+            const m = /^(\d+)x(\d+)$/.exec(String(data).trim());
+            if (m) {
+                cols = Number(m[1]);
+                rows = Number(m[2]);
+            }
+        }
+    }
+    return { ansi: out.join(''), cols, rows };
+}
+/**
+ * Derive timing checkpoints from a cast, aligned to the byte offsets of the
+ * stream {@link extractFrame} produces (the concatenated `o`-event output). Each
+ * output event contributes a `[msSinceStart, cumulativeByteOffset]` checkpoint,
+ * so the animation pipeline can map a frame boundary in that stream back to the
+ * moment it played — exactly like the timing sidecar a live `record` writes.
+ */
+function extractTiming(raw) {
+    const header = parseHeader(raw);
+    const events = [];
+    let offset = 0;
+    const lines = raw.split('\n');
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(event) || event.length < 3)
+            continue;
+        const [time, code, data] = event;
+        if (typeof time !== 'number' || code !== 'o')
+            continue;
+        offset += Buffer.byteLength(String(data), 'utf8');
+        events.push([Math.max(0, Math.round(time * 1000)), offset]);
+    }
+    return {
+        schemaVersion: timing_1.TIMING_SCHEMA_VERSION,
+        startedAt: header.timestamp ? new Date(header.timestamp * 1000).toISOString() : '',
+        events,
+    };
+}