cozyclay 3.1.6 → 3.2.1

package/tools/test-graph.mjs

@@ -0,0 +1,181 @@
+// Test → file dependency graph for change-based test selection (#632).
+// Each test's set is a superset of what it loads: static imports, literal
+// dynamic imports, literal spawned scripts, and every string literal in a
+// reached file that names an existing repository file or directory (which
+// covers readFileSync(new URL("../src/x.js", import.meta.url)) and
+// join(root, "src/x.js")). A test-side file whose import() or spawned script
+// path cannot be read as a literal marks the test unresolved: it always runs.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, normalize, relative } from "node:path";
+
+const CODE = /\.(?:m?js|jsx|cjs)$/;
+const EXTENSIONS = ["", ".js", ".jsx", ".mjs", ".cjs", "/index.js", "/index.jsx", "/index.mjs"];
+const STATIC_IMPORT = /\b(?:import|export)\b[^;"'`]*?\bfrom\s*(["'])([^"'\n]+)\1|\bimport\s*(["'])([^"'\n]+)\3/g;
+const DYNAMIC_IMPORT = /\bimport\(\s*([^)]*)\)/g;
+const SPAWN = /\b(?:spawn|spawnSync|execFile|execFileSync|fork)\(\s*process\.execPath\s*,\s*\[([^\]]{0,300})/g;
+// File reads and URLs: a path built at run time hides what the test reads, like a non-literal import().
+// The argument is a lookahead, so readFileSync(new URL(...)) still yields its inner new URL( match.
+const READ = /\b(?:readFileSync|readFile|createReadStream|new URL)\((?=([^\n]{0,300}))/g;
+const JOINED = /\b(?:join|resolve)\(\s*[\w.$]+\s*,((?:\s*["'][^"'$\n]+["']\s*,?)+)\)/g;
+const PATH_LITERAL = /(["'`])((?:\.{0,2}\/)?[\w@.-]+(?:\/[\w@.-]*)*)\1/g;
+const STRING = /^\s*(["'`])([^"'`$]*)\1\s*$/;
+
+// Repository-relative, forward slashes; null for anything outside the tree or in node_modules.
+function repoPath(root, absolute) {
+	const path = relative(root, absolute).replaceAll("\\", "/");
+	return path && !path.startsWith("..") && !path.split("/").includes("node_modules") ? path : null;
+}
+
+function resolveFile(root, from, specifier) {
+	if (!/^(?:\.{1,2}\/|\/)/.test(specifier)) return null; // bare package or node: builtin
+	const base = specifier.startsWith("/") ? join(root, specifier) : join(root, dirname(from), specifier);
+	for (const extension of EXTENSIONS) {
+		const candidate = normalize(base.split("?")[0] + extension);
+		if (existsSync(candidate) && statSync(candidate).isFile()) return repoPath(root, candidate);
+	}
+	return null;
+}
+
+// A literal like "src/motion3/x.js", "../src/" or "./fixtures/a.json": the
+// existing file or directory it names, relative to the file or to the root.
+function resolveLiteral(root, from, literal) {
+	if (!literal.includes("/") && !/\.\w+$/.test(literal)) return null;
+	const bases = literal.startsWith("/") ? [join(root, literal)] : [join(root, dirname(from), literal), join(root, literal)];
+	for (const base of bases) {
+		const path = existsSync(base) ? repoPath(root, base) : null;
+		if (!path || path === "." ) continue;
+		if (statSync(base).isFile()) return { file: path };
+		if (path.includes("/") || literal.endsWith("/")) return { directory: `${path}/` };
+	}
+	return null;
+}
+
+// An argument is literal when it is a string, or an expression or one-level
+// `const name = ...` binding whose path part is a string without `${`.
+function firstElement(list) {
+	let depth = 0;
+	for (let index = 0; index < list.length; index += 1) {
+		if ("([{".includes(list[index])) depth += 1;
+		else if (")]}".includes(list[index])) depth -= 1;
+		if (depth < 0 || (depth === 0 && list[index] === ",")) return list.slice(0, index);
+	}
+	return list;
+}
+
+function literalArgument(source, argument, bound = false) {
+	const text = argument.trim();
+	if (!text || STRING.test(text) || /^["']-/.test(text) || text.startsWith("`data:") || text === "fileURLToPath(import.meta.url)") return true;
+	if (/^`[\w./-]+[?#]/.test(text)) return true; // a cache-busting query on a literal path
+	if (text.includes("${") || text.includes("+")) return false;
+	if (/["'][^"'$]+["']/.test(text)) return true;
+	const name = /^([A-Za-z_$][\w$]*)(?:\.href|\.pathname)?$/.exec(text)?.[1];
+	if (!name || name === "import") return false;
+	const binding = new RegExp(`\\b(?:const|let|var)\\s+${name.replace("$", "\\$")}\\s*(?:=|of)\\s*([^;\\n]+)`).exec(source);
+	return Boolean(binding && !bound && literalArgument(source, binding[1], true));
+}
+
+function scanFile(root, file) {
+	const source = readFileSync(join(root, file), "utf8");
+	const imports = new Set();
+	const files = new Set();
+	const directories = new Set();
+	let unresolved = null;
+	for (const match of source.matchAll(STATIC_IMPORT)) imports.add(match[2] ?? match[4]);
+	for (const [, argument] of source.matchAll(DYNAMIC_IMPORT)) {
+		const literal = STRING.exec(argument)?.[2] ?? /^\s*`([\w./-]+)[?#]/.exec(argument)?.[1];
+		if (literal) imports.add(literal);
+		else if (!literalArgument(source, argument)) unresolved ??= `import(${argument.trim().slice(0, 60)})`;
+	}
+	for (const [, list] of source.matchAll(SPAWN)) {
+		const argument = firstElement(list);
+		if (!literalArgument(source, argument)) unresolved ??= `spawn(process.execPath, [${argument.trim().slice(0, 60)}])`;
+	}
+	for (const match of source.matchAll(READ)) {
+		const [call, list] = match;
+		let argument = firstElement(list);
+		// readFileSync(new URL(...)) is judged by its own new URL( match; join(root, x) by its last part.
+		if (/^\s*new URL\(/.test(argument) || literalArgument(source, argument)) continue;
+		argument = /^\s*(?:join|resolve)\(\s*[\w.$]+\s*,\s*([A-Za-z_$][\w$]*)\s*\)\s*$/.exec(argument)?.[1] ?? argument;
+		// A bare parameter of the enclosing arrow or function (`paths.map(path => readFileSync(new URL(path, ...)))`):
+		// its values are the call sites' strings, which the literal scan below already records.
+		const name = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(argument)?.[1]?.replace("$", "\\$");
+		const context = source.slice(0, match.index).split("\n").slice(-4).join("\n");
+		if (name && new RegExp(`(?:\\b${name}\\s*=>|\\(([^()]*,\\s*)?${name}\\s*(?:,[^()]*)?\\)\\s*(?:=>|\\{))`).test(context)) continue;
+		// `../src/panels/${name}.jsx`, inline or in the `const` it names: the fixed directory before the first ${.
+		const bound = name && new RegExp(`\\bconst\\s+${name}\\s*=\\s*(\`[^\`\\n]*\`)`).exec(source.slice(0, match.index).split("\n").slice(-6).join("\n"))?.[1];
+		const prefix = /`([^`$]*\/)[^`/$]*\$\{/.exec(bound ?? argument)?.[1];
+		const directory = prefix && resolveLiteral(root, file, prefix)?.directory;
+		if (directory) directories.add(directory);
+		else unresolved ??= `${call.slice(0, call.indexOf("("))}(${argument.trim().slice(0, 60)})`;
+	}
+	for (const specifier of imports) {
+		const resolved = resolveFile(root, file, specifier);
+		if (resolved) files.add(resolved);
+	}
+	for (const [, , literal] of source.matchAll(PATH_LITERAL)) {
+		const resolved = resolveLiteral(root, file, literal);
+		if (resolved?.file) files.add(resolved.file);
+		else if (resolved?.directory) directories.add(resolved.directory);
+	}
+	for (const [, segments] of source.matchAll(JOINED)) {
+		const literal = [...segments.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]).join("/");
+		const resolved = resolveLiteral(root, file, literal.includes("/") ? literal : `./${literal}`);
+		if (resolved?.file) files.add(resolved.file);
+		else if (resolved?.directory) directories.add(resolved.directory);
+	}
+	files.delete(file);
+	return { files, directories, unresolved };
+}
+
+const isTestSide = (file) => file.startsWith("test/") || /^mcp\/verify[^/]*\.mjs$/.test(file);
+
+// Per test: every reachable file, every directory a reached file names, and
+// the first non-literal load found on the test side (null when none).
+export function buildGraph(root, tests) {
+	const scans = new Map();
+	const scan = (file) => {
+		if (!scans.has(file)) scans.set(file, CODE.test(file) ? scanFile(root, file) : { files: new Set(), directories: new Set(), unresolved: null });
+		return scans.get(file);
+	};
+	const graph = new Map();
+	for (const test of tests) {
+		const files = new Set([test]);
+		const directories = new Set();
+		let unresolved = null;
+		for (const file of files) {
+			const result = scan(file);
+			for (const next of result.files) files.add(next);
+			for (const directory of result.directories) directories.add(directory);
+			if (isTestSide(file)) unresolved ??= result.unresolved && `${file}: ${result.unresolved}`;
+		}
+		graph.set(test, { files, directories, unresolved });
+	}
+	return graph;
+}
+
+// File → tests that reach it, plus the directory entries for a prefix match.
+export function reverseIndex(graph) {
+	const byFile = new Map();
+	const byDirectory = new Map();
+	for (const [test, { files, directories }] of graph) {
+		for (const file of files) byFile.set(file, [...(byFile.get(file) ?? []), test]);
+		for (const directory of directories) byDirectory.set(directory, [...(byDirectory.get(directory) ?? []), test]);
+	}
+	return (file) => {
+		const tests = new Set(byFile.get(file) ?? []);
+		for (const [directory, readers] of byDirectory) if (file.startsWith(directory)) for (const test of readers) tests.add(test);
+		return tests;
+	};
+}
+
+// The same `verify*.mjs` sweep tools/run-tests.mjs uses, to detect a test the
+// manifest does not know about.
+export function sweepVerifyFiles(root, directory) {
+	const absolute = join(root, directory);
+	if (!existsSync(absolute)) return [];
+	return readdirSync(absolute, { withFileTypes: true }).flatMap((entry) => {
+		const path = `${directory}/${entry.name}`;
+		if (entry.isDirectory()) return entry.name === "node_modules" ? [] : sweepVerifyFiles(root, path);
+		return entry.isFile() && /^verify(-.*)?\.mjs$/.test(entry.name) ? [path] : [];
+	});
+}

package/tools/test-shards.mjs

@@ -0,0 +1,78 @@
+// Duration-balanced test shards (#632). tools/test-durations.json holds the
+// per-file wall-clock seconds of a full run; `node tools/update-test-durations.mjs`
+// refreshes it from the artifacts of the latest pages.yml run on main.
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+
+export const DURATIONS_PATH = new URL("./test-durations.json", import.meta.url);
+
+export function readDurations(path = DURATIONS_PATH) {
+	return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+}
+
+// Sorted keys, seconds to one decimal: the format of tools/test-durations.json.
+export function writeDurations(path, durations) {
+	const entries = Object.entries(durations).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	writeFileSync(path, `${JSON.stringify(Object.fromEntries(entries.map(([file, seconds]) => [file, Math.round(seconds * 10) / 10])), null, "\t")}\n`);
+}
+
+function median(values) {
+	const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+	if (sorted.length === 0) return 1;
+	const middle = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+
+// A file with no recorded time counts as the median of every recorded time,
+// so a batch of new suites spreads over the shards instead of piling up.
+export function estimate(files, durations) {
+	const fallback = median(Object.values(durations));
+	return new Map(files.map((file) => [file, Number.isFinite(durations[file]) ? durations[file] : fallback]));
+}
+
+// Longest first, ties by path, so the tail of a run is never one slow suite.
+export function slowestFirst(files, durations) {
+	const seconds = estimate(files, durations);
+	return [...files].sort((a, b) => seconds.get(b) - seconds.get(a) || (a < b ? -1 : a > b ? 1 : 0));
+}
+
+// LPT: each file, longest first, goes to the shard with the smallest predicted
+// sum (lowest index on a tie). Every CI shard computes the same split from the
+// same inputs, so the shards never need to agree at run time.
+export function assignShards(files, durations, total) {
+	const seconds = estimate(files, durations);
+	const shards = Array.from({ length: total }, () => ({ files: [], predicted: 0 }));
+	for (const file of slowestFirst(files, durations)) {
+		const lightest = shards.reduce((best, shard) => (shard.predicted < best.predicted ? shard : best));
+		lightest.files.push(file);
+		lightest.predicted += seconds.get(file);
+	}
+	return shards;
+}
+
+// tools/select-tests.mjs output: null (run everything) unless mode is "selected".
+export function readSelection(path) {
+	if (!path) return null;
+	const { mode, files } = JSON.parse(readFileSync(path, "utf8"));
+	if (mode !== "selected") return null;
+	if (!Array.isArray(files)) throw new Error(`${path}: a selected run needs a files array`);
+	return new Set(files);
+}
+
+export function parseShard(value = "") {
+	const match = /^(\d+)\/(\d+)$/.exec(value);
+	const current = Number(match?.[1]);
+	const total = Number(match?.[2]);
+	if (!match || current < 1 || total < 1 || current > total) {
+		throw new Error(`--shard must be INDEX/TOTAL with 1 <= INDEX <= TOTAL, got ${value}`);
+	}
+	return { current, total };
+}
+
+// Runs once the suite ends, pass or fail: writes --durations-out and, on a CI
+// runner, one line of the job's step summary.
+export function reportDurations(timings, { out, selected, predicted }) {
+	const actual = [...timings.values()].reduce((sum, seconds) => sum + seconds, 0);
+	if (out) writeDurations(out, Object.fromEntries(timings));
+	const summary = process.env.GITHUB_STEP_SUMMARY;
+	if (summary) appendFileSync(summary, `selected ${selected}, predicted ${predicted.toFixed(1)} s, actual ${actual.toFixed(1)} s\n`);
+}

package/tools/tutorial/README.md

@@ -0,0 +1,74 @@
+# Tutorial recorder
+
+Turns an episode script into a tutorial video that points at each feature: it drives the Studio (and an install terminal) over CDP, dims the page around the feature it names in a callout, shows chapter cards, screencasts it with a visible cursor, and burns captions in the `--locale` language into a band under the frame. No voice unless asked.
+
+```
+episode (flat steps | chapters) -> record.mjs -> steps.mjs (input, overlay.mjs, terminal.mjs, Studio)
+  -> assemble.mjs (capture) -> captions.mjs (PNG per cue) -> mux.mjs (band + captions [+ voice]) -> mp4, chapter cuts
+```
+
+| Episode shape | Output |
+| --- | --- |
+| flat array of steps | `dist/tutorial/<episode>.mp4` (`<episode>-ko.mp4`), `.ko.srt`, `.en.srt` |
+| `{ title, subtitle, chapters: [{ id, title, steps }] }` | `dist/tutorial/<episode>/<episode>.<locale>.mp4`, `<nn>-<chapter>.<locale>.mp4` per chapter, `<episode>.<locale>.srt` |
+
+## Run
+
+```sh
+npm run tutorial:record -- stub-tour --locale ko
+npm run tutorial:record -- first-video --size 1920x1080
+```
+
+`launch.mjs` starts `tools/dev-full.mjs` (the Agent panel needs the agent server) with an empty config dir and no provider keys or endpoints from your shell, so the panel shows the "Connect a model" card on any machine. It runs `record.mjs` inside `tools/qa-browser.mjs` and stops both. Ports: `TUTORIAL_DEV_PORT` (5594), `CDP_PORT` (5595), `COZYCLAY_LIVE_PORT` (5596), `COZYCLAY_OAUTH_PORT` (5597).
+
+Against a dev server you already run:
+
+```sh
+QA_URL=http://127.0.0.1:5594/app/ CDP_PORT=5595 node tools/qa-browser.mjs -- node tools/tutorial/record.mjs first-video
+```
+
+Opening the Studio clears the origin's storage first (`Storage.clearDataForOrigin`), so it always shows the chooser with the name field. Downloads from an export step go to a scratch dir. One continuous capture is cut into the chapter files, so chapters join without a seam.
+
+Flags: `--locale en|ko` (UI and caption language), `--size 1600x1000|1920x1080`, `--voice off|say` (default off), `--wps-ko 1.6` and `--wps-en 2.5` (reading speed), `--fps 30`, `--out dist/tutorial`. `npm run build` empties `dist/`.
+
+## Captions and optional voice
+
+A cue without a clip lasts max(its actions, 1.2 s + its words at the video language's reading speed). With `--voice say`, voice runs before recording, because each cue then lasts its clip plus 0.4 s. Per narrated step, in order:
+
+1. Your recording: `tools/tutorial/voice/<episode>/<step-id>.<ko|en>.<wav|m4a|mp3|aiff>` (ignored by git). Use the srt as the script.
+2. macOS `say` (ko Yuna, en Samantha). A step's `speech: { ko, en }` changes what is read, not the caption.
+3. Neither: the cue is silent and holds for its word count at `--wps-ko`/`--wps-en`.
+
+Captions are PNGs drawn by the recording Chrome and laid with ffmpeg `overlay` in a band added under the frame (13% of its height), so they never cover the UI. ffmpeg needs `libx264` and `aac`; libass is not required. Korean captions need a Korean font (macOS has one; on Linux install `fonts-noto-cjk`). The mux stops if a clip is longer than its cue.
+
+Requires ffmpeg on `PATH` or in `FFMPEG`; the recorder stops with one line if it is missing.
+
+## Episodes
+
+One file per episode in `episodes/`: a `.mjs` default export or a `.json` array of steps.
+
+```js
+{ id: "select", narration: { en: "...", ko: "..." }, click: "[data-node-id=characterA]", until: ".selected" }
+```
+
+Each step has exactly one action:
+
+| Action | Value |
+| --- | --- |
+| `click` | selector, or a list clicked in order |
+| `type` | text for the focused element, or `{ into: selector, text }` (clicks the field and replaces its value) |
+| `key` | chord such as `Mod+B` or `Space` (`Mod` is Cmd on macOS, Ctrl elsewhere); a focused button is blurred first |
+| `drag` | `{ from: selector or { js: expression giving { x, y } }, to: selector or { dx, dy } }` |
+| `wait` | selector, or milliseconds |
+| `hold` | milliseconds |
+| `eval` | page expression, awaited; a result with `ok: false` stops the run |
+
+| `spotlight` | selector, with `label: { ko, en }` and optional `note`; dims the page around the element (rect read at that moment, so open menus work) and names it; `null` clears |
+| `menu` | `{ open, then }`: click `open`, then click `then`, leaving the menu open for a spotlight |
+| `card` | `"opening"` (episode title), `"closing"` (lists the titled chapters) or `{ title, subtitle }` (numbered by its chapter) |
+| `terminal` | `{ typed, lines }`: `scenes/terminal.html` types the command and prints the lines |
+| `studio` | `true`: open the Studio at its startup chooser (an episode without it starts there) |
+
+A spotlight holds for 1.2 s + its label and note at reading speed, a card for at least 2 s, a terminal for 1.5 s after its last line; `hold` beside them overrides that.
+
+`until` (optional) waits for a selector after the action. A step without narration runs inside the cue of the narrated step before it; a chapter end closes the cue. The srt entry and caption span exactly the cue. `test/verify-tutorial-recorder.mjs` validates every rule above.

package/tools/tutorial/assemble.mjs

@@ -0,0 +1,43 @@
+// ffmpeg side of the tutorial recorder: find the binary (an external
+// requirement, never an npm dependency) and turn timestamped frames into a
+// constant-rate mp4.
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { once } from "node:events";
+
+const CANDIDATES = [process.env.FFMPEG, "ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg"].filter(Boolean);
+
+/** { path, version } of the first ffmpeg that runs; throws one actionable line when none does. */
+export function findFfmpeg() {
+	for (const path of CANDIDATES) {
+		const probe = spawnSync(path, ["-version"], { encoding: "utf8" });
+		if (probe.status === 0) return { path, version: probe.stdout.split("\n")[0] };
+	}
+	throw new Error("ffmpeg not found: install it (brew install ffmpeg, apt install ffmpeg) or set FFMPEG=/path/to/ffmpeg");
+}
+
+/**
+ * Encode `frames` ([{ file, ms }] in `dir`, ms from the start of the recording,
+ * sorted) into `output` at a constant `fps`. The screencast only sends a frame
+ * when the page changes, so output frame k repeats the newest capture at
+ * k / fps, and the video lasts exactly `endMs` — the clock the srt cues use.
+ */
+export async function encode({ ffmpeg, dir, frames, endMs, fps, output }) {
+	const args = ["-hide_banner", "-loglevel", "error", "-y", "-f", "image2pipe", "-c:v", "mjpeg", "-framerate", String(fps), "-i", "-", "-vf", "scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p", "-c:v", "libx264", "-preset", "medium", "-crf", "20", "-movflags", "+faststart", output];
+	const child = spawn(ffmpeg, args, { stdio: ["pipe", "ignore", "pipe"] });
+	let stderr = "";
+	child.stderr.on("data", (chunk) => { stderr += chunk; });
+	const exited = once(child, "close");
+	let source = 0;
+	let cached = { index: -1, data: null };
+	for (let index = 0; index < Math.round((endMs / 1000) * fps); index += 1) {
+		while (source + 1 < frames.length && frames[source + 1].ms <= (index * 1000) / fps) source += 1;
+		if (cached.index !== source) cached = { index: source, data: readFileSync(join(dir, frames[source].file)) };
+		if (!child.stdin.write(cached.data)) await once(child.stdin, "drain");
+	}
+	child.stdin.end();
+	const [code] = await exited;
+	if (code !== 0) throw new Error(`ffmpeg failed (exit ${code}): ${stderr.trim()}`);
+	return `${ffmpeg} ${args.join(" ")}`;
+}

package/tools/tutorial/captions.mjs

@@ -0,0 +1,43 @@
+// Caption PNGs for the tutorial recorder, drawn by the same headless Chrome
+// that recorded the episode: one transparent image per cue, as wide as the
+// video and as tall as the caption band under it (tools/tutorial/mux.mjs).
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const FONT = `"Apple SD Gothic Neo","Noto Sans CJK KR","Noto Sans KR","Malgun Gothic",sans-serif`;
+const escape = (text) => text.replace(/[&<>]/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[character]);
+
+function captionHtml(text, width, height) {
+	const size = Math.round(width * 0.024);
+	return `<!doctype html><meta charset="utf-8"><style>
+html,body{margin:0;background:transparent}
+body{width:${width}px;height:${height}px;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,.62)}
+p{margin:0 ${Math.round(width * 0.06)}px;font:600 ${size}px/1.35 ${FONT};color:#fff;text-align:center;word-break:keep-all;overflow-wrap:normal}
+</style><p>${escape(text)}</p>`;
+}
+
+/** One PNG per text in `dir`, rendered through the open CDP page; returns their paths. */
+export async function renderCaptions(cdp, { texts, width, height, dir, language }) {
+	const loaded = cdp.once("Page.loadEventFired");
+	await cdp.send("Page.navigate", { url: "about:blank" });
+	await loaded;
+	await cdp.send("Emulation.setDefaultBackgroundColorOverride", { color: { r: 0, g: 0, b: 0, a: 0 } });
+	const paths = [];
+	for (const [index, text] of texts.entries()) {
+		const html = captionHtml(text, width, height);
+		// Korean wraps at spaces only (keep-all); a line that still overflows the
+		// width, or text taller than the band, gets a smaller font, never a broken word.
+		await cdp.evaluate(`(async () => {
+			document.open(); document.write(${JSON.stringify(html)}); document.close();
+			await document.fonts.ready;
+			const text = document.querySelector("p");
+			let size = parseFloat(getComputedStyle(text).fontSize);
+			while (size > 16 && (text.scrollWidth > text.clientWidth || text.scrollHeight > ${height})) text.style.fontSize = (size -= 2) + "px";
+		})()`);
+		const shot = await cdp.send("Page.captureScreenshot", { format: "png", clip: { x: 0, y: 0, width, height, scale: 1 } });
+		const path = join(dir, `caption-${String(index).padStart(2, "0")}.${language}.png`);
+		writeFileSync(path, Buffer.from(shot.data, "base64"));
+		paths.push(path);
+	}
+	return paths;
+}

package/tools/tutorial/cdp.mjs

@@ -0,0 +1,55 @@
+// Raw-WebSocket CDP client for the tutorial recorder: the same pattern the
+// browser suites use (test/verify-first-success-guide-browser.mjs), packaged
+// so the recorder can also listen for screencast events.
+
+export async function connectPage(port) {
+	const targets = await (await fetch(`http://127.0.0.1:${port}/json`)).json();
+	const page = targets.find((target) => target.type === "page" && target.webSocketDebuggerUrl);
+	if (!page) throw new Error("no page target on the QA browser");
+	const ws = new WebSocket(page.webSocketDebuggerUrl);
+	await new Promise((resolve, reject) => { ws.onopen = resolve; ws.onerror = reject; });
+	let nextId = 1;
+	const pending = new Map();
+	const listeners = new Map();
+	ws.onmessage = (event) => {
+		const message = JSON.parse(event.data);
+		if (message.method) for (const listener of listeners.get(message.method) ?? []) listener(message.params);
+		if (!message.id || !pending.has(message.id)) return;
+		const { resolve, reject } = pending.get(message.id);
+		pending.delete(message.id);
+		if (message.error) reject(new Error(JSON.stringify(message.error)));
+		else resolve(message.result);
+	};
+	const send = (method, params = {}) => new Promise((resolve, reject) => {
+		const id = nextId++;
+		pending.set(id, { resolve, reject });
+		ws.send(JSON.stringify({ id, method, params }));
+	});
+	const on = (method, listener) => {
+		if (!listeners.has(method)) listeners.set(method, new Set());
+		listeners.get(method).add(listener);
+		return () => listeners.get(method).delete(listener);
+	};
+	const once = (method, timeoutMs = 30000) => new Promise((resolve, reject) => {
+		const timer = setTimeout(() => { off(); reject(new Error(`timed out waiting for ${method}`)); }, timeoutMs);
+		const off = on(method, (params) => { clearTimeout(timer); off(); resolve(params); });
+	});
+	const evaluate = async (expression) => {
+		const result = await send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true });
+		if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description || "evaluate failed");
+		return result.result.value;
+	};
+	/** Resolve true once `condition` (a page expression) holds, false on timeout. */
+	const waitFor = (condition, timeoutMs = 15000) => evaluate(`new Promise((resolve) => {
+		const started = performance.now();
+		const tick = () => {
+			let value = false;
+			try { value = Boolean(${condition}); } catch {}
+			if (value) resolve(true);
+			else if (performance.now() - started > ${timeoutMs}) resolve(false);
+			else setTimeout(tick, 50);
+		};
+		tick();
+	})`);
+	return { send, on, once, evaluate, waitFor, close: () => ws.close() };
+}

package/tools/tutorial/cursor.mjs

@@ -0,0 +1,159 @@
+// Visible input for the tutorial recorder. CDP frames carry no OS cursor, so
+// the page gets a DOM pointer (pointer-events: none) that glides to each
+// target before the real Input.dispatch* event lands there, a ripple on every
+// press, and a keycap badge for each shortcut.
+
+const OVERLAY = `(() => {
+	if (window.__tutorialCursor) return;
+	const root = document.createElement("div");
+	root.className = "tt-pointer-host";
+	root.style.cssText = "position:fixed;inset:0;pointer-events:none;z-index:2147483647;transition:opacity .3s";
+	const pointer = document.createElement("div");
+	pointer.style.cssText = "position:absolute;left:0;top:0;width:28px;height:28px;filter:drop-shadow(0 1px 2px rgba(0,0,0,.35))";
+	pointer.innerHTML = '<svg viewBox="0 0 28 28" width="28" height="28"><path d="M3 2 L3 22 L8.5 17 L12.5 25.5 L16 24 L12 15.8 L19.5 15.5 Z" fill="#fff" stroke="#111" stroke-width="1.6" stroke-linejoin="round"/></svg>';
+	const keycap = document.createElement("div");
+	keycap.style.cssText = "position:absolute;left:50%;bottom:72px;transform:translateX(-50%);padding:10px 18px;border-radius:10px;background:rgba(20,20,24,.86);color:#fff;font:600 22px/1 system-ui,sans-serif;letter-spacing:.04em;opacity:0;transition:opacity .18s";
+	root.append(pointer, keycap);
+	const mount = () => document.documentElement.append(root);
+	if (document.documentElement) mount(); else document.addEventListener("DOMContentLoaded", mount);
+	let x = innerWidth / 2, y = innerHeight / 2, keycapTimer = 0;
+	const place = () => { pointer.style.transform = "translate(" + (x - 3) + "px," + (y - 2) + "px)"; };
+	place();
+	window.__tutorialCursor = {
+		moveTo(toX, toY, ms) {
+			const fromX = x, fromY = y, started = performance.now();
+			return new Promise((resolve) => {
+				const frame = (now) => {
+					const t = Math.min(1, (now - started) / Math.max(1, ms));
+					const eased = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+					x = fromX + (toX - fromX) * eased; y = fromY + (toY - fromY) * eased; place();
+					if (t < 1) requestAnimationFrame(frame); else resolve();
+				};
+				requestAnimationFrame(frame);
+			});
+		},
+		jump(toX, toY) { x = toX; y = toY; place(); },
+		ripple() {
+			const ring = document.createElement("div");
+			ring.style.cssText = "position:absolute;left:" + (x - 18) + "px;top:" + (y - 18) + "px;width:36px;height:36px;border-radius:50%;border:3px solid rgba(37,99,235,.9);background:rgba(37,99,235,.18)";
+			root.insertBefore(ring, pointer);
+			ring.animate([{ transform: "scale(.35)", opacity: 1 }, { transform: "scale(1.5)", opacity: 0 }], { duration: 520, easing: "ease-out" }).finished.then(() => ring.remove());
+		},
+		keycap(label) {
+			keycap.textContent = label; keycap.style.opacity = "1";
+			clearTimeout(keycapTimer); keycapTimer = setTimeout(() => { keycap.style.opacity = "0"; }, 1400);
+		},
+	};
+})()`;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const MODIFIER_BITS = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+const NAMED_KEYS = { Space: [" ", "Space", 32], Enter: ["Enter", "Enter", 13], Escape: ["Escape", "Escape", 27], Tab: ["Tab", "Tab", 9], Backspace: ["Backspace", "Backspace", 8], ArrowLeft: ["ArrowLeft", "ArrowLeft", 37], ArrowUp: ["ArrowUp", "ArrowUp", 38], ArrowRight: ["ArrowRight", "ArrowRight", 39], ArrowDown: ["ArrowDown", "ArrowDown", 40] };
+const MAC_GLYPHS = { Meta: "⌘", Control: "⌃", Alt: "⌥", Shift: "⇧" };
+
+/** Input helpers on one CDP page; `mac` picks Cmd for "Mod" and the keycap glyphs. */
+export function createInput(cdp, { mac }) {
+	let at = null;
+	const mouse = (type, x, y, extra = {}) => cdp.send("Input.dispatchMouseEvent", { type, x, y, button: "left", ...extra });
+	const glide = async (x, y) => {
+		const distance = at ? Math.hypot(x - at.x, y - at.y) : 600;
+		const ms = Math.round(Math.min(1100, Math.max(350, distance * 1.1)));
+		await cdp.evaluate(`window.__tutorialCursor.moveTo(${x}, ${y}, ${ms})`);
+		await mouse("mouseMoved", x, y, { button: "none" });
+		at = { x, y };
+	};
+	/** Center of a target (window.__tutorialFind, overlay.mjs), scrolled into view; null when it never shows. */
+	const locate = async (spec, timeoutMs = 10000) => {
+		const query = JSON.stringify(spec);
+		if (!(await cdp.waitFor(`!!window.__tutorialFind(${query})`, timeoutMs))) return null;
+		return cdp.evaluate(`(() => { window.__tutorialFind(${query}).el?.scrollIntoView({ block: "nearest", inline: "nearest" }); const box = window.__tutorialFind(${query}).rect; return { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) }; })()`);
+	};
+	const need = async (spec) => {
+		const point = await locate(spec);
+		if (!point) throw new Error(`no visible element for ${JSON.stringify(spec)}`);
+		return point;
+	};
+	/** A drag end: a target, or { js } evaluating to a viewport point such as a gizmo handle. */
+	const pointOf = async (source) => {
+		if (!source?.js) return need(source);
+		const point = await cdp.evaluate(`(async () => (${source.js}))()`);
+		if (!Number.isFinite(point?.x) || !Number.isFinite(point?.y)) throw new Error(`${source.js} gave no { x, y }`);
+		return { x: Math.round(point.x), y: Math.round(point.y) };
+	};
+	const press = async (point) => {
+		await glide(point.x, point.y);
+		await sleep(180);
+		await cdp.evaluate("window.__tutorialCursor.ripple()");
+		await mouse("mousePressed", point.x, point.y, { clickCount: 1, buttons: 1 });
+		await mouse("mouseReleased", point.x, point.y, { clickCount: 1 });
+		await sleep(250);
+	};
+	return {
+		/** The pointer and the teaching overlay on this page and every page the episode opens next. */
+		async install(...extra) {
+			for (const source of [OVERLAY, ...extra]) {
+				await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source });
+				await cdp.evaluate(source);
+			}
+		},
+		locate,
+		click: async (selector) => press(await need(selector)),
+		/** Glide to the element and rest there without pressing. */
+		async hover(selector) {
+			const point = await need(selector);
+			await glide(point.x, point.y);
+		},
+		async drag(from, to) {
+			const start = await pointOf(from);
+			const end = Number.isFinite(to?.dx) ? { x: start.x + to.dx, y: start.y + to.dy } : await pointOf(to);
+			await glide(start.x, start.y);
+			await cdp.evaluate("window.__tutorialCursor.ripple()");
+			await mouse("mousePressed", start.x, start.y, { clickCount: 1, buttons: 1 });
+			const steps = 45;
+			for (let index = 1; index <= steps; index += 1) {
+				const t = index / steps;
+				const eased = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+				const x = Math.round(start.x + (end.x - start.x) * eased);
+				const y = Math.round(start.y + (end.y - start.y) * eased);
+				await cdp.evaluate(`window.__tutorialCursor.jump(${x}, ${y})`);
+				await mouse("mouseMoved", x, y, { buttons: 1 });
+				await sleep(25);
+			}
+			await mouse("mouseReleased", end.x, end.y, { clickCount: 1 });
+			at = end;
+		},
+		async type(value) {
+			const { into, text } = typeof value === "string" ? { text: value } : value;
+			// The field the click found: every target form, as need() resolves it, not a bare selector.
+			const field = `window.__tutorialFind(${JSON.stringify(into)})?.el`;
+			if (into) {
+				await press(await need(into));
+				await cdp.evaluate(`${field}?.select?.()`);
+			}
+			for (const character of text) {
+				await cdp.send("Input.insertText", { text: character });
+				await sleep(70);
+			}
+			// A React-controlled input can drop inserted text; the native setter plus an input event cannot be missed.
+			if (into) await cdp.evaluate(`(() => {
+				const input = ${field};
+				if (!input || input.value === ${JSON.stringify(text)}) return;
+				Object.getOwnPropertyDescriptor(Object.getPrototypeOf(input), "value").set.call(input, ${JSON.stringify(text)});
+				input.dispatchEvent(new Event("input", { bubbles: true }));
+			})()`);
+		},
+		async key(chord) {
+			const parts = chord.split("+").map((part) => (part === "Mod" ? (mac ? "Meta" : "Control") : part === "Ctrl" ? "Control" : part === "Cmd" ? "Meta" : part));
+			const name = parts.pop();
+			const modifiers = parts.reduce((bits, part) => bits | (MODIFIER_BITS[part] ?? 0), 0);
+			const [key, code, keyCode] = NAMED_KEYS[name] ?? (/^\d$/.test(name) ? [name, `Digit${name}`, name.charCodeAt(0)] : [name.toLowerCase(), `Key${name.toUpperCase()}`, name.toUpperCase().charCodeAt(0)]);
+			const label = mac ? parts.map((part) => MAC_GLYPHS[part]).join("") + name : [...parts.map((part) => (part === "Control" ? "Ctrl" : part)), name].join("+");
+			// A focused button swallows Space and Cmd/Ctrl+B (src/motion/timeline.jsx), so the chord goes to the page.
+			await cdp.evaluate(`window.__tutorialCursor.keycap(${JSON.stringify(label)}); if (document.activeElement?.tagName === "BUTTON") document.activeElement.blur();`);
+			await sleep(350);
+			const event = { key, code, windowsVirtualKeyCode: keyCode, modifiers };
+			await cdp.send("Input.dispatchKeyEvent", { type: "keyDown", ...event, ...(key.length === 1 && !(modifiers & 6) ? { text: key } : {}) });
+			await cdp.send("Input.dispatchKeyEvent", { type: "keyUp", ...event });
+		},
+	};
+}