tui-cap 0.1.0

package/dist/server.js

@@ -0,0 +1,978 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GUI_PORT = void 0;
+exports.isPortInUse = isPortInUse;
+exports.waitForPort = waitForPort;
+exports.startServer = startServer;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_http_1 = __importDefault(require("node:http"));
+const node_net_1 = __importDefault(require("node:net"));
+const node_path_1 = __importDefault(require("node:path"));
+const parse_1 = require("./parse");
+const paths_1 = require("./paths");
+const meta_1 = require("./meta");
+const timing_1 = require("./timing");
+const input_1 = require("./input");
+const anim_1 = require("./anim");
+const edits_1 = require("./edits");
+const palette_1 = require("./palette");
+const svg_1 = require("./svg");
+const version_1 = require("./version");
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 50;
+const CAPTURE_EXT = /\.ans$/i;
+/** Default port the GUI binds to (shared by the `gui` command and record auto-launch). */
+exports.DEFAULT_GUI_PORT = 4787;
+const frameCache = new Map();
+/** Parse + cache the frames for one capture, keyed by file + mtime + dims. */
+async function getFrames(name, dims) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    const st = await (0, promises_1.stat)(file);
+    const key = `${name}|${dims.cols}|${dims.rows}`;
+    const hit = frameCache.get(key);
+    if (hit && hit.mtimeMs === st.mtimeMs)
+        return hit.frames;
+    const data = await (0, promises_1.readFile)(file);
+    // Pull in capture timing (if recorded) so frames carry real durations. The
+    // sidecar is optional; without it frames simply have no startMs/durationMs.
+    const timing = await (0, timing_1.readTiming)(file);
+    // Pull in keystroke counts (if recorded) so frames are tagged as user typing
+    // and carry a prompt caret. Also optional; parse falls back to content growth.
+    const input = await (0, input_1.readInput)(file);
+    const frames = await (0, parse_1.extractFrames)(data, {
+        cols: dims.cols,
+        rows: dims.rows,
+        timing: timing?.events,
+        input: input?.events,
+    });
+    frameCache.set(key, { mtimeMs: st.mtimeMs, frames });
+    return frames;
+}
+/** Drop every cached frame set for one capture (all dims), e.g. after deletion. */
+function invalidateFrames(name) {
+    const prefix = `${name}|`;
+    for (const key of frameCache.keys()) {
+        if (key.startsWith(prefix))
+            frameCache.delete(key);
+    }
+}
+const editsCache = new Map();
+/**
+ * Load a recording's edits sidecar (cached by sidecar mtime). Returns the
+ * default empty document when there is no sidecar yet. Never throws.
+ */
+async function getEditsDoc(name) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    let mtimeMs = null;
+    try {
+        mtimeMs = (await (0, promises_1.stat)((0, edits_1.editsPathFor)(file))).mtimeMs;
+    }
+    catch {
+        mtimeMs = null;
+    }
+    const hit = editsCache.get(name);
+    if (hit && hit.mtimeMs === mtimeMs)
+        return hit.doc;
+    const doc = (await (0, edits_1.readEdits)(file)) ?? (0, edits_1.defaultEdits)();
+    editsCache.set(name, { mtimeMs, doc });
+    return doc;
+}
+/** Drop the cached edits document for one capture (after a save or delete). */
+function invalidateEdits(name) {
+    editsCache.delete(name);
+}
+/**
+ * The list of edits that apply to a recording at the given dims, or an empty
+ * list when edits are disabled, absent, or the source recording changed shape
+ * (re-record) so the saved anchors no longer fit.
+ */
+async function applicableEdits(name, dims, editsOn) {
+    if (!editsOn)
+        return [];
+    const doc = await getEditsDoc(name);
+    if (doc.edits.length === 0)
+        return [];
+    if (!(0, edits_1.fingerprintMatches)(doc, { ansMtime: 0, cols: dims.cols, rows: dims.rows }))
+        return [];
+    return doc.edits;
+}
+/** Whether the `edits` query param disables edits for this request. */
+function editsEnabled(q) {
+    const v = q.get('edits');
+    return v !== '0' && v !== 'false';
+}
+/** Whether the typing block cursor should be drawn. Off unless `cursor=1`/`true`
+ *  is present, since it changes rendered appearance and SVG export. */
+function cursorEnabled(q) {
+    const v = q.get('cursor');
+    return v === '1' || v === 'true';
+}
+/* ----------------------------------------------------------- safety + args */
+/**
+ * Validate a capture name from a URL so it can only ever name a `.ans` file
+ * directly inside the captures folder — never escape it via `..` or absolute
+ * paths. Returns the clean basename, or null if the name is unsafe.
+ */
+function safeCaptureName(raw) {
+    let name;
+    try {
+        name = decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+    if (name.includes('\0'))
+        return null;
+    if (name !== node_path_1.default.basename(name))
+        return null;
+    if (name.startsWith('.'))
+        return null;
+    if (!CAPTURE_EXT.test(name))
+        return null;
+    return name;
+}
+/**
+ * Validate a user-supplied *new* capture name (from a rename request body),
+ * appending `.ans` when the user omits it. Like {@link safeCaptureName} it only
+ * ever permits a plain basename inside the captures folder — never a `..`
+ * traversal, absolute path, or dotfile. Returns the clean name, or null.
+ */
+function cleanCaptureName(raw) {
+    let name = raw.trim();
+    if (!name)
+        return null;
+    if (!CAPTURE_EXT.test(name))
+        name += '.ans';
+    if (name.includes('\0'))
+        return null;
+    if (name !== node_path_1.default.basename(name))
+        return null;
+    if (name.startsWith('.'))
+        return null;
+    if (!CAPTURE_EXT.test(name))
+        return null;
+    return name;
+}
+function intParam(value, fallback, min, max) {
+    const n = value === null ? NaN : Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.round(n)));
+}
+function floatParam(value, fallback, min, max) {
+    const n = value === null ? NaN : Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, n));
+}
+/**
+ * The dimensions a capture was recorded at, read from its `.meta.json` sidecar.
+ * Replaying through a terminal of the same size lands every cell back in its
+ * original column/row, so the recorded size is authoritative — the GUI no
+ * longer lets the user override it. Falls back to the defaults when a capture
+ * has no sidecar (e.g. recorded with --no-meta).
+ */
+async function resolveDims(name) {
+    const meta = await (0, meta_1.readMeta)(node_path_1.default.join((0, paths_1.capturesDir)(), name));
+    if (meta) {
+        return {
+            cols: Math.max(1, Math.min(1000, Math.round(meta.cols))),
+            rows: Math.max(1, Math.min(1000, Math.round(meta.rows))),
+        };
+    }
+    return { cols: DEFAULT_COLS, rows: DEFAULT_ROWS };
+}
+function renderOptsFromQuery(q) {
+    const theme = q.get('theme') === 'light' ? 'light' : 'dark';
+    const overrides = {};
+    const chrome = q.get('chrome');
+    if (chrome === '0' || chrome === 'false')
+        overrides.chrome = false;
+    const chromeStyle = q.get('chromeStyle');
+    if (chromeStyle === 'windows' ||
+        chromeStyle === 'windows-inactive' ||
+        chromeStyle === 'mac' ||
+        chromeStyle === 'mac-inactive')
+        overrides.chromeStyle = chromeStyle;
+    const title = q.get('title');
+    if (title !== null)
+        overrides.title = title;
+    const font = q.get('font');
+    if (font)
+        overrides.fontFamily = font;
+    if (q.get('fontSize'))
+        overrides.fontSize = intParam(q.get('fontSize'), 14, 6, 96);
+    if (q.get('lineHeight'))
+        overrides.lineHeight = floatParam(q.get('lineHeight'), 1.25, 0.8, 2.5);
+    if (q.get('padding'))
+        overrides.padding = intParam(q.get('padding'), 24, 0, 200);
+    if (q.get('radius'))
+        overrides.radius = intParam(q.get('radius'), 12, 0, 64);
+    // Uniform animation canvas: pin a minimum cols×rows so every frame in a
+    // recording renders at identical pixel dimensions (required for MP4 export).
+    if (q.get('fixedCols'))
+        overrides.fixedCols = intParam(q.get('fixedCols'), 0, 1, 100000);
+    if (q.get('fixedRows'))
+        overrides.fixedRows = intParam(q.get('fixedRows'), 0, 1, 100000);
+    return (0, svg_1.defaultRenderOptions)(theme, overrides);
+}
+/* ----------------------------------------------------------- http helpers */
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    res.end(text);
+}
+function sendError(res, status, message) {
+    sendJson(res, status, { error: message });
+}
+/** Read and JSON-parse a request body (capped), or null if absent/too big/invalid. */
+function readJsonBody(req, limitBytes = 1_000_000) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0;
+        let aborted = false;
+        req.on('data', (c) => {
+            if (aborted)
+                return;
+            size += c.length;
+            if (size > limitBytes) {
+                aborted = true;
+                resolve(null);
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            if (aborted)
+                return;
+            const text = Buffer.concat(chunks).toString('utf8').trim();
+            if (!text)
+                return resolve(null);
+            try {
+                resolve(JSON.parse(text));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        req.on('error', () => resolve(null));
+    });
+}
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.png': 'image/png',
+    '.woff2': 'font/woff2',
+};
+/** Locate the web/ assets, which sit next to this module in both dev and dist. */
+function webDir() {
+    return node_path_1.default.join(__dirname, 'web');
+}
+async function serveStatic(res, urlPath) {
+    const root = webDir();
+    const rel = urlPath === '/' ? 'index.html' : urlPath.replace(/^\/+/, '');
+    const target = node_path_1.default.join(root, rel);
+    // Never serve outside the web root.
+    if (target !== root && !target.startsWith(root + node_path_1.default.sep)) {
+        sendError(res, 403, 'forbidden');
+        return;
+    }
+    try {
+        const body = await (0, promises_1.readFile)(target);
+        res.writeHead(200, { 'content-type': MIME[node_path_1.default.extname(target)] ?? 'application/octet-stream' });
+        res.end(body);
+    }
+    catch {
+        sendError(res, 404, 'not found');
+    }
+}
+/* ----------------------------------------------------------- API endpoints */
+async function listRecordings(res) {
+    const dir = (0, paths_1.capturesDir)();
+    let names = [];
+    try {
+        names = (await (0, promises_1.readdir)(dir)).filter((n) => CAPTURE_EXT.test(n));
+    }
+    catch {
+        // captures dir may not exist yet — return an empty library
+    }
+    const items = await Promise.all(names.map(async (name) => {
+        const st = await (0, promises_1.stat)(node_path_1.default.join(dir, name));
+        let frameCount = 0;
+        let defaultIndex = 0;
+        try {
+            const frames = await getFrames(name, await resolveDims(name));
+            frameCount = frames.length;
+            defaultIndex = (0, parse_1.chooseFrame)(frames).index;
+        }
+        catch {
+            // unreadable capture — still list it, just with 0 frames
+        }
+        return { name, size: st.size, mtime: st.mtimeMs, frames: frameCount, defaultIndex };
+    }));
+    items.sort((a, b) => b.mtime - a.mtime);
+    sendJson(res, 200, { dir, recordings: items });
+}
+async function listFrames(res, name) {
+    const dims = await resolveDims(name);
+    const frames = await getFrames(name, dims);
+    const defaultIndex = (0, parse_1.chooseFrame)(frames).index;
+    // Trailing teardown trim: the animation runs from the first frame through the
+    // last *settled* one (the screen the user held on), dropping the half-erased
+    // exit frames after it. chooseFrame already finds that settled frame.
+    const animationEnd = defaultIndex;
+    const hasTiming = frames.some((f) => f.durationMs !== undefined);
+    // Content edits (recolours, rewrites, and especially spacing inserts/removes)
+    // change a frame's measured size, so measure the *edited* grids — the uniform
+    // animation canvas must be big enough for the edited content.
+    const edits = await applicableEdits(name, dims, true);
+    const editsDoc = await getEditsDoc(name);
+    const gridFor = (f) => (edits.length ? (0, edits_1.toDisplayGrid)(f.grid, edits) : f.grid);
+    // Uniform animation canvas: the largest content extent across the animation
+    // range [0..animationEnd]. The GUI pins every animation/export frame to this
+    // size (via fixedCols/fixedRows) so the MP4 has a single, stable resolution.
+    const animTheme = (0, svg_1.defaultRenderOptions)('dark').theme;
+    let animCols = 1;
+    let animRows = 1;
+    for (let i = 0; i <= Math.min(animationEnd, frames.length - 1); i++) {
+        const m = (0, svg_1.measureGrid)(gridFor(frames[i]), animTheme);
+        if (m.cols > animCols)
+            animCols = m.cols;
+        if (m.rows > animRows)
+            animRows = m.rows;
+    }
+    sendJson(res, 200, {
+        name,
+        cols: dims.cols,
+        rows: dims.rows,
+        defaultIndex,
+        animationEnd,
+        hasTiming,
+        editsRevision: editsDoc.revision,
+        animCanvas: { cols: animCols, rows: animRows },
+        frames: frames.map((f, i) => ({
+            index: i,
+            inAlt: f.inAlt,
+            preview: (0, parse_1.framePreview)(gridFor(f)),
+            startMs: f.startMs,
+            durationMs: f.durationMs,
+            isTyping: f.isTyping ?? false,
+            typedChars: f.typedChars ?? 0,
+        })),
+    });
+}
+async function renderFrameSvg(name, index, q) {
+    const dims = await resolveDims(name);
+    const frames = await getFrames(name, dims);
+    const i = Math.max(0, Math.min(frames.length - 1, index));
+    const edits = await applicableEdits(name, dims, editsEnabled(q));
+    // Apply content edits to the raw frame BEFORE trimming/rendering, so every
+    // output (preview, stills, MP4) inherits them through one shared transform.
+    const edited = edits.length ? (0, edits_1.toDisplayGrid)(frames[i].grid, edits) : frames[i].grid;
+    // `trim=0` keeps the captured grid untrimmed; pair it with fixedCols/fixedRows
+    // (see renderOptsFromQuery) so every animation frame renders at one uniform
+    // pixel size — required for MP4 export. The default trims background bleed for
+    // tighter stills.
+    const grid = q.get('trim') === '0' ? edited : (0, parse_1.trimBackgroundBleed)(edited);
+    const opts = renderOptsFromQuery(q);
+    // The caret is per-frame data (not a query param): when the cursor toggle is
+    // on, draw the block at this frame's prompt caret. Trimming may have dropped
+    // the empty caret cell, but renderSvg re-extends the canvas to include it.
+    opts.cursor = cursorEnabled(q) ? (frames[i].caret ?? null) : null;
+    return (0, svg_1.renderSvg)(grid, opts);
+}
+function svgFileName(name, index) {
+    const stem = node_path_1.default.basename(name, node_path_1.default.extname(name));
+    return `${stem}-frame${String(index + 1).padStart(2, '0')}.svg`;
+}
+async function serveFrameSvg(res, name, index, q) {
+    const svg = await renderFrameSvg(name, index, q);
+    const headers = {
+        'content-type': 'image/svg+xml',
+        'cache-control': 'no-store',
+    };
+    if (q.get('download') === '1') {
+        headers['content-disposition'] = `attachment; filename="${svgFileName(name, index)}"`;
+    }
+    res.writeHead(200, headers);
+    res.end(svg);
+}
+/**
+ * Geometry + per-row content for a frame, used by the GUI's selection overlay so
+ * hit-testing lines up with the displayed image. Returns the same geometry
+ * `renderSvg` uses (font size, padding, chrome bar) computed from the *edited*
+ * grid, plus two layers per row: the shown text/wide-cell columns (display) and
+ * the stable raw source text + source-row index (for anchor capture). Honours
+ * the same `trim`/`fixedCols`/`fixedRows`/`edits` params as the SVG endpoint so
+ * the two never disagree.
+ */
+async function serveCells(res, name, index, q) {
+    const dims = await resolveDims(name);
+    const frames = await getFrames(name, dims);
+    const i = Math.max(0, Math.min(frames.length - 1, index));
+    const rawGrid = frames[i].grid;
+    const edits = await applicableEdits(name, dims, editsEnabled(q));
+    const { grid: displayGrid, sourceRows } = (0, edits_1.buildDisplay)(rawGrid, edits);
+    const shown = q.get('trim') === '0' ? displayGrid : (0, parse_1.trimBackgroundBleed)(displayGrid);
+    const opts = renderOptsFromQuery(q);
+    const cellW = opts.fontSize * opts.advance;
+    const cellH = Math.round(opts.fontSize * opts.lineHeight);
+    const fit = (0, svg_1.measureGrid)(shown, opts.theme);
+    const usedCols = Math.max(fit.cols, opts.fixedCols ?? 0);
+    const usedRows = Math.max(fit.rows, opts.fixedRows ?? 0);
+    const isWindows = opts.chromeStyle === 'windows' || opts.chromeStyle === 'windows-inactive';
+    const barH = opts.chrome ? (isWindows ? 32 : 40) : 0;
+    const contentLeft = opts.padding;
+    const contentTop = barH + opts.padding;
+    const width = Math.ceil(usedCols * cellW + opts.padding * 2);
+    const height = Math.ceil(usedRows * cellH + opts.padding * 2 + barH);
+    const rows = shown.lines.slice(0, usedRows).map((cells, idx) => {
+        const src = sourceRows[idx] ?? null;
+        // Per-glyph rendered foreground colour, keyed by start column, for the GUI
+        // eyedropper. Only real glyphs (non-space) are sampleable.
+        const fg = {};
+        for (const c of cells) {
+            if (c.char !== ' ')
+                fg[c.col] = (0, svg_1.cellForeground)(c, opts.theme);
+        }
+        return {
+            sourceRow: src,
+            text: (0, edits_1.rowText)(cells),
+            wide: cells.filter((c) => c.width === 2).map((c) => c.col),
+            fg,
+            rawLineText: src === null ? '' : (0, edits_1.rowText)(rawGrid.lines[src] ?? []),
+        };
+    });
+    const editsDoc = await getEditsDoc(name);
+    sendJson(res, 200, {
+        name,
+        index: i,
+        editsRevision: editsDoc.revision,
+        geometry: { cellW, cellH, contentLeft, contentTop, barH, width, height, cols: usedCols, rows: usedRows },
+        rows,
+    });
+}
+async function recordCommand(res, q) {
+    const cmd = (q.get('cmd') ?? '').trim();
+    let name = (q.get('name') ?? '').trim();
+    if (name && !CAPTURE_EXT.test(name))
+        name += '.ans';
+    const safeName = name ? safeCaptureName(name) : null;
+    if (name && !safeName) {
+        sendError(res, 400, 'invalid capture name');
+        return;
+    }
+    // Named → bake in `-o`; blank → omit it so the CLI auto-names the next
+    // copilot-capture_NN.ans. `out` reflects the file that will be written either
+    // way, so the UI can show it.
+    const out = safeName ?? (await (0, paths_1.nextCaptureName)());
+    const command = safeName
+        ? `tui-cap record -o ${safeName} -- ${cmd || '<command>'}`
+        : `tui-cap record -- ${cmd || '<command>'}`;
+    sendJson(res, 200, { command, out });
+}
+/** GET a recording's animation settings, falling back to defaults when unsaved. */
+async function getAnimation(res, name) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    const saved = await (0, anim_1.readAnimation)(file);
+    sendJson(res, 200, { settings: saved ?? (0, anim_1.defaultAnimationSettings)() });
+}
+/** PUT (save) a recording's animation settings from a JSON body. */
+async function putAnimation(req, res, name) {
+    const body = await readJsonBody(req);
+    if (body === null) {
+        sendError(res, 400, 'invalid JSON body');
+        return;
+    }
+    const settings = (0, anim_1.normalizeSettings)(body);
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    try {
+        await (0, anim_1.writeAnimation)(file, settings);
+    }
+    catch (err) {
+        sendError(res, 500, err instanceof Error ? err.message : 'could not save settings');
+        return;
+    }
+    sendJson(res, 200, { settings });
+}
+/** GET a recording's content edits, falling back to an empty doc when unsaved. */
+async function getEdits(res, name) {
+    const doc = await getEditsDoc(name);
+    sendJson(res, 200, { edits: doc });
+}
+/**
+ * PUT (save) a recording's content edits from a JSON body. Bumps the document
+ * revision (for undo tagging + light optimistic concurrency) and stamps the
+ * current recording fingerprint so a later re-record can detect a shape change.
+ */
+async function putEdits(req, res, name) {
+    const body = await readJsonBody(req);
+    if (body === null) {
+        sendError(res, 400, 'invalid JSON body');
+        return;
+    }
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    const dims = await resolveDims(name);
+    let ansMtime = 0;
+    try {
+        ansMtime = (await (0, promises_1.stat)(file)).mtimeMs;
+    }
+    catch {
+        // capture vanished mid-edit; fingerprint just stays zero (treated as unknown)
+    }
+    const incoming = (0, edits_1.normalizeEdits)(body, { ansMtime, cols: dims.cols, rows: dims.rows });
+    const prev = await getEditsDoc(name);
+    const doc = {
+        ...incoming,
+        recording: { ansMtime, cols: dims.cols, rows: dims.rows },
+        revision: prev.revision + 1,
+    };
+    try {
+        await (0, edits_1.writeEdits)(file, doc);
+    }
+    catch (err) {
+        sendError(res, 500, err instanceof Error ? err.message : 'could not save edits');
+        return;
+    }
+    invalidateEdits(name);
+    sendJson(res, 200, { edits: doc });
+}
+/** DELETE (reset) a recording's content edits by removing the sidecar. */
+async function deleteEdits(res, name) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    await (0, promises_1.unlink)((0, edits_1.editsPathFor)(file)).catch(() => { });
+    invalidateEdits(name);
+    sendJson(res, 200, { reset: name });
+}
+/** The Primer palette the GUI offers for recolouring text, per theme. */
+function servePalette(res) {
+    const swatches = (t) => ({
+        ansi: palette_1.ANSI_PALETTES[t],
+        background: palette_1.THEMES[t].background,
+        foreground: palette_1.THEMES[t].foreground,
+    });
+    sendJson(res, 200, { dark: swatches('dark'), light: swatches('light') });
+}
+/** Delete a capture and its meta sidecar, dropping any cached frames. */
+async function deleteRecording(res, name) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    try {
+        await (0, promises_1.unlink)(file);
+    }
+    catch {
+        sendError(res, 404, 'recording not found');
+        return;
+    }
+    // Best-effort: sidecars may not exist (e.g. recorded with --no-meta, or never
+    // opened in the timeline editor).
+    await Promise.all([
+        (0, promises_1.unlink)((0, meta_1.metaPathFor)(file)).catch(() => { }),
+        (0, promises_1.unlink)((0, timing_1.timingPathFor)(file)).catch(() => { }),
+        (0, promises_1.unlink)((0, input_1.inputPathFor)(file)).catch(() => { }),
+        (0, promises_1.unlink)((0, anim_1.animPathFor)(file)).catch(() => { }),
+        (0, promises_1.unlink)((0, edits_1.editsPathFor)(file)).catch(() => { }),
+    ]);
+    invalidateFrames(name);
+    invalidateEdits(name);
+    sendJson(res, 200, { deleted: name });
+}
+/**
+ * Rename a capture and every sidecar that belongs to it (`.meta.json`,
+ * `.timing.json`, `.input.json`, `.anim.json`, `.edits.json`) in one go, so a
+ * project keeps all of its parts together. Refuses to clobber an existing
+ * recording. Sidecars are moved best-effort since any of them may be absent.
+ */
+async function renameRecording(req, res, name) {
+    const body = await readJsonBody(req);
+    const to = body?.to;
+    if (typeof to !== 'string') {
+        sendError(res, 400, 'missing "to" name');
+        return;
+    }
+    const target = cleanCaptureName(to);
+    if (!target) {
+        sendError(res, 400, 'invalid target name');
+        return;
+    }
+    if (target === name) {
+        sendJson(res, 200, { renamed: name, to: target });
+        return;
+    }
+    const dir = (0, paths_1.capturesDir)();
+    const src = node_path_1.default.join(dir, name);
+    const dst = node_path_1.default.join(dir, target);
+    // Never overwrite an existing capture.
+    try {
+        await (0, promises_1.stat)(dst);
+        sendError(res, 409, `a recording named ${target} already exists`);
+        return;
+    }
+    catch {
+        // good — the target name is free
+    }
+    try {
+        await (0, promises_1.rename)(src, dst);
+    }
+    catch (err) {
+        sendError(res, 500, err instanceof Error ? err.message : 'could not rename recording');
+        return;
+    }
+    await Promise.all([
+        (0, promises_1.rename)((0, meta_1.metaPathFor)(src), (0, meta_1.metaPathFor)(dst)).catch(() => { }),
+        (0, promises_1.rename)((0, timing_1.timingPathFor)(src), (0, timing_1.timingPathFor)(dst)).catch(() => { }),
+        (0, promises_1.rename)((0, input_1.inputPathFor)(src), (0, input_1.inputPathFor)(dst)).catch(() => { }),
+        (0, promises_1.rename)((0, anim_1.animPathFor)(src), (0, anim_1.animPathFor)(dst)).catch(() => { }),
+        (0, promises_1.rename)((0, edits_1.editsPathFor)(src), (0, edits_1.editsPathFor)(dst)).catch(() => { }),
+    ]);
+    invalidateFrames(name);
+    invalidateEdits(name);
+    sendJson(res, 200, { renamed: name, to: target });
+}
+/**
+ * Reveal a capture in the OS file manager so the user can find it on disk:
+ * Finder (macOS) and Explorer (Windows) select the file; other platforms open
+ * the captures folder. Best-effort — spawned detached so it never blocks. Set
+ * GHCP_REVEAL_CMD to override the launcher (handy on Linux, and for tests).
+ */
+function revealRecording(res, name) {
+    const file = node_path_1.default.join((0, paths_1.capturesDir)(), name);
+    let cmd;
+    let args;
+    const override = process.env.GHCP_REVEAL_CMD;
+    if (override) {
+        cmd = override;
+        args = [file];
+    }
+    else if (process.platform === 'darwin') {
+        cmd = 'open';
+        args = ['-R', file];
+    }
+    else if (process.platform === 'win32') {
+        cmd = 'explorer';
+        args = [`/select,${file}`];
+    }
+    else {
+        cmd = 'xdg-open';
+        args = [(0, paths_1.capturesDir)()];
+    }
+    try {
+        (0, node_child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: true }).unref();
+        sendJson(res, 200, { revealed: name });
+    }
+    catch (err) {
+        sendError(res, 500, err instanceof Error ? err.message : 'could not reveal file');
+    }
+}
+/**
+ * Open the captures folder itself in the OS file manager (as opposed to
+ * revealing a single file). Ensures the folder exists first so the launcher
+ * never fails on a fresh install. Best-effort — spawned detached.
+ */
+async function openCapturesFolder(res) {
+    const dir = (0, paths_1.capturesDir)();
+    await (0, promises_1.mkdir)(dir, { recursive: true }).catch(() => { });
+    const override = process.env.GHCP_REVEAL_CMD;
+    let cmd;
+    if (override)
+        cmd = override;
+    else if (process.platform === 'darwin')
+        cmd = 'open';
+    else if (process.platform === 'win32')
+        cmd = 'explorer';
+    else
+        cmd = 'xdg-open';
+    try {
+        (0, node_child_process_1.spawn)(cmd, [dir], { stdio: 'ignore', detached: true }).unref();
+        sendJson(res, 200, { opened: dir });
+    }
+    catch (err) {
+        sendError(res, 500, err instanceof Error ? err.message : 'could not open folder');
+    }
+}
+/* ---------------------------------------------------------- version/update */
+// Cache the registry lookup for the server's lifetime so repeated GUI loads and
+// SSE-driven refreshes don't hammer npm. A failed lookup is cached only briefly
+// so a transient network blip doesn't suppress the prompt for the full hour.
+const LATEST_TTL_MS = 60 * 60 * 1000;
+const LATEST_FAIL_TTL_MS = 60 * 1000;
+let latestCache = null;
+async function cachedLatestVersion() {
+    const now = Date.now();
+    if (latestCache && now < latestCache.expires)
+        return latestCache.value;
+    const value = await (0, version_1.fetchLatestVersion)();
+    latestCache = {
+        value,
+        expires: now + (value === null ? LATEST_FAIL_TTL_MS : LATEST_TTL_MS),
+    };
+    return value;
+}
+/** Report the running version and whether a newer one is published on npm. */
+async function serveVersion(res) {
+    const current = (0, version_1.currentVersion)();
+    const latest = await cachedLatestVersion();
+    sendJson(res, 200, {
+        name: version_1.PACKAGE_NAME,
+        current,
+        latest,
+        updateAvailable: latest !== null && (0, version_1.isNewer)(latest, current),
+        installKind: (0, version_1.installKind)(),
+        updateCommand: (0, version_1.updateCommand)(),
+    });
+}
+/**
+ * Run the self-update on the user's behalf (the GUI "Update now" button).
+ * An npx invocation has nothing to update in place, so it returns guidance
+ * instead of shelling out. The freshly running server still holds the old code
+ * until it's restarted, which the client is told to do on success.
+ */
+async function performUpdate(res) {
+    const kind = (0, version_1.installKind)();
+    if (kind === 'npx') {
+        sendJson(res, 200, {
+            ok: false,
+            skipped: true,
+            installKind: kind,
+            command: `npx ${version_1.PACKAGE_NAME}@latest`,
+            message: `You're running via npx — re-run \`npx ${version_1.PACKAGE_NAME}@latest\` to use the newest version.`,
+        });
+        return;
+    }
+    const result = await (0, version_1.runSelfUpdate)();
+    // Refresh the cache so a follow-up /api/version reflects the just-published
+    // latest (the running process is still the old build until restarted).
+    const latest = await cachedLatestVersion();
+    sendJson(res, result.ok ? 200 : 500, { ...result, installKind: kind, latest });
+}
+/* ----------------------------------------------------------- SSE (library) */
+function serveEvents(req, res) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+        connection: 'keep-alive',
+    });
+    res.write('retry: 2000\n\n');
+    const dir = (0, paths_1.capturesDir)();
+    let timer = null;
+    const ping = setInterval(() => res.write(': ping\n\n'), 25_000);
+    let watcher = null;
+    try {
+        watcher = (0, node_fs_1.watch)(dir, () => {
+            // Debounce bursts of fs events into a single notification.
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => res.write('event: recordings\ndata: changed\n\n'), 200);
+        });
+    }
+    catch {
+        // captures dir missing/unwatchable — the heartbeat still keeps SSE open
+    }
+    req.on('close', () => {
+        clearInterval(ping);
+        if (timer)
+            clearTimeout(timer);
+        watcher?.close();
+    });
+}
+/* ------------------------------------------------------------------ router */
+async function handle(req, res) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const { pathname, searchParams } = url;
+    if (!pathname.startsWith('/api/')) {
+        await serveStatic(res, pathname);
+        return;
+    }
+    if (pathname === '/api/recordings' && req.method === 'GET') {
+        return listRecordings(res);
+    }
+    if (pathname === '/api/events' && req.method === 'GET') {
+        return serveEvents(req, res);
+    }
+    if (pathname === '/api/record-command' && req.method === 'GET') {
+        return recordCommand(res, searchParams);
+    }
+    if (pathname === '/api/palette' && req.method === 'GET') {
+        return servePalette(res);
+    }
+    if (pathname === '/api/open-folder' && req.method === 'POST') {
+        return openCapturesFolder(res);
+    }
+    if (pathname === '/api/version' && req.method === 'GET') {
+        return serveVersion(res);
+    }
+    if (pathname === '/api/update' && req.method === 'POST') {
+        return performUpdate(res);
+    }
+    // /api/recordings/:name/frames  and  /api/recordings/:name/frames/:i/svg
+    const framesMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/frames$/);
+    const svgMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/frames\/(\d+)\/svg$/);
+    const cellsMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/frames\/(\d+)\/cells$/);
+    const animMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/animation$/);
+    const editsMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/edits$/);
+    const revealMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/reveal$/);
+    const renameMatch = pathname.match(/^\/api\/recordings\/([^/]+)\/rename$/);
+    const deleteMatch = pathname.match(/^\/api\/recordings\/([^/]+)$/);
+    const rawName = framesMatch?.[1] ??
+        svgMatch?.[1] ??
+        cellsMatch?.[1] ??
+        animMatch?.[1] ??
+        editsMatch?.[1] ??
+        revealMatch?.[1] ??
+        renameMatch?.[1] ??
+        deleteMatch?.[1];
+    if (rawName !== undefined) {
+        const name = safeCaptureName(rawName);
+        if (!name)
+            return sendError(res, 400, 'invalid recording name');
+        try {
+            await (0, promises_1.stat)(node_path_1.default.join((0, paths_1.capturesDir)(), name));
+        }
+        catch {
+            return sendError(res, 404, 'recording not found');
+        }
+        if (framesMatch && req.method === 'GET')
+            return listFrames(res, name);
+        if (svgMatch && req.method === 'GET') {
+            return serveFrameSvg(res, name, Number(svgMatch[2]), searchParams);
+        }
+        if (cellsMatch && req.method === 'GET') {
+            return serveCells(res, name, Number(cellsMatch[2]), searchParams);
+        }
+        if (animMatch && req.method === 'GET')
+            return getAnimation(res, name);
+        if (animMatch && req.method === 'PUT')
+            return putAnimation(req, res, name);
+        if (editsMatch && req.method === 'GET')
+            return getEdits(res, name);
+        if (editsMatch && req.method === 'PUT')
+            return putEdits(req, res, name);
+        if (editsMatch && req.method === 'DELETE')
+            return deleteEdits(res, name);
+        if (revealMatch && req.method === 'POST')
+            return revealRecording(res, name);
+        if (renameMatch && req.method === 'POST')
+            return renameRecording(req, res, name);
+        if (deleteMatch && req.method === 'DELETE')
+            return deleteRecording(res, name);
+    }
+    sendError(res, 404, 'not found');
+}
+/* ------------------------------------------------------------------ listen */
+/**
+ * Resolve whether something is already accepting connections on host:port by
+ * attempting a short-lived TCP connect. A successful connect means the port is
+ * in use (assume our GUI); a connection-refused or timeout means it's free.
+ * Used so `record` can skip launching a second server when one is already up.
+ */
+function isPortInUse(port, host = '127.0.0.1', timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const socket = new node_net_1.default.Socket();
+        let settled = false;
+        const finish = (inUse) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(inUse);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => finish(true));
+        socket.once('timeout', () => finish(false));
+        socket.once('error', () => finish(false));
+        socket.connect(port, host);
+    });
+}
+/**
+ * Poll until host:port accepts connections or the timeout elapses. Returns true
+ * once the port is live, false if it never came up. Used to confirm a
+ * detached GUI child actually started before reporting its URL.
+ */
+async function waitForPort(port, host = '127.0.0.1', timeoutMs = 4000) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await isPortInUse(port, host, 300))
+            return true;
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    return false;
+}
+function listen(server, port, host, maxTries) {
+    return new Promise((resolve, reject) => {
+        let attempts = 0;
+        const onError = (err) => {
+            if (err.code === 'EADDRINUSE' && port !== 0 && attempts < maxTries) {
+                attempts++;
+                server.listen(port + attempts, host);
+            }
+            else {
+                reject(err);
+            }
+        };
+        server.on('error', onError);
+        server.listen(port, host, () => {
+            server.removeListener('error', onError);
+            resolve(server.address().port);
+        });
+    });
+}
+function openBrowser(url) {
+    let cmd;
+    let args;
+    if (process.platform === 'darwin') {
+        cmd = 'open';
+        args = [url];
+    }
+    else if (process.platform === 'win32') {
+        cmd = 'cmd';
+        args = ['/c', 'start', '', url];
+    }
+    else {
+        cmd = 'xdg-open';
+        args = [url];
+    }
+    try {
+        (0, node_child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // best-effort; the URL is printed for the user to open manually
+    }
+}
+/**
+ * Start the local GUI server. Reuses the capture/render pipeline and serves the
+ * `web/` frontend. Binds to localhost only and resolves once it's listening.
+ */
+async function startServer(opts = {}) {
+    const host = opts.host ?? '127.0.0.1';
+    const desired = opts.port ?? exports.DEFAULT_GUI_PORT;
+    await (0, promises_1.mkdir)((0, paths_1.capturesDir)(), { recursive: true }).catch(() => { });
+    const server = node_http_1.default.createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!res.headersSent)
+                sendError(res, 500, message);
+            else
+                res.end();
+        });
+    });
+    const port = await listen(server, desired, host, 20);
+    const url = `http://${host}:${port}`;
+    if (opts.open !== false)
+        openBrowser(url);
+    return {
+        url,
+        port,
+        close: () => new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+    };
+}