@engine-room/after-effects-mcp 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engine-room/after-effects-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Control Adobe After Effects with AI — describe the animation you want and it gets built: layers, keyframes, effects, expressions and text, all editable afterwards.",
   "license": "MIT",

package/panel/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.2.0"
+<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.3.0"
                    ExtensionBundleName="AE MCP Bridge" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <ExtensionList>
-    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.2.0" />
+    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.3.0" />
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/panel/client/framecache.js

@@ -0,0 +1,98 @@
+// framecache.js — recent screenshot identity, for spotting a stale render.
+//
+// After Effects' render path sometimes answers a screenshot request with a
+// buffer it produced for an earlier one, and reports success either way. Nothing
+// else in the response distinguishes the two: the temp file is freshly named,
+// the op returns ok, the PNG is well formed. The one signal that survives is
+// content identity — two *different* requests coming back with byte-identical
+// pixels is not a coincidence, it is one buffer handed out twice. Reported and
+// evidenced as issue #29: byte-identical results for unrelated comps at
+// unrelated times, and at different downsample factors, which cannot even be the
+// same number of pixels.
+//
+// This lives in the panel rather than in the MCP server for two reasons. The
+// panel is the only thing that sees every render — the documented workaround for
+// this bug POSTs /op directly, and the check has to hold for that caller too.
+// And it outlives any one MCP client process, which is the right lifetime for
+// "what has this After Effects session rendered recently".
+//
+// Kept in its own file so tests/unit/frame-cache.mjs can require it without a
+// DOM or a running After Effects.
+
+"use strict";
+
+// Enough history to catch the bug — it shows up within a handful of calls — and
+// small enough that a long session cannot turn a linear scan into a cost.
+var DEFAULT_LIMIT = 24;
+// Long enough to span a working sequence of screenshots, short enough that a
+// comp genuinely edited between two visits is not compared against its own past.
+var DEFAULT_TTL_MS = 10 * 60 * 1000;
+
+function createFrameCache(options) {
+  var opts = options || {};
+  var limit = opts.limit || DEFAULT_LIMIT;
+  var ttlMs = opts.ttlMs || DEFAULT_TTL_MS;
+  var now = opts.now || function () { return Date.now(); };
+  var entries = [];
+
+  function prune() {
+    var cutoff = now() - ttlMs;
+    var kept = [];
+    for (var i = 0; i < entries.length; i++) {
+      if (entries[i].at > cutoff) kept.push(entries[i]);
+    }
+    entries = kept;
+  }
+
+  return {
+    /**
+     * The most recent *different* request that produced these exact pixels, or
+     * null. Matching the same key proves nothing: repeating a screenshot is
+     * allowed to return the same picture, and an agent retrying after a stale
+     * report must not be told the retry is stale too.
+     */
+    match: function (key, hash) {
+      prune();
+      for (var i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].hash === hash && entries[i].key !== key) {
+          return {
+            key: entries[i].key,
+            label: entries[i].label,
+            bytes: entries[i].bytes,
+            ageMs: now() - entries[i].at,
+          };
+        }
+      }
+      return null;
+    },
+
+    /**
+     * Record a frame that was actually delivered. Only successful, non-empty
+     * renders belong here: an empty frame is legitimately identical to every
+     * other empty frame, and remembering rejected ones would make the first
+     * stale buffer poison every later request that happens to repeat it.
+     */
+    remember: function (key, hash, meta) {
+      prune();
+      // One entry per request key, so re-running the same screenshot replaces
+      // its own record instead of filling the window with copies of itself.
+      var kept = [];
+      for (var i = 0; i < entries.length; i++) {
+        if (entries[i].key !== key) kept.push(entries[i]);
+      }
+      entries = kept;
+      entries.push({
+        key: key,
+        hash: hash,
+        at: now(),
+        label: (meta && meta.label) || key,
+        bytes: (meta && meta.bytes) || 0,
+      });
+      while (entries.length > limit) entries.shift();
+    },
+
+    size: function () { prune(); return entries.length; },
+  };
+}
+
+module.exports = { createFrameCache: createFrameCache };

package/panel/client/main.js

@@ -11,14 +11,12 @@
   var os = require("os");
   var http = require("http");
   var crypto = require("crypto");
-  var WebSocket;
-  try { WebSocket = require("ws"); }
-  catch (e) {
-    // ws is bundled in packages/ae-panel/node_modules; resolve manually if normal require fails.
-    var alt = path.join(__dirname, "..", "node_modules", "ws");
-    WebSocket = require(alt);
-  }
 
+  // The DOM handles and the logger come first so that everything below is able
+  // to report its own failure. `require("ws")` used to run before this point,
+  // so when it threw the exception escaped this whole function before a single
+  // line could be written — the panel sat on "starting…" indefinitely with the
+  // reason nowhere to be seen.
   var $status = document.getElementById("status");
   var $port = document.getElementById("port");
   var $ae = document.getElementById("ae");
@@ -41,8 +39,80 @@
     while ($log.childNodes.length > 80) $log.removeChild($log.lastChild);
   }
 
-  var cs = new CSInterface();
-  var extDir = cs.getSystemPath(SystemPath.EXTENSION);
+  // CSInterface comes from the plain <script> tag before this one, so it needs
+  // no require and is available here — which matters, because the extension
+  // path it reports is the only trustworthy anchor for everything below.
+  //
+  // __dirname is NOT that anchor. CEP anchors it at the *extension root* (where
+  // the manifest and node_modules live), not at the folder holding this file.
+  // That is why require("ws") resolves and a require of a file sitting right
+  // next to main.js does not.
+  var cs, extDir, clientDir;
+  try {
+    cs = new CSInterface();
+    extDir = cs.getSystemPath(SystemPath.EXTENSION);
+    clientDir = path.join(extDir, "client");
+  } catch (e) {
+    setStatus("cannot start — CSInterface is unavailable", "err");
+    log("error", "new CSInterface() failed: " + e.message);
+    return;
+  }
+
+  var WebSocket;
+  try { WebSocket = require("ws"); }
+  catch (primary) {
+    // ws is bundled at the extension root; resolve manually if normal require fails.
+    var alt = path.join(extDir, "node_modules", "ws");
+    try { WebSocket = require(alt); }
+    catch (fallback) {
+      // Nothing below can be built without ws, so this stops here — but it
+      // stops saying why, and naming the fix, rather than looking like a panel
+      // that is still starting up.
+      setStatus("cannot start — the ws module is missing", "err");
+      log("error", "require('ws') failed: " + primary.message);
+      log("error", "and " + alt + ": " + fallback.message);
+      log("error", "Quit After Effects, run the setup_panel tool, then reopen it.");
+      return;
+    }
+  }
+
+  // The screenshot checks live in their own files so a Node test can require
+  // them without a DOM: there is no After Effects on a CI runner, and neither
+  // real image code nor stale-buffer bookkeeping should be written blind.
+  // Same failure discipline as ws above — say what is missing, name the fix.
+  //
+  // The list is ordered by how much it is trusted, not by convenience.
+  // clientDir comes from CSInterface and is what the shipped layout actually
+  // is; the __dirname forms are kept behind it because a host build that
+  // anchors __dirname somewhere else again should degrade to a warning in the
+  // log rather than a panel that will not start.
+  function requireSibling(name) {
+    var candidates = [
+      path.join(clientDir, name),
+      path.join(__dirname, name),
+      path.join(__dirname, "client", name),
+      "./" + name,
+    ];
+    var failures = [];
+    for (var i = 0; i < candidates.length; i++) {
+      try { return require(candidates[i]); }
+      catch (e) { failures.push(candidates[i] + " (" + e.message.split("\n")[0] + ")"); }
+    }
+    throw new Error("could not load " + name + " from any of: " + failures.join("; "));
+  }
+  var pngCodec, frameCacheModule, mogrtModule;
+  try {
+    pngCodec = requireSibling("pngcodec.js");
+    frameCacheModule = requireSibling("framecache.js");
+    mogrtModule = requireSibling("mogrt.js");
+  } catch (e) {
+    setStatus("cannot start — pngcodec.js, framecache.js or mogrt.js is missing", "err");
+    log("error", "loading the panel's file-processing modules from " + __dirname + " failed: " + e.message);
+    log("error", "Quit After Effects, run the setup_panel tool, then reopen it.");
+    return;
+  }
+  var frameCache = frameCacheModule.createFrameCache();
+
   var bundlePath = path.join(extDir, "jsx", "bundle.jsx");
 
   // ---------- ExtendScript evalScript: serialized via Promise chain ----------
@@ -176,26 +246,109 @@
     return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
   }
 
+  function sha256(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+  }
+
   // Downsampling happens in ExtendScript via the comp's resolutionFactor, so
   // the file on disk is already the right size by the time we get here.
-  function readPngAsBase64(file) {
+  //
+  // What is *not* already right is the bit depth: a 16-bit project renders
+  // 16-bit-per-channel PNGs, which many decoders refuse outright. pngcodec
+  // converts those to 8-bit, tells us when the frame is entirely transparent,
+  // and hands back the decoded samples so a frame can be recognised if After
+  // Effects serves the same buffer again for a different request.
+  function readPngFrame(file) {
     // A cold render of a heavy 4K comp can take well over 15s — measured on a
     // real project. Five seconds silently failed screenshots that were simply
     // still rendering.
     return waitForPngFile(file, 120000).then(function () {
       var buf = fs.readFileSync(file);
-      var b64 = buf.toString("base64");
       try { fs.unlinkSync(file); } catch (e) {}
-      var dims = pngDimensions(buf);
+      var norm;
+      try {
+        norm = pngCodec.normalizePng(buf);
+      } catch (e) {
+        // A PNG this parser cannot read is still a PNG the client might. Ship
+        // it unchanged rather than throwing away a render that did happen — but
+        // say so, and fall back to hashing the file so the stale check survives.
+        log("warn", "could not normalise the frame (" + e.message + "); sending it unconverted");
+        var dims = pngDimensions(buf);
+        return {
+          buffer: buf,
+          width: dims ? dims.width : null,
+          height: dims ? dims.height : null,
+          empty: false,
+          hash: sha256(buf),
+          warning: "This frame could not be normalised to 8-bit (" + e.message +
+            ") and was sent exactly as After Effects wrote it. If it fails to decode, " +
+            "that is why.",
+        };
+      }
+      if (norm.empty) {
+        return { empty: true, width: norm.width, height: norm.height };
+      }
+      if (norm.converted) {
+        log("info", "converted a " + norm.bitDepth + "-bit frame to 8-bit (" +
+          buf.length + " -> " + norm.buffer.length + " bytes)");
+      }
       return {
-        base64: b64,
-        bytes: buf.length,
-        width: dims ? dims.width : null,
-        height: dims ? dims.height : null,
+        buffer: norm.buffer,
+        width: norm.width,
+        height: norm.height,
+        empty: false,
+        converted: norm.converted,
+        sourceBitDepth: norm.bitDepth,
+        hash: sha256(norm.hashInput),
+        // The pixels could not be read, so "empty" was never evaluated and the
+        // hash is of the compressed stream. Both are still better than nothing;
+        // saying which is what stops a later reader trusting the wrong one.
+        warning: norm.passthrough
+          ? "This frame's pixels were not inspected (" + norm.passthrough +
+            "), so it was sent exactly as After Effects wrote it."
+          : undefined,
       };
     });
   }
 
+  // ---------- Stale render detection ----------
+  // The request identity a render is expected to be unique to. Built from what
+  // ExtendScript resolved, not from the arguments, so a defaulted time or
+  // downsample is compared as the value actually rendered.
+  function frameKey(op, info) {
+    var layer = (info.layerId === undefined || info.layerId === null) ? "-" : info.layerId;
+    return [op, info.compId, layer, Number(info.time).toFixed(6), info.downsample].join("|");
+  }
+  function frameLabel(op, info) {
+    return "comp " + info.compId +
+      ((info.layerId === undefined || info.layerId === null) ? "" : " layer " + info.layerId) +
+      " @ " + Number(info.time).toFixed(3) + "s downsample " + info.downsample;
+  }
+  // An error rather than a warning attached to the image, because an agent that
+  // can see the picture will believe the picture. It carries the whole
+  // workaround: there is nothing this panel can do to make the render happen.
+  function staleFrameError(label, match, bytes) {
+    var ago = Math.max(1, Math.round(match.ageMs / 1000));
+    var err = new Error(
+      "Stale frame: After Effects returned pixels identical to an earlier, different " +
+      "request (" + match.label + ", " + match.bytes + " bytes, " + ago + "s ago), so this " +
+      "image is not a picture of " + label + " (" + bytes + " bytes) and has not been sent.\n" +
+      "\n" +
+      "What to do next:\n" +
+      "1. Wait a few seconds — back-to-back screenshots trigger this far more often.\n" +
+      "2. Retry with a higher `downsample` (6 has worked where 3-4 stayed stale).\n" +
+      "3. If it repeats, verify the animation by reading keyframes (get_keyframes / " +
+      "get_layer_full) instead. That is exact; a picture is not.\n" +
+      "\n" +
+      "Do NOT start disabling layers to make the render succeed: this is a limit of the " +
+      "panel's render path, not a problem with the project. If those two frames really " +
+      "are identical — a static comp — a different `downsample` will render a different " +
+      "number of pixels and confirm it."
+    );
+    err.code = "STALE_FRAME";
+    return err;
+  }
+
   // ---------- Long job continuation loop ----------
   function driveJob(jobId, progressToken) {
     var totalGuess = null;
@@ -218,12 +371,92 @@
     return step();
   }
 
+  // ---------- Motion Graphics template thumbnail ----------
+  // ExtendScript can render the poster frame but cannot rewrite a zip, so the
+  // JSX side hands back a PNG path and the archive surgery happens here.
+  //
+  // A failed patch is reported on an otherwise successful result, never thrown:
+  // the .mogrt is already written and valid at this point, and throwing away a
+  // successful export because its thumbnail could not be improved would be the
+  // worse trade. The result says plainly that the thumbnail is still AE's.
+  function patchMogrtThumbnail(info) {
+    return waitForPngFile(info.posterPngPath, 120000).then(function () {
+      var poster = fs.readFileSync(info.posterPngPath);
+      try { fs.unlinkSync(info.posterPngPath); } catch (e) {}
+      var patched = mogrtModule.patchThumbnail(fs.readFileSync(info.path), poster);
+      // Write via a sibling temp file and rename, so an interrupted write
+      // cannot leave a half-rewritten template where a valid one used to be.
+      var tmp = info.path + ".tmp-thumb";
+      fs.writeFileSync(tmp, patched.buffer);
+      fs.renameSync(tmp, info.path);
+      return {
+        patched: true,
+        posterTime: info.posterTime,
+        width: patched.width,
+        height: patched.height,
+        sourceWidth: patched.sourceWidth,
+        sourceHeight: patched.sourceHeight,
+        letterboxed: patched.letterboxed || undefined,
+      };
+    }).catch(function (e) {
+      try { fs.unlinkSync(info.posterPngPath); } catch (e2) {}
+      log("warn", "could not patch the .mogrt thumbnail: " + e.message);
+      return {
+        patched: false,
+        posterTime: info.posterTime,
+        reason: "The template exported correctly, but its thumbnail could not be replaced (" +
+          e.message + "). It still shows the one After Effects wrote.",
+      };
+    });
+  }
+
   // ---------- Op handler with vision/job specialization ----------
   function handleOp(op, args, progressToken) {
+    // Export writes the .mogrt; the thumbnail it wants is a second file that
+    // has to be folded into it afterwards.
+    if (op === "export_mogrt") {
+      return runOp(op, args).then(function (info) {
+        if (!info || !info.posterPngPath) return info;
+        return patchMogrtThumbnail(info).then(function (thumbnail) {
+          var out = {};
+          for (var k in info) { if (info.hasOwnProperty(k) && k !== "posterPngPath") out[k] = info[k]; }
+          out.thumbnail = thumbnail;
+          // The file changed size when the thumbnail was replaced, and the
+          // reported number has to be the one on disk.
+          try { out.bytes = fs.statSync(info.path).size; } catch (e) {}
+          return out;
+        });
+      });
+    }
     // Vision ops: run JSX, then read PNG and base64-encode on Node side.
     if (op === "screenshot_frame" || op === "screenshot_layer") {
       return runOp(op, args).then(function (info) {
-        return readPngAsBase64(info.path).then(function (img) {
+        return readPngFrame(info.path).then(function (img) {
+          // A frame with nothing in it is a fact about the composition, not a
+          // failure — and the ~5KB PNG that encodes it is the one decoders
+          // reject. Report it, cheaply, instead of shipping an image nobody can
+          // read and calling that a successful screenshot.
+          if (img.empty) {
+            return {
+              empty: true,
+              width: img.width,
+              height: img.height,
+              fullWidth: info.width,
+              fullHeight: info.height,
+              downsample: info.downsample,
+              time: info.time,
+              compId: info.compId,
+              layerId: info.layerId,
+              reason: "Every pixel of this frame is fully transparent — the frame is empty. " +
+                "No image was sent because there is nothing in it to see. Usually this means " +
+                "the time is outside the layers' in/out points, the layers are disabled or " +
+                "have zero opacity, or the wrong comp was addressed.",
+            };
+          }
+          var key = frameKey(op, info);
+          var match = frameCache.match(key, img.hash);
+          if (match) throw staleFrameError(frameLabel(op, info), match, img.buffer.length);
+          frameCache.remember(key, img.hash, { label: frameLabel(op, info), bytes: img.buffer.length });
           return {
             // Dimensions come from the PNG itself, not from arithmetic on the
             // comp size, so they cannot disagree with the image sent.
@@ -236,8 +469,13 @@
             compId: info.compId,
             layerId: info.layerId,
             mimeType: "image/png",
-            base64: img.base64,
-            bytes: img.bytes,
+            base64: img.buffer.toString("base64"),
+            bytes: img.buffer.length,
+            // Only present when the frame was not 8-bit as rendered, so the
+            // metadata stays quiet on the ordinary path.
+            converted: img.converted ? true : undefined,
+            sourceBitDepth: img.converted ? img.sourceBitDepth : undefined,
+            warning: img.warning,
           };
         });
       });
@@ -306,7 +544,10 @@
               .catch(function (err) {
                 log("error", body.op + ": " + err.message);
                 res.statusCode = 500; res.setHeader("content-type", "application/json");
-                res.end(JSON.stringify({ ok: false, error: err.message, stack: err.aeStack, line: err.aeLine }));
+                // `code` marks a failure the panel diagnosed itself rather than
+                // one ExtendScript raised, so the server can present it as what
+                // it is instead of prefixing it as an After Effects error.
+                res.end(JSON.stringify({ ok: false, error: err.message, code: err.code, stack: err.aeStack, line: err.aeLine }));
               });
             return;
           }