termcut 0.7.2 → 0.8.0

package/README.md

@@ -51,7 +51,11 @@ defineVideo({ output: "demo.mp4", browser: { position: "overlay" } }, async (t)
 });
 ```
 
-Polish: `shadow: true`, `watermark: "© you"`, `marginFill: "transparent"` (real alpha in PNG/WebP/GIF/WebM/SVG), `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. `tcut diff a.cast b.cast` catches output changes in CI.
+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.
+
+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.
+
+Test and inspect: `tcut diff a.cast b.cast` catches output changes in CI, `t.expect(/…/, { scope: "scrollback" })` checks output that scrolled away (`-o demo.log` writes the whole transcript), and `tcut doctor demo.cast` tells you what a recording used — and what can't be rendered (inline images).
 
 Cut and join without re-recording — on the cast, so every format works:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.7.2",
+  "version": "0.8.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/browser.ts

@@ -48,10 +48,18 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
   // Sampling starts once a page has loaded: headless Chrome never resolves a screenshot of the initial blank
   // view, and a hung screenshot blocks every later command on that view.
   let loaded = false;
-  /** Extra time allowed while the browser has never answered: a cold Chrome on a CI runner can take ~20 s to come up. */
-  const STARTUP_GRACE = 20_000;
+  /** Extra time allowed while the browser has never answered: a cold Chrome on a fresh Windows runner can take 20–40 s. */
+  const STARTUP_GRACE = 45_000;
   const startedAt = performance.now();
-  const startupDeadline = (deadline: number): number => (loaded ? deadline : Math.max(deadline, startedAt + STARTUP_GRACE));
+  let startupNoted = false;
+  const startupDeadline = (deadline: number): number => {
+    if (loaded) return deadline;
+    if (!startupNoted && performance.now() > startedAt + 5000) {
+      startupNoted = true;
+      log("waiting for the browser to start…");
+    }
+    return Math.max(deadline, startedAt + STARTUP_GRACE);
+  };
   // A view runs one evaluate() at a time; goto's probes, waitFor and the script's own evaluate calls take turns.
   let chain: Promise<unknown> = Promise.resolve();
   const serial = <T,>(fn: () => Promise<T>): Promise<T> => {
@@ -89,6 +97,11 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
     })();
     return sampling;
   };
+  /** A sample taken after this moment: waits out any in-flight screenshot (seconds on a cold Chrome), then takes a fresh one. */
+  const sampleNow = async (): Promise<void> => {
+    if (sampling) await sampling;
+    await sampleOnce();
+  };
   const sampler = (async () => {
     while (running) {
       await sampleOnce();
@@ -153,7 +166,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
         const text = String((await evaluate("document.body ? document.body.innerText : ''", 5000, "waitFor").catch(() => "")) ?? "");
         if (regex.test(text)) {
           loaded = true; // a page that answers is a page worth sampling, even if navigate() has not settled yet
-          await sampleOnce(); // the frame the script waited for, captured the moment it appeared
+          await sampleNow(); // the frame the script waited for, captured the moment it appeared
           return;
         }
         if (performance.now() > startupDeadline(deadline)) throw new WaitTimeoutError(`${regex} in the browser page`, timeout, text.slice(0, 2000));
@@ -178,7 +191,7 @@ export function startBrowserCapture(config: ResolvedConfig, stamp: () => number,
       if (!loaded && bcfg.url) await evaluate("document.readyState", 2000, "probe").catch(() => undefined); // marks loaded if the page answers
       running = false;
       await sampler;
-      await sampleOnce(); // final state of the page
+      await sampleNow(); // final state of the page
       try {
         view.close();
       } catch {

package/src/cli.ts

@@ -8,6 +8,7 @@ import * as api from "./index";
 import { recordLive } from "./live";
 import { ensurePublicBucket, loadPublishConfig, publicUrlFor, publishFiles, savePublishConfig, type PublishConfig, type Published } from "./publish";
 import { diffCasts, type DiffResult } from "./diff";
+import { diagnoseCast, formatDoctorReport, type DoctorReport } from "./doctor";
 import { toMs } from "./duration";
 import { concatRecordings, cutRecording, flattenedConfig, rebaseBrowserFrames, recordingDuration, selectChapters } from "./edit";
 import { presetNames, type PresetName } from "./presets";
@@ -15,7 +16,7 @@ import { renderOutputs } from "./render";
 import { generateScript } from "./scriptgen";
 import { runScriptTests, type TestSummary } from "./testing";
 import { findThemes, themeNames } from "./themes";
-import type { BrowserConfig, ClipSelection, CoreName, ThemeName, VideoConfig, WindowBar } from "./types";
+import type { BrowserConfig, ClipSelection, CoreName, Recording, ResolvedConfig, ThemeName, VideoConfig, WindowBar } from "./types";
 import { Video, attachBrowserFrames, castConfig, isVideo, renderCast } from "./video";
 
 // Let user scripts `import { defineVideo } from "tcut"` (or "termcut", the npm package name) regardless of
@@ -39,6 +40,7 @@ Usage:
   tcut render <file.cast> [options]   render an existing .cast (tcut or asciinema)
   tcut test <path...>                 run scripts in fast mode as tests (no video)
   tcut diff <a.cast> <b.cast>         compare what two recordings show on screen (exit 1 if different)
+  tcut doctor <file.cast>             what the program used, and what tcut cannot show (images, unknown sequences)
   tcut cut <file.cast> --from 2s --to 10s [--cast out.cast] [-o …]   keep part of a recording (by time or --chapters)
   tcut concat <a.cast> <b.cast…> [--gap 500ms] [--cast out.cast] [-o …]   join recordings end to end
   tcut publish <files...> [--open]    upload to your S3-compatible bucket and print share links
@@ -162,6 +164,7 @@ type CliReport =
   | { cast: string; cached: boolean; outputs: OutputFile[]; frames: number; durationSeconds: number }
   | { cast: string; events: number; durationSeconds: number; outputs: OutputFile[] }
   | DiffResult
+  | DoctorReport
   | TestSummary;
 
 /** With --json, the only thing on stdout is one JSON document (results or { error }). */
@@ -515,6 +518,13 @@ async function main(): Promise<void> {
       emit({ cast: rest[0], outputs: files, frames: result.frames, durationSeconds: result.durationSeconds });
       return;
     }
+    case "doctor": {
+      if (!rest[0]) fail("doctor needs a .cast file");
+      const report = await diagnoseCast(rest[0]);
+      if (!json) for (const line of formatDoctorReport(report)) console.log(line);
+      emit(report);
+      return;
+    }
     case "cut":
     case "concat": {
       const joining = first === "concat";
@@ -524,13 +534,13 @@ async function main(): Promise<void> {
       const castOut = values.cast ?? (joining ? path.join(path.dirname(rest[0]!), "concat.cast") : rest[0]!.replace(/\.cast$/, "") + "-cut.cast");
       const overrides = overridesFromFlags();
       delete overrides.cast;
-      const parts: Array<{ rec: Awaited<ReturnType<typeof readCast>>; config: ReturnType<typeof castConfig> }> = [];
+      const parts: Array<{ rec: Recording; config: ResolvedConfig }> = [];
       for (const [i, file] of rest.entries()) {
         const rec = await readCast(file);
         const config = applyOverrides(castConfig(rec, file, values.output), overrides);
         parts.push({ rec: await rebaseBrowserFrames(rec, file, castOut, joining ? `${i}-` : ""), config });
       }
-      let out: Awaited<ReturnType<typeof readCast>>;
+      let out: Recording;
       if (joining) {
         out = concatRecordings(parts, { gap: seconds("gap") ?? 0 });
       } else {

package/src/config.ts

@@ -114,6 +114,7 @@ export function resolveConfig(input: VideoConfig): ResolvedConfig {
     quantize: config.quantize ?? false,
     core: config.core ?? "ghostty",
     cache: config.cache ?? true,
+    requires: config.requires ?? [],
     font,
     theme,
     cursor: {

package/src/doctor.ts

@@ -0,0 +1,150 @@
+// `tcut doctor`: replay a cast through the emulator and report what the program used — and what tcut cannot show.
+import { MARKER, readCast } from "./cast";
+import { unsupportedProtocols, extractTitles, type UnsupportedProtocol } from "./osc";
+import { loadCore } from "./screen";
+import type { Recording } from "./types";
+
+export interface UnhandledSequenceSummary {
+  /** Final byte of the CSI/ESC sequence, e.g. "h". */
+  final: string;
+  count: number;
+}
+
+export interface DoctorReport {
+  cast: string;
+  cols: number;
+  rows: number;
+  durationSeconds: number;
+  events: number;
+  outputBytes: number;
+  /** Terminal features the program used. */
+  features: {
+    altScreen: boolean;
+    mouseTracking: boolean;
+    bracketedPaste: boolean;
+    appCursorKeys: boolean;
+    synchronizedOutput: boolean;
+    hyperlinks: number;
+    scrollbackLines: number;
+    titles: string[];
+  };
+  markers: { chapters: number; zoom: number; hidden: number; screenshots: number; browserFrames: number };
+  /** Things tcut cannot render faithfully. */
+  unsupported: UnsupportedProtocol[];
+  /** Escape sequences the lightweight core did not understand (the Ghostty core handles more but does not report). */
+  unhandled: UnhandledSequenceSummary[];
+  warnings: string[];
+}
+
+function unhandledSummary(seqs: Array<{ final: string }>): UnhandledSequenceSummary[] {
+  const counts = new Map<string, number>();
+  for (const s of seqs) counts.set(s.final, (counts.get(s.final) ?? 0) + 1);
+  return [...counts.entries()].map(([final, count]) => ({ final, count })).sort((a, b) => b.count - a.count);
+}
+
+export async function diagnoseRecording(rec: Recording, castPath = rec.source ?? "(memory)"): Promise<DoctorReport> {
+  const output = rec.events.filter((e) => e[1] === "o").map((e) => e[2]);
+  const outputText = output.join("");
+  // "Ever used" must not depend on state sampling: a mode entered and left inside one chunk still counts.
+  const requested = (code: string): boolean => outputText.includes(`\x1b[?${code}h`);
+  const links = new Set<string>();
+  const titles: string[] = [];
+  let altScreen = false;
+  let mouse = false;
+  let paste = false;
+  let appCursor = false;
+  let sync = false;
+
+  // Ghostty (the default renderer core) for feature detection, sampled after every output chunk.
+  const core = await loadCore("ghostty");
+  core.init(rec.header.width, rec.header.height);
+  for (const [, type, data] of rec.events) {
+    if (type === "r") {
+      const [c, r] = data.split("x").map(Number);
+      if (c! > 0 && r! > 0) core.resize(c!, r!);
+      continue;
+    }
+    if (type !== "o") continue;
+    core.writeString(data);
+    for (const t of extractTitles(data)) if (titles[titles.length - 1] !== t) titles.push(t);
+    altScreen ||= core.usingAltScreen() || requested("1049") || requested("47");
+    mouse ||= (core.mouseTracking?.() ?? 0) !== 0 || requested("1000") || requested("1002") || requested("1003");
+    paste ||= core.bracketedPaste() || requested("2004");
+    appCursor ||= core.cursorKeysApp() || requested("1");
+    sync ||= (core.synchronizedOutput?.() ?? false) || requested("2026");
+    for (let y = 0; y < core.getRows(); y++) {
+      for (let x = 0; x < core.getCols(); x++) {
+        const uri = core.getCell(y, x).linkUri;
+        if (uri) links.add(uri);
+      }
+    }
+  }
+  // The lightweight core reports sequences it does not implement.
+  const lite = await loadCore("lite");
+  lite.init(rec.header.width, rec.header.height);
+  for (const chunk of output) lite.writeString(chunk);
+  const unhandled = unhandledSummary(lite.getUnhandledSequences());
+
+  const markers = {
+    chapters: rec.events.filter((e) => e[1] === "m" && e[2].startsWith(MARKER.chapter)).length,
+    zoom: rec.events.filter((e) => e[1] === "m" && e[2].startsWith(MARKER.zoom)).length,
+    hidden: rec.events.filter((e) => e[1] === "m" && e[2] === MARKER.hide).length,
+    screenshots: rec.events.filter((e) => e[1] === "m" && e[2].startsWith(MARKER.screenshot)).length,
+    browserFrames: rec.events.filter((e) => e[1] === "b").length,
+  };
+  const unsupported = unsupportedProtocols(outputText); // shown on their own report lines; not repeated as warnings
+  const warnings: string[] = [];
+  if (altScreen && rec.events.some((e) => e[1] === "o" && e[2].includes("\x1b[?1049l"))) {
+    warnings.push("A full-screen program exited; text it left on the primary screen is normal — use t.hide(() => t.clear()) to tidy the video");
+  }
+  if (mouse) warnings.push("The program enabled mouse tracking: t.scrollUp()/scrollDown() work here");
+  if (!rec.header.bunVideo) warnings.push("No tcut config in the header (foreign asciicast): rendering uses defaults unless you pass --theme/--cols/--rows");
+
+  const duration = rec.header.duration ?? (rec.events.length ? rec.events[rec.events.length - 1]![0] : 0);
+  return {
+    cast: castPath,
+    cols: rec.header.width,
+    rows: rec.header.height,
+    durationSeconds: Number(duration.toFixed(3)),
+    events: rec.events.length,
+    outputBytes: new TextEncoder().encode(outputText).length,
+    features: {
+      altScreen,
+      mouseTracking: mouse,
+      bracketedPaste: paste,
+      appCursorKeys: appCursor,
+      synchronizedOutput: sync,
+      hyperlinks: links.size,
+      scrollbackLines: core.getScrollbackCount(),
+      titles,
+    },
+    markers,
+    unsupported,
+    unhandled,
+    warnings,
+  };
+}
+
+export async function diagnoseCast(file: string): Promise<DoctorReport> {
+  const rec = await readCast(file);
+  return diagnoseRecording(rec, file);
+}
+
+/** Human-readable report lines. */
+export function formatDoctorReport(r: DoctorReport): string[] {
+  const yes = (b: boolean) => (b ? "yes" : "no");
+  const lines = [
+    `${r.cast}: ${r.cols}×${r.rows}, ${r.durationSeconds.toFixed(1)}s, ${r.events} events, ${(r.outputBytes / 1024).toFixed(1)} KB of output`,
+    `features: alt screen ${yes(r.features.altScreen)} · mouse ${yes(r.features.mouseTracking)} · bracketed paste ${yes(r.features.bracketedPaste)} · app cursor keys ${yes(r.features.appCursorKeys)} · synchronized output ${yes(r.features.synchronizedOutput)} · ${r.features.hyperlinks} hyperlink(s) · ${r.features.scrollbackLines} scrollback line(s)`,
+  ];
+  if (r.features.titles.length) lines.push(`titles: ${r.features.titles.map((t) => JSON.stringify(t)).join(" → ")}`);
+  const m = r.markers;
+  if (m.chapters || m.zoom || m.hidden || m.screenshots || m.browserFrames) {
+    lines.push(`markers: ${m.chapters} chapter(s) · ${m.zoom} zoom · ${m.hidden} hidden section(s) · ${m.screenshots} screenshot(s) · ${m.browserFrames} browser frame(s)`);
+  }
+  for (const u of r.unsupported) lines.push(`unsupported: ${u.name} ×${u.count} — ${u.note}`);
+  if (r.unhandled.length) lines.push(`unhandled by the lite core: ${r.unhandled.map((u) => `${JSON.stringify(u.final)} ×${u.count}`).join(", ")} (use core: "ghostty", the default, for these)`);
+  for (const w of r.warnings) lines.push(`note: ${w}`);
+  if (!r.unsupported.length && !r.unhandled.length) lines.push("ok: nothing in this recording that tcut cannot show");
+  return lines;
+}

package/src/errors.ts

@@ -7,6 +7,16 @@ export class WaitTimeoutError extends Error {
   }
 }
 
+/** A program named in `requires` is not on the PATH — raised before the shell is even started. */
+export class MissingRequirementError extends Error {
+  constructor(readonly missing: string[]) {
+    super(
+      `${missing.length === 1 ? `\`${missing[0]}\` is` : `${missing.map((m) => `\`${m}\``).join(", ")} are`} not on the PATH. Install ${missing.length === 1 ? "it" : "them"}, or remove ${missing.length === 1 ? "it" : "them"} from \`requires\`.`,
+    );
+    this.name = "MissingRequirementError";
+  }
+}
+
 export class ExpectationError extends Error {
   constructor(what: string, screen: string) {
     super(`Expected ${what} to match.\n\n--- screen ---\n${screen}\n--------------`);

package/src/export/frames.ts

@@ -1,6 +1,7 @@
 import type { CellData, TerminalCore } from "@wterm/core";
+import { extractTitle } from "../osc";
 import { themeOsc } from "../renderer/page";
-import { loadCore } from "../screen";
+import { loadCore, scrollbackLines } from "../screen";
 import { buildTimeline, withReinjection } from "../timeline";
 import type { Recording, ResolvedConfig, Theme } from "../types";
 
@@ -22,6 +23,8 @@ export interface GridCell {
   fg: string | null;
   bg: string | null;
   flags: number;
+  /** OSC 8 hyperlink target, if the cell is inside one. */
+  link: string | null;
 }
 
 export interface GridFrame {
@@ -52,6 +55,10 @@ export interface GridReplay {
   duration: number;
   cols: number;
   rows: number;
+  /** Last window title the program set (OSC 0/2), if any. */
+  title: string | null;
+  /** Everything shown: scrollback lines followed by the final screen. */
+  transcript: string[];
 }
 
 const ANSI: (keyof Theme)[] = [
@@ -84,7 +91,7 @@ function toGridCell(cell: CellData, theme: Theme): GridCell {
     [fg, bg] = [bg ?? theme.background, fg ?? theme.foreground];
   }
   const text = cell.chars ?? (cell.char === 0 ? " " : String.fromCodePoint(cell.char));
-  return { text, width: cell.width === 2 ? 2 : 1, fg, bg, flags: cell.flags & ~FLAG.reverse };
+  return { text, width: cell.width === 2 ? 2 : 1, fg, bg, flags: cell.flags & ~FLAG.reverse, link: cell.linkUri ?? null };
 }
 
 interface ScreenSnapshot {
@@ -109,7 +116,7 @@ function snapshot(core: TerminalCore, theme: Theme): ScreenSnapshot {
     }
     if (meaningful) {
       rows.set(y, cells);
-      keyParts.push(`${y}:${cells.map((c) => `${c.text}${c.fg ?? ""}${c.bg ?? ""}${c.flags}`).join("")}`);
+      keyParts.push(`${y}:${cells.map((c) => `${c.text}${c.fg ?? ""}${c.bg ?? ""}${c.flags}${c.link ?? ""}`).join("")}`);
     }
   }
   return { rows, key: keyParts.join("\n") };
@@ -133,17 +140,31 @@ export async function replayFrames(rec: Recording, config: ResolvedConfig): Prom
   const frames: GridFrame[] = [];
   let pointer = 0;
   let lastKey: string | null = null;
+  let title: string | null = null;
+  // Synchronized output (mode 2026): while a program is mid-update, keep showing the previous frame — bounded,
+  // so a block that is never closed cannot freeze the video.
+  const maxHeld = Math.ceil(fps / 2);
+  let held = 0;
 
   for (let i = 0; i < totalFrames; i++) {
     const time = i / fps;
     while (pointer < events.length && events[pointer]!.vt <= time + 1e-9) {
       const e = events[pointer++]!;
-      if (e.type === "o") core.writeString(e.data);
-      else if (e.type === "r") {
+      if (e.type === "o") {
+        core.writeString(e.data);
+        const t = extractTitle(e.data);
+        if (t !== null) title = t;
+      } else if (e.type === "r") {
         const [c, r] = e.data.split("x").map(Number);
         if (c! > 0 && r! > 0) core.resize(c!, r!);
       }
     }
+    if (frames.length > 0 && held < maxHeld && core.synchronizedOutput?.()) {
+      held += 1;
+      frames[frames.length - 1]!.hold += 1 / fps;
+      continue;
+    }
+    held = 0;
     const cursor = core.getCursor();
     const { rows, key } = snapshot(core, config.theme);
     const fullKey = `${key}|${cursor.row},${cursor.col},${cursor.visible}|${core.getCols()}x${core.getRows()}`;
@@ -155,5 +176,7 @@ export async function replayFrames(rec: Recording, config: ResolvedConfig): Prom
     frames.push({ time, hold: 1 / fps, cols: core.getCols(), rows: core.getRows(), rows_: rows, cursor });
   }
 
-  return { frames, duration: totalFrames / fps, cols: rec.header.width, rows: rec.header.height };
+  const last = frames[frames.length - 1];
+  const transcript = [...scrollbackLines(core), ...(last ? frameText(last) : [])];
+  return { frames, duration: totalFrames / fps, cols: rec.header.width, rows: rec.header.height, title, transcript };
 }

package/src/export/html.ts

@@ -20,7 +20,7 @@ function windowBar(config: ResolvedConfig): string {
   const right = config.windowBar.endsWith("Right");
   const dot = (c: string) => `<span class="dot" style="${rings ? `border:2px solid ${c}` : `background:${c}`}"></span>`;
   const dots = `<div class="dots">${dot("#ff5f57")}${dot("#febc2e")}${dot("#28c840")}</div>`;
-  const title = `<div class="title">${escapeHtml(config.title)}</div>`;
+  const title = `<div class="title">${escapeHtml(config.title === "auto" ? "" : config.title)}</div>`;
   return `<div id="bar" class="${right ? "right" : ""}">${right ? title + dots : dots + title}</div>`;
 }
 
@@ -36,6 +36,7 @@ export async function buildHtml(rec: Recording, config: ResolvedConfig): Promise
     rows: rec.header.height,
     duration,
     speed: 1,
+    autoTitle: config.title === "auto",
     events: events.filter((e) => e.type === "o" || e.type === "r").map(({ vt, type, data }) => ({ vt, type, data })),
   };
   // "</script>" inside the JSON would terminate the data block; escape it.

package/src/export/svg.ts

@@ -54,7 +54,7 @@ export function svgGeometry(config: ResolvedConfig, cols: number, rows: number):
   };
 }
 
-function windowBar(config: ResolvedConfig, g: Geometry): string {
+function windowBar(config: ResolvedConfig, g: Geometry, title: string): string {
   if (config.windowBar === "none") return "";
   const rings = config.windowBar.startsWith("rings");
   const right = config.windowBar.endsWith("Right");
@@ -64,10 +64,10 @@ function windowBar(config: ResolvedConfig, g: Geometry): string {
   const dots = colors
     .map((c, i) => `<circle cx="${num(startX + i * 20)}" cy="${num(y)}" r="6" ${rings ? `fill="none" stroke="${c}" stroke-width="2"` : `fill="${c}"`}/>`)
     .join("");
-  const title = config.title
-    ? `<text x="${num(g.frameX + g.frameW / 2)}" y="${num(y + 4)}" text-anchor="middle" font-family="-apple-system, Segoe UI, Helvetica, Arial, sans-serif" font-size="13" fill="${config.theme.foreground}" opacity="0.7">${esc(config.title)}</text>`
+  const titleText = title
+    ? `<text x="${num(g.frameX + g.frameW / 2)}" y="${num(y + 4)}" text-anchor="middle" font-family="-apple-system, Segoe UI, Helvetica, Arial, sans-serif" font-size="13" fill="${config.theme.foreground}" opacity="0.7">${esc(title)}</text>`
     : "";
-  return dots + title;
+  return dots + titleText;
 }
 
 function styleAttrs(cell: GridCell, defaultFg: string): string {
@@ -103,22 +103,27 @@ function frameMarkup(frame: GridFrame, config: ResolvedConfig, g: Geometry): str
     }
     flushBg(x);
 
-    // Text runs with identical style
+    // Text runs with identical style (and link); OSC 8 links become real <a> elements
     const spans: string[] = [];
     x = 0;
-    let run: { x: number; text: string; style: string } | null = null;
+    let run: { x: number; text: string; style: string; link: string | null } | null = null;
+    const flushRun = () => {
+      if (!run || !run.text.trim()) return;
+      const span = `<tspan x="${num(run.x * g.cellW)}"${run.style}>${esc(run.text.replace(/\s+$/, ""))}</tspan>`;
+      spans.push(run.link ? `<a href="${esc(run.link)}">${span}</a>` : span);
+    };
     for (const cell of cells) {
       const blank = cell.text === " " && !(cell.flags & (FLAG.underline | FLAG.strike));
       const style = blank ? "" : styleAttrs(cell, theme.foreground);
-      if (run && (run.style === style || (blank && run.text.length > 0))) {
+      if (run && ((run.style === style && run.link === cell.link) || (blank && run.text.length > 0 && run.link === null))) {
         run.text += cell.text;
       } else {
-        if (run && run.text.trim()) spans.push(`<tspan x="${num(run.x * g.cellW)}"${run.style}>${esc(run.text.replace(/\s+$/, ""))}</tspan>`);
-        run = blank ? null : { x, text: cell.text, style };
+        flushRun();
+        run = blank ? null : { x, text: cell.text, style, link: cell.link };
       }
       x += cell.width;
     }
-    if (run && run.text.trim()) spans.push(`<tspan x="${num(run.x * g.cellW)}"${run.style}>${esc(run.text.replace(/\s+$/, ""))}</tspan>`);
+    flushRun();
     if (spans.length) parts.push(`<text y="${num(y * g.cellH + baseline)}">${spans.join("")}</text>`);
   }
 
@@ -189,7 +194,7 @@ text{white-space:pre;dominant-baseline:auto}
 ${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)}
+${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}

package/src/index.ts

@@ -11,6 +11,7 @@ export { buildSvg } from "./export/svg";
 export { buildHtml } from "./export/html";
 export { replayFrames } from "./export/frames";
 export type { GridFrame, GridCell, GridReplay } from "./export/frames";
+export { writeLog } from "./render";
 export { runScriptTests, discoverScripts } from "./testing";
 export type { TestResult, TestSummary } from "./testing";
 export { themes, themeNames, resolveTheme, findThemes, themeSlug, builtinThemes } from "./themes";
@@ -22,9 +23,12 @@ export { readCast, writeCast, parseCast, serializeCast } from "./cast";
 export { buildTimeline } from "./timeline";
 export { presets, presetNames, applyPreset } from "./presets";
 export { diffCasts } from "./diff";
+export { diagnoseCast, diagnoseRecording, formatDoctorReport } from "./doctor";
+export type { DoctorReport } from "./doctor";
+export { extractTitle, hyperlink, linkifyMarkdown, unsupportedProtocols } from "./osc";
 export type { DiffOptions, DiffResult } from "./diff";
 export { keyLabels, keyChips } from "./keylabels";
 export { startBrowserCapture } from "./browser";
 export { resolveConfig } from "./config";
-export { WaitTimeoutError, ExpectationError } from "./recorder";
+export { WaitTimeoutError, ExpectationError, MissingRequirementError } from "./recorder";
 export type * from "./types";

package/src/keys.ts

@@ -32,7 +32,26 @@ const keySequences = {
   f12: `${ESC}[24~`,
 } satisfies Record<KeyName, string>;
 
-export function keySequence(name: KeyName): string {
+/** In application cursor mode (DECCKM, used by vim/less/fzf) cursor keys send SS3 instead of CSI. */
+const appCursorSequences = new Map<string, string>([
+  ["up", `${ESC}OA`],
+  ["down", `${ESC}OB`],
+  ["right", `${ESC}OC`],
+  ["left", `${ESC}OD`],
+  ["home", `${ESC}OH`],
+  ["end", `${ESC}OF`],
+]);
+
+export interface KeySequenceOptions {
+  /** The program switched on application cursor mode; arrows/home/end use the SS3 form. */
+  appCursor?: boolean;
+}
+
+export function keySequence(name: KeyName, opts: KeySequenceOptions = {}): string {
+  if (opts.appCursor) {
+    const app = appCursorSequences.get(name);
+    if (app) return app;
+  }
   const seq = keySequences[name];
   if (seq === undefined) {
     throw new Error(`Unknown key "${name}". Known keys: ${Object.keys(keySequences).join(", ")}`);

package/src/osc.ts

@@ -0,0 +1,48 @@
+// Small helpers for OSC sequences tcut reads or writes itself, independent of the emulator core.
+// Patterns never contain control characters: ESC and BEL are mapped to private-use code points first.
+const ESC = "\x1b";
+const BEL = "\x07";
+const ESC_MARK = "";
+const BEL_MARK = "";
+
+const marked = (chunk: string): string => chunk.replaceAll(ESC, ESC_MARK).replaceAll(BEL, BEL_MARK);
+
+/** Every window title set in `chunk` via OSC 0/2 (`ESC ] 0 ; title BEL`), in order. */
+export function extractTitles(chunk: string): string[] {
+  return [...marked(chunk).matchAll(/\](?:0|2);([^]*)(?:|\\)/g)].map((m) => m[1] ?? "");
+}
+
+/** The last window title set in `chunk`, or null — what a live window bar should show after the chunk. */
+export function extractTitle(chunk: string): string | null {
+  const titles = extractTitles(chunk);
+  return titles.length ? titles[titles.length - 1]! : null;
+}
+
+/** Wrap `text` in an OSC 8 hyperlink (terminals, the HTML player and the SVG export make it clickable). */
+export function hyperlink(text: string, url: string): string {
+  return `${ESC}]8;;${url}${ESC}\\${text}${ESC}]8;;${ESC}\\`;
+}
+
+/** Markdown `[text](url)` → underlined text carrying an OSC 8 link, so captions get real links instead of a printed URL. */
+export function linkifyMarkdown(markdown: string): string {
+  return markdown.replace(/\[([^\]\n]+)\]\((https?:\/\/[^)\s]+)\)/g, (_, text: string, url: string) => hyperlink(`${ESC}[4m${text}${ESC}[24m`, url));
+}
+
+export interface UnsupportedProtocol {
+  name: string;
+  count: number;
+  note: string;
+}
+
+const PROTOCOLS: Array<{ name: string; pattern: RegExp; note: string }> = [
+  { name: "kitty-graphics", pattern: /_G/g, note: "Kitty graphics protocol (inline images) is not rendered" },
+  { name: "sixel", pattern: /P[0-9;]*q/g, note: "Sixel images are not rendered" },
+  { name: "iterm2-image", pattern: /\]1337;File=/g, note: "iTerm2 inline images are not rendered" },
+  { name: "tmux-passthrough", pattern: /Ptmux;/g, note: "tmux passthrough sequences are ignored" },
+];
+
+/** Image/graphics protocols tcut cannot draw, counted across a chunk of output. */
+export function unsupportedProtocols(output: string): UnsupportedProtocol[] {
+  const safe = marked(output);
+  return PROTOCOLS.map((p) => ({ name: p.name, count: (safe.match(p.pattern) ?? []).length, note: p.note })).filter((p) => p.count > 0);
+}