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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engine-room/after-effects-mcp",
-  "version": "0.3.1",
+  "version": "0.4.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.3.1"
+<ExtensionManifest Version="11.0" ExtensionBundleId="games.engine-room.ae-mcp" ExtensionBundleVersion="0.4.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.3.1" />
+    <Extension Id="games.engine-room.ae-mcp.panel" Version="0.4.0" />
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/panel/client/contactsheet.js

@@ -0,0 +1,347 @@
+// contactsheet.js — tile several rendered frames into one labelled sheet.
+//
+// Judging motion is one visual question — "does it move the way I think it
+// does" — and answering it used to cost three `screenshot_frame` calls. Three
+// calls is three image blocks resident in the context for the rest of the
+// session, three chances for After Effects to re-serve a stale buffer, and no
+// guarantee the agent lines the frames up in the right order. One sheet is one
+// image, one op, and the order is in the picture. Issue #56.
+//
+// The compositing happens here rather than in ExtendScript for the obvious
+// reason: `packages/jsx` has no pixels, no PNG encoder and no way to draw a
+// character. The panel already decodes and re-encodes frames for the 16-bit
+// conversion, so the sheet is a few hundred lines on top of machinery that
+// exists.
+//
+// Two rules the layout has to keep:
+//
+//   * Every requested time gets a cell, in order, whether or not it rendered.
+//     A sheet that silently drops the tile that failed no longer maps onto the
+//     times that were asked for, and an agent counting tiles left to right
+//     would read the wrong frame as the right one.
+//   * The time is burned into the picture. Metadata beside an image is not
+//     what a model looks at when it is comparing three frames.
+//
+// Node builtins only, and a CommonJS module, for the same reasons as
+// pngcodec.js: `client/main.js` requires it inside CEP's mixed context and
+// `tests/unit/contact-sheet.mjs` requires the same file under plain Node.
+
+"use strict";
+
+var pngCodec = require("./pngcodec.js");
+
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+
+// Columns per tile count. Not a formula, because the two things a formula gets
+// wrong are the ones that matter: three frames of an animation read as a strip
+// and should stay on one row, and five should not leave a hole in the middle of
+// a 2-wide grid. Two to six is the whole domain — the schema caps `times` there
+// — so the table is complete rather than a heuristic.
+var COLUMNS_FOR = { 2: 2, 3: 3, 4: 2, 5: 3, 6: 3 };
+
+function layoutFor(count) {
+  var cols = COLUMNS_FOR[count];
+  if (!cols) cols = Math.ceil(Math.sqrt(count));
+  return { cols: cols, rows: Math.ceil(count / cols) };
+}
+
+// The gutter is opaque on purpose. A transparent one would be invisible behind
+// a transparent overlay comp — which is exactly the kind of comp somebody
+// screenshots three times — and the tiles would run together.
+var GUTTER = 4;
+var BACKGROUND = [38, 38, 38, 255];
+var TILE_BORDER = [150, 150, 150, 255];
+
+// Flat blocks for the cells that have no picture. Each carries its status word
+// in the label chip as well; the colour alone is a hint, never the statement.
+var STATUS_FILL = {
+  empty: [22, 22, 28, 255],
+  stale: [74, 30, 30, 255],
+  failed: [74, 50, 20, 255],
+};
+
+// ---------------------------------------------------------------------------
+// A 5x7 bitmap font, five column bytes per glyph, bit 0 = top row.
+//
+// Burning text into a frame needs a font, and a font file would be a second
+// thing to ship into the CEP extension and keep in sync — the problem `ws`
+// already causes once. Fifty glyphs of pixels weigh nothing and render
+// identically on both platforms, which a system font would not.
+// ---------------------------------------------------------------------------
+var FONT = {
+  "0": [0x3e, 0x51, 0x49, 0x45, 0x3e],
+  "1": [0x00, 0x42, 0x7f, 0x40, 0x00],
+  "2": [0x42, 0x61, 0x51, 0x49, 0x46],
+  "3": [0x21, 0x41, 0x45, 0x4b, 0x31],
+  "4": [0x18, 0x14, 0x12, 0x7f, 0x10],
+  "5": [0x27, 0x45, 0x45, 0x45, 0x39],
+  "6": [0x3c, 0x4a, 0x49, 0x49, 0x30],
+  "7": [0x01, 0x71, 0x09, 0x05, 0x03],
+  "8": [0x36, 0x49, 0x49, 0x49, 0x36],
+  "9": [0x06, 0x49, 0x49, 0x29, 0x1e],
+  ".": [0x00, 0x60, 0x60, 0x00, 0x00],
+  "-": [0x08, 0x08, 0x08, 0x08, 0x08],
+  ":": [0x00, 0x36, 0x36, 0x00, 0x00],
+  " ": [0x00, 0x00, 0x00, 0x00, 0x00],
+  s: [0x48, 0x54, 0x54, 0x54, 0x20],
+  A: [0x7e, 0x11, 0x11, 0x11, 0x7e],
+  B: [0x7f, 0x49, 0x49, 0x49, 0x36],
+  C: [0x3e, 0x41, 0x41, 0x41, 0x22],
+  D: [0x7f, 0x41, 0x41, 0x22, 0x1c],
+  E: [0x7f, 0x49, 0x49, 0x49, 0x41],
+  F: [0x7f, 0x09, 0x09, 0x09, 0x01],
+  G: [0x3e, 0x41, 0x49, 0x49, 0x7a],
+  H: [0x7f, 0x08, 0x08, 0x08, 0x7f],
+  I: [0x00, 0x41, 0x7f, 0x41, 0x00],
+  J: [0x20, 0x40, 0x41, 0x3f, 0x01],
+  K: [0x7f, 0x08, 0x14, 0x22, 0x41],
+  L: [0x7f, 0x40, 0x40, 0x40, 0x40],
+  M: [0x7f, 0x02, 0x0c, 0x02, 0x7f],
+  N: [0x7f, 0x04, 0x08, 0x10, 0x7f],
+  O: [0x3e, 0x41, 0x41, 0x41, 0x3e],
+  P: [0x7f, 0x09, 0x09, 0x09, 0x06],
+  Q: [0x3e, 0x41, 0x51, 0x21, 0x5e],
+  R: [0x7f, 0x09, 0x19, 0x29, 0x46],
+  S: [0x46, 0x49, 0x49, 0x49, 0x31],
+  T: [0x01, 0x01, 0x7f, 0x01, 0x01],
+  U: [0x3f, 0x40, 0x40, 0x40, 0x3f],
+  V: [0x1f, 0x20, 0x40, 0x20, 0x1f],
+  W: [0x3f, 0x40, 0x38, 0x40, 0x3f],
+  X: [0x63, 0x14, 0x08, 0x14, 0x63],
+  Y: [0x07, 0x08, 0x70, 0x08, 0x07],
+  Z: [0x61, 0x51, 0x49, 0x45, 0x43],
+};
+var GLYPH_W = 5;
+var GLYPH_H = 7;
+var ADVANCE = GLYPH_W + 1;
+
+function glyphFor(ch) {
+  if (FONT[ch]) return FONT[ch];
+  var up = ch.toUpperCase();
+  if (FONT[up]) return FONT[up];
+  return FONT[" "];
+}
+
+/** Width in pixels of `text` at `scale`, with no trailing inter-glyph gap. */
+function textWidth(text, scale) {
+  if (!text.length) return 0;
+  return (text.length * ADVANCE - 1) * scale;
+}
+
+/**
+ * Format a time for the label: shortest form that is still unambiguous.
+ * 0 -> "0s", 1.5 -> "1.5s", 2.25 -> "2.25s", 0.041666 -> "0.042s".
+ *
+ * Three decimals because a 30fps frame is 0.033s apart from its neighbour and
+ * two would print two adjacent frames identically — the one case where the
+ * label would actively mislead.
+ */
+function formatTime(t) {
+  if (typeof t !== "number" || !isFinite(t)) return "?s";
+  var s = t.toFixed(3);
+  // Trim the zeros the fixed form adds, but never the digit before the point.
+  s = s.replace(/0+$/, "").replace(/\.$/, "");
+  return s + "s";
+}
+
+// ---------------------------------------------------------------------------
+// Drawing
+// ---------------------------------------------------------------------------
+
+function setPixel(sheet, sheetW, sheetH, x, y, rgba) {
+  if (x < 0 || y < 0 || x >= sheetW || y >= sheetH) return;
+  var o = (y * sheetW + x) * 4;
+  sheet[o] = rgba[0];
+  sheet[o + 1] = rgba[1];
+  sheet[o + 2] = rgba[2];
+  sheet[o + 3] = rgba[3];
+}
+
+function fillRect(sheet, sheetW, sheetH, x, y, w, h, rgba) {
+  for (var j = 0; j < h; j++) {
+    for (var i = 0; i < w; i++) setPixel(sheet, sheetW, sheetH, x + i, y + j, rgba);
+  }
+}
+
+function strokeRect(sheet, sheetW, sheetH, x, y, w, h, rgba) {
+  for (var i = 0; i < w; i++) {
+    setPixel(sheet, sheetW, sheetH, x + i, y, rgba);
+    setPixel(sheet, sheetW, sheetH, x + i, y + h - 1, rgba);
+  }
+  for (var j = 0; j < h; j++) {
+    setPixel(sheet, sheetW, sheetH, x, y + j, rgba);
+    setPixel(sheet, sheetW, sheetH, x + w - 1, y + j, rgba);
+  }
+}
+
+/**
+ * Draw `text` in an opaque chip whose top-left corner is (x, y).
+ *
+ * Opaque rather than blended: the chip sits on top of whatever the frame
+ * happens to be, and a translucent one over a busy frame is the one case where
+ * the label becomes unreadable — which defeats the whole point of burning it in.
+ *
+ * Returns the chip's { x, y, width, height } so a caller can assert where it
+ * landed.
+ */
+function drawLabel(sheet, sheetW, sheetH, x, y, text, scale, ink, chip) {
+  var pad = 2 * scale;
+  var w = textWidth(text, scale) + pad * 2;
+  var h = GLYPH_H * scale + pad * 2;
+  fillRect(sheet, sheetW, sheetH, x, y, w, h, chip);
+  var penX = x + pad;
+  for (var c = 0; c < text.length; c++) {
+    var glyph = glyphFor(text.charAt(c));
+    for (var col = 0; col < GLYPH_W; col++) {
+      var bits = glyph[col];
+      for (var row = 0; row < GLYPH_H; row++) {
+        if (!(bits & (1 << row))) continue;
+        fillRect(
+          sheet, sheetW, sheetH,
+          penX + col * scale, y + pad + row * scale,
+          scale, scale, ink
+        );
+      }
+    }
+    penX += ADVANCE * scale;
+  }
+  return { x: x, y: y, width: w, height: h };
+}
+
+/**
+ * Copy one decoded frame into a cell, converting whatever channel count it
+ * arrived with to the sheet's RGBA.
+ *
+ * Frames larger than the cell are cropped rather than resampled. They should
+ * never be — every tile in a sheet is rendered at the same downsample from the
+ * same comp — but a crop keeps a surprise visible in the picture, where a
+ * silent resample would make a wrong frame look like a right one.
+ */
+function blitTile(sheet, sheetW, sheetH, dstX, dstY, cellW, cellH, tile) {
+  var ch = tile.channels;
+  var w = Math.min(tile.width, cellW);
+  var h = Math.min(tile.height, cellH);
+  for (var y = 0; y < h; y++) {
+    for (var x = 0; x < w; x++) {
+      var si = (y * tile.width + x) * ch;
+      var r, g, b, a;
+      if (ch === 1) { r = g = b = tile.pixels[si]; a = 255; }
+      else if (ch === 2) { r = g = b = tile.pixels[si]; a = tile.pixels[si + 1]; }
+      else if (ch === 3) { r = tile.pixels[si]; g = tile.pixels[si + 1]; b = tile.pixels[si + 2]; a = 255; }
+      else { r = tile.pixels[si]; g = tile.pixels[si + 1]; b = tile.pixels[si + 2]; a = tile.pixels[si + 3]; }
+      var o = ((dstY + y) * sheetW + (dstX + x)) * 4;
+      sheet[o] = r;
+      sheet[o + 1] = g;
+      sheet[o + 2] = b;
+      sheet[o + 3] = a;
+    }
+  }
+}
+
+/**
+ * Compose the sheet.
+ *
+ * `tiles` is one entry per *requested* time, in order:
+ *   { time, status, pixels?, width?, height?, channels?, note? }
+ * where status is "ok" for a frame that rendered and anything in STATUS_FILL
+ * ("empty", "stale", "failed") for one that did not.
+ *
+ * `opts.cellWidth`/`cellHeight` are what a tile is expected to measure — passed
+ * in rather than taken from the first tile, because the first tile is exactly
+ * the one that may have failed and have no dimensions at all.
+ *
+ * Returns { buffer, width, height, cols, rows, cellWidth, cellHeight, tiles },
+ * where each entry of `tiles` carries the cell rectangle it was drawn into.
+ */
+function composeContactSheet(tiles, opts) {
+  if (!tiles || !tiles.length) throw new Error("composeContactSheet needs at least one tile");
+  var o = opts || {};
+  var cellW = o.cellWidth;
+  var cellH = o.cellHeight;
+  for (var t = 0; t < tiles.length; t++) {
+    if (tiles[t].status === "ok" && tiles[t].width && tiles[t].height) {
+      // A rendered frame is the authority on its own size; the expectation is
+      // only a fallback for the cells that have no picture.
+      if (tiles[t].width > cellW) cellW = tiles[t].width;
+      if (tiles[t].height > cellH) cellH = tiles[t].height;
+    }
+  }
+  if (!(cellW > 0) || !(cellH > 0)) throw new Error("composeContactSheet needs a positive cell size");
+
+  var lay = layoutFor(tiles.length);
+  var cols = lay.cols;
+  var rows = lay.rows;
+  var gutter = o.gutter === undefined ? GUTTER : o.gutter;
+  var sheetW = cols * cellW + (cols + 1) * gutter;
+  var sheetH = rows * cellH + (rows + 1) * gutter;
+
+  var sheet = Buffer.alloc(sheetW * sheetH * 4);
+  fillRect(sheet, sheetW, sheetH, 0, 0, sheetW, sheetH, BACKGROUND);
+
+  // One label size for the whole sheet, from the cell width, so every tile is
+  // annotated identically and a 4K sheet does not get a 6px caption.
+  var scale = o.labelScale;
+  if (!scale) scale = Math.max(1, Math.min(4, Math.round(cellW / 300)));
+
+  var out = [];
+  for (var i = 0; i < tiles.length; i++) {
+    var tile = tiles[i];
+    var col = i % cols;
+    var row = Math.floor(i / cols);
+    var x = gutter + col * (cellW + gutter);
+    var y = gutter + row * (cellH + gutter);
+
+    if (tile.status === "ok" && tile.pixels) {
+      blitTile(sheet, sheetW, sheetH, x, y, cellW, cellH, tile);
+    } else {
+      var fill = STATUS_FILL[tile.status] || STATUS_FILL.failed;
+      fillRect(sheet, sheetW, sheetH, x, y, cellW, cellH, fill);
+    }
+    strokeRect(sheet, sheetW, sheetH, x, y, cellW, cellH, TILE_BORDER);
+
+    var text = formatTime(tile.time);
+    if (tile.status !== "ok") text += " " + String(tile.status).toUpperCase();
+    var chip = drawLabel(
+      sheet, sheetW, sheetH,
+      x + gutter, y + gutter,
+      text, scale,
+      [255, 255, 255, 255], [0, 0, 0, 255]
+    );
+
+    out.push({
+      time: tile.time,
+      status: tile.status,
+      x: x,
+      y: y,
+      width: cellW,
+      height: cellH,
+      label: text,
+      labelRect: chip,
+      note: tile.note,
+    });
+  }
+
+  return {
+    buffer: pngCodec.encodePng8(sheetW, sheetH, 6, sheet),
+    width: sheetW,
+    height: sheetH,
+    cols: cols,
+    rows: rows,
+    cellWidth: cellW,
+    cellHeight: cellH,
+    tiles: out,
+  };
+}
+
+module.exports = {
+  composeContactSheet: composeContactSheet,
+  // Exported for the tests, which have to be able to state the expected sheet
+  // size without re-deriving the layout from the code under test.
+  layoutFor: layoutFor,
+  formatTime: formatTime,
+  textWidth: textWidth,
+  GLYPH_H: GLYPH_H,
+  GUTTER: GUTTER,
+};

package/panel/client/framereader.js

@@ -0,0 +1,248 @@
+// framereader.js — wait for After Effects to finish writing a frame.
+//
+// `saveFrameToPng` is asynchronous: it returns before the bytes are on disk, so
+// the panel has to decide for itself when the file is finished. Getting that
+// decision wrong is issue #45.
+//
+// What it used to be: two `stat` calls 30ms apart reporting the same size. That
+// is not completion, it is a pause — and on a heavy comp (~88 layers, nested
+// precomps) the writer pauses routinely. The half-written file was read, shipped
+// and reported as a successful screenshot, and the agent got `truncated PNG:
+// chunk IDAT runs past the end of the file` for a render that was still
+// happening. Worse, the old passthrough path hashed those truncated bytes into
+// the stale-frame cache, so the next truncation at the same byte count came back
+// as "stale frame" — the wrong diagnosis, with the wrong remedy, for a bug that
+// was never about staleness.
+//
+// What it is now: a PNG is finished when it *is* a PNG — ends in a zero-length
+// IEND chunk with every chunk length from the signature adding up to exactly
+// that. A partial write cannot satisfy that test, so it can no longer be
+// delivered; it can only time out or be reported as corrupt.
+//
+// The two failures are kept apart on purpose, exactly as `BridgeTimeoutError`
+// and `BridgeUnreachableError` are kept apart on the server: "the render did not
+// finish in time" and "the file After Effects wrote is not a whole PNG" have
+// opposite remedies, and one sentence covering both would send half the readers
+// the wrong way.
+//
+// Node builtins only, and a CommonJS module, so `client/main.js` can require it
+// inside CEP's mixed context and `tests/unit/frame-integrity.mjs` can require
+// the same file under plain Node. There is no After Effects on a CI runner and
+// this is the code the bug lived in, so it must be exercisable without one.
+
+"use strict";
+
+var fs = require("fs");
+var pngCodec = require("./pngcodec.js");
+
+// How long a frame that has not arrived is still allowed to be on its way. A
+// cold render of a heavy 4K comp was measured taking well over 15s; the original
+// 5s silently failed screenshots that were merely still rendering.
+var FRAME_RENDER_BUDGET_MS = 120000;
+
+// How long a file may sit at exactly the same size, still not a whole PNG,
+// before the write is called abandoned rather than slow.
+//
+// Deliberately far short of the budget above. A corrupt frame has to fail fast
+// enough that one automatic re-render still fits inside the server's 300s
+// ceiling for this op — and a PNG write that has begun is a few hundred KB of
+// deflate output, not something that legitimately stalls for seconds.
+var FRAME_STALL_MS = 6000;
+
+var FRAME_POLL_MS = 40;
+
+function frameError(code, detail) {
+  var e = new Error(detail);
+  e.code = code;
+  e.detail = detail;
+  return e;
+}
+
+function unlinkQuietly(file) {
+  try { fs.unlinkSync(file); } catch (e) {}
+}
+
+/** True when the last 12 bytes are a zero-length IEND — the file ends where a PNG ends. */
+function endsWithIend(file, size) {
+  if (size < 12) return false;
+  var fd = null;
+  try {
+    fd = fs.openSync(file, "r");
+    var tail = Buffer.alloc(12);
+    fs.readSync(fd, tail, 0, 12, size - 12);
+    return tail.readUInt32BE(0) === 0 && tail.toString("ascii", 4, 8) === "IEND";
+  } catch (e) {
+    return false;
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch (e2) {} }
+  }
+}
+
+function readHead(file, n) {
+  var fd = null;
+  try {
+    fd = fs.openSync(file, "r");
+    var head = Buffer.alloc(n);
+    var got = fs.readSync(fd, head, 0, n, 0);
+    return head.subarray(0, got);
+  } catch (e) {
+    return null;
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch (e2) {} }
+  }
+}
+
+/**
+ * Resolve with the bytes of a complete PNG, or reject saying which failure it
+ * was. The temp file is removed on every path — a file left behind is one a
+ * later read could find, which is how a corrupt frame would start coming back
+ * for free.
+ *
+ * The tail probe in front of the full read is what keeps this cheap enough to
+ * run every 40ms on a multi-megabyte file: IEND is the last chunk in the
+ * format, so a file whose final twelve bytes are not one is definitively
+ * unfinished and does not need reading at all. The whole chunk walk still runs
+ * before any bytes are returned.
+ *
+ * Rejections:
+ *   FRAME_INCOMPLETE  the file exists, stopped changing, and is not a PNG.
+ *                     Re-rendering can fix it, and this fails within stallMs.
+ *   RENDER_TIMEOUT    it never got there inside the budget. Re-rendering
+ *                     immediately would only spend the budget a second time.
+ */
+function waitForCompletePng(file, opts) {
+  var o = opts || {};
+  var budgetMs = o.budgetMs || FRAME_RENDER_BUDGET_MS;
+  var stallMs = o.stallMs || FRAME_STALL_MS;
+  var pollMs = o.pollMs || FRAME_POLL_MS;
+  var deadline = Date.now() + budgetMs;
+  return new Promise(function (resolve, reject) {
+    var lastSize = -1;
+    var lastGrewAt = Date.now();
+    var headChecked = false;
+    var reason = "After Effects has not written the file yet";
+
+    function fail(code, detail) {
+      unlinkQuietly(file);
+      reject(frameError(code, detail));
+    }
+
+    (function poll() {
+      var size = -1;
+      try {
+        if (fs.existsSync(file)) size = fs.statSync(file).size;
+      } catch (e) { size = -1; }
+
+      if (size >= 0) {
+        if (size !== lastSize) {
+          lastSize = size;
+          lastGrewAt = Date.now();
+        }
+        // Something that is not a PNG at all will not become one by gaining
+        // bytes. Say so now rather than at the end of a two-minute budget.
+        if (!headChecked && size >= 8) {
+          headChecked = true;
+          var head = readHead(file, 8);
+          if (head) {
+            var early = pngCodec.inspectPngStructure(head);
+            if (!early.complete && !early.growable) return fail("FRAME_INCOMPLETE", early.reason);
+          }
+        }
+        if (endsWithIend(file, size)) {
+          var buf = null;
+          try { buf = fs.readFileSync(file); } catch (e) { buf = null; }
+          if (buf) {
+            var st = pngCodec.inspectPngStructure(buf);
+            if (st.complete) {
+              unlinkQuietly(file);
+              return resolve(buf);
+            }
+            if (!st.growable) return fail("FRAME_INCOMPLETE", st.reason);
+            reason = st.reason;
+          }
+        } else if (size > 0) {
+          reason = "the file reached " + size + " bytes with no IEND chunk";
+        }
+        if (size > 0 && Date.now() - lastGrewAt > stallMs) {
+          return fail(
+            "FRAME_INCOMPLETE",
+            "After Effects wrote " + size + " bytes, stopped for " +
+              Math.round((Date.now() - lastGrewAt) / 1000) + "s, and " + reason
+          );
+        }
+      }
+
+      if (Date.now() > deadline) {
+        return fail(
+          "RENDER_TIMEOUT",
+          "nothing complete arrived within " + Math.round(budgetMs / 1000) + "s (" + reason + ")"
+        );
+      }
+      setTimeout(poll, pollMs);
+    })();
+  });
+}
+
+/**
+ * Turn a one-sentence reader failure into the message an agent acts on.
+ *
+ * `attempts` is how many renders were spent, so the advice does not tell
+ * somebody to retry something that has already been retried for them.
+ *
+ * Anything without one of the two codes is returned untouched: an ExtendScript
+ * error travelling through here is not this module's to rewrite.
+ */
+function dressFrameError(err, attempts) {
+  if (!err || (err.code !== "FRAME_INCOMPLETE" && err.code !== "RENDER_TIMEOUT")) return err;
+  var tried = attempts > 1 ? " Both the first attempt and one automatic re-render failed the same way." : "";
+  var lines;
+  if (err.code === "FRAME_INCOMPLETE") {
+    lines = [
+      "Corrupt frame: " + err.detail + ", so the file is not a whole PNG and nothing was sent." + tried,
+      "",
+      "This is NOT a timeout. The render stopped writing and what it left behind is",
+      "incomplete — a truncated PNG decodes to a wrong picture or to none at all, and",
+      "neither is a screenshot. It correlates with how heavy the comp is (issue #45).",
+      "",
+      "What to do next:",
+      "1. Retry at a higher `downsample` (6 or 8). A smaller frame is a smaller write,",
+      "   and completes where a large one did not.",
+      "2. On a heavy assembled comp, screenshot the shot precomps one at a time rather",
+      "   than the assembly.",
+      "3. If it repeats, verify the animation by reading keyframes (get_keyframes /",
+      "   get_layer_full) instead. That is exact; a picture is not.",
+      "",
+      "Do NOT disable layers to make the render succeed: this is a limit of the render",
+      "path, not a problem with the project.",
+    ];
+  } else {
+    lines = [
+      "Render timed out: " + err.detail + "." + tried,
+      "",
+      "This is NOT a corrupt file and NOT a lost bridge. After Effects was still working",
+      "on the frame when the panel gave up waiting, so the render is most likely still",
+      "running and nothing has gone wrong with the project.",
+      "",
+      "What to do next:",
+      "1. Wait a few seconds before doing anything else — a re-render started now would",
+      "   queue behind the one still going.",
+      "2. Then retry at a higher `downsample` (6 or 8). Fewer pixels is less render.",
+      "3. On a heavy assembled comp, screenshot the shot precomps one at a time.",
+      "4. If it repeats, read keyframes (get_keyframes / get_layer_full) instead of",
+      "   looking at it. That is exact and costs nothing to render.",
+    ];
+  }
+  var out = new Error(lines.join("\n"));
+  out.code = err.code;
+  out.detail = err.detail;
+  return out;
+}
+
+module.exports = {
+  waitForCompletePng: waitForCompletePng,
+  dressFrameError: dressFrameError,
+  frameError: frameError,
+  unlinkQuietly: unlinkQuietly,
+  FRAME_RENDER_BUDGET_MS: FRAME_RENDER_BUDGET_MS,
+  FRAME_STALL_MS: FRAME_STALL_MS,
+};