cozyclay 3.2.0 → 3.2.1

package/tools/tutorial/episodes/first-video.mjs

@@ -0,0 +1,121 @@
+// Episode 1, "First video in 5 minutes": start screen to a keyframe-pack
+// export, following the measured beginner path. The in-app first-success
+// guide stays on screen and advances as each of its steps is done. The walk
+// take is compiled in the page because the recording has no signed-in agent;
+// the narration says so.
+import { skeletonFor } from "../../../src/motion3/rigs/index.js";
+import { castFirstCharacter } from "./cast.mjs";
+
+const skeleton = skeletonFor("y-bot-tpose");
+const rest = (bone) => skeleton.restWorldPos[skeleton.index[bone]];
+const ankle = rest("LeftFoot")[1];
+const WALK = {
+	schema: "cozyclay.motion-spec.v1",
+	fps: 24,
+	frames: 240,
+	keys: [{ f: 0, set: { root: [0, rest("Hips")[1] - 0.01, 0], yaw: 0, foot_l: [0.09, ankle, -0.03], foot_r: [-0.09, ankle, 0.03], fyaw_l: 0, fyaw_r: 0, armw_r: 0 } }],
+	generators: [{ type: "walk", f0: 6, steps: 8, heading: [0, 0] }],
+};
+const GUIDE_NEXT = ".v2-first-success-guide-next";
+
+export default [
+	{
+		id: "install",
+		narration: {
+			ko: "터미널에서 npx cozyclay를 실행하면 브라우저에 스튜디오가 열립니다.",
+			en: "Run npx cozyclay in a terminal and the studio opens in your browser.",
+		},
+		speech: { ko: "터미널에서 엔피엑스 코지클레이를 실행하면 브라우저에 스튜디오가 열립니다.", en: "Run N P X cozyclay in a terminal and the studio opens in your browser." },
+		wait: ".v2-start-screen",
+	},
+	{
+		id: "create",
+		narration: {
+			ko: "\"새 프로젝트\"에 이름을 적고 \"생성\"을 누르세요. 빈 무대에서 시작합니다.",
+			en: "Pick \"New project\", name it, and press \"Create\". You start from an empty stage.",
+		},
+		type: { into: "[data-testid=start-project-name]", text: "my_first_video" },
+	},
+	{ id: "create-click", click: "[data-testid=start-create]", until: ".timeline" },
+	// The character rig takes about a second to load after Create.
+	{ id: "rig-load", hold: 1500 },
+	...castFirstCharacter("cast", {
+		ko: "장면 보기의 \"추가\" 메뉴에서 Y Bot을 골라 캐릭터를 놓으세요.",
+		en: "Open Add in the Scene view and pick Y Bot to place a character.",
+	}),
+	{
+		id: "select",
+		narration: { ko: "아웃라이너에서 \"캐릭터 1\"을 고르세요.", en: "Select \"Character 1\" in the Outliner." },
+		click: "[data-node-id=characterA] .hierarchy-row",
+	},
+	{ id: "guide-select", click: GUIDE_NEXT },
+	{
+		id: "move",
+		narration: { ko: "장면 보기에서 바닥의 핸들을 끌어 옮기세요.", en: "Drag the handle on the floor in the Scene view to place it." },
+		drag: { from: { js: "window.__characterGizmoHandles?.().find((handle) => handle.axis === 'plane:xz')" }, to: { dx: -120, dy: 45 } },
+	},
+	{ id: "guide-move", click: GUIDE_NEXT },
+	{
+		id: "agent",
+		narration: {
+			ko: "Cmd/Ctrl+B로 에이전트 패널을 엽니다. 여기서 \"Sign in with ChatGPT\"로 로그인하면 동작을 말로 요청할 수 있어요.",
+			en: "Press Cmd/Ctrl+B to open the Agent panel. Sign in here, then describe the motion you want.",
+		},
+		speech: { ko: "커맨드 또는 컨트롤 B로 에이전트 패널을 엽니다. 여기서 \"Sign in with ChatGPT\"로 로그인하면 동작을 말로 요청할 수 있어요.", en: "Press Command or Control B to open the Agent panel. Sign in here, then describe the motion you want." },
+		key: "Mod+B",
+		until: "[data-agent-card=signed-out]",
+	},
+	{
+		id: "motion",
+		narration: {
+			ko: "로그인한 뒤 요청하면 테이크가 \"바디\" 레인에 올라옵니다. 여기서는 완성된 걷기 테이크를 바로 불러왔어요.",
+			en: "Once you are signed in, the take lands on the Body lane. Here we load a finished walk take.",
+		},
+		key: "Mod+B",
+	},
+	// The walk starts where the "move" step left the character: the studio's
+	// own character state offsets the spec's root and feet on the floor.
+	{
+		id: "motion-compile",
+		eval: `(() => {
+			const character = window.__cozyclay.characters[0], { x, z } = character;
+			const spec = ${JSON.stringify(WALK)};
+			const set = spec.keys[0].set;
+			for (const name of ["root", "foot_l", "foot_r"]) set[name] = [set[name][0] + x, set[name][1], set[name][2] + z];
+			return window.__cozyclay.runStudioAction("motion.compile", { characterId: character.id, spec });
+		})()`,
+	},
+	{ id: "guide-ask", click: GUIDE_NEXT },
+	{
+		id: "play",
+		narration: {
+			ko: "Space를 누르면 재생되고, 타임라인을 문질러 확인할 수도 있어요. 재생 헤드가 움직이면 첫 결과입니다.",
+			en: "Press Space to play, or scrub the timeline. Seeing the playhead move is your first visible result.",
+		},
+		key: "Space",
+		// The play button gains "on" while playing; its aria-label is translated.
+		until: ".tl-btn.play.on",
+	},
+	// The walk carries the character out of the viewport by frame ~100; pausing
+	// near frame 36 keeps it in view for the shot and export steps.
+	{ id: "playing", hold: 1500 },
+	{ id: "pause", key: "Space" },
+	{ id: "guide-complete", click: GUIDE_NEXT },
+	{ id: "guide-close", click: GUIDE_NEXT },
+	{
+		id: "shot",
+		narration: { ko: "카메라 컷 레인의 \"+\"를 누르면 짧은 샷이 추가됩니다.", en: "Press \"+\" on the Camera Cuts lane to add a short shot." },
+		click: ".tl-track-add.cut",
+	},
+	{
+		id: "export",
+		narration: {
+			ko: "파일, 내보내기에서 \"키프레임 팩 (zip)\"을 고르거나 Cmd/Ctrl+E를 누르세요. 첫 프레임, 마지막 프레임, 참고 클립, 프롬프트가 한 zip에 담깁니다.",
+			en: "Choose File, Export, \"Keyframe pack (zip)\", or press Cmd/Ctrl+E. First frame, last frame, reference clip and prompt land in one zip.",
+		},
+		speech: { ko: "파일, 내보내기에서 키프레임 팩 집을 고르거나 커맨드 또는 컨트롤 E를 누르세요. 첫 프레임, 마지막 프레임, 참고 클립, 프롬프트가 한 집 파일에 담깁니다.", en: "Choose File, Export, Keyframe pack zip, or press Command or Control E. First frame, last frame, reference clip and prompt land in one zip." },
+		key: "Mod+E",
+	},
+	// The last sentence finishes with the export toast still on screen.
+	{ id: "export-toast", hold: 1000 },
+];

package/tools/tutorial/episodes/stub-tour.mjs

@@ -0,0 +1,97 @@
+// Stub tour: proves the point-at-features format (cards, the install terminal,
+// spotlights with callouts, a menu path) on a short path. The terminal lines
+// are placeholders until the measured install output replaces them. Fixed
+// holds keep it under a minute; a real episode lets reading time decide.
+const OUTLINER = ".hierarchy-pane.v2-outliner";
+
+export default {
+	title: { ko: "CozyClay 둘러보기", en: "A tour of CozyClay" },
+	subtitle: { ko: "설치부터 편집기까지", en: "From install to the editor" },
+	firstChapter: 0,
+	chapters: [
+		{ id: "intro", steps: [{ id: "opening", card: "opening", hold: 2500 }] },
+		{
+			id: "install",
+			title: { ko: "설치", en: "Install" },
+			steps: [
+				{ id: "install-card", hold: 2000, card: { title: { ko: "설치", en: "Install" }, subtitle: { ko: "터미널에서 한 줄이면 됩니다", en: "One line in a terminal" } } },
+				{
+					id: "install-run",
+					narration: { ko: "터미널에서 npx cozyclay를 실행하세요.", en: "Run npx cozyclay in a terminal." },
+					terminal: { type: "npx cozyclay" },
+				},
+				{ id: "install-output", terminal: { print: ["[placeholder] installing CozyClay", "[placeholder] CozyClay is running at http://127.0.0.1:5180/app/", "[placeholder] opening your browser"] } },
+			],
+		},
+		{
+			id: "start",
+			title: { ko: "시작 화면", en: "Start screen" },
+			steps: [
+				{ id: "open-studio", studio: true },
+				{ id: "start-card", hold: 2000, card: { title: { ko: "시작 화면", en: "Start screen" }, subtitle: { ko: "프로젝트를 만드는 곳", en: "Where a project begins" } } },
+				{
+					id: "spot-animation",
+					narration: { ko: "먼저 프로젝트 모드를 고릅니다.", en: "First, pick the project mode." },
+					spotlight: "[data-testid=start-previs-mode] [data-previs-mode=animation]",
+					hold: 2600,
+					label: { ko: "애니메이션", en: "Animation" },
+					note: { ko: "움직임을 블로킹하고 샷을 찍는 모드", en: "Block continuous motion and shoot shots" },
+				},
+				{
+					id: "spot-create",
+					spotlight: "[data-testid=start-create]",
+					hold: 2600,
+					label: { ko: "생성", en: "Create" },
+					note: { ko: "빈 무대로 새 프로젝트를 엽니다", en: "Opens a new project on an empty stage" },
+				},
+				{ id: "spot-clear-start", spotlight: null },
+				{ id: "create", click: "[data-testid=start-create]", until: ".timeline" },
+				{ id: "rig-load", hold: 1500 },
+			],
+		},
+		{
+			id: "editor",
+			title: { ko: "편집기", en: "Editor" },
+			steps: [
+				{ id: "editor-card", hold: 2000, card: { title: { ko: "편집기", en: "Editor" }, subtitle: { ko: "장면, 모드, 타임라인", en: "Scene, modes and timeline" } } },
+				{
+					id: "spot-outliner",
+					narration: { ko: "편집기의 세 부분을 차례로 봅니다.", en: "Three parts of the editor, one at a time." },
+					spotlight: OUTLINER,
+					label: { ko: "아웃라이너", en: "Outliner" },
+					note: { ko: "장면에 있는 카메라, 조명, 캐릭터 목록", en: "Every camera, light and character in the scene" },
+				},
+				{
+					id: "spot-modes",
+					spotlight: ".vp-mode-keys",
+					hold: 2600,
+					label: { ko: "작업 모드", en: "Workflow modes" },
+					note: { ko: "배치, 포즈, 카메라, 모션, 조각을 오갑니다", en: "Switch between Stage, Pose, Camera, Motion and Sculpt" },
+				},
+				{
+					id: "spot-body",
+					spotlight: "[data-lane-label=Body]",
+					hold: 2600,
+					label: { ko: "바디 레인", en: "Body lane" },
+					note: { ko: "캐릭터의 동작 테이크가 올라오는 곳", en: "Where the character's motion takes land" },
+				},
+				{ id: "spot-clear-editor", spotlight: null },
+				{
+					id: "open-export",
+					narration: { ko: "내보내기는 파일 메뉴에 있습니다.", en: "Exports live in the File menu." },
+					menu: { open: "[data-testid=menu-file]", then: "[data-testid=topbar-export]" },
+				},
+				{
+					id: "spot-keyframe-pack",
+					spotlight: "[data-testid=export-keyframe-pack]",
+					hold: 2600,
+					label: { ko: "키프레임 팩 (zip)", en: "Keyframe pack (zip)" },
+					note: { ko: "첫 프레임, 마지막 프레임, 참고 클립, 프롬프트", en: "First frame, last frame, reference clip and prompt" },
+				},
+				{ id: "spot-clear-export", spotlight: null },
+				{ id: "close-menu", click: "[data-testid=menu-file]" },
+			],
+		},
+		{ id: "outro", steps: [{ id: "closing", card: "closing", hold: 3000 }] },
+	],
+};

package/tools/tutorial/launch.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// `npm run tutorial:record -- <episode> [flags]`: starts a dev server with a
+// throwaway config dir (so the Agent panel shows the signed-out screen, not
+// this machine's sign-in), runs record.mjs inside tools/qa-browser.mjs, and
+// tears both down. Ports come from TUTORIAL_DEV_PORT, CDP_PORT,
+// COZYCLAY_LIVE_PORT and COZYCLAY_OAUTH_PORT, defaulting to 5594-5597 so a
+// recording never touches a Studio on 5180/5184. dev-full, not vite alone:
+// without the agent server the panel reports a missing server instead of the
+// sign-in card.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findFfmpeg } from "./assemble.mjs";
+import { installSignalCleanup, spawnOwned, terminateOwned, waitForExit } from "../process-supervisor.mjs";
+
+const devPort = Number(process.env.TUTORIAL_DEV_PORT || 5594);
+const cdpPort = String(process.env.CDP_PORT || 5595);
+const livePort = String(process.env.COZYCLAY_LIVE_PORT || 5596);
+const oauthPort = String(process.env.COZYCLAY_OAUTH_PORT || 5597);
+const url = `http://127.0.0.1:${devPort}/app/`;
+const reachable = () => fetch(url).then((response) => response.ok, () => false);
+
+try {
+	findFfmpeg();
+} catch (error) {
+	console.error(error.message);
+	process.exit(1);
+}
+if (await reachable()) {
+	console.error(`port ${devPort} already serves a page; stop it or set TUTORIAL_DEV_PORT`);
+	process.exit(1);
+}
+
+const configDir = mkdtempSync(join(tmpdir(), "cozyclay-tutorial-config-"));
+const children = [];
+const removeSignalCleanup = installSignalCleanup(() => children, () => rmSync(configDir, { recursive: true, force: true }));
+// No provider key or endpoint from this shell may reach the recording's agent sidecar.
+const devEnv = Object.fromEntries(Object.entries(process.env).filter(([name]) => !/(_API_KEY|_AUTH_TOKEN|_BASE_URL)$/.test(name) && name !== "COZYCLAY_CODEX_AUTH_FILE"));
+try {
+	const dev = spawnOwned(process.execPath, ["tools/dev-full.mjs", "--host", "127.0.0.1", "--port", String(devPort)], {
+		env: { ...devEnv, COZYCLAY_CONFIG_DIR: configDir, XDG_CONFIG_HOME: configDir, COZYCLAY_LIVE_PORT: livePort, COZYCLAY_OAUTH_PORT: oauthPort },
+		stdio: ["ignore", "ignore", "inherit"],
+	});
+	children.push(dev);
+	const deadline = Date.now() + 60000;
+	while (!(await reachable())) {
+		if (dev.exitCode !== null) throw new Error("the dev server exited before it served the Studio");
+		if (Date.now() > deadline) throw new Error(`the dev server did not answer on ${url} within 60s`);
+		await new Promise((resolve) => setTimeout(resolve, 250));
+	}
+	const recorder = spawnOwned(process.execPath, ["tools/qa-browser.mjs", "--", process.execPath, "tools/tutorial/record.mjs", ...process.argv.slice(2)], {
+		env: { ...process.env, QA_URL: url, CDP_PORT: cdpPort, QA_STARTUP_CHOOSER: "1" },
+	});
+	children.push(recorder);
+	process.exitCode = (await waitForExit(recorder)).code ?? 1;
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+} finally {
+	removeSignalCleanup();
+	await Promise.allSettled(children.map((child) => terminateOwned(child)));
+	rmSync(configDir, { recursive: true, force: true });
+}

package/tools/tutorial/mux.mjs

@@ -0,0 +1,61 @@
+// Final assembly for the tutorial recorder: the silent capture gets a caption
+// band under the frame (so a caption never covers the UI the step points at),
+// one caption PNG per cue in that band, and the voice clips laid on the cue
+// windows. This ffmpeg has neither libass nor freetype, so captions are images
+// and the graph is built here. Pure, so the test checks it without ffmpeg.
+
+const seconds = (ms) => (ms / 1000).toFixed(3);
+
+/**
+ * ffmpeg argv for `output`. `cues` are contiguous [{ id, startMs, endMs }];
+ * `clips` maps a cue id to { path, audioS } (may be empty: captions only);
+ * `captions` holds one PNG per cue, `bandHeight` px tall.
+ */
+export function muxArgs({ base, output, cues, clips, captions, endMs, bandHeight }) {
+	for (const cue of cues) {
+		const clip = clips.get(cue.id);
+		if (clip && clip.audioS * 1000 > cue.endMs - cue.startMs) {
+			throw new Error(`the voice clip for ${cue.id} runs ${clip.audioS.toFixed(2)} s, longer than its ${seconds(cue.endMs - cue.startMs)} s cue; record again so the hold follows the clip`);
+		}
+	}
+	const voiced = clips.size > 0;
+	const inputs = ["-i", base];
+	// Each audio segment runs from its cue start to the next cue start (the first from 0, the last to the end).
+	const segments = cues.map((cue, index) => ({ cue, fromMs: index === 0 ? 0 : cue.startMs, toMs: index + 1 < cues.length ? cues[index + 1].startMs : endMs }));
+	const filters = [];
+	if (voiced) {
+		segments.forEach(({ cue, fromMs, toMs }, index) => {
+			const length = seconds(toMs - fromMs);
+			const clip = clips.get(cue.id);
+			inputs.push(...(clip ? ["-i", clip.path] : ["-f", "lavfi", "-t", length, "-i", "anullsrc=r=48000:cl=mono"]));
+			const delay = index === 0 && cue.startMs > 0 ? `,adelay=delays=${Math.round(cue.startMs)}:all=1` : "";
+			filters.push(`[${index + 1}:a]aresample=48000,aformat=channel_layouts=mono${delay},apad=whole_dur=${length},atrim=end=${length}[a${index}]`);
+		});
+		filters.push(`${segments.map((_, index) => `[a${index}]`).join("")}concat=n=${segments.length}:v=0:a=1[aout]`);
+	}
+	const firstCaption = voiced ? cues.length + 1 : 1;
+	for (const caption of captions) inputs.push("-i", caption);
+	filters.push(`[0:v]pad=iw:ih+${bandHeight}:0:0:color=0x111111[v]`);
+	cues.forEach((cue, index) => {
+		filters.push(`[${index ? `v${index - 1}` : "v"}][${firstCaption + index}:v]overlay=0:H-h:enable='between(t,${seconds(cue.startMs)},${seconds(cue.endMs)})'[v${index}]`);
+	});
+	return [
+		"-hide_banner", "-loglevel", "error", "-y", ...inputs,
+		"-filter_complex", filters.join(";"),
+		"-map", cues.length ? `[v${cues.length - 1}]` : "[v]", ...(voiced ? ["-map", "[aout]", "-c:a", "aac", "-b:a", "128k"] : []),
+		"-c:v", "libx264", "-preset", "medium", "-crf", "20", "-pix_fmt", "yuv420p",
+		"-t", seconds(endMs), "-movflags", "+faststart", output,
+	];
+}
+
+/** Caption band height for a frame height: about 13%, even, so two lines fit. */
+export const bandHeightFor = (height) => Math.round((height * 0.13) / 2) * 2;
+
+/** ffmpeg argv cutting [startMs, endMs) of the finished episode into one chapter file, re-encoded for exact cuts. */
+export function chapterCutArgs({ input, output, startMs, endMs, audio }) {
+	return [
+		"-hide_banner", "-loglevel", "error", "-y", "-ss", seconds(startMs), "-t", seconds(endMs - startMs), "-i", input,
+		"-c:v", "libx264", "-preset", "medium", "-crf", "20", "-pix_fmt", "yuv420p",
+		...(audio ? ["-c:a", "aac", "-b:a", "128k"] : ["-an"]), "-movflags", "+faststart", output,
+	];
+}

package/tools/tutorial/overlay.mjs

@@ -0,0 +1,142 @@
+// Teaching overlays for the tutorial recorder, injected into every page the
+// episode visits: a spotlight (the page dimmed around a cut-out with an accent
+// ring, a callout naming the feature beside it) and full-frame chapter cards.
+// pointer-events: none throughout, so the real input still reaches the app.
+
+/**
+ * Where a callout box goes beside a target rect: right, left, below, above,
+ * the first side where it fits; else the roomiest side, clamped into the
+ * viewport. Self-contained, because it is also serialized into the page.
+ */
+export function calloutPlacement(target, box, viewport, gap = 16, margin = 12) {
+	const fits = {
+		right: target.x + target.width + gap + box.width <= viewport.width - margin,
+		left: target.x - gap - box.width >= margin,
+		below: target.y + target.height + gap + box.height <= viewport.height - margin,
+		above: target.y - gap - box.height >= margin,
+	};
+	const room = { right: viewport.width - target.x - target.width, left: target.x, below: viewport.height - target.y - target.height, above: target.y };
+	const sides = ["right", "left", "below", "above"];
+	const side = sides.find((name) => fits[name]) ?? sides.reduce((best, name) => (room[name] > room[best] ? name : best));
+	const middleX = target.x + target.width / 2 - box.width / 2;
+	const middleY = target.y + target.height / 2 - box.height / 2;
+	const x = side === "right" ? target.x + target.width + gap : side === "left" ? target.x - gap - box.width : middleX;
+	const y = side === "below" ? target.y + target.height + gap : side === "above" ? target.y - gap - box.height : middleY;
+	const clamp = (value, low, high) => Math.min(Math.max(value, low), Math.max(low, high));
+	return { side, x: Math.round(clamp(x, margin, viewport.width - margin - box.width)), y: Math.round(clamp(y, margin, viewport.height - margin - box.height)) };
+}
+
+/**
+ * Resolves a target in the page: a CSS selector (first visible match),
+ * { css, text } (first visible match containing the text), { js } (an
+ * expression giving an element or a { x, y, width, height } rect), or an
+ * array (the union of its targets). Returns { el, rect } or null.
+ * Self-contained, because it is serialized into the page.
+ */
+function findTarget(spec) {
+	if (Array.isArray(spec)) {
+		const rects = spec.map(findTarget).filter(Boolean).map((found) => found.rect);
+		if (!rects.length) return null;
+		const left = Math.min(...rects.map((rect) => rect.x)), top = Math.min(...rects.map((rect) => rect.y));
+		const right = Math.max(...rects.map((rect) => rect.x + rect.width)), bottom = Math.max(...rects.map((rect) => rect.y + rect.height));
+		return { el: null, rect: { x: left, y: top, width: right - left, height: bottom - top } };
+	}
+	const box = (node) => { const rect = node.getBoundingClientRect(); return rect.width > 0 && rect.height > 0 ? { el: node, rect: { x: rect.left, y: rect.top, width: rect.width, height: rect.height } } : null; };
+	if (spec && typeof spec === "object" && spec.js) {
+		const value = (0, eval)(spec.js);
+		if (!value) return null;
+		return value instanceof Element ? box(value) : { el: null, rect: { x: value.x, y: value.y, width: value.width, height: value.height } };
+	}
+	const { css, text } = typeof spec === "string" ? { css: spec } : spec;
+	for (const node of document.querySelectorAll(css)) {
+		if (text && !node.textContent.includes(text)) continue;
+		const found = box(node);
+		if (found) return found;
+	}
+	return null;
+}
+
+const FONT = `"Apple SD Gothic Neo","Noto Sans CJK KR","Noto Sans KR","Malgun Gothic",system-ui,sans-serif`;
+
+export const TEACHING_OVERLAY = `(() => {
+	if (window.__tutorialOverlay) return;
+	const place = ${calloutPlacement.toString()};
+	const find = ${findTarget.toString()};
+	window.__tutorialFind = find;
+	const PAD = 8;
+	const css = document.createElement("style");
+	css.textContent = \`
+.tt-root{position:fixed;inset:0;pointer-events:none;z-index:2147483646;font-family:${FONT.replace(/"/g, "'")}}
+.tt-hole{position:absolute;border-radius:10px;border:2px solid #3b82f6;box-shadow:0 0 0 4px rgba(59,130,246,.28),0 0 0 9999px rgba(8,10,14,.62);opacity:0;transition:left .35s ease,top .35s ease,width .35s ease,height .35s ease,opacity .3s ease}
+.tt-callout{position:absolute;max-width:640px;padding:12px 16px;border-radius:10px;background:#fff;color:#111827;box-shadow:0 10px 30px rgba(0,0,0,.35);opacity:0;transition:opacity .3s ease}
+.tt-callout b{display:block;font-size:19px;line-height:1.3;margin-bottom:3px}
+.tt-callout span{display:block;font-size:15px;line-height:1.35;color:#374151;white-space:nowrap}
+.tt-card{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:14px;background:rgba(10,12,18,.9);color:#fff;opacity:0;transition:opacity .35s ease;text-align:center}
+.tt-card small{font-size:20px;letter-spacing:.08em;color:#93c5fd;font-weight:600}
+.tt-card h1{margin:0;font-size:60px;line-height:1.2;font-weight:700;word-break:keep-all}
+.tt-card p{margin:0;font-size:26px;color:#cbd5e1;word-break:keep-all}
+.tt-card ol{margin:10px 0 0;padding:0;list-style:none;font-size:26px;line-height:1.7;color:#e5e7eb;text-align:left}
+.tt-card ol li b{color:#93c5fd;margin-right:14px}
+.tt-carded .tt-pointer-host{opacity:0}\`;
+	const root = document.createElement("div");
+	root.className = "tt-root";
+	const hole = document.createElement("div");
+	hole.className = "tt-hole";
+	root.append(hole);
+	let target = null, callout = null, card = null;
+	const mount = () => { document.documentElement.append(css, root); };
+	if (document.documentElement) mount(); else document.addEventListener("DOMContentLoaded", mount);
+	const follow = () => {
+		const found = target ? find(target) : null;
+		if (found) {
+			const box = found.rect;
+			const rect = { x: box.x - PAD, y: box.y - PAD, width: box.width + PAD * 2, height: box.height + PAD * 2 };
+			Object.assign(hole.style, { left: rect.x + "px", top: rect.y + "px", width: rect.width + "px", height: rect.height + "px" });
+			if (callout) {
+				const spot = place(rect, { width: callout.offsetWidth, height: callout.offsetHeight }, { width: innerWidth, height: innerHeight });
+				callout.style.left = spot.x + "px"; callout.style.top = spot.y + "px";
+			}
+		}
+		requestAnimationFrame(follow);
+	};
+	requestAnimationFrame(follow);
+	const fadeOut = (node) => { if (!node) return; node.style.opacity = "0"; setTimeout(() => node.remove(), 350); };
+	const text = (tag, value) => { const node = document.createElement(tag); node.textContent = value; return node; };
+	window.__tutorialOverlay = {
+		spotlight(spec, label, note) {
+			const found = find(spec);
+			if (!found) return false;
+			found.el?.scrollIntoView({ block: "nearest", inline: "nearest" });
+			target = spec;
+			fadeOut(callout);
+			callout = null;
+			if (label) {
+				callout = document.createElement("div");
+				callout.className = "tt-callout";
+				callout.append(text("b", label));
+				if (note) callout.append(text("span", note));
+				root.append(callout);
+			}
+			requestAnimationFrame(() => { hole.style.opacity = "1"; if (callout) callout.style.opacity = "1"; });
+			return true;
+		},
+		clear() { hole.style.opacity = "0"; fadeOut(callout); callout = null; setTimeout(() => { if (!callout) target = null; }, 350); },
+		card({ eyebrow, title, subtitle, items }) {
+			fadeOut(card);
+			card = document.createElement("div");
+			card.className = "tt-card";
+			if (eyebrow) card.append(text("small", eyebrow));
+			card.append(text("h1", title));
+			if (subtitle) card.append(text("p", subtitle));
+			if (items?.titles.length) {
+				const list = document.createElement("ol");
+				items.titles.forEach((item, index) => { const row = document.createElement("li"); if (items.numbered) row.append(text("b", String(index + 1).padStart(2, "0"))); row.append(item); list.append(row); });
+				card.append(list);
+			}
+			root.append(card);
+			document.documentElement.classList.add("tt-carded");
+			requestAnimationFrame(() => { card.style.opacity = "1"; });
+		},
+		hideCard() { fadeOut(card); card = null; document.documentElement.classList.remove("tt-carded"); },
+	};
+})()`;

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