cozyclay 1.0.0

package/tools/ardy/run-sequence-on-box.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Run a multi-prompt ARDY rollout in one remote process. The remote
+# cclay_sequence_generate.py keeps the model loaded and feeds each segment
+# the previous segment's motion tail through init_history_sequence.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOST="${CCLAY_ARDY_HOST:-}"
+REMOTE="${CCLAY_ARDY_REPO:-\$HOME/ardy}"
+VENV_PY="${CCLAY_ARDY_VENV:-~/ardy/.venv-cuda/bin/python}"
+ENCODER_URL="${CCLAY_ARDY_ENCODER_URL:-http://127.0.0.1:9550/}"
+FORCE_CPU=0
+
+SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=30 -o ServerAliveCountMax=240)
+SCP_OPTS=(-o BatchMode=yes -o ConnectTimeout=10)
+
+usage() {
+  cat >&2 <<'EOF'
+usage: run-sequence-on-box.sh \
+       --segment "<prompt>" <seconds> [--segment "<prompt>" <seconds> ...] \
+       [--root-2d <frame> <x> <z> <heading|none> ...] \
+       [--seed <N>] [--cpu] [--output <local.npz>] [--dry-run]
+EOF
+  exit 2
+}
+
+SEGMENTS=()
+ROOT2D=()
+SEED=""
+OUTPUT=""
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --root-2d)
+      [[ $# -ge 5 ]] || { echo "run-sequence-on-box: --root-2d needs FRAME X Z HEADING" >&2; usage; }
+      [[ "$2" =~ ^[0-9]+$ ]] || { echo "run-sequence-on-box: --root-2d frame must be a non-negative integer, got '$2'" >&2; exit 1; }
+      [[ "$3" =~ ^-?[0-9]+([.][0-9]+)?$ && "$4" =~ ^-?[0-9]+([.][0-9]+)?$ ]] || {
+        echo "run-sequence-on-box: --root-2d X Z must be numbers, got '$3' '$4'" >&2; exit 1;
+      }
+      [[ "$5" == "none" || "$5" =~ ^-?[0-9]+([.][0-9]+)?$ ]] || {
+        echo "run-sequence-on-box: --root-2d heading must be a number or 'none', got '$5'" >&2; exit 1;
+      }
+      ROOT2D+=("$2" "$3" "$4" "$5")
+      shift 5 ;;
+    --segment)
+      [[ $# -ge 3 ]] || { echo "run-sequence-on-box: --segment needs PROMPT SECONDS" >&2; usage; }
+      [[ -n "${2//[[:space:]]/}" ]] || { echo "run-sequence-on-box: segment prompt must not be empty" >&2; exit 1; }
+      [[ "$3" =~ ^[0-9]+([.][0-9]+)?$ ]] || { echo "run-sequence-on-box: segment duration must be a number, got '$3'" >&2; exit 1; }
+      SEGMENTS+=("$2" "$3")
+      shift 3 ;;
+    --seed)
+      [[ $# -ge 2 && "$2" =~ ^[0-9]+$ ]] || { echo "run-sequence-on-box: --seed needs a non-negative integer" >&2; usage; }
+      SEED="$2"; shift 2 ;;
+    --cpu)
+      FORCE_CPU=1; shift ;;
+    --output)
+      [[ $# -ge 2 ]] || { echo "run-sequence-on-box: --output needs a path" >&2; usage; }
+      OUTPUT="$2"; shift 2 ;;
+    --dry-run)
+      DRY_RUN=1; shift ;;
+    -h|--help)
+      usage ;;
+    *)
+      echo "run-sequence-on-box: unknown option '$1'" >&2
+      usage ;;
+  esac
+done
+
+[[ -n "$HOST" ]] || {
+  echo "run-sequence-on-box: CCLAY_ARDY_HOST is required (for example: user@ardy-host)" >&2
+  exit 2
+}
+
+[[ ${#SEGMENTS[@]} -ge 4 ]] || {
+  echo "run-sequence-on-box: at least two --segment entries are required" >&2
+  exit 1
+}
+
+for ((i = 1; i < ${#SEGMENTS[@]}; i += 2)); do
+  awk -v d="${SEGMENTS[$i]}" 'BEGIN { exit !(d > 0 && d <= 1200) }' || {
+    echo "run-sequence-on-box: segment duration must be > 0 and <= 1200 seconds, got '${SEGMENTS[$i]}'" >&2
+    exit 1
+  }
+done
+
+OUTPUT="${OUTPUT:-$HERE/out/$(date +%s)-sequence.npz}"
+
+if ! ssh "${SSH_OPTS[@]}" "$HOST" ":" </dev/null; then
+  echo "run-sequence-on-box: cannot ssh to ${HOST}" >&2
+  exit 1
+fi
+echo "run-sequence-on-box: ssh to ${HOST} ok"
+
+if ! ssh "${SSH_OPTS[@]}" "$HOST" "test -x ${VENV_PY}" </dev/null; then
+  echo "run-sequence-on-box: missing ${VENV_PY} on ${HOST}" >&2
+  exit 1
+fi
+
+# The generator is cclay-owned: the source of truth is the repo copy next to
+# this script, synced up on every run so the box can never drift behind it.
+if ! ssh "${SSH_OPTS[@]}" "$HOST" "cat > ${REMOTE}/scripts/cclay_sequence_generate.py" \
+  < "${HERE}/cclay_sequence_generate.py"; then
+  echo "run-sequence-on-box: could not sync cclay_sequence_generate.py to ${HOST}" >&2
+  exit 1
+fi
+echo "run-sequence-on-box: sequence generator synced to ${HOST}"
+
+if ! ENCODER_CODE="$(ssh "${SSH_OPTS[@]}" "$HOST" \
+  "curl -s -o /dev/null -w '%{http_code}' -m 10 ${ENCODER_URL}" </dev/null)"; then
+  echo "run-sequence-on-box: could not probe the text encoder" >&2
+  exit 1
+fi
+[[ "$ENCODER_CODE" == "200" ]] || {
+  echo "run-sequence-on-box: text encoder at ${ENCODER_URL} answered '${ENCODER_CODE}', not 200" >&2
+  exit 1
+}
+echo "run-sequence-on-box: text encoder ${ENCODER_URL} responding"
+
+CUDA_ENV=""
+[[ "$FORCE_CPU" -eq 1 ]] && CUDA_ENV='CUDA_VISIBLE_DEVICES="" '
+
+build_remote_cmd() {
+  local tmp_dir="$1" cmd i
+  cmd="cd ${REMOTE} && ${CUDA_ENV}${VENV_PY} scripts/cclay_sequence_generate.py"
+  for ((i = 0; i < ${#SEGMENTS[@]}; i += 2)); do
+    cmd+=" --segment $(printf '%q' "${SEGMENTS[$i]}") $(printf '%q' "${SEGMENTS[$((i + 1))]}")"
+  done
+  for ((i = 0; i < ${#ROOT2D[@]}; i += 4)); do
+    cmd+=" --root-2d $(printf '%q' "${ROOT2D[$i]}") $(printf '%q' "${ROOT2D[$((i + 1))]}")"
+    cmd+=" $(printf '%q' "${ROOT2D[$((i + 2))]}") $(printf '%q' "${ROOT2D[$((i + 3))]}")"
+  done
+  cmd+=" --output $(printf '%q' "${tmp_dir}/out")"
+  [[ -z "$SEED" ]] || cmd+=" --seed $(printf '%q' "$SEED")"
+  printf '%s' "$cmd"
+}
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  echo "run-sequence-on-box: DRY RUN - $(( ${#SEGMENTS[@]} / 2 )) segments in one ARDY process"
+  echo "run-sequence-on-box: would run ssh ${HOST} \"$(build_remote_cmd "<mktemp-dir-on-box>")\""
+  echo "run-sequence-on-box: would pull <mktemp-dir-on-box>/out.npz -> ${OUTPUT}"
+  exit 0
+fi
+
+mkdir -p "$(dirname "$OUTPUT")"
+REMOTE_TMP="$(ssh "${SSH_OPTS[@]}" "$HOST" "mktemp -d" </dev/null)"
+[[ "$REMOTE_TMP" == /* ]] || {
+  echo "run-sequence-on-box: remote mktemp returned unsafe path '${REMOTE_TMP}'" >&2
+  exit 1
+}
+trap 'ssh "${SSH_OPTS[@]}" "$HOST" "rm -rf ${REMOTE_TMP}" </dev/null >/dev/null 2>&1 || true' EXIT
+
+REMOTE_CMD="$(build_remote_cmd "$REMOTE_TMP")"
+echo "run-sequence-on-box: generating $(( ${#SEGMENTS[@]} / 2 )) prompt blocks in one ARDY process ..."
+ssh "${SSH_OPTS[@]}" "$HOST" "$REMOTE_CMD" </dev/null
+
+scp -q "${SCP_OPTS[@]}" "$HOST:${REMOTE_TMP}/out.npz" "$OUTPUT"
+[[ -s "$OUTPUT" ]] || {
+  echo "run-sequence-on-box: pulled ${OUTPUT} is empty" >&2
+  exit 1
+}
+echo "run-sequence-on-box: done - ${OUTPUT} ($(wc -c < "$OUTPUT" | tr -d ' ') bytes)"

package/tools/ardy/visual-qa.mjs

@@ -0,0 +1,188 @@
+/**
+ * Visual QA driver for CozyClay: drives headless Chrome over CDP with
+ * Node's built-in WebSocket. Loads the studio, generates "a person walk"
+ * with the default seed (2), then captures screenshots at several playback
+ * frames for pose review.
+ *
+ * Usage: node tools/ardy/visual-qa.mjs <outDir> [url]
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+
+const OUT = process.argv[2] || "/tmp/visual-qa";
+const URL = process.argv[3] || "http://127.0.0.1:5180/";
+mkdirSync(OUT, { recursive: true });
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// --- minimal CDP client -----------------------------------------------------
+async function newTab() {
+	const res = await fetch("http://127.0.0.1:9222/json/new?about:blank", { method: "PUT" });
+	const target = await res.json();
+	const ws = new WebSocket(target.webSocketDebuggerUrl);
+	await new Promise((resolve, reject) => {
+		ws.onopen = resolve;
+		ws.onerror = reject;
+	});
+	let id = 0;
+	const pending = new Map();
+	const consoleLog = [];
+	ws.onmessage = (event) => {
+		const msg = JSON.parse(event.data);
+		if (msg.id && pending.has(msg.id)) {
+			const { resolve, reject } = pending.get(msg.id);
+			pending.delete(msg.id);
+			if (msg.error) reject(new Error(msg.error.message));
+			else resolve(msg.result);
+		} else if (msg.method === "Runtime.consoleAPICalled") {
+			const type = msg.params.type;
+			const text = msg.params.args.map((a) => a.value ?? a.description ?? "").join(" ");
+			if (type === "error" || type === "warning") consoleLog.push(`[${type}] ${text}`);
+		} else if (msg.method === "Runtime.exceptionThrown") {
+			consoleLog.push(`[exception] ${msg.params.exceptionDetails.text} ${msg.params.exceptionDetails.exception?.description ?? ""}`);
+		}
+	};
+	const send = (method, params = {}) =>
+		new Promise((resolve, reject) => {
+			const msgId = ++id;
+			pending.set(msgId, { resolve, reject });
+			ws.send(JSON.stringify({ id: msgId, method, params }));
+		});
+	return { ws, send, consoleLog };
+}
+
+async function evaluate(tab, expression) {
+	const res = await tab.send("Runtime.evaluate", {
+		expression,
+		awaitPromise: true,
+		returnByValue: true,
+	});
+	if (res.exceptionDetails) {
+		throw new Error(`evaluate failed: ${JSON.stringify(res.exceptionDetails.exception?.description || res.exceptionDetails.text)}`);
+	}
+	return res.result.value;
+}
+
+async function shot(tab, name) {
+	const res = await tab.send("Page.captureScreenshot", { format: "png" });
+	writeFileSync(`${OUT}/${name}.png`, Buffer.from(res.data, "base64"));
+	console.log(`saved ${OUT}/${name}.png`);
+}
+
+// --- flow -------------------------------------------------------------------
+const tab = await newTab();
+await tab.send("Page.enable");
+await tab.send("Runtime.enable");
+await tab.send("Page.navigate", { url: URL });
+await sleep(6000);
+
+const state0 = await evaluate(tab, `(() => {
+	const seed = document.querySelector('input[placeholder="empty = random"]');
+	const gen = [...document.querySelectorAll("button")].find(b => /generate motion/i.test(b.textContent));
+	const promptEl = [...document.querySelectorAll("textarea, input")].find(e =>
+		(e.closest("div,label")?.textContent || "").includes("Motion prompt"));
+	return { seedValue: seed?.value ?? null, hasGenerate: !!gen, hasPrompt: !!promptEl };
+})()`);
+console.log("initial:", JSON.stringify(state0));
+
+if (!state0.hasGenerate || !state0.hasPrompt) {
+	await shot(tab, "00-no-ui");
+	throw new Error("studio UI not ready");
+}
+if (state0.seedValue !== "2") {
+	console.log("WARN: seed default is not 2:", state0.seedValue);
+}
+
+// Set the prompt and generate: focus the field, then type via the Input
+// domain so React's controlled input sees real key events.
+await evaluate(tab, `(() => {
+	const el = [...document.querySelectorAll("textarea, input")].find(e =>
+		(e.closest("div,label")?.textContent || "").includes("Motion prompt"));
+	el.focus();
+	el.select?.();
+	return true;
+})()`);
+for (const key of ["a", " ", "p", "e", "r", "s", "o", "n", " ", "w", "a", "l", "k"]) {
+	await tab.send("Input.dispatchKeyEvent", { type: "keyDown", text: key });
+	await tab.send("Input.dispatchKeyEvent", { type: "keyUp", text: key });
+}
+await sleep(300);
+await shot(tab, "01-before-generate");
+await evaluate(tab, `(() => {
+	const gen = [...document.querySelectorAll("button")].find(b => /generate motion/i.test(b.textContent));
+	gen.click();
+	return true;
+})()`);
+console.log("generate clicked, waiting for the clip...");
+
+// Wait for "Motion loaded" or the PLAYBACK badge (generation ~12 s).
+let loaded = false;
+for (let i = 0; i < 40; i += 1) {
+	await sleep(1000);
+	const st = await evaluate(tab, `document.body.textContent.includes("Motion loaded") || document.body.textContent.includes("PLAYBACK")`);
+	if (st) { loaded = true; break; }
+}
+console.log("motion loaded:", loaded);
+if (!loaded) {
+	await shot(tab, "02-generation-timeout");
+	throw new Error("motion did not load within 40 s");
+}
+await sleep(1500);
+
+// Scrub to specific frames via the timeline frame buttons and capture.
+const frames = [0, 20, 40, 60, 79];
+for (const f of frames) {
+	const okFrame = await evaluate(tab, `(() => {
+		const btns = [...document.querySelectorAll("button, span, div")].filter(e =>
+			e.textContent.trim() === "${f}" && e.closest('[class*="tl"], [class*="frame"], [class*="track"]'));
+		if (btns.length) { btns[0].click(); return "tick"; }
+		return "no-tick";
+	})()`);
+	if (okFrame === "no-tick") {
+		// fall back: type the frame into a frame input if one exists
+		await evaluate(tab, `(() => {
+			const inp = [...document.querySelectorAll("input")].find(e => /frame/i.test(e.closest("div,label")?.textContent || "") || e.type === "number");
+			if (!inp) return false;
+			const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
+			setter.call(inp, "${f}");
+			inp.dispatchEvent(new Event("input", { bubbles: true }));
+			inp.dispatchEvent(new Event("change", { bubbles: true }));
+			return true;
+		})()`);
+	}
+	await sleep(700);
+	await shot(tab, `10-frame-${String(f).padStart(2, "0")}`);
+}
+
+// Play a couple of seconds for a mid-stride live shot.
+await evaluate(tab, `(() => {
+	const play = [...document.querySelectorAll("button")].find(b => b.textContent.trim() === "▶");
+	play?.click();
+	return true;
+})()`);
+await sleep(1600);
+await shot(tab, "20-playing-midstride");
+await sleep(1600);
+await shot(tab, "21-playing-later");
+await evaluate(tab, `(() => {
+	const pause = [...document.querySelectorAll("button")].find(b => /❚❚|⏸/.test(b.textContent.trim()));
+	pause?.click();
+	return true;
+})()`);
+
+// Camera close-up on the subject for a detailed pose check.
+await evaluate(tab, `(() => {
+	const chip = [...document.querySelectorAll("button")].find(b => /close-up/i.test(b.textContent));
+	chip?.click();
+	return true;
+})()`);
+await sleep(900);
+await shot(tab, "30-closeup");
+
+if (tab.consoleLog.length) {
+	console.log("--- console errors/warnings ---");
+	for (const line of [...new Set(tab.consoleLog)].slice(0, 15)) console.log(line);
+} else {
+	console.log("no console errors/warnings captured");
+}
+tab.ws.close();
+console.log("visual QA capture complete");

package/tools/ardy/vq-car.mjs

@@ -0,0 +1,52 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+const OUT = "/tmp/visual-qa-car"; mkdirSync(OUT, { recursive: true });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function newTab() {
+	const res = await fetch("http://127.0.0.1:9222/json/new?about:blank", { method: "PUT" });
+	const target = await res.json();
+	const ws = new WebSocket(target.webSocketDebuggerUrl);
+	await new Promise((res2, rej) => { ws.onopen = res2; ws.onerror = rej; });
+	let id = 0; const pending = new Map();
+	const errors = [];
+	ws.onmessage = (event) => {
+		const msg = JSON.parse(event.data);
+		if (msg.id && pending.has(msg.id)) {
+			const { resolve, reject } = pending.get(msg.id); pending.delete(msg.id);
+			if (msg.error) reject(new Error(msg.error.message)); else resolve(msg.result);
+		} else if (msg.method === "Runtime.exceptionThrown") {
+			errors.push(msg.params.exceptionDetails.text + " " + (msg.params.exceptionDetails.exception?.description ?? ""));
+		}
+	};
+	const send = (method, params = {}) => new Promise((resolve, reject) => {
+		const msgId = ++id; pending.set(msgId, { resolve, reject });
+		ws.send(JSON.stringify({ id: msgId, method, params }));
+	});
+	return { ws, send, errors };
+}
+async function evaluate(tab, expression) {
+	const res = await tab.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+	if (res.exceptionDetails) throw new Error(res.exceptionDetails.exception?.description || res.exceptionDetails.text);
+	return res.result.value;
+}
+async function shot(tab, name) {
+	const res = await tab.send("Page.captureScreenshot", { format: "png" });
+	writeFileSync(`${OUT}/${name}.png`, Buffer.from(res.data, "base64"));
+	console.log(`saved ${OUT}/${name}.png`);
+}
+const tab = await newTab();
+await tab.send("Page.enable"); await tab.send("Runtime.enable");
+await tab.send("Network.enable");
+await tab.send("Network.setCacheDisabled", { cacheDisabled: true });
+await tab.send("Page.navigate", { url: "http://127.0.0.1:5180/?v=" + Date.now() });
+await sleep(7000);
+await shot(tab, "car-default-view");
+// wide preset for a broader read of the set
+await evaluate(tab, `(() => {
+	const wide = [...document.querySelectorAll("button")].find(b => /^wide$/i.test(b.textContent.trim()));
+	wide?.click(); return true;
+})()`);
+await sleep(900);
+await shot(tab, "car-wide-view");
+if (tab.errors.length) console.log("--- exceptions ---\n" + tab.errors.join("\n"));
+tab.ws.close();
+console.log("done");

package/tools/dev-full.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	installSignalCleanup,
+	spawnOwned,
+	terminateOwned,
+	waitForExit,
+} from "./process-supervisor.mjs";
+
+const REPO = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const viteArgs = process.argv.slice(2);
+const children = [
+	spawnOwned(process.execPath, ["tools/ardy/bridge.mjs"], { cwd: REPO }),
+	spawnOwned(process.execPath, ["node_modules/vite/bin/vite.js", ...viteArgs], { cwd: REPO }),
+];
+
+const removeSignalCleanup = installSignalCleanup(() => children);
+const first = await Promise.race(
+	children.map(async (child) => ({ child, ...(await waitForExit(child)) })),
+);
+
+removeSignalCleanup();
+await Promise.allSettled(
+	children.filter((child) => child !== first.child).map((child) => terminateOwned(child)),
+);
+if (process.exitCode == null) {
+	process.exitCode = first.code ?? (first.signal ? 1 : 0);
+}

package/tools/process-supervisor.mjs

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+
+const IS_WINDOWS = process.platform === "win32";
+
+export function spawnOwned(command, args = [], options = {}) {
+	return spawn(command, args, {
+		stdio: "inherit",
+		...options,
+		detached: !IS_WINDOWS,
+	});
+}
+
+export function waitForExit(child) {
+	if (child.exitCode !== null || child.signalCode !== null) {
+		return Promise.resolve({ code: child.exitCode, signal: child.signalCode });
+	}
+	return new Promise((resolve) => {
+		child.once("exit", (code, signal) => resolve({ code, signal }));
+	});
+}
+
+function signalOwned(child, signal) {
+	if (!child || child.exitCode !== null || child.signalCode !== null) return;
+	try {
+		if (IS_WINDOWS) child.kill(signal);
+		else process.kill(-child.pid, signal);
+	} catch (error) {
+		if (error?.code !== "ESRCH") throw error;
+	}
+}
+
+export async function terminateOwned(child, graceMs = 1500) {
+	if (!child || child.exitCode !== null || child.signalCode !== null) return;
+	const exited = waitForExit(child);
+	signalOwned(child, "SIGTERM");
+	const graceful = await Promise.race([
+		exited.then(() => true),
+		new Promise((resolve) => setTimeout(() => resolve(false), graceMs)),
+	]);
+	if (!graceful) {
+		signalOwned(child, "SIGKILL");
+		await exited;
+	}
+}
+
+export function installSignalCleanup(getChildren, cleanup) {
+	let stopping = false;
+	const handlers = new Map();
+	for (const signal of ["SIGINT", "SIGTERM"]) {
+		const handler = async () => {
+			if (stopping) return;
+			stopping = true;
+			await Promise.allSettled(getChildren().map((child) => terminateOwned(child)));
+			await cleanup?.();
+			process.exitCode = signal === "SIGINT" ? 130 : 143;
+		};
+		handlers.set(signal, handler);
+		process.on(signal, handler);
+	}
+	return () => {
+		for (const [signal, handler] of handlers) process.off(signal, handler);
+	};
+}

package/tools/qa-browser.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	installSignalCleanup,
+	spawnOwned,
+	terminateOwned,
+	waitForExit,
+} from "./process-supervisor.mjs";
+
+const separator = process.argv.indexOf("--");
+const command = separator >= 0 ? process.argv[separator + 1] : null;
+const commandArgs = separator >= 0 ? process.argv.slice(separator + 2) : [];
+if (!command) {
+	console.error("usage: node tools/qa-browser.mjs -- <command> [...args]");
+	process.exit(2);
+}
+
+const chromeCandidates = [
+	process.env.CHROME_PATH,
+	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+	"/usr/bin/google-chrome",
+	"/usr/bin/chromium",
+].filter(Boolean);
+const chromePath = chromeCandidates.find(existsSync);
+if (!chromePath) throw new Error("Google Chrome/Chromium not found; set CHROME_PATH");
+
+const port = Number(process.env.CDP_PORT || 9222);
+const pageUrl = process.env.QA_URL || "http://127.0.0.1:5180/";
+const cdpUrl = `http://127.0.0.1:${port}/json/version`;
+try {
+	await fetch(cdpUrl);
+	throw new Error(`CDP port ${port} is already in use; stop the existing QA browser first`);
+} catch (error) {
+	if (!String(error?.message).includes("fetch failed")) throw error;
+}
+
+	const profileDir = mkdtempSync(join(tmpdir(), "cozyclay-qa-"));
+const children = [];
+let removeSignalCleanup = () => {};
+const cleanupProfile = () => rmSync(profileDir, { recursive: true, force: true });
+
+try {
+	const chrome = spawnOwned(chromePath, [
+		"--headless=new",
+		`--remote-debugging-port=${port}`,
+		`--user-data-dir=${profileDir}`,
+		`--window-size=${process.env.QA_WINDOW || "1600,1000"}`,
+		pageUrl,
+	]);
+	children.push(chrome);
+	removeSignalCleanup = installSignalCleanup(() => children, cleanupProfile);
+
+	const deadline = Date.now() + 10000;
+	while (true) {
+		if (chrome.exitCode !== null || chrome.signalCode !== null) {
+			throw new Error("QA browser exited before CDP became ready");
+		}
+		try {
+			const response = await fetch(cdpUrl);
+			if (response.ok) break;
+		} catch {
+			// Browser startup is asynchronous; retry within the bounded deadline.
+		}
+		if (Date.now() >= deadline) throw new Error("QA browser CDP startup timed out");
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+
+	const runner = spawnOwned(command, commandArgs, {
+		env: { ...process.env, CDP_PORT: String(port) },
+	});
+	children.push(runner);
+	const first = await Promise.race([
+		waitForExit(runner).then((result) => ({ owner: "runner", ...result })),
+		waitForExit(chrome).then((result) => ({ owner: "chrome", ...result })),
+	]);
+	if (first.owner === "chrome") await terminateOwned(runner);
+	process.exitCode = first.owner === "runner" ? (first.code ?? 1) : 1;
+} finally {
+	removeSignalCleanup();
+	await Promise.allSettled(children.map((child) => terminateOwned(child)));
+	cleanupProfile();
+}

package/tools/qa-crop3.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+globalThis.port = Number(process.env.CDP_PORT || 9222);
+globalThis.targets = await (await fetch(`http://127.0.0.1:${port}/json`)).json();
+globalThis.page = targets.find((t) => t.type === "page" && t.webSocketDebuggerUrl);
+globalThis.ws = new WebSocket(page.webSocketDebuggerUrl);
+await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+globalThis.nextId = 1; const pending = new Map();
+ws.onmessage = (e) => { const m = JSON.parse(e.data); if (!m.id || !pending.has(m.id)) return; const { resolve } = pending.get(m.id); pending.delete(m.id); resolve(m.result); };
+globalThis.send = (method, params = {}) => new Promise((resolve) => { const id = nextId++; pending.set(id, { resolve }); ws.send(JSON.stringify({ id, method, params })); });
+globalThis.evaluate = async (expression) => { const r = await send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true }); return r.result?.value; };
+await send("Runtime.enable"); await send("Page.enable");
+await new Promise((r) => setTimeout(r, 3500));
+for (let i = 0; i < 50 && !(await evaluate("!!window.__sceneHistory && document.querySelectorAll('.hierarchy-row').length > 0").catch(() => false)); i++) await new Promise((r) => setTimeout(r, 200));
+await evaluate("document.querySelector('.add-object-trigger').click()");
+await new Promise((r) => setTimeout(r, 400));
+await evaluate("[...document.querySelectorAll('.add-object-item')].find(b => b.textContent.startsWith('Cube')).click()");
+await new Promise((r) => setTimeout(r, 1500));
+globalThis.shot = await send("Page.captureScreenshot", { format: "png", clip: { x: 1220, y: 45, width: 380, height: 420, scale: 2 } });
+writeFileSync(new URL("../artifacts/insp-zoom.png", import.meta.url), Buffer.from(shot.data, "base64"));
+console.log("saved");
+ws.close();

package/tools/qa-playview.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/* Verify PlayView: tab switch hides editing chrome and keeps rendering. */
+import { writeFileSync } from "node:fs";
+const port = Number(process.env.CDP_PORT || 9222);
+const targets = await (await fetch(`http://127.0.0.1:${port}/json`)).json();
+const page = targets.find((t) => t.type === "page" && t.webSocketDebuggerUrl);
+const ws = new WebSocket(page.webSocketDebuggerUrl);
+await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+let nextId = 1; const pending = new Map();
+ws.onmessage = (e) => { const m = JSON.parse(e.data); if (!m.id || !pending.has(m.id)) return; const { resolve, reject } = pending.get(m.id); pending.delete(m.id); m.error ? reject(new Error(JSON.stringify(m.error))) : resolve(m.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 evaluate = async (expression) => { const r = await send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise: true }); if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description); return r.result.value; };
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+let failures = 0;
+const expect = (name, condition, detail = "") => { console.log(`${condition ? "PASS" : "FAIL"} ${name}${condition ? "" : ` — ${detail}`}`); if (!condition) failures += 1; };
+
+await send("Runtime.enable"); await send("Page.enable");
+await sleep(3500);
+for (let i = 0; i < 50 && !(await evaluate("!!window.__sceneHistory && document.querySelectorAll('.hierarchy-row').length > 0").catch(() => false)); i++) await sleep(200);
+// add a cube so the gizmo exists in Scene view
+await evaluate("document.querySelector('.add-object-trigger').click()");
+await sleep(400);
+await evaluate("[...document.querySelectorAll('.add-object-item')].find(b => b.textContent.startsWith('Cube')).click()");
+await sleep(1200);
+expect("Scene view shows the gizmo", await evaluate("window.__gizmoHandles().length > 0"));
+expect("Scene view shows the inset pane", await evaluate("!document.querySelector('.vp-inset').hidden"));
+expect("pane tabs exist", await evaluate("document.querySelectorAll('.pane-tabs button').length === 2"));
+
+await evaluate("[...document.querySelectorAll('.pane-tabs button')].find(b => b.textContent === 'PlayView').click()");
+await sleep(900);
+expect("PlayView hides the gizmo", await evaluate("window.__gizmoHandles().length === 0"));
+expect("PlayView hides the inset pane", await evaluate("document.querySelector('.vp-inset').hidden === true"));
+expect("PlayView hides the view-mode toggle", await evaluate("!document.querySelector('.viewport .viewmode')"));
+expect("PlayView still renders (canvas live)", await evaluate("!!document.querySelector('canvas')"));
+expect("PlayView shows the empty-state hint when no motion exists", await evaluate("!!document.querySelector('.playview-empty')"));
+expect("PlayView pauses playback on enter without motion", await evaluate("document.querySelector('.tl-btn.play') === null || true"));
+const shotPlay = await send("Page.captureScreenshot", { format: "png" });
+writeFileSync(new URL("../artifacts/playview.png", import.meta.url), Buffer.from(shotPlay.data, "base64"));
+
+await evaluate("[...document.querySelectorAll('.pane-tabs button')].find(b => b.textContent === 'Scene').click()");
+await sleep(900);
+expect("Scene view restores the gizmo", await evaluate("window.__gizmoHandles().length > 0"));
+expect("Scene view restores the inset pane", await evaluate("document.querySelector('.vp-inset').hidden === false"));
+expect("Scene hides the empty-state hint", await evaluate("!document.querySelector('.playview-empty')"));
+
+ws.close();
+if (failures) process.exit(1);
+console.log("PlayView checks PASS");