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

package/panel/jsx/bundle.jsx

@@ -69,13 +69,33 @@ function __newJobId() {
 }
 
 // ---------- Undo wrapper ----------
-// __UNDO_OPEN tracks only the group *dispatch* opened. Nothing else may set it:
-// it is what lets withoutUndoGroup() reopen exactly what it closed, and leave
-// undo state alone entirely when we never opened a group in the first place.
+// __UNDO_OPEN tracks whether a group *this bundle* opened is currently open.
+// withUndo() is the only thing that may set it — dispatch and run_batch both
+// group through there — because it is what lets withoutUndoGroup() reopen
+// exactly what it closed, and leave undo state alone entirely when we never
+// opened a group in the first place.
 var __UNDO_OPEN = false;
 
-function withUndo(name, fn) {
+// Every undo group this bundle opens is counted here, and __beginUndoGroup is
+// the only place allowed to call app.beginUndoGroup. run_batch reports the
+// number of undo steps it cost as the *delta* of this counter, so the number an
+// agent repeats to the user as "press Cmd-Z N times" is measured rather than
+// predicted — a chunk that threw still opened its group, and a batched op that
+// called withoutUndoGroup() really did split itself into two steps.
+var __UNDO_GROUPS = 0;
+
+function __beginUndoGroup(name) {
+  __UNDO_GROUPS += 1;
   app.beginUndoGroup(name || "AE MCP");
+}
+
+function __undoGroupsOpened() { return __UNDO_GROUPS; }
+
+// An undo group must open and close inside ONE evalScript call. After Effects
+// discards one that spans two — see the note in CLAUDE.md; measured, not
+// inferred. Everything that groups goes through here for that reason.
+function withUndo(name, fn) {
+  __beginUndoGroup(name || "AE MCP");
   __UNDO_OPEN = true;
   try { return fn(); }
   finally { __UNDO_OPEN = false; app.endUndoGroup(); }
@@ -91,15 +111,28 @@ function withoutUndoGroup(fn) {
   app.endUndoGroup();
   __UNDO_OPEN = false;
   try { return fn(); }
-  finally { app.beginUndoGroup("AE MCP: continue"); __UNDO_OPEN = true; }
+  finally { __beginUndoGroup("AE MCP: continue"); __UNDO_OPEN = true; }
 }
 
 // ---------- Error helper ----------
+// A handler that can say more about *where* it failed than "an error happened"
+// attaches that on `aeDetail` and it is copied onto the result verbatim —
+// run_jsx maps After Effects' line number back onto the script the caller
+// actually submitted (issue #46). The bag is free-form here on purpose; the
+// panel forwards a named list of fields, which is where the contract is kept.
 function __mkError(e) {
   var msg = e && e.message ? String(e.message) : String(e);
   var stack = e && e.stack ? String(e.stack) : "";
   var line = e && typeof e.line !== "undefined" ? e.line : null;
-  return { ok: false, error: msg, stack: stack, line: line };
+  var out = { ok: false, error: msg, stack: stack, line: line };
+  var detail = null;
+  try { if (e && e.aeDetail) detail = e.aeDetail; } catch (ed) {}
+  if (detail) {
+    for (var k in detail) {
+      if (detail.hasOwnProperty(k)) out[k] = detail[k];
+    }
+  }
+  return out;
 }
 
 // ---------- Main dispatch ----------
@@ -268,6 +301,155 @@ OPS.delete_comp = function (args) {
   return { ok: true };
 };
 
+// ---------------------------------------------------------------------------
+// duplicate_comp
+// ---------------------------------------------------------------------------
+// There was duplicate_layer, create_comp and delete_comp but no way to copy a
+// comp, so every rig workflow detoured through run_jsx and CompItem.duplicate()
+// (issue #54). Two things that detour never got right:
+//
+//   * AE's own Duplicate is SHALLOW. The copy's precomp layers point at the
+//     same source comps as the original, so "make a variant of this rig" and
+//     then editing the variant edits the original too. `deep:true` duplicates
+//     the nested comps as well and re-points the copy's layers at them, which
+//     is the entire value of the flag.
+//   * The same nested comp usually appears on several layers. Duplicating per
+//     layer fans out one copy per reference; __dupNested keeps a map from
+//     original id to its copy and reuses it, and registers the copy *before*
+//     recursing so a cycle terminates instead of recursing for ever.
+
+// AE happily allows two project items with the same name, which makes a
+// deep-duplicated rig unreadable in the project panel. Appending a counter is
+// the smaller evil, and the chosen name is reported either way.
+function __dupNameTaken(name) {
+  for (var i = 1; i <= app.project.numItems; i++) {
+    if (app.project.item(i).name === name) return true;
+  }
+  return false;
+}
+
+function __dupUniqueName(base) {
+  if (!__dupNameTaken(base)) return base;
+  for (var n = 2; n < 1000; n++) {
+    var candidate = base + " " + n;
+    if (!__dupNameTaken(candidate)) return candidate;
+  }
+  return base;
+}
+
+// Depth is a backstop, not the cycle guard — `seen` is. AE refuses to nest a
+// comp inside itself, but nothing here should recurse for ever if a future
+// build ever allows it.
+var __DUP_MAX_DEPTH = 32;
+
+function __dupNested(src, opts, depth) {
+  var key = "C" + src.id;
+  if (opts.seen.hasOwnProperty(key)) return opts.seen[key];
+  if (depth > __DUP_MAX_DEPTH) {
+    throw new Error("nested comps are more than " + __DUP_MAX_DEPTH + " deep below the comp being duplicated");
+  }
+  var srcId = src.id;
+  var srcName = src.name;
+  var dup = src.duplicate();
+  opts.seen[key] = dup;
+  if (opts.nameSuffix) dup.name = __dupUniqueName(srcName + opts.nameSuffix);
+  opts.created.push({ fromCompId: srcId, fromName: srcName, compId: dup.id, name: dup.name });
+  __dupRepoint(dup, opts, depth);
+  return dup;
+}
+
+// Re-point every precomp layer of a freshly duplicated comp at the duplicate of
+// its source rather than the original. Layers whose source is footage, and
+// layers with no source at all, are left alone.
+function __dupRepoint(comp, opts, depth) {
+  for (var i = 1; i <= comp.numLayers; i++) {
+    var l = comp.layer(i);
+    if (!(l instanceof AVLayer)) continue;
+    var srcItem = null;
+    try { srcItem = l.source; } catch (e) { continue; }
+    if (!srcItem || !(srcItem instanceof CompItem)) continue;
+    var replacement = __dupNested(srcItem, opts, depth + 1);
+    // fixExpressions:false — the layer keeps its name and its own properties,
+    // so there is nothing for AE to rewrite, and letting it rewrite expressions
+    // on a rig is a change nobody asked for.
+    l.replaceSource(replacement, false);
+    opts.repointed += 1;
+  }
+}
+
+OPS.duplicate_comp = function (args) {
+  var src = getCompById(args.compId);
+  var folder = null;
+  if (args.folderId !== undefined && args.folderId !== null) {
+    var f = app.project.itemByID(args.folderId);
+    if (!f) throw new Error("No project item with id " + args.folderId + " to use as folderId");
+    if (!(f instanceof FolderItem)) {
+      throw new Error(
+        "folderId " + args.folderId + ' ("' + f.name + '") is a ' + __itemKind(f) +
+        ", not a project folder. Pass the id of a folder from get_project_summary, or omit folderId."
+      );
+    }
+    folder = f;
+  }
+
+  var opts = { seen: {}, created: [], repointed: 0, nameSuffix: null };
+  if (args.nameSuffix) opts.nameSuffix = args.nameSuffix;
+
+  // Captured as primitives before the duplicate. Some AE calls invalidate every
+  // handle held across them (exportAsMotionGraphicsTemplate is the measured
+  // one), so nothing below reads `src` again.
+  var srcId = src.id;
+  var srcName = src.name;
+  var dup = src.duplicate();
+  var newId = dup.id;
+  if (args.name) dup.name = args.name;
+
+  if (args.deep) {
+    opts.seen["C" + srcId] = dup;
+    try {
+      __dupRepoint(dup, opts, 1);
+    } catch (e) {
+      // The copy and any nested copies made before the failure are real and
+      // nothing rolled them back. Reporting {ok:true} over a half-built rig, or
+      // an error that does not name what exists, are the same class of lie.
+      var madeIds = [];
+      madeIds.push(String(newId));
+      for (var m = 0; m < opts.created.length; m++) madeIds.push(String(opts.created[m].compId));
+      throw new Error(
+        "duplicate_comp deep failed part-way: " + e.message +
+        ". These comps were created and still exist: ids " + madeIds.join(", ") +
+        ". Undo once in After Effects to back the whole thing out, or delete_comp them."
+      );
+    }
+  }
+
+  // Re-fetch by id rather than trusting the handle held across the duplication.
+  var made = app.project.itemByID(newId);
+  if (!made) throw new Error("duplicate_comp created comp " + newId + " but it could not be read back");
+  if (folder) made.parentFolder = folder;
+
+  var out = __compSummary(made);
+  out.fromCompId = srcId;
+  out.fromName = srcName;
+  out.deep = !!args.deep;
+  if (folder) {
+    out.folderId = folder.id;
+    out.folderName = folder.name;
+  }
+  if (args.deep) {
+    out.nestedDuplicated = opts.created;
+    out.nestedCount = opts.created.length;
+    out.layersRepointed = opts.repointed;
+    if (opts.created.length === 0) {
+      out.note = "deep:true had nothing to do - this comp has no precomp layers.";
+    }
+  } else {
+    out.note = "Shallow copy: its precomp layers still point at the SAME nested comps as the original, " +
+      "so editing one of those edits both. Pass deep:true to duplicate the nested comps too.";
+  }
+  return out;
+};
+
 OPS.set_active_comp = function (args) {
   var c = getCompById(args.compId);
   c.openInViewer();
@@ -415,12 +597,59 @@ OPS.create_adjustment_layer = function (args) {
   return __layerSummary(l);
 };
 
+// Where a new shape layer's origin goes (issue #51).
+//
+// AE's addShape() leaves Position at the comp centre with the Anchor Point at
+// [0,0], so layer space is offset from comp space by half a frame. Every path
+// this toolset can write — set_shape_path vertices, add_shape_content vertices,
+// a rect/ellipse `position` — is expressed in *layer* space, and nothing in the
+// response says where that space starts. An agent authoring in comp pixels gets
+// the whole drawing shifted by (width/2, height/2), and the check that would
+// catch it is a downsampled screenshot.
+//
+// Default [0,0] makes layer space and comp space the same space for a fresh
+// shape layer, which is the only arrangement in which a vertex list means what
+// it says. "center" is AE's own spawn point, kept as one word so the old
+// behaviour is still one argument away.
+function __shapeSpawnPosition(comp, position) {
+  if (position === undefined || position === null) return [0, 0];
+  if (position === "center") return [comp.width / 2, comp.height / 2];
+  if (position instanceof Array && position.length >= 2) {
+    if (position.length === 3) return [position[0], position[1], position[2]];
+    return [position[0], position[1]];
+  }
+  throw new Error(
+    "create_shape_layer: position must be [x,y], [x,y,z] or the string \"center\" (After Effects' own " +
+    "spawn point, the comp centre). Got: " + String(position)
+  );
+}
+
 OPS.create_shape_layer = function (args) {
   var c = getCompById(args.compId);
+  var pos = __shapeSpawnPosition(c, args.position);
   var l = c.layers.addShape();
   if (args.name) l.name = args.name;
+  try {
+    l.property("Transform").property("Position").setValue(pos);
+  } catch (ePos) {
+    // The shape that can still get here is three components on a 2D layer, which
+    // AE refuses. Leaving an empty shape layer in the timeline behind a thrown
+    // error is the half-built failure add_shape_content refuses to produce.
+    try { l.remove(); } catch (eRm) {}
+    throw new Error(
+      "create_shape_layer could not set position to [" + pos.join(", ") + "]: " + ePos.message +
+      ". (A three-component position needs a 3D layer; create it 2D and set threeDLayer with set_layer first.) " +
+      "The empty layer was removed, so nothing changed."
+    );
+  }
   // shapes payload kept loose for v1 — the agent can use add_shape_content for detail
-  return __layerSummary(l);
+  var out = __layerSummary(l);
+  // Read both back rather than echoing what we asked for: together they are the
+  // coordinate space every subsequent path on this layer is measured in, and a
+  // caller should never have to render a frame to find out what it is.
+  out.position = l.property("Transform").property("Position").value;
+  out.anchorPoint = l.property("Transform").property("Anchor Point").value;
+  return out;
 };
 
 OPS.create_precomp_layer = function (args) {
@@ -824,14 +1053,672 @@ OPS.parent_layer = function (args) {
   return out;
 };
 
+// Layers do not reorder with moveTo. `moveTo` is a PropertyBase method for
+// re-ranking a property inside an indexed group, and calling it on a Layer
+// throws "parent is not an INDEXED_GROUP" — which is every call this op has
+// ever served (issue #70). AE's layer-level primitives are moveBefore,
+// moveAfter, moveToBeginning and moveToEnd, and all four take a *layer*, never
+// an index. (The one legitimate moveTo in this codebase is the shape-property
+// one in shapes.jsx; it is on a PropertyBase and stays.)
+//
+// Two ways in, because reorder is the op that invalidates indexes:
+//
+//   * `beforeLayerId` / `afterLayerId` — place this layer relative to another
+//     one by id. Nothing about the answer depends on the stack not having moved
+//     since the caller last read it, which is why these are the preferred form.
+//   * `toIndex` — the index the layer ends up at, counting from the front.
+//     Stated as the *landing* index because "the index it displaces" and "the
+//     index it lands on" differ by one when moving down the stack and the
+//     caller cannot tell which one a tool meant.
+//
+// The two directions need different primitives, and swapping them is off by one
+// with no error. Moving up (toIndex < from), the layer currently at the target
+// is pushed down, so moveBefore lands exactly on it. Moving down, that layer
+// shifts up by one as this one leaves, so moveAfter is what lands on the target.
 OPS.reorder_layer = function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
-  l.moveTo(args.toIndex);
-  return __layerSummary(l);
+  var from = l.index;
+  var n = c.numLayers;
+  var to;
+
+  if (args.beforeLayerId !== undefined && args.beforeLayerId !== null) {
+    var b = getLayerById(c, args.beforeLayerId);
+    if (b.id === l.id) throw new Error("reorder_layer: beforeLayerId is the layer being moved (" + l.id + ").");
+    l.moveBefore(b);
+  } else if (args.afterLayerId !== undefined && args.afterLayerId !== null) {
+    var a = getLayerById(c, args.afterLayerId);
+    if (a.id === l.id) throw new Error("reorder_layer: afterLayerId is the layer being moved (" + l.id + ").");
+    l.moveAfter(a);
+  } else if (args.toIndex !== undefined && args.toIndex !== null) {
+    to = Math.round(args.toIndex);
+    if (to < 1) to = 1;
+    if (to > n) to = n;
+    if (to === from) {
+      // Nothing to do. Saying so beats an AE call that is a no-op anyway.
+    } else if (to === 1) {
+      l.moveToBeginning();
+    } else if (to === n) {
+      l.moveToEnd();
+    } else if (to < from) {
+      l.moveBefore(c.layer(to));
+    } else {
+      l.moveAfter(c.layer(to));
+    }
+  } else {
+    throw new Error("reorder_layer: pass one of toIndex, beforeLayerId or afterLayerId.");
+  }
+
+  // Report both ends of the move. The landing index is read back off the layer
+  // rather than assumed, so a result can never claim a position AE did not
+  // give it — and `movedFrom === index` is how a caller sees a no-op.
+  var out = __layerSummary(l);
+  out.movedFrom = from;
+  return out;
 };
 
 
+// ===== snapshot.jsx =====
+
+// snapshot.jsx — a cheap structural fingerprint of a comp, and the diff
+// between two of them.
+//
+// Verifying a write today means reading the comp back and comparing by eye,
+// and every one of those reads is re-sent on every later request for the rest
+// of the session. A fingerprint is the other end of that trade: it records
+// what an agent actually checks after a write — which layers exist, what they
+// are called, where they sit in time, what they are parented to, how many
+// keyframes/expressions/effects they carry — and nothing else. The diff of two
+// of them is a few dozen tokens for "3 layers added: ids 512-514; layer 498
+// Opacity keys 0 -> 4" (issue #52).
+//
+// Cheapness is the whole point, so the walk stops at the layer's own Transform
+// group plus four named properties. It never opens an effect's parameters or a
+// shape layer's Contents — those are what make get_layer_full expensive, and a
+// fingerprint that costs as much as the read it replaces is worth nothing.
+//
+// That has a cost of its own, and per the "a scoped read must say what it left
+// out" rule it is stated rather than left to be discovered: a diff can only
+// report a field it records. __DIFF_COVERS travels with every diff for exactly
+// that reason — "no differences" must never be read as "identical".
+
+var __DIFF_COVERS = "Compares recorded fields only - not property values, expression text, " +
+  "effect parameters, masks or shape contents. \"No differences\" means none of the recorded fields moved, " +
+  "not that the two states render identically.";
+
+var __FP_COVERS = "A snapshot records, per layer: id, name, index, type, inPoint, outPoint, startTime, " +
+  "parentId, enabled, keyframe counts per Transform property (plus Marker, Time Remap and Source Text), " +
+  "expression count and effect count. Per comp: name, size, duration, frame rate, work area and markers. " +
+  "It does NOT record property values, expression text, effect parameters, mask shapes or shape contents, " +
+  "because reading those costs as much as the read this replaces.";
+
+// Times are floats out of AE and are compared, not displayed, so they are
+// rounded once here rather than at every comparison site.
+var __FP_PRECISION = 1000000;
+
+function __fpRound(n) {
+  if (typeof n !== "number") return n;
+  if (!isFinite(n)) return null;
+  return Math.round(n * __FP_PRECISION) / __FP_PRECISION;
+}
+
+// Properties worth a fingerprint that do not live under Transform. Each is one
+// guarded lookup; a layer that has none of them pays four null checks.
+var __FP_EXTRA_PROPS = ["Marker", "Time Remap", "Source Text", "Audio Levels"];
+
+function __fpCountProperty(p, out) {
+  if (!p) return;
+  var keys = 0;
+  try { keys = p.numKeys; } catch (e) { return; }
+  if (typeof keys !== "number") return;
+  if (keys > 0) out.keyCounts[p.name] = keys;
+  try {
+    if (p.canSetExpression && p.expression) out.expressionCount += 1;
+  } catch (e2) {}
+}
+
+function __fpLayer(l) {
+  var out = {
+    id: l.id,
+    name: l.name,
+    index: l.index,
+    type: __layerKind(l),
+    inPoint: __fpRound(l.inPoint),
+    outPoint: __fpRound(l.outPoint),
+    startTime: __fpRound(l.startTime),
+    parentId: null,
+    enabled: l.enabled,
+    keyCounts: {},
+    expressionCount: 0,
+    effectCount: 0
+  };
+  try { if (l.parent) out.parentId = l.parent.id; } catch (e0) {}
+
+  var tr = null;
+  try { tr = l.property("Transform"); } catch (e1) {}
+  if (tr) {
+    for (var i = 1; i <= tr.numProperties; i++) __fpCountProperty(tr.property(i), out);
+  }
+  for (var j = 0; j < __FP_EXTRA_PROPS.length; j++) {
+    var extra = null;
+    try { extra = l.property(__FP_EXTRA_PROPS[j]); } catch (e2) {}
+    __fpCountProperty(extra, out);
+  }
+  // Effects are counted, never walked. The parameter tree is the expensive
+  // part and an agent checking "did my effect land" only needs the count plus
+  // list_effects when it did not.
+  try {
+    var fx = l.property("Effects");
+    if (fx) out.effectCount = fx.numProperties;
+  } catch (e3) {}
+  return out;
+}
+
+function __fpCompMarkers(c) {
+  var out = [];
+  var mp = null;
+  try { mp = c.markerProperty; } catch (e) { return out; }
+  if (!mp) return out;
+  var n = 0;
+  try { n = mp.numKeys; } catch (e2) { return out; }
+  for (var i = 1; i <= n; i++) {
+    var mv = mp.keyValue(i);
+    out.push(String(__fpRound(mp.keyTime(i))) + "|" + String(mv.comment) + "|" + String(__fpRound(mv.duration)));
+  }
+  return out;
+}
+
+function __compFingerprint(compId) {
+  var c = getCompById(compId);
+  var fp = {
+    compId: c.id,
+    name: c.name,
+    width: c.width,
+    height: c.height,
+    duration: __fpRound(c.duration),
+    frameRate: __fpRound(c.frameRate),
+    workAreaStart: __fpRound(c.workAreaStart),
+    workAreaDuration: __fpRound(c.workAreaDuration),
+    numLayers: c.numLayers,
+    markers: __fpCompMarkers(c),
+    layers: []
+  };
+  for (var i = 1; i <= c.numLayers; i++) fp.layers.push(__fpLayer(c.layer(i)));
+  return fp;
+}
+
+// ---------------------------------------------------------------------------
+// The diff
+// ---------------------------------------------------------------------------
+// Pure: two fingerprints in, one object out, no AE. That is what lets it be
+// tested against synthetic input (tests/unit/comp-snapshot.mjs) — there is no
+// ExtendScript runtime on a runner and this is the part that has to be right.
+
+// Below a frame at any sane frame rate, above the float noise a round-trip
+// through JSON leaves behind. Without it a comp re-read after a frame-rate
+// change reports every layer "retimed" by 1e-15.
+var __DIFF_EPS = 0.000001;
+
+function __diffMoved(a, b) {
+  if (typeof a !== "number") return a !== b;
+  if (typeof b !== "number") return true;
+  return Math.abs(a - b) > __DIFF_EPS;
+}
+
+// ES3 has no Map. The "L" prefix keeps a numeric id away from anything already
+// on Object.prototype.
+function __fpById(fp) {
+  var m = {};
+  for (var i = 0; i < fp.layers.length; i++) m["L" + fp.layers[i].id] = fp.layers[i];
+  return m;
+}
+
+function __diffKeyCounts(a, b) {
+  var out = null;
+  var seen = {};
+  var k;
+  for (k in a) {
+    if (!a.hasOwnProperty(k)) continue;
+    seen[k] = true;
+    var bv = 0;
+    if (b.hasOwnProperty(k)) bv = b[k];
+    if (a[k] !== bv) {
+      if (!out) out = {};
+      out[k] = { from: a[k], to: bv };
+    }
+  }
+  for (k in b) {
+    if (!b.hasOwnProperty(k)) continue;
+    if (seen[k]) continue;
+    if (!out) out = {};
+    out[k] = { from: 0, to: b[k] };
+  }
+  return out;
+}
+
+var __DIFF_EXACT_FIELDS = ["name", "type", "enabled"];
+var __DIFF_TIME_FIELDS = ["inPoint", "outPoint", "startTime"];
+var __DIFF_COUNT_FIELDS = ["expressionCount", "effectCount"];
+
+// `index` is deliberately not compared here: inserting one layer shifts every
+// index below it, which would report twenty changed layers for one addition.
+// Relative order is compared separately, in __diffReordered.
+function __diffLayer(a, b) {
+  var ch = {};
+  var n = 0;
+  var i, k;
+  for (i = 0; i < __DIFF_EXACT_FIELDS.length; i++) {
+    k = __DIFF_EXACT_FIELDS[i];
+    if (a[k] !== b[k]) { ch[k] = { from: a[k], to: b[k] }; n += 1; }
+  }
+  for (i = 0; i < __DIFF_TIME_FIELDS.length; i++) {
+    k = __DIFF_TIME_FIELDS[i];
+    if (__diffMoved(a[k], b[k])) { ch[k] = { from: a[k], to: b[k] }; n += 1; }
+  }
+  for (i = 0; i < __DIFF_COUNT_FIELDS.length; i++) {
+    k = __DIFF_COUNT_FIELDS[i];
+    if (a[k] !== b[k]) { ch[k] = { from: a[k], to: b[k] }; n += 1; }
+  }
+  if (a.parentId !== b.parentId) { ch.parentId = { from: a.parentId, to: b.parentId }; n += 1; }
+  var kc = __diffKeyCounts(a.keyCounts || {}, b.keyCounts || {});
+  if (kc) { ch.keyCounts = kc; n += 1; }
+  if (n === 0) return null;
+  return { id: b.id, name: b.name, changes: ch };
+}
+
+// Only layers present on both sides, and only when their order relative to one
+// another actually changed. A layer added or removed elsewhere in the stack is
+// not a reorder of anything.
+function __diffReordered(before, after, aMap, bMap) {
+  var seqA = [];
+  var seqB = [];
+  var i;
+  for (i = 0; i < before.layers.length; i++) {
+    var idA = before.layers[i].id;
+    if (bMap.hasOwnProperty("L" + idA)) seqA.push(idA);
+  }
+  for (i = 0; i < after.layers.length; i++) {
+    var idB = after.layers[i].id;
+    if (aMap.hasOwnProperty("L" + idB)) seqB.push(idB);
+  }
+  if (seqA.length !== seqB.length) return null;
+  var same = true;
+  for (i = 0; i < seqA.length; i++) {
+    if (seqA[i] !== seqB[i]) { same = false; break; }
+  }
+  if (same) return null;
+  var posA = {};
+  for (i = 0; i < seqA.length; i++) posA["L" + seqA[i]] = i;
+  var moved = [];
+  for (i = 0; i < seqB.length; i++) {
+    var id = seqB[i];
+    if (posA["L" + id] === i) continue;
+    moved.push({
+      id: id,
+      name: bMap["L" + id].name,
+      fromIndex: aMap["L" + id].index,
+      toIndex: bMap["L" + id].index
+    });
+  }
+  if (moved.length === 0) return null;
+  return moved;
+}
+
+function __diffMarkers(a, b) {
+  if (a.length !== b.length) return { from: a.length, to: b.length };
+  for (var i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return { count: a.length, edited: true };
+  }
+  return null;
+}
+
+function __diffCompFields(a, b) {
+  var ch = {};
+  var n = 0;
+  if (a.name !== b.name) { ch.name = { from: a.name, to: b.name }; n += 1; }
+  if (a.width !== b.width || a.height !== b.height) {
+    ch.size = { from: [a.width, a.height], to: [b.width, b.height] };
+    n += 1;
+  }
+  if (__diffMoved(a.duration, b.duration)) { ch.duration = { from: a.duration, to: b.duration }; n += 1; }
+  if (__diffMoved(a.frameRate, b.frameRate)) { ch.frameRate = { from: a.frameRate, to: b.frameRate }; n += 1; }
+  if (__diffMoved(a.workAreaStart, b.workAreaStart) || __diffMoved(a.workAreaDuration, b.workAreaDuration)) {
+    ch.workArea = {
+      from: [a.workAreaStart, a.workAreaDuration],
+      to: [b.workAreaStart, b.workAreaDuration]
+    };
+    n += 1;
+  }
+  var mk = __diffMarkers(a.markers || [], b.markers || []);
+  if (mk) { ch.markers = mk; n += 1; }
+  if (n === 0) return null;
+  return ch;
+}
+
+// ---------- summary prose ----------
+
+function __diffPlural(n) {
+  if (n === 1) return "";
+  return "s";
+}
+
+// "512-514" for a run, "512, 517" otherwise. Ids come out of AE in creation
+// order, so a batch of new layers is nearly always consecutive and this is the
+// difference between a readable line and a wall of numbers.
+function __diffIdList(ids) {
+  if (!ids.length) return "";
+  var sorted = [];
+  for (var i = 0; i < ids.length; i++) sorted.push(ids[i]);
+  sorted.sort(function (x, y) { return x - y; });
+  var parts = [];
+  var start = sorted[0];
+  var prev = sorted[0];
+  for (var j = 1; j <= sorted.length; j++) {
+    var cur = sorted[j];
+    var breaks = true;
+    if (j < sorted.length && cur === prev + 1) breaks = false;
+    if (breaks) {
+      if (start === prev) parts.push(String(start));
+      else if (prev === start + 1) parts.push(String(start) + ", " + String(prev));
+      else parts.push(String(start) + "-" + String(prev));
+      start = cur;
+    }
+    prev = cur;
+  }
+  return parts.join(", ");
+}
+
+function __diffParentLabel(v) {
+  if (v === null || v === undefined) return "none";
+  return String(v);
+}
+
+function __diffLayerPhrases(entry) {
+  var label = "layer " + entry.id;
+  var c = entry.changes;
+  var out = [];
+  if (c.name) out.push(label + ' renamed "' + c.name.from + '" -> "' + c.name.to + '"');
+  if (c.enabled) {
+    if (c.enabled.to) out.push(label + " enabled");
+    else out.push(label + " disabled");
+  }
+  var times = [];
+  if (c.inPoint) times.push("in " + c.inPoint.from + " -> " + c.inPoint.to);
+  if (c.outPoint) times.push("out " + c.outPoint.from + " -> " + c.outPoint.to);
+  if (c.startTime) times.push("start " + c.startTime.from + " -> " + c.startTime.to);
+  if (times.length) out.push(label + " retimed (" + times.join(", ") + ")");
+  if (c.parentId) {
+    out.push(label + " re-parented " + __diffParentLabel(c.parentId.from) + " -> " + __diffParentLabel(c.parentId.to));
+  }
+  if (c.keyCounts) {
+    for (var k in c.keyCounts) {
+      if (!c.keyCounts.hasOwnProperty(k)) continue;
+      out.push(label + " " + k + " keys " + c.keyCounts[k].from + " -> " + c.keyCounts[k].to);
+    }
+  }
+  if (c.effectCount) out.push(label + " effects " + c.effectCount.from + " -> " + c.effectCount.to);
+  if (c.expressionCount) {
+    out.push(label + " expressions " + c.expressionCount.from + " -> " + c.expressionCount.to);
+  }
+  if (c.type) out.push(label + " type " + c.type.from + " -> " + c.type.to);
+  return out;
+}
+
+function __diffCompPhrases(ch) {
+  var out = [];
+  if (ch.name) out.push('comp renamed "' + ch.name.from + '" -> "' + ch.name.to + '"');
+  if (ch.size) {
+    out.push("comp resized " + ch.size.from[0] + "x" + ch.size.from[1] + " -> " + ch.size.to[0] + "x" + ch.size.to[1]);
+  }
+  if (ch.duration) out.push("comp duration " + ch.duration.from + " -> " + ch.duration.to);
+  if (ch.frameRate) out.push("comp frame rate " + ch.frameRate.from + " -> " + ch.frameRate.to);
+  if (ch.workArea) out.push("comp work area moved");
+  if (ch.markers) {
+    if (ch.markers.edited) out.push("comp markers edited");
+    else out.push("comp markers " + ch.markers.from + " -> " + ch.markers.to);
+  }
+  return out;
+}
+
+// One line. Past this many clauses the rest is counted rather than spelled out
+// — the structured fields carry everything, and a summary nobody reads to the
+// end is worse than a short one that names where to look.
+var __DIFF_SUMMARY_CLAUSES = 8;
+
+function __diffSummary(d) {
+  var parts = [];
+  var i;
+  if (d.added) {
+    var addedIds = [];
+    for (i = 0; i < d.added.length; i++) addedIds.push(d.added[i].id);
+    parts.push(d.added.length + " layer" + __diffPlural(d.added.length) + " added: ids " + __diffIdList(addedIds));
+  }
+  if (d.removed) {
+    var removedIds = [];
+    for (i = 0; i < d.removed.length; i++) removedIds.push(d.removed[i].id);
+    parts.push(d.removed.length + " layer" + __diffPlural(d.removed.length) + " removed: ids " + __diffIdList(removedIds));
+  }
+  if (d.reordered) {
+    parts.push(d.reordered.length + " layer" + __diffPlural(d.reordered.length) + " moved in the stack");
+  }
+  if (d.changed) {
+    for (i = 0; i < d.changed.length; i++) {
+      var phrases = __diffLayerPhrases(d.changed[i]);
+      for (var p = 0; p < phrases.length; p++) parts.push(phrases[p]);
+    }
+  }
+  if (d.comp) {
+    var compPhrases = __diffCompPhrases(d.comp);
+    for (i = 0; i < compPhrases.length; i++) parts.push(compPhrases[i]);
+  }
+  if (parts.length === 0) {
+    return "No differences in the recorded fields. Property values, expression text, effect parameters " +
+      "and shape contents are not compared, so this is not a claim that nothing changed at all.";
+  }
+  if (parts.length > __DIFF_SUMMARY_CLAUSES) {
+    var extra = parts.length - __DIFF_SUMMARY_CLAUSES;
+    parts = parts.slice(0, __DIFF_SUMMARY_CLAUSES);
+    parts.push("and " + extra + " more change" + __diffPlural(extra) + " (see the fields below)");
+  }
+  return parts.join("; ");
+}
+
+// Two fingerprints -> only what moved. Unchanged layers are counted, never
+// listed: listing them is the cost this whole thing exists to avoid.
+function __diffFingerprints(before, after) {
+  var aMap = __fpById(before);
+  var bMap = __fpById(after);
+  var added = [];
+  var removed = [];
+  var changed = [];
+  var unchanged = 0;
+  var i, l;
+  for (i = 0; i < after.layers.length; i++) {
+    l = after.layers[i];
+    var prev = aMap["L" + l.id];
+    if (!prev) {
+      added.push({ id: l.id, name: l.name, index: l.index, type: l.type });
+      continue;
+    }
+    var d = __diffLayer(prev, l);
+    if (d) changed.push(d);
+    else unchanged += 1;
+  }
+  for (i = 0; i < before.layers.length; i++) {
+    l = before.layers[i];
+    if (bMap.hasOwnProperty("L" + l.id)) continue;
+    removed.push({ id: l.id, name: l.name, index: l.index, type: l.type });
+  }
+  var reordered = __diffReordered(before, after, aMap, bMap);
+  var comp = __diffCompFields(before, after);
+
+  var out = { compId: after.compId, compName: after.name };
+  if (added.length) out.added = added;
+  if (removed.length) out.removed = removed;
+  if (changed.length) out.changed = changed;
+  if (reordered) out.reordered = reordered;
+  if (comp) out.comp = comp;
+  out.unchangedLayers = unchanged;
+  var count = added.length + removed.length + changed.length;
+  if (reordered) count += reordered.length;
+  if (comp) count += 1;
+  out.changeCount = count;
+  out.summary = __diffSummary(out);
+  out.covers = __DIFF_COVERS;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Ops
+// ---------------------------------------------------------------------------
+// Both are internal: the tools an agent sees are snapshot_comp and diff_comp,
+// and those are half server-resident. Only the panel can read After Effects,
+// and only the server can remember anything between calls — so the server
+// keeps the fingerprint and these two gather it. See snapshots/store.ts.
+
+OPS._comp_fingerprint = noUndo(function (args) {
+  return __compFingerprint(args.compId);
+});
+
+OPS._comp_diff = noUndo(function (args) {
+  var before = args.since;
+  if (!before || !before.layers) {
+    throw new Error("_comp_diff needs a stored fingerprint in `since` (the MCP server supplies it from the snapshot id)");
+  }
+  var compId = args.compId;
+  if (compId === undefined || compId === null) compId = before.compId;
+  var after = __compFingerprint(compId);
+  return { diff: __diffFingerprints(before, after), fingerprint: after };
+});
+
+// ---------------------------------------------------------------------------
+// diff:true on the write ops
+// ---------------------------------------------------------------------------
+// The before-fingerprint has to be taken inside the same bridge call as the
+// write, or it is not a before at all: a separate snapshot_comp is a second
+// round-trip during which anything can happen, and the agent has to remember to
+// make it. run_jsx and run_batch therefore fingerprint, run, fingerprint again,
+// and diff — one call, one answer.
+
+function __diffPushUnique(list, v) {
+  for (var i = 0; i < list.length; i++) {
+    if (list[i] === v) return;
+  }
+  list.push(v);
+}
+
+// Explicit diffCompId wins. Otherwise a batch names its own comps in its ops,
+// and a script gets the comp the user is looking at. When none of the three
+// yields anything the diff is refused with a reason rather than quietly
+// skipped — a missing diff that looks like "nothing changed" is the failure
+// this whole feature exists to prevent.
+function __diffCompIds(args, ops) {
+  var ids = [];
+  if (args && args.diffCompId !== undefined && args.diffCompId !== null) {
+    __diffPushUnique(ids, args.diffCompId);
+    return ids;
+  }
+  if (ops) {
+    for (var i = 0; i < ops.length; i++) {
+      var a = ops[i].args;
+      if (a && typeof a.compId === "number") __diffPushUnique(ids, a.compId);
+    }
+    if (ids.length > 0) return ids;
+  }
+  var active = null;
+  try { active = app.project.activeItem; } catch (e) {}
+  if (active && active instanceof CompItem) __diffPushUnique(ids, active.id);
+  return ids;
+}
+
+function __diffStart(args, ops) {
+  if (!args || !args.diff) return null;
+  var ids = __diffCompIds(args, ops);
+  if (ids.length === 0) {
+    return {
+      unavailable: true,
+      reason: "no compId appeared in this call and no composition is open in the viewer — pass diffCompId to name the comp to fingerprint"
+    };
+  }
+  var state = { ids: ids, before: [], unavailable: false };
+  for (var i = 0; i < ids.length; i++) {
+    try {
+      state.before.push(__compFingerprint(ids[i]));
+    } catch (e) {
+      return { unavailable: true, reason: "comp " + ids[i] + " could not be fingerprinted before the call: " + e.message };
+    }
+  }
+  return state;
+}
+
+function __diffFinish(state) {
+  if (!state) return null;
+  if (state.unavailable) {
+    return {
+      unavailable: true,
+      reason: state.reason,
+      summary: "No diff was taken: " + state.reason + ". The call itself is unaffected."
+    };
+  }
+  var comps = [];
+  var total = 0;
+  for (var i = 0; i < state.before.length; i++) {
+    var b = state.before[i];
+    var after = null;
+    try {
+      after = __compFingerprint(b.compId);
+    } catch (e) {
+      comps.push({
+        compId: b.compId,
+        compName: b.name,
+        gone: true,
+        changeCount: 1,
+        summary: "comp " + b.compId + ' ("' + b.name + '") can no longer be read: ' + e.message
+      });
+      total += 1;
+      continue;
+    }
+    var d = __diffFingerprints(b, after);
+    comps.push(d);
+    total += d.changeCount;
+  }
+  if (comps.length === 1) return comps[0];
+  var parts = [];
+  for (var j = 0; j < comps.length; j++) parts.push("comp " + comps[j].compId + ": " + comps[j].summary);
+  return { comps: comps, changeCount: total, summary: parts.join(" | "), covers: __DIFF_COVERS };
+}
+
+// A script or batch that threw still changed whatever it changed before it
+// stopped, and nothing rolls back. Finding that stop point by reading the comp
+// back is one of the three cases issue #52 was opened for, so the diff is put
+// where the agent will actually see it: on the error. The error object itself
+// is mutated rather than replaced, so `line` and `stack` survive for the
+// caller's own reporting.
+function __diffAnnotateError(e, state) {
+  if (!state) return;
+  var d = null;
+  try { d = __diffFinish(state); } catch (e2) { return; }
+  if (!d || !d.summary) return;
+  try {
+    e.message = String(e.message) + " || Changed before it stopped: " + d.summary +
+      " (nothing rolls back - read the state back rather than re-running)";
+  } catch (e3) {}
+}
+
+// run_jsx returns whatever the script returned, which may be a number or a
+// string with nowhere to hang a diff on. With diff:true it is enveloped
+// instead. The null envelope __rjResult already builds is the right shape
+// already, so that one is extended rather than nested inside a second one.
+function __rjWithDiff(out, diff, undoGroupName) {
+  if (out && typeof out === "object" && !(out instanceof Array) &&
+      out.ok === true && out.returned === null && out.note) {
+    out.diff = diff;
+    return out;
+  }
+  return { ok: true, returned: out, undoGroup: undoGroupName, diff: diff };
+}
+
+
 // ===== transforms.jsx =====
 
 // transforms.jsx — fast-path for setting common transform properties.
@@ -889,50 +1776,121 @@ function __findKeyIndexAtTime(prop, time, eps) {
   return -1;
 }
 
-function __applyInterpolationToKey(prop, keyIndex, interp) {
-  if (!interp) return;
-  var inT = interp["in"] && __INTERP_MAP[interp["in"]] ? __INTERP_MAP[interp["in"]] : prop.keyInInterpolationType(keyIndex);
-  var outT = interp["out"] && __INTERP_MAP[interp["out"]] ? __INTERP_MAP[interp["out"]] : prop.keyOutInterpolationType(keyIndex);
-  prop.setInterpolationTypeAtKey(keyIndex, inT, outT);
-  if (interp.easeIn || interp.easeOut) {
-    // AE's setTemporalEaseAtKey expects an array of KeyframeEase per dimension —
-    // BUT spatial properties (Position, Anchor Point) use a single ease entry that
-    // applies along the motion path, regardless of 2D/3D. Non-spatial multi-dim
-    // properties (Scale, Color) need one entry per dimension.
-    var dim;
-    if (prop.isSpatial) {
-      dim = 1;
-    } else {
-      dim = (prop.value && prop.value.length) ? prop.value.length : 1;
-    }
-    var inEase = interp.easeIn || { influence: 33, speed: 0 };
-    var outEase = interp.easeOut || { influence: 33, speed: 0 };
-    var inArr = []; var outArr = [];
-    for (var d = 0; d < dim; d++) {
-      inArr.push(new KeyframeEase(inEase.speed, inEase.influence));
-      outArr.push(new KeyframeEase(outEase.speed, outEase.influence));
-    }
-    prop.setTemporalEaseAtKey(keyIndex, inArr, outArr);
+// ---------- ease array sizing (issue #50) ----------
+//
+// setTemporalEaseAtKey wants an array of KeyframeEase whose length belongs to
+// the *property*, and it is not derivable from the value: a 2D layer Scale
+// wants 3, a shape Ellipse Size wants 2 while its value reads [w,h], Opacity
+// and a slider want 1, and a spatial Position wants 1 whether the layer is 2D
+// or 3D because the ease runs along the motion path. Get it wrong and AE throws
+// "parameter 2" and says nothing else — no property name, no expected count.
+//
+// So: derive the likely count from the property, then try the others. The
+// derivation is the fast path; the retry is the safety net, because the Ellipse
+// Size case is precisely the one no table gets right from the outside. Whatever
+// AE accepted is reported back, so the answer for a given property stops being
+// folklore and becomes something a caller can read off a result.
+var __EASE_ARITIES = [1, 2, 3, 4];
+
+/** The count to try first, from the property rather than from the value passed in. */
+function __easePropertyArity(prop) {
+  // Spatial first and unconditionally: a 3D Position is ThreeD_SPATIAL and
+  // still takes one entry, so the value type must not get a say here.
+  if (prop.isSpatial) return 1;
+  var vt = null;
+  try { vt = prop.propertyValueType; } catch (eType) {}
+  if (vt !== null && vt !== undefined && typeof PropertyValueType !== "undefined") {
+    if (vt === PropertyValueType.OneD) return 1;
+    if (vt === PropertyValueType.TwoD) return 2;
+    if (vt === PropertyValueType.TwoD_SPATIAL) return 1;
+    if (vt === PropertyValueType.ThreeD) return 3;
+    if (vt === PropertyValueType.ThreeD_SPATIAL) return 1;
+    if (vt === PropertyValueType.COLOR) return 4;
   }
+  var v = null;
+  try { v = prop.value; } catch (eVal) {}
+  if (v && v.length) return v.length;
+  return 1;
 }
 
-OPS.add_keyframe = function (args) {
-  var c = getCompById(args.compId);
-  var l = getLayerById(c, args.layerId);
-  var prop = walkProperty(l, args.propertyPath);
-  prop.setValueAtTime(args.time, args.value);
-  if (args.interpolation) {
-    var idx = __findKeyIndexAtTime(prop, args.time);
-    if (idx > 0) __applyInterpolationToKey(prop, idx, args.interpolation);
+/** Derived count first, then every other plausible one, no repeats. */
+function __easeArityCandidates(prop) {
+  var first = __easePropertyArity(prop);
+  var out = [first];
+  for (var i = 0; i < __EASE_ARITIES.length; i++) {
+    if (__EASE_ARITIES[i] !== first) out.push(__EASE_ARITIES[i]);
   }
-  return { ok: true, keyIndex: __findKeyIndexAtTime(prop, args.time) };
-};
+  return out;
+}
 
-OPS.remove_keyframe = function (args) {
-  var c = getCompById(args.compId);
-  var l = getLayerById(c, args.layerId);
-  var prop = walkProperty(l, args.propertyPath);
-  var idx = __findKeyIndexAtTime(prop, args.time);
+function __easeArray(ease, n) {
+  var arr = [];
+  for (var i = 0; i < n; i++) arr.push(new KeyframeEase(ease.speed, ease.influence));
+  return arr;
+}
+
+/**
+ * Apply one {influence, speed} pair to every dimension of `prop` at `keyIndex`,
+ * and return the number of KeyframeEase entries After Effects accepted.
+ *
+ * Throws only when no count works, naming every one it tried. An ease that
+ * quietly failed to land is invisible until someone watches the render, which
+ * is the same class of lie as a swallowed error.
+ */
+function __applyTemporalEase(prop, keyIndex, easeIn, easeOut) {
+  var inEase = easeIn || { influence: 33, speed: 0 };
+  var outEase = easeOut || { influence: 33, speed: 0 };
+  var candidates = __easeArityCandidates(prop);
+  var lastMessage = "";
+  for (var i = 0; i < candidates.length; i++) {
+    var n = candidates[i];
+    try {
+      prop.setTemporalEaseAtKey(keyIndex, __easeArray(inEase, n), __easeArray(outEase, n));
+      return n;
+    } catch (e) {
+      lastMessage = (e && e.message) ? String(e.message) : String(e);
+    }
+  }
+  var label = "the property";
+  try { label = "'" + prop.name + "'"; } catch (eName) {}
+  throw new Error(
+    "Could not set the temporal ease on " + label + " at key " + keyIndex + ": After Effects rejected ease " +
+    "arrays of " + candidates.join(", ") + " entries. Last error from AE: " + lastMessage
+  );
+}
+
+/** Returns the ease arity that was used, or null when no ease was requested. */
+function __applyInterpolationToKey(prop, keyIndex, interp) {
+  if (!interp) return null;
+  var inT = interp["in"] && __INTERP_MAP[interp["in"]] ? __INTERP_MAP[interp["in"]] : prop.keyInInterpolationType(keyIndex);
+  var outT = interp["out"] && __INTERP_MAP[interp["out"]] ? __INTERP_MAP[interp["out"]] : prop.keyOutInterpolationType(keyIndex);
+  prop.setInterpolationTypeAtKey(keyIndex, inT, outT);
+  if (interp.easeIn || interp.easeOut) {
+    return __applyTemporalEase(prop, keyIndex, interp.easeIn, interp.easeOut);
+  }
+  return null;
+}
+
+OPS.add_keyframe = function (args) {
+  var c = getCompById(args.compId);
+  var l = getLayerById(c, args.layerId);
+  var prop = walkProperty(l, args.propertyPath);
+  prop.setValueAtTime(args.time, args.value);
+  var easeDimensions = null;
+  if (args.interpolation) {
+    var idx = __findKeyIndexAtTime(prop, args.time);
+    if (idx > 0) easeDimensions = __applyInterpolationToKey(prop, idx, args.interpolation);
+  }
+  var out = { ok: true, keyIndex: __findKeyIndexAtTime(prop, args.time) };
+  if (easeDimensions !== null) out.easeDimensions = easeDimensions;
+  return out;
+};
+
+OPS.remove_keyframe = function (args) {
+  var c = getCompById(args.compId);
+  var l = getLayerById(c, args.layerId);
+  var prop = walkProperty(l, args.propertyPath);
+  var idx = __findKeyIndexAtTime(prop, args.time);
   if (idx < 1) throw new Error("No keyframe at time " + args.time);
   prop.removeKey(idx);
   return { ok: true };
@@ -992,8 +1950,13 @@ OPS.set_temporal_ease = function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
   var prop = walkProperty(l, args.propertyPath);
-  __applyInterpolationToKey(prop, args.keyIndex, { easeIn: args.easeIn, easeOut: args.easeOut });
-  return { ok: true };
+  // A call with neither ease would previously return {ok:true} having done
+  // nothing at all, which reads as "the ease is set" to whoever asked for it.
+  if (!args.easeIn && !args.easeOut) {
+    throw new Error("set_temporal_ease needs easeIn, easeOut or both — nothing was changed.");
+  }
+  var n = __applyTemporalEase(prop, args.keyIndex, args.easeIn, args.easeOut);
+  return { ok: true, easeDimensions: n };
 };
 
 OPS.set_spatial_tangents = function (args) {
@@ -1600,10 +2563,26 @@ var __SCREENSHOT_TARGET_PX = 1280;
 // The correct downsample was always derivable from the comp, and an agent that
 // forgot it got a full-resolution 4K frame — the most expensive accident
 // available through these tools. So derive it, and let an explicit value win.
+function __autoDownsampleFor(comp, targetPx) {
+  var longEdge = comp.width > comp.height ? comp.width : comp.height;
+  var n = Math.ceil(longEdge / targetPx);
+  if (!(n > 1)) return 1;
+  return n > 8 ? 8 : n;
+}
+
 // 1080p -> 2 (960px), 4K -> 3 (1280px), and anything already small -> 1.
 function __autoDownsample(comp) {
-  var longEdge = comp.width > comp.height ? comp.width : comp.height;
-  var n = Math.ceil(longEdge / __SCREENSHOT_TARGET_PX);
+  return __autoDownsampleFor(comp, __SCREENSHOT_TARGET_PX);
+}
+
+// A contact sheet of N frames has to cost about what one frame costs, so each
+// tile gets 1/sqrt(N) of the single-frame long edge — N tiles of 1/N the area
+// each. Expressed as a multiple of what this comp's *single* frame would have
+// used rather than as its own target, for two reasons: it cannot drift from
+// __autoDownsample, and the factor is an integer, so deriving from the target
+// instead would let the rounding leave a 1080p sheet at nearly twice the budget.
+function __tileDownsample(comp, count) {
+  var n = Math.ceil(__autoDownsample(comp) * Math.sqrt(count));
   if (!(n > 1)) return 1;
   return n > 8 ? 8 : n;
 }
@@ -1617,24 +2596,68 @@ function __resolveDownsample(comp, requested) {
 // reduced frame directly instead of writing full size and resampling
 // afterwards. That is faster (a quarter of the pixels at factor 2) and needs no
 // external image tool, which is what makes it work off macOS.
+//
+// Factor 1 is *set*, not skipped. Skipping it rendered at whatever the user had
+// left the viewer on, so a comp parked at Quarter answered `downsample: 1` with
+// a quarter-size frame and `downsample: 2` came back **larger** than
+// `downsample: 1` (issue #72). Designers leave heavy comps at Quarter or Third
+// as a matter of course, so that was the common case rather than a corner. The
+// panel reads the real dimensions out of the PNG's IHDR, which means the
+// response stayed honest while the *picture* was not the one asked for — the
+// worse of the two failures, because an agent that can see a frame believes it.
+// Every factor reaching this function now names the resolution it renders at.
 function __saveFrameAt(comp, time, file, factor) {
-  if (factor <= 1) {
-    comp.saveFrameToPng(time, file);
-    return;
-  }
+  var f = (factor > 1) ? Math.round(factor) : 1;
   var previous = comp.resolutionFactor;
   try {
-    comp.resolutionFactor = [factor, factor];
+    comp.resolutionFactor = [f, f];
     comp.saveFrameToPng(time, file);
   } finally {
     // Restore unconditionally — a failed render must never leave the user
-    // looking at a half-resolution comp.
+    // looking at a half-resolution comp. This covers factor 1 too: the render
+    // happens at Full and the viewer goes back to Quarter afterwards.
     comp.resolutionFactor = previous;
   }
 }
 
+// Several times in one call. Every requested time gets an entry, in order,
+// whether or not it rendered — the panel draws a marked block for the ones that
+// did not, so the sheet it composes still lines up with the times that were
+// asked for. Dropping a failed tile would silently renumber the rest, which is
+// the same class of lie as swallowing an error.
+function __contactSheetFrames(comp, args) {
+  var times = args.times;
+  var ds;
+  if (args.downsample === undefined || args.downsample === null) {
+    ds = __tileDownsample(comp, times.length);
+  } else {
+    ds = __clampDownsample(args.downsample);
+  }
+  var tiles = [];
+  for (var i = 0; i < times.length; i++) {
+    var entry = { time: times[i], downsample: ds };
+    try {
+      var p = __tmpPngPath();
+      __saveFrameAt(comp, times[i], new File(p), ds);
+      entry.path = p;
+    } catch (e) {
+      // One time that will not render must not cost the other five.
+      entry.error = String(e && e.message ? e.message : e);
+    }
+    tiles.push(entry);
+  }
+  return {
+    contactSheet: true,
+    tiles: tiles,
+    downsample: ds,
+    width: comp.width, height: comp.height,
+    times: times, compId: comp.id
+  };
+}
+
 OPS.screenshot_frame = noUndo(function (args) {
   var c = getCompById(args.compId);
+  if (args.times && args.times.length) return __contactSheetFrames(c, args);
   var t = (args.time !== undefined && args.time !== null) ? args.time : c.time;
   var ds = __resolveDownsample(c, args.downsample);
   var path = __tmpPngPath();
@@ -1789,22 +2812,53 @@ function __brokenSvgAdvice() {
   );
 }
 
-OPS.import_footage = function (args) {
-  var path = args && args.path;
-  if (typeof path !== "string" || path.length === 0) throw new Error("path is required");
-
-  var file = new File(path);
-  if (!file.exists) throw new Error("No file at " + path);
-
+/**
+ * The bare import — ImportOptions, importFile, and the two ways AE can decline.
+ * Kept as its own function because it is the only import in the codebase and
+ * anything else that needs a file in the project (audio.jsx) must go through
+ * exactly this, not a second copy that drifts.
+ */
+function __importFile(file, path, sequence) {
   var opts = new ImportOptions(file);
-  if (args.sequence === true) {
+  if (sequence === true) {
     if (!opts.canImportAs(ImportAsType.FOOTAGE)) throw new Error("Cannot import " + path + " as footage, so it cannot be a sequence either");
     opts.importAs = ImportAsType.FOOTAGE;
     opts.sequence = true;
   }
-
   var item = app.project.importFile(opts);
   if (!item) throw new Error("After Effects returned no item for " + path);
+  return item;
+}
+
+/**
+ * fsName -> project item, for every item in the project that came from a file.
+ * One pass: the caller with N paths to resolve would otherwise walk the project
+ * N times, and a project with a few hundred items makes that visible.
+ */
+function __itemPathMap() {
+  var map = {};
+  var proj = app.project;
+  for (var i = 1; i <= proj.numItems; i++) {
+    var it = proj.item(i);
+    var key = null;
+    try {
+      if (it.mainSource && it.mainSource.file) key = String(it.mainSource.file.fsName);
+    } catch (e) {}
+    // First one wins: two items on the same file are a duplicate import, and
+    // reusing the earlier is what the user would have done by hand.
+    if (key && !map.hasOwnProperty(key)) map[key] = it;
+  }
+  return map;
+}
+
+OPS.import_footage = function (args) {
+  var path = args && args.path;
+  if (typeof path !== "string" || path.length === 0) throw new Error("path is required");
+
+  var file = new File(path);
+  if (!file.exists) throw new Error("No file at " + path);
+
+  var item = __importFile(file, path, args.sequence);
 
   if (typeof args.name === "string" && args.name.length > 0) item.name = args.name;
 
@@ -1868,6 +2922,432 @@ OPS.create_footage_layer = function (args) {
 };
 
 
+// ===== audio.jsx =====
+
+// audio.jsx — place a list of sound effects into a comp in one pass.
+//
+// Scoring a scene is 40-90 layers: import or reuse the file, add a layer, set
+// its start time, set its level in dB, name it, sometimes trim it. Done through
+// the general tools that is dozens of round trips; done through run_jsx it is a
+// hand-written loop that has to know the one thing nothing tells you —
+// `layer.property("ADBE Audio Levels")` returns **null** on an audio layer,
+// because Audio Levels lives under the layer's "Audio" group and the only
+// reliable handle is the `layer.audioLevels` shortcut (issue #48).
+//
+// Two properties carry the design:
+//
+//   - Nothing is created until every cue has been checked. A run that dies on
+//     cue 30 of 90 leaves 29 sound effects in someone's timeline and an error
+//     that does not say which ones — the same half-built failure
+//     add_shape_content refuses to produce. So: plan first with no side
+//     effects, throw naming the offending cue indices, and if a creation still
+//     fails, remove everything this call made before rethrowing.
+//   - A file named by several cues is imported once. Repeated imports of one
+//     .wav are the normal shape of a cue list ("whoosh" nine times), and each
+//     one would otherwise add another project item. Anything already in the
+//     project from that path is reused rather than imported a second time.
+
+var __MAX_AUDIO_CUES = 200;
+var __CUE_TIME_EPS = 1e-6;
+
+// AE's layer label colours. Users can rename them in preferences, but the tool
+// takes an index and the indices do not move, so the names are accepted as a
+// convenience and translated here. 0 is "None".
+var __LABEL_NAMES = {
+  none: 0, red: 1, yellow: 2, aqua: 3, pink: 4, lavender: 5, peach: 6,
+  seafoam: 7, blue: 8, green: 9, purple: 10, orange: 11, brown: 12,
+  fuchsia: 13, cyan: 14, sandstone: 15, darkgreen: 16
+};
+
+function __labelKey(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function __labelNameList() {
+  var names = [];
+  for (var k in __LABEL_NAMES) {
+    if (__LABEL_NAMES.hasOwnProperty(k)) names.push(k);
+  }
+  return names.join(", ");
+}
+
+/** 0..16, or a thrown error naming everything it would have taken. */
+function __resolveLabel(label) {
+  if (typeof label === "number") {
+    if (label !== Math.floor(label) || label < 0 || label > 16) {
+      throw new Error("label must be a whole number 0-16 or a colour name (" + __labelNameList() + "); got " + label);
+    }
+    return label;
+  }
+  var key = __labelKey(label);
+  if (__LABEL_NAMES.hasOwnProperty(key)) return __LABEL_NAMES[key];
+  throw new Error("unknown label \"" + label + "\" — use 0-16 or one of: " + __labelNameList());
+}
+
+function __basename(p) {
+  var s = String(p).replace(/\\/g, "/");
+  var slash = s.lastIndexOf("/");
+  if (slash >= 0) s = s.substring(slash + 1);
+  return s;
+}
+
+function __stripExtension(name) {
+  var s = String(name);
+  var dot = s.lastIndexOf(".");
+  if (dot > 0) return s.substring(0, dot);
+  return s;
+}
+
+/**
+ * The Audio Levels property of a layer.
+ *
+ * `layer.audioLevels` is the shortcut that works. `layer.property("ADBE Audio
+ * Levels")` returns null on an audio layer — the property sits inside the
+ * layer's "Audio" group, not on the layer — and a null there is what silently
+ * turns a scripted level into no level at all. The group walk is only a
+ * fallback for a layer whose shortcut is somehow absent; if neither answers,
+ * the caller is told rather than left with an unset level.
+ */
+function __audioLevelsProperty(layer) {
+  var p = null;
+  try { p = layer.audioLevels; } catch (e) {}
+  if (p) return p;
+  try {
+    var g = layer.property("Audio");
+    if (g) p = g.property("Audio Levels");
+  } catch (e2) {}
+  return p;
+}
+
+/** null when the item can carry an audio cue, else the reason it cannot. */
+function __audioItemProblem(item) {
+  if (item instanceof FolderItem) return "\"" + item.name + "\" is a folder, not footage";
+  if (item instanceof CompItem) return "\"" + item.name + "\" is a comp — use create_precomp_layer for that";
+  if (item.footageMissing) return "\"" + item.name + "\" is offline; the file it points at is missing";
+  // Explicitly `=== false`, not `!item.hasAudio`: an item that does not report
+  // the flag at all must not be refused on the strength of a missing property.
+  if (item.hasAudio === false) return "\"" + item.name + "\" has no audio track";
+  return null;
+}
+
+function __sourceReport(item, path) {
+  return { itemId: item.id, name: item.name, path: path };
+}
+
+/**
+ * Turn the cue list into a plan, touching nothing. Every problem found is
+ * collected with the index of the cue that caused it rather than thrown on the
+ * spot, so one call reports all of them instead of one per round trip.
+ */
+function __planAudioCues(comp, args) {
+  var cues = args.cues;
+  if (!(cues instanceof Array) || cues.length === 0) {
+    throw new Error("place_audio_cues needs a non-empty `cues` array.");
+  }
+  if (cues.length > __MAX_AUDIO_CUES) {
+    throw new Error(
+      "place_audio_cues was given " + cues.length + " cues and the limit is " + __MAX_AUDIO_CUES + " per call. " +
+      "ExtendScript is single-threaded, so one long run freezes After Effects' interface for its whole duration. " +
+      "Split the list into calls of " + __MAX_AUDIO_CUES + " or fewer."
+    );
+  }
+
+  var prefix = "SFX_";
+  if (typeof args.namePrefix === "string") prefix = args.namePrefix;
+
+  var byPath = __itemPathMap();
+  var problems = [];
+  var planned = [];
+  var toImport = [];
+  var toImportSeen = {};
+
+  for (var i = 0; i < cues.length; i++) {
+    var cue = cues[i];
+    if (!cue) { problems.push({ cue: i, reason: "is empty" }); continue; }
+
+    var hasId = (cue.footageId !== undefined && cue.footageId !== null);
+    var hasPath = (typeof cue.path === "string" && cue.path.length > 0);
+    if (hasId && hasPath) { problems.push({ cue: i, reason: "has both footageId and path — give exactly one" }); continue; }
+    if (!hasId && !hasPath) { problems.push({ cue: i, reason: "has neither footageId nor path — give exactly one" }); continue; }
+
+    var time = cue.time;
+    if (typeof time !== "number" || !isFinite(time)) {
+      problems.push({ cue: i, reason: "time must be a number of seconds; got " + String(time) });
+      continue;
+    }
+    if (time < -__CUE_TIME_EPS || time > comp.duration + __CUE_TIME_EPS) {
+      problems.push({ cue: i, reason: "time " + time + "s is outside the comp, which runs 0 to " + comp.duration + "s" });
+      continue;
+    }
+
+    var levelDb = 0;
+    if (cue.levelDb !== undefined && cue.levelDb !== null) {
+      if (typeof cue.levelDb !== "number" || !isFinite(cue.levelDb)) {
+        problems.push({ cue: i, reason: "levelDb must be a number of decibels (0 is unedited); got " + String(cue.levelDb) });
+        continue;
+      }
+      levelDb = cue.levelDb;
+    }
+
+    var inPoint = null;
+    var outPoint = null;
+    var trimBad = false;
+    if (cue.inPoint !== undefined && cue.inPoint !== null) {
+      if (typeof cue.inPoint !== "number" || !isFinite(cue.inPoint)) {
+        problems.push({ cue: i, reason: "inPoint must be a comp time in seconds; got " + String(cue.inPoint) });
+        trimBad = true;
+      } else {
+        inPoint = cue.inPoint;
+      }
+    }
+    if (!trimBad && cue.outPoint !== undefined && cue.outPoint !== null) {
+      if (typeof cue.outPoint !== "number" || !isFinite(cue.outPoint)) {
+        problems.push({ cue: i, reason: "outPoint must be a comp time in seconds; got " + String(cue.outPoint) });
+        trimBad = true;
+      } else {
+        outPoint = cue.outPoint;
+      }
+    }
+    if (trimBad) continue;
+    // in/out are absolute comp times, like everywhere else in these tools, so
+    // they are measured against `time` rather than against the file.
+    if (inPoint !== null && inPoint < time - __CUE_TIME_EPS) {
+      problems.push({ cue: i, reason: "inPoint " + inPoint + "s is before the cue's own time " + time + "s; both are comp times" });
+      continue;
+    }
+    var trimStart = time;
+    if (inPoint !== null) trimStart = inPoint;
+    if (outPoint !== null && outPoint <= trimStart + __CUE_TIME_EPS) {
+      problems.push({ cue: i, reason: "outPoint " + outPoint + "s is not after the cue starts at " + trimStart + "s" });
+      continue;
+    }
+
+    var label = null;
+    if (cue.label !== undefined && cue.label !== null) {
+      try {
+        label = __resolveLabel(cue.label);
+      } catch (eLabel) {
+        problems.push({ cue: i, reason: eLabel.message });
+        continue;
+      }
+    }
+
+    // Resolve the source. A footageId names an item that must already be
+    // usable; a path is either something the project already holds or an
+    // import this call will do exactly once.
+    var source = null;
+    var defaultName = null;
+    if (hasId) {
+      var item = app.project.itemByID(cue.footageId);
+      if (!item) { problems.push({ cue: i, reason: "no project item with id " + cue.footageId }); continue; }
+      var why = __audioItemProblem(item);
+      if (why) { problems.push({ cue: i, reason: why }); continue; }
+      source = { kind: "item", item: item, fsName: null, path: null };
+      defaultName = item.name;
+    } else {
+      var file = new File(cue.path);
+      if (!file.exists) { problems.push({ cue: i, reason: "no file at " + cue.path }); continue; }
+      var fsName = String(file.fsName);
+      var existing = null;
+      if (byPath.hasOwnProperty(fsName)) existing = byPath[fsName];
+      if (existing) {
+        var whyExisting = __audioItemProblem(existing);
+        if (whyExisting) { problems.push({ cue: i, reason: whyExisting + " (already in the project from " + cue.path + ")" }); continue; }
+        source = { kind: "reused", item: existing, fsName: fsName, path: cue.path };
+      } else {
+        if (!toImportSeen.hasOwnProperty(fsName)) {
+          toImportSeen[fsName] = true;
+          toImport.push({ fsName: fsName, path: cue.path, file: file });
+        }
+        source = { kind: "import", item: null, fsName: fsName, path: cue.path };
+      }
+      // The caller named a path, so the path's basename is the honest default
+      // even when the project item it resolves to was renamed by hand.
+      defaultName = __basename(cue.path);
+    }
+
+    var name = prefix + __stripExtension(defaultName);
+    if (typeof cue.name === "string" && cue.name.length > 0) name = cue.name;
+
+    planned.push({
+      index: i, name: name, time: time, levelDb: levelDb,
+      inPoint: inPoint, outPoint: outPoint, label: label, source: source
+    });
+  }
+
+  return { prefix: prefix, planned: planned, problems: problems, toImport: toImport };
+}
+
+function __audioProblemMessage(problems, total) {
+  var lines = [];
+  for (var i = 0; i < problems.length; i++) {
+    lines.push("cue " + problems[i].cue + ": " + problems[i].reason);
+  }
+  return (
+    "place_audio_cues placed nothing — " + problems.length + " of " + total + " cues cannot be placed. " +
+    lines.join("; ") + ". Every cue is checked before anything is created, so the comp and project are " +
+    "untouched. Fix these and call again; dryRun:true checks a list without placing it."
+  );
+}
+
+function __audioDryRunReport(comp, plan, total) {
+  var cues = [];
+  for (var i = 0; i < plan.planned.length; i++) {
+    var p = plan.planned[i];
+    var src = { kind: p.source.kind };
+    if (p.source.item) {
+      src.itemId = p.source.item.id;
+      src.name = p.source.item.name;
+    }
+    if (p.source.path) src.path = p.source.path;
+    cues.push({
+      cue: p.index, name: p.name, time: p.time, levelDb: p.levelDb,
+      inPoint: p.inPoint, outPoint: p.outPoint, label: p.label, source: src
+    });
+  }
+  var wouldImport = [];
+  for (var j = 0; j < plan.toImport.length; j++) wouldImport.push(plan.toImport[j].path);
+
+  var out = {
+    dryRun: true,
+    ok: plan.problems.length === 0,
+    compId: comp.id,
+    compName: comp.name,
+    cueCount: total,
+    wouldPlace: cues.length,
+    wouldImport: wouldImport,
+    problems: plan.problems,
+    cues: cues,
+    note: "Nothing was imported, created or changed, and this call is not an undo step."
+  };
+  if (wouldImport.length > 0) {
+    out.unverified =
+      wouldImport.length + " of these files are not in the project yet. They exist on disk, but whether each " +
+      "carries an audio track is only knowable once After Effects has imported it — a real run checks that and " +
+      "refuses the whole call if one does not.";
+  }
+  return out;
+}
+
+/** Undo everything this call made, newest first. Layers before items: an item still in use cannot go. */
+function __rollbackAudioCues(layers, items) {
+  for (var i = layers.length - 1; i >= 0; i--) {
+    try { layers[i].remove(); } catch (e) {}
+  }
+  for (var j = items.length - 1; j >= 0; j--) {
+    try { items[j].remove(); } catch (e2) {}
+  }
+}
+
+/**
+ * `created` is the rollback list, and the layer joins it the instant it exists
+ * rather than once it is fully configured. A cue that dies between add() and
+ * the last setValue is exactly the case rollback is for, and a layer that had
+ * not been registered yet would be the one thing left behind.
+ */
+function __placeAudioCue(comp, p, item, created) {
+  var layer = comp.layers.add(item);
+  created.push(layer);
+  layer.name = p.name;
+  // startTime first: it slides the whole layer and would drag any trim with it.
+  layer.startTime = p.time;
+  var levels = __audioLevelsProperty(layer);
+  if (!levels) {
+    throw new Error(
+      "the layer created for \"" + item.name + "\" has no Audio Levels property, so its level could not be set"
+    );
+  }
+  // AE's Audio Levels is itself in decibels, one entry per channel.
+  levels.setValue([p.levelDb, p.levelDb]);
+  if (p.label !== null) layer.label = p.label;
+  if (p.inPoint !== null) layer.inPoint = p.inPoint;
+  if (p.outPoint !== null) layer.outPoint = p.outPoint;
+  return layer;
+}
+
+OPS.place_audio_cues = noUndoWhen(
+  // dryRun is not an undo step either. A plan that quietly appeared in the
+  // user's undo history would make "this changed nothing" false in the one
+  // place they can see it.
+  function (args) { return !!(args && args.dryRun === true); },
+  function (args) {
+    var comp = getCompById(args.compId);
+    var total = 0;
+    if (args.cues instanceof Array) total = args.cues.length;
+    var plan = __planAudioCues(comp, args);
+
+    if (args.dryRun === true) return __audioDryRunReport(comp, plan, total);
+    if (plan.problems.length > 0) throw new Error(__audioProblemMessage(plan.problems, total));
+
+    var createdLayers = [];
+    var importedItems = [];
+    var importedReport = [];
+    var reusedReport = [];
+    var reusedSeen = {};
+    var placed = [];
+
+    try {
+      // One import per distinct file, before any layer exists, so a bad file
+      // costs nothing but the import itself.
+      var imported = {};
+      for (var i = 0; i < plan.toImport.length; i++) {
+        var spec = plan.toImport[i];
+        var newItem = __importFile(spec.file, spec.path, false);
+        importedItems.push(newItem);
+        var why = __audioItemProblem(newItem);
+        if (why) throw new Error("imported " + spec.path + " and then found that " + why);
+        imported[spec.fsName] = newItem;
+        importedReport.push(__sourceReport(newItem, spec.path));
+      }
+
+      for (var k = 0; k < plan.planned.length; k++) {
+        var p = plan.planned[k];
+        var item = p.source.item;
+        if (!item) item = imported[p.source.fsName];
+        if (p.source.kind !== "import" && !reusedSeen.hasOwnProperty(String(item.id))) {
+          reusedSeen[String(item.id)] = true;
+          reusedReport.push(__sourceReport(item, p.source.path));
+        }
+        var layer;
+        try {
+          layer = __placeAudioCue(comp, p, item, createdLayers);
+        } catch (eCue) {
+          throw new Error("cue " + p.index + " (\"" + p.name + "\" at " + p.time + "s): " + eCue.message);
+        }
+        placed.push({
+          layerId: layer.id,
+          index: layer.index,
+          name: layer.name,
+          time: p.time,
+          levelDb: p.levelDb,
+          itemId: item.id,
+          // Read the trim back: AE clamps an in/out point to what the source
+          // can actually supply, and the caller should see what it got.
+          inPoint: layer.inPoint,
+          outPoint: layer.outPoint,
+          label: layer.label
+        });
+      }
+    } catch (e) {
+      __rollbackAudioCues(createdLayers, importedItems);
+      throw new Error(
+        "place_audio_cues failed on " + ((e && e.message) ? e.message : String(e)) +
+        ". The " + createdLayers.length + " layer(s) and " + importedItems.length +
+        " import(s) it had already made were removed, so the comp and project are as they were."
+      );
+    }
+
+    return {
+      compId: comp.id,
+      placed: placed,
+      count: placed.length,
+      sources: { imported: importedReport, reused: reusedReport },
+      levelUnit: "dB"
+    };
+  }
+);
+
+
 // ===== mogrt.jsx =====
 
 // mogrt.jsx — export a comp as a Motion Graphics template without the three
@@ -1901,6 +3381,19 @@ OPS.create_footage_layer = function (args) {
 //     a project writes Untitled.mogrt over the last one.
 //   * The export invalidates every object reference held across it, including
 //     `app.project`. See the re-fetch below.
+//
+// And one thing suppression costs, which is the whole of issue #71.
+// exportAsMotionGraphicsTemplate reports a boolean and nothing else — AE never
+// says *why* it declined — so once dialogs are suppressed a refusal and a
+// success-that-wrote-nothing look identical from a script. That silence is
+// evidence of nothing in particular, and it must not be read as "a dialog
+// blocked us": under beginSuppressDialogs() a blocking dialog is the one cause
+// ruled out by construction, because suppressing them is exactly what that call
+// did. A comp with an empty Essential Graphics panel is not exportable, and it
+// used to come back blaming a dialog that did not exist and offering a remedy
+// (retry unsuppressed and click it) that led nowhere. So: check every
+// precondition that can be checked *before* the export and name it, and when
+// the export still fails, report the cause as unknown rather than as a dialog.
 
 /** Distinct fonts used by the text layers in a comp, following nested comps. */
 function __collectFonts(comp, depth, seenComps, fonts) {
@@ -1937,6 +3430,106 @@ function __mogrtFileName(name) {
   return String(name) + ".mogrt";
 }
 
+/** Trailing separators off, so two spellings of the same folder compare equal. */
+function __trimTrailingSeparator(p) {
+  var s = String(p);
+  while (s.length > 1) {
+    var last = s.charAt(s.length - 1);
+    if (last !== "/" && last !== "\\") break;
+    s = s.substring(0, s.length - 1);
+  }
+  return s;
+}
+
+function __isBlank(s) {
+  var t = String(s);
+  for (var i = 0; i < t.length; i++) {
+    var ch = t.charAt(i);
+    if (ch !== " " && ch !== "\t" && ch !== "\n" && ch !== "\r") return false;
+  }
+  return true;
+}
+
+/**
+ * How many controllers the comp's Essential Graphics panel holds, or null when
+ * the host will not say.
+ *
+ * null is not zero. A read that throws means this AE cannot be asked, and
+ * refusing an export on the strength of a question that was never answered
+ * would be its own confidently wrong diagnosis. Only an explicit 0 refuses.
+ */
+function __controllerCount(comp) {
+  var n = null;
+  try { n = comp.motionGraphicsTemplateControllerCount; } catch (e) { return null; }
+  if (typeof n !== "number") return null;
+  return n;
+}
+
+/**
+ * Whether After Effects can actually write into the destination folder.
+ *
+ * ExtendScript has no permission API, so the only reliable test is to write.
+ * A folder that exists and refuses writes is another cause the export reports
+ * as nothing at all, and it is worth naming before spending the export rather
+ * than after. The probe is removed on every path; it never outlives the call.
+ */
+function __folderIsWritable(folder) {
+  var probe = new File(__joinPath(folder.fsName, ".ae-mcp-write-probe"));
+  var opened = false;
+  try {
+    opened = probe.open("w");
+    if (opened) probe.write("");
+  } catch (eW) {
+    opened = false;
+  }
+  try { probe.close(); } catch (eC) {}
+  try { if (probe.exists) probe.remove(); } catch (eR) {}
+  return opened === true;
+}
+
+/**
+ * The failure message for an export that wrote nothing.
+ *
+ * Built rather than fixed, because the only honest message names what was
+ * actually established and stops there. `suppressed` is the hinge: with dialogs
+ * suppressed a modal cannot be the cause and must not be mentioned as one
+ * (issue #71); without suppression it is the first thing to look at. Everything
+ * after that is unknown, and says so — AE's own UI is the only place the real
+ * reason exists, which is why the diagnostic step is to run the export by hand.
+ */
+function __exportFailureMessage(info) {
+  var lines = [];
+  lines.push(
+    "After Effects did not write a template. It returned " + String(info.exported) +
+    " and there is no file at " + info.outPath + "."
+  );
+  lines.push(
+    "Ruled out before the export ran: the project is saved (" + info.projectPath + "); the destination " +
+    "folder exists and accepts writes; the template name resolves to that folder; and the comp has " +
+    info.controllerText + "."
+  );
+  if (!info.suppressed) {
+    lines.push(
+      "Dialogs were NOT suppressed for this call, so a modal dialog waiting in After Effects is the " +
+      "likeliest cause — switch to After Effects and look for one. Retry with the default " +
+      "suppressDialogs:true once it is cleared."
+    );
+  } else {
+    lines.push(
+      "Dialogs were suppressed, so a modal dialog cannot be what stopped this — do not go looking for " +
+      "one to click. After Effects reported no reason at all, and there is no reason for a script to " +
+      "read, so the cause is unknown."
+    );
+    lines.push(
+      "To find out what After Effects would have said, ask the user to export the same comp by hand: " +
+      "Window > Essential Graphics, select the comp, then Export Motion Graphics Template. After " +
+      "Effects shows its own error there. Running this tool again with suppressDialogs:false shows the " +
+      "same dialog, but it will freeze this connection until someone clicks it."
+    );
+  }
+  return lines.join(" ");
+}
+
 OPS.export_mogrt = noUndo(function (args) {
   var comp = getCompById(args.compId);
 
@@ -1952,6 +3545,29 @@ OPS.export_mogrt = noUndo(function (args) {
     );
   }
 
+  // Every precondition that can be established from a script runs here, before
+  // the project is touched at all: the template is not renamed, the project is
+  // not saved and no export is attempted until they all pass. A refusal below
+  // therefore costs the user nothing and names its own remedy — which is the
+  // whole point, since a failure *after* the export names nothing.
+
+  // The Essential Graphics panel has to have something in it. AE will not build
+  // a template with no controllers, and under suppression it declines without a
+  // word — which is what made this look like a dialog (issue #71). An explicit
+  // 0 is the whole diagnosis; a count the host refuses to give is not.
+  var preControllerCount = __controllerCount(comp);
+  if (preControllerCount === 0) {
+    throw new Error(
+      "This comp has 0 Essential Graphics controllers, and After Effects cannot export a template " +
+      "from a comp with an empty Essential Graphics panel. It refuses without writing a file and " +
+      "without reporting anything a script can read, so nothing was exported and nothing in the " +
+      "project was changed. To fix it, put at least one property into the panel: in After Effects " +
+      "open Window > Essential Graphics, pick this comp in the panel's dropdown, then drag a layer " +
+      "property into it — a text layer's Source Text, a colour, a slider, a position. Then call " +
+      "export_mogrt again."
+    );
+  }
+
   var templateName = (typeof args.name === "string" && args.name.length > 0) ? args.name : null;
   var previousTemplateName = null;
   try { previousTemplateName = comp.motionGraphicsTemplateName; } catch (e) {}
@@ -1959,7 +3575,16 @@ OPS.export_mogrt = noUndo(function (args) {
     // AE's own default is "Untitled" for a template built by script, which
     // silently collides with every other comp in the project. The comp name is
     // what the user would have typed. A name they *did* type is left alone.
-    templateName = (!previousTemplateName || previousTemplateName === "Untitled") ? comp.name : previousTemplateName;
+    if (!previousTemplateName || previousTemplateName === "Untitled") {
+      templateName = comp.name;
+    } else {
+      templateName = previousTemplateName;
+    }
+  }
+  if (__isBlank(templateName)) {
+    throw new Error(
+      "The template name is empty, and it becomes the .mogrt filename. Pass a `name`."
+    );
   }
 
   var destDir = (typeof args.destDir === "string" && args.destDir.length > 0)
@@ -1974,6 +3599,22 @@ OPS.export_mogrt = noUndo(function (args) {
 
   var outPath = __joinPath(folder.fsName, __mogrtFileName(templateName));
   var outFile = new File(outPath);
+
+  // The name becomes a filename, so a separator in it sends the write somewhere
+  // else — or nowhere, silently. Measured rather than pattern-matched: ask the
+  // File where it actually landed and compare. That works the same on both
+  // platforms, which a list of illegal characters would not.
+  var resolvedParent = null;
+  try { resolvedParent = outFile.parent.fsName; } catch (eP) {}
+  if (resolvedParent !== null &&
+      __trimTrailingSeparator(resolvedParent) !== __trimTrailingSeparator(folder.fsName)) {
+    throw new Error(
+      "The template name \"" + templateName + "\" is used as the .mogrt filename, and it resolves to " +
+      outPath + ", which is not inside " + folder.fsName + ". Pass a `name` with no slashes in it, and " +
+      "a `destDir` if you want it written somewhere else."
+    );
+  }
+
   var existed = outFile.exists;
   if (existed && args.overwrite !== true) {
     throw new Error(
@@ -1982,6 +3623,17 @@ OPS.export_mogrt = noUndo(function (args) {
     );
   }
 
+  // Last of the checkable preconditions, and the last thing that costs nothing
+  // to get wrong. A folder that will not accept a file is one more cause the
+  // export reports as silence.
+  if (!__folderIsWritable(folder)) {
+    throw new Error(
+      "After Effects cannot write into " + folder.fsName + " — a test file could not be created there. " +
+      "Nothing was exported. Pass a `destDir` the user can write to, or ask them to fix the folder's " +
+      "permissions."
+    );
+  }
+
   var fonts = [];
   try { __collectFonts(comp, 0, [], fonts); } catch (eF) {}
 
@@ -1995,6 +3647,7 @@ OPS.export_mogrt = noUndo(function (args) {
   // Everything the result needs, read *before* the export. See below.
   var compId = comp.id;
   var compName = comp.name;
+  var projectPath = app.project.file.fsName;
 
   var suppress = args.suppressDialogs !== false;
   var suppressed = false;
@@ -2023,10 +3676,21 @@ OPS.export_mogrt = noUndo(function (args) {
   // codebase refuses to pass on.
   var written = new File(outPath);
   if (!written.exists) {
-    throw new Error(
-      "After Effects reported " + String(exported) + " for the export but no file appeared at " + outPath +
-      ". If suppressDialogs was false, a modal dialog in After Effects may have cancelled it."
-    );
+    var controllerText;
+    if (preControllerCount === null) {
+      controllerText = "controllers this version of After Effects would not count";
+    } else if (preControllerCount === 1) {
+      controllerText = "1 Essential Graphics controller";
+    } else {
+      controllerText = String(preControllerCount) + " Essential Graphics controllers";
+    }
+    throw new Error(__exportFailureMessage({
+      exported: exported,
+      outPath: outPath,
+      projectPath: projectPath,
+      suppressed: suppress,
+      controllerText: controllerText
+    }));
   }
   var bytes = written.length;
   if (!(bytes > 0)) throw new Error("The exported template at " + outPath + " is empty (0 bytes).");
@@ -2042,7 +3706,9 @@ OPS.export_mogrt = noUndo(function (args) {
     createdDir: createdDir,
     projectSaved: app.project.file.fsName,
     dialogsSuppressed: suppress,
-    controllerCount: comp.motionGraphicsTemplateControllerCount,
+    // Re-read rather than echoed: the export is the only thing that can change
+    // it, and a host that will not answer says null instead of a made-up 0.
+    controllerCount: __controllerCount(comp),
     fonts: fonts
   };
   if (!suppress) {
@@ -2196,32 +3862,66 @@ OPS.set_house_style = noUndo(function (args) {
 
 // batch.jsx — execute many ops in one ExtendScript pass.
 // For huge batches, registers a job and processes in chunks via _continue_job.
+//
+// UNDO GROUPING, which is the whole design constraint here (issue #69):
+// After Effects **discards** an undo group opened in one `evalScript` call and
+// closed in another. Measured, not inferred — a 600-op batch that opened its
+// group in `run_batch` and closed it from a later `_continue_job` produced ~600
+// undo steps, and AE's Edit menu read `Undo New Solid` rather than the group's
+// name. So a group only survives if it opens and closes inside one call, and
+// that gives the two paths below genuinely different answers:
+//
+//   inline (<= 500 ops, or any size with singleUndo) — the whole batch runs in
+//     one call, so one group round it is real. One undo step.
+//   chunked (> 500 ops) — the batch spans N calls, so the most AE will keep is
+//     one group per chunk. N undo steps, counted and reported, never claimed
+//     to be one.
+
+// The inline cutoff. Inline stays sub-second for typical create/keyframe ops up
+// to a few hundred; the async-job overhead (jobId envelope, polling, progress
+// notifications) is only worth it for genuinely long jobs.
+var __BATCH_INLINE_MAX = 500;
+// Chunk size for the async path. The panel reads this back off the envelope
+// rather than holding its own copy, so the two cannot drift.
+var __BATCH_CHUNK = 25;
+// The ceiling on singleUndo. Past this, one blocking ExtendScript call freezes
+// After Effects for long enough that the user will think it has hung, with no
+// progress events to say otherwise — so it is refused rather than attempted.
+var __BATCH_SINGLE_UNDO_MAX = 2000;
 
 OPS.run_batch = function (args) {
   var ops = args.ops || [];
   var transactional = args.transactional !== false;
   var name = args.undoGroupName || "AE MCP Batch";
-  // Short batches: run inline synchronously. Inline stays sub-second for
-  // typical create/keyframe ops up to a few hundred; the async-job overhead
-  // (jobId envelope, polling, progress notifications) is only worth it for
-  // genuinely long jobs.
-  if (ops.length <= 500) {
-    var results = []; var errors = [];
-    for (var i = 0; i < ops.length; i++) {
-      var step = ops[i];
-      try {
-        var handler = OPS[step.op];
-        if (!handler) throw new Error("Unknown op: " + step.op);
-        results.push(handler(step.args || {}));
-      } catch (e) {
-        errors.push({ index: i, op: step.op, error: e.message });
-        if (transactional) throw new Error("Batch failed at op[" + i + "] " + step.op + ": " + e.message);
-      }
-    }
-    return { results: results, errors: errors, total: ops.length };
+  var singleUndo = args.singleUndo === true;
+
+  // Refused before anything else happens, including the diff fingerprint: a
+  // call that is not going to run should cost nothing.
+  if (singleUndo && ops.length > __BATCH_SINGLE_UNDO_MAX) {
+    throw new Error(
+      "singleUndo refuses " + ops.length + " ops (the limit is " + __BATCH_SINGLE_UNDO_MAX + "). " +
+      "One undo step means the whole batch runs inside a single ExtendScript call, which " +
+      "freezes After Effects' interface for the whole of it and reports no progress; at this " +
+      "size the user would reasonably think it had hung. Either split the work into batches of " +
+      __BATCH_SINGLE_UNDO_MAX + " or fewer, or drop singleUndo and accept one undo step per " +
+      "chunk of " + __BATCH_CHUNK + " (the result says exactly how many)."
+    );
+  }
+
+  // diff:true fingerprints the comps this batch names, before and after, inside
+  // this one call — see snapshot.jsx. Null unless asked for.
+  var diffState = __diffStart(args, ops);
+
+  if (ops.length <= __BATCH_INLINE_MAX || singleUndo) {
+    return __batchInline(ops, transactional, name, diffState);
   }
+
   // Long batches: register job, return jobId; panel polls _continue_job.
+  // No undo group is opened here on purpose. One opened now would be closed
+  // from a different call and AE would throw it away, which is exactly how this
+  // op spent three releases reporting one undo step and delivering hundreds.
   var jobId = __newJobId();
+  var estimate = Math.ceil(ops.length / __BATCH_CHUNK);
   JOBS[jobId] = {
     cursor: 0,
     total: ops.length,
@@ -2231,48 +3931,212 @@ OPS.run_batch = function (args) {
     cancelled: false,
     transactional: transactional,
     name: name,
+    chunkSize: __BATCH_CHUNK,
+    // Counted as groups are actually opened, never predicted. See __UNDO_GROUPS.
+    undoSteps: 0,
+    // Carried across the chunked continuations: the before-fingerprint has to
+    // outlive the call that took it, or a long batch could never be diffed.
+    diffState: diffState,
+  };
+  return {
+    jobId: jobId,
+    async: true,
+    total: ops.length,
+    chunkSize: __BATCH_CHUNK,
+    // Labelled an estimate because it is one: a transactional failure ends the
+    // batch early, and the exact count comes back with the final result.
+    undoStepsEstimate: estimate,
+    undoGroupName: name,
+    note: "This batch runs in " + estimate + " chunks of " + __BATCH_CHUNK + " and will land as " +
+      "about " + estimate + " undo steps, NOT one — After Effects discards an undo group that " +
+      "spans two script calls, so a chunked batch can only group per chunk. The final result " +
+      "reports the exact number. If the user needs a single Cmd-Z, re-send with singleUndo:true " +
+      "(up to " + __BATCH_SINGLE_UNDO_MAX + " ops), which runs the whole batch in one blocking " +
+      "call with no progress events.",
   };
-  // Wrap async run already inside an undoGroup chain. We open it now, the
-  // continuations stay inside it until finalization.
-  app.beginUndoGroup(name);
-  JOBS[jobId].undoOpen = true;
-  return { jobId: jobId, async: true, total: ops.length };
 };
-// run_batch is allowed to manage its own undo (we open/close it manually for long jobs).
+// run_batch is allowed to manage its own undo: the inline path opens exactly one
+// group of its own, and the chunked path opens one per continuation.
 OPS.run_batch.__meta = { noUndo: true };
 
+// The inline path: every op inside one undo group inside one evalScript, which
+// is the only shape After Effects keeps.
+//
+// withUndo() rather than a bare beginUndoGroup/endUndoGroup pair, for two
+// reasons: its `finally` closes the group when a transactional op throws, and it
+// is the only thing that keeps __UNDO_OPEN honest, so a batched op that calls
+// withoutUndoGroup() still works instead of silently doing nothing.
+function __batchInline(ops, transactional, name, diffState) {
+  var results = [];
+  var errors = [];
+  var before = __undoGroupsOpened();
+  // A run_batch listed as an op inside another run_batch would otherwise open a
+  // second group inside the first, and AE's groups do not nest: the inner
+  // endUndoGroup closes the outer one and the rest of the outer batch writes
+  // ungrouped. Run inside the group that is already open instead, and say so —
+  // an inner batch reporting "one undo step" of its own would be a second lie
+  // in the same shape as the one this fixes.
+  var nested = __UNDO_OPEN;
+  // An empty batch opens nothing. AE records no undo step for a group that
+  // changed nothing, so opening one would make `undoSteps: 1` an over-report on
+  // the one call where the truth is unambiguous.
+  var empty = ops.length === 0;
+  var run = function () {
+    for (var i = 0; i < ops.length; i++) {
+      var step = ops[i];
+      try {
+        var handler = OPS[step.op];
+        if (!handler) throw new Error("Unknown op: " + step.op);
+        results.push(handler(step.args || {}));
+      } catch (e) {
+        errors.push({ index: i, op: step.op, error: e.message });
+        if (transactional) {
+          // Nothing rolls back, so the half-applied state is what the caller
+          // has to reason about. The diff says where it stopped.
+          var failure = new Error("Batch failed at op[" + i + "] " + step.op + ": " + e.message);
+          __diffAnnotateError(failure, diffState);
+          throw failure;
+        }
+      }
+    }
+  };
+  try {
+    if (nested || empty) run();
+    else withUndo(name, run);
+  } catch (e) {
+    // The group is already closed by withUndo's finally. Say what it cost, so a
+    // failed batch is as clear about its undo history as a successful one.
+    try {
+      e.message = String(e.message) + " || " +
+        __batchUndoNote(__undoGroupsOpened() - before, name, nested, false);
+    } catch (e2) {}
+    throw e;
+  }
+  var out = {
+    results: results,
+    errors: errors,
+    total: ops.length,
+    undoSteps: __undoGroupsOpened() - before,
+    undoGroupName: name,
+  };
+  if (nested) out.nested = true;
+  out.note = __batchUndoNote(out.undoSteps, name, nested, false);
+  if (diffState) out.diff = __diffFinish(diffState);
+  return out;
+}
+
+// The one sentence every batch result carries about its own undo history.
+// Written for an agent that is about to tell a person how to undo the work.
+// `steps` is always the measured count, so this describes what happened rather
+// than what the path intended.
+function __batchUndoNote(steps, name, nested, chunked) {
+  if (nested) {
+    return "This batch ran inside an undo group that was already open (a run_batch nested in " +
+      "another one), so it adds no undo step of its own — its work is part of the outer step.";
+  }
+  if (steps <= 0) {
+    return "This batch opened no undo group, so it added no undo steps.";
+  }
+  if (steps === 1) {
+    // A chunked batch reaches one step only by stopping after its first chunk —
+    // cancelled, or failed in it — and that group is named "(1)", not the bare
+    // name. Quoting the wrong one would send the user looking for a menu entry
+    // that is not there.
+    return 'This batch is one undo step ("' + name + (chunked ? " (1)" : "") +
+      '"): a single Cmd-Z (Ctrl-Z on Windows) undoes all of it.';
+  }
+  if (chunked) {
+    return "This batch landed as " + steps + " undo steps, NOT one — named \"" + name + " (1)\" " +
+      'through "' + name + " (" + steps + ')". After Effects discards an undo group that spans ' +
+      "two script calls, so a chunked batch can only group per chunk. Undoing all of it takes up " +
+      "to " + steps + " presses of Cmd-Z (Ctrl-Z on Windows) — tell the user that number rather " +
+      "than saying one. (A chunk whose ops changed nothing records no step, so that is the " +
+      "ceiling.) singleUndo:true buys a single step back, at the cost of freezing AE's interface " +
+      "for the whole batch and emitting no progress.";
+  }
+  return "This batch landed as " + steps + " undo steps rather than one: an op inside it closed " +
+    "the batch's undo group and opened a new one (withoutUndoGroup — After Effects refuses " +
+    "copyToComp on a parented or expression-linked layer while a group is open). Undoing all of " +
+    "it takes up to " + steps + " presses of Cmd-Z (Ctrl-Z on Windows).";
+}
+
 // Continuation step. Returns one chunk's worth of progress.
+//
+// Cancellation, which used to need bookkeeping across calls and no longer does:
+// _cancel_job is its own evalScript and the panel serializes those, so a cancel
+// can only ever be observed *between* chunks. A chunk's group opens and closes
+// inside this one call, so there is never an open group for a cancel — or a
+// throw, or a dropped WebSocket — to leave behind. That is what the old
+// `j.undoOpen` flag was for, and it was tracking a group AE had already dropped.
 OPS._continue_job = noUndo(function (args) {
   var jobId = args.jobId;
   var j = JOBS[jobId];
   if (!j) throw new Error("No job: " + jobId);
   if (j.cancelled) {
-    if (j.undoOpen) { app.endUndoGroup(); j.undoOpen = false; }
-    return { done: true, cancelled: true, jobId: jobId, results: j.results, errors: j.errors };
+    var stopped = {
+      done: true, cancelled: true, jobId: jobId,
+      results: j.results, errors: j.errors,
+      undoSteps: j.undoSteps, undoGroupName: j.name,
+      note: __batchUndoNote(j.undoSteps, j.name, false, true),
+    };
+    if (j.diffState) stopped.diff = __diffFinish(j.diffState);
+    return stopped;
   }
-  var chunkSize = args.chunkSize || 25;
+  var chunkSize = args.chunkSize || j.chunkSize || __BATCH_CHUNK;
   var endAt = Math.min(j.cursor + chunkSize, j.total);
-  for (; j.cursor < endAt; j.cursor++) {
-    var step = j.ops[j.cursor];
-    try {
-      var handler = OPS[step.op];
-      if (!handler) throw new Error("Unknown op: " + step.op);
-      j.results.push(handler(step.args || {}));
-    } catch (e) {
-      j.errors.push({ index: j.cursor, op: step.op, error: e.message });
-      if (j.transactional) {
-        if (j.undoOpen) { app.endUndoGroup(); j.undoOpen = false; }
-        // Attempt rollback via undo
-        try { app.executeCommand(app.findMenuCommandId("Undo")); } catch (e2) {}
-        return { done: true, failed: true, jobId: jobId, error: e.message, atIndex: j.cursor, results: j.results, errors: j.errors };
+  var before = __undoGroupsOpened();
+  var failure = null;
+  // One group per chunk, opened and closed inside this call. The chunk number
+  // is in the name so the Edit menu says which part of the batch a step is.
+  withUndo(j.name + " (" + (j.undoSteps + 1) + ")", function () {
+    for (; j.cursor < endAt; j.cursor++) {
+      var step = j.ops[j.cursor];
+      try {
+        var handler = OPS[step.op];
+        if (!handler) throw new Error("Unknown op: " + step.op);
+        j.results.push(handler(step.args || {}));
+      } catch (e) {
+        j.errors.push({ index: j.cursor, op: step.op, error: e.message });
+        if (j.transactional) {
+          failure = { error: e.message, atIndex: j.cursor };
+          return;
+        }
       }
     }
+  });
+  j.undoSteps += __undoGroupsOpened() - before;
+
+  if (failure) {
+    // No rollback is attempted. The old code fired one `Undo` menu command
+    // here, which undoes at most the last step even when it works at all —
+    // menu commands depend on host focus and the active selection, neither of
+    // which this bridge has. Reporting a rollback that did not happen is the
+    // same class of lie as swallowing an error, so it says plainly what is on
+    // disk and how many steps it took.
+    var failed = {
+      done: true, failed: true, jobId: jobId,
+      error: failure.error, atIndex: failure.atIndex,
+      results: j.results, errors: j.errors,
+      rolledBack: false,
+      undoSteps: j.undoSteps, undoGroupName: j.name,
+      note: __batchUndoNote(j.undoSteps, j.name, false, true) +
+        " Nothing was rolled back: the ops before op[" + failure.atIndex + "] are applied and " +
+        "stay applied. Read the state back rather than re-running the batch.",
+    };
+    if (j.diffState) failed.diff = __diffFinish(j.diffState);
+    return failed;
   }
   if (j.cursor >= j.total) {
-    if (j.undoOpen) { app.endUndoGroup(); j.undoOpen = false; }
-    return { done: true, jobId: jobId, results: j.results, errors: j.errors, total: j.total };
+    var done = {
+      done: true, jobId: jobId,
+      results: j.results, errors: j.errors, total: j.total,
+      undoSteps: j.undoSteps, undoGroupName: j.name,
+      note: __batchUndoNote(j.undoSteps, j.name, false, true),
+    };
+    if (j.diffState) done.diff = __diffFinish(j.diffState);
+    return done;
   }
-  return { done: false, jobId: jobId, progress: j.cursor, total: j.total };
+  return { done: false, jobId: jobId, progress: j.cursor, total: j.total, undoSteps: j.undoSteps };
 });
 
 OPS._cancel_job = noUndo(function (args) {
@@ -2285,7 +4149,10 @@ OPS._cancel_job = noUndo(function (args) {
 OPS._get_job = noUndo(function (args) {
   var j = JOBS[args.jobId];
   if (!j) return null;
-  return { cursor: j.cursor, total: j.total, cancelled: j.cancelled, errorCount: j.errors.length };
+  return {
+    cursor: j.cursor, total: j.total, cancelled: j.cancelled,
+    errorCount: j.errors.length, undoSteps: j.undoSteps,
+  };
 });
 
 
@@ -2464,14 +4331,97 @@ function __serializeText(layer) {
   } catch (e) { return null; }
 }
 
-function __serializeShapeContents(group, depth) {
+// ---------- shape contents ----------
+//
+// Two of the groups hanging off every vector group are fixed-shape and almost
+// never the reason anyone reads a shape layer.
+//
+// Material Options is the 48-property 3D extrusion model. It means something
+// only for an extruded shape under the Cinema 4D renderer, and on the 2D shape
+// layers that are nearly all of them it is inert — while being most of the
+// weight of a shape read: one 68x68 circle in one group came back as 13KB of
+// shape JSON, 10KB of it material properties (issue #42). Skipped unless
+// `shapeMaterials` asks for it, and the skip is counted and explained in the
+// response rather than being silent.
+var __SHAPE_MATERIALS = "ADBE Vector Materials Group";
+var __SHAPE_TRANSFORM = "ADBE Vector Transform Group";
+
+// A group Transform still at its creation values says nothing that
+// `atDefaults: true` does not. Tested by value rather than through
+// PropertyBase.isModified: the values are the contract, they can be asserted
+// with no AE to run in, and a property this table does not know about — a
+// future AE adding one — has to fail the test rather than be folded away
+// unread.
+var __VECTOR_TRANSFORM_DEFAULTS = [
+  ["ADBE Vector Anchor", [0, 0]],
+  ["ADBE Vector Position", [0, 0]],
+  ["ADBE Vector Scale", [100, 100]],
+  ["ADBE Vector Skew", 0],
+  ["ADBE Vector Skew Axis", 0],
+  ["ADBE Vector Rotation", 0],
+  ["ADBE Vector Group Opacity", 100]
+];
+
+function __isPropertyGroup(p) {
+  return p.propertyType === PropertyType.NAMED_GROUP || p.propertyType === PropertyType.INDEXED_GROUP;
+}
+
+function __vectorTransformDefault(matchName) {
+  for (var i = 0; i < __VECTOR_TRANSFORM_DEFAULTS.length; i++) {
+    if (__VECTOR_TRANSFORM_DEFAULTS[i][0] === matchName) return __VECTOR_TRANSFORM_DEFAULTS[i][1];
+  }
+  return null;
+}
+
+function __sameVectorValue(a, b) {
+  if (b instanceof Array) {
+    if (!(a instanceof Array) || a.length !== b.length) return false;
+    for (var i = 0; i < a.length; i++) { if (a[i] !== b[i]) return false; }
+    return true;
+  }
+  return a === b;
+}
+
+function __isIdentityVectorTransform(tg) {
+  if (!tg || !tg.numProperties) return false;
+  for (var i = 1; i <= tg.numProperties; i++) {
+    var p = tg.property(i);
+    // Animated or expression-driven is never "at defaults", whatever it reads
+    // at this instant.
+    if (p.numKeys > 0) return false;
+    try { if (p.canSetExpression && p.expression) return false; } catch (e) {}
+    var def = __vectorTransformDefault(p.matchName);
+    if (def === null) return false;
+    var v;
+    try { v = p.value; } catch (e2) { return false; }
+    if (!__sameVectorValue(v, def)) return false;
+  }
+  return true;
+}
+
+// Carries the caller's choices down the walk and collects what was left out, so
+// the omissions can be named once at the top of the section instead of being
+// repeated on every group.
+function __shapeOpts(args) {
+  return {
+    materials: !!(args && args.shapeMaterials),
+    compact: !!(args && args.shapeDetail === "compact"),
+    materialsOmitted: 0
+  };
+}
+
+function __serializeShapeContents(group, depth, opts) {
   if (!group || !group.numProperties) return [];
   var out = [];
   for (var i = 1; i <= group.numProperties; i++) {
     var p = group.property(i);
+    if (p.matchName === __SHAPE_MATERIALS && !opts.materials) { opts.materialsOmitted += 1; continue; }
+    // `index` stays the real one whatever was skipped, so a path built from
+    // this response still addresses the node it names.
     var entry = { name: p.name, matchName: p.matchName, index: i };
-    if (p.propertyType === PropertyType.NAMED_GROUP || p.propertyType === PropertyType.INDEXED_GROUP) {
-      if (depth > 0) entry.children = __serializeShapeContents(p, depth - 1);
+    if (__isPropertyGroup(p)) {
+      if (p.matchName === __SHAPE_TRANSFORM && __isIdentityVectorTransform(p)) entry.atDefaults = true;
+      else if (depth > 0) entry.children = __serializeShapeContents(p, depth - 1, opts);
       // Say where the walk stopped. A group that simply has no `children` key
       // reads as empty, which for a deep shape tree is a lie.
       else if (p.numProperties > 0) entry.childrenOmitted = p.numProperties;
@@ -2483,6 +4433,120 @@ function __serializeShapeContents(group, depth) {
   return out;
 }
 
+// ---------- compact shape serialization ----------
+//
+// One line per group, with that group's own leaf properties folded onto it.
+// The full form spends four JSON lines on every property it reports; the same
+// lamp layer is around 450 characters here against 2,800 full (and 13,000
+// before the material groups came out). It is a reading format, not a lesser
+// one: the write tools address nodes by name, and every name is still on the
+// line. `shapeDetail` stays "full" by default all the same — a caller that
+// never heard of it has to keep getting exactly what it always got.
+
+function __compactNumber(n) {
+  if (typeof n !== "number") return String(n);
+  if (isNaN(n) || !isFinite(n)) return String(n);
+  // Four decimals round-trips an 8-bit colour channel and keeps float noise
+  // (0.6627450980392157 for one byte) out of a format whose point is brevity.
+  return String(Math.round(n * 10000) / 10000);
+}
+
+function __compactLeafValue(p) {
+  var v;
+  try { v = p.value; } catch (e) { return "?"; }
+  // A path's value is a Shape object, which is a wall of vertex arrays in full
+  // and unreadable in one line. Its size and closedness are what you check.
+  try {
+    if (v && v.vertices && v.vertices.length !== undefined) {
+      return "path(" + v.vertices.length + (v.closed ? " verts, closed)" : " verts, open)");
+    }
+  } catch (e2) {}
+  if (v instanceof Array) {
+    var parts = [];
+    for (var i = 0; i < v.length; i++) parts.push(__compactNumber(v[i]));
+    return "[" + parts.join(",") + "]";
+  }
+  if (typeof v === "number") return __compactNumber(v);
+  return String(v);
+}
+
+function __compactLeaves(g) {
+  var parts = [];
+  for (var i = 1; i <= g.numProperties; i++) {
+    var p = g.property(i);
+    if (__isPropertyGroup(p)) continue;
+    var s = p.name + "=" + __compactLeafValue(p);
+    if (p.numKeys > 0) s += " [" + p.numKeys + " keys]";
+    try { if (p.canSetExpression && p.expression) s += " [expr]"; } catch (e) {}
+    parts.push(s);
+  }
+  return parts.join("  ");
+}
+
+// Only the "ADBE " prefix comes off: "ADBE Vector Group" and "ADBE Vectors
+// Group" are different nodes, so anything cleverer would collide.
+function __compactKind(matchName) {
+  return (matchName.substring(0, 5) === "ADBE ") ? matchName.substring(5) : matchName;
+}
+
+function __hasGroupChild(g) {
+  for (var i = 1; i <= g.numProperties; i++) { if (__isPropertyGroup(g.property(i))) return true; }
+  return false;
+}
+
+function __compactShapeContents(group, depth, indent, lines, opts) {
+  if (!group || !group.numProperties) return lines;
+  // Leaves sitting directly on the group being walked have no line of their
+  // own to fold onto; at the root, give them one.
+  if (indent === "") {
+    var rootLeaves = __compactLeaves(group);
+    if (rootLeaves) lines.push(rootLeaves);
+  }
+  for (var i = 1; i <= group.numProperties; i++) {
+    var p = group.property(i);
+    if (!__isPropertyGroup(p)) continue;
+    if (p.matchName === __SHAPE_MATERIALS && !opts.materials) { opts.materialsOmitted += 1; continue; }
+    var line = indent + p.name + "  " + __compactKind(p.matchName);
+    if (p.matchName === __SHAPE_TRANSFORM && __isIdentityVectorTransform(p)) {
+      lines.push(line + "  (at defaults)");
+      continue;
+    }
+    var leaves = __compactLeaves(p);
+    lines.push(leaves ? line + "  " + leaves : line);
+    if (depth > 0) __compactShapeContents(p, depth - 1, indent + "  ", lines, opts);
+    // The leaves are already on the line above, so only unwalked sub-groups
+    // are missing — and saying so is the same rule as `childrenOmitted`.
+    else if (__hasGroupChild(p)) lines.push(indent + "  (sub-groups not walked — raise shapeDepth)");
+  }
+  return lines;
+}
+
+// The whole `shape` section, with its own omissions named on it.
+function __serializeShape(layer, depth, args) {
+  var opts = __shapeOpts(args);
+  var shape = { depth: depth };
+  try {
+    var contents = layer.property("Contents");
+    if (opts.compact) {
+      shape.detail = "compact";
+      shape.contents = __compactShapeContents(contents, depth, "", [], opts);
+    } else {
+      shape.contents = __serializeShapeContents(contents, depth, opts);
+    }
+  } catch (e) {
+    // An unreadable Contents used to leave the section off entirely, which
+    // reads as "this shape layer has no shapes".
+    shape.error = (e && e.message) ? String(e.message) : String(e);
+  }
+  if (opts.materialsOmitted > 0) {
+    shape.materialsOmitted = opts.materialsOmitted;
+    shape.materialsNote = "Material Options omitted on " + opts.materialsOmitted + " shape group" +
+      (opts.materialsOmitted === 1 ? "" : "s") + " — 48 3D-extrusion properties each, meaningful only for an " +
+      "extruded shape under the Cinema 4D renderer. Pass shapeMaterials:true to read them.";
+  }
+  return shape;
+}
+
 OPS.get_layer_full = noUndo(function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
@@ -2526,8 +4590,7 @@ OPS.get_layer_full = noUndo(function (args) {
   if (l instanceof TextLayer && __wantsSection(want, "text")) out.text = __serializeText(l);
   if (l instanceof ShapeLayer && __wantsSection(want, "shape")) {
     var depth = (args && args.shapeDepth !== undefined && args.shapeDepth !== null) ? args.shapeDepth : 4;
-    try { out.shape = { depth: depth, contents: __serializeShapeContents(l.property("Contents"), depth) }; }
-    catch (e) {}
+    out.shape = __serializeShape(l, depth, args);
   }
   if (__wantsSection(want, "source")) {
     if (l.source && l.source instanceof CompItem) {
@@ -2628,6 +4691,115 @@ OPS.find_layers = noUndo(function (args) {
 });
 
 
+// ===== helpers.jsx =====
+
+// helpers.jsx — the scope a run_jsx script runs in.
+//
+// Everything in this file is a global function, which is what makes it visible
+// to `eval`d script bodies and to anything loaded through run_jsx's
+// `libraries`. It exists because the run_jsx description promised "helpers in
+// scope" and never said which, so every session re-derived the same four or
+// five functions — find-a-layer-by-id, ease-with-the-right-array-size, a shape
+// builder that zeros the position (issue #53). Each of these was written from
+// scratch in the transcript, at token cost, with a fresh chance of getting the
+// AE quirk wrong.
+//
+// The rule for adding one: it has to be something an agent would otherwise
+// write badly, not merely something it would write often. All four below wrap
+// a documented AE trap.
+//
+// These are listed by signature in the run_jsx tool description. If you change
+// one, change that too — it is the only place a caller ever sees them.
+
+// getCompById by a shorter name, because that is the name agents guess.
+function compById(id) {
+  return getCompById(id);
+}
+
+// getLayerById, but the comp may be given as an id. An agent holding
+// (compId, layerId) — the pair every tool returns — can use it directly.
+function layerById(comp, layerId) {
+  var c = comp;
+  if (typeof c === "number") c = getCompById(c);
+  return getLayerById(c, layerId);
+}
+
+// {influence, speed}, or a bare number read as influence. AE's own default
+// ease is 33% influence at zero speed, so that is what an omitted field gets.
+function __hEaseSpec(spec) {
+  if (spec === null || spec === undefined) return { influence: 33, speed: 0 };
+  if (typeof spec === "number") return { influence: spec, speed: 0 };
+  var inf = 33;
+  var spd = 0;
+  if (typeof spec.influence === "number") inf = spec.influence;
+  if (typeof spec.speed === "number") spd = spec.speed;
+  return { influence: inf, speed: spd };
+}
+
+// ease(prop, keyIndex, easeIn, easeOut) — sizes its own ease array.
+//
+// setTemporalEaseAtKey wants one KeyframeEase per dimension and the count is
+// NOT derivable from the value: a spatial property takes exactly one whatever
+// its dimension (the ease runs along the motion path), a 2D layer's Scale takes
+// three, a shape's Ellipse Size takes two, Opacity and sliders take one. The
+// wrong count throws "parameter 2" and says nothing else (issue #50).
+//
+// The sizing lives in `__applyTemporalEase` in keyframes.jsx, which is what
+// `set_temporal_ease` and `add_keyframe` use. This helper is the same function
+// with a friendlier signature — deliberately not a second implementation, so a
+// script written through run_jsx and the same work done through the tools can
+// never disagree about what a property wanted.
+//
+// easeOut omitted means the same ease on both sides. Returns the number of
+// entries that worked, so a caller can see what the property actually wanted.
+function ease(prop, keyIndex, easeIn, easeOut) {
+  var inSpec = __hEaseSpec(easeIn);
+  var outSpec = __hEaseSpec(easeOut === undefined ? easeIn : easeOut);
+  return __applyTemporalEase(prop, keyIndex, inSpec, outSpec);
+}
+
+// addKeys(prop, [[time, value], ...]) — or [{time, value}, ...].
+// Returns the key index of each, in the order given, so the next call can ease
+// them without searching for them again.
+function addKeys(prop, pairs) {
+  if (!pairs || !pairs.length) return [];
+  var out = [];
+  for (var i = 0; i < pairs.length; i++) {
+    var p = pairs[i];
+    var t;
+    var v;
+    if (p instanceof Array) {
+      t = p[0];
+      v = p[1];
+    } else {
+      t = p.time;
+      v = p.value;
+    }
+    prop.setValueAtTime(t, v);
+    out.push(prop.nearestKeyIndex(t));
+  }
+  return out;
+}
+
+// shape(comp, {name, position}) — a shape layer that lands at [0,0].
+//
+// AE spawns a scripted shape layer at the comp centre with its anchor at
+// (0,0), so paths authored in comp pixels come out offset by half a frame —
+// easy to miss on a downsampled screenshot (issue #51). Position [0,0] makes
+// the layer's coordinate space the comp's, which is what path vertices assume.
+function shape(comp, opts) {
+  var c = comp;
+  if (typeof c === "number") c = getCompById(c);
+  var o = opts || {};
+  var l = c.layers.addShape();
+  if (o.name) l.name = o.name;
+  var pos = o.position ? o.position : [0, 0];
+  var value = (pos.length === 3) ? pos : [pos[0], pos[1]];
+  l.property("Transform").property("Position").setValue(value);
+  return l;
+}
+
+
 // ===== raw.jsx =====
 
 // raw.jsx — escape hatch. Eval arbitrary ExtendScript and return the value.
@@ -2729,11 +4901,349 @@ function __rjSerialize(v, depth, stack, budget) {
   return out;
 }
 
-function __rjResult(result) {
-  // A script with no `return` returns undefined at the top level; that is
-  // genuinely "nothing", not an unserializable value.
-  if (typeof result === "undefined") return null;
-  return __rjSerialize(result, 0, [], { n: 0 });
+// A script whose last statement is a bare expression completes and yields
+// undefined — with every side effect already applied. Handing back a bare
+// `null` for that made "ran fine, returned nothing" identical on the wire to
+// "did not run", and the natural response to a suspected failure is to run the
+// script again. Nothing here rolls back, so a second run of a non-idempotent
+// script duplicates layers, re-applies moveTo, writes keyframes on top of
+// keyframes (issue #43) — and the guidance to prefer few large scripts means
+// the ones most likely to be re-run are the most destructive to re-run.
+//
+// So a null result is never returned bare: it comes back as an envelope that
+// says the script finished. An explicit `return null` is folded into the same
+// envelope, because the ambiguity is in the value, not in how it was produced.
+function __rjResult(result, undoGroupName) {
+  var serialized = (typeof result === "undefined") ? null : __rjSerialize(result, 0, [], { n: 0 });
+  if (serialized !== null) return serialized;
+  return {
+    ok: true,
+    returned: null,
+    undoGroup: undoGroupName,
+    note: "Completed with no `return` value — this is not a failure. Use `return X` to send a value back. " +
+      "Anything the script changed is already applied and nothing rolls back, so read the state back rather than re-running it."
+  };
+}
+
+// ---------- Mapping a failure back onto the caller's own script ----------
+// A failed run_jsx reported After Effects' line number with nothing to measure
+// it against, and that number does not count from where the caller thinks it
+// does: the same "line 22" pointed at two different statements in consecutive
+// calls (issue #46). Nothing rolls back, so an agent that cannot locate the
+// throw has to read the whole project back to find out where the script stopped.
+//
+// Two halves, and the second is the one that actually helps. The caller's line
+// 1 sits a *counted* distance down the evaluated source: with no libraries the
+// prefix carries no newline and the distance is zero, and with libraries it is
+// however many lines of library text were inlined ahead of the script.
+// __rjBuildSource measures the preamble it actually built rather than asserting
+// a constant, so the number can never drift from the string it describes —
+// a hand-written constant beside a string is exactly how the two came apart the
+// first time. Then the mapped line is reported with its TEXT, which an agent
+// can act on without trusting any numbering at all.
+//
+// The mapping refuses to guess: a line that falls outside the submitted source
+// is reported as unmappable, never clamped — unless it lands in a library that
+// was inlined ahead of it, which is a real file with real lines and is named.
+// A confident wrong line number is worse than none — it sends the reader to a
+// statement that did not fail.
+var __RJ_WRAP_PREFIX = "(function(){ ";
+// The closer sits on its own line. Appended to the caller's last line, a script
+// ending in a `//` comment commented out its own `})()` and failed to parse for
+// a reason nothing in the error mentioned.
+var __RJ_WRAP_SUFFIX = "\n})()";
+
+// No regex literal: tests/unit/jsx-ternary.mjs strips string and comment
+// literals from these sources and does not understand regex literals, so one
+// here could desynchronise its scan of this file. (audio.jsx and footage.jsx do
+// carry a few; they survive only because their contents happen to pair up.)
+function __rjLines(s) {
+  return String(s).split("\r\n").join("\n").split("\r").join("\n").split("\n");
+}
+
+// The preamble of a call with no libraries: the bare wrapper opener, which
+// carries no newline, so zero. __rjBuildSource recomputes this per call once
+// libraries are in it; this is the default __rjSourceInfo falls back on when a
+// caller hands it no layout.
+var __RJ_PREAMBLE_LINES = __rjLines(__RJ_WRAP_PREFIX).length - 1;
+
+function __rjTrim(s) {
+  var t = String(s);
+  var a = 0;
+  var b = t.length;
+  while (a < b && (t.charAt(a) === " " || t.charAt(a) === "\t")) a++;
+  while (b > a && (t.charAt(b - 1) === " " || t.charAt(b - 1) === "\t")) b--;
+  return t.substring(a, b);
+}
+
+function __rjClip(s, max) {
+  var t = String(s);
+  if (t.length <= max) return t;
+  return t.substring(0, max) + " ...";
+}
+
+// What After Effects reported, mapped onto the source the caller submitted.
+// Nothing here is fabricated: when the number does not land inside the script,
+// sourceLine stays null and the server says the number could not be mapped.
+//
+// `layout` is what __rjBuildSource returned for this call — how many lines of
+// preamble sit ahead of the caller's line 1, and where each inlined library
+// landed in the evaluated source. Omitted, it means the bare wrapper: no
+// libraries and a zero-line preamble, which is every call without `libraries`.
+function __rjSourceInfo(e, code, scriptPath, layout) {
+  var lay = layout ? layout : { preambleLines: __RJ_PREAMBLE_LINES, segments: [] };
+  var preamble = lay.preambleLines;
+  var segs = lay.segments ? lay.segments : [];
+  var lines = __rjLines(code);
+  var info = {
+    lineCount: lines.length,
+    rawLine: null,
+    sourceLine: null,
+    sourceText: null
+  };
+  if (scriptPath) info.sourceName = String(scriptPath);
+
+  var raw = null;
+  try {
+    if (e && typeof e.line === "number" && isFinite(e.line)) raw = e.line;
+  } catch (e1) {}
+  info.rawLine = raw;
+
+  // Which line of the *evaluated source* — the wrapper, the inlined libraries
+  // and the caller's script together — the failure sits on. After Effects' own
+  // `line` already counts from there, which is what makes it usable at all.
+  var wrapperLine = null;
+
+  // ExtendScript's Error also carries `source` (the text the error was raised
+  // in) with `start`/`end` character offsets into it, and the documentation
+  // presents those as the better answer, because they need no assumption about
+  // what `line` counts from. On After Effects 2026 they are not offsets at all.
+  //
+  // Probed inside AE, catching from a four-line script that throws on line 4:
+  //
+  //   eval("(function(){ var a=1;\nvar b=2;\nvar c=3;\nnope.boom();\n})()")
+  //   caught -> { "line": 4, "start": 0, "end": 0, "srcLen": 57 }
+  //
+  // `line` is already correct. `start` and `end` came back 0 on every error
+  // measured, however far into the source it was raised. Read as an offset, a
+  // zero start puts *every* failure on line 1 and prints line 1's text — which
+  // is exactly what issue #46 still did after it was reported fixed, with the
+  // true number demoted to the parenthetical afterwards.
+  //
+  // So the branch survives only for offsets that could actually be real: 0/0 is
+  // After Effects declining to say, not After Effects pointing at the first
+  // character. Do not restore this from the documentation.
+  try {
+    var src = null;
+    if (e && typeof e.source === "string") src = e.source;
+    var start = null;
+    if (e && typeof e.start === "number" && isFinite(e.start)) start = e.start;
+    var end = null;
+    if (e && typeof e.end === "number" && isFinite(e.end)) end = e.end;
+    var offsetsUsable = false;
+    if (start !== null && start > 0) offsetsUsable = true;
+    if (start === 0 && end !== null && end > 0) offsetsUsable = true;
+    if (offsetsUsable && src !== null &&
+        src.substring(0, __RJ_WRAP_PREFIX.length) === __RJ_WRAP_PREFIX) {
+      wrapperLine = __rjLines(src.substring(0, start)).length;
+    }
+  } catch (e2) {}
+  if (wrapperLine === null) wrapperLine = raw;
+  if (wrapperLine === null) return info;
+
+  var mapped = wrapperLine - preamble;
+  if (mapped >= 1 && mapped <= lines.length) {
+    info.sourceLine = mapped;
+    info.sourceText = __rjClip(__rjTrim(lines[mapped - 1]), 200);
+    return info;
+  }
+
+  // Not the caller's script. A library inlined ahead of it is a real file with
+  // real lines, so name it and point into it rather than reporting the number
+  // as unmappable: that file is where the reader has to look, and naming the
+  // script instead would send them to a line that did not fail.
+  for (var s = 0; s < segs.length; s++) {
+    var seg = segs[s];
+    var count = seg.lines.length - 1;
+    var within = wrapperLine - seg.firstLine + 1;
+    if (within >= 1 && within <= count) {
+      info.sourceName = seg.path;
+      info.lineCount = count;
+      info.sourceLine = within;
+      info.sourceText = __rjClip(__rjTrim(seg.lines[within - 1]), 200);
+      return info;
+    }
+  }
+  return info;
+}
+
+// Rethrow with the mapping attached. dispatch()'s catch copies whatever sits on
+// `aeDetail` onto the error result; the panel forwards the fields it names and
+// the server prints the line's text. A plain object rather than an Error
+// because ExtendScript will not reliably let us write `line` on one, and
+// __mkError only ever reads message/stack/line.
+function __rjThrowWithSource(e, code, scriptPath, layout) {
+  var info = __rjSourceInfo(e, code, scriptPath, layout);
+  var msg = "";
+  try { if (e && e.message) msg = String(e.message); } catch (e1) {}
+  if (!msg) {
+    try { msg = String(e); } catch (e2) { msg = "ExtendScript error"; }
+  }
+  var stack = "";
+  try { if (e && e.stack) stack = String(e.stack); } catch (e3) {}
+  throw { message: msg, stack: stack, line: info.rawLine, aeDetail: info };
+}
+
+// ---------- Helper libraries ----------
+// A library's source is inlined into the SAME eval as the caller's script,
+// ahead of it. That is not the obvious design, and it is the only one that
+// works.
+//
+// The first version used $.evalFile, on the documented premise that it
+// evaluates at global scope — load once, call for the rest of the After Effects
+// session (issue #53). Probed inside AE 2026, calling $.evalFile from the body
+// of an eval'd script, on a library declaring `function rig2()` and
+// `var RIGVAR = 3`:
+//
+//   {"exists":true, "typeofRig2_local":"function", "typeofRIGVAR_local":"number",
+//    "globalRig2":"undefined", "viaGlobal":null}
+//   // and on the next run_jsx call, in the same AE session:
+//   {"typeofRig2":"undefined", "viaGlobal":"undefined"}
+//
+// $.evalFile evaluates into the *calling function's* scope, exactly as eval
+// does. Everything a library defined therefore lived inside the loader and was
+// gone before the wrapper ran, so `libraries` answered "Function rig is
+// undefined" every time, for every library, in every session. The per-session
+// cache keyed on a content hash has gone with it: nothing was ever left loaded
+// to reuse, so the only work it ever skipped was work whose result had already
+// been discarded.
+//
+// One eval means one scope: a library's `function helper(){}` is a declaration
+// in the same function body as the script, so the script can call it. Two
+// consequences, both handled here rather than left to surprise someone:
+//
+//  * A library is re-evaluated on every call. That is the price of the scoping
+//    After Effects actually has. Keep libraries to declarations, not to work.
+//  * The library text shifts the caller's line 1 down, which is precisely the
+//    failure issue #46 was about. __rjBuildSource *counts* the preamble it
+//    built rather than asserting a constant, and __rjSourceInfo subtracts that
+//    count — so a caller's line 1 is line 1 of their own script whether they
+//    passed libraries or not.
+
+// No regex literal, for the same reason __rjLines has none.
+function __rjIsBlank(s) {
+  var t = String(s);
+  for (var i = 0; i < t.length; i++) {
+    var c = t.charAt(i);
+    if (c !== " " && c !== "\t" && c !== "\n" && c !== "\r") return false;
+  }
+  return true;
+}
+
+// Every library ends in a newline before the next one — or the caller's script
+// — follows it. Appended directly, a library whose last line is a `//` comment
+// would comment out whatever came after it: the same trap __RJ_WRAP_SUFFIX
+// exists for at the other end of the wrapper.
+function __rjEndWithNewline(s) {
+  var t = String(s);
+  if (t.length === 0) return "\n";
+  var last = t.charAt(t.length - 1);
+  if (last === "\n" || last === "\r") return t;
+  return t + "\n";
+}
+
+// The server reads library files and sends {path, text}, exactly as it does for
+// scriptPath — one place reads files, and its errors can name the path it was
+// given. Arriving with a path and no text means the call did not come through
+// the run_jsx tool: a run_batch step, whose args are never validated, or a
+// hand-rolled POST /op.
+function __rjLibrarySource(lib) {
+  var p = null;
+  var text = null;
+  if (typeof lib === "string") {
+    p = lib;
+  } else if (lib) {
+    p = lib.path;
+    if (typeof lib.text === "string") text = lib.text;
+  }
+  if (!p) throw new Error("run_jsx: a libraries entry has no path.");
+  if (text === null) {
+    throw new Error(
+      "run_jsx library \"" + p + "\" arrived with no source text. The server reads library files " +
+      "and substitutes their contents, so this call did not go through the run_jsx tool — " +
+      "run_batch steps and direct /op posts must pass {path, text} themselves."
+    );
+  }
+  if (__rjIsBlank(text)) throw new Error("run_jsx library is empty: " + p);
+  return { path: String(p), text: __rjEndWithNewline(text) };
+}
+
+// Parse each library on its own before any of it reaches the shared eval.
+// Inlining means a library that does not parse takes the whole wrapper with it,
+// and the line After Effects reports for a syntax error is wherever its parser
+// gave up — frequently inside the caller's script, which would blame the wrong
+// file for someone else's missing brace. An uncalled function expression forces
+// a full parse of exactly this library and nothing else, so the failure names
+// it and counts from its own line 1.
+function __rjCheckLibraryParses(lib) {
+  try {
+    eval("(function(){ " + lib.text + "})");
+  } catch (e) {
+    var m = "";
+    try { m = (e && e.message) ? String(e.message) : String(e); } catch (e1) { m = "unknown error"; }
+    var ln = null;
+    try { if (e && typeof e.line === "number" && isFinite(e.line)) ln = e.line; } catch (e2) {}
+    var libLines = __rjLines(lib.text);
+    var count = libLines.length - 1;
+    var detail = {
+      lineCount: count,
+      rawLine: ln,
+      sourceLine: null,
+      sourceText: null,
+      sourceName: lib.path
+    };
+    if (ln !== null && ln >= 1 && ln <= count) {
+      detail.sourceLine = ln;
+      detail.sourceText = __rjClip(__rjTrim(libLines[ln - 1]), 200);
+    }
+    throw {
+      message: "run_jsx library failed to parse: " + lib.path + " — " + m,
+      stack: "",
+      line: ln,
+      aeDetail: detail
+    };
+  }
+}
+
+// The evaluated source for one call, plus the map that turns any line of it
+// back into a line of a file the caller knows about.
+//
+// `preambleLines` is COUNTED from the text that precedes the script rather than
+// assumed. That is the invariant issue #46 turned on, and it now has to hold
+// for a preamble whose length changes from call to call: it can never drift
+// from the string it describes, however many libraries there are.
+function __rjBuildSource(code, libraries) {
+  var prefix = __RJ_WRAP_PREFIX;
+  var segments = [];
+  if (libraries && libraries.length) {
+    for (var i = 0; i < libraries.length; i++) {
+      var lib = __rjLibrarySource(libraries[i]);
+      __rjCheckLibraryParses(lib);
+      segments.push({
+        path: lib.path,
+        // The wrapper opener carries no newline, so the first library's line 1
+        // shares line 1 of the evaluated source with it.
+        firstLine: __rjLines(prefix).length,
+        lines: __rjLines(lib.text)
+      });
+      prefix = prefix + lib.text;
+    }
+  }
+  return {
+    wrapper: prefix + code + __RJ_WRAP_SUFFIX,
+    preambleLines: __rjLines(prefix).length - 1,
+    segments: segments
+  };
 }
 
 // undoGroup:false is a per-call opt-out, read by dispatch() through the
@@ -2742,7 +5252,42 @@ function __rjResult(result) {
 // which is exactly the layer worth copying (issue #30).
 OPS.run_jsx = noUndoWhen(function (args) { return args.undoGroup === false; }, function (args) {
   var code = args.code || "";
-  // We wrap in a function so `return` works.
-  var wrapper = "(function(){ " + code + " })()";
-  return __rjResult(eval(wrapper));
+  // scriptPath is resolved to code by the *server* before the payload is built.
+  // Arriving here with a path and no code means it came in some other way — a
+  // run_batch step, whose args are never validated, or a hand-rolled POST /op.
+  // Running an empty script would return the "completed with no return value"
+  // envelope, which is a success result for a file nobody read.
+  if (!code && args.scriptPath) {
+    throw new Error(
+      "run_jsx received scriptPath \"" + args.scriptPath + "\" with no code. The server reads that " +
+      "file and substitutes it, so this path did not go through the run_jsx tool — run_batch steps " +
+      "and direct /op posts must pass `code` themselves."
+    );
+  }
+  if (!code) throw new Error("run_jsx needs `code` — an empty script would report success for nothing.");
+  // We wrap in a function so `return` works, with any libraries inlined ahead
+  // of the script so they share its scope. Assembled and parse-checked before
+  // anything runs, and outside the try below: a library that fails to parse is
+  // not a line in the caller's script and must not be reported as one.
+  var built = __rjBuildSource(code, args.libraries);
+  // Which undo step to look for in AE if the script has to be backed out. The
+  // name mirrors dispatch()'s default ("AE MCP: " + op); false means the caller
+  // asked for no group and the changes landed as whatever steps AE recorded.
+  var undoGroupName = (args.undoGroup === false) ? false : "AE MCP: run_jsx";
+  // diff:true fingerprints the comp before and after, inside this one call —
+  // see snapshot.jsx. Null unless asked for, so the ordinary path is untouched.
+  var __d = __diffStart(args, null);
+  var __value;
+  try {
+    __value = eval(built.wrapper);
+  } catch (e) {
+    // Annotate before mapping the line: __rjThrowWithSource reads e.message,
+    // so the diff note has to be on it by then, and the source mapping is what
+    // makes the reported line the caller's own (#46).
+    __diffAnnotateError(e, __d);
+    __rjThrowWithSource(e, code, args.scriptPath, built);
+  }
+  var __out = __rjResult(__value, undoGroupName);
+  if (__d) return __rjWithDiff(__out, __diffFinish(__d), undoGroupName);
+  return __out;
 });