reel-studio 0.2.0 → 0.2.3

package/.claude/skills/make-video/SKILL.md

@@ -18,7 +18,8 @@ Fill sections 1–4 of the production README: the problem, the benefit, 3 hook v
 visual, **engine**, on-screen text, sound), caption. Pick engines with the `pick-engine` skill and say why.
 State size, length, placement and sound (VO / music / silent).
 
-**Stop and ask for approval.** No plates, audio or composition before the box is ticked.
+**Stop and ask for approval** in chat. No plates, audio or composition before the box is ticked. (If the person uses
+the optional desk, they may approve there instead: `review-desk` skill. Never tick the box on your own.)
 
 ## 2. Produce
 

package/.claude/skills/review-desk/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: review-desk
+description: Optional. Open the Reel Studio desk (a local review app) and work from its review notes - notes pinned to frames, renders, approvals. Use only when the person asks for the desk or already uses it - "open the desk", "apply my desk notes", "fix what I marked", "what's on this frame" - or a production has a review.json. Never required: reviewing and approving in chat works the same.
+---
+
+# Review desk (optional)
+
+The kit works the same without it: storyboards are approved in chat, and QA is the `make-video` steps. Don't start
+the desk or suggest it unless the person asks, or they already use it (a `review.json` in the production).
+
+The desk (`desk/`) is a local page for the person: it plays a production's composition frame-exact through the
+renderer's own clock (`__seek`), and lets them pin notes to frames, render stills, preview videos and QA, read the
+storyboard, approve, and send notes to Claude. It only reads and writes files in the project, so everything it does
+reaches you as files (and, if it is registered, through the `reel-desk` MCP server).
+
+## Open it
+
+`node desk/server.mjs` (run it in the background), then the person opens <http://127.0.0.1:4100>. In the Claude
+desktop app, open that URL in the browser pane. `npx reel-studio desk` does the same. Port: `--port <n>`.
+
+The `reel-desk` MCP tools below are not registered by default. If they aren't available and the person wants them:
+`claude mcp add reel-desk --scope project -- node desk/mcp.mjs` (then restart the session). Without them, read and
+write `review.json` directly.
+
+## Where things are
+
+| | |
+|---|---|
+| Notes and approvals | `productions/<brand>/<ID>/review.json` (tracked in git: it is the review record) |
+| What the person has open | `desk/.state.json`, or the `desk_state` tool |
+| Desk renders | `productions/<brand>/<ID>/qa/desk/` (stills, `preview.mp4`, `qa/`); never the delivered export |
+
+## Working from notes
+
+1. `desk_state` tells you which production and time "this frame" means. `list_notes` gives the open notes
+   (`id`, `t` in seconds, `text`). Without the MCP server, read `review.json`.
+2. For each note: change the composition, check it with `render_frame` at the note's `t` (or
+   `node core/render.mjs still … --t <t>`) and **look at the image**.
+3. `resolve_note` with a one-line reply saying what changed. If a note needs a fact, an asset or a decision you
+   don't have, keep it `open` and put the question in the reply. Only the person closes notes (after checking).
+4. Your own QA findings can go on the timeline too: `add_note` (they show as by `claude`).
+
+The desk's **Send to Claude** button runs exactly this loop headlessly (`claude -p` with the person's own Claude Code
+login, `ANTHROPIC_API_KEY` removed, tools limited to read/edit/render/QA and `reel-desk`), one session per production
+(`review.json` → `claude.session`).
+
+## Approvals are the person's
+
+The desk's **Approve storyboard** ticks `- [x] Storyboard approved` in the production README and fills
+*Approved by / date*; **Approve final cut** adds a final-cut line. Both are logged in `review.json` → `approvals`.
+**Never write an approval yourself**, in the README or in `review.json`, and never treat a fixed note as approval.
+When a storyboard is ready, say "it's in the desk for approval" and stop (golden rule 2).

package/.claude/skills/scene-3d/SKILL.md

@@ -15,6 +15,11 @@ description: Build a 3D shot for a video - live in the composition with Three.js
   to the import map). Wrap the load in `Studio.wait(...)`. Put model files in the brand's `assets/models/` or the production's `composition/`.
 - Cartoon look: `toon(color, { steps })` + `outline(mesh, { thickness })`. Hard light: one `DirectionalLight` + low `AmbientLight`.
 - Animated GLB clips: create an `AnimationMixer`, then in `update` call `mixer.setTime(t - start)`. Never `mixer.update(delta)`.
+- HTML tags that follow 3D points: in `update(t)`, call `camera.updateMatrixWorld()` and the parent's
+  `updateMatrixWorld()` before `vector.applyMatrix4(obj.matrixWorld).project(camera)`. Three.js refreshes these only
+  inside `render()`, so without it a tag follows the previous frame. Example: `productions/bike-logger/REEL-002-engines`.
+- CAD meshes as JSON (vertices + indices): `toNonIndexed()` + `computeVertexNormals()` gives crisp flat facets.
+  Render with `threeLayer(..., { pixelRatio: 2 })` for supersampled edges.
 - Physics: bake it (simulate at a fixed 1/120 s step into an array before the first frame) and look up by `t`.
 
 ## Blender (plate)

package/README.md

@@ -1,13 +1,20 @@
 <h1 align="center">🎬 Reel Studio</h1>
 
 <p align="center">
+  <a href="https://github.com/murathany7/reel-studio/actions/workflows/ci.yml"><img src="https://github.com/murathany7/reel-studio/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/reel-studio"><img src="https://img.shields.io/npm/v/reel-studio?color=e8a33d" alt="npm"></a>
+  <a href="https://pypi.org/project/reel-studio/"><img src="https://img.shields.io/pypi/v/reel-studio?color=e8a33d" alt="PyPI"></a>
+  <a href="https://github.com/murathany7/homebrew-reel-studio"><img src="https://img.shields.io/badge/homebrew-tap-e8a33d" alt="Homebrew"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3ecf7a" alt="MIT"></a>
   <img src="https://img.shields.io/badge/Claude%20Code-plugin-8b93a1" alt="Claude Code plugin">
 </p>
 
-<p align="center"><b>Make marketing reels, ads and posts with code, for any brand, with Claude Code.</b><br>
-Plain HTML pages on one clock → headless Chrome → MP4. Every frame is reproducible.</p>
+<p align="center"><b>Agency-quality reels, ads and posts, made by Claude Code.</b><br>
+Open source and free. Your Claude subscription does the rest.<br>
+No editor, no timeline, no per-video fees. Every frame is code you own.</p>
+
+<p align="center"><sub>Plain HTML pages on one clock → headless Chrome → MP4, for any brand. Every frame is reproducible.<br>
+AI voiceover (ElevenLabs) is optional and billed by its provider.</sub></p>
 
 <p align="center">
   <img src="docs/media/bike-logger-reel.gif" width="240" alt="Bike Logger reel">
@@ -81,6 +88,20 @@ It copies the renderer into the folder, installs it and checks Chrome and ffmpeg
 npx reel-studio init
 ```
 
+**Or with Python or Homebrew**, the same kit and the same `init` (the renderer still runs on Node):
+
+```bash
+pipx install reel-studio && reel-studio init      # or: uvx reel-studio init
+brew install murathany7/reel-studio/reel-studio && reel-studio init   # brings Node and ffmpeg
+```
+
+**Or with Docker**, with Node, Chromium, ffmpeg and fonts inside, nothing to install (Linux renders use software WebGL):
+
+```bash
+docker run --rm -it -v "$PWD":/work ghcr.io/murathany7/reel-studio reel-studio init
+docker run --rm -v "$PWD":/work ghcr.io/murathany7/reel-studio node core/render.mjs video <page>.html out.mp4
+```
+
 **Or clone it** and work inside the repo:
 
 ```bash
@@ -93,6 +114,14 @@ cd core && npm install && cd ..
 > *Add my product as a new brand: https://my-product.com* → facts, colours, fonts, voice, rules
 > *Make a 15 s reel for &lt;brand&gt; about &lt;feature&gt;* → brief and storyboard, then the video once you approve
 
+That's the whole product: you talk to Claude Code, it writes the storyboard, waits for your OK in chat, then makes,
+renders and checks the video.
+
+**Optional: the desk.** If you'd rather review on a page than in chat, run `npx reel-studio desk` (or
+`node desk/server.mjs`) and open <http://127.0.0.1:4100>. You can scrub frame by frame, pin notes to frames, send them
+to Claude Code (your own login, no API key), render stills and previews, and approve the storyboard and the final cut.
+Nothing else needs it, and nothing changes if you never open it. See [`desk/README.md`](desk/README.md).
+
 ## What's inside
 
 ```
@@ -101,12 +130,17 @@ engines/       one adapter per engine
 brands/        one folder per brand  (_template to start)
 productions/   one folder per piece  (brief, composition, audio, QA, export)
 scripts/       audio mix, transcription, QA, frame tools
-.claude/skills setup · make-video · new-brand · pick-engine · scene-3d · character-2d · capture-site
+desk/          optional local review app (and its optional reel-desk MCP server)
+.claude/skills setup · make-video · new-brand · pick-engine · scene-3d · character-2d · capture-site · review-desk (optional)
 ```
 
 ## Contributing
 
-Open source and early. New engine adapters, brand examples and QA checks are all welcome; open an issue or a PR.
+Open source and early. New engine adapters, skill fixes and QA checks are all welcome: see
+[CONTRIBUTING.md](CONTRIBUTING.md). `npm test` re-renders the demo twice and checks every frame matches.
+
+**Made something?** [Show your reel](https://github.com/murathany7/reel-studio/issues/new?template=show-your-reel.yml):
+good examples get featured here. Questions go to [Discussions](https://github.com/murathany7/reel-studio/discussions).
 
 ## License
 

package/bin/reel-studio.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 // npx reel-studio init [dir] [--update]: copy the Reel Studio kit and its Claude Code skills into a project.
+// npx reel-studio desk [--port 4100]: open the review desk of the project in this folder.
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -17,15 +19,27 @@ if (cmd === "init") {
     console.log(`
 Done. Open this folder in Claude Code and ask:
   "Add my product as a new brand: https://…"
-  "Make a 15 s reel for <brand> about <feature>"`);
+  "Make a 15 s reel for <brand> about <feature>"
+Optional, to review on a page instead of in chat:  npx reel-studio desk`);
   }
   process.exit(r.status ?? 1);
 }
 
+if (cmd === "desk") {
+  // The project's own copy, so the desk serves the project (its brands, productions and kit version)
+  const server = path.resolve("desk/server.mjs");
+  if (!existsSync(server)) {
+    console.error("No desk/ here. Run `npx reel-studio init` in this folder first (or `--update` an older project).");
+    process.exit(1);
+  }
+  process.exit(spawnSync(process.execPath, [server, ...rest], { stdio: "inherit" }).status ?? 1);
+}
+
 console.log(`Reel Studio: marketing videos made with code, run by Claude Code.
 
   npx reel-studio init [dir]           copy the kit and skills into dir (default: here) and install it
-  npx reel-studio init [dir] --update  refresh core/, engines/, scripts/ and skills from this version
+  npx reel-studio init [dir] --update  refresh core/, engines/, scripts/, desk/ and skills from this version
+  npx reel-studio desk [--port 4100]   optional review page: play, pin notes, send them to Claude, approve
 
 Claude Code plugin instead:  /plugin marketplace add murathany7/reel-studio
 More: https://github.com/murathany7/reel-studio`);

package/core/lib/runtime.js

@@ -86,7 +86,17 @@
       this.onSeek((t) => new Promise((res) => {
         const target = Math.max(0, Math.min(t - start, (el.duration || 0) - 0.001));
         if (Math.abs(el.currentTime - target) < 0.0005) return res();
-        el.addEventListener("seeked", res, { once: true });
+        // "seeked" can fire before the new frame is painted, and a screenshot then catches the old one (seen on a
+        // cold CI runner): also wait for the frame to be presented. A seek within the same plate frame presents
+        // nothing new, so that wait gives up after a moment; the old frame is the right one then.
+        let seeked = false, shown = !el.requestVideoFrameCallback, timer;
+        const done = () => seeked && shown && (clearTimeout(timer), res());
+        if (!shown) el.requestVideoFrameCallback(() => { shown = true; done(); });
+        el.addEventListener("seeked", () => {
+          seeked = true;
+          timer = setTimeout(() => { shown = true; done(); }, 250);
+          done();
+        }, { once: true });
         el.currentTime = target;
       }));
       return el;

package/core/package-lock.json

@@ -9,8 +9,8 @@
         "gsap": "^3.12.5",
         "lottie-web": "^5.12.2",
         "pixi.js": "^8.6.0",
-        "playwright-core": "1.49.1",
-        "three": "^0.170.0"
+        "playwright-core": "1.64.1",
+        "three": "^0.187.0"
       }
     },
     "node_modules/@pixi/colord": {
@@ -118,21 +118,21 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.49.1",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.49.1.tgz",
-      "integrity": "sha512-BzmpVcs4kE2CH15rWfzpjzVGhWERJfmnXmniSyKeRZUs9Ws65m+RGIi7mjJK/euCegfn3i7jvqWeWyHe9y3Vgg==",
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",
+      "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "node_modules/three": {
-      "version": "0.170.0",
-      "resolved": "https://registry.npmjs.org/three/-/three-0.170.0.tgz",
-      "integrity": "sha512-FQK+LEpYc0fBD+J8g6oSEyyNzjp+Q7Ks1C568WWaoMRLW+TkNNWmenWeGgJjV105Gd+p/2ql1ZcjYvNiPZBhuQ==",
+      "version": "0.187.0",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.187.0.tgz",
+      "integrity": "sha512-Qiu7R+Cmh8CstZsY1uJOSWnVlfo7ZtNLV7mF8Jltk3LB3AtDu9cRZlcnRKkAk8Y4z6KKw35z7Y7Urd7jWY8etA==",
       "license": "MIT"
     },
     "node_modules/tiny-lru": {

package/core/package.json

@@ -10,7 +10,7 @@
     "gsap": "^3.12.5",
     "lottie-web": "^5.12.2",
     "pixi.js": "^8.6.0",
-    "playwright-core": "1.49.1",
-    "three": "^0.170.0"
+    "playwright-core": "1.64.1",
+    "three": "^0.187.0"
   }
 }

package/core/render.mjs

@@ -78,8 +78,10 @@ function serve() {
 // WebGL (Three.js, Pixi) on the GPU, but compositing in software: with GPU compositing Chrome
 // draws <video> plates ~10 levels brighter than ffmpeg decodes them (measured 2026-11-02).
 // playwright-core is pinned (1.49.1) because 1.64 shifted plate colours the same way.
-const CHROME_ARGS = ["--force-color-profile=srgb", "--hide-scrollbars",
-  "--enable-gpu", "--use-angle=metal", "--ignore-gpu-blocklist", "--disable-gpu-compositing"];
+// WebGL: Metal on macOS; elsewhere (Linux, CI without a GPU) Chrome's software renderer, SwiftShader
+const CHROME_ARGS = ["--force-color-profile=srgb", "--hide-scrollbars", "--enable-gpu", "--ignore-gpu-blocklist",
+  "--disable-gpu-compositing",
+  ...(process.platform === "darwin" ? ["--use-angle=metal"] : ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"])];
 
 async function openPage(input, safe) {
   const server = await serve();

package/desk/README.md

@@ -0,0 +1,47 @@
+# Desk (optional)
+
+A local review app for productions, **for people who'd rather review on a page than in chat**. Nothing in the kit
+needs it: the skills are the product, and Claude Code writes, renders and checks the pieces either way. If you never
+open the desk, nothing changes. It adds no dependencies and doesn't register itself anywhere.
+
+```bash
+node desk/server.mjs            # or: npx reel-studio desk   →  http://127.0.0.1:4100
+```
+
+| Panel | What it does |
+|---|---|
+| Player | Loads `composition/index.html?render=1` and drives it with `__ready`, `__meta`, `__seek`, the same calls as `core/render.mjs`. Space play/pause, ←/→ one frame (⇧ one second), S safe zones, N new note |
+| Notes | Pin a note to the current frame. Dots on the scrubber. Claude marks notes *fixed* with a reply; you close them after checking |
+| Claude | Sends the open notes and/or a request to a headless Claude Code run and streams what it does. The composition reloads when it's done |
+| Render | Still at this frame, preview video, QA (`scripts/qa-video.sh`). Output goes to `qa/desk/`, never `export/` |
+| Approve | Storyboard (ticks the README box) and final cut. People only: Claude and the MCP server can't approve |
+| Storyboard | The production README |
+
+## How Claude is involved, and what it costs
+
+There are three ways, and none needs an API key.
+
+1. **Files.** Notes and approvals live in `productions/<brand>/<ID>/review.json`. In any Claude Code session say
+   "apply my desk notes" (the `review-desk` skill).
+2. **Send to Claude** runs `claude -p` (the Claude Code CLI on this machine, signed in as you) from the project root.
+   `ANTHROPIC_API_KEY` is removed from its environment, so it always uses your Claude Code login. Its tools are limited
+   to Read/Edit/Write/Glob/Grep, `node core/render.mjs`, `scripts/qa-video.sh`, `scripts/extract-frames.sh` and the
+   `reel-desk` tools. It runs one session per production (`--resume`). Set `CLAUDE_BIN` to use another `claude`.
+3. **`reel-desk` MCP server** (`desk/mcp.mjs`), optional on top of the optional desk, and not registered by default.
+   Add it with `claude mcp add reel-desk --scope project -- node desk/mcp.mjs`. It lets a Claude Code session see the desk:
+   `desk_state`, `list_productions`, `list_notes`, `add_note`, `resolve_note`, `render_frame` (returns the image).
+   It has no approval tool.
+
+## Safety
+
+The server listens on 127.0.0.1 only, serves files from the project root only (not `.git` or `.env*`), and refuses
+API calls from other origins, so another site open in your browser can't drive it. It has no dependencies.
+
+## Files
+
+| | |
+|---|---|
+| `server.mjs` | HTTP server: static files with range requests (for plates) + the JSON API + job streams (SSE) |
+| `lib.mjs` | Productions, notes, approvals, render commands, the Claude prompt. Shared by the server and the MCP server |
+| `mcp.mjs` | The `reel-desk` MCP server (stdio JSON-RPC) |
+| `index.html`, `app.js`, `desk.css` | The page. No build step |