cozyclay 1.2.0 → 1.3.0

package/dist/fonts/InstrumentSerif-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Instrument Serif Project Authors (https://github.com/Instrument/instrument-serif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/fonts/Inter-OFL.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/fonts/README.md

@@ -0,0 +1,15 @@
+# Bundled fonts
+
+The `.woff2` files in this directory are redistributed with CozyClay under the
+SIL Open Font License 1.1, which permits bundling them with software provided
+each copy carries the copyright notice and the licence. Those are the two
+`-OFL.txt` files here; keep them alongside the fonts.
+
+| File | Family | Copyright | Licence |
+| --- | --- | --- | --- |
+| `inter-latin.woff2` | [Inter](https://github.com/rsms/inter) | Copyright (c) 2016 The Inter Project Authors | [OFL-1.1](Inter-OFL.txt) |
+| `instrument-serif-latin.woff2`, `instrument-serif-italic-latin.woff2` | [Instrument Serif](https://github.com/Instrument/instrument-serif) | Copyright 2022 The Instrument Serif Project Authors | [OFL-1.1](InstrumentSerif-OFL.txt) |
+
+Both are subsets. Under OFL a modified copy may not use the Reserved Font Name,
+so if a subset is ever renamed or edited beyond subsetting, check clause 3 before
+shipping it.

package/dist/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-    <meta name="description" content="CozyClay is an open-source, browser-based 3D staging and previz studio. Block a scene, pose characters, author camera moves and cuts, and preview generated motion — no Blender, no Unity, no install." />
+    <meta name="description" content="Free, open source previs software that runs in the browser. Block a scene, pose characters, and author camera moves and cuts, then hand the same shots to an AI video model. No Blender, no Unity, no install." />
     <meta name="theme-color" content="#232323" />
     <meta name="apple-mobile-web-app-title" content="CozyClay" />
     <link rel="canonical" href="https://cozyclay.org/" />
@@ -14,19 +14,19 @@
 
     <meta property="og:type" content="website" />
     <meta property="og:site_name" content="CozyClay" />
-    <meta property="og:title" content="CozyClay — browser-based 3D staging and previz studio" />
+    <meta property="og:title" content="CozyClay — open source 3D previs software, in your browser" />
     <meta property="og:description" content="Block a scene, pose characters, author camera moves and cuts, and preview generated motion. Open source, runs in your browser." />
     <meta property="og:url" content="https://cozyclay.org/" />
     <meta property="og:image" content="https://cozyclay.org/media/cozyclay-demo-poster.jpg" />
     <meta property="og:image:width" content="1920" />
     <meta property="og:image:height" content="1080" />
-    <meta property="og:image:alt" content="A CozyClay shot mid-wipe: the greybox previz on one half, the generated result on the other." />
+    <meta property="og:image:alt" content="A CozyClay shot mid-wipe: the greybox previs on one half, the generated result on the other." />
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="CozyClay — browser-based 3D staging and previz studio" />
+    <meta name="twitter:title" content="CozyClay — open source 3D previs software, in your browser" />
     <meta name="twitter:description" content="Block a scene, pose characters, author camera moves and cuts, and preview generated motion. Open source, runs in your browser." />
     <meta name="twitter:image" content="https://cozyclay.org/media/cozyclay-demo-poster.jpg" />
 
-    <title>CozyClay — browser-based 3D staging and previz studio</title>
+    <title>CozyClay — open source 3D previs software, in your browser</title>
 
     <meta property="og:video" content="https://cozyclay.org/media/cozyclay-demo.mp4" />
     <meta property="og:video:type" content="video/mp4" />
@@ -67,7 +67,23 @@
             "name": "What is CozyClay?",
             "acceptedAnswer": {
               "@type": "Answer",
-              "text": "CozyClay is an open-source 3D staging and previsualization studio that runs in a browser. You block a scene with primitives and set pieces, pose characters, draw root paths, author camera moves and cuts on a timeline, and preview generated motion."
+              "text": "CozyClay is open source previs software that runs in a browser. You block a scene with primitives and set pieces, pose characters, draw root paths, author camera moves and cuts on a timeline, and preview generated motion."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "What is previs, and is it spelled previz?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "Previs is short for previsualization: the rough 3D pass where a shot gets blocked — camera position, lens, character movement, cut points — before anyone commits to final assets or render budget. It is written both previs and previz; the industry mostly writes previs, and both mean the same thing."
+            }
+          },
+          {
+            "@type": "Question",
+            "name": "Is there free previs software?",
+            "acceptedAnswer": {
+              "@type": "Answer",
+              "text": "CozyClay is free and open source under GPL-3.0, and it runs in the browser, so there is no licence and no install between you and a blocked shot. Run it locally with npx cozyclay and nothing leaves your machine."
             }
           },
           {
@@ -221,7 +237,7 @@
           <a href="#what">What it does</a>
           <a href="#start">Quick start</a>
           <a href="#controls">Controls</a>
-          <a href="#faq">FAQ</a>
+          <a href="/ai-camera-control/">AI camera control</a>
           <a href="https://github.com/HaD0Yun/CozyClay">GitHub</a>
         </nav>
       </div>
@@ -235,9 +251,9 @@
 
         <h1>Block the shot before you pay to render it</h1>
         <p class="lede">
-          CozyClay is a browser-based 3D staging studio. Block a scene, pose characters,
-          author camera moves and cuts, then hand the exact same shots to a video model.
-          No Blender, no Unity, no install.
+          CozyClay is free, open source previs software that runs in your browser. Block a
+          scene, pose characters, and author camera moves and cuts — then hand the same
+          shots to an AI video model. No Blender, no Unity, no install.
         </p>
 
         <div class="reel">
@@ -249,8 +265,9 @@
           ></video>
         </div>
         <p class="reel-note">
-          Thirty seconds: greybox previz on the left of the wipe, the generated result on the
-          right. Every cut came out of the same camera setup you see being built.
+          Thirty seconds: greybox previs on the left of the wipe, the generated result on the
+          right. Every cut came out of the same camera setup you see being built — more on
+          <a href="/ai-camera-control/">camera control for AI video</a>.
         </p>
 
         <div class="cta">
@@ -266,7 +283,7 @@
       <section id="what">
         <h2>What you can do</h2>
         <p class="sub">
-          Previz is the part of animation where you decide what happens before anyone commits
+          Previs is the part of animation where you decide what happens before anyone commits
           to final assets. CozyClay keeps that whole loop in one page.
         </p>
         <div class="grid">
@@ -355,9 +372,36 @@ npm run dev</code></pre>
         <details open>
           <summary>What is CozyClay?</summary>
           <p>
-            CozyClay is an open-source 3D staging and previsualization studio that runs in a
-            browser. You block a scene with primitives and set pieces, pose characters, draw
-            root paths, author camera moves and cuts on a timeline, and preview generated motion.
+            CozyClay is open source previs software that runs in a browser. You block a scene
+            with primitives and set pieces, pose characters, draw root paths, author camera
+            moves and cuts on a timeline, and preview generated motion.
+          </p>
+        </details>
+        <details>
+          <summary>What is previs, and is it spelled previz?</summary>
+          <p>
+            Previs is short for previsualization: the rough 3D pass where a shot gets blocked —
+            camera position, lens, character movement, cut points — before anyone commits to
+            final assets or render budget. It is written both <strong>previs</strong> and
+            <strong>previz</strong>; the industry mostly writes previs, and both mean the same
+            thing.
+          </p>
+        </details>
+        <details>
+          <summary>Is there free previs software?</summary>
+          <p>
+            CozyClay is free and open source under GPL-3.0, and it runs in the browser, so there
+            is no licence and no install between you and a blocked shot. Run it locally with
+            <code>npx cozyclay</code> and nothing leaves your machine.
+          </p>
+        </details>
+        <details>
+          <summary>Can I use it for camera control in AI video?</summary>
+          <p>
+            That is the reason it exists. Block the shot in 3D — angle, lens, dolly, the frame
+            the cut lands on — then take those camera moves to a video model instead of
+            describing them in a prompt and hoping. See
+            <a href="/ai-camera-control/">camera control for AI video</a>.
           </p>
         </details>
         <details>

package/dist/sitemap.xml

@@ -2,8 +2,14 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://cozyclay.org/</loc>
-    <lastmod>2026-08-14</lastmod>
+    <lastmod>2026-08-15</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
+  <url>
+    <loc>https://cozyclay.org/ai-camera-control/</loc>
+    <lastmod>2026-08-15</lastmod>
+    <changefreq>monthly</changefreq>
+    <priority>0.8</priority>
+  </url>
 </urlset>

package/mcp/LIVE-PROTOCOL.md

@@ -0,0 +1,63 @@
+# CozyClay live-control protocol v1
+
+One WebSocket, JSON text frames. The **MCP server hosts** the socket
+(`ws://127.0.0.1:5184/live`); the **editor is the client** and reconnects
+every 3 s while the page is open. Either side may be absent: the editor works
+exactly as before when nothing is listening, and the MCP server falls back to
+its in-memory scene when no editor is connected.
+
+## Frames
+
+editor -> server, once after connect:
+
+    { "type": "hello", "role": "editor", "version": 1 }
+
+server -> editor, one per command:
+
+    { "type": "cmd", "id": "<opaque string>", "name": "<command>", "args": { ... } }
+
+editor -> server, one per command, echoing `id`:
+
+    { "type": "result", "id": "<same id>", "ok": true,  "value": { ... } }
+    { "type": "result", "id": "<same id>", "ok": false, "error": "<human message>" }
+
+Unknown `name` MUST answer `ok:false`, never silence. The server times a
+command out after 5 s and treats it as failed.
+
+## Commands (v1)
+
+All coordinates are metres, rotations are degrees of yaw, ids are the ids the
+scene document already uses.
+
+| name | args | value | notes |
+| --- | --- | --- | --- |
+| `ping` | `{}` | `{ "pong": true }` | liveness |
+| `describe` | `{}` | `{ sceneName, camera: { x, y, z, focalMm }, characters: [{ id, subject, x, z, rot, hidden }], objects: [{ id, name, x, y, z, rot, scaleX, scaleY, scaleZ, footprint, height }] }` | read the live scene; object scale and footprint travel too, so sizes are reported from what was actually built |
+| `set_camera` | `{ x?, y?, z?, focalMm? }` | `{ camera }` | omitted fields keep their value; the **viewport must visibly move** |
+| `add_character` | `{ subject, x?, z?, rot? }` | `{ id }` | |
+| `update_character` | `{ ref, x?, z?, rot?, subject?, hidden? }` | `{ id }` | `ref` = id, letter (`"A"`) or 1-based slot |
+| `remove_character` | `{ ref }` | `{ id }` | must refuse to empty the cast |
+| `place_object` | `{ kind, x?, z?, y?, rot? }` | `{ id }` | `kind` from OBJECT_LIBRARY |
+| `update_object` | `{ id, x?, y?, z?, rot?, rotX?, rotZ?, scale?, scaleX?, scaleY?, scaleZ?, color? }` | `{ id }` | `scale` sets all three axes; per-axis values override it |
+| `remove_object` | `{ id }` | `{ id }` | |
+| `load_scenes` | `{ document }` | `{ sceneName }` | replace the whole scene document (same shape `serializeSceneDocument` emits); the big hammer that guarantees parity |
+
+## Hard rules for the editor side
+
+- Every mutation MUST go through the same React state paths the UI itself
+  uses (the setters/reducers the gizmo, inspector and panels call). Mutating
+  three.js objects directly is forbidden: anything outside React state is
+  overwritten on the next render.
+- Every mutation MUST land in undo history exactly like the equivalent UI
+  action would, or be explicitly documented as not undoable.
+- The socket client MUST be a no-op in production builds unless explicitly
+  enabled; in dev it may always try. A failed connection must never surface
+  an error to the user - silence and retry.
+
+## Hard rules for the server side
+
+- When an editor is connected, live-capable tools forward to it and answer
+  from its `describe`; when none is connected they fall back to the in-memory
+  scene exactly as today. The tool surface does not change.
+- One editor at a time: a second `hello` replaces the first (last write wins),
+  and the displaced socket is closed.

package/mcp/README.md

@@ -0,0 +1,142 @@
+# CozyClay MCP server
+
+Lets an AI assistant (Claude Desktop, Cursor, any MCP client) block a scene, place the camera,
+generate character motion and read the shot back as film vocabulary — then turn it into an AI
+image/video prompt.
+
+Works two ways, with the same tools:
+
+- **Editor open** — tool calls drive the visible viewport live: camera, cast, set, motion,
+  prompt blocks on the timeline.
+- **No editor** — everything runs headless: no browser, no GPU, no build step.
+
+## Run it locally
+
+```sh
+cd mcp
+npm install
+npm start          # speaks MCP over stdio and hosts ws://127.0.0.1:5184/live
+npm run verify     # drives the no-editor fallback as a client and checks results
+npm run verify:live # drives a fake editor over the live WebSocket protocol
+```
+
+Then point a client at it. For Claude Desktop, in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cozyclay": {
+      "command": "node",
+      "args": ["/absolute/path/to/CozyClay/mcp/server.mjs"]
+    }
+  }
+}
+```
+
+Restart the client; 20 tools appear.
+
+Prefer a long-lived endpoint? `node server.mjs --http 5183` serves Streamable HTTP at
+`http://127.0.0.1:5183/mcp` (one isolated session per client), with a plain status page at `/`.
+
+## What it does
+
+Describe the shot you want. The server does the trigonometry and answers the way a crew would.
+
+> "Put a detective and a courier in an alley, then give me a low wide profile shot of the courier."
+
+```
+WIDE SHOT · RIGHT PROFILE · KNEE LEVEL · 24MM
+
+size      wide shot — the subject fills 40% of frame height
+view      a right-side profile view
+level     a low knee-level angle looking up at the subject
+distance  4.39m
+```
+
+`render_prompt` turns that same geometry into a prompt that carries the real framing, so the
+generated frame matches the blocking instead of drifting off into a generic shot.
+
+## Tools
+
+| tool | what it does |
+| --- | --- |
+| `describe_scene` | the whole state: camera, framing, cast, set |
+| `live_status` | whether an editor tab is connected for live control |
+| `describe_shot` | current camera geometry as film vocabulary |
+| `set_camera` | move the lens / change focal length directly |
+| `frame_shot` | frame by intent — size, view, level, side |
+| `add_character` / `place_character` / `remove_character` | the cast |
+| `focus_character` | choose who the camera frames |
+| `place_object` / `update_object` / `remove_object` | the set |
+| `render_prompt` | the shot as an AI image or video prompt |
+| `generate_motion` | multi-phase character motion through the ARDY bridge — phases land as prompt blocks |
+| `mark_camera_move` / `describe_camera_move` | name a move between two camera positions |
+| `add_scene` / `switch_scene` | multiple scenes per project |
+| `open_project` / `save_project` | read and write `.cclayproject` files |
+
+Coordinates are metres (`x` right, `z` toward the default camera, `y` height above the floor).
+Rotations are degrees of yaw. Characters are addressed by letter (`"A"`), slot (`"2"`) or id
+(`"char-a"`).
+
+## Live editor control
+
+The server hosts `ws://127.0.0.1:5184/live` by default (`COZYCLAY_LIVE_PORT` or
+`--live-port <port>` to change it). A CozyClay editor tab served by `npm run dev` connects on
+its own; `live_status` tells you whether one is attached. With an editor connected, mutations
+forward to it and reads report its real state — the screen you are looking at is the source of
+truth. Without one, every tool keeps its in-memory behaviour. In `--http` mode each session
+child attempts to bind the live port, so one session owns the editor and the others
+intentionally run memory-only.
+
+The wire protocol — one WebSocket, ten commands, editor-side rules — is specified in
+[`LIVE-PROTOCOL.md`](LIVE-PROTOCOL.md).
+
+## Motion generation
+
+`generate_motion` takes plain-language beats and a length:
+
+```
+phases: ["seated on a chair, slowly stands up",
+         "breaks into a sprint",
+         "trips and falls hard to the ground"]
+seconds: 10
+```
+
+It tiles them into contiguous ARDY segments, streams the generation through the local bridge
+(`127.0.0.1:5181`, started by `npm run dev`), and — when an editor is connected — loads the
+result onto the active character with one prompt block per phase on the timeline. Pass a
+previous `motion_url` to reload a clip without generating again.
+
+## Round-trips with the studio
+
+`save_project` writes a real `.cclayproject` file, so a scene blocked here opens in the studio to
+be posed, timed and generated — and a scene built in the studio opens here with `open_project`.
+
+## Design
+
+This server owns no geometry, no film vocabulary and no prompt text. Every answer is computed by
+the same modules the studio renders with, imported straight from the working tree:
+
+| module | responsibility |
+| --- | --- |
+| `../src/shot.js` | geometry → film vocabulary → prompt |
+| `../src/scenes.js` | the scene document and its stage envelope |
+| `../src/scene-objects.js` | the set: create / update / remove, clamped and snapped |
+| `../src/camera-move.js` | two framings → a named camera move |
+| `../src/project.js` | the `.cclayproject` envelope |
+
+That is the whole design. Because the imports are relative, the server always speaks the working
+tree's vocabulary: retune a band in `shot.js` and this server reports the new answer on its next
+start, with nothing to publish or reinstall. The studio and the MCP server cannot disagree about
+what a 35mm medium shot is, because there is only one implementation of it.
+
+`frame_shot` is the one place that inverts `shot.js` rather than calling it — it solves for the
+camera position that produces a requested size. `npm run verify` checks all 420 combinations the
+schema accepts, so a retune in `shot.js` fails loudly here instead of quietly mis-framing.
+
+### Framing conflicts
+
+Shot size is treated as the stronger request. An extreme close-up from an overhead lens is
+geometrically impossible on a wide lens — the camera would sit inside the subject — so the server
+lengthens the lens until the requested angle fits and says so, the way a crew swaps glass rather
+than abandoning the close-up.