cozyclay 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,172 @@
 # 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
+be distinguished from real launches and returning use.
+
+- `npx cozyclay`, `bunx cozyclay`, and global `cclay` launches get a
+  signed-package-verified anonymous installation ID.
+- The existing scene, edit, motion, export, and activation funnel is available
+  for npm sessions with `distribution: npm` and `app_version` properties.
+- Source checkouts, forks, CI, tests, malformed or unsigned packages, and
+  opted-out launches remain untracked.
+- `cclay telemetry status|on|off` controls the package-wide setting; the
+  in-app toggle stays synchronized with it.
+- URL/referrer/campaign-derived values are scrubbed before any event leaves the
+  browser, and corrupted telemetry state fails closed.
+
 ## 1.5.0
 
 The release where the camera can climb a shaped path, recordings leave the studio as

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
+- 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:
 
-<details>
-<summary><b>Token-free ARDY text encoder</b> — skip the Hugging Face gate</summary>
+| 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` |
+
+**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
@@ -179,8 +218,54 @@ Found something broken, or want a feature? [Open an issue](https://github.com/No
 
 All runtime libraries intentionally live in `devDependencies` because the published npm package ships the prebuilt `dist/`, so `npx cozyclay` must not install the studio's dependency tree.
 
+## Analytics & privacy
+
+The hosted site at [cozyclay.org](https://cozyclay.org/) collects anonymous usage analytics via [PostHog](https://posthog.com/) (US Cloud). There are no cookies and no session recording, and Do-Not-Track is respected. A random pseudonymous identifier is kept in your browser's localStorage so that returning visits and retention can be counted; it is never linked to an account or project content and is removed by clearing site data or using the opt-out toggle.
+
+Events collected:
+
+| Event | Purpose |
+| --- | --- |
+| `install:first_launch` | First run of the official npm package |
+| `app:session_started` | Start of an official npm package session |
+| `$pageview` | Funnel and drop-off analysis |
+| `scene:created` | Funnel and drop-off analysis |
+| `scene:loaded` | Funnel and drop-off analysis |
+| `craft:first_action` | Funnel and drop-off analysis |
+| `motion:job_started` | Motion reliability |
+| `motion:job_succeeded` | Motion reliability |
+| `motion:job_failed` | Motion reliability |
+| `export:blocking_frame_succeeded` | Funnel and drop-off analysis |
+| `activation:completed` | Funnel and drop-off analysis |
+
+Geo data comes from ingest-time GeoIP country lookup only — no precise location is collected. Prompt text, asset names, file names, project content, local paths, and any user-entered text are never collected.
+
+The official npm package also measures anonymous first launches, sessions, and
+the same in-app funnel on its `127.0.0.1` studio. It stores one random
+installation identifier in `~/.config/cozyclay/state.json` so returning use can
+be counted across ports and browser storage resets. Source checkouts, forks,
+development servers, CI, and tests do not send analytics. Official npm
+artifacts carry a signature checked by the launcher, so copying or repackaging
+the source does not enable telemetry.
+
+The npm package prints this disclosure once on first launch. Control it at any
+time:
+
+```bash
+cclay telemetry status
+cclay telemetry off
+cclay telemetry on
+```
+
+`COZYCLAY_TELEMETRY=0` and `DO_NOT_TRACK=1` disable collection for a launch.
+The in-app topbar toggle changes the same npm-package setting and removes its
+anonymous installation identifier. Hosted-site visitors can opt out with that
+toggle, browser Do-Not-Track, or a content blocker.
+
+PostHog's free plan retains events for 1 year.
+
 ## License & credits
 
 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/THIRD_PARTY_NOTICES.md

@@ -101,6 +101,14 @@ as third-party content that this licence does not cover.
 - `x-bot-tpose.fbx`, `y-bot-tpose.fbx` — Adobe Mixamo
 - Terms: https://www.adobe.com/legal/terms.html
 
+## posthog-js
+
+The hosted site at cozyclay.org uses [posthog-js](https://posthog.com/docs/libraries/js) for anonymous usage analytics.
+
+- Copyright PostHog Inc.
+- License: Apache-2.0 AND MIT
+- Source: https://github.com/PostHog/posthog-js
+
 ## CozyClay license scope
 
 The CozyClay combined work in this repository is distributed under AGPL-3.0-or-later, subject to the transition details in `LICENSING.md`. That license does not replace or relicense Three.js, ARDY, ARDY model checkpoints, the bundled fonts, the character rigs, or any other third-party component.