termcut 0.8.0 → 1.0.0

package/README.md

@@ -51,7 +51,7 @@ defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t)
 });
 ```
 
-Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `title: "auto"` follows the title the program sets, `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.timelapse(fn, { speed: 8 })` fast-forwards an install, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `preset: "x"` sizes it for X.
+Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `title: "auto"` follows the title the program sets, `keys: true` shows key presses, `maxPause: "800ms"` cuts dead air, `t.timelapse(fn, { speed: 8 })` fast-forwards an install, `t.zoom({ rows: [0, 5] })` magnifies output, `t.chapter("Install")` adds mp4 chapters, `t.snapshot("hero.png")` (or `.svg`) saves a still of that exact moment on every render, `preset: "x"` sizes it for X.
 
 Faithful to the terminal: arrows switch to the form vim/less asked for, `t.paste()` uses bracketed paste (no autoindent stair-steps), synchronized-output repaints never show torn frames, and OSC 8 hyperlinks — including Markdown links in `t.print()` captions — stay clickable in SVG and HTML output.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",

package/src/cli.ts

@@ -370,7 +370,7 @@ export default defineVideo(
     await t.sleep("400ms");
     await t.enter();
     await t.wait();                         // prompt is back
-    await t.screenshot("${name}-notes.png");
+    await t.snapshot("${name}-notes.png");
     await t.sleep("1.5s");
   },
 );

package/src/export/svg.ts

@@ -1,3 +1,5 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
 import { fitFrame } from "../loop";
 import { barHeight, embedImage } from "../renderer/page";
 import type { Recording, ResolvedConfig } from "../types";
@@ -165,11 +167,29 @@ export interface SvgResult {
   duration: number;
 }
 
+/** The shared document: chrome (background, window, bar, watermark) around exporter-supplied style + body. */
+async function svgDocument(config: ResolvedConfig, g: Geometry, title: string, style: string, body: string): Promise<string> {
+  const { theme, font } = config;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${g.width}" height="${g.height}" viewBox="0 0 ${g.width} ${g.height}" font-family="${esc(font.family)}" font-size="${font.size}">
+<style>
+${style}text{white-space:pre;dominant-baseline:auto}
+</style>
+${config.marginFill === "transparent" ? "" : `<rect width="100%" height="100%" fill="${config.marginFill}"/>`}
+${shadowDefs(config)}
+<rect x="${num(g.frameX)}" y="${num(g.frameY)}" width="${num(g.frameW)}" height="${num(g.frameH)}" rx="${config.borderRadius}" fill="${theme.background}"${config.shadow ? ' filter="url(#shadow)"' : ""}/>
+${windowBar(config, g, title)}
+<clipPath id="term"><rect x="${num(g.termX)}" y="${num(g.termY)}" width="${num(g.termW)}" height="${num(g.termH)}"/></clipPath>
+<g clip-path="url(#term)"><g transform="translate(${num(g.termX)} ${num(g.termY)})">${body}</g></g>
+${await watermarkMarkup(config, g)}
+</svg>
+`;
+}
+
 /** Animated SVG: a horizontal strip of unique frames moved by a stepped CSS animation. No JS, no fonts embedded. */
 export async function buildSvg(rec: Recording, config: ResolvedConfig): Promise<SvgResult> {
   const replay = await replayFrames(rec, config);
   const g = svgGeometry(config, replay.cols, replay.rows);
-  const { theme, font } = config;
   const n = replay.frames.length;
   const total = replay.duration;
 
@@ -184,25 +204,46 @@ export async function buildSvg(rec: Recording, config: ResolvedConfig): Promise<
     .map((f, i) => `<g transform="translate(${num(i * g.termW)} 0)">${frameMarkup(f, config, g)}</g>`)
     .join("\n");
 
-  const svg = `<?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="${g.width}" height="${g.height}" viewBox="0 0 ${g.width} ${g.height}" font-family="${esc(font.family)}" font-size="${font.size}">
-<style>
-.strip{animation:tcut ${num(total)}s steps(1,end) infinite}
-@keyframes tcut{${keyframes.join("")}}
-text{white-space:pre;dominant-baseline:auto}
-</style>
-${config.marginFill === "transparent" ? "" : `<rect width="100%" height="100%" fill="${config.marginFill}"/>`}
-${shadowDefs(config)}
-<rect x="${num(g.frameX)}" y="${num(g.frameY)}" width="${num(g.frameW)}" height="${num(g.frameH)}" rx="${config.borderRadius}" fill="${theme.background}"${config.shadow ? ' filter="url(#shadow)"' : ""}/>
-${windowBar(config, g, config.title === "auto" ? (replay.title ?? "") : config.title)}
-<clipPath id="term"><rect x="${num(g.termX)}" y="${num(g.termY)}" width="${num(g.termW)}" height="${num(g.termH)}"/></clipPath>
-<g clip-path="url(#term)"><g transform="translate(${num(g.termX)} ${num(g.termY)})"><g class="strip" xml:space="preserve">
-${frames}
-</g></g></g>
-${await watermarkMarkup(config, g)}
-</svg>
-`;
-  return { svg, frames: n, duration: total };
+  const style = `.strip{animation:tcut ${num(total)}s steps(1,end) infinite}\n@keyframes tcut{${keyframes.join("")}}\n`;
+  const body = `<g class="strip" xml:space="preserve">\n${frames}\n</g>`;
+  const title = config.title === "auto" ? (replay.title ?? "") : config.title;
+  return { svg: await svgDocument(config, g, title, style, body), frames: n, duration: total };
+}
+
+export interface SnapshotMark {
+  file: string;
+  /** Seconds on the visible timeline. */
+  at: number;
+}
+
+/** The frame on screen at `at` seconds (frames carry their start time; the last one started before `at` wins). */
+function frameAt(frames: GridFrame[], at: number): GridFrame | undefined {
+  let current = frames[0];
+  for (const f of frames) {
+    if (f.time <= at + 1e-9) current = f;
+    else break;
+  }
+  return current;
+}
+
+/** Static (non-animated) SVG stills for `t.snapshot("x.svg")` marks — one replay serves all of them. */
+export async function writeSvgSnapshots(rec: Recording, config: ResolvedConfig, marks: SnapshotMark[]): Promise<string[]> {
+  const replay = await replayFrames(rec, config);
+  const g = svgGeometry(config, replay.cols, replay.rows);
+  const title = config.title === "auto" ? (replay.title ?? "") : config.title;
+  const written: string[] = [];
+  for (const mark of marks) {
+    // The raster pass applies output and marks that share a frame tick together; match that: the mark
+    // captures the first tick at or after its instant, so output recorded just before it is included.
+    const tick = Math.ceil(mark.at * config.fps - 1e-6) / config.fps;
+    const frame = frameAt(replay.frames, tick);
+    if (!frame) continue;
+    const svg = await svgDocument(config, g, title, "", `<g xml:space="preserve">${frameMarkup(frame, config, g)}</g>`);
+    await mkdir(path.dirname(path.resolve(mark.file)), { recursive: true });
+    await Bun.write(mark.file, svg);
+    written.push(mark.file);
+  }
+  return written;
 }
 
 export async function writeSvg(rec: Recording, config: ResolvedConfig, file: string): Promise<SvgResult> {

package/src/recorder.ts

@@ -385,10 +385,11 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     expect,
     hide,
     timelapse,
-    screenshot: async (file) => {
+    snapshot: async (file) => {
       await screen.settle();
       push("m", MARKER.screenshot + file);
     },
+    screenshot: (file) => session.snapshot(file),
     marker: async (name) => {
       push("m", name);
     },

package/src/render.ts

@@ -1,14 +1,38 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
+import { MARKER } from "./cast";
 import { chapterRanges, chapterSlug, cutRecording, findChapters, flattenedConfig, selectChapters } from "./edit";
 import { frameText, replayFrames } from "./export/frames";
 import { writeHtml } from "./export/html";
-import { writeSvg } from "./export/svg";
+import { writeSvg, writeSvgSnapshots, type SnapshotMark } from "./export/svg";
+import { buildTimeline } from "./timeline";
 import { render as renderRaster, type RenderResult } from "./renderer/webview";
 import type { ClipSelection, Recording, RenderProgress, ResolvedConfig } from "./types";
 
 export type { RenderResult };
 
+/**
+ * `t.snapshot(file)` marks with their instants on the visible timeline. `.svg` stills are produced headlessly
+ * (same clock as the SVG exporter); anything else is a raster still written by the WebView pass.
+ */
+interface SnapshotMarks {
+  vector: SnapshotMark[];
+  /** How many marks need pixels (anything that is not `.svg`). */
+  raster: number;
+}
+
+function snapshotMarks(rec: Recording, config: ResolvedConfig): SnapshotMarks {
+  const vector: SnapshotMark[] = [];
+  let raster = 0;
+  for (const e of buildTimeline(rec.events, config.playbackSpeed).events) {
+    if (e.type !== "m" || !e.data.startsWith(MARKER.screenshot)) continue;
+    const file = e.data.slice(MARKER.screenshot.length);
+    if (file.toLowerCase().endsWith(".svg")) vector.push({ file, at: e.vt });
+    else raster += 1;
+  }
+  return { vector, raster };
+}
+
 const kind = (output: string): "svg" | "html" | "txt" | "log" | "raster" => {
   if (output.endsWith("/")) return "raster";
   const ext = path.extname(output).toLowerCase();
@@ -50,6 +74,7 @@ export async function renderOutputs(
   const raster = config.output.filter((o) => kind(o) === "raster");
 
   const result: RenderResult = { outputs: [], frames: 0, screenshots: [], durationSeconds: 0 };
+  const marks = snapshotMarks(rec, config);
 
   for (const file of txt) {
     await writeTxt(rec, config, file);
@@ -70,7 +95,11 @@ export async function renderOutputs(
     await writeHtml(rec, config, file);
     result.outputs.push(file);
   }
-  if (raster.length > 0) {
+  if (marks.vector.length > 0) {
+    result.screenshots.push(...(await writeSvgSnapshots(rec, config, marks.vector)));
+  }
+  // Raster snapshots need pixels: run the WebView pass even when no raster output is configured.
+  if (raster.length > 0 || marks.raster > 0) {
     const r = await renderRaster(rec, { ...config, output: raster }, onProgress);
     result.outputs.push(...r.outputs);
     result.frames = r.frames;

package/src/renderer/webview.ts

@@ -216,7 +216,7 @@ export async function render(
 
       const blinkOn = !config.cursor.blink || Math.floor((time / blinkPeriod) * 2) % 2 === 0;
       const drawable = batch.filter((e) => e.type === "o" || e.type === "r");
-      const shots = batch.filter((e) => e.type === "m" && e.data.startsWith(MARKER.screenshot));
+      const shots = batch.filter((e) => e.type === "m" && e.data.startsWith(MARKER.screenshot) && !e.data.toLowerCase().endsWith(".svg"));
       const browserFrame = hasBrowser ? batch.filter((e) => e.type === "b").at(-1) : undefined;
       const focusChanged = hasBrowser && batch.some((e) => e.type === "m" && e.data.startsWith(MARKER.focus));
       let dirty = lastPng === null || drawable.length > 0 || blinkOn !== lastBlink || browserFrame !== undefined || focusChanged;

package/src/types.ts

@@ -353,7 +353,14 @@ export interface TerminalSession {
 
   /** Everything inside `fn` happens, but is cut from the video (state changes are kept). */
   hide<T>(fn: () => Promise<T>): Promise<T>;
-  /** Save a PNG of the current frame during rendering. */
+  /**
+   * Save a still of this exact moment when the video renders: `.png` (pixel-perfect raster) or `.svg`
+   * (vector, selectable text — produced headlessly, no WebView). Written by `tcut <script>` and
+   * `tcut render`, even when no video output is configured, so one script keeps the video and its
+   * screenshots in sync.
+   */
+  snapshot(path: string): Promise<void>;
+  /** Alias of `snapshot` (pre-1.0 name). */
   screenshot(path: string): Promise<void>;
   /** Insert a named marker (written to the .cast, useful for chapters/tooling). */
   marker(name: string): Promise<void>;