reel-studio 0.2.0 → 0.2.3

package/desk/lib.mjs

@@ -0,0 +1,190 @@
+// Shared by the desk server and the desk MCP server: productions, review notes, approvals, renders.
+// A production's review lives in productions/<brand>/<ID>/review.json:
+//   { "notes": [{ id, t, text, by: "human"|"claude", status: "open"|"fixed"|"closed", reply, at }],
+//     "approvals": [{ stage: "storyboard"|"final", by, at }],
+//     "claude": { "session": "<id of the last headless Claude run>" } }
+// Approvals are written by people only (the desk's buttons), never by Claude or the MCP server.
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const ROOT = process.env.REEL_STUDIO_ROOT
+  ? path.resolve(process.env.REEL_STUDIO_ROOT)
+  : path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const STATE = path.join(ROOT, "desk", ".state.json");
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+/** `brand/ID-slug` → absolute folder, refusing anything outside productions/. */
+export function prodDir(id) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(id || "") || id.startsWith("_")) throw new Error(`bad production id: ${id}`);
+  const dir = path.join(ROOT, "productions", id);
+  if (!existsSync(path.join(dir, "README.md"))) throw new Error(`no production ${id}`);
+  return dir;
+}
+
+function field(readme, name) {
+  const m = new RegExp(`^\\|\\s*${name}\\s*\\|\\s*(.*?)\\s*\\|\\s*$`, "mi").exec(readme);
+  return m ? m[1].replace(/`/g, "") : "";
+}
+
+export function listProductions() {
+  const base = path.join(ROOT, "productions");
+  const out = [];
+  for (const brand of existsSync(base) ? readdirSync(base).sort() : []) {
+    if (brand.startsWith("_") || brand.startsWith(".") || !statSync(path.join(base, brand)).isDirectory()) continue;
+    for (const name of readdirSync(path.join(base, brand)).sort()) {
+      const dir = path.join(base, brand, name);
+      if (!existsSync(path.join(dir, "README.md"))) continue;
+      const readme = readFileSync(path.join(dir, "README.md"), "utf8");
+      const comp = path.join(dir, "composition", "index.html");
+      const exportDir = path.join(dir, "export");
+      const review = readReview(`${brand}/${name}`);
+      out.push({
+        id: `${brand}/${name}`, brand,
+        title: (/^#\s+(.+)$/m.exec(readme)?.[1] || name).trim(),
+        status: field(readme, "Status"),
+        composition: existsSync(comp) ? `/productions/${brand}/${name}/composition/index.html` : null,
+        exports: existsSync(exportDir) ? readdirSync(exportDir).filter((f) => /\.(mp4|png|jpg)$/i.test(f))
+          .map((f) => `/productions/${brand}/${name}/export/${f}`) : [],
+        openNotes: review.notes.filter((n) => n.status === "open").length,
+        approvals: review.approvals,
+      });
+    }
+  }
+  return out;
+}
+
+export function readReview(id) {
+  const file = path.join(prodDir(id), "review.json");
+  const r = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  return { notes: r.notes || [], approvals: r.approvals || [], claude: r.claude || {} };
+}
+
+export function writeReview(id, review) {
+  writeFileSync(path.join(prodDir(id), "review.json"), JSON.stringify(review, null, 2) + "\n");
+  return review;
+}
+
+export function addNote(id, { t, text, by = "human" }) {
+  if (!text?.trim()) throw new Error("note needs text");
+  const r = readReview(id);
+  const note = { id: Math.max(0, ...r.notes.map((n) => n.id)) + 1, t: +(+t || 0).toFixed(3), text: text.trim(), by,
+    status: "open", reply: "", at: new Date().toISOString() };
+  r.notes.push(note);
+  writeReview(id, r);
+  return note;
+}
+
+export function updateNote(id, noteId, patch) {
+  const r = readReview(id);
+  const note = r.notes.find((n) => n.id === +noteId);
+  if (!note) throw new Error(`no note ${noteId}`);
+  for (const k of ["status", "reply", "text"]) if (patch[k] !== undefined) note[k] = patch[k];
+  if (!["open", "fixed", "closed"].includes(note.status)) throw new Error(`bad status ${note.status}`);
+  writeReview(id, r);
+  return note;
+}
+
+export function deleteNote(id, noteId) {
+  const r = readReview(id);
+  r.notes = r.notes.filter((n) => n.id !== +noteId);
+  writeReview(id, r);
+}
+
+/** A person approves the storyboard (ticks the README box) or the final cut. */
+export function approve(id, stage, by) {
+  if (!["storyboard", "final"].includes(stage)) throw new Error(`bad stage ${stage}`);
+  if (!by?.trim()) throw new Error("approval needs a name");
+  const dir = prodDir(id);
+  const file = path.join(dir, "README.md");
+  let readme = readFileSync(file, "utf8");
+  const stamp = `${today()}, ${by.trim()}, in the desk`;
+  if (stage === "storyboard") {
+    readme = readme.replace(/^- \[ \] Storyboard approved\./m, `- [x] Storyboard approved (${stamp}).`);
+    readme = readme.replace(/^(\|\s*Approved by \/ date\s*\|)\s*\|\s*$/m, `$1 ${by.trim()}, ${today()} |`);
+  } else {
+    const line = `- [x] Final cut approved for delivery (${stamp}).`;
+    readme = /^- \[x\] Storyboard approved.*$/m.test(readme)
+      ? readme.replace(/^- \[x\] Storyboard approved.*$/m, (m) => `${m}\n${line}`)
+      : readme.trimEnd() + `\n\n${line}\n`;
+  }
+  writeFileSync(file, readme);
+  const r = readReview(id);
+  r.approvals.push({ stage, by: by.trim(), at: new Date().toISOString() });
+  writeReview(id, r);
+  return r.approvals;
+}
+
+/** What the person has open in the desk, for Claude (desk_state). */
+export function readState() {
+  return existsSync(STATE) ? JSON.parse(readFileSync(STATE, "utf8")) : {};
+}
+export function writeState(s) {
+  writeFileSync(STATE, JSON.stringify({ ...s, at: new Date().toISOString() }, null, 2) + "\n");
+}
+
+/** Render outputs from the desk go to qa/desk/ so a delivered export is never overwritten. */
+export function renderArgs(id, kind, t = 0, safe = false) {
+  const dir = prodDir(id);
+  const comp = path.join(dir, "composition", "index.html");
+  if (!existsSync(comp)) throw new Error(`${id} has no composition yet`);
+  const out = path.join(dir, "qa", "desk");
+  mkdirSync(out, { recursive: true });
+  const rel = (p) => path.relative(ROOT, p);
+  const sf = safe ? ["--safe"] : [];
+  if (kind === "still") {
+    const file = path.join(out, `still_t${(+t).toFixed(2)}${safe ? "_safe" : ""}.png`);
+    return { cmd: process.execPath, args: ["core/render.mjs", "still", rel(comp), rel(file), "--t", String(+t), ...sf], file: rel(file) };
+  }
+  if (kind === "video") {
+    const file = path.join(out, "preview.mp4");
+    return { cmd: process.execPath, args: ["core/render.mjs", "video", rel(comp), rel(file), ...sf], file: rel(file) };
+  }
+  if (kind === "qa") {
+    const video = path.join(out, "preview.mp4");
+    if (!existsSync(video)) throw new Error("render a preview video first");
+    return { cmd: "bash", args: ["scripts/qa-video.sh", rel(video), rel(path.join(out, "qa"))], file: rel(path.join(out, "qa", "report.md")) };
+  }
+  throw new Error(`bad render kind ${kind}`);
+}
+
+/** Run a command from the repo root; onLine gets each output line. `done` resolves to the exit code. */
+export function runLines(cmd, args, onLine) {
+  const p = spawn(cmd, args, { cwd: ROOT, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+  const done = new Promise((resolve) => {
+    let buf = "";
+    const feed = (d) => {
+      buf += d;
+      const parts = buf.split(/\r?\n|\r/);
+      buf = parts.pop();
+      for (const l of parts) if (l.trim()) onLine(l);
+    };
+    p.stdout.on("data", feed);
+    p.stderr.on("data", feed);
+    p.on("error", (e) => { onLine(String(e)); resolve(127); });
+    p.on("close", (code) => { if (buf.trim()) onLine(buf); resolve(code ?? 1); });
+  });
+  return { proc: p, done };
+}
+
+/** The prompt a headless Claude run gets from the desk's "Send to Claude". */
+export function claudePrompt(id, notes, extra = "") {
+  const lines = [
+    `You are working on the Reel Studio production productions/${id}/ (follow CLAUDE.md, STATUS.md and the make-video skill).`,
+    `The person reviewing it in the desk asked for this. Composition: productions/${id}/composition/index.html.`,
+  ];
+  if (notes.length) {
+    lines.push("", "Review notes pinned to frames (from review.json):");
+    for (const n of notes) lines.push(`- #${n.id} at ${n.t.toFixed(2)} s: ${n.text}`);
+    lines.push("", "For each note: change the composition, render a still at that time to check it " +
+      "(node core/render.mjs still ... --t <t>, or the reel-desk render_frame tool), then call the reel-desk tool " +
+      "resolve_note with a one-line reply saying what you changed. If a note needs a decision or a fact you do not have, " +
+      "leave it open and reply with the question.");
+  }
+  if (extra.trim()) lines.push("", "Request: " + extra.trim());
+  lines.push("", "Rules: never record or tick an approval (only the person does that in the desk); never invent product facts; " +
+    "do not render the final export, the person renders previews from the desk. End with a two-line summary.");
+  return lines.join("\n");
+}

package/desk/mcp.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/* reel-desk: an optional MCP server (stdio, zero dependencies) that lets Claude Code see the desk.
+ * Not registered by default. To add it to a project:
+ *   claude mcp add reel-desk --scope project -- node desk/mcp.mjs
+ * (The desk's own "Send to Claude" passes it with --mcp-config, so that works without registering.)
+ *
+ * Tools: desk_state (what the person has open), list_productions, list_notes, add_note (Claude's own QA findings),
+ * resolve_note (mark a note fixed with a reply; the person closes it after checking), render_frame (a still, returned
+ * as an image). There is deliberately no approval tool: approvals are made by people in the desk.
+ * Talks to no network service; renders run core/render.mjs locally.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import * as desk from "./lib.mjs";
+
+let VERSION = "0";
+try { VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || VERSION; } catch {}
+const prod = { type: "string", description: "Production id, brand/ID-slug, e.g. bike-logger/REEL-002-engines" };
+
+const tools = {
+  desk_state: {
+    description: "What the person has open in the Reel Studio desk right now: production and time (s). Use it to resolve 'this frame' or 'here'.",
+    inputSchema: { type: "object", properties: {} },
+    run: () => {
+      const s = desk.readState();
+      return s.production ? s : { note: "The desk has not been opened yet (node desk/server.mjs)." };
+    },
+  },
+  list_productions: {
+    description: "Every production with its status, composition, exports, open note count and approvals.",
+    inputSchema: { type: "object", properties: {} },
+    run: () => desk.listProductions(),
+  },
+  list_notes: {
+    description: "Review notes pinned to frames of a production. Each has id, t (seconds), text, by, status (open|fixed|closed) and reply.",
+    inputSchema: { type: "object", properties: { production: prod, status: { type: "string", enum: ["open", "fixed", "closed", "all"] } }, required: ["production"] },
+    run: ({ production, status = "open" }) => desk.readReview(production).notes.filter((n) => status === "all" || n.status === status),
+  },
+  add_note: {
+    description: "Pin your own finding (e.g. from frame-by-frame QA) to a time so the person sees it on the desk timeline.",
+    inputSchema: { type: "object", properties: { production: prod, t: { type: "number" }, text: { type: "string" } }, required: ["production", "t", "text"] },
+    run: ({ production, t, text }) => desk.addNote(production, { t, text, by: "claude" }),
+  },
+  resolve_note: {
+    description: "After changing the composition for a note, mark it fixed with a one-line reply. To ask a question instead, keep status open and put the question in reply. Only the person closes notes.",
+    inputSchema: { type: "object", properties: { production: prod, id: { type: "number" }, reply: { type: "string" },
+      status: { type: "string", enum: ["fixed", "open"], default: "fixed" } }, required: ["production", "id", "reply"] },
+    run: ({ production, id, reply, status = "fixed" }) => desk.updateNote(production, id, { status, reply }),
+  },
+  render_frame: {
+    description: "Render one frame of a production's composition with the real renderer and return it as an image. Saved in qa/desk/.",
+    inputSchema: { type: "object", properties: { production: prod, t: { type: "number" }, safe: { type: "boolean", description: "Draw the safe zones" } }, required: ["production", "t"] },
+    run: async ({ production, t, safe = false }) => {
+      const { cmd, args, file } = desk.renderArgs(production, "still", t, safe);
+      const out = [];
+      const code = await desk.runLines(cmd, args, (l) => out.push(l)).done;
+      if (code !== 0) throw new Error(`render failed (exit ${code}):\n${out.join("\n")}`);
+      return { content: [
+        { type: "text", text: `${file} (t=${t}s)${out.length > 1 ? "\n" + out.slice(1).join("\n") : ""}` },
+        { type: "image", mimeType: "image/png", data: readFileSync(path.join(desk.ROOT, file)).toString("base64") },
+      ] };
+    },
+  },
+};
+
+const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", ...msg }) + "\n");
+
+async function handle(msg) {
+  const { id, method, params = {} } = msg;
+  if (id === undefined) return; // notifications (initialized, cancelled)
+  if (method === "initialize") {
+    return send({ id, result: { protocolVersion: params.protocolVersion || "2025-06-18", capabilities: { tools: {} },
+      serverInfo: { name: "reel-desk", version: VERSION },
+      instructions: "Reel Studio desk: review notes pinned to frames, and frame renders. Never approve on the person's behalf." } });
+  }
+  if (method === "ping") return send({ id, result: {} });
+  if (method === "tools/list") {
+    return send({ id, result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema })) } });
+  }
+  if (method === "tools/call") {
+    const tool = tools[params.name];
+    if (!tool) return send({ id, error: { code: -32602, message: `unknown tool ${params.name}` } });
+    try {
+      const r = await tool.run(params.arguments || {});
+      return send({ id, result: r?.content ? r : { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] } });
+    } catch (e) {
+      return send({ id, result: { isError: true, content: [{ type: "text", text: e.message }] } });
+    }
+  }
+  send({ id, error: { code: -32601, message: `method not found: ${method}` } });
+}
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return send({ id: null, error: { code: -32700, message: "parse error" } }); }
+  handle(msg);
+});

package/desk/server.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/* Reel Studio desk: an optional local review app for productions. Nothing else in the kit needs it.
+ *
+ *   node desk/server.mjs [--port 4100]      then open http://127.0.0.1:4100
+ *
+ * Serves the repo root (so compositions load exactly as the renderer loads them) plus a small JSON API:
+ * productions, frame notes, approvals, renders (still / preview video / QA) and "Send to Claude", which runs the
+ * local Claude Code CLI headlessly (`claude -p`) with your existing login. No API key: ANTHROPIC_API_KEY is removed
+ * from Claude's environment so a key in your shell is never billed by accident.
+ * Listens on 127.0.0.1 only. Zero dependencies.
+ */
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import * as desk from "./lib.mjs";
+
+const { ROOT } = desk;
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const argv = process.argv.slice(2);
+const PORT = +(argv.includes("--port") ? argv[argv.indexOf("--port") + 1] : process.env.PORT ?? 4100);
+const CLAUDE = process.env.CLAUDE_BIN || "claude";
+// What a desk-started Claude may do: read and edit the project, render, run QA, use the desk tools. Nothing else.
+const ALLOWED = ["Read", "Edit", "Write", "Glob", "Grep", "Bash(node core/render.mjs *)", "Bash(scripts/qa-video.sh *)",
+  "Bash(scripts/extract-frames.sh *)", "mcp__reel-desk"];
+const TYPES = {
+  ".html": "text/html; charset=utf-8", ".js": "text/javascript", ".mjs": "text/javascript", ".css": "text/css",
+  ".json": "application/json", ".md": "text/markdown; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png",
+  ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".ttf": "font/ttf", ".otf": "font/otf",
+  ".woff2": "font/woff2", ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime", ".mp3": "audio/mpeg",
+  ".wav": "audio/wav", ".txt": "text/plain; charset=utf-8", ".csv": "text/plain; charset=utf-8",
+};
+
+// ---- jobs: renders and Claude runs, streamed to the page over server-sent events ----
+const jobs = new Map();
+let nextJob = 1;
+function newJob(kind, production) {
+  const job = { id: nextJob++, kind, production, lines: [], done: false, code: null, file: null, proc: null, subs: new Set() };
+  jobs.set(job.id, job);
+  return job;
+}
+function emit(job, event) {
+  if (event.line !== undefined) job.lines.push(event.line);
+  for (const res of job.subs) res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+function finish(job, code) {
+  job.done = true; job.code = code; job.proc = null;
+  emit(job, { done: true, code, file: job.file });
+  for (const res of job.subs) res.end();
+  job.subs.clear();
+}
+const publicJob = (j) => ({ id: j.id, kind: j.kind, production: j.production, done: j.done, code: j.code, file: j.file });
+
+function startRender(production, kind, t, safe) {
+  const { cmd, args, file } = desk.renderArgs(production, kind, t, safe);
+  const job = newJob(kind, production);
+  job.file = "/" + file;
+  emit(job, { line: `$ ${path.basename(cmd)} ${args.join(" ")}` });
+  const { proc, done } = desk.runLines(cmd, args, (line) => emit(job, { line }));
+  job.proc = proc;
+  done.then((code) => finish(job, code));
+  return job;
+}
+
+/** One line per stream-json event, enough to follow the run. */
+function describe(ev) {
+  if (ev.type === "system" && ev.subtype === "init") return `session ${ev.session_id} · ${ev.model || ""}`;
+  if (ev.type === "assistant") {
+    return (ev.message?.content || []).map((b) => {
+      if (b.type === "text") return b.text.trim();
+      if (b.type === "tool_use") {
+        const i = b.input || {};
+        const arg = i.command || i.file_path || i.pattern || (i.t !== undefined ? `t=${i.t}` : "") || i.id || "";
+        return `→ ${b.name.replace(/^mcp__reel-desk__/, "desk.")} ${String(arg).slice(0, 160)}`;
+      }
+      return "";
+    }).filter(Boolean).join("\n");
+  }
+  if (ev.type === "result") return `${ev.is_error ? "✗" : "✓"} done in ${((ev.duration_ms || 0) / 1000).toFixed(0)} s, ${ev.num_turns ?? "?"} turns`;
+  return "";
+}
+
+function startClaude(production, noteIds, extra) {
+  const review = desk.readReview(production);
+  const notes = review.notes.filter((n) => (noteIds?.length ? noteIds.includes(n.id) : n.status === "open"));
+  if (!notes.length && !extra?.trim()) throw new Error("nothing to send: no open notes and no request");
+  const prompt = desk.claudePrompt(production, notes, extra);
+  const mcp = JSON.stringify({ mcpServers: { "reel-desk": { command: process.execPath, args: [path.join(HERE, "mcp.mjs")],
+    env: { REEL_STUDIO_ROOT: ROOT } } } });
+  const args = ["-p", prompt, "--output-format", "stream-json", "--verbose", "--mcp-config", mcp,
+    "--allowedTools", ALLOWED.join(","), "--permission-mode", "acceptEdits"];
+  if (review.claude.session) args.push("--resume", review.claude.session);
+  const job = newJob("claude", production);
+  emit(job, { line: `Sending ${notes.length} note(s)${extra?.trim() ? " and a request" : ""} to Claude Code${review.claude.session ? " (same session as last time)" : ""}…` });
+  const env = { ...process.env };
+  delete env.ANTHROPIC_API_KEY; // use the Claude Code login, never a stray key
+  const proc = spawn(CLAUDE, args, { cwd: ROOT, env, stdio: ["ignore", "pipe", "pipe"] });
+  job.proc = proc;
+  let buf = "", session = null;
+  proc.stdout.on("data", (d) => {
+    buf += d;
+    const parts = buf.split("\n");
+    buf = parts.pop();
+    for (const l of parts) {
+      if (!l.trim()) continue;
+      let ev;
+      try { ev = JSON.parse(l); } catch { emit(job, { line: l }); continue; }
+      if (ev.session_id) session = ev.session_id;
+      const text = describe(ev);
+      if (text) emit(job, { line: text });
+    }
+  });
+  proc.stderr.on("data", (d) => String(d).split("\n").filter((l) => l.trim()).forEach((line) => emit(job, { line })));
+  proc.on("error", (e) => emit(job, { line: e.code === "ENOENT" ? `Claude Code CLI not found (${CLAUDE}). Install it and sign in once with \`claude\`.` : String(e) }));
+  proc.on("close", (code) => {
+    if (session) {
+      const r = desk.readReview(production); // re-read: Claude resolved notes while it ran
+      r.claude = { ...r.claude, session };
+      desk.writeReview(production, r);
+    }
+    finish(job, code ?? 1);
+  });
+  return job;
+}
+
+// ---- HTTP ----
+const json = (res, code, body) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(body)); };
+const body = (req) => new Promise((resolve, reject) => {
+  let s = "";
+  req.on("data", (d) => (s += d)).on("end", () => { try { resolve(s ? JSON.parse(s) : {}); } catch (e) { reject(e); } });
+});
+
+async function api(req, res, url) {
+  const q = url.searchParams;
+  const parts = url.pathname.split("/").filter(Boolean).slice(1); // after "api"
+  const m = req.method;
+  if (parts[0] === "productions" && m === "GET") return json(res, 200, desk.listProductions());
+  if (parts[0] === "review" && m === "GET") return json(res, 200, desk.readReview(q.get("p")));
+  if (parts[0] === "readme" && m === "GET") {
+    res.writeHead(200, { "content-type": "text/markdown; charset=utf-8" });
+    return res.end(await readFile(path.join(desk.prodDir(q.get("p")), "README.md")));
+  }
+  if (parts[0] === "notes") {
+    const p = q.get("p");
+    if (m === "POST") return json(res, 200, desk.addNote(p, await body(req)));
+    if (m === "PATCH") return json(res, 200, desk.updateNote(p, parts[1], await body(req)));
+    if (m === "DELETE") { desk.deleteNote(p, parts[1]); return json(res, 200, { ok: true }); }
+  }
+  if (parts[0] === "approve" && m === "POST") {
+    const b = await body(req);
+    return json(res, 200, desk.approve(q.get("p"), b.stage, b.by));
+  }
+  if (parts[0] === "state" && m === "POST") { desk.writeState(await body(req)); return json(res, 200, { ok: true }); }
+  if (parts[0] === "render" && m === "POST") {
+    const b = await body(req);
+    return json(res, 200, publicJob(startRender(q.get("p"), b.kind, b.t, b.safe)));
+  }
+  if (parts[0] === "claude" && m === "POST") {
+    const b = await body(req);
+    return json(res, 200, publicJob(startClaude(q.get("p"), b.notes, b.request)));
+  }
+  if (parts[0] === "jobs") {
+    const job = jobs.get(+parts[1]);
+    if (!parts[1]) return json(res, 200, [...jobs.values()].map(publicJob).reverse());
+    if (!job) return json(res, 404, { error: "no such job" });
+    if (parts[2] === "stop" && m === "POST") { job.proc?.kill("SIGTERM"); return json(res, 200, { ok: true }); }
+    if (parts[2] === "events") {
+      res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+      for (const line of job.lines) res.write(`data: ${JSON.stringify({ line })}\n\n`);
+      if (job.done) { res.write(`data: ${JSON.stringify({ done: true, code: job.code, file: job.file })}\n\n`); return res.end(); }
+      job.subs.add(res);
+      req.on("close", () => job.subs.delete(res));
+      return;
+    }
+    return json(res, 200, publicJob(job));
+  }
+  json(res, 404, { error: "unknown endpoint" });
+}
+
+async function files(req, res, url) {
+  let rel = decodeURIComponent(url.pathname);
+  if (rel === "/") rel = "/desk/index.html";
+  // The desk's own page comes from this folder; everything else from the project root
+  const [base, sub] = rel.startsWith("/desk/") ? [HERE, rel.slice(5)] : [ROOT, rel];
+  const file = path.join(base, sub);
+  if (!file.startsWith(base + path.sep) || /\/\.(git|env)/.test(rel)) throw Object.assign(new Error("forbidden"), { code: 403 });
+  const s = await stat(file);
+  const data = await readFile(s.isDirectory() ? path.join(file, "index.html") : file);
+  const type = TYPES[path.extname(s.isDirectory() ? "x.html" : file).toLowerCase()] || "application/octet-stream";
+  // Range requests: Chrome needs them to seek inside <video> plates (same as core/render.mjs)
+  const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range || "");
+  if (range) {
+    const start = range[1] ? +range[1] : data.length - +range[2];
+    const end = range[1] && range[2] ? Math.min(+range[2], data.length - 1) : data.length - 1;
+    res.writeHead(206, { "content-type": type, "accept-ranges": "bytes", "content-range": `bytes ${start}-${end}/${data.length}`, "content-length": end - start + 1 });
+    return res.end(data.subarray(start, end + 1));
+  }
+  res.writeHead(200, { "content-type": type, "accept-ranges": "bytes", "cache-control": "no-store" });
+  res.end(data);
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, "http://x");
+  try {
+    if (url.pathname.startsWith("/api/")) {
+      // Only the desk page itself may call the API (blocks other sites in your browser from driving it)
+      const origin = req.headers.origin;
+      if (origin && origin !== `http://${req.headers.host}`) return json(res, 403, { error: "cross-origin" });
+      return await api(req, res, url);
+    }
+    await files(req, res, url);
+  } catch (e) {
+    if (url.pathname.startsWith("/api/")) return json(res, e.code === 403 ? 403 : 400, { error: e.message });
+    res.writeHead(e.code === 403 ? 403 : 404); res.end(e.code === 403 ? "forbidden" : "not found");
+  }
+});
+
+server.listen(PORT, "127.0.0.1", () => {
+  console.log(`Reel Studio desk: http://127.0.0.1:${server.address().port}  (serving ${ROOT})`);
+  console.log("Optional: let your Claude Code sessions see the desk with  claude mcp add reel-desk --scope project -- node desk/mcp.mjs");
+});

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "reel-studio",
-  "version": "0.2.0",
-  "description": "Make marketing reels, ads and posts with code, for any brand, with Claude Code. HTML on one clock → MP4.",
+  "version": "0.2.3",
+  "description": "Agency-quality marketing reels, ads and posts made by Claude Code. Free and open source; no per-video fees.",
   "type": "module",
   "bin": { "reel-studio": "bin/reel-studio.mjs" },
   "files": [
     "bin/",
+    "desk/",
+    "!desk/.state.json",
     "core/README.md",
     "core/package.json",
     "core/package-lock.json",
@@ -21,8 +23,12 @@
     "examples/engines-demo/plates/blob.mp4",
     ".claude/skills/"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:python": "packaging/build-python.sh && cd python && uv run --isolated --with . python -m unittest discover -s tests -v"
+  },
   "engines": { "node": ">=18" },
-  "keywords": ["video", "reels", "marketing", "claude-code", "gsap", "threejs", "pixi", "blender", "ffmpeg", "remotion-alternative"],
+  "keywords": ["video", "reels", "marketing", "claude-code", "claude-code-plugin", "claude-skills", "ai-video", "video-generation", "video-ads", "motion-graphics", "instagram-reels", "tiktok", "gsap", "threejs", "pixi", "blender", "ffmpeg", "headless-chrome", "remotion-alternative"],
   "author": "Murathan Yıldırım (https://github.com/murathany7)",
   "license": "MIT",
   "homepage": "https://github.com/murathany7/reel-studio#readme",

package/scripts/init-project.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Copy the Reel Studio kit into a project so its skills can render there.
 #   scripts/init-project.sh <kit_root> [project_dir] [--update] [--with-skills]
-# Copies core/, engines/, scripts/, the engines demo and the brand/production templates, adds CLAUDE.md,
+# Copies core/, engines/, scripts/, desk/ (the optional review app), the engines demo and the brand/production templates, adds CLAUDE.md,
 # STATUS.md and .gitignore if missing, then runs npm install in core/ and checks the tools.
 # Existing files are kept; --update refreshes core/, engines/ and scripts/ (and the skills) from the kit (brands and
 # productions are never touched). --with-skills also copies the skills into .claude/skills/ (for installs without
@@ -36,6 +36,7 @@ else
   copy core core $mode
   copy engines engines $mode
   copy scripts scripts $mode
+  copy desk desk $mode
   copy brands/_template brands/_template
   copy productions/_TEMPLATE productions/_TEMPLATE
   [ -n "$skills" ] && copy .claude/skills .claude/skills $mode

package/templates/project/CLAUDE.md

@@ -14,6 +14,7 @@ per brand, one folder per production.
 | 3D (Three.js, Blender) | `scene-3d` skill |
 | A cartoon character or mascot | `character-2d` skill |
 | Recording a brand's live website | `capture-site` skill |
+| *Optional:* the person reviews in the desk (frame notes, approvals) | `review-desk` skill, `desk/README.md` |
 | Render, audio and QA commands | `core/README.md` |
 | What is in progress, decided, learned | `STATUS.md` |
 
@@ -21,6 +22,7 @@ per brand, one folder per production.
 |---|---|
 | `core/` | `render.mjs` (HTML → MP4/PNG), `lib/runtime.js` (the `Studio` clock), `lib/base.css` |
 | `engines/` | One adapter per engine |
+| `desk/` | *Optional* review app (`node desk/server.mjs`): frame notes, renders, approvals. Nothing else depends on it |
 | `scripts/` | Audio mix, transcription, video QA, frame tools |
 | `brands/<slug>/` | Facts and their sources, look, voice, `compliance.md` (start from `brands/_template`) |
 | `productions/<brand>/<ID>-<slug>/` | One piece (start from `productions/_TEMPLATE`) |

package/templates/project/gitignore

@@ -1,6 +1,9 @@
 node_modules/
 .DS_Store
 **/qa/flagged/
+# Desk: renders made from the desk and what it has open (review.json stays tracked)
+**/qa/desk/
+desk/.state.json
 __pycache__/
 
 # Big media stays out of git