termcut 0.6.3 → 0.7.0

package/src/publish.ts

@@ -61,19 +61,19 @@ export function publicUrlFor(cfg: PublishConfig, key: string): string {
   return `${base}/${key.split("/").map(encodeURIComponent).join("/")}`;
 }
 
-const MIME: Record<string, string> = {
-  ".mp4": "video/mp4",
-  ".webm": "video/webm",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".svg": "image/svg+xml",
-  ".html": "text/html; charset=utf-8",
-  ".cast": "application/x-asciicast",
-  ".txt": "text/plain; charset=utf-8",
-};
+const MIME = new Map<string, string>([
+  [".mp4", "video/mp4"],
+  [".webm", "video/webm"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".svg", "image/svg+xml"],
+  [".html", "text/html; charset=utf-8"],
+  [".cast", "application/x-asciicast"],
+  [".txt", "text/plain; charset=utf-8"],
+]);
 
 export async function contentHash(file: string): Promise<string> {
   const hasher = new Bun.CryptoHasher("sha256");
@@ -111,7 +111,7 @@ export interface PublishOptions {
 
 async function upload(cfg: PublishConfig, file: string, key: string): Promise<void> {
   const s3 = client(cfg);
-  const type = MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+  const type = MIME.get(path.extname(file).toLowerCase()) ?? "application/octet-stream";
   try {
     await s3.write(key, Bun.file(file), { type, acl: "public-read" });
   } catch (err) {
@@ -151,21 +151,19 @@ function hmac(key: Uint8Array | string, data: string): Uint8Array {
 }
 const sha256Hex = (data: string | Uint8Array) => new Bun.CryptoHasher("sha256").update(data).digest("hex");
 
-export function signV4(cfg: PublishConfig, method: string, url: URL, body: string, now = new Date()): Record<string, string> {
+export function signV4(cfg: PublishConfig, method: string, url: URL, body: string, now = new Date()) {
   const region = cfg.region ?? "us-east-1";
   const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
   const date = amzDate.slice(0, 8);
   const payloadHash = sha256Hex(body);
-  const headers: Record<string, string> = {
+  const headers = {
     host: url.host,
     "x-amz-content-sha256": payloadHash,
     "x-amz-date": amzDate,
   };
-  const signedHeaders = Object.keys(headers).sort().join(";");
-  const canonicalHeaders = Object.keys(headers)
-    .sort()
-    .map((h) => `${h}:${headers[h]!.trim()}\n`)
-    .join("");
+  const sortedHeaders = Object.entries(headers).sort(([a], [b]) => (a < b ? -1 : 1));
+  const signedHeaders = sortedHeaders.map(([h]) => h).join(";");
+  const canonicalHeaders = sortedHeaders.map(([h, v]) => `${h}:${v.trim()}\n`).join("");
   const canonicalQuery = [...url.searchParams.entries()]
     .sort(([a], [b]) => (a < b ? -1 : 1))
     .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)

package/src/recorder.ts

@@ -106,15 +106,15 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
   };
 
   const setup = shellSetup(config);
-  const env: Record<string, string> = {
-    ...process.env,
+  const { PROMPT_COMMAND: _userPromptCommand, ...inheritedEnv } = process.env; // a user PROMPT_COMMAND would repaint over the clean prompt
+  const env = {
+    ...inheritedEnv,
     TERM: "xterm-256color",
     COLORTERM: "truecolor",
     LANG: process.env.LANG ?? "en_US.UTF-8",
     ...setup.env,
     ...config.env,
   };
-  delete env.PROMPT_COMMAND;
 
   let exited = false;
   const proc = Bun.spawn(setup.cmd, {
@@ -160,7 +160,7 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
   const raw = async (data: string | Uint8Array): Promise<void> => {
     ensureAlive();
     terminal.write(data);
-    push("i", typeof data === "string" ? data : decoder.decode(data));
+    push("i", data instanceof Uint8Array ? decoder.decode(data) : data);
   };
 
   /** Put text on screen as if the terminal had printed it: into the cast and the screen model, not the PTY. */
@@ -227,7 +227,7 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     pattern.test(scope === "screen" ? screen.screen() : screen.line());
 
   const toRegExp = (pattern: RegExp | string): RegExp =>
-    typeof pattern === "string" ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")) : pattern;
+    pattern instanceof RegExp ? pattern : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
 
   const waitFor = async (
     description: string,
@@ -307,6 +307,22 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     }
   };
 
+  const speedStack: number[] = [];
+  const timelapse = async <T>(fn: () => Promise<T>, tlOpts: { speed?: number } = {}): Promise<T> => {
+    const speed = tlOpts.speed ?? 8;
+    if (!(speed > 0)) throw new Error(`timelapse speed must be greater than 0, got ${speed}`);
+    await screen.settle();
+    speedStack.push(speed);
+    push("m", `${MARKER.speed}${speed}`);
+    try {
+      return await fn();
+    } finally {
+      await screen.settle();
+      speedStack.pop();
+      push("m", `${MARKER.speed}${speedStack[speedStack.length - 1] ?? 1}`);
+    }
+  };
+
   const session: TerminalSession = {
     type,
     run,
@@ -336,6 +352,7 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     wait,
     expect,
     hide,
+    timelapse,
     screenshot: async (file) => {
       await screen.settle();
       push("m", MARKER.screenshot + file);

package/src/render.ts

@@ -1,20 +1,31 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
+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 { render as renderRaster, type RenderResult } from "./renderer/webview";
-import type { Recording, RenderProgress, ResolvedConfig } from "./types";
+import type { ClipSelection, Recording, RenderProgress, ResolvedConfig } from "./types";
 
 export type { RenderResult };
 
-const kind = (output: string): "svg" | "html" | "raster" => {
+const kind = (output: string): "svg" | "html" | "txt" | "raster" => {
   if (output.endsWith("/")) return "raster";
   const ext = path.extname(output).toLowerCase();
   if (ext === ".svg") return "svg";
   if (ext === ".html" || ext === ".htm") return "html";
+  if (ext === ".txt") return "txt";
   return "raster";
 };
 
+/** The final screen as plain text (what `t.screen()` would return at the end). */
+export async function writeTxt(rec: Recording, config: ResolvedConfig, file: string): Promise<void> {
+  const replay = await replayFrames(rec, config);
+  const last = replay.frames[replay.frames.length - 1];
+  await mkdir(path.dirname(path.resolve(file)), { recursive: true });
+  await Bun.write(file, (last ? frameText(last) : []).join("\n") + "\n");
+}
+
 /**
  * Fan the configured outputs out to the right backend: `.svg` and `.html` are produced from the headless core
  * (no WebView, no ffmpeg); everything else goes through the WebView + ffmpeg renderer in one pass.
@@ -26,10 +37,15 @@ export async function renderOutputs(
 ): Promise<RenderResult> {
   const svg = config.output.filter((o) => kind(o) === "svg");
   const html = config.output.filter((o) => kind(o) === "html");
+  const txt = config.output.filter((o) => kind(o) === "txt");
   const raster = config.output.filter((o) => kind(o) === "raster");
 
   const result: RenderResult = { outputs: [], frames: 0, screenshots: [], durationSeconds: 0 };
 
+  for (const file of txt) {
+    await writeTxt(rec, config, file);
+    result.outputs.push(file);
+  }
   for (const file of svg) {
     await mkdir(path.dirname(path.resolve(file)), { recursive: true });
     const r = await writeSvg(rec, config, file);
@@ -47,6 +63,57 @@ export async function renderOutputs(
     result.frames = r.frames;
     result.screenshots.push(...r.screenshots);
     result.durationSeconds = r.durationSeconds;
+    if (r.notes) result.notes = r.notes;
   }
   return result;
 }
+
+/** "demo.mp4" + "-01-install" → "demo-01-install.mp4"; "frames/" → "frames-01-install/". */
+function suffixOutput(output: string, suffix: string): string {
+  if (output.endsWith("/")) return `${output.slice(0, -1)}${suffix}/`;
+  const ext = path.extname(output);
+  return `${output.slice(0, output.length - ext.length)}${suffix}${ext}`;
+}
+
+/**
+ * Render a part of the recording: a time window, a set of chapters, or every chapter as its own file.
+ * Cutting happens on the cast (see edit.ts), so every output format is supported.
+ */
+export async function renderSelection(
+  rec: Recording,
+  config: ResolvedConfig,
+  clip: ClipSelection | undefined,
+  onProgress?: (p: RenderProgress) => void,
+): Promise<RenderResult> {
+  if (!clip || (clip.from === undefined && clip.to === undefined && !clip.chapters && !clip.splitChapters)) {
+    return renderOutputs(rec, config, onProgress);
+  }
+  if (clip.splitChapters) {
+    let ranges = chapterRanges(rec, config);
+    if (clip.chapters) ranges = findChapters(ranges, clip.chapters);
+    if (ranges.length === 0) throw new Error("--split-chapters needs chapters: add `t.chapter(name)` calls to the script");
+    const total: RenderResult = { outputs: [], frames: 0, screenshots: [], durationSeconds: 0 };
+    for (const [i, range] of ranges.entries()) {
+      const part = cutRecording(rec, config, range);
+      const suffix = `-${chapterSlug(i, range.title)}`;
+      const r = await renderOutputs(part, { ...flattenedConfig(config), output: config.output.map((o) => suffixOutput(o, suffix)) }, onProgress);
+      total.outputs.push(...r.outputs);
+      total.frames += r.frames;
+      total.screenshots.push(...r.screenshots);
+      total.durationSeconds += r.durationSeconds;
+      if (r.notes) total.notes = [...(total.notes ?? []), ...r.notes];
+    }
+    return total;
+  }
+  let part = rec;
+  let partConfig = config;
+  if (clip.chapters) {
+    part = selectChapters(rec, config, clip.chapters);
+    partConfig = flattenedConfig(config);
+  }
+  if (clip.from !== undefined || clip.to !== undefined) {
+    part = cutRecording(part, partConfig, clip);
+    partConfig = flattenedConfig(partConfig);
+  }
+  return renderOutputs(part, partConfig, onProgress);
+}

package/src/renderer/encoder.ts

@@ -9,6 +9,8 @@ export interface FrameSink {
   readonly target: string;
   /** True for outputs that loop (GIF, WebP) — `loopOffset` applies to these. */
   readonly loops?: boolean;
+  /** True when this sink receives RGBA frames (transparent output). */
+  readonly alpha?: boolean;
 }
 
 type Format = "mp4" | "webm" | "gif" | "webp" | "png-sequence" | "png" | "jpeg";
@@ -40,11 +42,15 @@ export function detectFormat(output: string): Format {
 /** Still image of the final frame. PNG is written as-is; JPEG is transcoded with Bun.Image (no ffmpeg). */
 class StillSink implements FrameSink {
   private last: Uint8Array | null = null;
+  readonly alpha: boolean;
 
   constructor(
     readonly target: string,
     private format: "png" | "jpeg",
-  ) {}
+    alpha = false,
+  ) {
+    this.alpha = alpha && format === "png";
+  }
 
   async frame(png: Uint8Array): Promise<void> {
     this.last = png;
@@ -70,7 +76,7 @@ function ffmpegCandidates(): string[] {
     Bun.which("ffmpeg"),
     "/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg",
     "/usr/local/opt/ffmpeg-full/bin/ffmpeg",
-  ].filter((p): p is string => typeof p === "string" && p.length > 0);
+  ].filter((p): p is string => p !== undefined && p !== null && p.length > 0);
   return [...new Set(list)];
 }
 
@@ -121,12 +127,12 @@ export async function hasEncoder(...candidates: string[]): Promise<string | null
 
 type FfmpegFormat = Exclude<Format, "png-sequence" | "png" | "jpeg">;
 
-const REQUIRED_ENCODERS: Record<FfmpegFormat, { candidates: string[]; hint: string }> = {
+const REQUIRED_ENCODERS = {
   mp4: { candidates: ["libx264"], hint: "an ffmpeg build with libx264" },
   webm: { candidates: ["libvpx-vp9"], hint: "an ffmpeg build with libvpx" },
   gif: { candidates: ["gif"], hint: "an ffmpeg build with the gif encoder" },
   webp: { candidates: ["libwebp_anim", "libwebp"], hint: "an ffmpeg build with libwebp (Homebrew: `brew install ffmpeg-full`)" },
-};
+} satisfies Record<FfmpegFormat, { candidates: string[]; hint: string }>;
 
 async function requireEncoder(format: FfmpegFormat, output: string): Promise<EncoderMatch> {
   const { candidates, hint } = REQUIRED_ENCODERS[format];
@@ -156,10 +162,26 @@ export function chaptersMetadata(chapters: Chapter[], durationSeconds: number):
   return lines.join("\n") + "\n";
 }
 
-function ffmpegArgs(format: Format, fps: number, output: string, encoder: string, metadataFile?: string): string[] {
+function ffmpegArgs(format: Format, fps: number, output: string, encoder: string, metadataFile?: string, alpha = false): string[] {
   const input = ["-y", "-loglevel", "error", "-f", "image2pipe", "-framerate", String(fps), "-i", "pipe:0"];
   if (metadataFile && format === "mp4") input.push("-i", metadataFile, "-map_metadata", "1");
   const evenSize = "scale=trunc(iw/2)*2:trunc(ih/2)*2";
+  if (alpha && format === "webm") {
+    return [...input, "-vf", `${evenSize},format=yuva420p`, "-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-auto-alt-ref", "0", "-b:v", "0", "-crf", "30", "-row-mt", "1", output];
+  }
+  if (alpha && format === "gif") {
+    const gifFps = Math.min(fps, 50);
+    return [
+      ...input,
+      "-vf",
+      `fps=${gifFps},split[a][b];[a]palettegen=stats_mode=diff:reserve_transparent=1[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle:alpha_threshold=128`,
+      "-loop", "0",
+      output,
+    ];
+  }
+  if (alpha && format === "webp") {
+    return [...input, "-c:v", encoder, "-pix_fmt", "yuva420p", "-lossless", "0", "-q:v", "85", "-loop", "0", "-preset", "text", output];
+  }
   switch (format) {
     case "mp4":
       return [
@@ -191,11 +213,15 @@ function ffmpegArgs(format: Format, fps: number, output: string, encoder: string
   }
 }
 
+/** Formats whose container/codec can carry an alpha channel. */
+export const ALPHA_FORMATS = new Set<Format>(["webm", "gif", "webp", "png", "png-sequence"]);
+
 class FfmpegSink implements FrameSink {
   private proc: Subprocess<"pipe", "ignore", "pipe">;
   private stdin: FileSink;
   private stderr: Promise<string>;
   readonly loops: boolean;
+  readonly alpha: boolean;
 
   constructor(
     readonly target: string,
@@ -203,9 +229,11 @@ class FfmpegSink implements FrameSink {
     fps: number,
     match: EncoderMatch,
     metadataFile?: string,
+    alpha = false,
   ) {
     this.loops = format === "gif" || format === "webp";
-    this.proc = Bun.spawn([match.binary, ...ffmpegArgs(format, fps, target, match.encoder, metadataFile)], { stdin: "pipe", stdout: "ignore", stderr: "pipe" });
+    this.alpha = alpha && ALPHA_FORMATS.has(format);
+    this.proc = Bun.spawn([match.binary, ...ffmpegArgs(format, fps, target, match.encoder, metadataFile, this.alpha)], { stdin: "pipe", stdout: "ignore", stderr: "pipe" });
     this.stdin = this.proc.stdin;
     this.stderr = new Response(this.proc.stderr).text();
   }
@@ -229,7 +257,10 @@ class PngSequenceSink implements FrameSink {
   private index = 0;
   private pending: Promise<unknown>[] = [];
 
-  constructor(readonly target: string) {}
+  constructor(
+    readonly target: string,
+    readonly alpha = false,
+  ) {}
 
   async frame(png: Uint8Array): Promise<void> {
     const file = path.join(this.target, `frame-${String(this.index++).padStart(6, "0")}.png`);
@@ -254,7 +285,14 @@ export async function ensureFfmpeg(): Promise<void> {
   );
 }
 
-export async function createSinks(outputs: string[], fps: number, opts: { chapters?: Chapter[]; durationSeconds?: number } = {}): Promise<FrameSink[]> {
+export interface SinkOptions {
+  chapters?: Chapter[];
+  durationSeconds?: number;
+  /** Frames will be RGBA; sinks whose format supports it keep the alpha channel. */
+  alpha?: boolean;
+}
+
+export async function createSinks(outputs: string[], fps: number, opts: SinkOptions = {}): Promise<FrameSink[]> {
   const sinks: FrameSink[] = [];
   let metadataFile: string | undefined;
   if (opts.chapters && opts.chapters.length > 0) {
@@ -265,18 +303,18 @@ export async function createSinks(outputs: string[], fps: number, opts: { chapte
     const format = detectFormat(output);
     if (format === "png-sequence") {
       await mkdir(output, { recursive: true });
-      sinks.push(new PngSequenceSink(output));
+      sinks.push(new PngSequenceSink(output, opts.alpha === true));
       continue;
     }
     if (format === "png" || format === "jpeg") {
       await mkdir(path.dirname(path.resolve(output)), { recursive: true });
-      sinks.push(new StillSink(output, format));
+      sinks.push(new StillSink(output, format, opts.alpha === true));
       continue;
     }
     await ensureFfmpeg();
     const match = await requireEncoder(format as FfmpegFormat, output);
     await mkdir(path.dirname(path.resolve(output)), { recursive: true });
-    sinks.push(new FfmpegSink(output, format, fps, match, metadataFile));
+    sinks.push(new FfmpegSink(output, format, fps, match, metadataFile, opts.alpha === true));
   }
   return sinks;
 }