playrig 0.0.0-stage → 0.1.0

package/editions/ae/lib/panel-core.jsxinc

@@ -0,0 +1,249 @@
+// Playrig for After Effects panel core: everything the panel needs that is NOT user interface. ES3 only.
+// Loaded once by the panel (lib/ folder) and defines $.global.PlayrigCore. Kept free of ScriptUI on purpose so it can move to a UXP
+// port nearly unchanged: actions + job-header parsing/inference (data in actions.json), the per-project history reader and the
+// detail-text builder. File access goes through File/Folder only.
+(function () {
+    var G = $.global;
+    var C = {};
+    var DATA = null;
+    var cache = {};   // result.json path -> { t, size, row }
+    var FALLBACK = { logFolder: "EDIT_LOGS", legacyLogFolder: "AE-BRIDGE", recipePrefix: "recipe.", actions: {
+        "custom": { label: "Custom action", summary: "A job with no declared action." },
+        "job.rejected": { label: "Rejected job", summary: "The job was refused before it ran." } }, inferById: [], inferBySource: [] };
+
+    function readText(f) {
+        var s;
+        f.encoding = "UTF-8";
+        if (!f.open("r")) { throw new Error("Cannot open " + f.fsName); }
+        s = f.read();
+        f.close();
+        return s;
+    }
+
+    // Strict JSON parser: B.json.parse from bridge-api when loaded, else eval of a validated-by-shape string is NOT used.
+    function parse(text) {
+        if (G.PLAYRIG && G.PLAYRIG.json) { return G.PLAYRIG.json.parse(text); }
+        throw new Error("JSON parser not loaded");
+    }
+
+    // dir: folder containing actions.json. Safe to call again.
+    C.init = function (dir) {
+        var f = new File(dir + "/actions.json"), d;
+        try { d = parse(readText(f)); } catch (e) { d = null; C.initError = e.message; }
+        DATA = d && d.actions ? d : FALLBACK;
+        return DATA === d;
+    };
+    C.data = function () { return DATA || FALLBACK; };
+    C.logFolder = function () { return C.data().logFolder || "EDIT_LOGS"; };
+    C.legacyLogFolder = function () { return C.data().legacyLogFolder || "AE-BRIDGE"; };
+
+    // ------------------------------------------------------------ actions
+    function isRecipe(id) {
+        var p = C.data().recipePrefix || "recipe.";
+        return typeof id === "string" && id.length > p.length && id.substr(0, p.length) === p;
+    }
+    C.isKnownAction = function (id) { return !!(id && (C.data().actions[id] || isRecipe(id))); };
+
+    // Label of a result/row: a recipe job carries its recipe's title in actionLabel; unknown ids are "Custom action".
+    C.actionLabel = function (action, actionLabel) {
+        var a = C.data().actions;
+        if (actionLabel) { return String(actionLabel); }
+        if (a[action]) { return a[action].label; }
+        if (isRecipe(action)) { return "Recipe: " + action.substr((C.data().recipePrefix || "recipe.").length); }
+        return a.custom.label;
+    };
+    C.actionSummary = function (action) {
+        var a = C.data().actions;
+        if (a[action]) { return a[action].summary; }
+        if (isRecipe(action)) { return a["recipe.run"] ? a["recipe.run"].summary : ""; }
+        return a.custom.summary;
+    };
+
+    // First `// ...` lines of a job script: `// @action <id>` declares the action; the first other comment line is the description.
+    C.parseJobHeader = function (src) {
+        var out = { action: null, description: null }, lines = String(src || "").split(/\r\n|\r|\n/), i, m, t, a;
+        for (i = 0; i < lines.length && i < 10; i++) {
+            m = /^\s*\/\/\s?(.*)$/.exec(lines[i]);
+            if (!m) { if (/\S/.test(lines[i])) { break; } else { continue; } }
+            t = m[1].replace(/^\s+|\s+$/g, "");
+            a = /^@action\s+([A-Za-z0-9_.\-]+)/.exec(t);
+            if (a) { out.action = a[1]; }
+            else if (t && !out.description) { out.description = t.substr(0, 240); }
+        }
+        return out;
+    };
+
+    // Best guess from the job id and script. Ordered rules, first match wins.
+    C.inferAction = function (src, id) {
+        var d = C.data(), s = String(src || ""), i, r;
+        for (i = 0; i < d.inferById.length; i++) {
+            r = d.inferById[i];
+            if (new RegExp(r.re, r.flags || "").test(String(id || ""))) { return r.action; }
+        }
+        for (i = 0; i < d.inferBySource.length; i++) {
+            r = d.inferBySource[i];
+            if (new RegExp(r.re, r.flags || "").test(s)) { return r.action; }
+        }
+        return "custom";
+    };
+
+    // Decides {action, actionSource, actionLabel, description} for a job from options (aeb --action/--desc) and its script.
+    C.classify = function (opts, src, id) {
+        var h = C.parseJobHeader(src), out = { action: null, actionSource: "inferred", actionLabel: null, description: null }, declared;
+        opts = opts || {};
+        declared = opts.action || h.action;
+        if (declared) {
+            out.actionSource = "declared";
+            out.action = C.isKnownAction(String(declared)) ? String(declared) : "custom";
+        } else {
+            out.action = C.inferAction(src, id);
+        }
+        if (opts.actionLabel) { out.actionLabel = String(opts.actionLabel).substr(0, 120); }
+        out.description = opts.description ? String(opts.description).substr(0, 240) : (h.description || null);
+        return out;
+    };
+
+    // ------------------------------------------------------------ formatting
+    function pad2(n) { return (n < 10 ? "0" : "") + n; }
+    // "2026-10-02T17:42:05+02:00" -> "02-10-26 17:42" (the clock time the job was started at, not converted).
+    C.formatTime = function (iso) {
+        var m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(String(iso || ""));
+        return m ? (m[3] + "-" + m[2] + "-" + m[1].substr(2) + " " + m[4] + ":" + m[5]) : "";
+    };
+    C.formatDuration = function (ms) {
+        if (ms === null || ms === undefined || isNaN(Number(ms))) { return ""; }
+        return ms < 1000 ? (ms + " ms") : ((Math.round(ms / 100) / 10) + " s");
+    };
+    C.statusGlyph = function (status) {
+        return { ok: "\u2713", error: "\u2715", rejected: "\u26A0", timeout: "\u23F1" }[status] || "?";
+    };
+    C.statusIconName = function (status) {
+        return { ok: "status-ok", error: "status-error", rejected: "status-rejected", timeout: "status-timeout" }[status] || "status-unknown";
+    };
+
+    // ------------------------------------------------------------ project log folder
+    // Returns the Folder holding the project's log (EDIT_LOGS, or the legacy AE-BRIDGE until it is migrated), or null.
+    C.logDir = function (projectFile) {
+        var dir, f;
+        if (!projectFile) { return null; }
+        dir = projectFile.parent;
+        f = new Folder(dir.fsName + "/" + C.logFolder());
+        if (f.exists) { return f; }
+        f = new Folder(dir.fsName + "/" + C.legacyLogFolder());
+        return f.exists ? f : null;
+    };
+
+    // ------------------------------------------------------------ history
+    // One light row per result.json: only what the table and tooltip need. The full result is re-read for the detail window.
+    function toRow(id, resultFile, logDir, projectPath) {
+        var r = parse(readText(resultFile)), row, src = null, cls;
+        if (projectPath && r.project && r.project.path && r.project.path !== projectPath) { return null; }   // another project/app sharing the folder
+        row = { id: id, status: r.status || "?", startedAt: r.startedAt || "", durationMs: r.durationMs, action: r.action || null,
+            actionSource: r.actionSource || "declared", actionLabel: r.actionLabel || null, description: r.description || null,
+            error: r.error && r.error.message ? String(r.error.message) : null, framesOk: 0, resultPath: resultFile.fsName, projectPath: r.project ? r.project.path : null };
+        for (var i = 0; r.snapshots && i < r.snapshots.length; i++) { if (r.snapshots[i].ok) { row.framesOk++; } }
+        if (!row.action || !C.isKnownAction(row.action)) {
+            // Older job without an action: infer from the script kept in the project log.
+            try {
+                src = new File(logDir.fsName + "/jobs/" + id + ".jsx");
+                src = src.exists ? readText(src) : "";
+            } catch (e) { src = ""; }
+            cls = C.classify({}, src, id);
+            row.action = row.action ? "custom" : cls.action;
+            row.actionSource = "inferred";
+            if (!row.description) { row.description = cls.description; }
+        }
+        return row;
+    }
+
+    // Latest `limit` jobs of the project, newest first. {rows, total, dir}. total = result folders found.
+    C.loadHistory = function (projectFile, limit) {
+        var logDir = C.logDir(projectFile), res, dirs, i, list = [], f, key, c, rows = [], row, projectPath, total;
+        if (!logDir) { return { rows: [], total: 0, dir: null }; }
+        projectPath = projectFile.fsName;
+        res = new Folder(logDir.fsName + "/results");
+        if (!res.exists) { return { rows: [], total: 0, dir: logDir.fsName }; }
+        dirs = res.getFiles(function (x) { return x instanceof Folder; });
+        for (i = 0; i < dirs.length; i++) {
+            f = new File(dirs[i].fsName + "/result.json");
+            if (f.exists) { list.push({ id: dirs[i].displayName, f: f, t: f.modified ? f.modified.getTime() : 0 }); }
+        }
+        list.sort(function (a, b) { return (b.t - a.t) || (a.id < b.id ? 1 : (a.id > b.id ? -1 : 0)); });
+        for (i = 0; i < list.length; i++) {
+            key = list[i].f.fsName;
+            c = cache[key];
+            if (c && c.t === list[i].t) { row = c.row; }
+            else {
+                try { row = toRow(list[i].id, list[i].f, logDir, projectPath); } catch (e) { row = { id: list[i].id, status: "?", startedAt: "", action: "custom", actionSource: "inferred", error: "unreadable result.json: " + e.message, resultPath: key }; }
+                cache[key] = { t: list[i].t, row: row };
+            }
+            if (row) { rows.push(row); }
+        }
+        total = rows.length;
+        // Most recent start first (file times can tie when results are copied).
+        rows.sort(function (a, b) { return a.startedAt < b.startedAt ? 1 : (a.startedAt > b.startedAt ? -1 : 0); });
+        if (rows.length > limit) { rows.length = limit; }
+        return { rows: rows, total: total, dir: logDir.fsName };
+    };
+
+    // A light row built from a finished in-memory result (used for unsaved projects).
+    C.rowFromResult = function (r, resultPath) {
+        return { id: r.id, status: r.status, startedAt: r.startedAt, durationMs: r.durationMs, action: r.action || "custom", actionSource: r.actionSource || "inferred",
+            actionLabel: r.actionLabel || null, description: r.description || null, error: r.error && r.error.message ? String(r.error.message) : null,
+            framesOk: 0, resultPath: resultPath, projectPath: r.project ? r.project.path : null };
+    };
+
+    C.readResult = function (row) {
+        var f = new File(row.resultPath);
+        return f.exists ? parse(readText(f)) : null;
+    };
+
+    // ------------------------------------------------------------ tooltip / summary line
+    C.summaryText = function (row) {
+        var t = row.description || C.actionSummary(row.action), bits = [t];
+        if (row.actionSource === "inferred") { bits.push("Action: " + C.actionLabel(row.action, row.actionLabel) + " (inferred from the script)"); }
+        bits.push("Result: " + row.status + (row.durationMs !== undefined && row.durationMs !== null ? " in " + C.formatDuration(row.durationMs) : ""));
+        if (row.error) { bits.push(row.error.substr(0, 160)); }
+        if (row.framesOk) { bits.push(row.framesOk + " frame" + (row.framesOk === 1 ? "" : "s") + " exported"); }
+        return bits.join(" | ");
+    };
+
+    // ------------------------------------------------------------ detail text
+    // Sections for the job detail window, from a full result.json: [{ title, text }]. Dev-only extras are added by the panel.
+    C.detail = function (r, row) {
+        var out = [], i, s, sn, t, ret;
+        out.push({ title: "What happened", text: (r.description || C.actionSummary(r.action || row.action)) });
+        out.push({ title: "Action", text: C.actionLabel(r.action || row.action, r.actionLabel || row.actionLabel) + (r.actionSource === "inferred" || (!r.actionSource && row.actionSource === "inferred") ? " (inferred)" : "") });
+        out.push({ title: "Job id", text: String(r.id) });
+        out.push({ title: "Started", text: (C.formatTime(r.startedAt) || "?") + (r.durationMs !== undefined ? "  (" + C.formatDuration(r.durationMs) + ")" : "") });
+        out.push({ title: "Project", text: r.project && r.project.path ? r.project.path + (r.project.dirty ? "  (unsaved changes)" : "") : "(unsaved project)" });
+        if (r.aeVersion) { out.push({ title: "After Effects", text: String(r.aeVersion) }); }
+        if (r.error) {
+            t = String(r.error.message);
+            if (r.error.line) { t += "\nline " + r.error.line; }
+            if (r.error.source) { t += ": " + String(r.error.source).replace(/^\s+|\s+$/g, ""); }
+            out.push({ title: "Error", text: t, multi: true });
+        }
+        if (r.log && r.log.length) {
+            s = [];
+            for (i = 0; i < r.log.length && i < 100; i++) { s.push(String(r.log[i])); }
+            out.push({ title: "Log", text: s.join("\n") + (r.log.length > 100 ? "\n... " + (r.log.length - 100) + " more" : ""), multi: true });
+        }
+        if (r.snapshots && r.snapshots.length) {
+            s = [];
+            for (i = 0; i < r.snapshots.length; i++) {
+                sn = r.snapshots[i];
+                s.push(sn.ok ? (sn.comp + " @ " + sn.time + " s: " + sn.file) : ("FAILED " + (sn.comp || "") + " @ " + (sn.time === undefined ? "?" : sn.time) + ": " + (sn.error || "unknown")));
+            }
+            out.push({ title: "Frames exported", text: s.join("\n"), multi: true });
+        }
+        if (r.returnValue !== null && r.returnValue !== undefined) {
+            ret = (G.PLAYRIG && G.PLAYRIG.json) ? G.PLAYRIG.json.stringify(r.returnValue) : String(r.returnValue);
+            out.push({ title: "Returned", text: ret.length > 600 ? ret.substr(0, 600) + " ... (truncated)" : ret, multi: true });
+        }
+        out.push({ title: "Files", text: row.resultPath });
+        return out;
+    };
+
+    G.PlayrigCore = C;
+})();

package/editions/ae/lib/update-key.pem

@@ -0,0 +1,11 @@
+-----BEGIN PUBLIC KEY-----
+MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAqLgsqpSkR8hPJA6pKLsp
+Rxsu189MMharZQOJa+jS/cyatLklNebjrxhh41n4iHCiB5WZ7Ua6Z/yJFPs3FtmA
+anRE8o86ZJuo16zq0+xrQklAjZWzwi20IODce6+hnv0imtQ84EXi0pp7NYOYTXCX
+3ialfXf5LHR3xtGe6xc49TkMesaFhJsb5Ip270o67tCNFo4PdtO81sG9PuYGRlEM
+d4bd7AFQhT+g00QjWu6cDWHF9X2XzkNRGwpXwAkKmwxU/r2/JW4cRl5V37uIUB2q
+6X6f25YYi7wBXqzEE6ubR+26Y9wz7tqr4xS9R2dvnagQSUY81C0harK/M5RhQ2zo
+Gpp2SixYwsieS60gTO75FQE2RBQhNdBpYQdb3Jc1hz2HlIWSV9WCmg7cPEpqIN1l
+RZYyrTv/c6W+TFhnbbPhvFvUHxmDycFGs/ti3cLIFVI0esIiDAJpmlJVclIQmFnU
+77s3AK5DbbV51KH49YzTzoykrDkfWFffSC1uIlluGEXjAgMBAAE=
+-----END PUBLIC KEY-----

package/editions/ae/lib/updater.jsxinc

@@ -0,0 +1,148 @@
+// Playrig updater: checks the public update feed and installs a newer core into the user's data folder. ES3 only, no UI.
+// Defines $.global.PlayrigUpdater. The panel calls configure() first (folder of the running core, settings, JSON parser).
+//
+// Why curl: ExtendScript sockets have no TLS, so HTTPS goes through the system's curl via system.callSystem. This needs
+// "Allow Scripts to Write Files and Access Network" (already required by Playrig).
+// Trust: an update is installed only if (1) its URL is on the pinned GitHub releases path, (2) its SHA-256 matches the feed and
+// (3) its RSA-SHA256 signature verifies against lib/update-key.pem, which ships with the installed panel (never downloaded).
+// Step 3 needs `openssl` (macOS has it; stock Windows does not): without it the panel only reports the update and tells the
+// user to run `playrig update ae`, which verifies natively.
+(function () {
+    var G = $.global;
+    var FEED = "https://raw.githubusercontent.com/viveknigam3003/playrig-releases/main/versions.json";
+    var ASSET_PREFIX = "https://github.com/viveknigam3003/playrig-releases/releases/download/";
+    var STUB_API = 1;
+    var DAY_MS = 24 * 60 * 60 * 1000;
+    var WIN = String($.os).indexOf("Windows") >= 0;
+    var env = null;
+    var U = {};
+
+    function q(s) {
+        s = String(s);
+        return WIN ? '"' + s.replace(/"/g, "") + '"' : "'" + s.replace(/'/g, "'\\''") + "'";
+    }
+    function sh(cmd) {
+        var out;
+        try { out = system.callSystem(WIN ? "cmd /s /c \"" + cmd + "\"" : cmd); } catch (e) { return ""; }
+        return String(out === undefined || out === null ? "" : out);
+    }
+    var CURL = WIN ? "curl.exe" : "/usr/bin/curl";
+
+    function parseVer(v) {
+        var m = /(\d+)\.(\d+)\.(\d+)/.exec(String(v || ""));
+        return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+    }
+    function isNewer(a, b) {
+        var i;
+        a = parseVer(a); b = parseVer(b);
+        if (!a || !b) { return false; }
+        for (i = 0; i < 3; i++) { if (a[i] !== b[i]) { return a[i] > b[i]; } }
+        return false;
+    }
+    function readText(f) { var s; f.encoding = "UTF-8"; if (!f.open("r")) { return null; } s = f.read(); f.close(); return s; }
+    function writeText(f, s) { f.encoding = "UTF-8"; if (!f.open("w")) { return false; } f.write(s); f.close(); return true; }
+    function ensure(dir) { var f = new Folder(dir); if (!f.exists) { f.create(); } return f.exists; }
+    function baseDir() { return Folder.userData.fsName + "/Playrig/ae"; }
+
+    U.configure = function (e) { env = e; };
+    U.parseVersion = parseVer;
+    U.isNewer = isNewer;
+
+    U.current = function () {
+        var f = new File(env.here + "/version.json"), s, m;
+        s = f.exists ? readText(f) : null;
+        m = s ? /"version"\s*:\s*"([^"]+)"/.exec(s) : null;
+        return m ? m[1] : null;
+    };
+
+    U.feedUrl = function () { return env.getSet("updateFeed", "") || FEED; };
+    // A custom feed (development only) may point at file:// or another host; the signature check still applies.
+    function pinned(url) { return !!env.getSet("updateFeed", "") || String(url).indexOf(ASSET_PREFIX) === 0; }
+
+    U.due = function () {
+        var last = Number(env.getSet("updateCheckedAt", "0")) || 0;
+        return new Date().getTime() - last > DAY_MS;
+    };
+
+    U.canVerify = function () { return /(OpenSSL|LibreSSL)/.test(sh("openssl version")); };
+
+    // Reads the feed. Returns { ok, current, latest, newer, entry, error }.
+    U.check = function (timeoutSec) {
+        var cur = U.current(), out, feed, entry, r;
+        env.setSet("updateCheckedAt", String(new Date().getTime()));
+        out = sh(CURL + " -fsL --connect-timeout 5 --max-time " + (timeoutSec || 15) + " " + q(U.feedUrl()));
+        if (!out) { return { ok: false, current: cur, error: "Could not reach the update server." }; }
+        if (out.indexOf("{") !== 0) { return { ok: false, current: cur, error: "Could not read the update feed. No release has been published yet, or the repository is not public." }; }
+        try { feed = env.parse(out); } catch (e) { return { ok: false, current: cur, error: "The update feed is not valid." }; }
+        entry = feed && feed.ae;
+        if (!entry || !parseVer(entry.version)) { return { ok: false, current: cur, error: "The update feed has no After Effects entry." }; }
+        r = { ok: true, current: cur, latest: entry.version, newer: isNewer(entry.version, cur), entry: entry, notes: entry.notes || "", page: entry.page || "" };
+        if (r.newer && entry.stubApi && Number(entry.stubApi) > STUB_API) {
+            r.newer = false; r.needsReinstall = true;
+            r.error = "Version " + entry.version + " needs a newer Playrig.jsx: run `playrig install ae`.";
+        }
+        return r;
+    };
+
+    function sha256(file) {
+        var out, m;
+        if (WIN) {
+            out = sh("certutil -hashfile " + q(file) + " SHA256").split(/\r?\n/);
+            return out.length > 1 ? out[1].replace(/\s+/g, "").toLowerCase() : "";
+        }
+        out = sh("shasum -a 256 " + q(file));
+        m = /^([0-9a-fA-F]{64})/.exec(out);
+        return m ? m[1].toLowerCase() : "";
+    }
+
+    function fail(msg, tmp) {
+        if (tmp) { sh(WIN ? "rmdir /s /q " + q(tmp) : "rm -rf " + q(tmp)); }
+        return { ok: false, error: msg };
+    }
+
+    // Downloads, verifies and installs entry into <userData>/Playrig/ae/current. Takes effect after After Effects restarts.
+    U.install = function (entry) {
+        var stamp = String(new Date().getTime()), tmp = Folder.temp.fsName + "/playrig-update-" + stamp, base = baseDir();
+        var zip = tmp + "/payload.zip", sigB64 = tmp + "/sig.b64", sigBin = tmp + "/sig.bin", keyFile, fresh = base + "/new-" + stamp, out, v, vf, s;
+        if (!entry || !entry.url || !entry.sha256 || !entry.sig) { return fail("The update entry is incomplete."); }
+        if (!pinned(entry.url)) { return fail("The update URL is not on the Playrig releases page; refusing it."); }
+        if (!U.canVerify()) { return fail("Cannot verify the signature here (openssl not found). Run `playrig update ae` in a terminal instead."); }
+        keyFile = env.libFile("update-key.pem");
+        if (!keyFile) { return fail("update-key.pem is missing from the installed panel. Run `playrig install ae`."); }
+        if (!ensure(tmp) || !ensure(base)) { return fail("Cannot create a working folder (is scripting file access allowed?)."); }
+
+        out = sh(CURL + " -fsL --connect-timeout 10 --max-time 180 -o " + q(zip) + " " + q(entry.url) + (WIN ? " && echo PP_OK" : " && echo PP_OK"));
+        if (out.indexOf("PP_OK") < 0 || !new File(zip).exists) { return fail("Download failed.", tmp); }
+        if (sha256(zip) !== String(entry.sha256).toLowerCase()) { return fail("Checksum mismatch: the download is not the release that was published. Nothing was installed.", tmp); }
+
+        if (!writeText(new File(sigB64), entry.sig)) { return fail("Cannot write the signature file.", tmp); }
+        out = sh("openssl base64 -d -A -in " + q(sigB64) + " -out " + q(sigBin) + " && echo PP_OK");
+        if (out.indexOf("PP_OK") < 0) { return fail("The signature is not valid base64.", tmp); }
+        out = sh("openssl dgst -sha256 -verify " + q(keyFile.fsName) + " -signature " + q(sigBin) + " " + q(zip));
+        if (!/Verified OK/i.test(out)) { return fail("Signature check failed: the update was not signed by Playrig. Nothing was installed.", tmp); }
+
+        if (!ensure(fresh)) { return fail("Cannot create " + fresh, tmp); }
+        out = sh((WIN ? "tar -xf " + q(zip) + " -C " + q(fresh) : "/usr/bin/unzip -q -o " + q(zip) + " -d " + q(fresh)) + " && echo PP_OK");
+        if (out.indexOf("PP_OK") < 0) { sh(WIN ? "rmdir /s /q " + q(fresh) : "rm -rf " + q(fresh)); return fail("Could not unpack the update.", tmp); }
+
+        vf = new File(fresh + "/version.json");
+        s = vf.exists ? readText(vf) : null;
+        v = s ? /"version"\s*:\s*"([^"]+)"/.exec(s) : null;
+        if (!new File(fresh + "/core.jsx").exists || !v || v[1] !== entry.version) {
+            sh(WIN ? "rmdir /s /q " + q(fresh) : "rm -rf " + q(fresh));
+            return fail("The unpacked update is not the expected version.", tmp);
+        }
+
+        if (WIN) {
+            out = sh("(if exist " + q(base + "/previous") + " rmdir /s /q " + q(base + "/previous") + ") & (if exist " + q(base + "/current") + " move " + q(base + "/current") + " " + q(base + "/previous") + ") & move " + q(fresh) + " " + q(base + "/current") + " && echo PP_OK");
+        } else {
+            out = sh("rm -rf " + q(base + "/previous") + "; if [ -d " + q(base + "/current") + " ]; then mv " + q(base + "/current") + " " + q(base + "/previous") + "; fi; mv " + q(fresh) + " " + q(base + "/current") + " && echo PP_OK");
+        }
+        if (out.indexOf("PP_OK") < 0) { return fail("Could not put the update in place.", tmp); }
+        sh(WIN ? "rmdir /s /q " + q(tmp) : "rm -rf " + q(tmp));
+        env.setSet("updateInstalled", entry.version);
+        return { ok: true, version: entry.version, restart: true };
+    };
+
+    G.PlayrigUpdater = U;
+})();

package/editions/ae/library-starter/INDEX.md

@@ -0,0 +1,5 @@
+# Motion Library: Index
+
+0 usable recipes. Generated by `playrig ae lib index`: edit the recipe files, not this one.
+
+No recipes yet. Create one with the `create-ae-recipe` skill or `playrig ae lib new <category>/<id>`.

package/editions/ae/library-starter/README.md

@@ -0,0 +1,161 @@
+# Motion Library
+
+Your own project-independent library of motion-graphics building blocks for After Effects, designed to grow to hundreds of entries and to be used by agents without loading everything.
+
+**One Markdown file per recipe.** Each file has YAML frontmatter (what an agent needs to choose and call it), a body (how it works, which settings matter, gotchas), and the ExtendScript in a ```jsx block. `INDEX.md` is the router.
+
+This folder is a starter: it ships no recipes. Create yours with the `create-ae-recipe` skill (from a description or a reference video) or `playrig ae lib new <category>/<id>`, then `playrig ae lib index`.
+
+## Progressive disclosure (how agents use it)
+
+| Level | File | Read when | Size |
+|---|---|---|---|
+| 0 | `INDEX.md` | Always first. One line per recipe: id, summary, aliases. | ~230 bytes/recipe |
+| 0b | `categories/<name>.md` | Only when the library is large (see below) | one category |
+| 1 | `recipes/<category>/<id>.md` | Once a recipe is chosen: parameters, tweaks, gotchas, what it combines with | ~3-7 KB |
+| 2 | `<id>--t<seconds>.png` next to the recipe, embedded in its `## Preview` section | Only to see what it looks like | images |
+| 3 | the `jsx` block | Only to modify the recipe (running it never needs reading it) | in the recipe file |
+
+The agent never has to read recipe scripts to *use* a recipe: `playrig ae lib run` pulls the script out of the file itself.
+
+When the library passes **40 recipes**, `playrig ae lib index` automatically turns `INDEX.md` into a short category list with one index per category, so level 0 stays small however big the library gets.
+
+## Use a recipe
+
+**Start a video with the `create-ae-video` skill** (`.claude/skills/create-ae-video/`): preflight, discovery, storyboard, then it hands off to the two skills below.
+
+For agents and for building whole scenes, the **`use-ae-recipes`** skill (`.claude/skills/use-ae-recipes/`) wraps this: it routes through the index, chains recipes, previews, tunes with you and assembles a master comp. To *add* recipes use **`create-ae-recipe`**.
+
+Needs After Effects open with the Playrig for After Effects panel started (see the edition README). Run from anywhere:
+
+```bash
+playrig ae lib list <word>                # search ids, names, tags, aliases, summaries
+playrig ae lib list --category camera
+playrig ae lib show <recipe-id>      # parameters + preview paths  (--full prints the notes too)
+playrig ae lib run  <recipe-id> --param comp="Scene 1" --param text="Ship faster" --param boldWord=faster
+```
+
+- `--param key=value`, repeatable. Validated by type: numbers (with min/max), `#RRGGBB` colours, true/false, lists with `|`. Unknown parameters are rejected with the valid list.
+- Every recipe has a `comp` parameter (the comp to build in, **created if missing**). To chain recipes into one scene, give them the same `comp`; pass `width`, `height`, `duration`, `fps` on the first one.
+- Each run is one Undo step in After Effects. Preview frames are rendered and their paths printed; `--no-snap` skips them.
+- Planned recipes (no script yet) refuse to run and point to their file, which describes how they are built.
+
+### Editing in place (no rebuilding)
+
+Every run tags the layers it creates in the target comp (layer comment `aeb:<recipe>:<instance>`). To change a recipe's look later, re-run it with `--replace`: only **that recipe's layers** are removed and the new ones take the **same stacking position**; everything else in the scene is untouched.
+
+```bash
+playrig ae lib run <recipe-id> --param comp=S1 --param text="New words" --param size=100 --replace
+playrig ae lib run chips-pop-stagger   --param comp=S1 --param seed=3 --instance second --replace      # a specific instance
+```
+
+- Running a recipe again **without** `--replace` adds another instance on purpose (`default`, `default-2`, …); name them with `--instance`.
+- Replacing **content** under a rig (`camera-slow-push-in`) leaves the new layers outside the rig: re-run the rig with `--replace`. Layers that lost a parent are reported.
+- Recipes that modify existing layers (`text-cmy-split-scatter`, `rig-tilt-board`) are `idempotent: false`; `--replace` refuses and prints what to do instead. `playrig ae lib show <id>` says which.
+- For new words only: `.claude/skills/use-ae-recipes/scripts/edit-text.jsx` edits the text layer directly and keeps its animators.
+- Authoring: a recipe should only create layers (so removing them restores the comp). If it must change existing layers, set `idempotent: false` and write the `replace_note`. `playrig ae lib check` enforces the pair.
+
+### Scenes as chains
+
+```bash
+playrig ae lib run bg-radial-gradient     --param comp=S1 --param duration=3.5
+playrig ae lib run <recipe-id>    --param comp=S1 --param text="the bar for excellence goes high" --param boldWord=excellence
+playrig ae lib run chips-pop-stagger      --param comp=S1 --param start=0.5 --param outAt=2.9
+playrig ae lib run text-cmy-split-scatter --param comp=S1 --param splitAt=2.9 --param cutAt=3.5
+
+playrig ae lib run bg-blueprint-grid       --param comp=S2 --param duration=2.5
+playrig ae lib run text-letter-stagger-pop --param comp=S2 --param text="proof of work" --param driftPercent=0
+playrig ae lib run camera-slow-push-in     --param comp=S2
+```
+
+Order matters where a recipe acts on content: run `text-cmy-split-scatter`, `camera-slow-push-in` and `rig-tilt-board` **after** the layers they operate on exist. Each recipe's "Combine with" and "Gotchas" sections say so.
+
+## Recipe file format
+
+```markdown
+---
+id: <recipe-id>            # lowercase-kebab; must equal the file name
+name: "Per-word 3D fly-in headline"
+category: type                     # must equal the folder name
+status: ready                      # ready | experimental | planned
+summary: "One sentence, <= 150 chars. Read for every routing decision."
+use_when: "When the user wants ..."
+tags: ["kinetic-typography", "3D"]
+aliases: ["word by word reveal", "3D text animator"]    # other names / industry terms people will say
+composes_with: ["bg-radial-gradient", "text-cmy-split-scatter"]   # must be existing ids
+origin: "Where it came from (project / scene)"
+idempotent: true                   # optional; false = cannot be replaced in place (needs replace_note)
+replace_note: "..."                 # only with idempotent: false: how to change it instead
+preview_times: [0.25, 0.5, 1.0]    # seconds in the comp; rendered on every run, saved with --save-preview
+params:                            # one flow-map per parameter; quote strings
+  comp: {type: string, default: "Scene", desc: "Target comp (created if missing)"}
+  size: {type: number, default: 86, min: 4, desc: "Font size in px"}
+  color: {type: color, default: "#111111", desc: "Text colour"}
+---
+
+# Title
+<!-- previews --> images embedded here automatically by --save-preview
+## What it looks like        plain-words description, as you would brief an artist
+## How it works              the After Effects mechanics in a few lines
+## Tweaks that matter        table: setting -> what it changes visually, with useful values
+## Gotchas                   what bit you, ordering rules, limits
+## Combine with              related recipes
+## Script                    ```jsx block: ES3; parameters arrive as P.<name>; lib* helpers from _common.jsx
+```
+
+Parameter types: `string`, `number`, `boolean`, `color`, `list`. Defaults live **only** in the frontmatter; the CLI merges them with `--param` values and hands the script a complete `P`. The frontmatter is a small YAML subset (top-level keys, one level of nesting, flow lists/maps), parsed without dependencies.
+
+## Add a recipe
+
+```bash
+playrig ae lib new type/my-effect        # scaffold (already passes the linter)
+# edit recipes/type/my-effect.md, then:
+playrig ae lib check                     # lint everything
+playrig ae lib run my-effect --param comp=TEST --save-preview
+playrig ae lib index                     # rebuild INDEX.md (+ categories/, index.json)
+```
+
+**Guided way:** use the `create-ae-recipe` skill (`.claude/skills/create-ae-recipe/`): describe the effect and iterate with visual previews, or give it a reference video to break down frame by frame and convert into a recipe. It handles scratch comps, previews, the lint, and cleanup.
+
+**Easiest way:** finish a good effect in a real project and tell Claude: *"add the <thing> in comp X to the library"*. It inspects it through the bridge, writes the recipe file, tests it on a scratch comp, looks at the preview, saves it and re-indexes.
+
+`playrig ae lib check` enforces: id matches file name and kebab-case; category matches folder; required fields; summary length; valid param types and defaults (inside min/max); every `P.x` used by the script is declared; `composes_with` ids exist; the script parses and uses no ES3-forbidden syntax (`let`, `const`, `=>`, template literals, `JSON`, `forEach/map/filter`); ready recipes have previews; embedded images exist. Run it before committing.
+
+### Conventions (each came from a real bug)
+
+- **matchNames**, never display names (`"ADBE Text Animator"`, `"ADBE Vector Shape - Rect"`).
+- **ES3**: no `let/const`, arrow functions, `Array.indexOf/map/forEach`, `JSON`. The linter catches most.
+- Name parameters for what they do visually (`staggerFrames`, `popFrom`) and put units in `desc`. Give numbers sensible `min`/`max`.
+- Expressions use the JavaScript expression engine (After Effects default) and must be self-contained.
+- Never depend on a specific project: create what you need, find existing things by a parameter.
+- Order-sensitive recipes must say so in "Gotchas". Document what each setting does at low/high values in "Tweaks that matter": that table is what lets an agent tune a recipe without reading the script.
+- Test on a scratch comp, look at the frames, then save previews.
+
+## Scaling and housekeeping
+
+- Add a category by creating a folder under `recipes/` and (optionally) a line in `categories.json` for its description.
+- Past 40 recipes the index splits by category automatically (`INDEX_SPLIT_THRESHOLD` in the CLI (`playrig/lib/ae.js`)).
+- `index.json` is the machine-readable catalogue (all metadata + params + path), for tools that prefer JSON.
+- The library is just a folder. Copy it anywhere, or point to it with `--lib <dir>` / `AE_LIBRARY`. The scripts are plain ExtendScript; the Playrig for After Effects is only needed to run them.
+- Preview images live **next to the recipe** as `<id>--t<seconds>.png` and are embedded in its `## Preview` block (between `<!-- previews:start -->` and `<!-- previews:end -->` markers, kept up to date by `--save-preview`). Moving or copying a recipe means moving its `.md` and its `<id>--t*.png` files together.
+
+## Things to know
+
+- **Fonts** must be installed (After Effects substitutes silently). Defaults use Inter; pass `--param font=…` (PostScript name).
+- **Pixel defaults** (positions, areas) assume a 1920x1080 comp.
+- `text-cmy-split-scatter` only works on **light** backgrounds.
+
+## Layout
+
+```
+<library>/
+├── README.md              this file
+├── INDEX.md               level-0 router (generated)
+├── index.json             machine-readable catalogue (generated)
+├── categories.json        one-line description per category
+├── categories/<c>.md      per-category indexes (generated, only when the library is large)
+├── _common.jsx            shared helper functions appended to every script
+└── recipes/<category>/
+    ├── <id>.md
+    └── <id>--t<seconds>.png      its preview images
+```