termcut 0.5.0 → 0.6.0

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;
@@ -278,6 +306,18 @@ export interface TerminalSession {
   resize(cols: number, rows: number): Promise<void>;
   /** Shorthand for `run("clear")`. */
   clear(): Promise<void>;
+  /**
+   * Show Markdown in the terminal as a caption (rendered to ANSI by @wterm/markdown). It is written into the
+   * recording and the screen model only, never sent to the shell; afterwards the shell is asked for a fresh prompt.
+   * Use at a shell prompt, not inside a full-screen program.
+   */
+  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). */