Skip to content

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

13.2 KB
Raw Blame
/**
 * Terminal: a scripted shell session. Commands type with a human rhythm,
 * output streams in, spinners resolve to check marks, progress bars fill,
 * and the view scrolls by whole lines, all on cue. Wrapped in an `AppFrame`
 * terminal window by default.
 */
import {
	type KeyframeTuple,
	LayerAnimation,
	type LayoutNode,
	type TextSpan,
} from "@framefields/compositions/program";
import { z } from "zod";
import { appFrame } from "../app-frame/index.js";
import { bind, defineComponent } from "../core/contract.js";
import type { Animatable } from "../core/host.js";
import { ascending } from "../core/keys.js";
import { toPathData, type Vec2 } from "../core/path.js";
import type { Theme } from "../core/theme.js";
import { counter } from "../counter/index.js";
import {
	planTerminal,
	SCROLL_GLIDE,
	type Span,
	type Step,
	spansText,
} from "./plan.js";

export type { Step as TerminalStep } from "./plan.js";

export interface TerminalCues {
	[name: string]: ReadonlyArray<{ frame: number }>;
	/** Every typed character: for key sounds. */
	keystrokes: ReadonlyArray<{ frame: number; index: number; step: number }>;
	/** Enter, per command. */
	submits: ReadonlyArray<{ frame: number; step: number }>;
	/** Each output step, first line to last. */
	outputs: ReadonlyArray<{ frame: number; end: number; step: number }>;
	/** The script has finished. */
	done: ReadonlyArray<{ frame: number }>;
}

/** The 16-colour palette, from theme tokens where they exist. */
function palette(theme: Theme): Record<string, string> {
	const c = theme.color;
	return {
		black: "#1b1d23",
		red: c.negative,
		green: c.positive,
		yellow: c.highlight,
		blue: c.accent,
		magenta: c.accent2,
		cyan: "#4cc9e0",
		white: c.ink,
		gray: c.muted,
		dim: c.muted,
		accent: c.accent,
	};
}

function stepSchema() {
	const frames = z.number().int().positive();
	return z.union([
		z.object({ cmd: z.string(), prompt: z.string().optional() }).strict(),
		z.object({ output: z.union([z.string(), z.array(z.string())]) }).strict(),
		z
			.object({ spinner: z.string(), for: frames, done: z.string().optional() })
			.strict(),
		z.object({ progress: z.string(), for: frames }).strict(),
		z.object({ pause: frames }).strict(),
		z.object({ clear: z.literal(true) }).strict(),
	]);
}

export const terminal = /* @__PURE__ */ defineComponent({
	name: "Terminal",
	props: () => ({
		script: z.array(stepSchema()).min(1),
		prompt: z.string().default("$ "),
		/** Typing speed, characters a second (seeded ±30 % jitter). */
		cps: z.number().positive().default(18),
		/** Output lines a second, or `"instant"`. */
		outputRate: z
			.union([z.number().positive(), z.literal("instant")])
			.default(40),
		rows: z.number().int().positive().default(16),
		/** Columns. Default: the widest line, between 40 and 100. */
		cols: z.number().int().positive().optional(),
		/** `{green}ok{/}`-style colours (black red green yellow blue magenta cyan white gray dim accent, bold). */
		markup: z.boolean().default(true),
		/** Wrap in an AppFrame terminal window (`false` for the bare screen). */
		frame: z
			.union([
				z.boolean(),
				z
					.object({
						title: z.string().optional(),
						elevation: z.number().int().min(0).max(3).optional(),
					})
					.strict(),
			])
			.default(true),
		caret: z.enum(["block", "bar", "underline"]).default("block"),
		fontFamily: z.string().optional(),
		fontSize: z.number().positive().optional(),
	}),
	defaults: { enter: false, exit: false },
	build(ctx, props) {
		const { host, theme, fps } = ctx;
		const s = theme.scale;
		const fs = props.fontSize ?? 24 * s;
		const fontFamily = props.fontFamily ?? theme.font.mono;
		const colors = palette(theme);
		const LINE_HEIGHT = 1.5;
		const glyph = host.measure("M", {
			fontFamily,
			fontSize: fs,
			lineHeight: LINE_HEIGHT,
		});
		const adv = glyph.width;
		const lh = glyph.lineHeight;

		const plan = planTerminal(props.script as Step[], {
			prompt: props.prompt,
			cps: props.cps,
			outputRate: props.outputRate,
			rows: props.rows,
			fps,
			markup: props.markup,
			rng: ctx.rng("typing"),
		});
		const cols = props.cols ?? Math.min(100, Math.max(40, plan.widest + 2));
		const pad = fs * 0.9;
		const viewW = cols * adv + pad * 2;
		const viewH = props.rows * lh + pad * 2;

		const parts: Record<string, Animatable<LayoutNode>> = {};
		const content: LayoutNode[] = [];
		/** A node drawn from `from` until `until` (local frames). */
		const live = (from: number, until: number) => ({
			startFrame: from,
			...(Number.isFinite(until) && {
				durationFrames: Math.max(1, until - from),
			}),
		});
		const toSpans = (spans: readonly Span[]): TextSpan[] =>
			spans.map((sp) => ({
				text: sp.text,
				fill: sp.color
					? (colors[sp.color] ?? theme.color.ink)
					: theme.color.ink,
				...(sp.bold && { fontWeight: theme.weight.bold }),
			}));

		// ── Lines ─────────────────────────────────────────────────────────
		plan.lines.forEach((line, i) => {
			const node = host.text(spansText(line.spans), {
				id: ctx.partId(`line-${i}`),
				position: "absolute",
				x: (line.indent ?? 0) * adv,
				y: line.row * lh,
				fontFamily,
				fontSize: fs,
				lineHeight: LINE_HEIGHT,
				fill: theme.color.ink,
				spans: toSpans(line.spans),
				...live(line.appear, line.until),
			});
			if (line.typing) {
				const total = spansText(line.spans).length;
				// The text track is a reveal amount: ≤ 1 a fraction, > 1 a count.
				const count = (c: number) => (c <= 1 ? c / total : c);
				const shown = line.typing.prompt;
				const keys: KeyframeTuple[] = [[0, count(shown)]];
				line.typing.frames.forEach((f, k) => {
					keys.push([f - line.appear, count(shown + k + 1), "hold"]);
				});
				node.animate(LayerAnimation.keys("text" as never, keys));
			}
			content.push(node);
		});

		// ── Spinners, checks, progress ────────────────────────────────────
		const cell = (row: number, col: number) => ({ x: col * adv, y: row * lh });
		plan.spinners.forEach((sp, i) => {
			const r = fs * 0.32;
			const c: Vec2 = [adv / 2, lh / 2];
			const arc: Vec2[] = Array.from({ length: 25 }, (_, k) => {
				const a = (k / 24) * Math.PI * 1.5;
				return [c[0] + Math.cos(a) * r, c[1] + Math.sin(a) * r];
			});
			const spinner = host.shape("path", {
				id: ctx.partId(`spinner-${i}`),
				position: "absolute",
				...cell(sp.row, 0),
				width: adv,
				height: lh,
				d: toPathData(arc),
				fillType: "none",
				strokeColor: colors.accent,
				strokeWidth: fs * 0.1,
				strokeLineCap: "round",
				...live(sp.from, sp.to),
			});
			spinner.animate(
				LayerAnimation.keys("rotation", [
					[0, 0],
					[sp.to - sp.from, (360 * (sp.to - sp.from)) / (fps * 0.8), "none"],
				]),
			);
			content.push(spinner);
		});
		plan.checks.forEach((ck, i) => {
			const line = plan.lines.find(
				(l) => l.kind === "done" && l.row === ck.row && l.appear === ck.at,
			);
			const pts: Vec2[] = [
				[adv * 0.12, lh * 0.52],
				[adv * 0.4, lh * 0.72],
				[adv * 0.9, lh * 0.28],
			];
			const check = host.shape("path", {
				id: ctx.partId(`check-${i}`),
				position: "absolute",
				...cell(ck.row, 0),
				width: adv,
				height: lh,
				d: toPathData(pts),
				fillType: "none",
				strokeColor: colors.green,
				strokeWidth: fs * 0.12,
				strokeLineCap: "round",
				strokeLineJoin: "round",
				trimEnd: 0,
				...live(ck.at, line?.until ?? Number.POSITIVE_INFINITY),
			});
			check.animate(
				LayerAnimation.keys("trimEnd", [
					[0, 0],
					[Math.max(3, Math.round(fps * 0.2)), 1, "power2.out"],
				]),
			);
			content.push(check);
		});
		const makeCounter = bind(host, counter);
		plan.progress.forEach((pg, i) => {
			const line = plan.lines.find(
				(l) => l.kind === "progress" && l.row === pg.row,
			);
			const barCols = 24;
			const x0 = (pg.label.length + 1) * adv;
			const barW = barCols * adv;
			const barH = Math.max(4, lh * 0.32);
			const y = (lh - barH) / 2;
			const length = pg.to - pg.from;
			const fill = host.box({
				id: ctx.partId(`progress-${i}-fill`),
				position: "absolute",
				x: 0,
				y: 0,
				width: 0,
				height: barH,
				background: colors.accent,
				borderRadius: barH / 2,
			});
			fill.animate(
				LayerAnimation.keys("width", [
					[0, 0],
					[length, barW, "power1.inOut"],
				]),
			);
			const track = host.box({
				id: ctx.partId(`progress-${i}-track`),
				position: "absolute",
				x: x0,
				y,
				width: barW,
				height: barH,
				background: theme.color.line,
				borderRadius: barH / 2,
				overflow: "hidden",
				children: [fill],
			});
			const percent = makeCounter({
				id: ctx.partId(`progress-${i}-percent`),
				to: 100,
				suffix: "%",
				style: "count",
				countDuration: length,
				ease: "power1.inOut",
				digitStagger: 0,
				fontFamily,
				fontSize: fs,
				fill: theme.color.muted,
				x: x0 + barW + adv,
				y:
					(lh - host.measure("0", { fontFamily, fontSize: fs }).lineHeight) / 2,
				theme,
			});
			content.push(
				host.box({
					id: ctx.partId(`progress-${i}`),
					position: "absolute",
					...cell(pg.row, 0),
					width: viewW,
					height: lh,
					children: [track, percent],
					...live(pg.from, line?.until ?? Number.POSITIVE_INFINITY),
				}),
			);
		});

		// ── Caret ─────────────────────────────────────────────────────────
		const caretW = props.caret === "bar" ? Math.max(2, fs * 0.08) : adv;
		const caretH =
			props.caret === "underline" ? Math.max(2, fs * 0.1) : fs * 1.15;
		const caretDy = props.caret === "underline" ? lh * 0.82 : (lh - caretH) / 2;
		const xs: KeyframeTuple[] = [];
		const ys: KeyframeTuple[] = [];
		const on: KeyframeTuple[] = [];
		const half = Math.max(1, Math.round(fps * 0.5));
		plan.caret.forEach(([f, at], k) => {
			if (at) {
				xs.push([f, at.col * adv, "hold"]);
				ys.push([f, at.row * lh + caretDy, "hold"]);
			}
			on.push([f, at ? 1 : 0, "hold"]);
			// Idle with the caret up: blink until the next change.
			const next = plan.caret[k + 1]?.[0] ?? f + fps * 6;
			if (at)
				for (
					let b = f + half * 2, shown = false;
					b < next;
					b += half, shown = !shown
				)
					on.push([b, shown ? 1 : 0, "hold"]);
		});
		const caret = host.box({
			id: ctx.partId("caret"),
			position: "absolute",
			x: 0,
			y: 0,
			width: caretW,
			height: caretH,
			background: theme.color.ink,
			opacity: 0,
		});
		caret.animate(
			LayerAnimation.create()
				.keys("x", ascending(xs))
				.keys("y", ascending(ys))
				.keys("opacity", ascending(on)),
		);
		content.push(caret);
		parts.caret = caret;

		// ── Screen and scroll ─────────────────────────────────────────────
		// Whole lines at a time: glide on new output, snap on clear. A scroll
		// that arrives mid-glide retargets the glide instead of stacking.
		const scrollY = (top: number) => pad - top * lh;
		const scrollKeys: KeyframeTuple[] = [
			[0, scrollY(plan.scroll[0]?.[1] ?? 0)],
		];
		for (const [f, top, jump] of plan.scroll.slice(1)) {
			const last = scrollKeys[scrollKeys.length - 1] as KeyframeTuple;
			if (jump)
				scrollKeys.push([Math.max(f, last[0] + 1), scrollY(top), "hold"]);
			else if (last[0] > f && last[2] !== "hold") {
				scrollKeys[scrollKeys.length - 1] = [
					f + SCROLL_GLIDE,
					scrollY(top),
					last[2] as string,
				];
			} else {
				scrollKeys.push([Math.max(f, last[0] + 1), last[1]]);
				scrollKeys.push([
					Math.max(f, last[0] + 1) + SCROLL_GLIDE,
					scrollY(top),
					"power2.out",
				]);
			}
		}
		const lines = host.box({
			id: ctx.partId("lines"),
			position: "absolute",
			x: pad,
			y: pad,
			width: cols * adv,
			// Every row, not just a screenful: children outside a box are culled.
			height: (Math.max(0, ...plan.lines.map((l) => l.row)) + 1) * lh,
			children: content,
		});
		lines.animate(LayerAnimation.keys("y", ascending(scrollKeys)));
		const screen = host.box({
			id: ctx.partId("screen"),
			position: "absolute",
			x: 0,
			y: 0,
			width: viewW,
			height: viewH,
			overflow: "hidden",
			...(props.frame === false && {
				background: theme.color.surface,
				borderRadius: theme.radius.md,
			}),
			children: [lines],
		});
		parts.lines = lines;
		parts.screen = screen;

		let root: LayoutNode = screen;
		let width = viewW;
		let height = viewH;
		if (props.frame !== false) {
			const o = props.frame === true ? {} : props.frame;
			const bar = 40 * s;
			const frameNode = bind(
				host,
				appFrame,
			)({
				id: ctx.partId("window"),
				kind: "terminal",
				width: viewW,
				height: viewH + bar,
				content: [screen],
				contentBackground: theme.color.surface,
				enter: false,
				theme,
				...(o.title !== undefined && { title: o.title }),
				...(o.elevation !== undefined && { elevation: o.elevation }),
			});
			parts.window = frameNode;
			root = frameNode;
			height = viewH + bar;
			width = viewW;
		}

		return {
			children: [root],
			width,
			height,
			duration: plan.done + 1,
			openEnded: true,
			cues: {
				keystrokes: plan.keystrokes,
				submits: plan.submits,
				outputs: plan.outputs,
				done: [{ frame: plan.done }],
			} as TerminalCues,
			parts,
		};
	},
});