Skip to content

Code-first video & image, rendered natively on WebGPU.

8.4 KB
Raw Blame
/**
 * Terminal planning, kept pure: run the script on a clock and record what
 * appears where and when. Nodes are built from this plan; tests read it.
 */
import type { Rng } from "../core/rng.js";
import { typingFrames } from "../core/typing.js";

export type Step =
	| { cmd: string; prompt?: string }
	| { output: string | string[] }
	| { spinner: string; for: number; done?: string }
	| { progress: string; for: number }
	| { pause: number }
	| { clear: true };

/** A run of text in one colour (a palette name) and weight. */
export interface Span {
	text: string;
	color?: string;
	bold?: boolean;
}

export interface PlannedLine {
	row: number;
	/** Frame the line appears. */
	appear: number;
	/** Frame it stops being drawn (scrolled out or cleared); Infinity if never. */
	until: number;
	spans: Span[];
	step: number;
	kind: "cmd" | "output" | "spinner" | "done" | "progress" | "prompt";
	/** Columns the text starts in (room for a spinner or check mark). */
	indent?: number;
	/** For commands: characters already shown (the prompt) and each keystroke's frame. */
	typing?: { prompt: number; frames: number[] };
}

export interface TerminalPlan {
	lines: PlannedLine[];
	/** Rotating spinners: row, from frame, to frame. */
	spinners: Array<{ row: number; from: number; to: number; step: number }>;
	/** Check marks drawn at `at` on `row`, before the text from column 2. */
	checks: Array<{ row: number; at: number; step: number }>;
	progress: Array<{
		row: number;
		from: number;
		to: number;
		label: string;
		step: number;
	}>;
	/** First visible row from each frame on; `jump` (a clear) snaps instead of gliding. */
	scroll: Array<[frame: number, top: number, jump?: boolean]>;
	/** Where the caret is, from each frame on (null = hidden). */
	caret: Array<[frame: number, at: { row: number; col: number } | null]>;
	keystrokes: Array<{ frame: number; index: number; step: number }>;
	submits: Array<{ frame: number; step: number }>;
	outputs: Array<{ frame: number; end: number; step: number }>;
	done: number;
	/** Longest line, in characters. */
	widest: number;
}

export interface PlanOptions {
	prompt: string;
	cps: number;
	/** Lines a second, or every output line at once. */
	outputRate: number | "instant";
	rows: number;
	fps: number;
	markup: boolean;
	rng: Rng;
}

const COLORS = new Set([
	"black",
	"red",
	"green",
	"yellow",
	"blue",
	"magenta",
	"cyan",
	"white",
	"gray",
	"dim",
	"accent",
]);

/** `{green}ok{/} done` → spans. `{bold}` sets weight; unknown tags stay literal. */
export function parseMarkup(source: string, markup = true): Span[] {
	if (!markup) return [{ text: source }];
	const spans: Span[] = [];
	const stack: Array<{ color?: string; bold?: boolean }> = [{}];
	let buffer = "";
	const flush = () => {
		if (!buffer) return;
		const top = stack[stack.length - 1] ?? {};
		spans.push({ text: buffer, ...top });
		buffer = "";
	};
	const re = /\{(\/|[a-z]+)\}/g;
	let last = 0;
	for (const m of source.matchAll(re)) {
		const tag = m[1] as string;
		const index = m.index ?? 0;
		buffer += source.slice(last, index);
		last = index + m[0].length;
		if (tag === "/") {
			flush();
			if (stack.length > 1) stack.pop();
		} else if (tag === "bold" || COLORS.has(tag)) {
			flush();
			const top = stack[stack.length - 1] ?? {};
			stack.push(
				tag === "bold" ? { ...top, bold: true } : { ...top, color: tag },
			);
		} else buffer += m[0];
	}
	buffer += source.slice(last);
	flush();
	return spans;
}

export const spansText = (spans: readonly Span[]) =>
	spans.map((s) => s.text).join("");

/** Frames between Enter and the first line of output. */
const SUBMIT_BEAT = 0.3;
/** Frames the scroll takes to glide one or more lines. */
export const SCROLL_GLIDE = 4;
/** A check mark replaces these leading glyphs (fonts often lack them). */
const DONE_MARK = /^\s*[✔✓√]\s*/;

/**
 * The spans without a leading check mark, found in the first span with
 * visible text, so `{green}✓{/} done` loses it as `✓ done` does (the
 * drawn check takes its place).
 */
export function withoutDoneMark(spans: Span[]): Span[] {
	const first = spans.findIndex((sp) => sp.text.trim() !== "");
	const span = spans[first];
	if (!span || !DONE_MARK.test(span.text)) return spans;
	const rest = [
		{ ...span, text: span.text.replace(DONE_MARK, "") },
		...spans.slice(first + 1),
	];
	// The mark's trailing space goes with it, even when it's in the next span.
	while (rest[0] && rest[0].text.trimStart() === "") rest.shift();
	if (rest[0]) rest[0] = { ...rest[0], text: rest[0].text.trimStart() };
	return rest;
}

export function planTerminal(
	script: readonly Step[],
	o: PlanOptions,
): TerminalPlan {
	const plan: TerminalPlan = {
		lines: [],
		spinners: [],
		checks: [],
		progress: [],
		scroll: [[0, 0]],
		caret: [[0, null]],
		keystrokes: [],
		submits: [],
		outputs: [],
		done: 0,
		widest: 0,
	};
	let t = 0;
	let row = 0;
	let top = 0;
	let typed = 0;
	const perLine = o.outputRate === "instant" ? 0 : o.fps / o.outputRate;

	const show = (line: Omit<PlannedLine, "until" | "row">): PlannedLine => {
		if (row - top >= o.rows) {
			top = row - o.rows + 1;
			plan.scroll.push([line.appear, top]);
		}
		const planned = { ...line, row, until: Number.POSITIVE_INFINITY };
		plan.lines.push(planned);
		plan.widest = Math.max(
			plan.widest,
			spansText(line.spans).length + (line.indent ?? 0),
		);
		row++;
		return planned;
	};
	const caretAt = (frame: number, at: { row: number; col: number } | null) =>
		plan.caret.push([frame, at]);

	script.forEach((step, s) => {
		if ("cmd" in step) {
			const prompt = step.prompt ?? o.prompt;
			const line = show({
				appear: t,
				spans: [{ text: prompt, color: "accent" }, { text: step.cmd }],
				step: s,
				kind: "cmd",
			});
			const frames = typingFrames(
				step.cmd,
				o.cps,
				o.fps,
				o.rng,
				t + Math.round(o.fps * 0.25),
			);
			line.typing = { prompt: prompt.length, frames };
			caretAt(t, { row: line.row, col: prompt.length });
			frames.forEach((f, i) => {
				plan.keystrokes.push({ frame: f, index: typed++, step: s });
				caretAt(f, { row: line.row, col: prompt.length + i + 1 });
			});
			const submit =
				(frames[frames.length - 1] ?? t) + Math.round(o.fps * SUBMIT_BEAT);
			plan.submits.push({ frame: submit, step: s });
			caretAt(submit, null);
			t = submit + 1;
		} else if ("output" in step) {
			const lines = Array.isArray(step.output)
				? step.output
				: step.output.split("\n");
			const first = Math.round(t);
			let at = t;
			for (const text of lines) {
				show({
					appear: Math.round(at),
					spans: parseMarkup(text, o.markup),
					step: s,
					kind: "output",
				});
				at += perLine;
			}
			plan.outputs.push({
				frame: first,
				end: Math.round(Math.max(t, at - perLine)),
				step: s,
			});
			t = Math.round(at);
		} else if ("spinner" in step) {
			const from = Math.round(t);
			const to = from + step.for;
			const spinning = show({
				appear: from,
				spans: [{ text: step.spinner }],
				indent: 2,
				step: s,
				kind: "spinner",
			});
			spinning.until = to;
			plan.spinners.push({ row: spinning.row, from, to, step: s });
			row--;
			show({
				appear: to,
				spans: withoutDoneMark(
					parseMarkup(step.done ?? step.spinner, o.markup),
				),
				indent: 2,
				step: s,
				kind: "done",
			});
			plan.checks.push({ row: spinning.row, at: to, step: s });
			t = to;
		} else if ("progress" in step) {
			const from = Math.round(t);
			const line = show({
				appear: from,
				spans: [{ text: step.progress }],
				step: s,
				kind: "progress",
			});
			plan.progress.push({
				row: line.row,
				from,
				to: from + step.for,
				label: step.progress,
				step: s,
			});
			plan.widest = Math.max(plan.widest, step.progress.length + 32);
			t = from + step.for;
		} else if ("pause" in step) {
			t += step.pause;
		} else {
			const at = Math.round(t);
			for (const line of plan.lines) line.until = Math.min(line.until, at);
			top = row;
			plan.scroll.push([at, top, true]);
		}
	});

	plan.done = Math.round(t);
	// A fresh prompt waits at the end.
	const last = show({
		appear: plan.done,
		spans: [{ text: o.prompt, color: "accent" }],
		step: script.length,
		kind: "prompt",
	});
	caretAt(plan.done, { row: last.row, col: o.prompt.length });

	// Lines stop drawing once scrolled out (after the glide), so only a
	// screenful of nodes is ever live.
	for (const line of plan.lines) {
		const gone = plan.scroll.find(([, top]) => top > line.row);
		if (gone) line.until = Math.min(line.until, gone[0] + SCROLL_GLIDE);
	}
	return plan;
}