cozyclay 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,156 @@
 # Changelog
 
+## 1.7.0
+
+Kimodo becomes the default motion-generation backend, and a full edit-and-refine
+loop lands on top of it: draw over a trail to reshape it, keep most of a take
+and regenerate only a window, and step back through 20 checkpoints of a
+take's history. Multi-character rigs, prop motion, and camera work all get
+real editing surfaces, and three failure modes that used to blank the whole
+studio now degrade with a way back instead.
+
+### Kimodo motion backend, now default
+
+- Kimodo, introduced behind `CCLAY_MOTION_BACKEND=kimodo`, is now the default
+  motion-generation backend.
+- Root 2D path constraints, pose pinning (via Kimodo's fullbody constraints),
+  and motion-edit-by-regeneration (IK-adjust a span, then regenerate) now all
+  work on Kimodo — base clips still refuse, since Kimodo has no autoregressive
+  history input for them.
+- The prompt-block cap is raised from 4s to 5s after measuring seam quality
+  across block lengths — 5s scored best short of a single seamless take, while
+  8s blocks collapsed and sub-2s blocks lost a third of their frames to the
+  transition window.
+
+### Draw to edit a take (line editing)
+
+- A new line-edit mode: drag a joint's motion trail to reshape it, or draw a
+  fresh stroke across empty space when the trail doesn't reach where you want.
+  Stroke endpoints snap to the take's own nearby frames so edits land where
+  you meant, and a smoothstep seam keeps the join from popping.
+- Pin exact moments in 3D: scrub the playhead, drag a joint into place, and
+  pin up to 8 moments across a take.
+- Runs on a new ProjFlow-based backend on the Kimodo box; edits are
+  seed-deterministic, so a release-quality regenerate reproduces the preview
+  bit for bit.
+- Ctrl/Cmd+Z undoes the last pull; releasing a drag previews at reduced
+  quality first (~1s), then a full-quality generate confirms with the same
+  seed.
+
+### Keep most of a take (preserve mode)
+
+- A preserve slider and grouped per-limb masks let you regenerate only part of
+  a take — free one limb, or a masked region — instead of the whole clip.
+- Effector constraints keep specific joints anchored through a regeneration.
+
+### Take recipes and version history
+
+- Every generate or edit now records its own recipe (seed, prompt blocks, and
+  edits in order), and extending a take re-sends its edits so refining before
+  extending no longer throws work away.
+- A version strip above the timeline checkpoints every generate/edit up to 20
+  deep — click any entry to restore that take and its recipe.
+- The edit surface collapses to two modes: 장면 (Kimodo blocking — new, again,
+  add-block) and 다듬기 (line-edit refinement, one click from a loaded take).
+
+### Multi-character rigs and IK
+
+- Every cast member now gets its own namespaced rig subtree in the Hierarchy
+  panel, not just the first — bones, IK badges, and focus all follow the
+  active character correctly (#76, #77, #78).
+- IK corrections on an inactive character now survive a focus switch instead
+  of silently reverting to the uncorrected take (#77).
+- Timeline pins (IK correction keys, prompt-clip ranges) migrate through
+  segment retimes instead of firing on the wrong frame after a slow-mo (#79).
+- Body Contact: dragging a character down during IK editing now stops the
+  pelvis at the floor and holds any planted foot or reaching hand there,
+  measured per character from the actual skinned mesh — no more clay figures
+  hovering above the ground.
+- Motion trails now render per body part in IK handle colors, with trail
+  editing and IK editing split into separate tools instead of one ambiguous
+  shared gizmo.
+- A One-Euro filter now smooths SAM-extracted wrist tremor by speed —
+  quieting rest-state jitter while leaving fast strikes untouched (#84).
+
+### Prop motion: travel paths and speed
+
+- Scene objects (props) can now be given a travel path, authored the same way
+  as a camera rail: draw it in Top-View, refine it in the 3D scene, with a
+  mid-route point insertable by double-click.
+- A speed graph — shared by props and the camera dolly — lets you drag a
+  stretch of the timeline faster or slower; the area under the curve is the
+  distance, so the rest of the segment compensates automatically, and a cut
+  pins the take at an exact time/distance point.
+- Drag a prop onto a character or a specific rig bone in the Hierarchy to
+  attach it — it now rides that character's motion (a carried bat stays in a
+  walking character's hand instead of staying world-anchored).
+
+### Viewport and lighting
+
+- Auto Color mode: a topbar toggle stamps a stable, automatically derived
+  color onto every set object, the way Blender's random viewport shading
+  colors objects — display-only, so authored colors, saved projects, undo
+  history, and the MCP scene view are untouched.
+- A new Grid view swaps the clay stage for a dark, Blender-style reference
+  grid for blocking work — overlay-only, so exports and the plan board never
+  see it.
+- The key light is now a grabbable sun: move it like any other object, and
+  dial its warmth between cool daylight and warm sunset amber.
+- Blender-style composition guides (thirds, golden ratio, center+diagonals,
+  safe areas) on the shot preview, and exported frames can burn in a slate +
+  zero-padded frame counter.
+
+### Camera
+
+- Crane marks get a 3-axis gizmo; a rail now always carries a crane profile,
+  and the old on/off toggle is gone (a flat profile at the follow height reads
+  as "off").
+
+### Project workflow
+
+- A startup chooser and local project session replace the always-on implicit
+  scene.
+- New workflow-focused camera motion modes, plus several passes cleaning up
+  timeline control grouping, control visibility, and removing legacy
+  console/generation panels.
+
+### AI control (MCP)
+
+- `describe_scene` now reports the key light and the shot list; `update_object`
+  can set a prop's travel path; `load_motion` can target a specific character
+  by letter/slot/id and re-install an assembled take without a full
+  regeneration.
+- Editors now identify themselves (project, scene, cast size) in
+  `live_status`, so multi-tab routing no longer depends on an opaque UUID.
+
+### Hosted demo v1
+
+- cozyclay.org's install-free demo got a real backend: a Cloudflare Worker
+  queue (Google OAuth + Turnstile, single-FIFO D1 queue, private R2 result
+  proxy) and an outbound-polling GPU box worker with zero inbound sockets.
+
+### Reliability
+
+- Three failure modes that used to blank the whole studio now degrade
+  instead: a render error anywhere in the app shows a message with a
+  reload-and-resume, a lost WebGL context (sleep/wake, driver restart) shows
+  an overlay and repaints on restore, and layout-save writes are guarded like
+  every other write in the app (#64).
+- A selected object's own gizmo cage no longer blocks clicks meant for a
+  different object (#81).
+- Recording no longer exports frozen tail frames after a cast member or
+  motion segment shrinks (#80).
+
+### Also in this release
+
+- Onboarding: a hosted-demo visitor now gets a "watch the sample" path instead
+  of landing on an empty stage, and three funnel-measurement gaps (startup
+  scene creation, video export, cutout import) are closed.
+- The studio's PWA update banner finally has a listener, so a waiting version
+  reloads on request instead of running stale indefinitely.
+- Objects can now be parented from the Inspector's own Parent picker, not
+  only through MCP.
+
 ## 1.6.0
 
 The official npm package now records anonymous product usage so downloads can

package/README.md

@@ -13,7 +13,7 @@
 <p align="center">
   <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
   <a href="https://www.npmjs.com/package/cozyclay"><img alt="npm" src="https://img.shields.io/npm/v/cozyclay"></a>
-  <img alt="Node 22+" src="https://img.shields.io/badge/node-22%2B-brightgreen">
+  <img alt="Node 22.13+" src="https://img.shields.io/badge/node-22.13%2B-brightgreen">
   <a href="https://github.com/NomaDamas/CozyClay/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/NomaDamas/CozyClay?style=flat"></a>
 </p>
 
@@ -34,7 +34,7 @@ CozyClay is a browser-based 3D staging studio built with Three.js and React Thre
 npx cozyclay
 ```
 
-That is the whole install. **[cozyclay.org](https://cozyclay.org/)** has the demo reel and a walkthrough of what the studio does; to use it, run it on your own machine. It ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating *new* motion needs a local ARDY machine, so that part stays off until you point it at one.
+That is the whole install. **[cozyclay.org](https://cozyclay.org/)** has the demo reel and a walkthrough of what the studio does; to use it, run it on your own machine. It ships seeded with a pre-generated motion clip, so you can scrub the timeline, drive the cameras and draw a dolly rail straight away — generating *new* motion is optional and uses the Kimodo bridge when configured.
 
 ## Demo
 
@@ -44,18 +44,18 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 
 |  | |
 | --- | --- |
-| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with a W/E/R gizmo. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths. |
+| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with a W/E/R gizmo. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye plan view drives 2D root waypoints for character paths. The topbar's Auto Color toggle gives every object its own stable display color — Blender's random viewport color, so twenty grey blockout boxes stay tellable apart — without touching the colors you authored (captures include the display colors while it is on). |
 | **Fly the camera** | Right-drag flies (WASD walks, Q/E cranes), middle-drag pans, Alt+drag orbits the selection, click selects, `F` frames — the muscle memory you already have from a 3D editor. |
 | **Undo anything** | Every scene mutation goes through one history store: a drag, a scrub, an inspector edit is exactly one undo entry. `Esc` cancels an in-flight drag and restores the pre-drag transform. |
-| **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to ARDY, then play the result back with sparse IK correction where the generated motion needs fixing. |
+| **Generate motion** | Pose characters and export poses, sequence multi-phase motion as Prompt Blocks on a resizable timeline, send them to Kimodo, then play the result back with sparse IK correction where the generated motion needs fixing. |
 | **Direct it with an AI** | Connect Claude — or any MCP client — and ask for a shot in plain language. It places the cast, frames “a low wide profile”, generates multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control-mcp). |
 
 ## Requirements
 
-- Node.js 22 or newer
+- Node.js 22.13 or newer
 - npm, or bun
 - A Chromium-based browser
-- *Optional:* an SSH-accessible NVIDIA machine running ARDY, for motion generation — first-time setup downloads a ~16.4 GB text-encoder stack onto that machine; see [`tools/ardy/README.md`](tools/ardy/README.md)
+- An SSH-accessible NVIDIA machine running Kimodo, for motion generation — run `npm run kimodo:setup` once; the first setup downloads the Kimodo checkpoint and text-encoder stack.
 
 ## Quick start
 
@@ -65,17 +65,21 @@ npx cozyclay
 bunx cozyclay
 ```
 
-That downloads the built studio and opens it at `http://127.0.0.1:5180`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-ardy`.
+That downloads the built studio and opens it at `http://127.0.0.1:5180/app/`. Nothing to compile, no dependency tree to install. Useful flags: `--port 5200`, `--no-open`, `--no-motion`.
 
 A global install gives you `cclay`, the same command with less typing. Once a day the launcher checks npm for a newer release and prints a one-line notice after the studio is up; it stays quiet when you're current or offline. `cclay update` installs the latest release, and `--no-update-check` skips the check entirely.
 
-Motion generation stays off until you point it at a machine that can run it:
+Motion generation uses Kimodo by default once you point it at an SSH-accessible NVIDIA machine:
 
 ```bash
-CCLAY_ARDY_HOST=user@your-gpu-box npx cozyclay
+CCLAY_KIMODO_HOST=user@your-gpu-box npx cozyclay
 ```
 
-Everything else — staging through camera work and playback — runs without it.
+Install the remote worker once:
+
+```bash
+CCLAY_KIMODO_HOST=user@your-gpu-box npm run kimodo:setup
+```
 
 ## AI control (MCP)
 
@@ -116,20 +120,53 @@ npm install
 npm run dev
 ```
 
-Open `http://127.0.0.1:5180`. `npm run dev` starts the studio together with its local ARDY bridge; `npm run dev:ui` starts the browser UI alone, without Block Generation. The bridge listens on loopback only; the environment variables that point it at a remote ARDY machine are documented in [`tools/ardy/BRIDGE.md`](tools/ardy/BRIDGE.md).
+Open `http://127.0.0.1:5180/app/`. `npm run dev` starts the studio together with its local Kimodo bridge once `CCLAY_KIMODO_HOST` points at a GPU box; without that variable it starts the studio alone and says so, and Block Generation stays unavailable until you set it. `npm run dev:ui` starts the browser UI alone in every case. The bridge listens on loopback only; Kimodo host variables are documented in [`tools/kimodo/setup-on-box.sh`](tools/kimodo/setup-on-box.sh).
+
+## Hosted demo
+
+Installing a GPU motion backend is the hard part, so `cozyclay.org` also runs a queued demo: a visitor writes one prompt, gets a ticket link, and a GPU box owned by the maintainer generates the motion and uploads it. The visitor never installs anything and never leaves the site — the result opens in the studio itself.
+
+The pieces live in this repository, under `AGPL-3.0-or-later` like everything else:
+
+| Path | Role |
+| --- | --- |
+| `demo/`, `d/` | Static composer and ticket/result pages, built into `dist/` by the same `npm run build` |
+| `workers/api/` | Cloudflare Worker queue API (D1 for state, R2 for results), with its own pinned toolchain |
+| `tools/demo-worker/` | The GPU-box poller. Outbound fetch only — it never opens a listening socket |
+
+**Queue policy.** Jobs run in a single FIFO queue. All of these values live in `workers/api/src/policy.js`; nothing else carries a copy.
+
+| Rule | Value |
+| --- | --- |
+| Active jobs per account | 1 |
+| Daily cap | 2 per account |
+| Global waiting cap | 200, then submissions are refused |
+| Lease / heartbeat / hard timeout | 15 min lease, renewed every 60 s, 20 min hard stop |
+| Attempts | 2 (one automatic retry); a failed job refunds the daily cap |
+| Result retention | 30 days, then the R2 object is deleted |
+| Prompt limit | shared with the studio via `tools/ardy/prompt-limits.mjs` |
 
-<details>
-<summary><b>Token-free ARDY text encoder</b> — skip the Hugging Face gate</summary>
+**Secrets.** Never committed. Configure each with `wrangler secret put` against `workers/api/wrangler.toml`:
+`GOOGLE_CLIENT_SECRET`, `CC_WORKER_SECRET`, `SESSION_SIGNING_KEY`, `TURNSTILE_SECRET_KEY`. The non-secret `GOOGLE_CLIENT_ID` and `TURNSTILE_SITE_KEY` vars in `wrangler.toml` must also be replaced before a real deployment.
 
-ARDY's text encoder normally requires a Hugging Face account, gated-model approval, and an access token on the ARDY machine. CozyClay ships a token-free alternative — one command provisions the same encoder stack from public repositories, pinned by commit and SHA-256:
+**Running the API locally.**
 
 ```bash
-CCLAY_ARDY_HOST=user@your-gpu-box tools/ardy/setup-text-encoder-on-box.sh
+npm run demo:api:install   # npm --prefix workers/api ci
+npm --prefix workers/api exec -- wrangler d1 migrations apply cozyclay-demo --local
+npm run demo:api           # wrangler dev on 127.0.0.1:8787
 ```
 
-See [`tools/ardy/README.md`](tools/ardy/README.md) for details. This workflow is built with Meta Llama 3; the encoder's base weights are licensed under the Meta Llama 3 Community License.
+**Running the GPU-box worker.** The hosted queue worker has its own isolated runtime and reaches the API outbound only. It is independent from the local Studio's Kimodo backend.
+
+```bash
+CC_DEMO_API_BASE=https://api.cozyclay.org \
+CC_WORKER_ID=box1 \
+CC_WORKER_SECRET=... \
+  npm run demo:worker
+```
 
-</details>
+See [`workers/api/README.md`](workers/api/README.md) for the deployment, migration and rollback runbook, and [`tools/demo-worker/README.md`](tools/demo-worker/README.md) for service units, environment-file permissions and the listening-socket check.
 
 ## Controls
 
@@ -138,16 +175,18 @@ See [`tools/ardy/README.md`](tools/ardy/README.md) for details. This workflow is
 | Right-drag | Look around (fly) |
 | RMB + WASD | Walk while flying |
 | RMB + Q/E | Crane down / up |
+| RMB + Shift | Boost fly speed 2.6× |
 | Middle-drag | Pan |
 | Alt + drag | Orbit the selection |
-| Scroll | Dolly |
+| Scroll | Dolly; while flying, sets the fly speed instead |
 | Click | Select; empty space clears |
 | W / E / R | Move / rotate / scale tool |
-| Ctrl (during drag) | Invert grid snapping |
+| Ctrl/Cmd (during drag) | Invert grid snapping |
 | Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z | Undo / redo |
 | Esc | Cancel the in-flight drag |
 | End | Drop the selection to the surface |
 | Ctrl/Cmd+D | Duplicate the selection |
+| Delete / Backspace | Delete the selection |
 | F | Frame the selection |
 
 ## Validate
@@ -160,15 +199,15 @@ See [`tools/ardy/README.md`](tools/ardy/README.md) for details. This workflow is
 | `npm run test:objects` | Gizmo interaction in a real browser — needs `npm run dev:ui` in another shell |
 | `npm run test:theme` / `test:appearance` / `test:layout` | UI theme, appearance, layout |
 | `npm run test:lifecycle` | Dev-server process lifecycle |
-| `npm run test:ardy` | ARDY conversion, playback, and IK pipeline |
+| `npm run test:ardy` | Motion conversion, playback, and IK pipeline |
 | `cd mcp && npm install && npm run verify` | MCP server over real stdio — all 420 framing combinations |
 | `cd mcp && npm run verify:live` | Live-control protocol against a fake editor (same `npm install` first) |
 | `npm run build` | Production build |
 
-Ad-hoc browser QA, while a dev server is available:
+Ad-hoc browser QA, while a dev server is available (the browser opens the studio at `/app/`):
 
 ```bash
-npm run qa:browser -- <qa-script>
+npm run qa:browser -- node <qa-script>
 ```
 
 ## Contributing
@@ -229,4 +268,4 @@ PostHog's free plan retains events for 1 year.
 
 GNU Affero General Public License v3.0 or later — see [`LICENSE`](LICENSE) and the transition details in [`LICENSING.md`](LICENSING.md). Modified network services must offer their users the corresponding source. Third-party projects retain their own licenses and copyright; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
 
-CozyClay can connect to [NVIDIA ARDY](https://github.com/nv-tlabs/ardy) for motion generation. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA.
+The hosted demo worker may use an externally installed [NVIDIA ARDY](https://github.com/nv-tlabs/ardy) runtime. ARDY is a separate third-party project owned and maintained by NVIDIA; it is not included in this repository, and CozyClay is not affiliated with or endorsed by NVIDIA. The local Studio uses Kimodo instead.

package/bin/cozyclay.mjs

@@ -3,12 +3,12 @@
  * cozyclay - run the studio from a published package.
  *
  * `npx cozyclay` / `bunx cozyclay` should behave like `npm run dev` does in a
- * clone: the studio in a browser, with the optional ARDY sidecar wired up.
+ * clone: the studio in a browser, with the optional motion sidecar wired up.
  * The difference is that nothing is built here. The package ships the built
  * `dist/`, so this launcher only has to
  *
  *   - serve those files over loopback,
- *   - forward /ardy to its dynamically selected sidecar port (the job Vite's dev proxy does),
+ *   - forward /ardy to its dynamically selected sidecar port (the same job Vite's dev proxy does),
  *   - keep the sidecar's lifetime tied to this process.
  *
  * It has no dependencies on purpose. A launcher that needs an install step
@@ -50,7 +50,12 @@ const OFFICIAL_PACKAGE = (
 	&& !existsSync(join(PKG_ROOT, ".git"))
 	&& verifyPackageMarker(join(DIST, "cozyclay-package.json"), PKG_ROOT, packageMetadata)
 );
-let bridgePort = 5181;
+// A bridge is optional. Keep the endpoint unset until this launcher owns a
+// sidecar; otherwise /ardy requests could accidentally reach an unrelated
+// process that happens to be listening on the bridge's historical default
+// port (5181).
+let bridge = null;
+let bridgePort = null;
 
 const TYPES = {
 	".html": "text/html; charset=utf-8",
@@ -70,14 +75,14 @@ const TYPES = {
 };
 
 function parseArgs(argv) {
-	const opts = { port: 5180, host: "127.0.0.1", ardy: true, open: true, star: true, updateCheck: true };
+	const opts = { port: 5180, host: "127.0.0.1", motion: true, open: true, star: true, updateCheck: true };
 	for (let i = 0; i < argv.length; i += 1) {
 		const arg = argv[i];
 		if (arg === "--port" || arg === "-p") opts.port = Number(argv[++i]);
 		else if (arg.startsWith("--port=")) opts.port = Number(arg.slice(7));
 		else if (arg === "--host") opts.host = String(argv[++i]);
 		else if (arg.startsWith("--host=")) opts.host = arg.slice(7);
-		else if (arg === "--no-ardy") opts.ardy = false;
+		else if (arg === "--no-motion") opts.motion = false;
 		else if (arg === "--no-open") opts.open = false;
 		else if (arg === "--no-star") opts.star = false;
 		else if (arg === "--no-update-check") opts.updateCheck = false;
@@ -115,7 +120,7 @@ const HELP = `cozyclay - browser-based 3D staging studio
   npx cozyclay mcp          run the MCP server (for Claude, Cursor, any MCP client)
   cclay update              install the latest cozyclay globally (npm install -g)
   npx cozyclay --port 5200  serve on another port
-  npx cozyclay --no-ardy    skip the optional motion-generation sidecar
+  npx cozyclay --no-motion  skip the optional motion-generation sidecar
   npx cozyclay --no-open    do not open a browser
   npx cozyclay --no-star    never ask about starring the repo
   npx cozyclay --no-update-check
@@ -126,8 +131,8 @@ const HELP = `cozyclay - browser-based 3D staging studio
 
 cclay is the same command, shorter: a global install gives you both.
 
-Motion generation needs an SSH-reachable NVIDIA machine running ARDY; point
-the sidecar at it with CCLAY_ARDY_HOST. Everything else - staging, posing,
+Motion generation needs an SSH-reachable NVIDIA machine running Kimodo; point
+the sidecar at it with CCLAY_KIMODO_HOST. Everything else - staging, posing,
 paths, cameras, timeline, playback - runs locally with no extra setup.`;
 
 function serveFile(res, path) {
@@ -145,6 +150,12 @@ function serveFile(res, path) {
 // Forward /ardy to the sidecar. Same contract as the Vite dev proxy, so the
 // browser code needs no build-time knowledge of how it was launched.
 function proxyToBridge(req, res) {
+	if (!bridge || bridgePort === null || bridge.exitCode !== null || bridge.signalCode !== null) {
+		req.resume();
+		res.writeHead(503, { "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify({ error: "motion sidecar is not running" }));
+		return;
+	}
 	const upstream = httpRequest(
 		{ host: "127.0.0.1", port: bridgePort, path: req.url, method: req.method, headers: req.headers },
 		(upstreamRes) => {
@@ -156,7 +167,7 @@ function proxyToBridge(req, res) {
 		// An absent sidecar is an expected state, not a crash: the app treats a
 		// failed probe as "generation unavailable" and carries on.
 		res.writeHead(503, { "content-type": "application/json" });
-		res.end(JSON.stringify({ error: "ardy sidecar is not running" }));
+		res.end(JSON.stringify({ error: "motion sidecar is not running" }));
 	});
 	req.pipe(upstream);
 }
@@ -260,9 +271,9 @@ if (argv[0] === "mcp") {
 } else {
 
 const opts = parseArgs(argv);
-	if (opts.help) {
-		console.log(HELP);
-		process.exit(opts.invalid ? 1 : 0);
+if (opts.help) {
+	console.log(HELP);
+	process.exit(opts.invalid ? 1 : 0);
 }
 const version = readVersion();
 if (opts.version) {
@@ -295,9 +306,8 @@ if (!existsSync(join(DIST, "app", "index.html"))) {
 
 // The sidecar exits immediately without a box to talk to, so starting it
 // unconditionally would greet a first-time `npx cozyclay` with an error it
-// cannot act on. An unset CCLAY_ARDY_HOST is the normal case, not a fault.
-const ardyHost = process.env.CCLAY_ARDY_HOST?.trim();
-let bridge = null;
+// cannot act on. An unset CCLAY_KIMODO_HOST is the normal case, not a fault.
+const kimodoHost = process.env.CCLAY_KIMODO_HOST?.trim();
 let server = null;
 const startedAt = Date.now();
 let shuttingDown = false;
@@ -316,7 +326,7 @@ async function shutdown(exitCode = 0) {
 process.on("SIGINT", () => shutdown(130));
 process.on("SIGTERM", () => shutdown(143));
 
-if (opts.ardy && ardyHost && existsSync(BRIDGE)) {
+if (opts.motion && kimodoHost && existsSync(BRIDGE)) {
 	try {
 		({ child: bridge, port: bridgePort } = await startBridge({
 			command: process.execPath,
@@ -342,7 +352,7 @@ if (opts.ardy && ardyHost && existsSync(BRIDGE)) {
 		}));
 	} catch (err) {
 		console.error(`cozyclay: motion generation sidecar failed: ${err.message}`);
-		console.error("cozyclay: studio did not start; set COZYCLAY_BRIDGE_PORT to an available port or use --no-ardy.");
+		console.error("cozyclay: studio did not start; set COZYCLAY_BRIDGE_PORT to an available port or use --no-motion.");
 		if (bridge) await terminateOwned(bridge);
 		process.exit(1);
 	}
@@ -432,7 +442,10 @@ server = createServer((req, res) => {
 		if (runtime.firstLaunch) {
 			markTelemetryFirstLaunch(STATE_FILE);
 		}
-		const script = `<script>window.__COZYCLAY_RUNTIME__ = ${JSON.stringify(runtime).replaceAll("<", "\\u003c")};</script>`;
+		// __COZYCLAY_LIVE__ opts the production build into the loopback live
+		// socket (src/App.jsx gates on DEV || this flag); without it an
+		// npx-served studio can never attach to the MCP server's live hub.
+		const script = `<script>window.__COZYCLAY_RUNTIME__ = ${JSON.stringify(runtime).replaceAll("<", "\\u003c")}; window.__COZYCLAY_LIVE__ = true;</script>`;
 		const html = readFileSync(target, "utf8").replace("</head>", `${script}\n</head>`);
 		res.writeHead(200, {
 			"content-type": "text/html; charset=utf-8",
@@ -461,12 +474,12 @@ server.listen({ port: opts.port, host: "127.0.0.1", ipv6Only: false }, () => {
 	const url = `http://127.0.0.1:${opts.port}/app/`;
 	console.log(`CozyClay is running at ${url}`);
 	console.log("Use a Chromium-based browser — Safari and Firefox are not supported.");
-	if (!opts.ardy) console.log("Motion generation: off (--no-ardy).");
-	else if (bridge) console.log(`Motion generation: sidecar running against ${ardyHost}.`);
+	if (!opts.motion) console.log("Motion generation: off (--no-motion).");
+	else if (bridge) console.log(`Motion generation: sidecar running against ${kimodoHost}.`);
 	else
 		console.log(
-			"Motion generation: off. It runs on an SSH-reachable NVIDIA machine with ARDY;\n" +
-				"set CCLAY_ARDY_HOST=user@host to turn it on. Everything else works without it.",
+			"Motion generation: off. It runs on an SSH-reachable NVIDIA machine with Kimodo;\n" +
+				"set CCLAY_KIMODO_HOST=user@host to turn it on. Everything else works without it.",
 		);
 	if (opts.open) openBrowser(url);
 	void updatePending?.then((latest) => {

package/dist/app/index.html

@@ -34,8 +34,9 @@
     <title>CozyClay Studio — 3D staging and previs in your browser</title>
 
     <script defer src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token": "6a4384d1375d4ffc8a30a6346a8ad1a0"}'></script>
-    <script type="module" crossorigin src="/assets/app-G55dPEDB.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/app-CqOk49Bk.css">
+    <script type="module" crossorigin src="/assets/app-BdCI2Bys.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-P2Xu9kJm.js">
+    <link rel="stylesheet" crossorigin href="/assets/app-CrB3UF4K.css">
   </head>
   <body>
     <div id="root">