@engine-room/after-effects-mcp 0.3.1 → 0.5.0

package/panel/client/main.js

@@ -100,13 +100,15 @@
     }
     throw new Error("could not load " + name + " from any of: " + failures.join("; "));
   }
-  var pngCodec, frameCacheModule, mogrtModule;
+  var pngCodec, frameCacheModule, mogrtModule, contactSheetModule, frameReaderModule;
   try {
     pngCodec = requireSibling("pngcodec.js");
     frameCacheModule = requireSibling("framecache.js");
     mogrtModule = requireSibling("mogrt.js");
+    contactSheetModule = requireSibling("contactsheet.js");
+    frameReaderModule = requireSibling("framereader.js");
   } catch (e) {
-    setStatus("cannot start — pngcodec.js, framecache.js or mogrt.js is missing", "err");
+    setStatus("cannot start — one of the panel's file-processing modules 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;
@@ -148,6 +150,20 @@
         var err = new Error(msg);
         err.aeStack = parsed.stack;
         err.aeLine = parsed.line;
+        // Where the failure sits in the caller's *own* source, when the handler
+        // could work it out — run_jsx maps AE's line number back onto the
+        // script that was submitted (issue #46). Forwarded field by field on
+        // purpose: the server prints these, and relaying a free-form bag would
+        // let the two drift apart with nothing to notice.
+        if (parsed.sourceLine !== undefined || parsed.rawLine !== undefined) {
+          err.aeSource = {
+            sourceLine: parsed.sourceLine,
+            sourceText: parsed.sourceText,
+            sourceName: parsed.sourceName,
+            rawLine: parsed.rawLine,
+            lineCount: parsed.lineCount
+          };
+        }
         throw err;
       }
       return parsed.result;
@@ -196,10 +212,68 @@
   }
 
   // ---------- Port file (so MCP server can discover) ----------
+  // Written only once a port is actually bound, and only with that port. The
+  // file is a hint for the server, never the authority — the socket is — and
+  // the one way it lies is by describing a bind that did not happen or a panel
+  // that has since gone (issue #92). So it is written after `listen` succeeds
+  // and removed again on unload, and never with a port this panel merely tried.
+  var portDir = path.join(os.homedir(), ".engineroom-ae-mcp");
+  var portFile = path.join(portDir, "port");
+  var configFile = path.join(portDir, "config.json");
+
   function writePortFile(port) {
-    var dir = path.join(os.homedir(), ".engineroom-ae-mcp");
-    try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
-    try { fs.writeFileSync(path.join(dir, "port"), String(port), "utf8"); } catch (e) { log("warn", "could not write port file: " + e.message); }
+    try { fs.mkdirSync(portDir, { recursive: true }); } catch (e) {}
+    try { fs.writeFileSync(portFile, String(port), "utf8"); } catch (e) { log("warn", "could not write port file: " + e.message); }
+  }
+
+  // Only this panel's own entry. Another panel may have written the file since
+  // — a second After Effects instance, say — and its port is not ours to erase.
+  function removePortFile(port) {
+    try {
+      if (fs.readFileSync(portFile, "utf8").trim() === String(port)) fs.unlinkSync(portFile);
+    } catch (e) {}
+  }
+
+  // ---------- Config ----------
+  // A CEP panel cannot read an environment variable the user set: it runs in
+  // After Effects' process, with Adobe's environment. So its two knobs live in
+  // a JSON file beside the port file, ~/.engineroom-ae-mcp/config.json:
+  //
+  //   { "port": 7777, "allowPortWalk": false }
+  //
+  //   port          the port to bind. Default 7777. 0 binds an ephemeral port,
+  //                 which is what the offline tests use.
+  //   allowPortWalk when the port is held by another AE MCP panel, move to the
+  //                 next free one instead of waiting for it. For people who run
+  //                 two After Effects instances at once. Off by default: on one
+  //                 machine the holder is a zombie, and walking around it is
+  //                 what issue #92 was.
+  //
+  // Anything unreadable is logged and ignored; the defaults are what shipped.
+  var DEFAULT_PORT = 7777;
+  function readConfig() {
+    var cfg = { port: DEFAULT_PORT, allowPortWalk: false, bindRetryMs: 2000, source: null };
+    var raw;
+    try { raw = fs.readFileSync(configFile, "utf8"); } catch (e) { return cfg; }
+    var parsed;
+    try { parsed = JSON.parse(raw); }
+    catch (e) { log("warn", "ignoring " + configFile + " — not valid JSON (" + e.message + ")"); return cfg; }
+    if (!parsed || typeof parsed !== "object") {
+      log("warn", "ignoring " + configFile + " — expected a JSON object");
+      return cfg;
+    }
+    cfg.source = configFile;
+    if (parsed.port !== undefined) {
+      if (typeof parsed.port === "number" && parsed.port >= 0 && parsed.port <= 65535 && parsed.port === Math.floor(parsed.port)) cfg.port = parsed.port;
+      else log("warn", "ignoring \"port\" in " + configFile + " — expected a whole number 0-65535, got " + JSON.stringify(parsed.port));
+    }
+    if (parsed.allowPortWalk !== undefined) {
+      if (typeof parsed.allowPortWalk === "boolean") cfg.allowPortWalk = parsed.allowPortWalk;
+      else log("warn", "ignoring \"allowPortWalk\" in " + configFile + " — expected true or false");
+    }
+    // Undocumented on purpose: how often to retry a held port. Tests shorten it.
+    if (typeof parsed.bindRetryMs === "number" && parsed.bindRetryMs >= 50) cfg.bindRetryMs = parsed.bindRetryMs;
+    return cfg;
   }
 
   // ---------- WS broadcast ----------
@@ -212,39 +286,16 @@
   }
 
   // ---------- Vision: read PNG and base64-encode (for screenshot_* ops) ----------
-  function waitForPngFile(file, maxMs) {
-    var deadline = Date.now() + (maxMs || 3000);
-    return new Promise(function (resolve, reject) {
-      (function poll() {
-        try {
-          if (fs.existsSync(file)) {
-            var stat = fs.statSync(file);
-            // Reasonable size + ensure not currently being written (re-check)
-            if (stat.size > 64) {
-              setTimeout(function () {
-                try {
-                  var stat2 = fs.statSync(file);
-                  if (stat2.size === stat.size) return resolve(stat2.size);
-                } catch (e) {}
-                if (Date.now() > deadline) return reject(new Error("PNG file write timed out"));
-                poll();
-              }, 30);
-              return;
-            }
-          }
-        } catch (e) {}
-        if (Date.now() > deadline) return reject(new Error("PNG file did not appear: " + file));
-        setTimeout(poll, 40);
-      })();
-    });
-  }
-  // Read the true pixel dimensions out of the PNG's IHDR chunk rather than
-  // computing them, so what we report is always what the client received.
-  function pngDimensions(buf) {
-    if (buf.length < 24) return null;
-    if (buf.readUInt32BE(12) !== 0x49484452) return null; // "IHDR"
-    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
-  }
+  // Deciding when After Effects has finished writing a frame is issue #45, and
+  // it lives in framereader.js so a unit test can drive it with a file it grows
+  // by hand. What matters here: `waitForCompletePng` resolves only with bytes
+  // that parse end-to-end as a PNG, deletes the temp file on every path, and
+  // rejects with FRAME_INCOMPLETE or RENDER_TIMEOUT — never with one message
+  // covering both.
+  var waitForCompletePng = frameReaderModule.waitForCompletePng;
+  var dressFrameError = frameReaderModule.dressFrameError;
+  var frameError = frameReaderModule.frameError;
+  var unlinkQuietly = frameReaderModule.unlinkQuietly;
 
   function sha256(bytes) {
     return crypto.createHash("sha256").update(bytes).digest("hex");
@@ -259,19 +310,25 @@
   // 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);
-      try { fs.unlinkSync(file); } catch (e) {}
+    // waitForCompletePng owns the temp file and removes it on every path,
+    // success or failure. A file left behind is one a later read could find,
+    // which is how a corrupt frame would start coming back for free.
+    return waitForCompletePng(file).then(function (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.
+        // The completeness gate above guarantees this file ends in a well-formed
+        // IEND, so a truncation error here would mean the gate is broken. Refuse
+        // rather than ship: "never report success for work that didn't happen"
+        // outranks the fallback below.
+        if (/truncated PNG/.test(e.message)) {
+          throw frameError("FRAME_INCOMPLETE", "the file passed the completeness check and then failed to parse (" + e.message + ")");
+        }
+        // A complete 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 {
@@ -299,6 +356,11 @@
         empty: false,
         converted: norm.converted,
         sourceBitDepth: norm.bitDepth,
+        // Decoded samples, kept only so the contact sheet can composite them
+        // without decoding the same PNG a second time. Null on the passthrough
+        // path, where the pixels were never interpreted.
+        pixels: norm.decoded ? norm.hashInput : null,
+        channels: norm.channels,
         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;
@@ -311,6 +373,55 @@
     });
   }
 
+  // Read the true pixel dimensions out of the PNG's IHDR chunk rather than
+  // computing them, so what we report is always what the client received.
+  function pngDimensions(buf) {
+    if (buf.length < 24) return null;
+    if (buf.readUInt32BE(12) !== 0x49484452) return null; // "IHDR"
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+
+  // ---------- Rendering one frame, with one bounded retry ----------
+  function renderFrameOnce(op, args) {
+    return runOp(op, args).then(function (info) {
+      return readPngFrame(info.path).then(function (img) {
+        return { info: info, img: img };
+      });
+    });
+  }
+
+  /**
+   * Render a frame, and re-render exactly once if what came back was corrupt.
+   *
+   * Safe to repeat, which is the only reason this is here. Both screenshot ops
+   * are read-only: `screenshot_frame` renders to a temp file, `screenshot_layer`
+   * additionally solos a layer and restores every solo state in a `finally`.
+   * Neither leaves anything in the project, so a second run is
+   * indistinguishable from one run — this is not `run_jsx`, where re-running a
+   * script that already had its side effects duplicates them (issue #43).
+   *
+   * Only on FRAME_INCOMPLETE, never on RENDER_TIMEOUT. A timeout has already
+   * spent the 120s budget; a second one would take the op past the server's
+   * 300s ceiling and turn a precise "the render did not finish" into a bridge
+   * timeout, whose remedy ("do not restart anything, wait") is a different
+   * remedy for a different problem. A corrupt read, by contrast, fails within
+   * FRAME_STALL_MS, and the evidence in #45 is that a retry sometimes succeeds
+   * — a light comp returned one truncated frame and then rendered.
+   *
+   * The temp file of a failed attempt is deleted before the retry (in
+   * `waitForCompletePng`), and ExtendScript names a fresh one per call, so a
+   * retry can never be handed the previous attempt's bytes.
+   */
+  function renderFrameWithRetry(op, args) {
+    return renderFrameOnce(op, args).catch(function (first) {
+      if (first.code !== "FRAME_INCOMPLETE") throw dressFrameError(first, 1);
+      log("warn", op + ": " + first.detail + " — re-rendering once");
+      return renderFrameOnce(op, args).catch(function (second) {
+        throw dressFrameError(second, 2);
+      });
+    });
+  }
+
   // ---------- 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
@@ -350,10 +461,17 @@
   }
 
   // ---------- Long job continuation loop ----------
-  function driveJob(jobId, progressToken) {
+  // Each turn of this loop is one evalScript, and each one now opens and closes
+  // its own undo group inside itself — a group cannot span two calls, because
+  // After Effects discards one that does (issue #69). So the chunk size is not
+  // only a pacing knob any more: it decides how many undo steps a long batch
+  // costs the user. It comes off the job envelope so the JSX side owns the
+  // number and the two cannot drift.
+  function driveJob(jobId, progressToken, chunkSize) {
     var totalGuess = null;
+    var size = chunkSize || 25;
     function step() {
-      return runOp("_continue_job", { jobId: jobId, chunkSize: 25 }).then(function (res) {
+      return runOp("_continue_job", { jobId: jobId, chunkSize: size }).then(function (res) {
         if (res.total) totalGuess = res.total;
         if (!res.done) {
           broadcast({ type: "progress", jobId: jobId, progress: res.progress, total: res.total, message: "running" });
@@ -361,11 +479,37 @@
           return new Promise(function (r) { setTimeout(r, 0); }).then(step);
         }
         if (res.failed) {
-          broadcast({ type: "error", jobId: jobId, error: res.error || "batch failed" });
-          return { done: true, failed: true, jobId: jobId, error: res.error, results: res.results, errors: res.errors, atIndex: res.atIndex };
+          // A failed job reaches the server as an error string and nothing else,
+          // so what the batch cost has to travel inside it or it is lost: the
+          // ops before the failure are applied and stay applied.
+          var failedMsg = (res.error || "batch failed") + (res.note ? " || " + res.note : "");
+          broadcast({ type: "error", jobId: jobId, error: failedMsg });
+          return { done: true, failed: true, jobId: jobId, error: res.error, results: res.results, errors: res.errors, atIndex: res.atIndex, undoSteps: res.undoSteps, note: res.note };
         }
-        broadcast({ type: "complete", jobId: jobId, result: { results: res.results, errors: res.errors, total: res.total || totalGuess, cancelled: !!res.cancelled } });
-        return { done: true, jobId: jobId, results: res.results, errors: res.errors, total: res.total || totalGuess, cancelled: !!res.cancelled };
+        // `undoSteps` is the measured number of undo groups the batch opened,
+        // and `diff` is the batch's own before/after — both are only ever seen
+        // by the agent if they are carried on this event.
+        broadcast({
+          type: "complete",
+          jobId: jobId,
+          result: {
+            results: res.results,
+            errors: res.errors,
+            total: res.total || totalGuess,
+            cancelled: !!res.cancelled,
+            undoSteps: res.undoSteps,
+            undoGroupName: res.undoGroupName,
+            note: res.note,
+            diff: res.diff,
+          },
+        });
+        return {
+          done: true, jobId: jobId,
+          results: res.results, errors: res.errors,
+          total: res.total || totalGuess, cancelled: !!res.cancelled,
+          undoSteps: res.undoSteps, undoGroupName: res.undoGroupName,
+          note: res.note, diff: res.diff,
+        };
       });
     }
     return step();
@@ -380,9 +524,12 @@
   // 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) {}
+    // The same completeness gate the screenshot path uses. The poster frame is
+    // written by the same asynchronous `saveFrameToPng`, so a half-written one
+    // is just as possible here — and it would be resampled into the template's
+    // thumbnail rather than merely displayed.
+    // It takes the poster file with it, on success and on failure alike.
+    return waitForCompletePng(info.posterPngPath).then(function (poster) {
       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.
@@ -399,7 +546,7 @@
         letterboxed: patched.letterboxed || undefined,
       };
     }).catch(function (e) {
-      try { fs.unlinkSync(info.posterPngPath); } catch (e2) {}
+      unlinkQuietly(info.posterPngPath);
       log("warn", "could not patch the .mogrt thumbnail: " + e.message);
       return {
         patched: false,
@@ -410,6 +557,203 @@
     });
   }
 
+  // ---------- Contact sheet ----------
+  //
+  // ExtendScript renders every requested time and hands back one temp path per
+  // tile; everything from here on is pixels, which `packages/jsx` has no way to
+  // touch. One tile that fails is drawn as a marked block rather than dropped —
+  // the sheet has to keep mapping onto the times that were asked for, or an
+  // agent counting frames left to right reads the wrong one as the right one.
+
+  /** One line, for a note inside a tile rather than a whole error message. */
+  function shortReason(err) {
+    var s = err && err.detail ? err.detail : (err && err.message ? err.message : String(err));
+    return String(s).split("\n")[0];
+  }
+
+  function readSheetTile(info, tile) {
+    if (tile.error) {
+      return Promise.resolve({ time: tile.time, status: "failed", note: tile.error });
+    }
+    return readPngFrame(tile.path).then(function (img) {
+      return { time: tile.time, status: "ok", img: img };
+    }, function (err) {
+      if (err.code !== "FRAME_INCOMPLETE") {
+        return { time: tile.time, status: "failed", note: shortReason(err) };
+      }
+      // The same bounded retry the single-frame path gets, and safe for the same
+      // reason — but re-rendering only this one time. The already-derived
+      // downsample is passed explicitly so the per-tile factor cannot drift from
+      // the rest of the sheet.
+      log("warn", "contact sheet tile at " + tile.time + "s: " + shortReason(err) + " — re-rendering once");
+      return runOp("screenshot_frame", {
+        compId: info.compId,
+        time: tile.time,
+        downsample: info.downsample,
+      }).then(function (retry) {
+        return readPngFrame(retry.path).then(function (img) {
+          return { time: tile.time, status: "ok", img: img };
+        });
+      }).catch(function (again) {
+        return { time: tile.time, status: "failed", note: shortReason(again) };
+      });
+    });
+  }
+
+  function finishContactSheet(info, read) {
+    var i;
+    var ds = info.downsample;
+    // Pass one: classify. Every `match` is computed before any `remember`, so a
+    // sheet's own tiles cannot collide with each other through the cache.
+    var seen = {};
+    for (i = 0; i < read.length; i++) {
+      var t = read[i];
+      if (t.status !== "ok") continue;
+      if (t.img.empty) { t.status = "empty"; t.img = null; continue; }
+      var ident = { compId: info.compId, layerId: null, time: t.time, downsample: ds };
+      t.key = frameKey("screenshot_frame", ident);
+      var match = frameCache.match(t.key, t.img.hash);
+      if (match) {
+        // Pixels identical to an *earlier, different* request are the #29 stale
+        // buffer, and a tile of them is not a picture of this time. Mark the
+        // block rather than showing it: an agent that can see a frame believes
+        // the frame.
+        t.status = "stale";
+        t.note = "identical to " + match.label + ", rendered " +
+          Math.max(1, Math.round(match.ageMs / 1000)) + "s earlier";
+        t.img = null;
+        continue;
+      }
+      // Two tiles of one sheet matching each other is what a static comp looks
+      // like — the caller asked for several times on purpose, and refusing the
+      // second would be a false alarm on a correct answer. Flagged, not refused.
+      if (seen[t.img.hash] !== undefined) {
+        t.note = "pixel-identical to the " + contactSheetModule.formatTime(seen[t.img.hash]) +
+          " tile — nothing changed between them";
+      } else {
+        seen[t.img.hash] = t.time;
+      }
+    }
+
+    var specs = [];
+    var ok = 0;
+    for (i = 0; i < read.length; i++) {
+      var r = read[i];
+      var spec = { time: r.time, status: r.status, note: r.note };
+      if (r.status === "ok") {
+        var px = r.img.pixels;
+        var channels = r.img.channels;
+        if (!px) {
+          // The passthrough path never interpreted the pixels. A sheet needs
+          // them, so decode strictly here; a frame that cannot be decoded
+          // becomes a marked block rather than a wrong one.
+          try {
+            var dec = pngCodec.decodePng8(r.img.buffer);
+            px = dec.pixels;
+            channels = dec.channels;
+          } catch (e) {
+            // Both records move together: `spec` is what gets drawn, `r` is what
+            // the cache loop below reads, and a frame that is not delivered must
+            // not be remembered as if it were.
+            spec.status = "failed";
+            r.status = "failed";
+            spec.note = "the frame could not be decoded for tiling (" + e.message + ")";
+          }
+        }
+        if (spec.status === "ok") {
+          spec.pixels = px;
+          spec.channels = channels;
+          spec.width = r.img.width;
+          spec.height = r.img.height;
+          ok++;
+        }
+      }
+      specs.push(spec);
+    }
+
+    if (!ok) {
+      var why = [];
+      for (i = 0; i < specs.length; i++) {
+        why.push(contactSheetModule.formatTime(specs[i].time) + ": " + specs[i].status +
+          (specs[i].note ? " (" + specs[i].note + ")" : ""));
+      }
+      var dead = new Error(
+        "No tile of the contact sheet rendered, so there is no sheet to send. Per time:\n" +
+        why.join("\n") + "\n\n" +
+        "A sheet of coloured blocks is not a screenshot. Retry at a higher `downsample`, " +
+        "or screenshot the shot precomps one at a time; if it repeats, read keyframes " +
+        "(get_keyframes / get_layer_full) instead."
+      );
+      dead.code = "CONTACT_SHEET_FAILED";
+      throw dead;
+    }
+
+    // The expected cell size, used only for the cells with no picture. A tile
+    // that rendered is the authority on its own dimensions.
+    var sheet = contactSheetModule.composeContactSheet(specs, {
+      cellWidth: Math.round(info.width / ds),
+      cellHeight: Math.round(info.height / ds),
+    });
+
+    // Only what is actually being delivered goes into the cache.
+    for (i = 0; i < read.length; i++) {
+      if (read[i].status === "ok" && read[i].key) {
+        frameCache.remember(read[i].key, read[i].img.hash, {
+          label: frameLabel("screenshot_frame", { compId: info.compId, time: read[i].time, downsample: ds }),
+          bytes: read[i].img.buffer.length,
+        });
+      }
+    }
+
+    var bad = [];
+    for (i = 0; i < sheet.tiles.length; i++) {
+      if (sheet.tiles[i].status !== "ok") {
+        bad.push(sheet.tiles[i].label + (sheet.tiles[i].note ? " — " + sheet.tiles[i].note : ""));
+      }
+    }
+
+    return {
+      contactSheet: true,
+      width: sheet.width,
+      height: sheet.height,
+      cols: sheet.cols,
+      rows: sheet.rows,
+      cellWidth: sheet.cellWidth,
+      cellHeight: sheet.cellHeight,
+      fullWidth: info.width,
+      fullHeight: info.height,
+      downsample: ds,
+      compId: info.compId,
+      tiles: sheet.tiles,
+      mimeType: "image/png",
+      base64: sheet.buffer.toString("base64"),
+      bytes: sheet.buffer.length,
+      // Named and counted, because a sheet that looks complete and is not is the
+      // same class of lie as a swallowed error.
+      warning: bad.length
+        ? bad.length + " of " + sheet.tiles.length + " tiles are marked blocks, not frames: " + bad.join("; ")
+        : undefined,
+    };
+  }
+
+  function renderContactSheet(args) {
+    return runOp("screenshot_frame", args).then(function (info) {
+      var jsxTiles = info.tiles || [];
+      // Sequentially: `evalScript` is a mutex anyway, a per-tile retry re-enters
+      // ExtendScript, and reading them in order keeps the panel log legible.
+      var read = [];
+      var chain = Promise.resolve();
+      for (var i = 0; i < jsxTiles.length; i++) {
+        chain = chain.then(function (tile) {
+          return function () {
+            return readSheetTile(info, tile).then(function (res) { read.push(res); });
+          };
+        }(jsxTiles[i]));
+      }
+      return chain.then(function () { return finishContactSheet(info, read); });
+    });
+  }
+
   // ---------- Op handler with vision/job specialization ----------
   function handleOp(op, args, progressToken) {
     // Export writes the .mogrt; the thumbnail it wants is a second file that
@@ -430,36 +774,19 @@
     }
     // 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 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 });
+      if (op === "screenshot_frame" && args && args.times && args.times.length) {
+        return renderContactSheet(args);
+      }
+      return renderFrameWithRetry(op, args).then(function (r) {
+        var info = r.info;
+        var img = r.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 {
-            // Dimensions come from the PNG itself, not from arithmetic on the
-            // comp size, so they cannot disagree with the image sent.
+            empty: true,
             width: img.width,
             height: img.height,
             fullWidth: info.width,
@@ -468,16 +795,41 @@
             time: info.time,
             compId: info.compId,
             layerId: info.layerId,
-            mimeType: "image/png",
-            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,
+            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.",
           };
-        });
+        }
+        // Only a frame that read cleanly ever reaches the cache. A corrupt read
+        // is rejected above and never remembered — before the completeness gate
+        // existed, a truncated file was hashed and recorded here, so the next
+        // truncation at the same byte count was reported as a stale buffer and
+        // the real fault was hidden behind the wrong diagnosis.
+        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.
+          width: img.width,
+          height: img.height,
+          fullWidth: info.width,
+          fullHeight: info.height,
+          downsample: info.downsample,
+          time: info.time,
+          compId: info.compId,
+          layerId: info.layerId,
+          mimeType: "image/png",
+          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,
+        };
       });
     }
     // Long batches: returns {jobId, async, total}. We kick off background drive
@@ -485,10 +837,21 @@
     if (op === "run_batch") {
       return runOp(op, args).then(function (res) {
         if (res && res.async && res.jobId) {
-          driveJob(res.jobId, progressToken).catch(function (e) {
+          driveJob(res.jobId, progressToken, res.chunkSize).catch(function (e) {
             broadcast({ type: "error", jobId: res.jobId, error: e.message });
           });
-          return { jobId: res.jobId, async: true, total: res.total };
+          // The undo fields ride out with the envelope so the agent is told the
+          // batch will be several steps *before* it goes and says otherwise —
+          // the final count arrives much later, on the completion event.
+          return {
+            jobId: res.jobId,
+            async: true,
+            total: res.total,
+            chunkSize: res.chunkSize,
+            undoStepsEstimate: res.undoStepsEstimate,
+            undoGroupName: res.undoGroupName,
+            note: res.note,
+          };
         }
         return res; // small batch: inline result already
       });
@@ -509,9 +872,15 @@
           res.setHeader("content-type", "application/json");
           // bundleHash identifies the code this panel is *running*, which is what
           // the server needs to know before sending an op the panel may predate.
+          // `ok` + `bundleHash` is also how another copy of this panel, and the
+          // server's discovery, recognise this as an AE MCP panel — see
+          // isOurHealth below and isPanelHealth in the server's discovery.ts.
+          // The port is read off the socket, not the argument: port 0 binds an
+          // ephemeral one and the argument would say 0.
+          var addr = server.address();
           res.end(JSON.stringify({
             ok: true,
-            port: port,
+            port: addr && addr.port ? addr.port : port,
             bundleLoaded: true,
             bundleHash: loadedBundleHash,
             ts: Date.now()
@@ -547,7 +916,7 @@
                 // `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 }));
+                res.end(JSON.stringify({ ok: false, error: err.message, code: err.code, stack: err.aeStack, line: err.aeLine, source: err.aeSource }));
               });
             return;
           }
@@ -582,26 +951,156 @@
     });
   }
 
-  function startServers(startPort) {
-    var tries = 0;
-    function attempt(p) {
-      tries++;
+  // ---------- Who holds the port? ----------
+  // The same test the server's discovery makes (isPanelHealth in discovery.ts):
+  // `ok` plus `bundleHash` — or `bundleLoaded`, on a panel from before the hash
+  // existed — is what nothing else on a loopback port would answer with.
+  function isOurHealth(body) {
+    return !!body && typeof body === "object" && body.ok === true &&
+      ("bundleHash" in body || "bundleLoaded" in body);
+  }
+
+  // Never rejects: every outcome is a classification the caller acts on.
+  //   panel  — another AE MCP panel; its health body is attached
+  //   other  — something answered, but not as the panel
+  //   silent — accepted the connection and said nothing, or errored
+  function identifyHolder(port) {
+    return new Promise(function (resolve) {
+      var done = false;
+      function finish(r) { if (!done) { done = true; resolve(r); } }
+      var req = http.get({ host: "127.0.0.1", port: port, path: "/health", timeout: 1500 }, function (res) {
+        var bufs = [];
+        res.on("data", function (c) { bufs.push(c); });
+        res.on("end", function () {
+          var body = null;
+          try { body = JSON.parse(Buffer.concat(bufs).toString("utf8")); } catch (e) {}
+          if (res.statusCode === 200 && isOurHealth(body)) finish({ kind: "panel", health: body });
+          else finish({ kind: "other", detail: "answered HTTP " + res.statusCode + (body ? " with an unfamiliar body" : " with no JSON") });
+        });
+        res.on("error", function (e) { finish({ kind: "silent", detail: e.message }); });
+      });
+      req.on("timeout", function () { req.destroy(); finish({ kind: "silent", detail: "accepted the connection but did not answer within 1.5s" }); });
+      req.on("error", function (e) { finish({ kind: "silent", detail: e.message }); });
+    });
+  }
+
+  // 7777 through 7799 was the old ceiling; kept as a distance so a configured
+  // start port walks the same number of steps.
+  var WALK_LIMIT = 22;
+
+  /**
+   * Bind the configured port, and decide what to do when it is taken.
+   *
+   * It used to walk: EADDRINUSE, try the next port, up to 7799, then write
+   * whatever it got to the port file. On one machine nothing else ever holds
+   * 7777, so the thing being walked around was always a previous instance of
+   * this same panel — a CEPHtmlEngine that lingered across an After Effects
+   * relaunch, or a second panel window — and the walk routed round it in
+   * silence, leaving the port file as a second source of truth that could
+   * disagree with the socket. Four incidents in a week (issue #92).
+   *
+   * So the holder is identified first. If it is one of us, this panel does not
+   * move: it says so in its status and log, and retries the bind on an interval
+   * so it takes the port over the moment the other one exits, with no restart.
+   * If it is something else, or answers nothing, the walk happens as before —
+   * loudly, naming the holder and the port chosen, because that is the one
+   * case where the port file legitimately says something other than 7777.
+   * `allowPortWalk` in config.json opts back into walking past our own panel,
+   * for people who really run two After Effects instances.
+   */
+  function startServers(cfg) {
+    var startPort = cfg.port;
+    var retryMs = cfg.bindRetryMs;
+    var waits = 0;
+
+    function bindWith(p) {
       return startHttp(p).then(function (server) {
+        // Read back rather than assumed: port 0 binds an ephemeral one.
+        var bound = server.address().port;
         // Mount WS on the same HTTP server.
         var wss = new WebSocket.Server({ server: server, path: "/events" });
         wss.on("connection", function (ws) {
           wsClients.add(ws);
           ws.on("close", function () { wsClients.delete(ws); });
         });
-        return { port: p, server: server, wss: wss };
-      }).catch(function (e) {
-        if (e.code === "EADDRINUSE" && tries < 23 && p < 7799) {
-          return attempt(p + 1);
-        }
-        throw e;
+        return { port: bound, server: server, wss: wss };
+      });
+    }
+
+    function walk(p, tries, why) {
+      var next = p + 1;
+      if (tries >= WALK_LIMIT) {
+        throw new Error("ports " + startPort + " through " + p + " are all in use — nothing free to bind. Last holder: " + why);
+      }
+      log("warn", "port " + p + " is held by " + why + " — moving to port " + next + ". " +
+        "The MCP server finds this port through the port file; if tool calls fail on " + p +
+        " while check_setup passes, this is why, and the server re-checks the port on the next refused call.");
+      return attempt(next, tries + 1);
+    }
+
+    function waitForHolder(p, holder) {
+      var same = holder.health.bundleHash && holder.health.bundleHash === loadedBundleHash;
+      var hash = holder.health.bundleHash
+        ? String(holder.health.bundleHash).slice(0, 12)
+        : "no bundleHash — a panel older than 0.3";
+      setStatus("waiting — port " + p + " is held by another AE MCP panel", "warn");
+      if (waits === 0) {
+        log("warn", "port " + p + " is already held by another AE MCP panel (bundle " + hash + ", " +
+          (same ? "the same version as this one" : "a DIFFERENT version from this one") + "). " +
+          "Not moving to another port: that would leave the port file pointing at whichever panel bound last, " +
+          "and the MCP server talking to the wrong one (issue #92).");
+        log("warn", "Retrying the bind every " + (retryMs / 1000) + "s; this panel takes the port over the moment " +
+          "the other one exits, with no restart. If After Effects was relaunched and this persists, the previous " +
+          "panel process is still running: quit After Effects fully, check Activity Monitor / Task Manager for a " +
+          "leftover CEPHtmlEngine, and reopen it. To run two After Effects at once instead, set " +
+          "\"allowPortWalk\": true in " + configFile + ".");
+      } else if (waits % 30 === 0) {
+        log("info", "still waiting for port " + p + " (" + waits + " attempts)");
+      }
+      waits += 1;
+      return new Promise(function (r) { setTimeout(r, retryMs); }).then(function () { return attempt(p, 0); });
+    }
+
+    function attempt(p, tries) {
+      return bindWith(p).catch(function (e) {
+        if (e.code !== "EADDRINUSE") throw e;
+        return identifyHolder(p).then(function (holder) {
+          if (holder.kind === "panel") {
+            if (cfg.allowPortWalk) {
+              return walk(p, tries, "another AE MCP panel, and allowPortWalk is on in " + configFile);
+            }
+            return waitForHolder(p, holder);
+          }
+          var why = holder.kind === "other"
+            ? "something that is not an AE MCP panel (" + holder.detail + ")"
+            : "something that did not identify itself (" + holder.detail + ")";
+          return walk(p, tries, why);
+        });
       });
     }
-    return attempt(startPort);
+    return attempt(startPort, 0);
+  }
+
+  // ---------- Shutdown ----------
+  // When the panel window closes or After Effects quits, give the port back and
+  // take this panel's port-file entry with it. A panel that exits cleanly must
+  // not leave a file naming a port nobody listens on — that is the other half
+  // of how the port file came to disagree with the socket (issue #92). A
+  // process that dies without unloading still leaves the file; the server's
+  // discovery treats the file as a hint for exactly that reason.
+  var running = null;
+  function shutdown() {
+    if (!running) return;
+    var s = running;
+    running = null;
+    try { s.wss.close(); } catch (e) {}
+    try { if (typeof s.server.closeAllConnections === "function") s.server.closeAllConnections(); } catch (e) {}
+    try { s.server.close(); } catch (e) {}
+    removePortFile(s.port);
+  }
+  if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    window.addEventListener("beforeunload", shutdown);
+    window.addEventListener("unload", shutdown);
   }
 
   // ---------- Boot sequence ----------
@@ -611,14 +1110,22 @@
     $ae.textContent = (host && host.appName ? host.appName : "AE") + " " + (host && host.appVersion ? host.appVersion : "");
   } catch (e) {}
 
+  var config = readConfig();
+  if (config.source) {
+    log("info", "read " + config.source + ": port " + config.port + (config.allowPortWalk ? ", allowPortWalk on" : ""));
+  }
+
   loadJsxBundle()
-    .then(function () { return startServers(7777); })
+    .then(function () { return startServers(config); })
     .then(function (s) {
+      running = s;
+      // The only write of the port file, and only with the port actually bound.
       writePortFile(s.port);
       $port.textContent = String(s.port);
       $port.className = "ok";
       setStatus("ready", "ok");
-      log("info", "Bridge listening on http://127.0.0.1:" + s.port);
+      log("info", "Bridge listening on http://127.0.0.1:" + s.port +
+        (s.port !== config.port && config.port !== 0 ? " (configured port " + config.port + " was taken — see above)" : ""));
     })
     .catch(function (e) {
       setStatus("failed", "err");