termcut 0.5.1 → 0.6.0

package/src/renderer/page-entry.ts

@@ -97,6 +97,34 @@ const api = {
     return true;
   },
 
+  /** Key overlay: show these chips (empty array hides them). */
+  keys(labels: string[]): boolean {
+    const el = document.getElementById("keys");
+    if (!el) return false;
+    el.replaceChildren(...labels.map((l) => Object.assign(document.createElement("span"), { textContent: l })));
+    return true;
+  },
+
+  /** Zoom: scale the terminal so the px rect (relative to the grid) fills the grid box; null resets. */
+  zoom(rect: { x: number; y: number; w: number; h: number } | null): Promise<boolean> {
+    const el = document.getElementById("zoom")!;
+    const term = document.getElementById("term")!;
+    if (!rect) {
+      el.style.transform = "";
+    } else {
+      const W = term.clientWidth;
+      const H = term.clientHeight;
+      const scale = Math.min(W / rect.w, H / rect.h);
+      // Centre the region; clamp so we never show outside the grid.
+      let tx = (W - rect.w * scale) / 2 - rect.x * scale;
+      let ty = (H - rect.h * scale) / 2 - rect.y * scale;
+      tx = Math.min(0, Math.max(W - W * scale, tx));
+      ty = Math.min(0, Math.max(H - H * scale, ty));
+      el.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`;
+    }
+    return paint();
+  },
+
   /** Overlay layout: which window is in front. */
   focus(target: "terminal" | "browser"): boolean {
     document.getElementById("stage")?.classList.toggle("front-browser", target === "browser");

package/src/renderer/page.ts

@@ -140,6 +140,18 @@ export function renderHtml(config: ResolvedConfig): string {
     overflow: hidden;
   }
   #term .term-row { overflow: hidden; }
+  /* Key overlay: chips for recent key presses, driven by the renderer on the render clock. */
+  #keys {
+    position: absolute; left: 0; right: 0; ${config.keys?.position === "top" ? "top" : "bottom"}: ${Math.max(10, config.padding - 6)}px;
+    display: ${config.keys ? "flex" : "none"}; justify-content: center; gap: 6px; pointer-events: none; z-index: 5;
+  }
+  #keys span {
+    font: 600 ${Math.max(12, Math.round(config.font.size * 0.75))}px ${font.family};
+    color: #fff; background: rgba(0,0,0,0.72); border: 1px solid rgba(255,255,255,0.25);
+    border-radius: 6px; padding: 3px 8px; letter-spacing: 0.02em; white-space: pre;
+  }
+  /* Zoom: the terminal grid is scaled inside its frame; the renderer sets the transform per frame. */
+  #zoom { transform-origin: 0 0; will-change: transform; }
 </style>
 <style id="blink"></style>
 </head>
@@ -147,7 +159,8 @@ export function renderHtml(config: ResolvedConfig): string {
 <div id="stage">
 <div id="frame">
   ${windowBarHtml(config)}
-  <div id="term"></div>
+  <div id="zoom"><div id="term"></div></div>
+  <div id="keys"></div>
 </div>
 ${
   config.browser

package/src/renderer/webview.ts

@@ -5,7 +5,8 @@ import type { Recording, RenderProgress, ResolvedConfig } from "../types";
 import { fitFrame, loopOffsetFrames, rotateFrames } from "../loop";
 import { buildTimeline, withReinjection, type TimedEvent } from "../timeline";
 import { pageAssets } from "./bundle";
-import { createSinks } from "./encoder";
+import { createSinks, type Chapter } from "./encoder";
+import { keyChips } from "../keylabels";
 import { BROWSER_GAP, barHeight, renderHtml, themeOsc } from "./page";
 
 export interface RenderResult {
@@ -13,6 +14,41 @@ export interface RenderResult {
   frames: number;
   screenshots: string[];
   durationSeconds: number;
+  chapters?: Chapter[];
+}
+
+interface ZoomRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** 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 {
+  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);
+  const c0 = Math.max(0, (spec.cols?.[0] ?? 0) - pad);
+  const c1 = Math.min(cols - 1, (spec.cols?.[1] ?? cols - 1) + pad);
+  return { x: c0 * cell.w, y: r0 * cell.h, w: (c1 - c0 + 1) * cell.w, h: (r1 - r0 + 1) * cell.h };
+}
+
+const easeInOut = (p: number) => (p < 0.5 ? 2 * p * p : 1 - Math.pow(-2 * p + 2, 2) / 2);
+
+/** Where the zoom is at `time`, interpolating from → to over [start, start + duration]. null = no zoom. */
+function currentZoom(from: ZoomRect | null, to: ZoomRect | null, start: number, duration: number, time: number, full?: ZoomRect): ZoomRect | null {
+  if (from === null && to === null) return null;
+  const p = duration <= 0 ? 1 : Math.min(1, Math.max(0, (time - start) / duration));
+  if (p >= 1) return to;
+  const e = easeInOut(p);
+  const a = from ?? to!; // from null = "unzoomed": treat as the target's containing box expanded; approximate with target
+  const b = to ?? from!;
+  const lerp = (u: number, v: number) => u + (v - u) * e;
+  // Zooming from/to "no zoom" needs the full grid rect; callers pass it via `full` when known.
+  const A = from ?? full ?? a;
+  const B = to ?? full ?? b;
+  return { x: lerp(A.x, B.x), y: lerp(A.y, B.y), w: lerp(A.w, B.w), h: lerp(A.h, B.h) };
 }
 
 export async function render(
@@ -57,9 +93,14 @@ export async function render(
     },
   });
 
-  const timeline = buildTimeline(rec.events, config.playbackSpeed);
+  const timeline = buildTimeline(rec.events, config.playbackSpeed, { keepInput: Boolean(config.keys), maxPause: config.maxPause });
   const lite = config.core === "lite";
   const events = lite ? timeline.events : withReinjection(timeline.events, osc);
+  // Key overlay chips come from input events; zoom/chapter markers are read as the clock passes them.
+  const chips = config.keys ? keyChips(events.filter((e) => e.type === "i"), config.keys.merge / 1000) : [];
+  const chapters: Chapter[] = events
+    .filter((e) => e.type === "m" && e.data.startsWith(MARKER.chapter))
+    .map((e) => ({ title: e.data.slice(MARKER.chapter.length), start: e.vt }));
   const fps = config.fps;
   const totalFrames = Math.max(1, Math.ceil(timeline.duration * fps) + 1);
   const blinkPeriod = config.cursor.period / 1000;
@@ -124,7 +165,15 @@ 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);
+    const sinks = await createSinks(config.output, fps, { chapters, durationSeconds: timeline.duration });
+    const cellPx = cell;
+    const fullRect: ZoomRect = { x: 0, y: 0, w: termW, h: termH };
+    let zoomFrom: ZoomRect | null = null;
+    let zoomTo: ZoomRect | null = null;
+    let zoomStart = 0;
+    let zoomDuration = 0;
+    let zoomApplied: string | null = null;
+    let lastChips = "";
     // 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));
@@ -146,7 +195,7 @@ export async function render(
       const shots = batch.filter((e) => e.type === "m" && e.data.startsWith(MARKER.screenshot));
       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));
-      const dirty = lastPng === null || drawable.length > 0 || blinkOn !== lastBlink || browserFrame !== undefined || focusChanged;
+      let dirty = lastPng === null || drawable.length > 0 || blinkOn !== lastBlink || browserFrame !== undefined || focusChanged;
 
       if (drawable.length > 0) {
         const id = ++batchId;
@@ -160,10 +209,42 @@ export async function render(
       if (focus) {
         await view.evaluate(`window.__vt.focus(${JSON.stringify(focus.data.slice(MARKER.focus.length))})`);
       }
+
+      // Zoom markers start an animation on the render clock; interpolate until it lands.
+      const zoomMarker = batch.filter((e) => e.type === "m" && e.data.startsWith(MARKER.zoom)).at(-1);
+      if (zoomMarker) {
+        const spec = JSON.parse(zoomMarker.data.slice(MARKER.zoom.length)) as null | { rows?: [number, number]; cols?: [number, number]; duration?: number; padding?: number };
+        zoomFrom = currentZoom(zoomFrom, zoomTo, zoomStart, zoomDuration, time, fullRect);
+        zoomTo = spec ? zoomRect(spec, rec.header.width, rec.header.height, cellPx) : null;
+        zoomStart = time;
+        zoomDuration = (spec?.duration ?? 400) / 1000;
+      }
+      const zoomNow = currentZoom(zoomFrom, zoomTo, zoomStart, zoomDuration, time, fullRect);
+      const zoomKey = zoomNow ? `${zoomNow.x.toFixed(1)},${zoomNow.y.toFixed(1)},${zoomNow.w.toFixed(1)},${zoomNow.h.toFixed(1)}` : "";
+      let zoomChanged = false;
+      if (zoomKey !== zoomApplied) {
+        await view.evaluate(`window.__vt.zoom(${zoomNow ? JSON.stringify(zoomNow) : "null"})`);
+        zoomApplied = zoomKey;
+        zoomChanged = true;
+      }
+
+      // Key chips visible at this instant.
+      let chipsChanged = false;
+      if (config.keys) {
+        const ttl = config.keys.ttl / 1000;
+        const visible = chips.filter((c) => c.at <= time + 1e-9 && time - c.at < ttl).slice(-6).map((c) => c.label);
+        const key = visible.join("\u0000");
+        if (key !== lastChips) {
+          await view.evaluate(`window.__vt.keys(${JSON.stringify(visible)})`);
+          lastChips = key;
+          chipsChanged = true;
+        }
+      }
       if (blinkOn !== lastBlink) {
         await view.evaluate(`window.__vt.cursor(${blinkOn})`);
         lastBlink = blinkOn;
       }
+      if (zoomChanged || chipsChanged) dirty = true;
       if (dirty) {
         lastPng = (await view.screenshot({ encoding: "buffer" })) as Uint8Array;
       }
@@ -185,7 +266,7 @@ export async function render(
       for (const png of rotated) for (const sink of loopSinks) await sink.frame(png);
     }
     for (const sink of sinks) await sink.finish();
-    return { outputs: sinks.map((s) => s.target), frames: totalFrames, screenshots, durationSeconds: timeline.duration };
+    return { outputs: sinks.map((s) => s.target), frames: totalFrames, screenshots, durationSeconds: timeline.duration, chapters };
   } finally {
     view.close();
     server.stop(true);

package/src/timeline.ts

@@ -2,7 +2,7 @@ import { MARKER } from "./cast";
 import type { CastEvent } from "./types";
 
 export interface TimedEvent {
-  /** Time on the visible (hide-collapsed, speed-adjusted) timeline, seconds. */
+  /** Time on the visible (hide-collapsed, speed-adjusted, idle-compressed) timeline, seconds. */
   vt: number;
   type: CastEvent[1];
   data: string;
@@ -13,16 +13,22 @@ export interface Timeline {
   duration: number;
 }
 
+export interface TimelineOptions {
+  /** Keep `i` (input) events; the renderer needs them for the key overlay. Default false. */
+  keepInput?: boolean;
+  /** Cap any gap between consecutive events to this many seconds (idle compression). */
+  maxPause?: number;
+}
+
 /**
- * Collapse hidden intervals and apply playback speed. 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: the PTY already echoed them.
+ * 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.
  */
-export function buildTimeline(events: CastEvent[], playbackSpeed: number): Timeline {
+export function buildTimeline(events: CastEvent[], playbackSpeed: number, opts: TimelineOptions = {}): Timeline {
   const out: TimedEvent[] = [];
   let hiddenSince: number | null = null;
   let removed = 0;
-  let duration = 0;
 
   for (const [t, type, data] of events) {
     if (type === "m" && data === MARKER.hide) {
@@ -36,12 +42,25 @@ export function buildTimeline(events: CastEvent[], playbackSpeed: number): Timel
       }
       continue;
     }
-    if (type === "i") continue;
+    if (type === "i" && !opts.keepInput) continue;
     const visible = hiddenSince === null ? t - removed : hiddenSince - removed;
-    const vt = visible / playbackSpeed;
-    out.push({ vt, type, data });
-    if (vt > duration) duration = vt;
+    out.push({ vt: visible / playbackSpeed, type, data });
+  }
+
+  if (opts.maxPause !== undefined && opts.maxPause >= 0) {
+    // Walk forward; whenever the next event is further away than maxPause, pull everything after it closer.
+    let shift = 0;
+    let prev: number | null = null;
+    for (const e of out) {
+      const original = e.vt;
+      if (prev !== null && original - prev > opts.maxPause) shift += original - prev - opts.maxPause;
+      prev = original;
+      e.vt = original - shift;
+    }
   }
+
+  let duration = 0;
+  for (const e of out) if (e.vt > duration) duration = e.vt;
   return { events: out, duration };
 }
 

package/src/types.ts

@@ -48,6 +48,26 @@ export interface FontConfig {
   letterSpacing?: number;
 }
 
+export interface KeysConfig {
+  position?: "bottom" | "top";
+  /** How long a chip stays visible, e.g. "1.2s". */
+  ttl?: Duration;
+  /** Printable keys pressed within this window merge into one chip. Default "350ms". */
+  merge?: Duration;
+}
+
+/** A region of the terminal grid to magnify. */
+export interface ZoomRegion {
+  /** Inclusive row range, 0-based. Default: all rows. */
+  rows?: [number, number];
+  /** Inclusive column range, 0-based. Default: all columns. */
+  cols?: [number, number];
+  /** Animation length on the render clock. Default "400ms". */
+  duration?: Duration;
+  /** Inner padding around the region, in cells. Default 1. */
+  padding?: number;
+}
+
 /** A browser window recorded next to the terminal (Bun.WebView). */
 export interface BrowserConfig {
   /** Page to open when recording starts (may also be opened later with `t.browser.goto`). */
@@ -115,6 +135,12 @@ export interface VideoConfig {
   height?: number;
   /** Where looping outputs (GIF, WebP) start: a frame number or a percentage like "50%". */
   loopOffset?: number | string;
+  /** Idle compression: at render time, gaps between events longer than this are shortened to this. */
+  maxPause?: Duration;
+  /** Show recent key presses as chips. `true` = bottom centre, 1.2 s. */
+  keys?: boolean | KeysConfig;
+  /** A named bundle of defaults applied under explicit settings: readme | x | youtube | square. */
+  preset?: "readme" | "x" | "youtube" | "square";
 
   /** Frames per second of the output. Default 60. */
   fps?: number;
@@ -169,6 +195,8 @@ export interface ResolvedConfig {
   width?: number;
   height?: number;
   loopOffset?: number | string;
+  maxPause?: number;
+  keys?: Required<KeysConfig> & { ttl: number; merge: number };
   fps: number;
   typingSpeed: number;
   typingJitter: number;
@@ -286,6 +314,10 @@ export interface TerminalSession {
   print(markdown: string): Promise<void>;
   /** A title card: big heading + rule, then a pause (default "1.5s"). */
   title(text: string, opts?: { pause?: Duration }): Promise<void>;
+  /** Magnify a region of the terminal (animated at render time); `zoom(null)` resets. */
+  zoom(region: ZoomRegion | null): Promise<void>;
+  /** Named chapter: becomes mp4 chapter metadata and shows up in `--json` output. */
+  chapter(name: string): Promise<void>;
   /** The recorded browser window; throws if `browser` is not configured. */
   readonly browser: BrowserSession;
   /** Overlay layout: bring the terminal or the browser window to the front (recorded as a marker). */