cozyclay 3.0.2 → 3.1.0

package/tools/dev/pages/greybox-to-video.html

@@ -107,9 +107,8 @@
         <h2>Do it in the browser</h2>
         <p>
           CozyClay is open source previs that runs in a Chromium tab. It exists for exactly this loop: block,
-          camera, export, generate. The <a href="/#try">playground on the home page</a> walks through the camera
-          part in seven moves on the same city block you see in the reels, and <code>npx cozyclay --scene city-block</code>
-          opens that set on your machine.
+          camera, export, generate. The <a href="/#try">playground on the home page</a> runs the studio in the page, and
+          <code>npx cozyclay</code> runs it on your machine.
         </p>
         <div class="cta">
           <a class="btn primary" href="/#try">Try it in your browser</a>

package/tools/dev/pages/previs-software.html

@@ -64,8 +64,8 @@
         <p>
           The honest split is time, not money. Blender can do everything on this page and will take an
           afternoon to learn just the camera. CozyClay does one thing (block, camera, cut, export) and expects
-          you to be productive in the first ten minutes; there is a <a href="/#try">seven-step tutorial on the home page</a>
-          that takes about that long.
+          you to be productive in the first ten minutes; the <a href="/#try">playground on the home page</a>
+          runs it in the page.
         </p>
       </section>
 

package/tools/dev/pages/privacy.html

@@ -86,12 +86,11 @@ cclay telemetry on</code></pre>
             <thead><tr><th>Event</th><th>Purpose</th></tr></thead>
             <tbody>
               <tr><td>install:first_launch, app:session_started, app:session_ended</td><td>Counting installs and sessions; duration and action counts are bucketed. install:first_launch may carry heard_from (x, hn, reddit, github, friend, other, site or playground), from the first-launch prompt or a copied <code>npx cozyclay --via</code> command. app:session_ended also carries per-session edit gesture counts in five groups, pose_edit_bucket, camera_edit_bucket, object_edit_bucket, shot_edit_bucket and prompt_edit_bucket, each bucketed (0, 1-3, 4-10 or gte11); never what was edited</td></tr>
-              <tr><td>feature:used</td><td>One signal per feature per session: a fixed feature name such as pose_edit (a real bone or pose change), pose_save (saving a pose to the library), fal_motion_open (opening the AI video A/B card), camera_fly or export_video</td></tr>
+              <tr><td>feature:used</td><td>One signal per feature per session: a fixed feature name such as pose_edit (a real bone or pose change), pose_save (saving a pose to the library), camera_fly or export_video</td></tr>
               <tr><td>$pageview, scene:created, scene:loaded, craft:first_action, activation:completed</td><td>Funnel and drop-off analysis</td></tr>
               <tr><td>craft:first_edit</td><td>First successful Studio authoring change per editor mount; only a fixed edit-kind label and definition version 1 (not camera navigation, playback, loading, restore, or undo/redo)</td></tr>
               <tr><td>playground:first_edit</td><td>The same versioned first-edit definition for Playground, counted separately from Studio; no prompts or scene contents</td></tr>
               <tr><td>project:saved, project:opened</td><td>Whether people keep their work (object counts and ages are bucketed; never names or paths)</td></tr>
-              <tr><td>motion:backend_state</td><td>Session capability baseline: backend (none, local_kimodo or hosted) and boolean host_configured, never a host address</td></tr>
               <tr><td>motion:generate_requested</td><td>Explicit generation intent, not prompt-block editing: initiating surface (timeline, line_edit, trail, mcp, fal_card or agent), input_mode (prompt, pose, edit, a_to_b or still) and an ephemeral random request_id</td></tr>
               <tr><td>motion:preflight_blocked</td><td>Request readiness refusal: request_id, surface and normalized reason (unconfigured, unreachable, unsupported_route, locked or missing_input). locked means the AI video route is not enabled for the account yet; missing_input means the A/B captures were incomplete</td></tr>
               <tr><td>motion:preflight_passed</td><td>Request readiness accepted, before job start: request_id, surface and backend (none, local_kimodo, hosted or fal)</td></tr>
@@ -117,10 +116,6 @@ cclay telemetry on</code></pre>
               <tr><td>device:profile</td><td>Once per session, whether the studio can run smoothly: gpu_vendor (nvidia, amd, intel, apple, qualcomm, arm, software, other or unknown), gpu_class (discrete, integrated, software or unknown), webgl (webgl2, webgl1 or none), cpu_bucket (1-4, 5-8, 9-16, gte17 or unknown), memory_bucket (lt4, 4-7, gte8 or unknown) and frame_rate_bucket (lt20, 20-40, 40-55, gte55 or unknown) from one three-second sample. The GPU renderer string and exact hardware values never leave the browser.</td></tr>
               <tr><td>survey:use_case</td><td>An optional question shown at most once after a successful export, only while telemetry is on: use_case (animation, film, game, ad_mv, personal, other or skip) and team (team, solo or skip). Closed choices only; no free text.</td></tr>
               <tr><td>hosted:composer_viewed, hosted:login_started, hosted:ticket_created, hosted:result_opened, hosted:opened_in_studio</td><td>Hosted demo funnel</td></tr>
-              <tr><td>tutorial:started</td><td>Camera tutorial attempts on surface (studio or playground), with numeric tutorial_version 1 and start_source (query, settings or landing). Restarting starts a new attempt; no tutorial attempt identifier or user text is sent.</td></tr>
-              <tr><td>tutorial:step_entered, tutorial:dismissed</td><td>Entered steps and explicit dismissal of an unfinished tutorial; surface (studio or playground), numeric tutorial_version 1 and step_kind (fly, walk, dolly, orbit, shot, rail or play). Missing completion can indicate abandonment or missing telemetry; browser close does not promise a dismissal event.</td></tr>
-              <tr><td>tutorial:step_completed</td><td>One completion per step per attempt; surface (studio or playground), numeric tutorial_version 1, step_kind (fly, walk, dolly, orbit, shot, rail or play) and elapsed_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s) since entering that step. No raw timing, prompts, scene contents, names or paths.</td></tr>
-              <tr><td>tutorial:completed</td><td>All seven steps completed; surface (studio or playground), numeric tutorial_version 1 and elapsed_bucket (lt1s, 1-3s, 3-10s, 10-30s or gte30s) since tutorial start. Sample loading and camera playback do not count as a user edit.</td></tr>
             </tbody>
           </table>
         </div>
@@ -132,7 +127,8 @@ cclay telemetry on</code></pre>
       <section>
         <h2>The hosted demo (Google sign-in)</h2>
         <p>
-          The hosted motion demo asks you to sign in with Google so that the daily generation cap can be
+          The hosted demo is not open to the public right now. This section describes what it handled while it
+          was running. The hosted motion demo asks you to sign in with Google so that the daily generation cap can be
           enforced per account. It receives your Google account's email address and basic profile only, stores
           a session cookie signed by our server, and keeps your prompt and the generated result for up to 30
           days so the ticket link keeps working. Results are stored on Cloudflare R2 and deleted after that

package/tools/dev/pages/seedance-camera-control.html

@@ -87,8 +87,8 @@
           Any 3D tool that renders flat can make the reference. Blender works with a clay material and a
           workbench render. CozyClay, open source and in the browser, exports the flat clip directly with the
           delivery ratio and a camera timeline built in; the reel at the top of this page came out of it.
-          The <a href="/#try">home-page playground</a> walks through blocking a shot and drawing a dolly rail in
-          seven moves, and <code>npx cozyclay --scene city-block</code> opens that set locally.
+          The <a href="/#try">home-page playground</a> runs the studio in the page, and
+          <code>npx cozyclay</code> runs it locally.
         </p>
         <div class="cta">
           <a class="btn primary" href="/#try">Try it in your browser</a>

package/tools/dev-full.mjs

@@ -45,7 +45,6 @@ await new Promise((resolvePromise, reject) => {
 });
 
 const children = [];
-const removeSignalCleanup = installSignalCleanup(() => children, () => {});
 const agentHandler = createAgentHandler({ port: mainPort });
 const oauthServer = createServer((req, res) => {
 	const path = (req.url || "").split("?")[0];
@@ -62,6 +61,16 @@ const oauthPort = configuredOAuthPort ? Number(configuredOAuthPort) : 0;
 await new Promise((resolvePromise, reject) => { oauthServer.once("error", reject); oauthServer.listen({ port: oauthPort, host: "127.0.0.1" }, resolvePromise); });
 const actualOAuthPort = oauthServer.address().port;
 
+// The oauth/agent HTTP server and the agent's live hub (its own listener on
+// COZYCLAY_LIVE_PORT) keep the event loop alive, so shutdown must close both
+// (dropping open keep-alive/SSE sockets) or the process never exits.
+const closeServers = async () => {
+	const httpClosed = new Promise((resolvePromise) => oauthServer.close(() => resolvePromise()));
+	oauthServer.closeAllConnections();
+	await Promise.allSettled([httpClosed, agentHandler.close()]);
+};
+const removeSignalCleanup = installSignalCleanup(() => children, closeServers);
+
 const vite = spawnOwned(process.execPath, ["node_modules/vite/bin/vite.js", ...viteArgs], {
 	cwd: REPO,
 		env: {
@@ -77,7 +86,7 @@ const first = await Promise.race(
 );
 
 removeSignalCleanup();
-await new Promise((resolvePromise) => oauthServer.close(resolvePromise));
+await closeServers();
 await Promise.allSettled(
 	children.filter((child) => child !== first.child).map((child) => terminateOwned(child)),
 );

package/tools/eslint-baseline.json

@@ -7,16 +7,16 @@
 	"no-regex-spaces": 2,
 	"no-undef": 24,
 	"no-unsafe-finally": 2,
-	"no-unused-vars": 100,
-	"no-useless-assignment": 10,
+	"no-unused-vars": 98,
+	"no-useless-assignment": 9,
 	"no-useless-escape": 6,
 	"preserve-caught-error": 6,
-	"react-hooks/immutability": 88,
-	"react-hooks/preserve-manual-memoization": 31,
+	"react-hooks/immutability": 81,
+	"react-hooks/preserve-manual-memoization": 28,
 	"react-hooks/purity": 5,
-	"react-hooks/refs": 111,
+	"react-hooks/refs": 102,
 	"react-hooks/rules-of-hooks": 2,
-	"react-hooks/set-state-in-effect": 30,
+	"react-hooks/set-state-in-effect": 26,
 	"react-hooks/use-memo": 1,
 	"require-yield": 2
 }

package/tools/knip-baseline.json

@@ -7,14 +7,7 @@
 	"export mcp/image-file.mjs#REFERENCE_MAX_BYTES",
 	"export src/asset-pane.jsx#CHARACTER_ASSETS",
 	"export src/asset-pane.jsx#FolderGrid",
-	"export src/burn-in.js#burnInCapture",
 	"export src/camera-block.js#CAMERA_MODES",
-	"export src/camera-tutorial.jsx#CAMERA_TUTORIAL_STEPS",
-	"export src/camera-tutorial.jsx#GestureCue",
-	"export src/camera-tutorial.jsx#TUTORIAL_BEACONS",
-	"export src/camera-tutorial.jsx#TutorialBeacon",
-	"export src/camera-tutorial.jsx#WALK_KEYS",
-	"export src/camera-tutorial.jsx#default",
 	"export src/domains/motion.js#createMotionDomain",
 	"export src/domains/objects.js#createObjectsDomain",
 	"export src/grid-view.js#STAGE_BACKGROUND_LIGHT",
@@ -23,13 +16,10 @@
 	"export src/mesh-sniff.js#looksLikeObj",
 	"export src/mesh-sniff.js#readFbxVersion",
 	"export src/object-catalog.jsx#default",
-	"export src/object-path.js#MAX_PATH_HEIGHT",
 	"export src/project.js#storeProjectHandle",
 	"export src/range-pin-panel.jsx#RANGE_PIN_TRACKS",
 	"export src/scene-asset-cache.js#loadAssetTexture",
 	"export src/scene-mesh-cache.js#loadMeshScene",
-	"export src/scenes.js#CHARACTER_SCALE_MAX",
-	"export src/scenes.js#CHARACTER_SCALE_MIN",
 	"export src/scenes.js#LEGACY_FRAME_FPS",
 	"export src/scenes.js#toTimelineFrame",
 	"export src/stage-attach-frames.js#ATTACH_BONE_NAMES",
@@ -55,7 +45,6 @@
 	"export src/stage-editor-gizmos.jsx#GizmoLabel",
 	"export src/stage-editor-gizmos.jsx#prepareRailBend",
 	"export src/ui-scrub.js#SCRUB_RANGE_STEPS",
-	"export src/use-semantic-state.js#useSemanticState",
 	"export src/workflow/AgentPanel.jsx#AGENT_PANEL_RAIL_WIDTH",
 	"export src/workflow/AgentPanel.jsx#AGENT_STATES",
 	"export src/workflow/video-contract.js#falVideoContract",

package/tools/loc-baseline.json

@@ -1,34 +1,33 @@
 {
-	"bin/agent/agent-routes.mjs": 865,
-	"bin/agent/agent-runner.mjs": 496,
-	"bin/agent/providers.mjs": 409,
+	"bin/agent/agent-routes.mjs": 804,
+	"bin/agent/agent-runner.mjs": 495,
+	"bin/agent/providers.mjs": 338,
 	"bin/agent/session-store.mjs": 324,
 	"bin/agent/supervisor.mjs": 283,
 	"bin/agent/video-adapters.mjs": 334,
-	"bin/cozyclay.mjs": 440,
+	"bin/cozyclay.mjs": 438,
 	"bin/live/cli.mjs": 456,
 	"mcp/live-hub.mjs": 529,
 	"mcp/tool-handlers.mjs": 1730,
-	"mcp/verify-live-batch.mjs": 486,
+	"mcp/verify-live-batch.mjs": 485,
 	"mcp/verify-live-capture.mjs": 268,
 	"mcp/verify-live-controller.mjs": 340,
 	"mcp/verify-live-p0.mjs": 264,
 	"mcp/verify-live.mjs": 416,
-	"src/analytics.js": 1169,
-	"src/App.jsx": 4711,
-	"src/asset-pane.jsx": 648,
+	"src/analytics.js": 1038,
+	"src/App.jsx": 4476,
+	"src/asset-pane.jsx": 643,
 	"src/camera-follow.js": 505,
 	"src/camera-move.js": 289,
-	"src/camera-tutorial.jsx": 443,
-	"src/command-bus.js": 378,
-	"src/controls.jsx": 340,
+	"src/command-bus.js": 356,
+	"src/controls.jsx": 330,
 	"src/domains/cast.js": 717,
-	"src/domains/motion.js": 812,
+	"src/domains/motion.js": 806,
 	"src/domains/objects.js": 907,
-	"src/domains/scenes.js": 754,
+	"src/domains/scenes.js": 740,
 	"src/domains/shots.js": 411,
-	"src/dualview.jsx": 371,
-	"src/hierarchy-panel.jsx": 779,
+	"src/dualview.jsx": 365,
+	"src/hierarchy-panel.jsx": 777,
 	"src/live-control.js": 338,
 	"src/matte-editor.js": 486,
 	"src/matte.js": 472,
@@ -36,41 +35,41 @@
 	"src/motion/fix-collisions.js": 748,
 	"src/motion/ik.js": 1135,
 	"src/motion/range-pin.js": 277,
-	"src/motion/timeline.jsx": 2047,
-	"src/object-gizmo.jsx": 824,
+	"src/motion/timeline.jsx": 2042,
+	"src/object-gizmo.jsx": 740,
 	"src/object-path.js": 410,
 	"src/panels/ObjectTransformPanel.jsx": 545,
 	"src/panels/SculptPanel.jsx": 370,
 	"src/planview.jsx": 887,
 	"src/poses.js": 321,
 	"src/posestudio.jsx": 1240,
-	"src/project-browser.jsx": 401,
+	"src/project-browser.jsx": 371,
 	"src/project.js": 603,
-	"src/props.jsx": 417,
+	"src/props.jsx": 414,
 	"src/range-pin-panel.jsx": 305,
 	"src/scene-assets.js": 400,
 	"src/scene-mesh.js": 350,
-	"src/scene-objects.js": 1136,
-	"src/scenes.js": 387,
+	"src/scene-objects.js": 1134,
+	"src/scenes.js": 385,
 	"src/sculpt-compare.js": 357,
 	"src/sculpt-recipe.js": 363,
 	"src/sculpt-run.js": 309,
 	"src/shell/BoardSlot.jsx": 316,
 	"src/shell/BottomDock.jsx": 416,
 	"src/shell/DetailsSlot.jsx": 334,
-	"src/shell/MenuBar.jsx": 640,
-	"src/shell/PreferencesDialog.jsx": 466,
+	"src/shell/MenuBar.jsx": 632,
+	"src/shell/PreferencesDialog.jsx": 269,
 	"src/shell/ViewportToolbar.jsx": 567,
-	"src/shot-authoring.js": 348,
-	"src/stage-canvas-rigs.jsx": 352,
+	"src/shot-authoring.js": 345,
+	"src/stage-canvas-rigs.jsx": 350,
 	"src/stage-editor-gizmos.jsx": 1116,
-	"src/studio-agent-commands.js": 492,
-	"src/studio-agent-protocol.js": 486,
+	"src/studio-agent-commands.js": 487,
+	"src/studio-agent-protocol.js": 480,
 	"src/studio-app-binding.js": 346,
-	"src/ui.jsx": 393,
-	"src/workflow/agent-client.js": 1386,
-	"src/workflow/AgentPanel.jsx": 880,
+	"src/ui.jsx": 385,
+	"src/workflow/agent-client.js": 1369,
+	"src/workflow/AgentPanel.jsx": 811,
 	"src/workflow/WorkflowBuilder.jsx": 592,
 	"tools/qa/css-rule-usage.mjs": 251,
-	"tools/run-tests.mjs": 448
+	"tools/run-tests.mjs": 441
 }

package/tools/metrics-snapshot.mjs

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
 /**
- * Snapshot GitHub traffic + repo stats + npm downloads into JSONL ledgers.
+ * Snapshot GitHub traffic, stars, referrers, repo stats and npm downloads
+ * into JSONL ledgers on the `metrics` branch.
  *
- * GitHub's traffic API only keeps 14 days, so this must run on a schedule
+ * GitHub's traffic API only keeps 14 days, so this runs daily
  * (.github/workflows/metrics.yml) to build a permanent time series. Rows are
  * deduped by date so overlapping 14-day windows never double-count.
  *
+ * Files written to <output-dir>:
+ *   traffic-daily.jsonl  one row per UTC day: views, view_uniques, clones, clone_uniques
+ *   stars-daily.jsonl    one row per UTC day: new_stars, total (rebuilt from starred_at)
+ *   referrers.jsonl      one row per run date: 14-day top referrers and paths
+ *   repo-stats.jsonl     one row per run date: stars, forks, watchers, issues, npm weekly
+ *
  * Usage: GITHUB_TOKEN=... node tools/metrics-snapshot.mjs <output-dir>
  */
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
@@ -26,9 +33,9 @@ if (!token) {
 	process.exit(2);
 }
 
-async function github(path) {
+async function github(path, accept = "application/vnd.github+json") {
 	const res = await fetch(`https://api.github.com/repos/${REPO}${path}`, {
-		headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+		headers: { authorization: `Bearer ${token}`, accept },
 	});
 	if (!res.ok) throw new Error(`GET ${path} -> ${res.status}`);
 	return res.json();
@@ -95,4 +102,35 @@ stats.set(today, {
 });
 const statsTotal = saveRows(statsFile, stats);
 
-console.log(`traffic-daily: +${added} new day(s), ${trafficTotal} total; repo-stats: ${statsTotal} snapshot(s)`);
+// 3) Stars per UTC day, rebuilt from every stargazer's starred_at. Someone who
+// later unstars drops out of the history, so totals can trail repo.stargazers_count
+// by a few. Rebuilt in full each run, so it never drifts.
+const starDays = new Map();
+for (let page = 1; page <= 400; page++) {
+	const batch = await github(`/stargazers?per_page=100&page=${page}`, "application/vnd.github.star+json");
+	if (!Array.isArray(batch) || batch.length === 0) break;
+	for (const s of batch) {
+		const day = String(s.starred_at).slice(0, 10);
+		starDays.set(day, (starDays.get(day) ?? 0) + 1);
+	}
+	if (batch.length < 100) break;
+}
+const starRows = new Map();
+let running = 0;
+for (const day of [...starDays.keys()].sort()) {
+	running += starDays.get(day);
+	starRows.set(day, { date: day, new_stars: starDays.get(day), total: running });
+}
+const starsTotal = saveRows(join(outDir, "stars-daily.jsonl"), starRows);
+
+// 4) 14-day referrers and paths, one snapshot per run date.
+const [referrers, paths] = await Promise.all([github("/traffic/popular/referrers"), github("/traffic/popular/paths")]);
+const refFile = join(outDir, "referrers.jsonl");
+const refs = loadRows(refFile);
+refs.set(today, { date: today, referrers, paths });
+const refTotal = saveRows(refFile, refs);
+
+console.log(
+	`traffic-daily: +${added} new day(s), ${trafficTotal} total; repo-stats: ${statsTotal} snapshot(s); ` +
+		`stars-daily: ${starsTotal} day(s), ${running} stars; referrers: ${refTotal} snapshot(s)`,
+);

package/tools/render-start-thumbs.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Render the start-screen template thumbnails from the real studio.
+ *
+ *   npm run dev -- --port 5180            # any running dev server
+ *   node tools/render-start-thumbs.mjs [--url http://127.0.0.1:5180/app/] [--out public/thumbs]
+ *
+ * For each template (Blank Stage plus every entry in STARTER_SCENES) and each
+ * theme, this opens the studio in a fresh headless Chrome profile, creates the
+ * project the way a user does (Blank Stage: the chooser's Create button; a
+ * starter: `?scene=<id>`), renders one offscreen frame through the studio's own
+ * capture path (`window.__cozyclay.captureFraming`), and writes
+ * `<out>/<template-id>-<theme>.webp` at 680x383 (2x the 340px preview).
+ * The chooser picks the file by id and theme and falls back to a plain tile
+ * when it is missing, so a new starter only needs this script re-run. A
+ * starter with no entry in FRAMINGS is shot through its own shot camera.
+ *
+ * Options: --url, --out, --cdp-port (default 9472), --only <template-id>.
+ * CHROME_PATH picks the browser; THUMBS_CHROME_FLAGS replaces the GPU flags
+ * (default: Metal on macOS, SwiftShader elsewhere).
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnOwned, terminateOwned } from "./process-supervisor.mjs";
+import { STARTER_SCENES } from "../src/starter-scenes.js";
+import { THEMES, THEME_KEY } from "../src/theme.js";
+
+const ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const WIDTH = 680;
+const HEIGHT = 383;
+const MAX_BYTES = 60 * 1024;
+
+function arg(name, fallback) {
+	const argv = process.argv.slice(2);
+	const index = argv.indexOf(name);
+	return index >= 0 ? argv[index + 1] : fallback;
+}
+const appUrl = new URL(arg("--url", "http://127.0.0.1:5180/app/"));
+const outDir = resolve(ROOT, arg("--out", "public/thumbs"));
+const cdpPort = Number(arg("--cdp-port", 9472));
+const only = arg("--only", null);
+const chromePath = process.env.CHROME_PATH || "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+const gpuFlags = (process.env.THUMBS_CHROME_FLAGS
+	?? (process.platform === "darwin" ? "--use-angle=metal --ignore-gpu-blocklist" : "--use-angle=swiftshader --enable-unsafe-swiftshader"))
+	.split(/\s+/).filter(Boolean);
+
+/** A studio framing ({ pos, yaw, pitch, fovDeg }) from an eye point and a target. */
+function lookAt(eye, target, fovDeg) {
+	const [dx, dy, dz] = target.map((value, index) => value - eye[index]);
+	return { pos: { x: eye[0], y: eye[1], z: eye[2] }, yaw: Math.atan2(-dx, -dz), pitch: Math.atan2(dy, Math.hypot(dx, dz)), fovDeg };
+}
+
+// Eye-level 3/4 view. Blank Stage: the default character on the floor grid.
+const FRAMINGS = {
+	"blank-stage": lookAt([1.6, 1.55, 3.7], [0, 0.88, 0], 40),
+};
+
+const templates = [
+	{ id: "blank-stage", url: appUrl.href, create: true },
+	...STARTER_SCENES.map((scene) => ({ id: scene.id, url: `${appUrl.href}?scene=${encodeURIComponent(scene.id)}`, create: false })),
+].filter((template) => !only || template.id === only);
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+async function connect() {
+	const deadline = Date.now() + 30000;
+	while (Date.now() < deadline) {
+		try {
+			const targets = await (await fetch(`http://127.0.0.1:${cdpPort}/json`)).json();
+			const page = targets.find((target) => target.type === "page" && target.webSocketDebuggerUrl);
+			if (page) {
+				const ws = new WebSocket(page.webSocketDebuggerUrl);
+				await new Promise((done, fail) => { ws.onopen = done; ws.onerror = fail; });
+				return ws;
+			}
+		} catch {
+			// Chrome is still starting.
+		}
+		await sleep(150);
+	}
+	throw new Error("headless Chrome did not expose a page target");
+}
+
+function client(ws) {
+	let nextId = 1;
+	const pending = new Map();
+	ws.onmessage = (event) => {
+		const message = JSON.parse(event.data);
+		const entry = pending.get(message.id);
+		if (!entry) return;
+		pending.delete(message.id);
+		if (message.error) entry.reject(new Error(JSON.stringify(message.error)));
+		else entry.resolve(message.result);
+	};
+	const send = (method, params = {}) => new Promise((resolveSend, reject) => {
+		const id = nextId++;
+		pending.set(id, { resolve: resolveSend, reject });
+		ws.send(JSON.stringify({ id, method, params }));
+	});
+	const evaluate = async (expression) => {
+		const result = await send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+		if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description || "evaluate failed");
+		return result.result.value;
+	};
+	const waitFor = async (label, expression, timeoutMs = 30000) => {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) {
+			if (await evaluate(`(() => { try { return Boolean(${expression}); } catch { return false; } })()`)) return;
+			await sleep(200);
+		}
+		throw new Error(`timed out waiting for ${label}`);
+	};
+	return { send, evaluate, waitFor };
+}
+
+// Runs in the page: render the framing at 2x, downscale, and encode WebP under the size cap.
+const encodeInPage = (framing) => `(async () => {
+	const studio = window.__cozyclay;
+	const framing = ${JSON.stringify(framing)};
+	const output = { width: ${WIDTH * 2}, height: ${HEIGHT * 2} };
+	const png = framing ? studio.captureFraming(framing, output) : studio.capturePlate();
+	if (!png) throw new Error("studio capture returned nothing");
+	const image = new Image();
+	image.src = png;
+	await image.decode();
+	const canvas = document.createElement("canvas");
+	canvas.width = ${WIDTH};
+	canvas.height = ${HEIGHT};
+	const ctx = canvas.getContext("2d");
+	ctx.imageSmoothingQuality = "high";
+	const scale = Math.max(canvas.width / image.width, canvas.height / image.height);
+	const w = image.width * scale, h = image.height * scale;
+	ctx.drawImage(image, (canvas.width - w) / 2, (canvas.height - h) / 2, w, h);
+	for (let quality = 0.92; quality > 0.4; quality -= 0.06) {
+		const url = canvas.toDataURL("image/webp", quality);
+		if (url.length * 0.75 <= ${MAX_BYTES} || quality <= 0.46) return url;
+	}
+})()`;
+
+async function renderOne(template, theme) {
+	const profile = mkdtempSync(join(tmpdir(), "cozyclay-thumbs-"));
+	const chrome = spawnOwned(chromePath, [
+		"--headless=new", `--remote-debugging-port=${cdpPort}`, `--user-data-dir=${profile}`,
+		"--window-size=1440,900", "--no-first-run", "--no-default-browser-check", ...gpuFlags, "about:blank",
+	], { stdio: "ignore" });
+	try {
+		const cdp = client(await connect());
+		await cdp.send("Page.enable");
+		await cdp.send("Page.addScriptToEvaluateOnNewDocument", { source: `try { localStorage.setItem(${JSON.stringify(THEME_KEY)}, ${JSON.stringify(theme)}); } catch {}` });
+		await cdp.send("Page.navigate", { url: template.url });
+		if (template.create) {
+			await cdp.waitFor("the start screen", `document.querySelector('[data-template-id="${template.id}"]')`);
+			await cdp.evaluate(`document.querySelector('[data-template-id="${template.id}"]').click()`);
+			await sleep(200);
+			await cdp.evaluate("document.querySelector('.v2-start-project-form').requestSubmit()");
+		}
+		await cdp.waitFor("the studio", "window.__cozyclay?.charA && !document.querySelector('.v2-start-screen')");
+		await sleep(3000); // character model, textures and shadows settle
+		const dataUrl = await cdp.evaluate(encodeInPage(FRAMINGS[template.id] ?? null));
+		const bytes = Buffer.from(dataUrl.split(",")[1], "base64");
+		const file = join(outDir, `${template.id}-${theme}.webp`);
+		writeFileSync(file, bytes);
+		console.log(`${file.slice(ROOT.length + 1)}  ${(bytes.length / 1024).toFixed(1)} KB`);
+	} finally {
+		await terminateOwned(chrome);
+		rmSync(profile, { recursive: true, force: true });
+	}
+}
+
+mkdirSync(outDir, { recursive: true });
+for (const template of templates) {
+	for (const theme of THEMES) await renderOne(template, theme);
+}

package/tools/run-tests.mjs

@@ -14,7 +14,7 @@ if (!process.env.COZYCLAY_AGENT_SESSIONS_DIR) {
 }
 
 const NODE_FILES = [
-	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
+	"test/motion3/verify-motion3-core.mjs", "test/motion3/verify-playback-frame-store.mjs", "test/verify-playback-render-isolation.mjs", "test/motion3/verify-motion3-idle.mjs", "test/motion3/verify-motion3-flip.mjs", "test/motion3/verify-motion3-timing.mjs", "test/motion3/verify-motion3-self.mjs", "test/motion3/verify-motion3-commands.mjs", "test/motion3/verify-motion3-exitcar.mjs", "test/motion3/verify-motion3-agentloop.mjs", "test/motion3/verify-motion3-search.mjs", "test/motion3/verify-motion3-skills.mjs", "test/motion3/verify-motion3-carried.mjs", "test/motion3/verify-motion3-people.mjs", "test/motion3/verify-motion3-hit.mjs", "test/motion3/verify-motion3-socket.mjs", "test/motion3/verify-motion3-shapes.mjs", "test/motion3/verify-motion3-grasp-fields.mjs", "test/motion3/verify-motion3-finger-contact.mjs", "test/motion3/verify-motion3-grasp-qa.mjs", "test/motion3/verify-motion3-load.mjs", "test/motion3/verify-motion3-throw.mjs", "test/motion3/verify-motion3-catch.mjs", "test/motion3/verify-motion3-grasp-hints.mjs", "test/motion3/verify-motion3-reach-human.mjs", "test/motion3/verify-motion3-stance-grasp.mjs", "test/motion3/verify-motion3-grasp-friction.mjs", "test/motion3/verify-motion3-grasp-measure.mjs", "test/motion3/verify-motion3-contracts.mjs", "test/motion3/verify-motion3-describe.mjs", "test/motion3/verify-motion3-timeline.mjs", "test/motion3/verify-motion3-probes.mjs", "test/motion3/verify-motion3-grab.mjs", "test/motion3/verify-motion3-grab-blend.mjs", "test/motion3/verify-motion3-patch.mjs", "test/motion3/verify-motion3-repair.mjs", "test/motion3/verify-motion3-specstore.mjs", "test/motion3/verify-motion3-visual.mjs", "test/motion3/verify-motion3-goals.mjs", "test/motion3/verify-motion3-prompt.mjs", "test/motion3/verify-motion3-cup.mjs", "test/verify-proxy-figure.mjs", "test/verify-text-object.mjs",
 	"test/verify-proxy-figure-bounds.mjs",
 	"test/verify-character-capabilities.mjs",
 	"test/verify-root-path.mjs",
@@ -22,13 +22,12 @@ const NODE_FILES = [
 	"test/bus/verify-view-mode-pose.mjs",
 	"test/verify-studio-actions.mjs",
 	"test/ardy/verify-collision-blockers.mjs",
-	"test/verify-facing-marks.mjs",
 	"test/verify-pose-fade.mjs",
 	"test/verify-pose-gizmo.mjs",
 	"test/ardy/verify-key-runs.mjs",
 	"test/ardy/verify-playback-clock.mjs",
 	"test/ardy/verify-timeline-coordinates.mjs",
-	"test/verify-tokens.mjs",
+	"test/verify-tokens.mjs", "test/verify-lens-scrub.mjs",
 	"test/demo/verify-api-routes.mjs",
 	"test/ik/verify-collision-capsules.mjs",
 	"test/ik/verify-ground.mjs",
@@ -44,7 +43,7 @@ const NODE_FILES = [
 	"test/ik/verify-range-pin-ui.mjs",
 	"test/ik/verify-range-pin-object-transform.mjs",
 	"test/verify-ik-camera-performance.mjs",
-	"test/verify-ik-entry-camera.mjs",
+	"test/verify-ik-entry-camera.mjs", "test/verify-viewport-visible-rect.mjs",
 	"test/process/verify-lifecycle.mjs",
 	"test/process/verify-mcp-package-isolation.mjs",
 	"test/process/verify-package-telemetry.mjs",
@@ -65,7 +64,7 @@ const NODE_FILES = [
 	"test/verify-schema-to-typebox.mjs",
 	"test/verify-agent-sse-golden.mjs",
 	"test/verify-agent-context-budget.mjs", "test/verify-agent-context-trim.mjs",
-	"test/verify-agent-supervisor.mjs",
+	"test/verify-agent-supervisor.mjs", "test/verify-studio-tasks.mjs", "test/verify-task-board.mjs",
 	"test/verify-studio-agent-protocol.mjs",
 	"test/verify-studio-agent-sampled-framing.mjs",
 	"test/verify-studio-agent-tokens.mjs",
@@ -95,17 +94,14 @@ const NODE_FILES = [
 	"test/verify-asset-shelf.mjs",
 	"test/verify-blocking-depth.mjs",
 	"test/verify-render-passes-video.mjs",
-	"test/verify-burn-in.mjs",
 	"test/verify-camera-block.mjs", "test/verify-camera-direction.mjs",
 	"test/verify-camera-follow.mjs",
 	"test/verify-camera-move.mjs",
 	"test/verify-camera-rail-schedule.mjs",
 	"test/verify-camera-pointer-lock.mjs",
-	"test/verify-camera-tutorial.mjs",
-	"test/verify-first-shot-handoff.mjs",
 	"test/verify-codex-client.mjs",
 	"test/verify-cuts.mjs",
-	"test/verify-shot-guides.mjs",
+	"test/verify-shot-guides.mjs", "test/verify-shot-frame.mjs",
 	"test/verify-error-boundary.mjs",
 	"test/verify-g006-css.mjs",
 	"test/verify-gizmo-claim.mjs",
@@ -238,9 +234,6 @@ const BROWSER_FILES = [
 	"test/verify-static-shot-export-browser.mjs",
 	"test/qa-agent-view-toggle-browser.mjs",
 	"test/qa-agent-scenarios-browser.mjs",
-	"test/qa-camera-tutorial-browser.mjs",
-	"test/qa-first-shot-handoff-browser.mjs",
-	"test/qa-tutorial-analytics-browser.mjs",
 	"test/qa-camera-pointer-lock-browser.mjs",
 	"test/qa-first-edit-browser.mjs",
 	"test/qa-ia-tail-browser.mjs",
@@ -262,7 +255,7 @@ const BROWSER_FILES = [
 // The inventory sweep only picks up `verify*.mjs`; a browser suite named for
 // the QA runner it needs is listed here so it still shows up in the manifest
 // (as an EXCLUDE with its reason) instead of going unmentioned.
-const EXTRA_INVENTORY = ["test/ik/translation-step.mjs", "test/qa-scenes-v5-migration-browser.mjs", "test/qa-agent-scenarios-browser.mjs", "test/qa-execution-outcomes-browser.mjs", "test/qa-export-recovery-browser.mjs", "test/qa-agent-view-toggle-browser.mjs", "test/qa-camera-tutorial-browser.mjs", "test/qa-first-shot-handoff-browser.mjs", "test/qa-tutorial-analytics-browser.mjs", "test/qa-camera-pointer-lock-browser.mjs", "test/qa-first-edit-browser.mjs", "test/qa-ia-tail-browser.mjs", "test/qa-keyframe-pack-browser.mjs", "test/qa-preview-browser.mjs", "test/qa-reference-slots-browser.mjs", "test/qa-scene-playback-browser.mjs", "test/qa-scene-switcher-browser.mjs", "test/qa-send-to-ai-browser.mjs", "test/qa-view-menu-browser.mjs", "test/qa-live-reconnect-browser.mjs", "test/qa-clipboard-paste-browser.mjs", "test/qa-rail-lean-browser.mjs", "test/qa-rail-reach-browser.mjs", "test/qa-rail-ring-browser.mjs", "test/qa-speed-graph-browser.mjs"];
+const EXTRA_INVENTORY = ["test/ik/translation-step.mjs", "test/qa-scenes-v5-migration-browser.mjs", "test/qa-agent-scenarios-browser.mjs", "test/qa-execution-outcomes-browser.mjs", "test/qa-export-recovery-browser.mjs", "test/qa-agent-view-toggle-browser.mjs", "test/qa-camera-pointer-lock-browser.mjs", "test/qa-first-edit-browser.mjs", "test/qa-ia-tail-browser.mjs", "test/qa-keyframe-pack-browser.mjs", "test/qa-preview-browser.mjs", "test/qa-reference-slots-browser.mjs", "test/qa-scene-playback-browser.mjs", "test/qa-scene-switcher-browser.mjs", "test/qa-send-to-ai-browser.mjs", "test/qa-view-menu-browser.mjs", "test/qa-live-reconnect-browser.mjs", "test/qa-clipboard-paste-browser.mjs", "test/qa-rail-lean-browser.mjs", "test/qa-rail-reach-browser.mjs", "test/qa-rail-ring-browser.mjs", "test/qa-speed-graph-browser.mjs"];
 
 EXTRA_INVENTORY.push("test/qa-proxy-figure-browser.mjs");
 EXTRA_INVENTORY.push("test/qa-proxy-entry-browser.mjs");
@@ -275,7 +268,7 @@ function verificationFiles(directory) {
 		.flatMap((entry) => {
 			const path = join(directory, entry.name);
 			if (entry.isDirectory()) return entry.name === "node_modules" ? [] : verificationFiles(path);
-			return entry.isFile() && /^verify(-.*)?\.mjs$/.test(entry.name) ? [relative(".", path)] : [];
+			return entry.isFile() && /^verify(-.*)?\.mjs$/.test(entry.name) ? [relative(".", path).replaceAll("\\", "/")] : [];
 		})
 		.sort();
 }

package/tools/sitemap.mjs

@@ -8,7 +8,7 @@ import { resolve } from "node:path";
 
 const ORIGIN = "https://cozyclay.org";
 const PAGES = [
-	{ path: "/", sources: ["index.html", "public/media", "public/scenes"] },
+	{ path: "/", sources: ["index.html", "public/media"] },
 	{ path: "/greybox-to-video/", sources: ["greybox-to-video/index.html"] },
 	{ path: "/previs-software/", sources: ["previs-software/index.html"] },
 	{ path: "/seedance-camera-control/", sources: ["seedance-camera-control/index.html"] },