cozyclay 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## Unreleased
+
+## 2.1.0 - 2026-10-12
+
+Storyboard and Animation modes. A project is now either a storyboard (a row of
+still panels) or an animation (moving shots); both are on in a normal launch.
+
+Modes
+
+- The start screen has a Storyboard / Animation control, the project keeps its
+  mode through save and reopen, and the top bar shows it as a badge. A
+  storyboard project hides the Generate group and Motion mode (`4`); motion
+  commands are refused with a reason instead of failing quietly. (#649, #650)
+- The bottom dock has a **Board** tab in storyboard projects: one card per
+  panel with a greybox thumbnail, caption, hold, duplicate, delete and
+  drag-to-reorder. Each panel can keep its own cast placement. (#640, #641)
+- **Stylize** turns a panel into a finished picture through the image route
+  and keeps it in the project beside the greybox; **Send to Workflow** puts
+  the stylized image or the greybox on a Workflow canvas with a connected
+  Video node. (#643, #645)
+
+Capsule figures
+
+- A rigless **Capsule figure** joins the Assets tile list for blocking: stand,
+  sit or lie, set in Details. It follows root paths in the viewport and in
+  exports. Rig-only tools (Pose, IK, motion, take import, physics) refuse it
+  and say why. (#634, #635)
+
+Storyboard exports
+
+- The Export menu of a storyboard lists **Contact sheet (PNG)**, **Panel pack
+  (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and
+  **Depth + normal (PNG)**. File ▸ **Export as Animation project…** turns the
+  panels into an Animation project. Keyframe pack and shot video stay
+  Animation-only.
+
+Agent and MCP
+
+- In a storyboard project the Studio Agent adds one panel per request, frames
+  it and never generates motion; the Studio context and `describe_scene` now
+  report the project mode and each character's kind. (#637, #642)
+- MCP motion tools answer `NOT_IN_MODE` in a storyboard and
+  `TARGET_NOT_READY` on a capsule figure; `add_character` takes a model and
+  posture. (#652)
+
+Analytics and docs
+
+- Three counts-only events: `storyboard:panel_created` (`source`),
+  `storyboard:panel_stylized` (`outcome`) and `cast:proxy_added`
+  (`surface`); `scene:created` carries `previs_mode`, and the export
+  `export_kind` vocabulary gains `contact_sheet`, `panel_pack`, `animatic`
+  and `animation_project`. Captions, names and prompts are never properties.
+  Disclosed in `docs/privacy.md` and `docs/analytics-queries.md`. (#653)
+- README has a **Modes** section; the Agent rules, the Studio IA and the
+  capsule-figure notes are updated. (#653)
+
+## 2.0.2
+
+The first-run audit release: `npx cozyclay` is exercised end to end as a new
+user, and the things that broke on that path are fixed. 2.0.1 (the camera
+tutorial refresh and light-mode default, #586) was tagged but never reached
+npm; this release carries it.
+
+Agent and package
+
+- The Studio Agent panel in the npm package answered every turn with
+  "502 — agent unavailable": the sidecar's Studio tools imported `three`
+  (a devDependency the package does not ship) through `src/scenes.js`. The
+  timeline clock moved to its own module and a test now walks every import
+  reachable from `bin/` and fails on any chain to `three`. (#591)
+- A CLIProxy key in the environment no longer leaves the panel on the ChatGPT
+  sign-in wall; readiness counts every key-authenticated provider. (#591)
+- `CCLAY_KIMODO_HOST=… npx cozyclay` died at start with
+  `Cannot find package 'three'`: the motion bridge now runs from the staged
+  MCP runtime (which carries `three`, `tools/` and `dist/models`), and the
+  package isolation test keeps it that way. (#591)
+- A live-hub port already taken by another CozyClay is reported on the
+  launcher's terminal and named in the pane's error instead of
+  "Studio execution is not installed"; agent handler failures are logged
+  before the 502; a session id with no record no longer shows
+  "Previous conversation could not be restored". (#591)
+
+Studio
+
+- Create on the start screen opens the selected sample scene under the typed
+  name instead of an empty stage named after it; starting over with unsaved
+  work asks first. (#591)
+- Reloading a project created from the start screen brought the previous
+  session's walking take back onto the character, with "Unsaved changes":
+  the hosted-demo seed re-fired on every mount while the bridge probe was
+  down. It now skips a saved project (a `?scene=` launch still seeds), and a
+  reload opens on the clean checkpoint. (#591)
+- With a take installed, the gizmo and the Transform panel's Position and
+  Rotation move the character again; the take keeps animating relative to
+  the new placement. (#591)
+- The shot card's hover actions sit above the card, so clicking a short
+  shot's name selects it instead of hitting Delete. Draw rail is disabled
+  with a reason when no shot is selected. (#591)
+
+Tests
+
+- The start-screen and project-menu browser suites run against the v2
+  shell again, gain the sample-card Create regression, and join the CI
+  browser matrix as observation suites; new regressions cover the package
+  import graph, CLIProxy readiness, the stage transform and the reload
+  session. (#591)
+
+## 2.0.1
+
+- The camera tutorial follows the v2 shell and new installs default to the
+  light theme. (#586)
+
 ## 2.0.0
 
 CozyClay 2.0 is the v2 editor: a floating-glass shell with light and dark

package/README.md

@@ -52,7 +52,7 @@ 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 the transform strip's gizmo. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye Top-View drives 2D root waypoints for character paths. **View ▾** on the viewport bar holds the reference grid and Auto 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). |
+| **Stage a scene** | Create primitives and set pieces, then move, rotate and scale them with the transform strip's gizmo. Cast people from **Assets › Characters**: a rigged character you can pose and animate, or a **Capsule figure** — a rigless stand-in with one posture (stand, sit or lie) chosen in Details, for blocking where nobody needs to move their limbs. Capsule figures follow root paths and per-panel placements like any character but refuse pose, IK and motion tools, with the reason in the tooltip. Grid snapping is a preference, not a law — hold `Ctrl` mid-drag to invert it. A bird's-eye Top-View drives 2D root waypoints for character paths. **View ▾** on the viewport bar holds the reference grid and Auto 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. Fly, pan and orbit lock the pointer for the hold, so the view can turn past the window edge. Selecting the camera switches to Camera mode. **Look through** in the Shot monitor puts you behind the shot camera with the same bindings; click the on-screen **Shot camera** indicator or press `Esc` to return to the free camera. |
 | **Cut and move the camera** | Add shots on the timeline, draw a dolly rail on the Top-View, set speed, height and crane, and preview the move through the shot camera. Each shot carries a **Target model** (Seedance 2.5, Kling 2, Veo 3, self-hosted MiniMax-H3) and is flagged when the cut runs past that model's limits. |
 | **Export for AI video** | One **Export ▾** menu: a keyframe pack (first/last frame, clip, camera JSON, prompt, README) as a zip, an mp4 of the shot, depth + normal conditioning passes, a storyboard contact sheet, and an OTIO cut list. Seedance 2.5 reads the pack's greybox clip as its white-model reference video, and MiniMax H3, Wan 3.0, LTX Desktop and fal render-to-real accept the same clip. The **Shot Prompt** turns the framing into a structured prompt for the model you picked. |
@@ -61,6 +61,21 @@ https://github.com/user-attachments/assets/1d0113e5-6922-443d-affc-1bdabc666247
 | **Capture motion from video or a photo** | Drop a clip or a still: the GPU box runs [GVHMR](https://github.com/zju3dv/GVHMR) and the result is retargeted onto the character with stabilisation, contact correction and a quality gate. |
 | **Direct it with an AI** | Open the **Agent panel** (`Cmd/Ctrl+B`), sign in with your ChatGPT account, and ask for a shot in plain language; the conversation survives reloads and you can paste a reference screenshot into it. Or connect Claude — or any MCP client — or drive the Studio from a terminal with `cclay live`. All three place the cast, frame "a low wide profile", generate multi-phase motion, and the viewport moves in front of you. See [AI control](#ai-control). |
 
+## Modes
+
+A project is either a **Storyboard** or an **Animation**. Pick it on the start screen (the badge in the top bar shows which one you are in); a project keeps its mode when saved and reopened.
+
+| | Storyboard | Animation |
+| --- | --- | --- |
+| **Choose it when** | You want a row of still panels: framing, who stands where, a caption and a hold per panel | You want moving shots: motion on a timeline, camera moves, takes |
+| **Timeline** | The **Board** dock tab: one card per panel with a greybox thumbnail, caption, hold, duplicate, delete and drag-to-reorder | Shots on the timeline, with motion and Prompt Blocks |
+| **Cast** | Rigged characters or capsule figures; each panel can keep its own placement ("Use stage placement" clears it) | Rigged characters with Pose and Motion mode; capsule figures for blocking |
+| **Motion tools** | Hidden: no Generate group, no Motion mode (`4`); the agent has no `generate_motion` and the MCP motion tools answer `NOT_IN_MODE` | Available |
+| **Agent** | **Agent · Storyboard** builds one panel per request and never generates motion | The full Studio tool set |
+| **Exports** | **Stylize** a panel through the image route, **Send to Workflow** (the stylized image or the greybox) from its card, plus the Export ▾ menu: **Contact sheet (PNG)**, **Panel pack (zip)**, **All panels (zip)**, **Animatic (mp4)**, **Cut list (OTIO)** and **Depth + normal (PNG)**; File ▸ **Export as Animation project…** turns the panels into an Animation. There is no keyframe pack or shot video in a storyboard | Export ▾: keyframe pack, mp4, depth + normal passes, contact sheet, OTIO cut list |
+
+Start in Storyboard when you are deciding what the shots are, then open the idea as an Animation when it needs motion.
+
 ## Quick start
 
 You need Node.js 22.19 or newer, npm or bun, and a Chromium-based browser.
@@ -182,7 +197,7 @@ Every control's home is recorded in [`docs/studio-ui-ia.md`](docs/studio-ui-ia.m
 | --- | --- |
 | [`docs/kimodo-setup.md`](docs/kimodo-setup.md) | Installing Kimodo: the route table, CUDA over SSH, local MLX/Metal/CPU generation and what each route supports |
 | [`docs/agent-cli.md`](docs/agent-cli.md) | Driving the Studio from a terminal with `cclay live` |
-| [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking |
+| [`docs/agent-prompt-to-scene.md`](docs/agent-prompt-to-scene.md) | The ask / infer / omit rule the Agent follows when turning a video prompt into blocking, and the one-panel-per-request rule in storyboards |
 | [`mcp/README.md`](mcp/README.md) | MCP tools, transports, and the live-control protocol |
 | [`docs/studio-ui-ia.md`](docs/studio-ui-ia.md) | Where every Studio control lives and why |
 | [`docs/privacy.md`](docs/privacy.md) | The full analytics disclosure: events, identifiers, opt-out, internal QA marking |

package/THIRD_PARTY_NOTICES.md

@@ -165,6 +165,14 @@ Their transitive runtime dependencies, which the agent sidecar also loads, are:
 - `ignore` — License: MIT — https://github.com/kaelzhang/node-ignore
 - `yaml` — License: ISC — https://github.com/eemeli/yaml
 
+## jpeg-js
+
+The MCP runtime decodes JPEG reference images for `compare_sculpt` with `jpeg-js`, on the local machine.
+
+- Copyright (c) 2014, Eugene Ware and Adobe
+- License: BSD-3-Clause
+- Source: https://github.com/jpeg-js/jpeg-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.