playrig 0.0.0-stage → 0.1.0

package/editions/pr/plugin/index.js

@@ -0,0 +1,710 @@
+// Playrig (UXP): runs JavaScript jobs dropped into <root>/inbox and writes results to <root>/out/<id>/.
+// Mirrors every job into <project folder>/EDIT_LOGS/ so the project can move between systems.
+// SPIKE: Premiere DOM calls marked "unverified" in README.md have not been run against a real Premiere yet.
+const ppro = require("premierepro");
+const fs = require("fs");
+const os = require("os");
+const uxp = require("uxp");
+
+const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_JOBS_SHOWN = 50;
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+
+const S = { jobs: [], on: false, busy: false, timer: null, seq: 0, unsynced: [] };
+const $ = (id) => document.getElementById(id);
+
+// ------------------------------------------------------------ settings and paths
+// Settings saved under the former name ("pb.*", Premiere Bridge) are still read, so an upgrade keeps its folder and options.
+const getSet = (k, d) => { try { let v = localStorage.getItem("pp." + k); if (v === null) v = localStorage.getItem("pb." + k); return v === null ? d : v; } catch (e) { return d; } };
+const setSet = (k, v) => { try { localStorage.setItem("pp." + k, String(v)); } catch (e) { } };
+// UXP file stats expose the modified time as `mtime` (milliseconds), not `mtimeMs`.
+const mtimeOf = (st) => Number(st.mtime !== undefined ? (st.mtime instanceof Date ? st.mtime.getTime() : st.mtime) : st.mtimeMs) || 0;
+const norm = (p) => String(p).replace(/\\/g, "/").replace(/\/+$/, "");
+// Default <Documents>/Playrig/pr; an existing <Documents>/Premiere Bridge keeps being used until the new folder exists (see pickDefaultRoot).
+const NEW_ROOT = () => os.homedir() + "/Documents/Playrig/pr", LEGACY_ROOT = () => os.homedir() + "/Documents/Premiere Bridge";
+let defaultRoot = NEW_ROOT();
+const root = () => norm(getSet("root", "") || defaultRoot);
+async function pickDefaultRoot() { if (!(await exists(NEW_ROOT() + "/inbox")) && (await exists(LEGACY_ROOT() + "/inbox"))) defaultRoot = LEGACY_ROOT(); showRoot(); }
+const sub = (n) => root() + "/" + n;
+const dirname = (p) => norm(p).replace(/\/[^/]*$/, "");
+const basename = (p) => norm(p).replace(/^.*\//, "");
+
+function stamp() {
+  const d = new Date(), p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+// ------------------------------------------------------------ files
+async function exists(p) { try { await fs.lstat(p); return true; } catch (e) { return false; } }
+async function mkdirs(p) {
+  const parts = norm(p).split("/");
+  let cur = "";
+  for (const part of parts) {
+    cur = cur ? cur + "/" + part : part || "/";
+    if (!part) continue;
+    if (!(await exists(cur))) { try { await fs.mkdir(cur); } catch (e) { if (!(await exists(cur))) throw e; } }
+  }
+}
+const readText = (p) => fs.readFile(p, { encoding: "utf-8" });
+async function writeText(p, s) { await fs.writeFile(p, s, { encoding: "utf-8" }); }
+async function writeAtomic(p, s) {
+  const tmp = p + ".tmp";
+  await writeText(tmp, s);
+  if (await exists(p)) await fs.unlink(p);
+  await fs.rename(tmp, p);
+}
+async function appendText(p, s) { await writeText(p, ((await exists(p)) ? await readText(p) : "") + s); }
+async function moveFile(src, destDir) {
+  const dest = destDir + "/" + basename(src);
+  if (await exists(dest)) await fs.unlink(dest);
+  await fs.rename(src, dest);
+  return dest;
+}
+async function copyFile(src, destDir) {
+  await mkdirs(destDir);
+  const dest = destDir + "/" + basename(src);
+  if (await exists(dest)) await fs.unlink(dest);
+  await fs.copyFile(src, dest);
+}
+
+// ------------------------------------------------------------ UI
+function setStatus(t) {
+  $("status").textContent = t;
+  $("dot").className = "dot" + (/^Running/.test(t) ? " run" : /^Error/.test(t) ? " err" : S.on ? " on" : "");
+  $("status").style.color = /^Error/.test(t) ? "#f85149" : "#a0a0a0";
+}
+let msgTimer = null;
+function uiLog(t) {
+  $("msg").textContent = t;
+  clearTimeout(msgTimer);
+  if (t && !/fail|cannot|could not|error/i.test(t)) msgTimer = setTimeout(() => { $("msg").textContent = ""; }, 12000);   // info fades, problems stay
+}
+
+// ------------------------------------------------------------ jobs table (per project)
+// The list shows the jobs of the project that is open now, read from <project folder>/EDIT_LOGS/results/ (the same files the project
+// log keeps), so switching projects switches the list and a project's history travels with it. Rows open a detail window.
+const STATUS_ICON = { ok: "status-ok", error: "status-error", rejected: "status-rejected", timeout: "status-timeout" };
+const humanName = (id) => { const m = /^\d{8}-\d{6}-(.+)$/.exec(String(id)); return String(m ? m[1] : id).replace(/[-_]+/g, " ").trim() || String(id); };
+function fmtWhen(iso) {
+  const d = new Date(iso); if (isNaN(d.getTime())) return "";
+  const p = (n) => String(n).padStart(2, "0");
+  return p(d.getDate()) + "-" + p(d.getMonth() + 1) + "-" + String(d.getFullYear()).slice(2) + " " + p(d.getHours()) + ":" + p(d.getMinutes());   // DD-MM-YY HH:MM
+}
+const fmtDur = (ms) => (ms === undefined || ms === null) ? "" : (ms < 1000 ? ms + " ms" : (ms / 1000).toFixed(ms < 10000 ? 1 : 0) + " s");
+function rowFromResult(r, src) {
+  const declared = r.action && ACTIONS[r.action] ? r.action : null;
+  const action = r.status === "rejected" ? "job.rejected" : (declared || inferAction(src, r.id));
+  const inferred = r.status !== "rejected" && !(declared && r.actionSource === "declared");
+  return { id: r.id, status: r.status || "unknown", startedAt: r.startedAt, durationMs: r.durationMs, action, actionInferred: inferred, name: actionInfo(action).label,
+    description: r.description || null, error: r.error && r.error.message ? r.error.message : null, firstLog: (r.log && r.log.length) ? String(r.log[0]).slice(0, 120) : null,
+    snapshots: (r.snapshots || []).filter((x) => x.ok).length, moved: r.organized && r.organized.moved ? r.organized.moved.length : 0 };
+}
+function tooltipFor(j) {
+  const info = actionInfo(j.action), t = [];
+  t.push(j.description ? j.description : info.summary);
+  t.push("Action: " + info.label + (j.actionInferred ? " (inferred from the script)" : ""));
+  t.push("Result: " + j.status + (j.durationMs !== undefined ? " in " + fmtDur(j.durationMs) : ""));
+  if (j.error) t.push("Error: " + j.error);
+  if (j.snapshots) t.push(j.snapshots + " frame" + (j.snapshots === 1 ? "" : "s") + " exported");
+  if (j.moved) t.push(j.moved + " item" + (j.moved === 1 ? "" : "s") + " filed into bins");
+  t.push("Click for details");
+  return t.join("\n");
+}
+function renderJobs() {
+  const box = $("jobs");
+  box.textContent = "";
+  $("jobsCount").textContent = S.jobTotal ? (S.jobTotal > S.jobs.length ? "latest " + S.jobs.length + " of " + S.jobTotal : S.jobTotal + (S.jobTotal === 1 ? " job" : " jobs")) : "";
+  if (!S.jobs.length) {
+    const e = document.createElement("div"); e.className = "empty";
+    e.textContent = S.projectPath === "" ? "Save the project to keep its job history with it." : "No jobs yet in this project.";
+    box.appendChild(e); return;
+  }
+  for (const j of S.jobs) {
+    const row = document.createElement("div"); row.className = "job"; row.setAttribute("title", tooltipFor(j));
+    const st = document.createElement("div"); st.className = "c-status";
+    const ic = document.createElement("img"); ic.setAttribute("src", "icons/" + (STATUS_ICON[j.status] || "status-unknown") + ".svg"); ic.setAttribute("width", "14"); ic.setAttribute("height", "14");
+    const word = document.createElement("span"); word.className = "st-" + (STATUS_ICON[j.status] ? j.status : "unknown"); word.textContent = j.status;
+    st.append(ic, word);
+    const nm = document.createElement("div"); nm.className = "c-name"; nm.textContent = j.name;
+    const wh = document.createElement("div"); wh.className = "c-when"; wh.textContent = fmtWhen(j.startedAt);
+    row.append(st, nm, wh);
+    row.addEventListener("click", () => openJobDetail(j));
+    box.appendChild(row);
+  }
+}
+// add a job that just ran (or was rejected) in the project that is open now
+function pushJob(row) {
+  if (typeof row === "string") row = { id: row, status: arguments[1], startedAt: new Date().toISOString(), name: humanName(row) };
+  row.projectPath = S.projectPath;
+  S.sessionJobs = (S.sessionJobs || []).filter((x) => x.id !== row.id); S.sessionJobs.unshift(row); S.sessionJobs.length = Math.min(S.sessionJobs.length, 100);
+  const existed = S.jobs.some((x) => x.id === row.id);
+  S.jobs = S.jobs.filter((x) => x.id !== row.id); S.jobs.unshift(row); S.jobTotal = (S.jobTotal || 0) + (existed ? 0 : 1);
+  S.jobs.length = Math.min(S.jobs.length, MAX_JOBS_SHOWN);
+  renderJobs();
+}
+async function loadRecentJobs() {
+  const path = S.projectPath || "", rows = [];
+  if (path) {
+    const dir = dirname(path) + "/EDIT_LOGS/results";
+    try {
+      for (const name of await fs.readdir(dir)) {
+        if (!ID_RE.test(name)) continue;
+        try {
+          const r = JSON.parse(await readText(dir + "/" + name + "/result.json"));
+          let src = ""; if (!(r.action && ACTIONS[r.action])) { try { src = await readText(dirname(path) + "/EDIT_LOGS/jobs/" + name + ".js"); } catch (e) { } }   // older jobs: infer from the script
+          rows.push(rowFromResult(r, src));
+        } catch (e) { }
+      }
+    } catch (e) { }
+  }
+  for (const j of (S.sessionJobs || [])) if (j.projectPath === path && !rows.some((x) => x.id === j.id)) rows.push(j);   // e.g. rejected jobs, or an unsaved project
+  rows.sort((a, b) => (Date.parse(b.startedAt) || 0) - (Date.parse(a.startedAt) || 0));
+  S.jobTotal = rows.length;
+  S.jobs = rows.slice(0, MAX_JOBS_SHOWN);
+  renderJobs();
+}
+// which project is open? Reload the list when it changes.
+async function watchProject() {
+  try {
+    const p = await activeProject();
+    const path = p ? String(p.path || "") : "", name = p ? String(p.name || "").replace(/\.prproj$/i, "") : "";
+    $("projName").textContent = name || "No project open";
+    if (path !== S.projectPath) { S.projectPath = path; await loadRecentJobs(); }
+  } catch (e) { }
+}
+
+// job detail window
+function el(tag, cls, text) { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined && text !== null) e.textContent = text; return e; }
+async function openJobDetail(j) {
+  const body = $("jobDetail"); body.textContent = "";
+  let r = j.result || null;
+  const ws = S.projectPath ? dirname(S.projectPath) + "/EDIT_LOGS" : null;
+  if (!r && ws) { try { r = JSON.parse(await readText(ws + "/results/" + j.id + "/result.json")); } catch (e) { } }
+  r = r || {};
+  const head = el("div", "jd-head"), ic = document.createElement("img");
+  ic.setAttribute("src", "icons/" + (STATUS_ICON[j.status] || "status-unknown") + ".svg"); ic.setAttribute("width", "18"); ic.setAttribute("height", "18");
+  head.append(ic, el("div", "jd-title", j.name), el("div", "jd-status st-" + (STATUS_ICON[j.status] ? j.status : "unknown"), j.status));
+  body.appendChild(head);
+  const kv = (k, v) => { if (v === undefined || v === null || v === "") return; const row = el("div", "jd-row"); row.append(el("div", "jd-k", k), el("div", "jd-v", v)); body.appendChild(row); };
+  const info = actionInfo(j.action);
+  kv("What happened", r.description || j.description || info.summary);
+  kv("Action", info.label + (j.actionInferred ? "  (inferred from the script; a job can declare it with // @action)" : ""));
+  kv("Job id", j.id);
+  kv("Started", fmtWhen(j.startedAt) + (j.durationMs !== undefined ? "   (" + fmtDur(j.durationMs) + ")" : ""));
+  kv("Project", r.project && r.project.path ? r.project.path : (S.projectPath || "(unsaved)"));
+  kv("Premiere", r.appVersion);
+  if (r.error) {
+    body.appendChild(el("div", "jd-h", "Error"));
+    body.appendChild(el("div", "jd-pre jd-err", r.error.message + (r.error.line ? "\n(line " + r.error.line + ")" : "") + (r.error.source ? "\n> " + String(r.error.source).trim() : "")));
+  }
+  if (r.log && r.log.length) { body.appendChild(el("div", "jd-h", "Log (" + r.log.length + " line" + (r.log.length === 1 ? "" : "s") + ")")); body.appendChild(el("div", "jd-pre", r.log.slice(0, 200).join("\n") + (r.log.length > 200 ? "\n... " + (r.log.length - 200) + " more" : ""))); }
+  const frames = (r.snapshots || []).filter((x) => x.ok);
+  if (frames.length) { body.appendChild(el("div", "jd-h", "Frames exported (" + frames.length + ")")); body.appendChild(el("div", "jd-pre", frames.map((x) => (x.sequence || x.comp) + " @ " + x.time + " s  " + x.file).join("\n"))); }
+  if (r.organized && r.organized.moved && r.organized.moved.length) { body.appendChild(el("div", "jd-h", "Filed into bins")); body.appendChild(el("div", "jd-pre", r.organized.moved.join("\n"))); }
+  if (r.returnValue !== null && r.returnValue !== undefined) { let t = ""; try { t = JSON.stringify(r.returnValue, null, 1); } catch (e) { t = String(r.returnValue); } body.appendChild(el("div", "jd-h", "Returned")); body.appendChild(el("div", "jd-pre", t.length > 2500 ? t.slice(0, 2500) + "\n... (truncated; full value in result.json)" : t)); }
+  // Developer-only extras (job script, script path): provided by dev.js, which is not part of packaged builds.
+  if (typeof DEV !== "undefined" && DEV && typeof DEV.jobDetail === "function") { try { await DEV.jobDetail({ body, el, job: j, ws, readText }); } catch (e) { } }
+  if (ws) { body.appendChild(el("div", "jd-h", "Files")); body.appendChild(el("div", "jd-pre", ws + "/results/" + j.id + "/result.json")); }
+  const dlg = $("jobDialog");
+  if (typeof dlg.uxpShowModal === "function") {
+    try { await dlg.uxpShowModal({ title: "Job details", resize: "both", size: { width: 560, height: 410 }, minSize: { width: 560, height: 410 }, maxSize: { width: 560, height: 410 } }); return; } catch (e) { }
+  }
+  dlg.classList.add("fallback");
+}
+$("closeJob").addEventListener("click", () => { const d = $("jobDialog"); if (d.classList.contains("fallback")) d.classList.remove("fallback"); else { try { d.close("done"); } catch (e) { } } });
+
+async function ensureDirs() {
+  for (const n of ["inbox", "running", "done", "out", "backups", "rejected"]) await mkdirs(sub(n));
+}
+
+// ------------------------------------------------------------ BRIDGE API handed to jobs
+async function activeProject() { try { return await ppro.Project.getActiveProject(); } catch (e) { return null; } }
+
+async function findSequence(project, name) {
+  const seqs = await project.getSequences();
+  const hits = [];
+  for (const s of seqs) if (s.name === name) hits.push(s);
+  if (!hits.length) throw new Error(`PLAYRIG.sequence: no sequence named "${name}"`);
+  if (hits.length > 1) throw new Error(`PLAYRIG.sequence: ${hits.length} sequences are named "${name}"`);
+  return hits[0];
+}
+
+function makeBridge(id, project) {
+  const logLines = [], snapQueue = [];
+  let ret = null;
+  const B = {
+    root: root(), ppro, project,
+    log(m) { logLines.push(typeof m === "string" ? m : JSON.stringify(m)); },
+    ret(v) { ret = v; },
+    sequence: (name) => findSequence(project, name),
+    snap(sequence, time) { snapQueue.push({ sequence, time: Number(time) || 0 }); },
+    // Runs fn(compoundAction) as ONE undo step. UNVERIFIED: signature taken from the Premiere UXP docs.
+    transact(name, fn) {
+      return project.lockedAccess(() => project.executeTransaction((ca) => fn(ca), name));
+    },
+    // Minimal in v0.1: sequence names and sizes. Extend per-track/clip once the DOM is verified.
+    async inspect() {
+      const out = { project: project.name, sequences: [] };
+      for (const s of await project.getSequences()) out.sequences.push({ name: s.name });
+      return out;
+    },
+    _log: () => logLines, _snaps: () => snapQueue, _ret: () => ret
+  };
+  // Incremental editing: tag / owned / adopt / sync / place / remove / setLevelDb / levelKeys (see incremental.js).
+  Object.assign(B, makeIncremental(ppro, project, B));
+  // Project organization: fileStrays / organizePlan / ensureBin / moveItem / importInto (see organize.js).
+  Object.assign(B, makeOrganizer(ppro, project, B));
+  return B;
+}
+
+async function takeSnapshots(project, list, outDir, defaults) {
+  const res = [];
+  for (const s of list) {
+    const r = { sequence: s.sequence, time: s.time, file: null, ok: false };
+    try {
+      const seq = await findSequence(project, s.sequence);
+      const name = `${s.sequence.replace(/[^A-Za-z0-9_-]+/g, "_")}_${Number(s.time).toFixed(3)}.png`;
+      const tick = ppro.TickTime.createWithSeconds(Number(s.time));
+      let w = defaults.width, h = defaults.height;
+      if (!w || !h) { try { const fsz = await seq.getFrameSize(); w = fsz.width; h = fsz.height; } catch (e) { w = 1920; h = 1080; } }
+      const ok = await ppro.Exporter.exportSequenceFrame(seq, tick, name, outDir + "/", w, h);
+      r.file = name;
+      r.ok = !!ok;
+      // Verify the PNG exists and is non-empty, polling briefly in case export returns early.
+      for (let i = 0; i < 100 && !(await pngReady(outDir + "/" + name)); i++) await new Promise((x) => setTimeout(x, 100));
+      r.ok = await pngReady(outDir + "/" + name);
+      if (!r.ok) r.error = "PNG not written within 10 s (exporter returned " + ok + ")";
+    } catch (e) { r.error = e.message; }
+    res.push(r);
+  }
+  return res;
+}
+async function pngReady(p) { try { return (await fs.lstat(p)).size > 0; } catch (e) { return false; } }
+
+
+// ------------------------------------------------------------ asset manifest
+function relPath(from, to) {
+  const a = norm(from).split("/"), b = norm(to).split("/");
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return a.slice(i).map(() => "..").concat(b.slice(i)).join("/");
+}
+
+async function collectAssets(project, projDir, sequenceNames) {
+  const items = [];
+  async function walk(folder, path, depth) {
+    for (const it of await folder.getItems()) {
+      const o = { name: it.name, bin: path || "/" };
+      let isBin = false;
+      try { isBin = !!ppro.FolderItem.cast(it); } catch (e) { }
+      if (isBin) {
+        o.kind = "bin"; items.push(o);
+        if (depth < 8) await walk(ppro.FolderItem.cast(it), path + "/" + it.name, depth + 1);
+        continue;
+      }
+      try {
+        const c = ppro.ClipProjectItem.cast(it);
+        const f = c ? await c.getMediaFilePath() : "";
+        if (f && f.charAt(0) === "/" || /^[A-Za-z]:[\\/]/.test(f || "")) {
+          o.kind = "media"; o.file = norm(f); o.relative = relPath(projDir, f);
+          o.offline = !!(await c.isOffline()) || !(await exists(f));
+        } else { o.kind = sequenceNames.indexOf(it.name) >= 0 ? "sequence" : "generated"; }
+      } catch (e) { o.kind = "unknown"; o.error = e.message; }
+      items.push(o);
+    }
+  }
+  await walk(await project.getRootItem(), "", 0);
+  return { generatedAt: new Date().toISOString(), projectFolder: projDir, items };
+}
+
+function assetsMarkdown(a) {
+  const media = a.items.filter((x) => x.kind === "media"), seqs = a.items.filter((x) => x.kind === "sequence");
+  let s = `# Project assets\n\nGenerated ${a.generatedAt} by Playrig for Premiere Pro. Relative paths are from the .prproj folder (\`${a.projectFolder}\`).\n\n`;
+  s += `## Sequences (${seqs.length})\n\n` + seqs.map((x) => `- ${x.name} (bin ${x.bin})`).join("\n") + "\n\n";
+  s += `## Media (${media.length})\n\n`;
+  for (const x of media) s += `- ${x.name} (bin ${x.bin}): \`${x.relative}\`${x.offline ? " **OFFLINE/MISSING**" : ""}\n`;
+  s += "\n## Bins\n\n" + a.items.filter((x) => x.kind === "bin").map((x) => `- ${x.bin === "/" ? "" : x.bin}/${x.name}`).join("\n") + "\n";
+  return s;
+}
+
+// ------------------------------------------------------------ project-folder sync
+const WS_README = `# EDIT_LOGS
+
+Written automatically by the Playrig for Premiere Pro next to the .prproj. Move this folder with the project.
+
+- \`JOURNAL.md\`: chronological record of every job (newest last).
+- \`jobs/<id>.js\` (+ \`<id>.json\`): the exact scripts run on this project.
+- \`results/<id>/\`: \`result.json\` and PNG frames of each job.
+- \`assets.md\` / \`assets.json\`: bins, sequences and media files in the project as of the last job (OFFLINE / EXTERNAL flagged, with paths relative to the .prproj folder).
+
+To continue elsewhere: open the project, read \`JOURNAL.md\` and \`assets.md\`, relink any missing media, then submit new jobs as usual.
+`;
+
+function journalEntry(r, jobFile) {
+  let s = `\n## ${r.id} [${r.status}]\n\n- started: ${r.startedAt} (${r.durationMs} ms), Premiere ${r.appVersion}\n`;
+  if (jobFile) s += `- script: \`jobs/${jobFile}\`\n`;
+  if (r.error) s += `- error: ${r.error.message}${r.error.line ? ` (line ${r.error.line})` : ""}\n`;
+  if (r.returnValue !== null && r.returnValue !== undefined) s += `- return: \`${JSON.stringify(r.returnValue).slice(0, 500)}\`\n`;
+  if (r.log.length) s += "- log:\n" + r.log.slice(0, 100).map((l) => "    " + String(l).replace(/[\r\n]+/g, " ")).join("\n") + "\n";
+  for (const sn of r.snapshots) if (sn.ok) s += `- frame: \`results/${r.id}/${sn.file}\` (${sn.sequence} @ ${sn.time})\n`;
+  return s;
+}
+
+async function syncOne(ws, id, runFile, optFile, outDir) {
+  if (runFile && (await exists(runFile))) await copyFile(runFile, ws + "/jobs");
+  if (optFile && (await exists(optFile))) await copyFile(optFile, ws + "/jobs");
+  await mkdirs(ws + "/results/" + id);
+  for (const name of await fs.readdir(outDir)) if (!/\.tmp$/i.test(name)) await copyFile(outDir + "/" + name, ws + "/results/" + id);
+}
+
+// Never throws: a sync problem must not fail the job.
+async function syncToProject(project, id, result, runFile, optFile, outDir) {
+  let projPath = null;
+  try { projPath = project && project.path; } catch (e) { }
+  if (!projPath) {
+    S.unsynced.push(id);
+    return { ok: false, reason: "project has no saved path; will sync after the next job once it is saved" };
+  }
+  try {
+    const ws = dirname(projPath) + "/EDIT_LOGS";
+    await mkdirs(ws);
+    if (!(await exists(ws + "/README.md"))) await writeText(ws + "/README.md", WS_README);
+    const pend = S.unsynced; S.unsynced = [];
+    for (const pid of pend) {
+      try {
+        await syncOne(ws, pid, sub("done") + "/" + pid + ".js", sub("done") + "/" + pid + ".json", sub("out") + "/" + pid);
+        await appendText(ws + "/JOURNAL.md", `\n## ${pid} (ran before the project was first saved; see results/${pid}/result.json)\n`);
+      } catch (e) { }
+    }
+    result.sync = { ok: true, dir: ws };
+    await writeAtomic(outDir + "/result.json", JSON.stringify(result, null, 2) + "\n");
+    await syncOne(ws, id, runFile, optFile, outDir);
+    if (!(await exists(ws + "/JOURNAL.md"))) await writeText(ws + "/JOURNAL.md", `# Playrig journal\n\nProject: ${basename(projPath)}\n`);
+    await appendText(ws + "/JOURNAL.md", journalEntry(result, basename(runFile)));
+    try {
+      const names = (await project.getSequences()).map((q) => q.name);
+      const assets = await collectAssets(project, dirname(projPath), names);
+      await writeText(ws + "/assets.json", JSON.stringify(assets, null, 2) + "\n");
+      await writeText(ws + "/assets.md", assetsMarkdown(assets));
+    } catch (e) { result.sync.assetsError = e.message; }
+    return result.sync;
+  } catch (e) { return { ok: false, reason: e.message }; }
+}
+
+// Copies the saved .prproj (reflects the last save, not unsaved edits).
+async function backupProject(project, id) {
+  try {
+    const p = project && project.path;
+    if (!p || !(await exists(p))) return { ok: false, reason: "project has never been saved" };
+    await mkdirs(sub("backups"));
+    const dest = sub("backups") + "/" + basename(p).replace(/\.prproj$/i, "") + "-" + id + ".prproj";
+    await fs.copyFile(p, dest);
+    return { ok: true, file: dest, reflectsUnsavedChanges: false };
+  } catch (e) { return { ok: false, reason: e.message }; }
+}
+
+// ------------------------------------------------------------ job handling
+async function simpleResult(id, status, message, extra) {
+  await mkdirs(sub("out") + "/" + id);
+  await writeAtomic(sub("out") + "/" + id + "/result.json", JSON.stringify(Object.assign({
+    id, status, startedAt: new Date().toISOString(), error: { message }, log: [], snapshots: []
+  }, extra || {}), null, 2) + "\n");
+}
+
+async function reject(file, reason) {
+  const base = basename(file).replace(/\.js$/i, "");
+  let id = base, dest = file;
+  if (!ID_RE.test(base)) {
+    id = `rejected-${stamp()}-${++S.seq}`;
+    dest = dirname(file) + "/" + id + ".js";
+    try { await fs.rename(file, dest); } catch (e) { try { await fs.unlink(file); } catch (e2) { } dest = null; }
+  }
+  await simpleResult(id, "rejected", reason, { originalName: basename(file) });
+  if (dest && (await exists(dest))) await moveFile(dest, sub("rejected"));
+  pushJob({ id, status: "rejected", startedAt: new Date().toISOString(), action: "job.rejected", name: actionInfo("job.rejected").label, error: reason, description: "Refused before running: " + reason });
+}
+
+async function pickJob() {
+  const valid = [];
+  for (const name of await fs.readdir(sub("inbox"))) {
+    if (!/\.js$/i.test(name)) continue; // ignores *.tmp and the options *.json
+    const p = sub("inbox") + "/" + name;
+    if (!ID_RE.test(name.replace(/\.js$/i, ""))) { await reject(p, "File name must match ^[A-Za-z0-9_-]{1,64}$"); continue; }
+    const st = await fs.lstat(p);
+    if (st.size > MAX_BYTES) { await reject(p, "Job file is larger than 2 MB"); continue; }
+    valid.push({ p, t: mtimeOf(st) });
+  }
+  valid.sort((a, b) => a.t - b.t);
+  return valid.length ? valid[0].p : null;
+}
+
+function errInfo(e, src) {
+  const info = { message: e && e.message ? e.message : String(e), line: null, fileName: null, source: null };
+  // UXP error stacks look like "...<anonymous>:LINE:COL"; the AsyncFunction wrapper adds 2 header lines.
+  const m = e && e.stack ? /<anonymous>:(\d+):\d+/.exec(e.stack) : null;
+  if (m && src) {
+    info.line = Math.max(1, Number(m[1]) - 2);
+    info.source = src.split(/\r\n|\r|\n/)[info.line - 1] || null;
+  }
+  return info;
+}
+
+async function runJob(inboxFile) {
+  const id = basename(inboxFile).replace(/\.js$/i, "");
+  const t0 = Date.now();
+  S.busy = true;
+  setStatus("Running " + id);
+  let result;
+  try {
+    const runFile = await moveFile(inboxFile, sub("running"));
+    const optInbox = sub("inbox") + "/" + id + ".json";
+    const optFile = (await exists(optInbox)) ? await moveFile(optInbox, sub("running")) : null;
+    const outDir = sub("out") + "/" + id;
+    await mkdirs(outDir);
+    if (await exists(outDir + "/result.json")) await fs.unlink(outDir + "/result.json");
+
+    const project = await activeProject();
+    result = { id, status: "ok", startedAt: new Date(t0).toISOString(), durationMs: 0, appVersion: String(await safeVersion()),
+      project: { path: safe(() => project.path), name: safe(() => project.name) }, error: null, log: [], snapshots: [], inspect: null, returnValue: null };
+
+    let opts = {};
+    try { if (optFile) opts = JSON.parse(await readText(optFile)); } catch (e) { result.status = "rejected"; result.error = errInfo(e); }
+
+    if (getSet("backup", "1") === "1") result.backup = await backupProject(project, id);
+    const B = makeBridge(id, project);
+    if (!project) { result.status = "error"; result.error = { message: "No active project", line: null, fileName: null, source: null }; }
+
+    if (result.status === "ok") {
+      const src = (await readText(runFile)).replace(/^/, "");
+      const hdr = parseJobHeader(src), declared = opts.action || hdr.action;
+      result.description = opts.description || hdr.description || null;
+      result.action = declared || inferAction(src, id);
+      result.actionSource = declared ? "declared" : "inferred";
+      const timeoutMs = (opts.timeoutSec || 120) * 1000;
+      let timer;
+      try {
+        const fn = new AsyncFunction("PLAYRIG", "PLAYPILOT", "BRIDGE", "ppro", "alert", "confirm", src); // PLAYPILOT, BRIDGE: legacy aliases for older job scripts
+        const job = fn(B, B, B, ppro, (m) => B.log("[alert] " + m), (m) => { B.log("[confirm -> false] " + m); return false; });
+        const timeout = new Promise((_, rej) => { timer = setTimeout(() => rej(Object.assign(new Error(`Job exceeded timeoutSec=${opts.timeoutSec || 120}; it keeps running in the background`), { isTimeout: true })), timeoutMs); });
+        await Promise.race([job, timeout]);
+      } catch (e) {
+        result.status = e && e.isTimeout ? "timeout" : "error";
+        result.error = e && e.isTimeout ? { message: e.message, line: null, fileName: null, source: null } : errInfo(e, src);
+      } finally { clearTimeout(timer); }
+    }
+
+    if (project && result.status !== "rejected") {
+      const list = [];
+      for (const sn of opts.snapshots || []) for (const t of sn.times || []) list.push({ sequence: sn.sequence, time: t });
+      list.push(...B._snaps());
+      result.snapshots = await takeSnapshots(project, list, outDir, { width: opts.width, height: opts.height });
+      if (opts.inspect) { try { result.inspect = await B.inspect(opts.inspect.sequence, opts.inspect.depth); } catch (e) { result.inspect = { error: e.message }; } }
+    }
+    if (result.actionSource === "inferred" && result.action === "custom" && result.snapshots.some((x) => x.ok)) result.action = "frame.export";
+    result.log = B._log();
+    result.returnValue = B._ret();
+    // Keep the project organized: file NEW loose items into their bins (never moves items already in a bin, never renames).
+    if (project && getSet("organize", "1") === "1") {
+      try { const o = await B.fileStrays(); result.organized = { moved: o.moved, needsDecision: o.decisions }; if (o.moved.length) result.log.push("[organize] filed " + o.moved.join("; ")); o.decisions.forEach((d) => result.log.push("[organize] needs a decision: " + d.name + ": " + d.why)); }
+      catch (e) { result.organized = { error: e.message }; }
+    }
+    result.durationMs = Date.now() - t0;
+
+    await writeAtomic(outDir + "/result.json", JSON.stringify(result, null, 2) + "\n");
+    result.sync = await syncToProject(project, id, result, runFile, optFile, outDir);
+    await writeAtomic(outDir + "/result.json", JSON.stringify(result, null, 2) + "\n");
+    if (result.sync.ok) await copyFile(outDir + "/result.json", result.sync.dir + "/results/" + id);
+    await moveFile(runFile, sub("done"));
+    if (optFile) await moveFile(optFile, sub("done"));
+    pushJob(Object.assign(rowFromResult(result), { result }));
+    setStatus(result.status === "error" ? "Error (" + id + ")" : "Idle");
+  } catch (fatal) {
+    try { await simpleResult(id, "error", "Playrig failure: " + fatal.message); } catch (e) { }
+    pushJob({ id, status: "error", startedAt: new Date().toISOString(), action: "custom", name: actionInfo("custom").label, error: "Playrig failure: " + fatal.message });
+    uiLog("Playrig failure: " + fatal.message);
+    setStatus("Error");
+  } finally { S.busy = false; }
+}
+
+const safe = (fn) => { try { const v = fn(); return v === undefined ? null : v; } catch (e) { return null; } };
+async function safeVersion() { try { return require("uxp").host.version; } catch (e) { return "unknown"; } }
+
+async function tick() {
+  if (!S.on || S.busy) return;
+  try {
+    const job = await pickJob();
+    if (job) await runJob(job);
+  } catch (e) { setStatus("Error"); uiLog("tick: " + e.message); }
+}
+
+// ------------------------------------------------------------ organize (button)
+async function organizeNow() {
+  if (S.busy) { uiLog("A job is running; try again in a moment."); return; }
+  S.busy = true;
+  const wasStatus = $("status").textContent;
+  setStatus("Organizing...");
+  try {
+    const project = await activeProject();
+    if (!project) { uiLog("No project is open."); return; }
+    const B = makeBridge("organize", project);
+    const r = await B.organizeProject({ fix: true, scheme: true });
+    const moved = r.moved.length, bins = r.createdBins.length, dec = r.decisions.length;
+    const parts = [];
+    if (moved) parts.push("moved " + moved + " item" + (moved === 1 ? "" : "s"));
+    if (bins) parts.push("created " + bins + " bin" + (bins === 1 ? "" : "s"));
+    if (dec) parts.push(dec + " need" + (dec === 1 ? "s" : "") + " a decision: " + r.decisions.map((d) => d.name).slice(0, 3).join(", ") + (dec > 3 ? "..." : ""));
+    uiLog((parts.length ? "Organized: " + parts.join(", ") + "." : "Already organized.") + (r.warnings.length ? " Warning: " + r.warnings[0] : "") + " (structure: " + r.source + ")");
+    // journal entry next to the project, like a job
+    const pp = project.path;
+    if (pp && (moved || bins || dec)) {
+      try {
+        const ws = dirname(pp) + "/EDIT_LOGS"; await mkdirs(ws);
+        let t = "\n## organize-" + stamp() + " [manual]\n\n- structure: " + r.source + "\n";
+        if (bins) t += "- created bins: " + r.createdBins.join(", ") + "\n";
+        r.moved.forEach((m) => { t += "- moved " + m + "\n"; });
+        r.decisions.forEach((d) => { t += "- needs a decision: " + d.name + ": " + d.why + "\n"; });
+        await appendText(ws + "/JOURNAL.md", t);
+      } catch (e) { }
+    }
+  } catch (e) { uiLog("Organize failed: " + e.message); }
+  finally { S.busy = false; setStatus(S.on ? "Idle" : "Stopped"); }
+}
+
+// Writes the effective structure to <project folder>/EDIT_LOGS/organize.json when there is none, then tries to open it.
+async function editStructure() {
+  const say = (t) => { uiLog(t); const el = $("structMsg"); if (el) el.textContent = t; };   // the dialog is modal, so show it there too
+  say("Working...");
+  try {
+    const project = await activeProject();
+    if (!project || !project.path) { say("Open and save a project first; the structure file lives in its EDIT_LOGS folder."); return; }
+    await mkdirs(dirname(project.path) + "/EDIT_LOGS");
+    const B = makeBridge("organize", project), w = await B.writeStructure();
+    let how = "";
+    try { await uxp.shell.openPath(w.file); how = (w.created ? "Created and opened " : "Opened ") + w.file; }
+    catch (e) { how = (w.created ? "Created " : "Structure file: ") + w.file + ". Could not open it automatically (" + (e && e.message ? e.message : e) + "). Unload and load the plugin in the UXP Developer Tool so the new permission applies, or open the file in any text editor."; }
+    say(how + (w.created ? "" : "") + " Edit it, then press Organize Project.");
+  } catch (e) { say("Edit structure failed: " + (e && e.message ? e.message : e)); }
+}
+
+// ------------------------------------------------------------ start / stop
+async function start() {
+  if (S.on) return;
+  try { await ensureDirs(); } catch (e) { setStatus("Error"); uiLog("Cannot create folders: " + e.message); return; }
+  S.on = true;
+  S.timer = setInterval(tick, 1000);
+  $("powerIcon").setAttribute("src", "icons/power-on.svg");
+  uiLog("");
+  setStatus("Idle");
+}
+function stop() {
+  clearInterval(S.timer);
+  S.on = false;
+  $("powerIcon").setAttribute("src", "icons/power-off.svg");
+  setStatus("Stopped");
+}
+
+function showRoot() { $("root").value = root(); }
+showRoot();
+$("auto").checked = getSet("auto", "0") === "1";
+$("backup").checked = getSet("backup", "1") === "1";
+$("auto").addEventListener("change", () => setSet("auto", $("auto").checked ? "1" : "0"));
+$("backup").addEventListener("change", () => setSet("backup", $("backup").checked ? "1" : "0"));
+$("organize").checked = getSet("organize", "1") === "1";
+$("organize").addEventListener("change", () => setSet("organize", $("organize").checked ? "1" : "0"));
+$("organizeNow").addEventListener("click", organizeNow);
+// Settings: a modal dialog (gear icon). Falls back to an in-panel overlay if this build cannot show modal dialogs.
+async function openSettings() {
+  const dlg = $("settingsDialog");
+  showRoot();
+  if (typeof dlg.uxpShowModal === "function") {
+    try { await dlg.uxpShowModal({ title: "Playrig Settings", resize: "both", size: { width: 560, height: 440 }, minSize: { width: 560, height: 440 }, maxSize: { width: 560, height: 440 } }); return; }
+    catch (e) { if (e && /cancel|close|dismiss/i.test(String(e.message || e))) return; }   // closed by the user
+  }
+  dlg.classList.add("fallback");
+}
+function closeSettings() {
+  const dlg = $("settingsDialog");
+  if (dlg.classList.contains("fallback")) { dlg.classList.remove("fallback"); return; }
+  try { dlg.close("done"); } catch (e) { dlg.classList.remove("fallback"); }
+}
+// left list switches the right pane
+document.querySelectorAll(".nav-item").forEach((n) => n.addEventListener("click", () => {
+  document.querySelectorAll(".nav-item").forEach((m) => m.classList.toggle("active", m === n));
+  document.querySelectorAll(".pane").forEach((p) => { p.style.display = p.id === "pane-" + n.getAttribute("data-pane") ? "block" : "none"; });
+}));
+// About: version from the manifest, links open in the default browser (needs the https scheme in launchProcess).
+try { const v = (uxp.versions && uxp.versions.plugin) || "0.1.0"; $("versionText").textContent = "Version " + v + " (preview)"; } catch (e) { }
+function openLink(url) {
+  uxp.shell.openExternal(url).then(() => { $("aboutMsg").textContent = ""; }, (e) => { $("aboutMsg").textContent = "Could not open " + url + " (" + (e && e.message ? e.message : e) + "). Unload and load the plugin in the UXP Developer Tool so the new permission applies."; });
+}
+
+// ------------------------------------------------------------ updates
+// This panel cannot replace its own files (UXP plugins are installed and updated by Creative Cloud), so it only reports: it reads the
+// public feed (needs the "network" permission in manifest.json), compares versions and links to the release. Checked once a day
+// while "Check for updates automatically" is on (default); the check sends nothing about you or your project.
+const UPDATE_FEED = "https://raw.githubusercontent.com/viveknigam3003/playrig-releases/main/versions.json";
+const UPDATE_PAGE_PREFIX = "https://github.com/viveknigam3003/playrig-releases/";
+const pluginVersion = () => { try { return (uxp.versions && uxp.versions.plugin) || "0.1.0"; } catch (e) { return "0.1.0"; } };
+function isNewerVersion(a, b) {
+  const pa = /(\d+)\.(\d+)\.(\d+)/.exec(String(a || "")), pb = /(\d+)\.(\d+)\.(\d+)/.exec(String(b || ""));
+  if (!pa || !pb) return false;
+  for (let i = 1; i <= 3; i++) if (Number(pa[i]) !== Number(pb[i])) return Number(pa[i]) > Number(pb[i]);
+  return false;
+}
+let updatePage = null;
+function showUpdate(entry) {
+  updatePage = entry && typeof entry.page === "string" && entry.page.startsWith(UPDATE_PAGE_PREFIX) ? entry.page : UPDATE_PAGE_PREFIX + "releases";
+  const text = "Playrig " + entry.version + " is available (you have " + pluginVersion() + ")." + (entry.notes ? " " + entry.notes : "");
+  $("updateBanner").textContent = text + " Click to download."; $("updateBanner").style.display = "block";
+  $("updateMsg").textContent = text; $("updateLink").style.display = "block";
+}
+async function checkForUpdate(manual) {
+  setSet("updateCheckedAt", String(Date.now()));
+  let feed;
+  try { const r = await fetch(UPDATE_FEED, { cache: "no-store" }); if (!r.ok) throw new Error(r.status === 404 ? "No update feed is published yet." : "HTTP " + r.status); feed = await r.json(); }
+  catch (e) { if (manual) $("updateMsg").textContent = "Could not check for updates: " + (e && e.message ? e.message : e); return; }
+  const entry = feed && feed.pr;
+  if (entry && isNewerVersion(entry.version, pluginVersion())) { showUpdate(entry); return; }
+  if (manual) { $("updateMsg").textContent = entry ? "You are up to date (version " + pluginVersion() + ")." : "No release has been published yet."; $("updateLink").style.display = "none"; }
+}
+const updateDue = () => Date.now() - (Number(getSet("updateCheckedAt", "0")) || 0) > 24 * 60 * 60 * 1000;
+$("checkUpdate").addEventListener("click", async () => { $("updateMsg").textContent = "Checking..."; await checkForUpdate(true); });
+$("updateLink").addEventListener("click", () => openLink(updatePage));
+$("updateBanner").addEventListener("click", () => { openSettings(); document.querySelectorAll(".nav-item").forEach((m) => { if (m.getAttribute("data-pane") === "about") m.click(); }); });
+$("updateAuto").checked = getSet("updateAuto", "1") === "1";
+$("updateAuto").addEventListener("change", () => setSet("updateAuto", $("updateAuto").checked ? "1" : "0"));
+
+$("linkTwitter").addEventListener("click", () => openLink("https://twitter.com/viveknigam_"));
+$("linkInstagram").addEventListener("click", () => openLink("https://www.instagram.com/viveknigam3003/"));
+$("openSettings").addEventListener("click", openSettings);
+$("closeSettings").addEventListener("click", closeSettings);
+$("editStructure").addEventListener("click", editStructure);
+$("toggle").addEventListener("click", () => (S.on ? stop() : start()));
+// Playrig folder: type or paste a path (applied on Enter / leaving the field), or Browse. A native folder picker cannot be used on top of a
+// modal window (nothing is clickable), so Browse closes Settings first and reopens it afterwards.
+const folderSay = (t) => { const el = $("folderMsg"); if (el) el.textContent = t; };
+async function applyRoot(raw) {
+  const p = String(raw || "").trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!p) { showRoot(); folderSay("Enter a folder path."); return false; }
+  if (!/^(\/|[A-Za-z]:\/)/.test(p)) { showRoot(); folderSay("Use a full path, starting with / (or a drive letter on Windows)."); return false; }
+  if (p === root()) { folderSay(""); return true; }
+  const prev = getSet("root", "");
+  setSet("root", p);
+  try { await ensureDirs(); await loadRecentJobs(); showRoot(); folderSay("Playrig folder set. Jobs are now read from " + p + "/inbox."); return true; }
+  catch (e) { setSet("root", prev); showRoot(); folderSay("Cannot use that folder: " + (e && e.message ? e.message : e)); return false; }
+}
+$("root").addEventListener("change", () => applyRoot($("root").value));
+$("choose").addEventListener("click", async () => {
+  closeSettings();
+  let picked = null;
+  try { picked = await uxp.storage.localFileSystem.getFolder(); } catch (e) { uiLog("Folder: " + (e && e.message ? e.message : e)); }
+  if (picked) await applyRoot(picked.nativePath);
+  openSettings();
+});
+uxp.entrypoints.setup({ panels: { playrig: { show() { } } } });
+renderJobs();
+watchProject();
+setInterval(watchProject, 1500);
+pickDefaultRoot().then(() => { if ($("auto").checked) start(); });
+if ($("updateAuto").checked && updateDue()) checkForUpdate(false);