fablecut 0.0.0-stage → 1.12.0

package/server.js

@@ -0,0 +1,775 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   FableCut server — zero-dependency Node.js
+   Run:  node server.js   →  http://localhost:7777
+
+   Adds to the browser editor:
+     • persistent project      ./project.json      (GET/PUT /api/project)
+     • media library folder    ./media/            (served at /media/*, POST /api/upload,
+                                                    POST /api/import-url)
+     • live reload             GET /api/events     (SSE: event "change" for
+                                                    project/media/library;
+                                                    event "profiles" for
+                                                    encoding-profiles.json)
+
+   Automation: any tool (e.g. Claude Code) can edit project.json or drop files
+   into ./media — the browser UI reloads instantly. Schema: see CLAUDE.md.
+   ═══════════════════════════════════════════════════════════════════════════ */
+"use strict";
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const { spawn, spawnSync, execFile } = require("child_process");
+
+const { analyze } = require("./analyze");
+const {
+  PROFILES_FILE,
+  loadEncodeProfiles,
+  invalidateEncodeProfiles,
+  resolveProfile,
+  listProfilesPublic,
+  profileSummary,
+  buildExportArgs,
+  dryRunProfile,
+} = require("./encode-profiles");
+const { downloadImportUrl, maybeFaststart } = require("./import-url");
+const { createExportJobs } = require("./export-jobs");
+const { denoiseFile, AMOUNT_IDS: DENOISE_AMOUNTS } = require("./denoise");
+
+const {
+  APP_DIR, DATA_DIR, MEDIA_DIR, EXPORTS_DIR, ANALYSIS_DIR, LIBRARY_DIR,
+  PROJECT_FILE, LIBRARY_SUBDIRS, ensureDirs,
+} = require("./paths");
+
+/* Static app files are served from the install dir; everything the user creates
+   lives under DATA_DIR. The two are the same unless FABLECUT_DATA_DIR is set. */
+const ROOT = APP_DIR;
+const PORT = process.env.PORT || 7777;
+const HOST = process.env.HOST || "127.0.0.1";
+
+/* Requests must come from the local machine (or an explicitly allowed host).
+   The Host check stops DNS rebinding; the Origin check stops malicious web
+   pages firing blind cross-origin writes at the API. Opt into LAN use with
+   HOST=0.0.0.0 and FABLECUT_ALLOWED_HOSTS=192.168.1.20,mybox.local */
+const ALLOWED_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1", HOST.toLowerCase()]);
+for (const h of (process.env.FABLECUT_ALLOWED_HOSTS || "").split(","))
+  if (h.trim()) ALLOWED_HOSTS.add(h.trim().toLowerCase());
+
+function hostAllowed(value) {
+  if (!value) return false;
+  // strip a :port suffix, but not the colons inside a bare IPv6 address
+  const host = value.replace(/^(\[[^\]]*\]|[^:]+)(:\d+)?$/, "$1").toLowerCase();
+  return ALLOWED_HOSTS.has(host);
+}
+function requestAllowed(req) {
+  if (!hostAllowed(req.headers.host)) return false;
+  const origin = req.headers.origin;
+  if (origin) {
+    try { return hostAllowed(new URL(origin).host); } catch { return false; }
+  }
+  return true;
+}
+
+/* ffmpeg powers optional niceties (faststart remux on upload, fast export).
+   Everything else works without it. */
+let HAS_FFMPEG = false;
+try { HAS_FFMPEG = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0; } catch {}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8", ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8", ".json": "application/json",
+  ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime",
+  ".mkv": "video/x-matroska", ".m4v": "video/mp4",
+  ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg",
+  ".m4a": "audio/mp4", ".aac": "audio/aac", ".flac": "audio/flac",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".ttf": "font/ttf", ".otf": "font/otf", ".woff": "font/woff", ".woff2": "font/woff2",
+};
+
+ensureDirs();
+if (!fs.existsSync(PROJECT_FILE)) {
+  fs.writeFileSync(PROJECT_FILE, JSON.stringify({
+    name: "Untitled Project", width: 1280, height: 720, fps: 30,
+    revision: 0, media: [], clips: [],
+  }, null, 2));
+}
+
+/* ── SSE clients + file watching ── */
+const sseClients = new Set();
+function broadcast(event = "change", data = event) {
+  const payload = `event: ${event}\ndata: ${data}\n\n`;
+  for (const res of sseClients) res.write(payload);
+}
+let debounce = null;
+let profilesDebounce = null;
+function onFsChange() {
+  clearTimeout(debounce);
+  debounce = setTimeout(() => broadcast("change"), 150);
+}
+function onProfilesChange() {
+  invalidateEncodeProfiles();
+  clearTimeout(profilesDebounce);
+  profilesDebounce = setTimeout(() => broadcast("profiles"), 150);
+}
+/* watch the directory, not the file — atomic tmp+rename writes would detach a
+   direct file watcher on Windows */
+if (process.env.FABLECUT_NO_FS_WATCH !== "1") {
+  try { fs.watch(DATA_DIR, (ev, f) => { if (f === "project.json") onFsChange(); }); } catch {}
+  try {
+    fs.watch(ROOT, (ev, f) => {
+      if (f === path.basename(PROFILES_FILE)) onProfilesChange();
+    });
+  } catch {}
+  try { fs.watch(MEDIA_DIR, onFsChange); } catch {}
+  for (const d of LIBRARY_SUBDIRS) {
+    try { fs.watch(path.join(LIBRARY_DIR, d), onFsChange); } catch {}
+  }
+}
+
+/* ── Helpers ── */
+function safeName(name) {
+  return name.replace(/[^\w.\- ()\[\]]+/g, "_").slice(0, 120) || "file";
+}
+function sendJSON(res, code, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(code, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+  res.end(body);
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+/** Claim final + sibling `.part` paths with exclusive create (`wx`) so concurrent
+ *  exports cannot pick the same free name before either file exists. */
+function reserveExportPaths(dir, baseName, ext) {
+  const base = baseName.replace(/\.(mp4|mov|m4v|mkv|webm)$/i, "");
+  let i = 0;
+  for (;;) {
+    const stem = i === 0 ? base : `${base}_${i}`;
+    i++;
+    const outPath = path.join(dir, stem + ext);
+    const partPath = path.join(dir, stem + ".part" + ext);
+    if (fs.existsSync(outPath)) continue;
+    try {
+      fs.closeSync(fs.openSync(partPath, "wx")); // exclusive create — claim the name
+    } catch (e) {
+      if (e.code === "EEXIST") continue;
+      throw e;
+    }
+    if (fs.existsSync(outPath)) {
+      try { fs.rmSync(partPath, { force: true }); } catch { }
+      continue;
+    }
+    return { outPath, partPath };
+  }
+}
+function run(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { maxBuffer: 1 << 24 }, (err, _out, stderr) =>
+      err ? reject(new Error((stderr || String(err)).slice(-800))) : resolve());
+  });
+}
+
+/* Remux MP4-family uploads with `+faststart` so the moov atom leads the file —
+   without it <video> stalls for seconds probing over Range requests. */
+function faststart(file) { return maybeFaststart(file); }
+
+/* ── Export sessions ──
+   Two modes share the same HTTP session API:
+     jpeg   — browser streams JPEGs (one POST may concatenate several);
+              ffmpeg encodes via an encoding profile (Fast)
+     annexb — browser streams Annex-B H.264 (one POST may concatenate several AUs);
+              ffmpeg stream-copies (WebCodecs)
+   Both spawn on the FIRST frame, not here: the audio mix is uploaded between
+   /begin and the first frame, and a one-pass encode needs it on disk. */
+const exportSessions = new Map();
+/* Container + bitstream BT.709/tv for the WebCodecs (annexb) path.
+   `-c copy` alone drops the colr atom; the bsf writes VUI so players see
+   primaries/transfer, not "unknown". JPEG Fast export uses profile.color instead. */
+const COLOR_TAGS = [
+  "-colorspace", "bt709", "-color_primaries", "bt709",
+  "-color_trc", "bt709", "-color_range", "tv",
+];
+const COLOR_BSF = "h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1:video_full_range_flag=0";
+const EXPORT_IDLE_MS = 10 * 60 * 1000; // abandon sessions with no successful activity
+const EXPORT_SWEEP_MS = 60 * 1000;
+let exportSweepTimer = null;
+function touchExport(sess) {
+  if (sess) sess.lastTouch = Date.now();
+}
+function attachProc(sess, proc) {
+  sess.proc = proc;
+  sess.stderr = "";
+  proc.stderr.on("data", (d) => { sess.stderr = (sess.stderr + d).slice(-2000); });
+  proc.stdin.on("error", () => {}); // EPIPE if ffmpeg dies mid-stream
+  sess.done = new Promise((res) => proc.on("close", res));
+}
+async function beginExport(fps, name, profileId, hasAudio, mode, extra = {}) {
+  const m = mode === "annexb" ? "annexb" : "jpeg";
+  const rate = Number(fps);
+  if (!Number.isFinite(rate) || rate <= 0) {
+    throw new Error("export fps required (pass project.fps)");
+  }
+  const pixelFormat = extra.pixelFormat === "rgba" ? "rgba" : "jpeg";
+  const width = Math.max(0, extra.width | 0);
+  const height = Math.max(0, extra.height | 0);
+  if (pixelFormat === "rgba" && (width < 2 || height < 2)) {
+    throw new Error("export width/height required for rgba");
+  }
+  const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+  const safe = safeName(name || "export");
+  // Same filesystem as the finished file so renameSync(partPath, out) cannot EXDEV.
+  const dir = fs.mkdtempSync(path.join(EXPORTS_DIR, "fablecut-"));
+
+  if (m === "annexb") {
+    const { outPath, partPath } = reserveExportPaths(EXPORTS_DIR, safe, ".mp4");
+    const sess = {
+      mode: m, fps: rate, proc: null, dir,
+      name: safe, hasAudio: !!hasAudio,
+      wav: null, partPath, outPath,
+      stderr: "", done: null, lastTouch: Date.now(),
+      err: () => sess.stderr.trim().split("\n").filter(Boolean).slice(-3)
+        .map((l) => l.trim()).join(" · "),
+    };
+    sess.writeLock = Promise.resolve();
+    exportSessions.set(id, sess);
+    return { id, mode: m };
+  }
+
+  const profile = resolveProfile(profileId);
+  const dry = await dryRunProfile(profile, { fps: rate, hasAudio });
+  if (!dry.ok) throw new Error(`profile "${profile.id}" was rejected by ffmpeg: ${dry.error}`);
+  // Reserve the output name now (not at first frame) so concurrent exports
+  // cannot both see the same free path. The empty .part file is overwritten by ffmpeg (-y).
+  const { outPath, partPath } = reserveExportPaths(EXPORTS_DIR, safe, profile.extension);
+  const sess = {
+    mode: m, proc: null, fps: rate, profile, name: safe, hasAudio: !!hasAudio,
+    pixelFormat, width, height,
+    dir, wav: null, partPath, outPath,
+    stderr: "", done: null, lastTouch: Date.now(),
+    err: () => sess.stderr.trim().split("\n").filter(Boolean).slice(-3)
+      .map((l) => l.trim()).join(" · "),
+  };
+  sess.writeLock = Promise.resolve();
+  exportSessions.set(id, sess);
+  return { id, mode: m, profile: profile.id, label: profile.label, summary: profileSummary(profile) };
+}
+/* Encode into the paths reserved at /begin; rename .part → final on clean exit
+   so an aborted render never leaves something that looks like a finished file. */
+function startEncoder(sess) {
+  const proc = spawn("ffmpeg", buildExportArgs(sess.profile, {
+    fps: sess.fps, wavPath: sess.wav, outPath: sess.partPath,
+    pixelFormat: sess.pixelFormat, width: sess.width, height: sess.height,
+  }), { stdio: ["pipe", "ignore", "pipe"] });
+  proc.stderr.on("data", (d) => { sess.stderr = (sess.stderr + d).slice(-2000); });
+  // EPIPE on end()/late writes is normal once ffmpeg has exited; writeExportFrame
+  // attaches its own error listener while a backpressured write is in flight.
+  proc.stdin.on("error", () => { });
+  sess.proc = proc;
+  sess.done = new Promise((res) => proc.on("close", res));
+  return proc;
+}
+/** Write one frame (JPEG or Annex-B NAL) to ffmpeg stdin. If the pipe is full,
+ *  wait for drain — but also reject if ffmpeg exits or the stdin errors, so the
+ *  HTTP request cannot hang forever after a failed encode. */
+function writeExportFrame(sess, body) {
+  const proc = sess.proc;
+  return new Promise((resolve, reject) => {
+    if (!proc || proc.exitCode !== null || proc.killed)
+      return reject(new Error("ffmpeg exited: " + sess.err()));
+
+    let settled = false;
+    const finish = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      proc.off("close", onClose);
+      proc.stdin.off("error", onErr);
+      proc.stdin.off("drain", onDrain);
+      fn(arg);
+    };
+    const onClose = () => finish(reject, new Error("ffmpeg exited: " + (sess.err() || "closed")));
+    const onErr = (e) => finish(reject, new Error(e?.message || "ffmpeg stdin error"));
+    const onDrain = () => finish(resolve);
+
+    proc.once("close", onClose);
+    proc.stdin.once("error", onErr);
+    let ok;
+    try { ok = proc.stdin.write(body); }
+    catch (e) { return finish(reject, e); }
+    if (proc.exitCode !== null)
+      return finish(reject, new Error("ffmpeg exited: " + sess.err()));
+    if (ok) finish(resolve);
+    else proc.stdin.once("drain", onDrain);
+  });
+}
+/* One-pass mux for WebCodecs: H.264 elementary stream on stdin + optional WAV.
+   Use input `-r` (not only `-framerate`): HW encoders stamp AUs with µs-rounded
+   durations (e.g. 33333µs ≈ 1/30), which otherwise become avg_frame_rate
+   1000000/33333. `-r` forces CFR PTS so the MP4 matches project.fps exactly. */
+function startAnnexbEncoder(sess) {
+  const fps = sess.fps;
+  const args = [
+    "-y", "-hide_banner",
+    "-fflags", "+genpts",
+    "-f", "h264", "-r", String(fps), "-i", "pipe:0",
+  ];
+  if (sess.wav) args.push("-i", sess.wav);
+  args.push("-map", "0:v:0", "-c:v", "copy", "-bsf:v", COLOR_BSF, ...COLOR_TAGS);
+  // do not use -shortest: with unset/generated PTS it drops the audio track
+  if (sess.wav) args.push("-map", "1:a:0", "-c:a", "aac", "-b:a", "192k");
+  args.push("-movflags", "+faststart+write_colr", sess.partPath);
+  attachProc(sess, spawn("ffmpeg", args, { stdio: ["pipe", "ignore", "pipe"] }));
+  return sess.proc;
+}
+function cleanupExport(id) {
+  const s = exportSessions.get(id);
+  if (!s) return;
+  exportSessions.delete(id);
+  try { s.proc?.kill(); } catch {}
+  try { fs.rmSync(s.dir, { recursive: true, force: true }); } catch {}
+  if (s.partPath) try { fs.rmSync(s.partPath, { force: true }); } catch {}
+}
+function sweepIdleExports() {
+  const now = Date.now();
+  for (const [id, s] of [...exportSessions]) {
+    if (now - (s.lastTouch || 0) > EXPORT_IDLE_MS) cleanupExport(id);
+  }
+}
+function startExportSweep() {
+  if (exportSweepTimer) return;
+  exportSweepTimer = setInterval(sweepIdleExports, EXPORT_SWEEP_MS);
+}
+function stopExportSweep() {
+  if (!exportSweepTimer) return;
+  clearInterval(exportSweepTimer);
+  exportSweepTimer = null;
+}
+
+/* Agent-requested exports: handed to an open editor tab over SSE, or to a
+   headless browser the server starts (export-jobs.js). */
+const exportJobs = createExportJobs({
+  url: (id) => `http://localhost:${PORT}/?exportJob=${encodeURIComponent(id)}`,
+  broadcast,
+  editors: () => sseClients.size,
+});
+
+/* Static file with HTTP Range support (required for <video> seeking) */
+function serveFile(req, res, filePath) {
+  fs.stat(filePath, (err, st) => {
+    if (err || !st.isFile()) { res.writeHead(404); res.end("Not found"); return; }
+    const ext = path.extname(filePath).toLowerCase();
+    const type = MIME[ext] || "application/octet-stream";
+    const extra = {};
+    if (ext === ".svg") {
+      extra["Content-Security-Policy"] = "sandbox; default-src 'none'; style-src 'unsafe-inline'";
+      extra["X-Content-Type-Options"] = "nosniff";
+    }
+    const range = req.headers.range;
+    if (range) {
+      const m = /bytes=(\d*)-(\d*)/.exec(range);
+      let start = m && m[1] ? parseInt(m[1]) : 0;
+      let end = m && m[2] ? parseInt(m[2]) : st.size - 1;
+      start = Math.min(start, st.size - 1); end = Math.min(end, st.size - 1);
+      res.writeHead(206, {
+        "Content-Type": type, "Accept-Ranges": "bytes",
+        "Content-Range": `bytes ${start}-${end}/${st.size}`,
+        "Content-Length": end - start + 1, ...extra,
+      });
+      fs.createReadStream(filePath, { start, end }).pipe(res);
+    } else {
+      res.writeHead(200, {
+        "Content-Type": type, "Content-Length": st.size,
+        "Accept-Ranges": "bytes", "Cache-Control": "no-cache", ...extra,
+      });
+      fs.createReadStream(filePath).pipe(res);
+    }
+  });
+}
+
+/* ── Server ── */
+const server = http.createServer(async (req, res) => {
+  if (!requestAllowed(req)) {
+    sendJSON(res, 403, { error: "forbidden: request must come from this machine (bad Host or Origin header)" });
+    return;
+  }
+  const url = new URL(req.url, "http://localhost");
+  const p = decodeURIComponent(url.pathname);
+  // never serve dotfiles/dot-directories (.git, .gitignore, …)
+  if (p.split(/[\\/]/).some((seg) => seg.startsWith("."))) { res.writeHead(403); res.end(); return; }
+
+  /* API: project */
+  if (p === "/api/project" && req.method === "GET") {
+    // strip UTF-8 BOM some editors/PowerShell prepend, which breaks JSON.parse
+    try { sendJSON(res, 200, JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(new RegExp("^\\uFEFF"), ""))); }
+    catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+  if (p === "/api/project" && req.method === "PUT") {
+    try {
+      const body = await readBody(req);
+      const data = JSON.parse(body.toString("utf8")); // validate JSON
+      /* Optimistic concurrency: a write whose revision isn't newer than what's
+         on disk was based on a stale read (someone else — the UI or an external
+         tool — saved in between). Reject it instead of clobbering their work.
+         ?force=1 skips the check for deliberate overwrites. */
+      let cur = {};
+      try { cur = JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(new RegExp("^\\uFEFF"), "")); } catch {}
+      if ((data.revision || 0) <= (cur.revision || 0) && url.searchParams.get("force") !== "1") {
+        sendJSON(res, 409, { error: "stale revision — project changed since it was read", revision: cur.revision || 0 });
+        return;
+      }
+      const tmp = PROJECT_FILE + ".tmp";
+      fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+      fs.renameSync(tmp, PROJECT_FILE);
+      sendJSON(res, 200, { ok: true, revision: data.revision });
+    } catch (e) { sendJSON(res, 400, { error: String(e) }); }
+    return;
+  }
+
+  /* API: media library listing */
+  if (p === "/api/media" && req.method === "GET") {
+    try {
+      const files = fs.readdirSync(MEDIA_DIR)
+        .filter((f) => fs.statSync(path.join(MEDIA_DIR, f)).isFile())
+        .map((f) => ({ name: f, src: "/media/" + encodeURIComponent(f), size: fs.statSync(path.join(MEDIA_DIR, f)).size }));
+      sendJSON(res, 200, files);
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+
+  /* API: default-asset library listing (./library/{sfx,elements,svg,fonts}) */
+  if (p === "/api/library" && req.method === "GET") {
+    const dir = url.searchParams.get("dir");
+    if (!LIBRARY_SUBDIRS.includes(dir)) { sendJSON(res, 400, { error: "dir must be one of " + LIBRARY_SUBDIRS.join("|") }); return; }
+    try {
+      const base = path.join(LIBRARY_DIR, dir);
+      const out = [];
+      const walk = (d, rel) => {
+        for (const f of fs.readdirSync(d)) {
+          const full = path.join(d, f), r = rel ? rel + "/" + f : f;
+          const st = fs.statSync(full);
+          if (st.isDirectory()) walk(full, r);
+          else out.push({
+            name: f, rel: r, size: st.size,
+            src: "/library/" + dir + "/" + r.split("/").map(encodeURIComponent).join("/"),
+          });
+        }
+      };
+      walk(base, "");
+      sendJSON(res, 200, out);
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+
+  /* API: upload → saved into ./media */
+  if (p === "/api/upload" && req.method === "POST") {
+    try {
+      let name = safeName(url.searchParams.get("name") || "upload.bin");
+      let target = path.join(MEDIA_DIR, name);
+      let i = 1;
+      const ext = path.extname(name), base = path.basename(name, ext);
+      while (fs.existsSync(target)) target = path.join(MEDIA_DIR, `${base}_${i++}${ext}`);
+      const body = await readBody(req);
+      fs.writeFileSync(target, body);
+      await faststart(target);
+      sendJSON(res, 200, { ok: true, src: "/media/" + encodeURIComponent(path.basename(target)) });
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+
+  /* API: download an HTTPS URL into ./media (same-origin src after import).
+     Body {url}. Rejects http/file/local/private targets. Does not register
+     project media — the client / MCP tool does that, matching /api/upload. */
+  if (p === "/api/import-url" && req.method === "POST") {
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const ac = new AbortController();
+      // IncomingMessage "close" also fires when the request body finishes, which
+      // would abort a successful download. ServerResponse "close" with
+      // writableEnded still false means the client dropped the connection.
+      res.on("close", () => { if (!res.writableEnded) ac.abort(); });
+      const { target, name } = await downloadImportUrl(opts.url, MEDIA_DIR, {
+        signal: ac.signal,
+        // test/rest-api.test.js: HTTP to 127.0.0.1 only (loopback fixture).
+        // Does not disable SSRF for LAN / metadata / other private ranges.
+        allowLoopback: process.env.FABLECUT_TEST_IMPORT_ALLOW_PRIVATE === "1",
+      });
+      await faststart(target);
+      sendJSON(res, 200, { ok: true, src: "/media/" + encodeURIComponent(name), name });
+    } catch (e) {
+      if (e && e.code === "ABORT_ERR") { try { res.end(); } catch {} return; }
+      const msg = e && e.message ? e.message : String(e);
+      const code = /must be https|invalid URL|blocked:|credentials|unsupported|too large|did not return/i.test(msg) ? 400 : 502;
+      sendJSON(res, code, { error: msg });
+    }
+    return;
+  }
+
+  /* API: agent-requested export jobs (see export-jobs.js).
+     POST /api/export/request {range?, profile?, where?} → job; GET /api/export/job?id=
+     polls it; the editor tab claims, reports and finishes it. */
+  if (p === "/api/export/request" && req.method === "POST") {
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH — export needs it" }); return; }
+      if (opts.profile) resolveProfile(String(opts.profile));
+      let revision = null;
+      try { revision = JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(/^\uFEFF/, "")).revision ?? null; } catch {}
+      sendJSON(res, 200, exportJobs.request({ range: opts.range, profile: opts.profile, where: opts.where, revision }));
+    } catch (e) {
+      const code = e.code === 409 || e.code === 400 ? e.code : /^Unknown encoding profile/.test(e.message || "") ? 400 : 500;
+      sendJSON(res, code, { error: String(e.message || e) });
+    }
+    return;
+  }
+  /* API: measure the graded program frame (fablecut_scopes) — a "scopes"
+     job on the export-job queue, polled with GET /api/export/job?id=. */
+  if (p === "/api/scopes/request" && req.method === "POST") {
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      let revision = null;
+      try { revision = JSON.parse(fs.readFileSync(PROJECT_FILE, "utf8").replace(/^/, "")).revision ?? null; } catch {}
+      const ok = typeof opts.time === "number" || (typeof opts.time === "string" && opts.time.trim() !== "" && Number.isFinite(Number(opts.time)));
+      if (opts.time != null && !ok) { sendJSON(res, 400, { error: "time must be seconds ≥ 0" }); return; }
+      const time = opts.time == null ? null : Number(opts.time);
+      const m = opts.matte;
+      if (m != null && (typeof m !== "object" || typeof m.clip !== "string" || !Number.isInteger(m.layer) || m.layer < 0)) {
+        sendJSON(res, 400, { error: "matte must be {clip: \"<clip id>\", layer: <index ≥ 0>}" }); return;
+      }
+      sendJSON(res, 200, exportJobs.request({ kind: "scopes", time, where: opts.where, revision, matte: m || null }));
+    } catch (e) {
+      sendJSON(res, e.code === 409 || e.code === 400 ? e.code : 500, { error: String(e.message || e) });
+    }
+    return;
+  }
+  if (p.startsWith("/api/export/job")) {
+    const id = url.searchParams.get("id") || "";
+    const action = p.slice("/api/export/job".length);
+    let got = false;
+    try {
+      got = action === "" && req.method === "GET" ? exportJobs.get(id)
+        : action === "/ticket" && req.method === "GET" ? exportJobs.ticket(id)
+        : action === "/claim" && req.method === "POST" ? (exportJobs.claim(id) ? { ok: true } : undefined)
+        : action === "/report" && req.method === "POST" ? exportJobs.report(id, JSON.parse((await readBody(req)).toString("utf8") || "{}"))
+        : action === "/cancel" && req.method === "POST" ? exportJobs.cancel(id)
+        : false;
+    } catch (e) { sendJSON(res, 400, { error: String(e.message || e) }); return; }
+    if (got === false) { sendJSON(res, 404, { error: "unknown export job endpoint" }); return; }
+    if (got === undefined) { sendJSON(res, 409, { error: "job is not pending — another tab took it, or it ended" }); return; }
+    if (got === null) { sendJSON(res, 404, { error: "no such export job" }); return; }
+    sendJSON(res, 200, got);
+    return;
+  }
+
+  /* API: fast export (browser-rendered frames → ffmpeg encode) */
+  if (p === "/api/export/ffmpeg" && req.method === "GET") {
+    sendJSON(res, 200, { available: HAS_FFMPEG });
+    return;
+  }
+  if (p === "/api/export/profiles" && req.method === "GET") {
+    try {
+      const detail = url.searchParams.get("detail") === "1";
+      sendJSON(res, 200, listProfilesPublic(detail));
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+  if (p === "/api/export/begin" && req.method === "POST") {
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const mode = opts.mode === "annexb" ? "annexb" : "jpeg";
+      if (mode !== "annexb" && opts.profile) resolveProfile(opts.profile); // 400, not 500, on a bad id — even without ffmpeg
+      if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH" }); return; }
+      sendJSON(res, 200, await beginExport(opts.fps, opts.name, opts.profile, opts.hasAudio !== false, mode, opts));
+    } catch (e) {
+      // an unusable profile is the caller's problem, not a server fault
+      const bad = /^Unknown encoding profile|was rejected by ffmpeg|export fps required|export width\/height required/.test(e.message || "");
+      sendJSON(res, bad ? 400 : 500, { error: String(e.message || e) });
+    }
+    return;
+  }
+  if (p === "/api/export/frame" && req.method === "POST") {
+    const id = url.searchParams.get("id");
+    const sess = exportSessions.get(id);
+    if (!sess) { sendJSON(res, 404, { error: "no such export session" }); return; }
+    try {
+      const body = await readBody(req);
+      if (!body || !body.length) throw new Error("empty frame");
+      if (sess.hasAudio && !sess.wav) {
+        sendJSON(res, 409, { error: "audio mix has not been uploaded yet" });
+        return;
+      }
+      // queue behind any in-flight write so concurrent POSTs cannot interleave stdin
+      const run = async () => {
+        if (!sess.proc) sess.mode === "annexb" ? startAnnexbEncoder(sess) : startEncoder(sess);
+        await writeExportFrame(sess, body);
+      };
+      const writeJob = sess.writeLock.then(run, run);
+      sess.writeLock = writeJob.catch(() => {}); // keep the chain alive after a failed write
+      await writeJob;
+      touchExport(sess);
+      sendJSON(res, 200, { ok: true });
+    } catch (e) {
+      cleanupExport(id);
+      sendJSON(res, 500, { error: String(e.message || e) });
+    }
+    return;
+  }
+  if (p === "/api/export/audio" && req.method === "POST") {
+    const sess = exportSessions.get(url.searchParams.get("id"));
+    if (!sess) { sendJSON(res, 404, { error: "no such export session" }); return; }
+    try {
+      const wavPath = path.join(sess.dir, "audio.wav");
+      fs.writeFileSync(wavPath, await readBody(req));
+      sess.wav = wavPath;
+      touchExport(sess);
+      sendJSON(res, 200, { ok: true });
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+  if (p === "/api/export/end" && req.method === "POST") {
+    const id = url.searchParams.get("id");
+    const sess = exportSessions.get(id);
+    if (!sess) { sendJSON(res, 404, { error: "no such export session" }); return; }
+    try {
+      if (url.searchParams.get("discard")) { cleanupExport(id); sendJSON(res, 200, { ok: true }); return; }
+      touchExport(sess); // keep alive through final mux
+      if (!sess.proc) throw new Error("no frames were uploaded");
+      sess.proc.stdin.end();
+      const code = await sess.done;
+      if (code !== 0) throw new Error("ffmpeg encode failed: " + sess.err());
+      const out = sess.outPath;
+      fs.renameSync(sess.partPath, out);
+      sess.partPath = null; // renamed — cleanup must not delete the finished file
+      cleanupExport(id);
+      sendJSON(res, 200, { ok: true, src: "/exports/" + encodeURIComponent(path.basename(out)) });
+    } catch (e) { cleanupExport(id); sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+
+  /* API: reference analysis → edit blueprint (shots, beats, BPM, energy, music).
+     POST body {src:"/media/ref.mp4", threshold?, music?} runs the analysis
+     (seconds to ~a minute — decode-bound); GET ?src= returns the cached result. */
+  if (p === "/api/analyze" && req.method === "GET") {
+    const src = decodeURIComponent(url.searchParams.get("src") || "");
+    const f = path.join(ANALYSIS_DIR, path.basename(src, path.extname(src)) + ".json");
+    if (!src || !fs.existsSync(f)) { sendJSON(res, 404, { error: "no cached analysis for that src — POST /api/analyze first" }); return; }
+    try { sendJSON(res, 200, JSON.parse(fs.readFileSync(f, "utf8"))); }
+    catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+  if (p === "/api/analyze" && req.method === "POST") {
+    if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH" }); return; }
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      const name = path.basename(decodeURIComponent(opts.src || ""));
+      const file = path.join(MEDIA_DIR, name);
+      if (!name || !fs.existsSync(file)) { sendJSON(res, 404, { error: "src must name an existing file under /media/" }); return; }
+      const bp = await analyze(file, {
+        threshold: opts.threshold,
+        music: opts.music !== false,
+        musicDir: MEDIA_DIR,
+        srcUrl: "/media/" + encodeURIComponent(name),
+      });
+      if (bp.music) bp.music.src = "/media/" + encodeURIComponent(bp.music.name);
+      fs.writeFileSync(path.join(ANALYSIS_DIR, path.basename(name, path.extname(name)) + ".json"),
+        JSON.stringify(bp, null, 2));
+      sendJSON(res, 200, bp);
+    } catch (e) { sendJSON(res, 500, { error: String(e) }); }
+    return;
+  }
+
+  /* API: noise reduction — POST {src:"/media/…"|"/library/…", amount:"light"|"medium"|"strong"}
+     writes a denoised FLAC of the whole file into media/ (reused if it exists)
+     and returns {src, name, duration, channels}. Registering it is the caller's job. */
+  if (p === "/api/denoise" && req.method === "POST") {
+    if (!HAS_FFMPEG) { sendJSON(res, 400, { error: "ffmpeg not found on PATH — noise reduction needs it" }); return; }
+    try {
+      const opts = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+      if (!DENOISE_AMOUNTS.includes(opts.amount)) { sendJSON(res, 400, { error: `amount must be one of ${DENOISE_AMOUNTS.join(", ")}` }); return; }
+      const src = decodeURIComponent(String(opts.src || "").split("?")[0]);
+      const [root, rel] = src.startsWith("/media/") ? [MEDIA_DIR, src.slice(7)]
+        : src.startsWith("/library/") ? [LIBRARY_DIR, src.slice(9)] : [null, null];
+      const file = root && path.normalize(path.join(root, rel));
+      if (!file || !file.startsWith(path.normalize(root + path.sep)) || !fs.existsSync(file)) {
+        sendJSON(res, 404, { error: "src must name an existing file under /media/ or /library/" });
+        return;
+      }
+      const r = await denoiseFile(file, MEDIA_DIR, opts.amount);
+      sendJSON(res, 200, { src: "/media/" + encodeURIComponent(r.name), name: r.name, duration: r.duration, channels: r.channels, cached: r.cached });
+    } catch (e) { sendJSON(res, 500, { error: String(e.message || e) }); }
+    return;
+  }
+
+  /* API: SSE live-reload channel */
+  if (p === "/api/events") {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream", "Cache-Control": "no-store",
+      Connection: "keep-alive",
+    });
+    res.write("data: hello\n\n");
+    sseClients.add(res);
+    req.on("close", () => sseClients.delete(res));
+    return;
+  }
+
+  /* Media files */
+  if (p.startsWith("/media/")) {
+    const file = path.join(MEDIA_DIR, path.basename(p));
+    serveFile(req, res, file);
+    return;
+  }
+
+  /* Finished exports */
+  if (p.startsWith("/exports/")) {
+    serveFile(req, res, path.join(EXPORTS_DIR, path.basename(p)));
+    return;
+  }
+
+  /* Library assets (supports subfolders) */
+  if (p.startsWith("/library/")) {
+    const file = path.normalize(path.join(LIBRARY_DIR, p.slice("/library/".length)));
+    if (!file.startsWith(LIBRARY_DIR + path.sep)) { res.writeHead(403); res.end(); return; }
+    serveFile(req, res, file);
+    return;
+  }
+
+  /* Static app files */
+  let file = p === "/" ? "/index.html" : p;
+  file = path.normalize(path.join(ROOT, file));
+  if (!file.startsWith(ROOT + path.sep)) { res.writeHead(403); res.end(); return; }
+  serveFile(req, res, file);
+});
+
+server.listen(PORT, HOST, () => {
+  console.log(`\n  FableCut running →  http://localhost:${PORT}\n`);
+  if (!["127.0.0.1", "localhost", "::1"].includes(HOST))
+    console.log(`  ⚠ WARNING: HOST=${HOST} exposes the editor (and its file APIs) to the network.\n`);
+  console.log(`  project file : ${PROJECT_FILE}`);
+  console.log(`  media folder : ${MEDIA_DIR}`);
+  console.log(`  library      : ${LIBRARY_DIR} (${LIBRARY_SUBDIRS.join(", ")})`);
+  if (DATA_DIR !== APP_DIR) console.log(`  app files    : ${APP_DIR}`);
+  console.log(`  ffmpeg       : ${HAS_FFMPEG ? "found (fast export + faststart remux on)" : "not found (real-time export only)"}`);
+  const enc = loadEncodeProfiles(true);
+  console.log(`  encode prof. : ${PROFILES_FILE} (${Object.keys(enc.profiles).join(", ")} · default ${enc.default})`);
+  for (const issue of enc.issues || []) console.log(`     ⚠ ${issue}`);
+  console.log("");
+  startExportSweep();
+});
+
+let shuttingDown = false;
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  stopExportSweep();
+  for (const id of [...exportSessions.keys()]) cleanupExport(id);
+  exportJobs.shutdown();
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 2000).unref?.();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);