termcut 0.6.4 → 0.7.1

package/src/renderer/png.ts

@@ -0,0 +1,189 @@
+// A minimal PNG codec for the renderer. Bun.WebView screenshots come in as opaque PNGs and Bun.Image has no raw
+// pixel access, so transparent output needs its own decode → matte → encode step. 8-bit RGB/RGBA, non-interlaced.
+// node:zlib rather than Bun.inflateSync/deflateSync: PNG needs zlib-framed streams and Bun's defaults are raw deflate.
+import { deflateSync, inflateSync } from "node:zlib";
+
+/** Straight (non-premultiplied) RGBA pixels, row-major. */
+export interface RgbaImage {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+export type Rgb = [number, number, number];
+
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+const readU32 = (b: Uint8Array, o: number): number => ((b[o]! << 24) | (b[o + 1]! << 16) | (b[o + 2]! << 8) | b[o + 3]!) >>> 0;
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+const paeth = (a: number, b: number, c: number): number => {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+};
+
+/** Undo a PNG row filter in place; `prev` is the previous (already unfiltered) row. */
+function unfilter(filter: number, row: Uint8Array, prev: Uint8Array, bpp: number): void {
+  switch (filter) {
+    case 0:
+      return;
+    case 1:
+      for (let i = bpp; i < row.length; i++) row[i] = (row[i]! + row[i - bpp]!) & 0xff;
+      return;
+    case 2:
+      for (let i = 0; i < row.length; i++) row[i] = (row[i]! + prev[i]!) & 0xff;
+      return;
+    case 3:
+      for (let i = 0; i < row.length; i++) row[i] = (row[i]! + (((i >= bpp ? row[i - bpp]! : 0) + prev[i]!) >> 1)) & 0xff;
+      return;
+    case 4:
+      for (let i = 0; i < row.length; i++) row[i] = (row[i]! + paeth(i >= bpp ? row[i - bpp]! : 0, prev[i]!, i >= bpp ? prev[i - bpp]! : 0)) & 0xff;
+      return;
+    default:
+      throw new Error(`Unsupported PNG filter ${filter}`);
+  }
+}
+
+export function decodePng(png: Uint8Array): RgbaImage {
+  for (let i = 0; i < SIGNATURE.length; i++) if (png[i] !== SIGNATURE[i]) throw new Error("Not a PNG file");
+  let width = 0;
+  let height = 0;
+  let depth = 0;
+  let colorType = 0;
+  let interlace = 0;
+  const idat: Uint8Array[] = [];
+  for (let pos = 8; pos + 8 <= png.length; ) {
+    const length = readU32(png, pos);
+    const type = String.fromCharCode(png[pos + 4]!, png[pos + 5]!, png[pos + 6]!, png[pos + 7]!);
+    const data = png.subarray(pos + 8, pos + 8 + length);
+    if (type === "IHDR") {
+      width = readU32(data, 0);
+      height = readU32(data, 4);
+      depth = data[8]!;
+      colorType = data[9]!;
+      interlace = data[12]!;
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    pos += 12 + length;
+  }
+  if (depth !== 8 || (colorType !== 6 && colorType !== 2) || interlace !== 0) {
+    throw new Error(`Unsupported PNG layout (bit depth ${depth}, colour type ${colorType}, interlace ${interlace})`);
+  }
+  const bpp = colorType === 6 ? 4 : 3;
+  const stride = width * bpp;
+  const raw = inflateSync(concat(idat));
+  const out = new Uint8Array(width * height * 4);
+  let prev = new Uint8Array(stride);
+  let row = new Uint8Array(stride);
+  let p = 0;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[p++]!;
+    row.set(raw.subarray(p, p + stride));
+    p += stride;
+    unfilter(filter, row, prev, bpp);
+    const o = y * width * 4;
+    if (bpp === 4) out.set(row, o);
+    else {
+      for (let x = 0; x < width; x++) {
+        out[o + x * 4] = row[x * 3]!;
+        out[o + x * 4 + 1] = row[x * 3 + 1]!;
+        out[o + x * 4 + 2] = row[x * 3 + 2]!;
+        out[o + x * 4 + 3] = 255;
+      }
+    }
+    [prev, row] = [row, prev];
+  }
+  return { width, height, data: out };
+}
+
+const CRC_TABLE = new Uint32Array(256).map((_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+function crc32(bytes: Uint8Array): number {
+  let c = 0xffffffff;
+  for (const b of bytes) c = CRC_TABLE[(c ^ b) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type: string, data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(12 + data.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, data.length);
+  for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  view.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+  return out;
+}
+
+/** Encode straight RGBA as an 8-bit PNG (filter 0; speed matters more than size — ffmpeg re-encodes anyway). */
+export function encodePng(img: RgbaImage): Uint8Array {
+  const stride = img.width * 4;
+  const raw = new Uint8Array((stride + 1) * img.height);
+  for (let y = 0; y < img.height; y++) {
+    raw[y * (stride + 1)] = 0;
+    raw.set(img.data.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const v = new DataView(ihdr.buffer);
+  v.setUint32(0, img.width);
+  v.setUint32(4, img.height);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 6; // RGBA
+  return concat([new Uint8Array(SIGNATURE), chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw, { level: 1 })), chunk("IEND", new Uint8Array(0))]);
+}
+
+export function parseHex(color: string): Rgb {
+  const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(color.trim());
+  if (!m) throw new Error(`Expected a #RRGGBB colour, got "${color}"`);
+  return [parseInt(m[1]!, 16), parseInt(m[2]!, 16), parseInt(m[3]!, 16)];
+}
+
+/** Relative luminance (0–1) of an #RRGGBB colour — picks a contrasting second matte background. */
+export function luminance(color: string): number {
+  const [r, g, b] = parseHex(color);
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+
+/**
+ * Two-background matting: the same frame rendered over backgrounds `a` and `b` gives, per pixel,
+ * alpha = 1 − (Pb − Pa) / (b − a) and colour = (Pa − (1 − alpha)·a) / alpha. Exact for anti-aliased edges and
+ * soft shadows alike, which is why the renderer prefers this over a colour key.
+ */
+export function matte(onA: RgbaImage, onB: RgbaImage, a: Rgb, b: Rgb): RgbaImage {
+  if (onA.width !== onB.width || onA.height !== onB.height) throw new Error("matte: frame sizes differ");
+  const n = onA.width * onA.height;
+  const out = new Uint8Array(n * 4);
+  const usable = [0, 1, 2].filter((c) => a[c] !== b[c]);
+  if (usable.length === 0) throw new Error("matte: the two backgrounds must differ");
+  for (let i = 0; i < n; i++) {
+    const o = i * 4;
+    let alpha = 0;
+    for (const c of usable) alpha += 1 - (onB.data[o + c]! - onA.data[o + c]!) / (b[c]! - a[c]!);
+    alpha = Math.min(1, Math.max(0, alpha / usable.length));
+    if (alpha <= 0.002) {
+      out[o + 3] = 0;
+      continue;
+    }
+    for (let c = 0; c < 3; c++) {
+      const v = (onA.data[o + c]! - (1 - alpha) * a[c]!) / alpha;
+      out[o + c] = Math.min(255, Math.max(0, Math.round(v)));
+    }
+    out[o + 3] = Math.round(alpha * 255);
+  }
+  return { width: onA.width, height: onA.height, data: out };
+}

package/src/renderer/view.ts

@@ -0,0 +1,41 @@
+// One place that knows how to open a headless Bun.WebView on every platform.
+// macOS uses the system WebKit; everywhere else Bun drives Chrome/Chromium over the DevTools protocol.
+
+export interface ViewSize {
+  width: number;
+  height: number;
+}
+
+/** Chrome flags that make headless rendering work in containers and CI without changing what is drawn. */
+export function chromeArgs(): string[] {
+  const args = ["--force-device-scale-factor=1", "--hide-scrollbars", "--disable-dev-shm-usage"];
+  // Chrome refuses to start its sandbox as root (Docker, most CI runners); unprivileged users keep it.
+  if (process.getuid?.() === 0) args.push("--no-sandbox");
+  return args;
+}
+
+/** Which backend to use: WebKit on macOS unless TCUT_WEBVIEW=chrome, Chrome elsewhere. */
+export function webViewBackend(): Bun.WebView.Backend {
+  const forced = process.env.TCUT_WEBVIEW;
+  if (process.platform === "darwin" && forced !== "chrome") return "webkit";
+  return {
+    type: "chrome",
+    url: false, // always spawn our own headless Chrome; never attach to a user's running browser
+    argv: chromeArgs(),
+    stderr: process.env.TCUT_DEBUG_CHROME ? "inherit" : "ignore",
+    ...(process.env.BUN_CHROME_PATH && { path: process.env.BUN_CHROME_PATH }),
+  };
+}
+
+export function createWebView(size: ViewSize): Bun.WebView {
+  if (!Bun.WebView) throw new Error("Bun.WebView is not available in this Bun version. tcut needs Bun >= 1.4.");
+  try {
+    return new Bun.WebView({ ...size, backend: webViewBackend() });
+  } catch (cause) {
+    const hint =
+      process.platform === "darwin"
+        ? ""
+        : " Rendering pixels on Linux/Windows needs Chrome or Chromium on the PATH (or BUN_CHROME_PATH=/path/to/chrome); SVG, HTML and TXT output need no browser.";
+    throw new Error(`Could not start the headless browser: ${cause instanceof Error ? cause.message : String(cause)}.${hint}`, { cause });
+  }
+}

package/src/renderer/webview.ts

@@ -1,3 +1,4 @@
+import type { CellSize } from "../config";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { MARKER } from "../cast";
@@ -7,7 +8,9 @@ import { buildTimeline, withReinjection, type TimedEvent } from "../timeline";
 import { pageAssets } from "./bundle";
 import { createSinks, type Chapter } from "./encoder";
 import { chipBuilder } from "../keylabels";
-import { BROWSER_GAP, barHeight, renderHtml, themeOsc } from "./page";
+import { BROWSER_GAP, barHeight, opaqueFill, renderHtml, themeOsc } from "./page";
+import { decodePng, encodePng, luminance, matte, parseHex } from "./png";
+import { createWebView } from "./view";
 
 export interface RenderResult {
   outputs: string[];
@@ -15,6 +18,8 @@ export interface RenderResult {
   screenshots: string[];
   durationSeconds: number;
   chapters?: Chapter[];
+  /** Things worth telling the user (e.g. a format that cannot carry alpha). */
+  notes?: string[];
 }
 
 interface ZoomRect {
@@ -25,7 +30,7 @@ interface ZoomRect {
 }
 
 /** Grid region (inclusive rows/cols, padded by `padding` cells) → px rect relative to the terminal grid. */
-function zoomRect(spec: { rows?: [number, number]; cols?: [number, number]; padding?: number }, cols: number, rows: number, cell: { w: number; h: number }): ZoomRect {
+function zoomRect(spec: { rows?: [number, number]; cols?: [number, number]; padding?: number }, cols: number, rows: number, cell: CellSize): ZoomRect {
   const pad = spec.padding ?? 1;
   const r0 = Math.max(0, (spec.rows?.[0] ?? 0) - pad);
   const r1 = Math.min(rows - 1, (spec.rows?.[1] ?? rows - 1) + pad);
@@ -56,10 +61,6 @@ export async function render(
   config: ResolvedConfig,
   onProgress?: (p: RenderProgress) => void,
 ): Promise<RenderResult> {
-  if (typeof Bun.WebView !== "function") {
-    throw new Error("Bun.WebView is not available in this Bun version. tcut needs Bun >= 1.4.");
-  }
-
   const assets = await pageAssets();
   const html = renderHtml(config);
   const osc = themeOsc(config.theme);
@@ -77,6 +78,7 @@ export async function render(
       if (pathname === "/wterm.css") return new Response(assets.css, { headers: { "content-type": "text/css" } });
       if (pathname === "/ghostty-vt.wasm") return new Response(Bun.file(assets.wasmPath), { headers: { "content-type": "application/wasm" } });
       if (pathname === "/theme") return new Response(osc, { headers: { "content-type": "text/plain; charset=utf-8" } });
+      if (pathname === "/watermark" && config.watermark?.image) return new Response(Bun.file(path.resolve(config.watermark.image)));
       if (pathname.startsWith("/bframe/")) {
         const rel = decodeURIComponent(pathname.slice("/bframe/".length));
         if (rel.includes("..")) return new Response("forbidden", { status: 403 });
@@ -107,8 +109,16 @@ export async function render(
   const totalFrames = Math.max(1, Math.ceil(timeline.duration * fps) + 1);
   const blinkPeriod = config.cursor.period / 1000;
   const screenshots: string[] = [];
+  const notes: string[] = [];
+  // Transparent output: every dirty frame is shot twice, over the theme background and over a contrasting one,
+  // and the pair is matted into real RGBA (the WebView itself always composites onto an opaque page).
+  const transparent = config.marginFill === "transparent";
+  const fillA = opaqueFill(config);
+  const fillB = luminance(fillA) > 0.5 ? "#000000" : "#ffffff";
+  const rgbA = parseHex(fillA);
+  const rgbB = parseHex(fillB);
 
-  const view = new Bun.WebView({ width: 800, height: 600 });
+  const view = createWebView({ width: 800, height: 600 });
   try {
     await view.navigate(`http://127.0.0.1:${server.port}/`);
     for (let i = 0; i < 100; i++) {
@@ -126,7 +136,7 @@ export async function render(
     await view.evaluate(`window.__vt.boot(${JSON.stringify(boot)})`);
     if (!lite) await view.evaluate("window.__vt.writeUrl('/theme')");
 
-    const cell = (await view.evaluate("window.__vt.measure()")) as { w: number; h: number };
+    const cell = (await view.evaluate("window.__vt.measure()")) as CellSize;
     if (!cell || !(cell.w > 0) || !(cell.h > 0)) throw new Error("Could not measure terminal cell size");
 
     const termW = Math.ceil(rec.header.width * cell.w);
@@ -167,7 +177,11 @@ export async function render(
     await view.resize(width, height);
     await view.evaluate("new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))");
 
-    const sinks = await createSinks(config.output, fps, { chapters, durationSeconds: timeline.duration });
+    const sinks = await createSinks(config.output, fps, { chapters, durationSeconds: timeline.duration, alpha: transparent });
+    if (transparent) {
+      const opaque = sinks.filter((s) => !s.alpha).map((s) => path.basename(s.target));
+      if (opaque.length) notes.push(`${opaque.join(", ")}: this format has no alpha channel, so the theme background was used instead of transparency`);
+    }
     const cellPx = cell;
     const fullRect: ZoomRect = { x: 0, y: 0, w: termW, h: termH };
     let zoomFrom: ZoomRect | null = null;
@@ -179,10 +193,12 @@ export async function render(
     // loopOffset rotates the frame order for looping outputs; those frames are buffered and flushed at the end.
     const loopSinks = config.loopOffset ? sinks.filter((s) => s.loops) : [];
     const streamSinks = sinks.filter((s) => !loopSinks.includes(s));
-    const buffered: Uint8Array[] = [];
+    const buffered: Array<{ opaque: Uint8Array; alpha: Uint8Array }> = [];
     let pointer = 0;
     let lastPng: Uint8Array | null = null;
+    let lastAlphaPng: Uint8Array | null = null;
     let lastBlink: boolean | null = null;
+    const setFill = (color: string) => view.evaluate(`window.__vt.background(${JSON.stringify(color)})`);
 
     for (let frame = 0; frame < totalFrames; frame++) {
       const time = frame / fps;
@@ -253,26 +269,33 @@ export async function render(
       if (zoomChanged || chipsChanged) dirty = true;
       if (dirty) {
         lastPng = (await view.screenshot({ encoding: "buffer" })) as Uint8Array;
+        if (transparent) {
+          await setFill(fillB);
+          const onB = (await view.screenshot({ encoding: "buffer" })) as Uint8Array;
+          await setFill(fillA);
+          lastAlphaPng = encodePng(matte(decodePng(lastPng), decodePng(onB), rgbA, rgbB));
+        }
       }
+      const frameFor = (sink: { alpha?: boolean }): Uint8Array => (sink.alpha && lastAlphaPng ? lastAlphaPng : lastPng!);
 
       for (const shot of shots) {
         const file = shot.data.slice(MARKER.screenshot.length);
         await mkdir(path.dirname(path.resolve(file)), { recursive: true });
-        await Bun.write(file, lastPng!);
+        await Bun.write(file, lastAlphaPng ?? lastPng!);
         screenshots.push(file);
       }
 
-      for (const sink of streamSinks) await sink.frame(lastPng!);
-      if (loopSinks.length) buffered.push(lastPng!);
+      for (const sink of streamSinks) await sink.frame(frameFor(sink));
+      if (loopSinks.length) buffered.push({ opaque: lastPng!, alpha: lastAlphaPng ?? lastPng! });
       onProgress?.({ frame: frame + 1, total: totalFrames });
     }
 
     if (loopSinks.length) {
       const rotated = rotateFrames(buffered, loopOffsetFrames(buffered.length, config.loopOffset));
-      for (const png of rotated) for (const sink of loopSinks) await sink.frame(png);
+      for (const pair of rotated) for (const sink of loopSinks) await sink.frame(sink.alpha ? pair.alpha : pair.opaque);
     }
     for (const sink of sinks) await sink.finish();
-    return { outputs: sinks.map((s) => s.target), frames: totalFrames, screenshots, durationSeconds: timeline.duration, chapters };
+    return { outputs: sinks.map((s) => s.target), frames: totalFrames, screenshots, durationSeconds: timeline.duration, chapters, ...(notes.length && { notes }) };
   } finally {
     view.close();
     server.stop(true);

package/src/screen.ts

@@ -32,6 +32,12 @@ export async function loadCore(core: CoreName = "ghostty"): Promise<TerminalCore
  * Headless terminal model backed by libghostty (WASM). The recorder feeds every PTY chunk through it so
  * `wait()` / `expect()` / `run()` look at the actual screen instead of a raw byte stream.
  */
+/** Zero-based cursor cell. */
+export interface CursorPosition {
+  x: number;
+  y: number;
+}
+
 export class Screen {
   private listeners = new Set<() => void>();
   onResponse: ((data: string) => void) | undefined;
@@ -47,8 +53,8 @@ export class Screen {
   }
 
   write(data: string | Uint8Array): void {
-    if (typeof data === "string") this.core.writeString(data);
-    else this.core.writeRaw(data);
+    if (data instanceof Uint8Array) this.core.writeRaw(data);
+    else this.core.writeString(data);
     this.drainResponses();
     for (const listener of this.listeners) listener();
   }
@@ -87,7 +93,7 @@ export class Screen {
     return this.core.getRows();
   }
 
-  cursor(): { x: number; y: number } {
+  cursor(): CursorPosition {
     const c = this.core.getCursor();
     return { x: c.col, y: c.row };
   }

package/src/scriptgen.ts

@@ -23,28 +23,28 @@ type Op =
   | { kind: "raw"; data: string }
   | { kind: "sleep"; ms: number };
 
-const NAMED: Record<string, string> = {
-  "\r": "enter",
-  "\n": "enter",
-  "\t": "tab",
-  "\x7f": "backspace",
-  "\x1b": "escape",
-  "\x1b[A": "up",
-  "\x1b[B": "down",
-  "\x1b[C": "right",
-  "\x1b[D": "left",
-  "\x1bOA": "up",
-  "\x1bOB": "down",
-  "\x1bOC": "right",
-  "\x1bOD": "left",
-  "\x1b[H": "home",
-  "\x1b[F": "end",
-  "\x1b[1~": "home",
-  "\x1b[4~": "end",
-  "\x1b[3~": "delete",
-  "\x1b[5~": "pageUp",
-  "\x1b[6~": "pageDown",
-};
+const NAMED = new Map<string, string>([
+  ["\r", "enter"],
+  ["\n", "enter"],
+  ["\t", "tab"],
+  ["\x7f", "backspace"],
+  ["\x1b", "escape"],
+  ["\x1b[A", "up"],
+  ["\x1b[B", "down"],
+  ["\x1b[C", "right"],
+  ["\x1b[D", "left"],
+  ["\x1bOA", "up"],
+  ["\x1bOB", "down"],
+  ["\x1bOC", "right"],
+  ["\x1bOD", "left"],
+  ["\x1b[H", "home"],
+  ["\x1b[F", "end"],
+  ["\x1b[1~", "home"],
+  ["\x1b[4~", "end"],
+  ["\x1b[3~", "delete"],
+  ["\x1b[5~", "pageUp"],
+  ["\x1b[6~", "pageDown"],
+]);
 
 /** Split a raw input chunk into individual key tokens (escape sequences, control chars, printable runs). */
 export function tokenize(input: string): string[] {
@@ -53,15 +53,16 @@ export function tokenize(input: string): string[] {
   while (i < input.length) {
     const ch = input[i]!;
     if (ch === "\x1b") {
-      // CSI: ESC [ params final  |  SS3: ESC O x  |  Alt+key: ESC x
-      const csi = /^\x1b\[[0-9;?]*[A-Za-z~]/.exec(input.slice(i));
-      const ss3 = /^\x1bO[A-Za-z]/.exec(input.slice(i));
+      // CSI: ESC [ params final  |  SS3: ESC O x  |  Alt+key: ESC x  (matched after the ESC we already hold)
+      const rest = input.slice(i + 1);
+      const csi = /^\[[0-9;?]*[A-Za-z~]/.exec(rest);
+      const ss3 = /^O[A-Za-z]/.exec(rest);
       if (csi) {
-        tokens.push(csi[0]);
-        i += csi[0].length;
+        tokens.push(ch + csi[0]);
+        i += csi[0].length + 1;
       } else if (ss3) {
-        tokens.push(ss3[0]);
-        i += ss3[0].length;
+        tokens.push(ch + ss3[0]);
+        i += ss3[0].length + 1;
       } else if (i + 1 < input.length) {
         tokens.push(input.slice(i, i + 2));
         i += 2;
@@ -139,7 +140,7 @@ export function eventsToOps(rec: Recording, opts: ScriptGenOptions): Op[] {
         pendingText += token;
         continue;
       }
-      const named = NAMED[token];
+      const named = NAMED.get(token);
       if (named === "enter") {
         if (opts.cleanShell && pendingText.trim()) {
           const command = pendingText;

package/src/themes.ts

@@ -134,7 +134,7 @@ export type BuiltinThemeName = keyof typeof builtinThemes;
 const generated = generatedJson as Record<string, Theme>;
 
 /** All themes by slug: the generated bundle, with the built-ins overriding colliding names. */
-export const themes: Record<string, Theme> = { ...generated, ...builtinThemes };
+export const themes = Object.assign({}, generated, builtinThemes);
 
 export const themeNames: string[] = Object.keys(themes).sort();
 
@@ -153,15 +153,13 @@ export function findThemes(query: string): string[] {
 
 export function resolveTheme(theme: ThemeName | Theme | undefined): Theme {
   if (!theme) return builtinThemes["catppuccin-mocha"];
-  if (typeof theme === "string") {
-    const found = themes[themeSlug(theme)];
-    if (!found) {
-      const near = findThemes(theme.split(/[\s-]+/)[0] ?? theme).slice(0, 5);
-      throw new Error(
-        `Unknown theme "${theme}". ${near.length ? `Did you mean: ${near.join(", ")}?` : ""} Run \`tcut themes [query]\` to list all ${themeNames.length}.`.trim(),
-      );
-    }
-    return found;
+  if (theme instanceof Object) return theme; // an inline Theme object
+  const found = themes[themeSlug(theme)];
+  if (!found) {
+    const near = findThemes(theme.split(/[\s-]+/)[0] ?? theme).slice(0, 5);
+    throw new Error(
+      `Unknown theme "${theme}". ${near.length ? `Did you mean: ${near.join(", ")}?` : ""} Run \`tcut themes [query]\` to list all ${themeNames.length}.`.trim(),
+    );
   }
-  return theme;
+  return found;
 }

package/src/timeline.ts

@@ -21,14 +21,25 @@ export interface TimelineOptions {
 }
 
 /**
- * Collapse hidden intervals, apply playback speed, optionally cap idle gaps. Hidden events keep their relative
- * order but all land on the instant the hide started, so the first visible frame after `show` reflects their
- * combined effect. Input (`i`) events are dropped unless `keepInput`: the PTY already echoed them.
+ * Collapse hidden intervals, apply playback speed (global and per `speed:` segment), optionally cap idle gaps.
+ * Hidden events keep their relative order but all land on the instant the hide started, so the first visible
+ * frame after `show` reflects their combined effect. Input (`i`) events are dropped unless `keepInput`: the PTY
+ * already echoed them.
  */
 export function buildTimeline(events: CastEvent[], playbackSpeed: number, opts: TimelineOptions = {}): Timeline {
   const out: TimedEvent[] = [];
   let hiddenSince: number | null = null;
   let removed = 0;
+  // Visible time accumulates per segment: (collapsed time since the last event) / (global × segment speed).
+  let segmentSpeed = 1;
+  let lastCollapsed = 0;
+  let vt = 0;
+  const advance = (t: number): number => {
+    const collapsed = hiddenSince === null ? t - removed : hiddenSince - removed;
+    vt += Math.max(0, collapsed - lastCollapsed) / (playbackSpeed * segmentSpeed);
+    lastCollapsed = collapsed;
+    return vt;
+  };
 
   for (const [t, type, data] of events) {
     if (type === "m" && data === MARKER.hide) {
@@ -42,9 +53,14 @@ export function buildTimeline(events: CastEvent[], playbackSpeed: number, opts:
       }
       continue;
     }
+    if (type === "m" && data.startsWith(MARKER.speed)) {
+      advance(t);
+      const speed = Number(data.slice(MARKER.speed.length));
+      segmentSpeed = Number.isFinite(speed) && speed > 0 ? speed : 1;
+      continue;
+    }
     if (type === "i" && !opts.keepInput) continue;
-    const visible = hiddenSince === null ? t - removed : hiddenSince - removed;
-    out.push({ vt: visible / playbackSpeed, type, data });
+    out.push({ vt: advance(t), type, data });
   }
 
   if (opts.maxPause !== undefined && opts.maxPause >= 0) {