cozyclay 3.1.6 → 3.2.1

package/tools/tutorial/record.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Records one tutorial episode: optional voice clips first (voice.mjs), then
+// one continuous capture over CDP (steps.mjs runs each step, the page carries
+// the cursor and teaching overlays), then captions in a band under the frame
+// and the mux (mux.mjs). A chaptered episode is also cut into one file per
+// chapter. Run it through tools/tutorial/launch.mjs (npm run tutorial:record
+// -- <episode>) or inside tools/qa-browser.mjs with QA_URL pointing at a dev
+// server. See tools/tutorial/README.md.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { encode, findFfmpeg } from "./assemble.mjs";
+import { renderCaptions } from "./captions.mjs";
+import { connectPage } from "./cdp.mjs";
+import { createInput } from "./cursor.mjs";
+import { DEFAULT_WPS, actionOf, chapterFileName, normalizeEpisode, stepHoldMs, toSrt, validateEpisode } from "./episode.mjs";
+import { bandHeightFor, chapterCutArgs, muxArgs } from "./mux.mjs";
+import { TEACHING_OVERLAY } from "./overlay.mjs";
+import { localeScript, openStudio, runStep } from "./steps.mjs";
+import { TERMINAL_URL } from "./terminal.mjs";
+import { prepareVoice } from "./voice.mjs";
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, Math.max(0, ms)));
+
+function parseArgs(argv) {
+	const options = { episode: null, locale: "en", size: "1600x1000", "wps-ko": DEFAULT_WPS.ko, "wps-en": DEFAULT_WPS.en, voice: "off", fps: 30, out: "dist/tutorial" };
+	for (let index = 0; index < argv.length; index += 1) {
+		const flag = argv[index];
+		if (flag.startsWith("--")) options[flag.slice(2)] = argv[(index += 1)];
+		else options.episode = flag;
+	}
+	const [width, height] = String(options.size).split("x").map(Number);
+	if (!options.episode) throw new Error("usage: record.mjs <episode> [--locale en|ko] [--size 1600x1000|1920x1080] [--voice off|say] [--wps-ko 1.6] [--wps-en 2.5] [--fps 30] [--out dist/tutorial]");
+	if (!["en", "ko"].includes(options.locale)) throw new Error(`--locale must be en or ko (got ${options.locale})`);
+	if (!(width > 0 && height > 0)) throw new Error(`--size must look like 1600x1000 (got ${options.size})`);
+	if (!["off", "say"].includes(options.voice)) throw new Error(`--voice must be off or say (got ${options.voice})`);
+	return { ...options, width, height, wps: { ko: Number(options["wps-ko"]), en: Number(options["wps-en"]) }, fps: Number(options.fps) };
+}
+
+async function loadEpisode(name) {
+	const base = existsSync(name) ? resolve(name) : resolve(import.meta.dirname, "episodes", name);
+	const file = [base, `${base}.mjs`, `${base}.json`].find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
+	if (!file) throw new Error(`no episode ${name} (looked in tools/tutorial/episodes/)`);
+	const episode = file.endsWith(".json") ? JSON.parse(readFileSync(file, "utf8")) : (await import(pathToFileURL(file).href)).default;
+	const errors = validateEpisode(episode);
+	if (errors.length) throw new Error(`episode ${name} is invalid:\n  ${errors.join("\n  ")}`);
+	return normalizeEpisode(episode);
+}
+
+const run = (ffmpeg, args, what) => {
+	const result = spawnSync(ffmpeg, args, { encoding: "utf8" });
+	if (result.status !== 0) throw new Error(`ffmpeg ${what} failed (exit ${result.status}): ${result.stderr.trim()}`);
+};
+
+const options = parseArgs(process.argv.slice(2));
+const ffmpeg = findFfmpeg();
+console.log(`ffmpeg: ${ffmpeg.path} (${ffmpeg.version})`);
+const episode = await loadEpisode(options.episode);
+const steps = episode.chapters.flatMap((chapter) => chapter.steps);
+const episodeName = options.episode.replace(/^.*\//, "").replace(/\.(mjs|json)$/, "");
+const outDir = episode.chaptered ? join(options.out, episodeName) : options.out;
+const fullPath = episode.chaptered ? join(outDir, `${episodeName}.${options.locale}.mp4`) : join(outDir, `${options.locale === "en" ? episodeName : `${episodeName}-${options.locale}`}.mp4`);
+const frameDir = mkdtempSync(join(tmpdir(), "cozyclay-tutorial-"));
+// Voice first: each cue's hold comes from its clip, so the clips exist before the capture.
+const clips = options.voice === "say" ? prepareVoice({ steps, language: options.locale, voiceDir: resolve(import.meta.dirname, "voice", episodeName), workDir: frameDir, ffprobe: ffmpeg.path.replace(/ffmpeg$/, "ffprobe") }) : new Map();
+console.log(clips.size ? `voice (${options.locale}): ${clips.size} clips` : `voice (${options.locale}): off, captions only`);
+const url = process.env.QA_URL || "http://127.0.0.1:5594/app/";
+const cdp = await connectPage(Number(process.env.CDP_PORT || 9222));
+try {
+	// An export step's download lands in the scratch dir, never in the user's Downloads.
+	await cdp.send("Browser.setDownloadBehavior", { behavior: "allow", downloadPath: join(frameDir, "downloads") });
+	await cdp.send("Emulation.setDeviceMetricsOverride", { width: options.width, height: options.height, deviceScaleFactor: 1, mobile: false });
+	await cdp.send("Page.enable");
+	const input = createInput(cdp, { mac: (await cdp.evaluate("navigator.platform")).startsWith("Mac") });
+	await input.install(TEACHING_OVERLAY, localeScript(new URL(url).origin, options.locale));
+	// An episode that opens the Studio itself starts on its first scene; otherwise on the chooser.
+	const firstScene = steps.map(actionOf).find((action) => action === "terminal" || action === "studio");
+	if (firstScene === "terminal") {
+		const loaded = cdp.once("Page.loadEventFired");
+		await cdp.send("Page.navigate", { url: TERMINAL_URL });
+		await loaded;
+	} else if (!firstScene) await openStudio(cdp, url);
+
+	const frames = [];
+	let started = 0;
+	cdp.on("Page.screencastFrame", ({ data, sessionId }) => {
+		void cdp.send("Page.screencastFrameAck", { sessionId }).catch(() => {});
+		const at = Date.now();
+		if (!started) started = at;
+		const file = `${String(frames.length).padStart(6, "0")}.jpg`;
+		writeFileSync(join(frameDir, file), Buffer.from(data, "base64"));
+		frames.push({ file, ms: at - started });
+	});
+	const firstFrame = cdp.once("Page.screencastFrame", 10000);
+	await cdp.send("Page.startScreencast", { format: "jpeg", quality: 90, maxWidth: options.width, maxHeight: options.height, everyNthFrame: 1 });
+	await firstFrame;
+	const clock = () => Date.now() - started;
+	await sleep(500);
+
+	// A narrated step opens a cue; the silent steps after it run inside that cue,
+	// and the cue closes once the narration has had its time, or at a chapter end.
+	const cues = [];
+	const marks = [];
+	const timeline = [];
+	let open = null;
+	const closeCue = async () => {
+		if (!open) return;
+		await sleep(open.startMs + stepHoldMs(clock() - open.startMs, open.narration, options.wps, clips.get(open.id)?.audioS ?? null, options.locale) - clock());
+		cues.push({ ...open, endMs: clock() });
+		open = null;
+	};
+	for (const chapter of episode.chapters) {
+		await closeCue();
+		marks.push({ chapter, startMs: marks.length ? clock() : 0 });
+		for (const step of chapter.steps) {
+			// A card is a new scene: the caption before it ends where it starts.
+			if (step.narration || step.card) {
+				await closeCue();
+				if (step.narration) open = { id: step.id, startMs: clock(), narration: step.narration };
+			}
+			const stepStart = clock();
+			await runStep({ cdp, input, wps: options.wps, locale: options.locale, url, episode, chapter }, step);
+			timeline.push({ chapter: chapter.id, id: step.id, action: actionOf(step), startMs: stepStart, endMs: clock() });
+		}
+		console.log(`chapter ${chapter.id}: ${((clock() - marks.at(-1).startMs) / 1000).toFixed(1)}s`);
+	}
+	await closeCue();
+	await sleep(800);
+	const endMs = clock();
+	await cdp.send("Page.stopScreencast");
+	if (frames.length === 0) throw new Error("the screencast produced no frames");
+
+	mkdirSync(outDir, { recursive: true });
+	const base = join(frameDir, "capture.mp4");
+	console.log(`ffmpeg command: ${await encode({ ffmpeg: ffmpeg.path, dir: frameDir, frames, endMs, fps: options.fps, output: base })}`);
+	const bandHeight = bandHeightFor(options.height);
+	const captions = await renderCaptions(cdp, { texts: cues.map((cue) => cue.narration[options.locale]), width: options.width, height: bandHeight, dir: frameDir, language: options.locale });
+	run(ffmpeg.path, muxArgs({ base, output: fullPath, cues, clips, captions, endMs, bandHeight }), "mux");
+	console.log(`ffmpeg mux: ${clips.size ? "h264 + aac" : "h264, no audio"}, ${captions.length} captions, ${options.width}x${options.height + bandHeight}`);
+	const srtBase = fullPath.replace(/\.mp4$/, "");
+	for (const language of episode.chaptered ? [options.locale] : ["ko", "en"]) writeFileSync(`${srtBase}${episode.chaptered ? "" : `.${language}`}.srt`, toSrt(cues, language));
+	// When each step ran, for QA frames (one per spotlight) and for timing a re-record.
+	writeFileSync(`${srtBase}.steps.json`, `${JSON.stringify(timeline, null, "\t")}\n`);
+	console.log(`wrote ${fullPath} (${(endMs / 1000).toFixed(1)}s, ${frames.length} frames)`);
+	if (episode.chaptered) marks.forEach((mark, index) => {
+		const endAt = index + 1 < marks.length ? marks[index + 1].startMs : endMs;
+		const output = join(outDir, chapterFileName(episode.firstChapter + index, mark.chapter.id, options.locale));
+		run(ffmpeg.path, chapterCutArgs({ input: fullPath, output, startMs: mark.startMs, endMs: endAt, audio: clips.size > 0 }), `cut ${mark.chapter.id}`);
+		console.log(`wrote ${output} (${((endAt - mark.startMs) / 1000).toFixed(1)}s)`);
+	});
+} finally {
+	cdp.close();
+	rmSync(frameDir, { recursive: true, force: true });
+}

package/tools/tutorial/scenes/terminal.html

@@ -0,0 +1,63 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Terminal</title>
+<style>
+	html, body { margin: 0; height: 100%; background: #2b2f36; }
+	body { display: flex; align-items: center; justify-content: center; }
+	.window { width: 1240px; height: 700px; border-radius: 12px; overflow: hidden; background: #16181d; box-shadow: 0 30px 80px rgba(0, 0, 0, .5); display: flex; flex-direction: column; }
+	.bar { height: 40px; display: flex; align-items: center; gap: 9px; padding: 0 16px; background: #23262d; color: #9aa3b2; font: 500 15px/1 system-ui, sans-serif; }
+	.bar i { width: 13px; height: 13px; border-radius: 50%; background: #4b5160; }
+	.bar span { flex: 1; text-align: center; margin-right: 60px; }
+	pre { flex: 1; margin: 0; padding: 26px 30px; color: #e5e7eb; font: 23px/1.6 ui-monospace, "DejaVu Sans Mono", "Noto Sans Mono", monospace; white-space: pre-wrap; }
+	.line { min-height: 1.6em; }
+	.prompt { color: #7dd3a7; }
+	.out { color: #b6bfcc; }
+	.caret { display: inline-block; width: .6em; height: 1.1em; vertical-align: -.18em; background: #e5e7eb; animation: blink 1s steps(1) infinite; }
+	@keyframes blink { 50% { opacity: 0; } }
+</style>
+</head>
+<body>
+<div class="window">
+	<div class="bar"><i></i><i></i><i></i><span>Terminal</span></div>
+	<pre id="screen"><div class="line"><span class="prompt">~ $ </span><span class="text"></span></div></pre>
+</div>
+<script>
+	// Played by tools/tutorial/terminal.mjs: events [{ at, kind: "line" | "char" | "enter", text }].
+	// A line prints on a new row (or fills the empty row an Enter left), a char
+	// types on the last row, an Enter opens an empty row. The caret follows.
+	const screen = document.getElementById("screen");
+	const caret = document.createElement("span");
+	caret.className = "caret";
+	const last = () => screen.lastElementChild;
+	const textOf = (line) => line.querySelector(".text");
+	const newLine = (className = "") => {
+		const line = document.createElement("div");
+		line.className = "line";
+		const text = document.createElement("span");
+		text.className = "text " + className;
+		line.append(text);
+		screen.append(line);
+		return line;
+	};
+	const placeCaret = () => last().append(caret);
+	placeCaret();
+	window.__terminal = {
+		play(events) {
+			for (const event of events) setTimeout(() => {
+				if (event.kind === "char") textOf(last()).textContent += event.text;
+				else if (event.kind === "enter") newLine();
+				else {
+					const blank = !last().querySelector(".prompt") && !textOf(last()).textContent;
+					const line = blank ? last() : newLine();
+					textOf(line).classList.add("out");
+					textOf(line).textContent = event.text;
+				}
+				placeCaret();
+			}, event.at);
+		},
+	};
+</script>
+</body>
+</html>

package/tools/tutorial/steps.mjs

@@ -0,0 +1,111 @@
+// Runs one episode step against the page: input actions through cursor.mjs,
+// teaching overlays through overlay.mjs, the install scene through
+// terminal.mjs, and the Studio itself.
+import { actionOf, joinTexts, localizeTarget, readingMs } from "./episode.mjs";
+import { playTerminal } from "./terminal.mjs";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+const CLOSING_TITLE = { ko: "이번 영상에서 본 것", en: "What we covered" };
+const CHAPTER = { ko: (number) => `챕터 ${number}`, en: (number) => `Chapter ${number}` };
+
+/** Runs on every new document: the chosen UI language before the Studio's own scripts read it. */
+export const localeScript = (origin, locale) => `if (location.origin === ${JSON.stringify(origin)}) { try { localStorage.setItem("cozyclay.locale", ${JSON.stringify(locale)}); } catch {} }`;
+
+/** Empty origin storage (no project session, no saved projects), then the Studio: the chooser a first-time author sees. */
+export async function openStudio(cdp, url) {
+	const origin = new URL(url).origin;
+	// A Studio still open on the origin could write its session back after the clear.
+	if ((await cdp.evaluate("location.origin")) === origin) {
+		const blank = cdp.once("Page.loadEventFired");
+		await cdp.send("Page.navigate", { url: "about:blank" });
+		await blank;
+	}
+	await cdp.send("Storage.clearDataForOrigin", { origin, storageTypes: "all" });
+	const loaded = cdp.once("Page.loadEventFired");
+	await cdp.send("Page.navigate", { url });
+	await loaded;
+}
+
+/** An action value with every target in it resolved for the UI language. */
+function localizeStep(value, local) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(local);
+	if (Object.hasOwn(value, "from")) return { from: local(value.from), to: Number.isFinite(value.to?.dx) ? value.to : local(value.to) };
+	if (Object.hasOwn(value, "open")) return { open: local(value.open), then: local(value.then) };
+	if (Object.hasOwn(value, "into")) return { ...value, into: local(value.into) };
+	return local(value);
+}
+
+/** The words a card shows, in `locale`. */
+function cardContent(step, { episode, chapter, locale }) {
+	const titled = episode.chapters.filter((item) => item.title);
+	if (step.card === "opening") return { eyebrow: "CozyClay", title: episode.title[locale], subtitle: episode.subtitle?.[locale] };
+	// Titles that carry their own number ("2 · Layout tour") are listed as they are.
+	const titles = titled.map((item) => item.title[locale]);
+	const items = titles.length ? { titles, numbered: !titles.every((title) => /^\d/.test(title)) } : null;
+	if (step.card === "closing") return { title: CLOSING_TITLE[locale], items };
+	// A title that already carries its number ("2 · Layout tour") gets no "Chapter N" above it.
+	const number = episode.chapters.indexOf(chapter) + episode.firstChapter;
+	const title = step.card.title[locale];
+	if (step.card.chapters) return { title, subtitle: step.card.subtitle?.[locale], items };
+	return { eyebrow: chapter.title && !/^\d/.test(title) ? CHAPTER[locale](number) : null, title, subtitle: step.card.subtitle?.[locale] };
+}
+
+/** Reading time of a card in the video's language, for its default hold (2 s at least). */
+function cardReadingMs(step, context, wps) {
+	const { eyebrow, title, subtitle, items } = cardContent(step, context);
+	const words = [eyebrow, title, subtitle, ...(items?.titles ?? [])].filter(Boolean).join(" ");
+	return Math.max(2000, readingMs({ [context.locale]: words }, wps, context.locale));
+}
+
+/**
+ * Run `step`. `context` carries { cdp, input, wps, locale, url, episode, chapter }:
+ * the normalized episode and the chapter the step belongs to.
+ */
+export async function runStep(context, step) {
+	const { cdp, input, wps, url } = context;
+	const action = actionOf(step);
+	const local = (target) => localizeTarget(target, context.locale);
+	const value = ["click", "wait", "spotlight", "drag", "menu", "type"].includes(action) ? localizeStep(step[action], local) : step[action];
+	if (action === "click") for (const target of Array.isArray(value) ? value : [value]) await input.click(target);
+	else if (action === "type") await input.type(value);
+	else if (action === "key") await input.key(value);
+	else if (action === "drag") await input.drag(value.from, value.to);
+	else if (action === "hold") await sleep(value);
+	else if (action === "eval") {
+		const result = await cdp.evaluate(`(async () => (${value}))()`);
+		if (result?.ok === false) throw new Error(`step ${step.id}: eval returned ${JSON.stringify(result)}`);
+	} else if (action === "wait") {
+		if (typeof value === "number") await sleep(value);
+		else if (!(await input.locate(value, 20000))) throw new Error(`step ${step.id}: ${JSON.stringify(value)} never showed`);
+	} else if (action === "spotlight") {
+		if (value === null) {
+			await cdp.evaluate("window.__tutorialOverlay.clear()");
+			await sleep(350);
+		} else {
+			// The rect is read now, after any menu or scroll the earlier steps opened.
+			if (step.glide !== false) await input.hover(value);
+			const shown = await cdp.evaluate(`window.__tutorialOverlay.spotlight(${JSON.stringify(value)}, ${JSON.stringify(step.label?.[context.locale] ?? "")}, ${JSON.stringify(step.note?.[context.locale] ?? "")})`);
+			if (!shown) throw new Error(`step ${step.id}: ${JSON.stringify(value)} is not on the page`);
+			await sleep(step.hold ?? readingMs(joinTexts(step.label, step.note), wps, context.locale));
+		}
+	} else if (action === "menu") {
+		await input.click(value.open);
+		await input.click(value.then);
+	} else if (action === "card") {
+		await cdp.evaluate("window.__tutorialOverlay.clear()");
+		await cdp.evaluate(`window.__tutorialOverlay.card(${JSON.stringify(cardContent(step, context))})`);
+		await sleep(step.hold ?? cardReadingMs(step, context, wps));
+		await cdp.evaluate("window.__tutorialOverlay.hideCard()");
+		await sleep(350);
+	} else if (action === "terminal") {
+		await playTerminal(cdp, value);
+		await sleep(step.hold ?? 1500);
+	} else if (action === "studio") {
+		await openStudio(cdp, url);
+		if (!(await cdp.waitFor("document.querySelector('.v2-start-screen')", 20000))) throw new Error(`step ${step.id}: the startup chooser never showed`);
+	}
+	if (step.until && !(await cdp.waitFor(`!!window.__tutorialFind(${JSON.stringify(local(step.until))})`, 20000))) {
+		throw new Error(`step ${step.id}: ${JSON.stringify(step.until)} never showed`);
+	}
+}

package/tools/tutorial/terminal.mjs

@@ -0,0 +1,43 @@
+// The install scene: a local terminal page (scenes/terminal.html) prints
+// output lines and types on the last line, captured like any Studio frame.
+// Consecutive terminal steps continue the same page, so a prompt printed by
+// one step can be answered by the next.
+import { pathToFileURL } from "node:url";
+
+export const TERMINAL_URL = pathToFileURL(new URL("./scenes/terminal.html", import.meta.url).pathname).href;
+
+/**
+ * The timed events the terminal page plays for one step: one `line` per
+ * printed line, then one `char` per typed character and an `enter`. Pure,
+ * so it is tested. About 12 typed characters a second, lines 0.6 s apart.
+ */
+export function terminalSequence({ print = [], type = "" }, { startMs = 400, lineMs = 600, charMs = 83, typeAfterMs = 500, enterMs = 450 } = {}) {
+	const events = [];
+	let at = startMs;
+	print.forEach((line, index) => {
+		if (index > 0) at += lineMs;
+		events.push({ at, kind: "line", text: line });
+	});
+	if (type) {
+		if (print.length) at += typeAfterMs;
+		for (const [index, character] of [...type].entries()) {
+			if (index > 0) at += charMs;
+			events.push({ at, kind: "char", text: character });
+		}
+		at += enterMs;
+		events.push({ at, kind: "enter" });
+	}
+	return { events, totalMs: at };
+}
+
+/** Play one terminal step: on a fresh page when asked or when the page is elsewhere, else continuing. */
+export async function playTerminal(cdp, scene) {
+	if (scene.fresh || (await cdp.evaluate("location.href")) !== TERMINAL_URL) {
+		const loaded = cdp.once("Page.loadEventFired");
+		await cdp.send("Page.navigate", { url: TERMINAL_URL });
+		await loaded;
+	}
+	const { events, totalMs } = terminalSequence(scene);
+	await cdp.evaluate(`window.__terminal.play(${JSON.stringify(events)})`);
+	await new Promise((resolve) => setTimeout(resolve, totalMs + 200));
+}

package/tools/tutorial/voice.mjs

@@ -0,0 +1,49 @@
+// Optional voice stage for the tutorial recorder. It runs before recording,
+// because each cue's hold comes from its clip length. Per narrated step: the
+// author's own recording at tools/tutorial/voice/<episode>/<id>.<lang>.<ext>
+// wins; otherwise macOS `say` reads the step; with neither, the step is silent
+// and the video keeps its burned-in caption.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const SAY_VOICES = { ko: "Yuna", en: "Samantha" };
+const EXTENSIONS = ["wav", "m4a", "mp3", "aiff"];
+
+/** The author's clip for one step and language, or null. */
+export function userClip(voiceDir, id, language) {
+	return EXTENSIONS.map((extension) => join(voiceDir, `${id}.${language}.${extension}`)).find(existsSync) ?? null;
+}
+
+/** What the voice reads: `speech` overrides the caption text (pronunciation of English names in Korean, say). */
+export const speechText = (step, language) => step.speech?.[language] ?? step.narration[language];
+
+/** True when `say` can speak this language with its voice (macOS only). */
+function sayAvailable(language) {
+	const list = spawnSync("say", ["-v", "?"], { encoding: "utf8" });
+	return list.status === 0 && new RegExp(`^${SAY_VOICES[language]}\\s`, "m").test(list.stdout);
+}
+
+/**
+ * Clips for every narrated step in `language`: Map id -> { path, audioS, source }.
+ * Steps without a user clip and without `say` are left out.
+ */
+export function prepareVoice({ steps, language, voiceDir, workDir, ffprobe, useSay = true }) {
+	const say = useSay && sayAvailable(language);
+	const clips = new Map();
+	for (const step of steps.filter((item) => item.narration)) {
+		let path = userClip(voiceDir, step.id, language);
+		const source = path ? "user" : "say";
+		if (!path && !say) continue;
+		if (!path) {
+			path = join(workDir, `${step.id}.${language}.wav`);
+			const spoken = spawnSync("say", ["-v", SAY_VOICES[language], "--data-format=LEI16@48000", "-o", path, speechText(step, language)], { encoding: "utf8" });
+			if (spoken.status !== 0) throw new Error(`say failed for step ${step.id}: ${spoken.stderr.trim()}`);
+		}
+		const probe = spawnSync(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", path], { encoding: "utf8" });
+		const audioS = Number(probe.stdout.trim());
+		if (probe.status !== 0 || !(audioS > 0)) throw new Error(`ffprobe could not read ${path}`);
+		clips.set(step.id, { path, audioS, source });
+	}
+	return clips;
+}

package/tools/update-test-durations.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// Usage: node tools/update-test-durations.mjs [RUN_ID]
+// Refreshes tools/test-durations.json from the test-durations-N artifacts of
+// the latest successful pages.yml run on main (or of RUN_ID). Only main runs
+// are full runs, so only they feed the file. A person runs this and commits
+// the result in a pull request; no workflow writes to main (#632).
+// GH_REPO overrides the repository (default NomaDamas/CozyClay).
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DURATIONS_PATH, readDurations, writeDurations } from "./test-shards.mjs";
+
+const repo = process.env.GH_REPO || "NomaDamas/CozyClay";
+const gh = (...arguments_) => execFileSync("gh", [...arguments_, "--repo", repo], { encoding: "utf8" });
+const latest = () => JSON.parse(gh("run", "list", "--workflow", "pages.yml", "--branch", "main", "--status", "success", "--limit", "1", "--json", "databaseId"))[0]?.databaseId;
+const runId = process.argv[2] ?? latest();
+if (!runId) throw new Error(`no successful pages.yml run on main in ${repo}`);
+
+const scratch = mkdtempSync(join(tmpdir(), "cozyclay-test-durations-"));
+try {
+	gh("run", "download", String(runId), "--pattern", "test-durations-*", "--dir", scratch);
+	const merged = readDurations();
+	let measured = 0;
+	for (const artifact of readdirSync(scratch)) {
+		for (const file of readdirSync(join(scratch, artifact)).filter((name) => name.endsWith(".json"))) {
+			for (const [test, seconds] of Object.entries(JSON.parse(readFileSync(join(scratch, artifact, file), "utf8")))) {
+				if (!Number.isFinite(seconds)) continue;
+				merged[test] = seconds;
+				measured += 1;
+			}
+		}
+	}
+	if (measured === 0) throw new Error(`run ${runId} has no test-durations-N artifacts with entries`);
+	// Files deleted since the last refresh drop out; files the run did not
+	// execute keep their old record.
+	const kept = Object.fromEntries(Object.entries(merged).filter(([test]) => existsSync(new URL(`../${test}`, import.meta.url))));
+	writeDurations(DURATIONS_PATH, kept);
+	console.log(`test durations: ${measured} files measured in run ${runId}, ${Object.keys(kept).length} recorded in tools/test-durations.json`);
+} finally {
+	rmSync(scratch, { recursive: true, force: true });
+}

package/tools/verify-package-tarball.mjs

@@ -6,6 +6,8 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+// CI has no signing key: --imports-only stops after the import check.
+const importsOnly = process.argv.includes("--imports-only");
 const temporaryRoot = mkdtempSync(join(tmpdir(), "cozyclay-package-check-"));
 const extractionRoot = join(temporaryRoot, "extracted");
 // Static, side-effect and dynamic imports with a relative specifier.
@@ -34,6 +36,21 @@ function missingImports(packedRoot) {
 	return missing;
 }
 
+async function verifySignature(packedRoot) {
+	const metadataPath = join(packedRoot, "package.json");
+	const markerPath = join(packedRoot, "dist", "cozyclay-package.json");
+	const signatureModulePath = join(packedRoot, "bin", "package-signature.mjs");
+	if (!existsSync(metadataPath) || !existsSync(markerPath) || !existsSync(signatureModulePath)) {
+		throw new Error("npm tarball is missing package metadata or its signature marker");
+	}
+	const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+	const { verifyPackageMarker } = await import(pathToFileURL(signatureModulePath).href);
+	if (!verifyPackageMarker(markerPath, packedRoot, metadata)) {
+		throw new Error("npm tarball signature digest does not match the files npm ships");
+	}
+	console.log(`package tarball signature PASS (${metadata.name}@${metadata.version})`);
+}
+
 try {
 	mkdirSync(extractionRoot);
 	execFileSync("npm", [
@@ -52,18 +69,7 @@ try {
 	const missing = missingImports(packedRoot);
 	if (missing.length > 0) throw new Error(`npm tarball is missing modules its bin/ and mcp/ code imports:\n  ${missing.join("\n  ")}`);
 	console.log("package tarball imports PASS (every relative import in bin/ and mcp/ resolves inside the tarball)");
-	const metadataPath = join(packedRoot, "package.json");
-	const markerPath = join(packedRoot, "dist", "cozyclay-package.json");
-	const signatureModulePath = join(packedRoot, "bin", "package-signature.mjs");
-	if (!existsSync(metadataPath) || !existsSync(markerPath) || !existsSync(signatureModulePath)) {
-		throw new Error("npm tarball is missing package metadata or its signature marker");
-	}
-	const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
-	const { verifyPackageMarker } = await import(pathToFileURL(signatureModulePath).href);
-	if (!verifyPackageMarker(markerPath, packedRoot, metadata)) {
-		throw new Error("npm tarball signature digest does not match the files npm ships");
-	}
-	console.log(`package tarball signature PASS (${metadata.name}@${metadata.version})`);
+	if (!importsOnly) await verifySignature(packedRoot);
 } finally {
 	rmSync(temporaryRoot, { recursive: true, force: true });
 }

package/dist/assets/TaskBoard-DwXhsJXz.js

@@ -1 +0,0 @@
-import{r as e}from"./rolldown-runtime-hePW80VL.js";import{Fa as t,Ji as n,c as r,d as i,f as a,l as o,m as s,o as c,v as l}from"./task-board-CkLZGPkv.js";import{o as u,r as d,t as f}from"./motion3-compile-Du7UXrWn.js";var p=e(t(),1),m=2e3,h=(e,t)=>new Promise(n=>{let r=setTimeout(n,e);t.addEventListener(`abort`,()=>{clearTimeout(r),n()},{once:!0})});function g(e,t){(0,p.useEffect)(()=>{let r=new Map;for(let[n,i]of Object.entries(e))for(let e of i)r.set(e,t[n]??n);let i=()=>{for(let e of document.querySelectorAll(`[data-node-id]`)){let t=r.get(e.getAttribute(`data-node-id`));t?(e.setAttribute(`data-task-scope`,t),e.setAttribute(`title`,n(`In task: ${t}`,`작업 중: ${t}`,`任务中：${t}`))):e.hasAttribute(`data-task-scope`)&&(e.removeAttribute(`data-task-scope`),e.removeAttribute(`title`))}};i();let a=new MutationObserver(i);return a.observe(document.body,{childList:!0,subtree:!0}),()=>{a.disconnect(),r.clear(),i()}},[e,t])}function _({sessionId:e,pulse:t,labelOf:n,onMainNote:_}){let v=(0,p.useMemo)(()=>c(),[]),y=u(),[b,x]=(0,p.useReducer)((e,t)=>t.seed?s(e,t.seed):t.reset?r():i(e,t.event),void 0,r),[S,C]=(0,p.useState)({}),[w,T]=(0,p.useState)(f),E=(0,p.useRef)(0),D=(0,p.useRef)(_);(0,p.useEffect)(()=>{E.current=b.after,D.current=_},[b.after,_]),(0,p.useEffect)(()=>{x({reset:!0}),E.current=0},[e]),(0,p.useEffect)(()=>d(T),[]),(0,p.useEffect)(()=>y.subscribe(e=>{typeof e?.type!=`string`||!e.type.startsWith(`task.`)||(C(t=>a(t,e)),(e.type===`task.userEdit`||e.type===`task.undone`)&&x({event:e}))}),[y]),(0,p.useEffect)(()=>{if(!e)return;let t=new AbortController;return(async()=>{for(;!t.signal.aborted;){try{let{tasks:n}=await v.board(e);x({seed:n}),await v.events(e,E.current,e=>{if(e.type===`main.turn`&&e.turnId){let n=``;v.frames(e.turnId,e=>{e.type===`text.delta`&&(n+=e.text??``),e.type===`tool.start`&&(n=``)},t.signal).then(()=>D.current?.(n),()=>{})}x({event:e})},t.signal)}catch{}await h(m,t.signal)}})(),()=>t.abort()},[v,e,t]);let O=b.order.filter(e=>b.tasks[e]?.status===`running`&&b.tasks[e]?.turnId),k=O.map(e=>`${e}:${b.tasks[e].turnId}`).join();return(0,p.useEffect)(()=>{let e=O.map(e=>{let t=new AbortController,{turnId:r}=b.tasks[e];return v.frames(r,t=>{let r=o(t,n);r&&x({event:{type:`task.progress`,taskId:e,status:`running`,progress:r}})},t.signal).catch(()=>{}),t});return()=>e.forEach(e=>e.abort())},[v,k,n]),g(S,(0,p.useMemo)(()=>Object.fromEntries(b.order.map(e=>[e,b.tasks[e].title])),[b])),(0,p.useEffect)(()=>{l.set({client:v,labelOf:n,undo:async e=>{let t=await y.run(`task.undo`,{taskId:e});if(t?.ok===!1)throw Error(t.message??t.code);x({event:{type:`task.undone`,taskId:e}})}})},[y,v,n]),(0,p.useEffect)(()=>{l.set({board:b,activity:w})},[b,w]),(0,p.useEffect)(()=>()=>l.set({board:r(),open:null}),[e]),null}export{_ as default};