cozyclay 3.2.0 → 3.2.1

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 });
+		},
+	};
+}

package/tools/tutorial/episode.mjs

@@ -0,0 +1,173 @@
+// Episode schema, step timing and the srt writer for the tutorial recorder.
+// Pure functions, so test/verify-tutorial-recorder.mjs checks them without a
+// browser.
+//
+// An episode is a flat array of steps, or { title, subtitle?, chapters: [{ id, title?, steps }] }.
+// A target is "<css>" (first visible match), { css, text } (first visible match containing
+// text), { js } (an expression giving an element or rect; a point for drag), an array (the
+// union, spotlight only), or { ko, en } holding one target per UI language.
+// A step is { id, narration?: { ko, en }, <one action>, until? }:
+//   click: target or [target, ...]       eased cursor move, then a real click on each
+//   type:  "text" | { into: "<css>", text }  typed into the focused element, or
+//                                        into `into` after clicking it and selecting its value
+//   key:   "Mod+B" | "Space" | ...       one chord; Mod is Cmd on macOS, Ctrl elsewhere
+//   drag:  { from, to }                  from: "<css>" or { js: "<expression giving { x, y }>" };
+//                                        to: "<css>" or { dx, dy } from the start
+//   wait:  "<css>" | ms                  until the element shows, or a pause
+//   hold:  ms                            keep the frame still (alone), or how long a
+//                                        spotlight, card or terminal stays (beside it)
+//   eval:  "<js>"                        run in the page and awaited (setup the viewer does not see)
+//   spotlight: target | null, label?: { ko, en }, note?: { ko, en }, glide?: false
+//                                        dim the page around the target, name it in a callout; null clears;
+//                                        glide: false skips the cursor move (a toast that lives 2 s)
+//   menu:  { open: target, then: target }  click open, then click then (File > Export)
+//   card:  "opening" | "closing" | { title: { ko, en }, subtitle?: { ko, en }, chapters?: true }
+//                                        chapters: true lists the titled chapters under it
+//   terminal: { print?: [...], type?: "npx cozyclay", fresh? }  the install scene: print lines,
+//                                        then type on the last line and press Enter; continues the
+//                                        page an earlier terminal step left, unless fresh
+//   studio: true                         open the Studio at its startup chooser
+// `until` is a selector the step waits for after its action. A step without
+// narration joins the cue of the narrated step before it. `speech: { ko?, en? }`
+// replaces what the voice reads (tools/tutorial/voice.mjs), not the caption.
+
+const ACTIONS = ["click", "type", "key", "drag", "wait", "eval", "spotlight", "menu", "card", "terminal", "studio"];
+const HELD = ["spotlight", "card", "terminal"];
+const LANGUAGES = ["ko", "en"];
+const isText = (value) => typeof value === "string" && value.trim().length > 0;
+const isMs = (value) => Number.isFinite(value) && value >= 0;
+const isPair = (value) => LANGUAGES.every((language) => isText(value?.[language]));
+const isLocalized = (value) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join() === "en,ko";
+
+/** A target as the episode may write it (see the header). */
+export function isTarget(value, { union = false } = {}) {
+	if (isText(value)) return true;
+	if (Array.isArray(value)) return union && value.length > 0 && value.every((item) => isTarget(item));
+	if (isLocalized(value)) return LANGUAGES.every((language) => isTarget(value[language], { union }));
+	if (isText(value?.js)) return true;
+	return isText(value?.css) && (value.text === undefined || isText(value.text) || (isLocalized(value.text) && isPair(value.text)));
+}
+
+/** The target for one UI language: { ko, en } maps and localized texts resolved. */
+export function localizeTarget(value, language) {
+	if (Array.isArray(value)) return value.map((item) => localizeTarget(item, language));
+	if (isLocalized(value)) return localizeTarget(value[language], language);
+	if (value && typeof value === "object" && isLocalized(value.text)) return { ...value, text: value.text[language] };
+	return value;
+}
+
+function actionError(name, value, step) {
+	if (name === "click") return (isTarget(value) || (Array.isArray(value) && value.length > 0 && value.every((item) => isTarget(item)))) ? null : "click needs a target or a non-empty target list";
+	if (name === "type") return isText(value) || (isTarget(value?.into) && isText(value?.text)) ? null : "type needs text, or { into, text }";
+	if (name === "key") return isText(value) ? null : "key needs a chord such as Mod+B";
+	if (name === "drag") return isTarget(value?.from) && (isTarget(value?.to) || (Number.isFinite(value?.to?.dx) && Number.isFinite(value?.to?.dy))) ? null : "drag needs from (target) and to (target or { dx, dy })";
+	if (name === "eval") return isText(value) ? null : "eval needs a page expression";
+	if (name === "wait") return isTarget(value) || isMs(value) ? null : "wait needs a target or milliseconds";
+	if (name === "spotlight") return value === null || (isTarget(value, { union: true }) && (step.label === undefined || isPair(step.label)) && (step.note === undefined || (isPair(step.note) && step.label))) ? null : "spotlight needs a target (label { ko, en } and note optional), or null";
+	if (name === "menu") return isTarget(value?.open) && isTarget(value?.then) ? null : "menu needs { open, then } targets";
+	if (name === "card") return value === "opening" || value === "closing" || (isPair(value?.title) && (value.subtitle === undefined || isPair(value.subtitle)) && (value.chapters === undefined || value.chapters === true)) ? null : "card needs \"opening\", \"closing\" or { title: { ko, en }, subtitle?, chapters? }";
+	if (name === "terminal") return value && typeof value === "object" && (value.type === undefined || isText(value.type)) && (value.print === undefined || (Array.isArray(value.print) && value.print.every((line) => typeof line === "string"))) && Object.keys(value).every((key) => ["print", "type", "fresh"].includes(key)) ? null : "terminal needs { print?: [lines], type?: text, fresh? }";
+	if (name === "studio") return value === true ? null : "studio must be true";
+	return isMs(value) ? null : "hold needs milliseconds";
+}
+
+/** The action a step performs; `hold` only when nothing else is there. */
+export const actionOf = (step) => ACTIONS.find((name) => Object.hasOwn(step, name)) ?? (Object.hasOwn(step, "hold") ? "hold" : undefined);
+
+/**
+ * { title, subtitle, chaptered, firstChapter, chapters: [{ id, title, steps }] } from either
+ * episode shape. `firstChapter` is the number the first chapter carries (default 1).
+ */
+export function normalizeEpisode(episode) {
+	if (Array.isArray(episode)) return { title: null, subtitle: null, chaptered: false, firstChapter: 1, chapters: [{ id: "main", title: null, steps: episode }] };
+	return { title: episode?.title ?? null, subtitle: episode?.subtitle ?? null, chaptered: true, firstChapter: episode?.firstChapter ?? 1, chapters: episode?.chapters ?? [] };
+}
+
+function stepErrors(step, label) {
+	const errors = [];
+	if (step && Object.hasOwn(step, "narration") && !isPair(step.narration)) errors.push(`${label}: narration needs ko and en`);
+	const actions = ACTIONS.filter((name) => Object.hasOwn(step ?? {}, name));
+	const action = actionOf(step ?? {});
+	if (actions.length > 1 || !action) errors.push(`${label}: needs exactly one action of ${[...ACTIONS, "hold"].join(", ")} (found ${actions.length})`);
+	else {
+		const problem = actionError(action, step[action], step);
+		if (problem) errors.push(`${label}: ${problem}`);
+		if (action !== "hold" && Object.hasOwn(step, "hold") && !(HELD.includes(action) && isMs(step.hold))) errors.push(`${label}: hold only times a spotlight, card or terminal`);
+	}
+	if (step && Object.hasOwn(step, "until") && !isTarget(step.until)) errors.push(`${label}: until must be a target`);
+	if (step && Object.hasOwn(step, "speech")) {
+		if (!step.narration) errors.push(`${label}: speech needs narration`);
+		for (const [language, text] of Object.entries(step.speech ?? {})) if (!LANGUAGES.includes(language) || !isText(text)) errors.push(`${label}: speech.${language} must be ko or en text`);
+	}
+	const allowed = ["id", "narration", "speech", "until", "hold", "label", "note", "glide", ...ACTIONS];
+	const unknown = Object.keys(step ?? {}).filter((key) => !allowed.includes(key) || (["label", "note", "glide"].includes(key) && action !== "spotlight") || (key === "glide" && step.glide !== false));
+	if (unknown.length) errors.push(`${label}: unknown field ${unknown.join(", ")}`);
+	return errors;
+}
+
+/** Every problem in an episode, as "<where>: <problem>" lines; empty when valid. */
+export function validateEpisode(episode) {
+	const { title, chaptered, chapters } = normalizeEpisode(episode);
+	if (chaptered && (!Array.isArray(chapters) || chapters.length === 0)) return ["an episode object needs a non-empty chapters array"];
+	const errors = Number.isInteger(normalizeEpisode(episode).firstChapter) && normalizeEpisode(episode).firstChapter >= 0 ? [] : ["firstChapter must be a whole number"];
+	const seen = new Set();
+	const chapterIds = new Set();
+	for (const chapter of chapters) {
+		if (chaptered && !/^[a-z0-9-]+$/.test(chapter?.id ?? "")) errors.push(`chapter ${chapter?.id}: id must be lowercase letters, digits and dashes`);
+		else if (chapterIds.has(chapter.id)) errors.push(`chapter ${chapter.id}: duplicate id`);
+		chapterIds.add(chapter?.id);
+		if (chapter?.title !== undefined && chapter?.title !== null && !isPair(chapter.title)) errors.push(`chapter ${chapter.id}: title needs ko and en`);
+		if (!Array.isArray(chapter?.steps) || chapter.steps.length === 0) {
+			errors.push(chaptered ? `chapter ${chapter?.id}: needs steps` : "an episode is a non-empty array of steps");
+			continue;
+		}
+		chapter.steps.forEach((step, index) => {
+			const label = `step ${step?.id ?? `#${index + 1}`}`;
+			if (!isText(step?.id)) errors.push(`${label}: id must be a non-empty string`);
+			else if (seen.has(step.id)) errors.push(`${label}: duplicate id`);
+			seen.add(step?.id);
+			errors.push(...stepErrors(step, label));
+			if (step?.card === "opening" && !isPair(title)) errors.push(`${label}: an opening card needs the episode title { ko, en }`);
+		});
+	}
+	return errors;
+}
+
+/** Reading speed with no voice: Korean `say` measures 1.7-1.9 words/s, so 1.6 leaves room. */
+export const DEFAULT_WPS = { ko: 1.6, en: 2.5 };
+
+/**
+ * 1.2 s to take in the new screen, then the words at that language's speed:
+ * the video's own language, or the slower of the two when none is given.
+ */
+export function readingMs(text, wps, language = null) {
+	const words = (value) => value.trim().split(/\s+/).filter(Boolean).length;
+	return 1200 + Math.max(...(language ? [language] : LANGUAGES).map((name) => words(text[name]) / wps[name])) * 1000;
+}
+
+/** The ko/en texts joined, for reading time of a callout or card. */
+export const joinTexts = (...pairs) => Object.fromEntries(LANGUAGES.map((language) => [language, pairs.filter(Boolean).map((pair) => pair[language]).join(" ")]));
+
+/**
+ * How long a cue stays on screen: its clip plus a 0.4 s breath when there is
+ * voice, the reading estimate otherwise, and never less than its actions.
+ * The epsilon keeps float noise (4.66 * 1000 = 4660.000000000001) from adding a millisecond.
+ */
+export const stepHoldMs = (actionMs, narration, wps, audioS = null, language = null) => Math.max(actionMs, audioS === null ? readingMs(narration, wps, language) : Math.ceil(audioS * 1000 - 1e-6) + 400);
+
+/** dist/tutorial/<episode>/<nn>-<id>.<locale>.mp4 for the chapter numbered `number`. */
+export const chapterFileName = (number, id, locale) => `${String(number).padStart(2, "0")}-${id}.${locale}.mp4`;
+
+export function srtTime(ms) {
+	const total = Math.max(0, Math.round(ms));
+	const pad = (value, width = 2) => String(value).padStart(width, "0");
+	const hours = Math.floor(total / 3600000);
+	const minutes = Math.floor(total / 60000) % 60;
+	const seconds = Math.floor(total / 1000) % 60;
+	return `${pad(hours)}:${pad(minutes)}:${pad(seconds)},${pad(total % 1000, 3)}`;
+}
+
+/** One srt track from [{ startMs, endMs, narration }] in the given language. */
+export function toSrt(cues, language) {
+	return cues.map((cue, index) => `${index + 1}\n${srtTime(cue.startMs)} --> ${srtTime(cue.endMs)}\n${cue.narration[language]}\n`).join("\n");
+}