cozyclay 3.2.0 → 3.2.1

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-BUjjuvm5.js

@@ -1 +0,0 @@
-import{r as e}from"./rolldown-runtime-hePW80VL.js";import{Za as t,c as n,d as r,f as i,l as a,m as o,o as s,ua as c,v as l}from"./task-board-5PKn7ZaA.js";import{o as u,r as d,t as f}from"./motion3-compile-B4SX4TGx.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 n=new Map;for(let[r,i]of Object.entries(e))for(let e of i)n.set(e,t[r]??r);let r=()=>{for(let e of document.querySelectorAll(`[data-node-id]`)){let t=n.get(e.getAttribute(`data-node-id`));t?(e.setAttribute(`data-task-scope`,t),e.setAttribute(`title`,c(`In task: ${t}`,`작업 중: ${t}`,`任务中：${t}`))):e.hasAttribute(`data-task-scope`)&&(e.removeAttribute(`data-task-scope`),e.removeAttribute(`title`))}};r();let i=new MutationObserver(r);return i.observe(document.body,{childList:!0,subtree:!0}),()=>{i.disconnect(),n.clear(),r()}},[e,t])}function _({sessionId:e,pulse:t,labelOf:c,onMainNote:_}){let v=(0,p.useMemo)(()=>s(),[]),y=u(),[b,x]=(0,p.useReducer)((e,t)=>t.seed?o(e,t.seed):t.reset?n():r(e,t.event),void 0,n),[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=>i(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:n}=b.tasks[e];return v.frames(n,t=>{let n=a(t,c);n&&x({event:{type:`task.progress`,taskId:e,status:`running`,progress:n}})},t.signal).catch(()=>{}),t});return()=>e.forEach(e=>e.abort())},[v,k,c]),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:c,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,c]),(0,p.useEffect)(()=>{l.set({board:b,activity:w})},[b,w]),(0,p.useEffect)(()=>()=>l.set({board:n(),open:null}),[e]),null}export{_ as default};