fablecut 0.0.0-stage → 1.12.1

package/encode-profiles.js

@@ -0,0 +1,302 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   Encoding profiles — user-editable ffmpeg settings for Fast export.
+
+   A profile is a raw ffmpeg argument list plus the things that are NOT ffmpeg
+   arguments: jpegQuality, extension, and optional `color` (output matrix/range).
+   There is deliberately no allow-list — encoding-profiles.json is a local file
+   the user owns, the browser only ever sends a profile *id*, and args are
+   passed to spawn() as an array (no shell), so validating codec names would buy
+   nothing but a smaller set of usable formats. Typos are caught by dryRunProfile
+   against the real ffmpeg build instead, which also knows which encoders it has.
+
+   Export is ONE ffmpeg pass; this module owns the input side (JPEG image2pipe
+   by default, or canvas RGBA when pixelFormat is "rgba") plus color conversion
+   and tags from profile.color; the profile owns everything in between:
+
+     ffmpeg -y -thread_queue_size 64 -f image2pipe -framerate <fps>
+            -c:v mjpeg -i - [-i audio.wav]
+            <jpeg-color vf+tags> <profile args…> <out><extension>
+   `pixelFormat: "rgba"` switches stdin to `-f rawvideo -pix_fmt rgba`.
+   ═══════════════════════════════════════════════════════════════════════════ */
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const PROFILES_FILE = path.join(__dirname, "encoding-profiles.json");
+
+/* Used when encoding-profiles.json is missing or unparseable, so export still
+   works out of the box. Not a merge base: profiles are taken as written. */
+const BUILTIN_ID = "delivery";
+const DEFAULT_COLOR = {
+  matrix: "bt709",
+  primaries: "bt709",
+  trc: "bt709",
+  range: "tv", // tv = limited, pc = full
+};
+const BUILTIN = {
+  label: "Delivery · H.264 balanced",
+  description: "Built-in fallback — good quality and compatibility.",
+  jpegQuality: 0.95,
+  extension: ".mp4",
+  color: { ...DEFAULT_COLOR },
+  args: ["-c:v", "libx264", "-preset", "fast", "-crf", "18", "-pix_fmt", "yuv420p",
+    "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", "-shortest"],
+};
+
+/* Flags the engine injects from profile.color — strip from user args so the
+   JPEG vf out_* and the stream tags cannot disagree. */
+const COLOR_ARG_FLAGS = new Set([
+  "-colorspace", "-color_primaries", "-color_trc", "-color_range",
+]);
+
+let cache = null;
+let cacheMtime = -1;
+
+function normalizeColor(raw) {
+  const c = raw && typeof raw === "object" ? raw : {};
+  const token = (v, fallback) => {
+    const s = String(v == null ? "" : v).trim().toLowerCase();
+    return /^[a-z0-9._-]+$/.test(s) ? s : fallback;
+  };
+  let range = token(c.range, DEFAULT_COLOR.range);
+  if (range === "full") range = "pc";
+  if (range === "limited") range = "tv";
+  if (range !== "tv" && range !== "pc") range = DEFAULT_COLOR.range;
+  const matrix = token(c.matrix ?? c.colorspace, DEFAULT_COLOR.matrix);
+  return {
+    matrix,
+    primaries: token(c.primaries, matrix),
+    trc: token(c.trc ?? c.transfer, matrix),
+    range,
+  };
+}
+
+function stripColorArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (COLOR_ARG_FLAGS.has(args[i])) { i++; continue; } // skip flag + value
+    out.push(args[i]);
+  }
+  return out;
+}
+
+function normalizeProfile(id, raw) {
+  const p = raw && typeof raw === "object" ? raw : {};
+  // a string is split on whitespace as a convenience; the array form is
+  // canonical because it needs no quoting (e.g. -vf drawtext=text='hi')
+  const args = Array.isArray(p.args)
+    ? p.args.map(String)
+    : String(p.args || "").split(/\s+/).filter(Boolean);
+  let ext = String(p.extension || BUILTIN.extension).trim().toLowerCase();
+  if (ext && !ext.startsWith(".")) ext = `.${ext}`;
+  // one suffix only (".mp4") — reject paths, extra dots, empty, or odd chars
+  if (!/^\.[a-z0-9]+$/.test(ext)) ext = BUILTIN.extension;
+  const q = Number(p.jpegQuality);
+  return {
+    id,
+    label: String(p.label || id),
+    description: String(p.description || p.desc || ""),
+    jpegQuality: q >= 0.1 && q <= 1 ? q : BUILTIN.jpegQuality,
+    extension: ext,
+    color: normalizeColor(p.color),
+    args,
+  };
+}
+
+function profilesFileMtime() {
+  try { return fs.statSync(PROFILES_FILE).mtimeMs; } catch { return 0; }
+}
+
+function loadEncodeProfiles(force) {
+  /* mtime check instead of a plain memo: the MCP server is long-lived and has
+     no file watcher, so a cache-only read would serve stale profiles forever */
+  const mtime = profilesFileMtime();
+  if (cache && !force && mtime === cacheMtime) return cache;
+
+  let file = null;
+  const issues = [];
+  try {
+    if (fs.existsSync(PROFILES_FILE))
+      file = JSON.parse(fs.readFileSync(PROFILES_FILE, "utf8").replace(/^\uFEFF/, ""));
+    else issues.push(`${path.basename(PROFILES_FILE)} not found — using the built-in profile`);
+  } catch (e) {
+    issues.push(`${path.basename(PROFILES_FILE)} could not be parsed (${e.message}) — using the built-in profile`);
+  }
+
+  const profiles = {};
+  if (file?.profiles && typeof file.profiles === "object")
+    for (const [id, raw] of Object.entries(file.profiles)) profiles[id] = normalizeProfile(id, raw);
+  for (const [id, p] of Object.entries(profiles))
+    if (!p.args.length) issues.push(`profile "${id}" has no args — ffmpeg will pick its own defaults`);
+  if (!Object.keys(profiles).length) profiles[BUILTIN_ID] = normalizeProfile(BUILTIN_ID, BUILTIN);
+
+  let defaultId = typeof file?.default === "string" ? file.default : BUILTIN_ID;
+  if (!profiles[defaultId]) {
+    const first = Object.keys(profiles)[0];
+    if (file?.default) issues.push(`default "${file.default}" is not a defined profile — using ${first}`);
+    defaultId = first;
+  }
+
+  cache = { default: defaultId, profiles, issues };
+  cacheMtime = mtime;
+  return cache;
+}
+
+function invalidateEncodeProfiles() {
+  cache = null;
+  cacheMtime = -1;
+}
+
+function resolveProfile(id) {
+  const cfg = loadEncodeProfiles();
+  const pid = id || cfg.default;
+  const p = cfg.profiles[pid];
+  if (!p) throw new Error(`Unknown encoding profile "${pid}"`);
+  return p;
+}
+
+function profileSummary(p, max = 120) {
+  const s = (p.args || []).join(" ") || "(no args — ffmpeg defaults)";
+  return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+
+function listProfilesPublic(detail) {
+  const cfg = loadEncodeProfiles();
+  const out = {
+    default: cfg.default, profiles: {},
+    file: path.basename(PROFILES_FILE),
+    issues: cfg.issues || [],
+  };
+  for (const [id, p] of Object.entries(cfg.profiles)) {
+    // jpegQuality + color are needed by the UI / agents — always included
+    const base = {
+      label: p.label,
+      description: p.description,
+      jpegQuality: p.jpegQuality,
+      extension: p.extension,
+      color: p.color,
+      summary: profileSummary(p),
+    };
+    out.profiles[id] = detail ? { ...base, args: p.args } : base;
+  }
+  return out;
+}
+
+/* Canvas RGBA is full-range BT.709-ish (sRGB). JPEG/JFIF is full-range BT.601.
+   Convert to the profile's output matrix/range and tag the stream, otherwise
+   x264 emits bt470bg/pc/unknown and players do the wrong YUV→RGB conversion.
+   Independent of -pix_fmt (420 vs 422/10-bit). */
+function inputColorVf(color, inMatrix) {
+  const c = color || DEFAULT_COLOR;
+  const matrix = inMatrix === "bt601" ? "bt601" : "bt709";
+  // Primaries / transfer are stamped on the frames too: frame colour
+  // properties win over the -color_* flags added below, so without this the
+  // file is tagged primaries/transfer "unknown". setparams (not scale's
+  // out_primaries / out_transfer, which need FFmpeg 7.1+) works on older builds.
+  return `scale=in_range=full:in_color_matrix=${matrix}:out_range=${c.range}:out_color_matrix=${c.matrix},` +
+    `setparams=color_primaries=${c.primaries}:color_trc=${c.trc}`;
+}
+function jpegColorTags(color) {
+  const c = color || DEFAULT_COLOR;
+  return [
+    "-colorspace", c.matrix,
+    "-color_primaries", c.primaries,
+    "-color_trc", c.trc,
+    "-color_range", c.range,
+  ];
+}
+
+function withInputColor(profile, inMatrix) {
+  const color = profile.color || DEFAULT_COLOR;
+  const vf = inputColorVf(color, inMatrix);
+  const args = stripColorArgs((profile.args || []).slice());
+  const vfAt = args.indexOf("-vf");
+  if (vfAt >= 0 && args[vfAt + 1] != null) args[vfAt + 1] = `${vf},${args[vfAt + 1]}`;
+  else args.unshift("-vf", vf);
+  args.push(...jpegColorTags(color));
+  return args;
+}
+
+/* The single export pass. Fast export sends JPEG image2pipe by default;
+   `pixelFormat: "rgba"` is uncompressed canvas frames. Audio mix is on disk
+   before spawn. */
+function buildExportArgs(profile, { fps, wavPath, outPath, pixelFormat, width, height } = {}) {
+  const args = ["-y", "-hide_banner"];
+  const raw = pixelFormat === "rgba";
+  if (raw) {
+    const w = Math.max(2, width | 0), h = Math.max(2, height | 0);
+    // Small queue: each raw frame is width×height×4 bytes (1080p ≈ 8 MiB).
+    args.push(
+      "-thread_queue_size", "8",
+      "-f", "rawvideo", "-pix_fmt", "rgba",
+      "-s", `${w}x${h}`, "-framerate", String(fps), "-i", "-",
+    );
+  } else {
+    args.push(
+      "-thread_queue_size", "64",
+      "-f", "image2pipe", "-framerate", String(fps), "-c:v", "mjpeg", "-i", "-",
+    );
+  }
+  if (wavPath) args.push("-i", wavPath);
+  args.push(...withInputColor(profile, raw ? "bt709" : "bt601"), outPath);
+  return args;
+}
+
+const DRY_RUN_TIMEOUT_MS = 15_000;
+
+/* Run the profile's args once against a synthetic input before the browser
+   renders anything. Without this a typo (or an encoder this ffmpeg build lacks)
+   would only surface when ffmpeg exits — i.e. after every frame was rendered.
+   Async spawn so /api/export/begin does not block the event loop. */
+function dryRunProfile(profile, { fps = 30, hasAudio = true } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fablecut-dry-"));
+  const out = path.join(dir, `probe${profile.extension}`);
+  const args = ["-y", "-hide_banner", "-f", "lavfi",
+    "-i", `color=c=black:s=64x64:r=${fps}:d=0.1`];
+  if (hasAudio) args.push("-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo");
+  args.push("-t", "0.1", ...withInputColor(profile, "bt709"), out);
+  return new Promise((resolve) => {
+    let stderr = "";
+    let settled = false;
+    let proc;
+    let timer;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch { }
+      resolve(result);
+    };
+    try {
+      proc = spawn("ffmpeg", args, { stdio: ["ignore", "ignore", "pipe"] });
+    } catch (e) {
+      finish({ ok: false, error: e.message || String(e) });
+      return;
+    }
+    timer = setTimeout(() => {
+      try { proc.kill(); } catch { }
+      finish({ ok: false, error: `ffmpeg dry-run timed out after ${DRY_RUN_TIMEOUT_MS}ms` });
+    }, DRY_RUN_TIMEOUT_MS);
+    proc.on("error", (e) => finish({ ok: false, error: e.message || String(e) }));
+    proc.stderr.on("data", (d) => { stderr = (stderr + d).slice(-4000); });
+    proc.on("close", (code) => {
+      if (code === 0) { finish({ ok: true }); return; }
+      const lines = stderr.trim().split("\n").filter(Boolean);
+      finish({ ok: false, error: lines.slice(-3).join(" · ") || `ffmpeg exited ${code}` });
+    });
+  });
+}
+
+module.exports = {
+  PROFILES_FILE,
+  DEFAULT_COLOR,
+  loadEncodeProfiles,
+  invalidateEncodeProfiles,
+  resolveProfile,
+  listProfilesPublic,
+  profileSummary,
+  buildExportArgs,
+  dryRunProfile,
+};

package/encoding-profiles.json

@@ -0,0 +1,68 @@
+{
+  "default": "delivery",
+  "profiles": {
+    "draft": {
+      "label": "Draft · H.264 fast",
+      "description": "Quick preview — smaller file, faster encode.",
+      "jpegQuality": 0.85,
+      "extension": ".mp4",
+      "color": { "matrix": "bt709", "primaries": "bt709", "trc": "bt709", "range": "tv" },
+      "args": [
+        "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p",
+        "-c:a", "aac", "-b:a", "128k",
+        "-movflags", "+faststart", "-shortest"
+      ]
+    },
+    "delivery": {
+      "label": "Delivery · H.264 balanced",
+      "description": "Default export — good quality and compatibility.",
+      "jpegQuality": 0.95,
+      "extension": ".mp4",
+      "color": { "matrix": "bt709", "primaries": "bt709", "trc": "bt709", "range": "tv" },
+      "args": [
+        "-c:v", "libx264", "-preset", "fast", "-crf", "18", "-pix_fmt", "yuv420p",
+        "-c:a", "aac", "-b:a", "192k",
+        "-movflags", "+faststart", "-shortest"
+      ]
+    },
+    "hq": {
+      "label": "High quality · H.264 4:2:2 10-bit slow",
+      "description": "Best H.264 quality — High 4:2:2 profile, 10-bit. Slower encode, larger file; for mastering and grading round-trips, not for browser or QuickTime playback.",
+      "jpegQuality": 0.98,
+      "extension": ".mp4",
+      "color": { "matrix": "bt709", "primaries": "bt709", "trc": "bt709", "range": "tv" },
+      "args": [
+        "-c:v", "libx264", "-preset", "slow", "-crf", "16", "-pix_fmt", "yuv422p10le",
+        "-c:a", "aac", "-b:a", "256k",
+        "-movflags", "+faststart", "-shortest"
+      ]
+    },
+    "broadcast1080i50": {
+      "label": "Broadcast · 1080i50 MOV",
+      "description": "Interlaced H.264 for broadcast-style delivery. Set the project to 1920x1080 @ 25fps (progressive); the filter chain builds the 50i field order.",
+      "jpegQuality": 0.98,
+      "extension": ".mov",
+      "color": { "matrix": "bt709", "primaries": "bt709", "trc": "bt709", "range": "tv" },
+      "args": [
+        "-c:v", "libx264", "-preset", "fast", "-crf", "18", "-pix_fmt", "yuv420p",
+        "-g", "10", "-maxrate", "60M", "-bufsize", "70M",
+        "-x264opts", "open_gop=0:interlaced=1:me=hex:subme=2:cabac=1:no-deblock:analyse=all:8x8dct=1:bframes=2:weightp=0:sliced-threads:level=41",
+        "-vf", "scale=1920:1080:interl=-1,fps=50,tinterlace=interleave_top:bypass_il",
+        "-c:a", "aac", "-b:a", "384k", "-ar", "48000", "-strict", "-2",
+        "-shortest"
+      ]
+    },
+    "prores422": {
+      "label": "ProRes 422 HQ · MOV",
+      "description": "Mezzanine / round-trip master. Large files, edits well anywhere.",
+      "jpegQuality": 1,
+      "extension": ".mov",
+      "color": { "matrix": "bt709", "primaries": "bt709", "trc": "bt709", "range": "tv" },
+      "args": [
+        "-c:v", "prores_ks", "-profile:v", "3", "-pix_fmt", "yuv422p10le",
+        "-c:a", "pcm_s16le",
+        "-shortest"
+      ]
+    }
+  }
+}

package/export-jobs.js

@@ -0,0 +1,163 @@
+/* Agent-requested exports (POST /api/export/request, MCP fablecut_export).
+
+   The compositor lives in the browser, so an export job is handed to an
+   editor tab: an open one gets it over SSE, otherwise a headless Chrome /
+   Edge is started on `/?exportJob=<id>` and closed when the job ends. The tab
+   claims the job, renders it with the normal Fast export, and reports
+   progress and the finished file back here. A job is
+     pending → running → done | failed | cancelled
+   and stays readable for an hour after it ends. Zero dependencies. */
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const PENDING_TAB_MS = 20_000;       // an open tab answers SSE within a beat
+const PENDING_HEADLESS_MS = 90_000;  // a cold browser has to boot and load media
+const STALL_MS = 120_000;            // a running tab reports at least every few seconds
+const KEEP_MS = 60 * 60 * 1000;
+
+/** A Chromium-family browser to run headless: FABLECUT_CHROME, else the usual
+ *  Chrome / Edge / Chromium install paths for this platform. Null if none. */
+function findBrowser(env = process.env) {
+  if (env.FABLECUT_CHROME) return fs.existsSync(env.FABLECUT_CHROME) ? env.FABLECUT_CHROME : null;
+  const candidates = [];
+  if (process.platform === "win32") {
+    const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean);
+    for (const r of roots) {
+      candidates.push(path.join(r, "Google", "Chrome", "Application", "chrome.exe"));
+      candidates.push(path.join(r, "Microsoft", "Edge", "Application", "msedge.exe"));
+      candidates.push(path.join(r, "Chromium", "Application", "chrome.exe"));
+    }
+  } else if (process.platform === "darwin") {
+    candidates.push("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium");
+  } else {
+    for (const name of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"]) {
+      const r = spawnSync("which", [name], { encoding: "utf8" });
+      if (r.status === 0 && r.stdout.trim()) candidates.push(r.stdout.trim());
+    }
+  }
+  return candidates.find((p) => { try { return fs.statSync(p).isFile(); } catch { return false; } }) || null;
+}
+
+/** opts: {url(id) → page to open headless, broadcast(event, data), editors() → open tab count} */
+function createExportJobs(opts) {
+  const jobs = new Map();
+  let timer = null;
+  const isEnded = (j) => j.status === "done" || j.status === "failed" || j.status === "cancelled";
+  const view = (j) => ({
+    id: j.id, kind: j.kind, status: j.status, via: j.via, range: j.range, profile: j.profile || null,
+    time: j.time ?? null, progress: j.progress, src: j.src || null, result: j.result || null, error: j.error || null,
+    created: j.created, updated: j.updated,
+  });
+
+  function closeBrowser(j) {
+    const b = j.browser;
+    if (!b) return;
+    j.browser = null;
+    try { b.proc.kill(); } catch {}
+    // The profile dir is locked until the browser exits.
+    const rm = (n) => fs.rm(b.profileDir, { recursive: true, force: true }, (err) => {
+      if (err && n > 0) setTimeout(() => rm(n - 1), 1000);
+    });
+    b.proc.once("exit", () => rm(5));
+    setTimeout(() => rm(5), 3000);
+  }
+  function end(j, status, fields = {}) {
+    if (isEnded(j)) return;
+    Object.assign(j, fields, { status, updated: Date.now() });
+    closeBrowser(j);
+  }
+  function sweep() {
+    const now = Date.now();
+    for (const j of jobs.values()) {
+      if (j.status === "pending" && now - j.created > (j.via === "headless" ? PENDING_HEADLESS_MS : PENDING_TAB_MS))
+        end(j, "failed", { error: j.via === "headless"
+          ? "the headless browser never picked up the job (it may have failed to start or to load the editor)"
+          : "no editor tab picked up the job — is it busy exporting? Retry with where:\"headless\"" });
+      else if (j.status === "running" && now - j.updated > STALL_MS)
+        end(j, "failed", { error: "the editor stopped reporting progress (tab closed or browser crashed)" });
+      else if (isEnded(j) && now - j.updated > KEEP_MS) jobs.delete(j.id);
+    }
+    if (![...jobs.values()].some((j) => !isEnded(j)) && timer) { clearInterval(timer); timer = null; }
+  }
+  function launch(j) {
+    const exe = findBrowser();
+    if (!exe) throw Object.assign(new Error("no editor tab is open and no Chrome / Edge was found to export headless — " +
+      "open the editor in a browser, or set FABLECUT_CHROME to a Chromium-based browser"), { code: 409 });
+    const profileDir = fs.mkdtempSync(path.join(os.tmpdir(), "fablecut-export-"));
+    const proc = spawn(exe, [
+      "--headless=new", `--user-data-dir=${profileDir}`, "--no-first-run", "--no-default-browser-check",
+      "--disable-extensions", "--mute-audio", "--autoplay-policy=no-user-gesture-required",
+      "--disable-background-timer-throttling", "--disable-renderer-backgrounding",
+      "--disable-backgrounding-occluded-windows", "--window-size=1600,900",
+      opts.url(j.id),
+    ], { stdio: "ignore", windowsHide: true });
+    j.browser = { proc, profileDir };
+    proc.on("error", (e) => end(j, "failed", { error: "could not start the headless browser: " + e.message }));
+    proc.on("exit", () => { if (j.browser) { j.browser = null; if (!isEnded(j)) end(j, "failed", { error: "the headless browser exited before the export finished" }); } });
+  }
+
+  return {
+    /** Queue an export. where: auto (open tab, else headless) · tab · headless.
+     *  kind "scopes" measures one still at `time` instead (fablecut_scopes). */
+    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null }) {
+      if (!["auto", "tab", "headless"].includes(where)) throw Object.assign(new Error("where must be auto, tab or headless"), { code: 400 });
+      if (kind !== "export" && kind !== "scopes") throw Object.assign(new Error("kind must be export or scopes"), { code: 400 });
+      if (time != null && !(Number.isFinite(time) && time >= 0)) throw Object.assign(new Error("time must be seconds ≥ 0"), { code: 400 });
+      if (range != null && range !== "entire" && range !== "in-out") throw Object.assign(new Error("range must be \"entire\" or \"in-out\""), { code: 400 });
+      const busy = [...jobs.values()].find((j) => !isEnded(j));
+      if (busy) throw Object.assign(new Error(`${busy.kind === "scopes" ? "scope reading" : "export"} ${busy.id} is still ${busy.status} — wait for it, or cancel it`), { code: 409 });
+      const tabs = opts.editors();
+      if (where === "tab" && !tabs) throw Object.assign(new Error("no editor tab is open — open the editor, or use where:\"headless\""), { code: 409 });
+      const now = Date.now();
+      const j = {
+        id: "x_" + Math.random().toString(36).slice(2, 10), kind, status: "pending", progress: 0,
+        range: range || null, profile: profile || null, time: time ?? null, revision: Number.isFinite(revision) ? revision : null,
+        matte: kind === "scopes" && matte ? { clip: String(matte.clip), layer: matte.layer } : null,
+        via: where === "headless" || (where === "auto" && !tabs) ? "headless" : "tab",
+        created: now, updated: now,
+      };
+      if (j.via === "headless") launch(j);
+      jobs.set(j.id, j);
+      if (j.via === "tab") opts.broadcast("export", JSON.stringify(this.ticket(j.id)));
+      if (!timer) { timer = setInterval(sweep, 1000); timer.unref?.(); }
+      return view(j);
+    },
+    get(id) { const j = jobs.get(id); return j ? view(j) : null; },
+    /** What a tab needs to run the job (headless pages fetch it by id). */
+    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, status: j.status } : null; },
+    /** First tab to claim a pending job runs it. */
+    claim(id) {
+      const j = jobs.get(id);
+      if (!j || j.status !== "pending") return false;
+      j.status = "running"; j.updated = Date.now();
+      return true;
+    },
+    /** Progress / result from the running tab. Returns {cancel} so a cancel reaches it. */
+    report(id, { progress, status, src, result, error } = {}) {
+      const j = jobs.get(id);
+      if (!j) return null;
+      if (j.status === "cancelled") return { cancel: true };
+      if (j.status !== "running") return { cancel: false };
+      j.updated = Date.now();
+      if (Number.isFinite(progress)) j.progress = Math.max(0, Math.min(1, progress));
+      if (status === "done") end(j, "done", { progress: 1, src: String(src || ""), result: result && typeof result === "object" ? result : null });
+      else if (status === "failed") end(j, "failed", { error: String(error || "export failed") });
+      return { cancel: false };
+    },
+    cancel(id) {
+      const j = jobs.get(id);
+      if (!j) return null;
+      // A running tab hears about it on its next report and stops; pending just ends.
+      if (!isEnded(j)) end(j, "cancelled", { error: "cancelled" });
+      return view(j);
+    },
+    shutdown() { for (const j of jobs.values()) closeBrowser(j); if (timer) clearInterval(timer); },
+  };
+}
+
+module.exports = { createExportJobs, findBrowser };

package/favicon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#7b6cff"/>
+      <stop offset="1" stop-color="#4f8cff"/>
+    </linearGradient>
+  </defs>
+  <rect width="512" height="512" rx="112" fill="url(#g)"/>
+  <!-- play triangle sliced by a cut (the "Cut" in FableCut) -->
+  <g fill="#fff">
+    <path d="M188 146 L244 176 L244 336 L188 366 Z"/>
+    <path d="M268 189 L392 256 L268 323 Z"/>
+  </g>
+</svg>