termcut 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termcut",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Script terminal sessions in TypeScript, render them to reproducible MP4/GIF/WebM/SVG/HTML with Bun.",
   "license": "MIT",
   "author": "Aman Varshney",
@@ -56,7 +56,8 @@
   "dependencies": {
     "@wterm/core": "^0.3.4",
     "@wterm/dom": "^0.3.4",
-    "@wterm/ghostty": "^0.3.4"
+    "@wterm/ghostty": "^0.3.4",
+    "@wterm/markdown": "^0.3.4"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/live.ts

@@ -98,7 +98,7 @@ export async function recordLive(config: ResolvedConfig, opts: LiveOptions = {})
     await Promise.race([exitedPromise, proc.exited]);
     push("m", MARKER.end);
   } finally {
-    process.off("SIGWINCH", onResize);
+    (process as unknown as { off(event: string, fn: () => void): void }).off("SIGWINCH", onResize); // newer @types/bun drop the signal overload on off()
     if (stdin) {
       stdin.off("data", onData);
       if (isTTY) stdin.setRawMode(false);

package/src/recorder.ts

@@ -1,3 +1,4 @@
+import { MarkdownRenderer } from "@wterm/markdown";
 import { MARKER } from "./cast";
 import { WINDOW_BAR_HEIGHT, estimateCell } from "./config";
 import { formatMs, toMs } from "./duration";
@@ -269,6 +270,30 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
     push("i", typeof data === "string" ? data : decoder.decode(data));
   };
 
+  /** Put text on screen as if the terminal had printed it: into the cast and the screen model, not the PTY. */
+  const inject = (data: string): void => {
+    push("o", data);
+    screen.write(data);
+  };
+
+  const renderMarkdown = (markdown: string): string => {
+    const renderer = new MarkdownRenderer({ width: Math.max(20, cols - 2) });
+    return renderer.push(markdown.endsWith("\n") ? markdown : markdown + "\n") + renderer.flush();
+  };
+
+  const print = async (markdown: string): Promise<void> => {
+    await screen.settle();
+    // Clear the prompt line, show the caption, then ask the shell for a fresh prompt on the next line.
+    inject(`\r\x1b[K${renderMarkdown(markdown)}`);
+    await raw("\r");
+    await waitFor(`prompt ${promptPattern} after print()`, promptVisible, config.waitTimeout);
+  };
+
+  const title = async (text: string, titleOpts: { pause?: Duration } = {}): Promise<void> => {
+    await print(`# ${text}\n\n---`);
+    await sleep(titleOpts.pause ?? "1.5s");
+  };
+
   const typingDelay = (base: number): number => {
     if (config.typingJitter === 0) return base;
     const factor = 1 + (rand() * 2 - 1) * config.typingJitter;
@@ -435,6 +460,8 @@ export async function record(config: ResolvedConfig, script: Script, opts: Recor
       await screen.settle();
     },
     clear: () => run("clear"),
+    print,
+    title,
     get browser(): BrowserSession {
       if (!browserSession) throw new Error("t.browser needs `browser: { url }` in the video config.");
       return browserSession;

package/src/types.ts

@@ -278,6 +278,14 @@ 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>;
   /** 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). */