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

package/panel/jsx/bundle.jsx

@@ -1,5 +1,4 @@
 // Auto-generated bundle. Do not edit directly — edit files in packages/jsx/.
-// Generated 2026-08-12T07:06:29.484Z
 
 // ===== core.jsx =====
 
@@ -70,10 +69,29 @@ 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.
+var __UNDO_OPEN = false;
+
 function withUndo(name, fn) {
   app.beginUndoGroup(name || "AE MCP");
+  __UNDO_OPEN = true;
   try { return fn(); }
-  finally { app.endUndoGroup(); }
+  finally { __UNDO_OPEN = false; app.endUndoGroup(); }
+}
+
+// Run fn with the dispatcher's undo group closed, then reopen it.
+// After Effects refuses a handful of operations while an undo group is open —
+// copyToComp on a layer with a parent or a linked expression is the one that
+// bites (issue #30). No-op when no group of ours is open, so it is always safe
+// to call. The work inside becomes its own undo step, separate from the rest.
+function withoutUndoGroup(fn) {
+  if (!__UNDO_OPEN) return fn();
+  app.endUndoGroup();
+  __UNDO_OPEN = false;
+  try { return fn(); }
+  finally { app.beginUndoGroup("AE MCP: continue"); __UNDO_OPEN = true; }
 }
 
 // ---------- Error helper ----------
@@ -97,7 +115,13 @@ function dispatch(payloadJson) {
   try {
     var handler = OPS[op];
     var meta = handler.__meta || {};
-    if (meta.noUndo) {
+    // __meta.noUndo is a boolean for handlers that never want a group, or a
+    // predicate over args for ops where the caller decides per call (run_jsx).
+    // Keeping the predicate on the handler is what stops one op's opt-out from
+    // leaking into the next: dispatch never remembers anything between calls.
+    var skipUndo = meta.noUndo;
+    if (typeof skipUndo === "function") skipUndo = skipUndo(args);
+    if (skipUndo) {
       return { ok: true, result: handler(args) };
     }
     var result = withUndo(meta.undoName || ("AE MCP: " + op), function () { return handler(args); });
@@ -109,6 +133,8 @@ function dispatch(payloadJson) {
 
 // Helper for handlers that don't want an undo group (read-only ops, job continuations).
 function noUndo(fn) { fn.__meta = { noUndo: true }; return fn; }
+// Same, but the handler decides per call from its own args.
+function noUndoWhen(pred, fn) { fn.__meta = { noUndo: pred }; return fn; }
 function undoNamed(name, fn) { fn.__meta = { undoName: name }; return fn; }
 
 
@@ -165,27 +191,42 @@ function colorOrDefault(c, fallback) {
 
 // comps.jsx — composition ops.
 
-function __compSummary(c) {
-  return {
-    id: c.id,
-    name: c.name,
-    width: c.width,
-    height: c.height,
-    duration: c.duration,
-    frameRate: c.frameRate,
-    pixelAspect: c.pixelAspect,
-    bgColor: [c.bgColor[0], c.bgColor[1], c.bgColor[2]],
-    numLayers: c.numLayers,
-    workAreaStart: c.workAreaStart,
-    workAreaDuration: c.workAreaDuration,
-  };
+// The section filter every read op shares. `sections` is the caller's `include`
+// array: null/undefined means "all of them", which is what every caller written
+// before `include` existed passes. An empty array means the identifying core
+// only. Defined here because comps.jsx is the first module in the bundle that
+// needs it; layers.jsx and explore.jsx use the same one.
+function __wantsSection(sections, name) {
+  if (!sections) return true;
+  for (var i = 0; i < sections.length; i++) if (sections[i] === name) return true;
+  return false;
+}
+
+function __compSummary(c, sections) {
+  // id and name are the map an agent orients with, so they are never optional.
+  var out = { id: c.id, name: c.name };
+  if (__wantsSection(sections, "size")) {
+    out.width = c.width;
+    out.height = c.height;
+    out.pixelAspect = c.pixelAspect;
+  }
+  if (__wantsSection(sections, "timing")) {
+    out.duration = c.duration;
+    out.frameRate = c.frameRate;
+    out.workAreaStart = c.workAreaStart;
+    out.workAreaDuration = c.workAreaDuration;
+  }
+  if (__wantsSection(sections, "bg")) out.bgColor = [c.bgColor[0], c.bgColor[1], c.bgColor[2]];
+  if (__wantsSection(sections, "counts")) out.numLayers = c.numLayers;
+  return out;
 }
 
 OPS.list_comps = noUndo(function (args) {
+  var sections = (args && args.include) ? args.include : null;
   var out = [];
   for (var i = 1; i <= app.project.numItems; i++) {
     var it = app.project.item(i);
-    if (it instanceof CompItem) out.push(__compSummary(it));
+    if (it instanceof CompItem) out.push(__compSummary(it, sections));
   }
   return out;
 });
@@ -272,32 +313,40 @@ function __layerKind(l) {
   return "unknown";
 }
 
-function __layerSummary(l) {
-  var parent = l.parent ? l.parent.id : null;
-  return {
+// `sections` is the caller's `include` array (see __wantsSection in comps.jsx).
+// Null means every section, so every existing caller is unaffected; the core —
+// the id/index/name/type map an agent orients with — is always present.
+function __layerSummary(l, sections) {
+  var out = {
     id: l.id,
     index: l.index,
     name: l.name,
-    enabled: l.enabled,
-    solo: l.solo,
-    locked: l.locked,
-    shy: l.shy,
-    threeDLayer: l.threeDLayer,
-    label: l.label,
-    inPoint: l.inPoint,
-    outPoint: l.outPoint,
-    startTime: l.startTime,
-    stretch: l.stretch,
     sourceType: __layerKind(l),
-    parent: parent,
-    blendingMode: l.blendingMode,
   };
+  if (__wantsSection(sections, "flags")) {
+    out.enabled = l.enabled;
+    out.solo = l.solo;
+    out.locked = l.locked;
+    out.shy = l.shy;
+    out.threeDLayer = l.threeDLayer;
+    out.label = l.label;
+    out.blendingMode = l.blendingMode;
+  }
+  if (__wantsSection(sections, "timing")) {
+    out.inPoint = l.inPoint;
+    out.outPoint = l.outPoint;
+    out.startTime = l.startTime;
+    out.stretch = l.stretch;
+  }
+  if (__wantsSection(sections, "parent")) out.parent = l.parent ? l.parent.id : null;
+  return out;
 }
 
 OPS.list_layers = noUndo(function (args) {
   var c = getCompById(args.compId);
+  var sections = (args && args.include) ? args.include : null;
   var out = [];
-  for (var i = 1; i <= c.numLayers; i++) out.push(__layerSummary(c.layer(i)));
+  for (var i = 1; i <= c.numLayers; i++) out.push(__layerSummary(c.layer(i), sections));
   return out;
 });
 
@@ -305,27 +354,35 @@ OPS.create_text_layer = function (args) {
   var c = getCompById(args.compId);
   var l = c.layers.addText(args.text || "");
   if (args.name) l.name = args.name;
-  // Apply font/size/color through TextDocument first — sourceRectAtTime depends on these.
-  if (args.font || args.size || args.color) {
+  // `anchorAlign` is paragraph justification, not geometry. Offsetting the
+  // anchor to the measured bbox edge (what this did before) looks right at
+  // creation and is wrong the moment the Source Text changes — retyped, driven
+  // by an expression, or edited through Essential Graphics in Premiere — because
+  // the anchor stays baked for the old string and the layout jumps. Justifying
+  // instead keeps the alignment live and leaves the anchor at the origin, which
+  // is also what sourceRectAtTime()-driven backgrounds expect.
+  //
+  // Tracking is normalised for a different reason: addText() inherits the
+  // workspace's Character panel, so an untouched layer arrives with whatever
+  // that was last left on (-20 is common) and the same call renders differently
+  // on two machines. `tracking` sets it explicitly; omitting it means 0.
+  //
+  // 'none' opts out of all of it and leaves AE's raw defaults alone.
+  var align = args.anchorAlign === undefined ? "left" : args.anchorAlign;
+  var wantJustify = align !== "none" && __JUSTIFICATION[align] !== undefined;
+  var wantTracking = args.tracking !== undefined || align !== "none";
+  if (args.font || args.size || args.color || wantJustify || wantTracking) {
     var srcText = l.property("Source Text");
     var td = srcText.value;
     if (args.font) td.font = args.font;
     if (args.size) td.fontSize = args.size;
     if (args.color) { td.applyFill = true; td.fillColor = [args.color[0], args.color[1], args.color[2]]; }
+    if (wantTracking) td.tracking = (args.tracking !== undefined ? args.tracking : 0);
+    if (wantJustify) td.justification = __JUSTIFICATION[align];
     srcText.setValue(td);
   }
-  // AE's addText() puts the anchor at the bbox center, which surprises agents
-  // who expect position to mean the left edge. Default to 'left' so position
-  // semantically matches the visible start of the text. 'none' opts out.
-  var align = args.anchorAlign === undefined ? "left" : args.anchorAlign;
   if (align !== "none") {
-    try {
-      var __rect = l.sourceRectAtTime(c.time, false);
-      var __ax = __rect.left;
-      if (align === "center") __ax = __rect.left + __rect.width / 2;
-      else if (align === "right") __ax = __rect.left + __rect.width;
-      l.property("Transform").property("Anchor Point").setValue([__ax, 0, 0]);
-    } catch (__e) {}
+    l.property("Transform").property("Anchor Point").setValue([0, 0, 0]);
   }
   if (args.position) {
     var p = args.position;
@@ -443,15 +500,328 @@ OPS.set_layer = function (args) {
   return __layerSummary(l);
 };
 
+// ---------------------------------------------------------------------------
+// Parenting that does not move the layer
+// ---------------------------------------------------------------------------
+// AE compensates a child's transform when you assign layer.parent, but within
+// one script evaluation it reads the parent from stale data if that parent was
+// itself re-parented earlier in the same evaluation: the compensation runs
+// against the pre-move parent and the child lands at W - parentWorld twice
+// over, and a parent whose scale is not 100 leaves children at 333% (issue
+// #28). run_batch and run_jsx are one evaluation, so this is their normal case.
+//
+// So we do not trust it. We compute the child's world transform ourselves from
+// property values before the assignment, compute it again after, and correct
+// the local transform when the two disagree. When AE gets it right the two
+// agree and nothing is written at all — that no-op is what makes
+// preserveTransform safe to default to true.
+//
+// The matrices are ours because AE's scripting DOM has no toComp/toWorld —
+// those exist only in the expression language. Limits, all reported in the
+// result rather than worked around:
+//   * 2D only. AE's 3D chain (orientation plus three rotations, composed in
+//     AE's own order) is not reimplementable here with any confidence, so a 3D
+//     layer, camera or light anywhere in either chain skips the correction.
+//   * One time. Everything is measured at the comp's current time. A keyframed
+//     or expression-driven ancestor makes the world transform time-varying, and
+//     no static correction is right at every frame.
+//   * Position only when AE is provably wrong. See __PARENT_POS_MODEL below.
+
+// Well below anything visible, well above double-precision noise through a
+// chain of matrix products. Nothing is written inside these — the point is that
+// a correct compensation is left exactly as AE wrote it.
+var __PT_TOL_POS = 1e-3;     // comp pixels
+var __PT_TOL_SCALE = 1e-3;   // percentage points
+var __PT_TOL_ROT = 1e-3;     // degrees
+
+// A child's Position is measured in its parent's space, and there are two
+// readings of where that space starts: at the parent's layer-space origin (so
+// Position is a point pushed through the parent's own matrix) or at the
+// parent's anchor point. They differ by exactly the parent's anchor, mapped up
+// the chain, and coincide whenever every anchor above is [0,0] — which covers
+// nulls, shapes and point text, i.e. most rigs. Rather than bet on one, we
+// compute both, and only rewrite Position when AE's own answer matches
+// *neither* — that is the only case where AE is provably wrong, and it is the
+// bug. When AE matches one of them we learn which for the rest of the session.
+var __PARENT_POS_MODEL = null;
+
+// Duck-typed rather than `instanceof Array` so it holds for anything indexable
+// AE hands back, and a bare number promotes to a vector.
+function __ptV2(v) {
+  if (v === null || v === undefined) return [0, 0];
+  if (typeof v === "number") return [v, 0];
+  return [v[0] || 0, v[1] || 0];
+}
+
+// 2D affine as [a, b, c, d, tx, ty]:  x' = a*x + c*y + tx,  y' = b*x + d*y + ty
+function __ptMId() { return [1, 0, 0, 1, 0, 0]; }
+function __ptMMul(m, n) {                 // apply n first, then m
+  return [
+    m[0] * n[0] + m[2] * n[1],
+    m[1] * n[0] + m[3] * n[1],
+    m[0] * n[2] + m[2] * n[3],
+    m[1] * n[2] + m[3] * n[3],
+    m[0] * n[4] + m[2] * n[5] + m[4],
+    m[1] * n[4] + m[3] * n[5] + m[5]
+  ];
+}
+function __ptMPoint(m, p) { return [m[0] * p[0] + m[2] * p[1] + m[4], m[1] * p[0] + m[3] * p[1] + m[5]]; }
+function __ptMVec(m, p) { return [m[0] * p[0] + m[2] * p[1], m[1] * p[0] + m[3] * p[1]]; }
+function __ptMLinear(m) { return [m[0], m[1], m[2], m[3], 0, 0]; }
+function __ptMInvert(m) {
+  var det = m[0] * m[3] - m[1] * m[2];
+  if (!isFinite(det) || Math.abs(det) < 1e-12) return null;   // a scale of 0 somewhere
+  var a = m[3] / det, b = -m[1] / det, cc = -m[2] / det, d = m[0] / det;
+  return [a, b, cc, d, -(a * m[4] + cc * m[5]), -(b * m[4] + d * m[5])];
+}
+function __ptNear(a, b, tol) {
+  if (!a || !b) return false;
+  return Math.abs(a[0] - b[0]) < tol && Math.abs(a[1] - b[1]) < tol;
+}
+function __ptWrapDeg(d) { while (d > 180) d -= 360; while (d <= -180) d += 360; return d; }
+function __ptR4(n) { return Math.round(n * 10000) / 10000; }   // for prose only; reported deltas keep full precision
+
+function __ptProps(l) {
+  var tr = l.property("Transform");
+  return {
+    position: tr.property("Position"),
+    anchor: tr.property("Anchor Point"),
+    scale: tr.property("Scale"),
+    rotation: tr.property("Rotation")
+  };
+}
+
+function __ptAnimated(p) {
+  var list = [p.position, p.anchor, p.scale, p.rotation];
+  for (var i = 0; i < list.length; i++) {
+    if (!list[i]) continue;
+    if (list[i].numKeys > 0) return true;
+    try { if (list[i].expressionEnabled) return true; } catch (e) {}
+  }
+  return false;
+}
+
+// T(position) · R(rotation) · S(scale/100) · T(-anchor). This is the same
+// matrix the layer uses for its own points, which is what lets a child's
+// Position be fed straight through its parent's copy of it.
+function __ptLocalMatrix(l, t) {
+  var p = __ptProps(l);
+  var pos = __ptV2(p.position.valueAtTime(t, false));
+  var anc = __ptV2(p.anchor.valueAtTime(t, false));
+  var sc = __ptV2(p.scale.valueAtTime(t, false));
+  var rad = p.rotation.valueAtTime(t, false) * Math.PI / 180;
+  var cos = Math.cos(rad), sin = Math.sin(rad);
+  var rs = [cos * sc[0] / 100, sin * sc[0] / 100, -sin * sc[1] / 100, cos * sc[1] / 100, 0, 0];
+  return __ptMMul(__ptMMul([1, 0, 0, 1, pos[0], pos[1]], rs), [1, 0, 0, 1, -anc[0], -anc[1]]);
+}
+
+// Walks up the parent chain. `m` is the layer's full world matrix; `wb` is its
+// world anchor position under the anchor-relative reading of Position.
+function __ptChain(l, t, depth) {
+  if (!l) return { ok: true, m: __ptMId(), wb: [0, 0], animated: false };
+  if (depth > 32) return { ok: false, reason: "parent chain deeper than 32 layers" };
+  if (!(l instanceof AVLayer)) return { ok: false, reason: 'a camera or light in the chain ("' + l.name + '") has no 2D transform' };
+  if (l.threeDLayer) return { ok: false, reason: 'a 3D layer in the chain ("' + l.name + '")' };
+  var up = __ptChain(l.parent, t, depth + 1);
+  if (!up.ok) return up;
+  var p = __ptProps(l);
+  var off = __ptMVec(up.m, __ptV2(p.position.valueAtTime(t, false)));
+  return {
+    ok: true,
+    m: __ptMMul(up.m, __ptLocalMatrix(l, t)),
+    wb: [up.wb[0] + off[0], up.wb[1] + off[1]],
+    animated: up.animated || __ptAnimated(p)
+  };
+}
+
+// Applies fn to a property's static value, or to every keyframe. AE's own
+// compensation rewrites every key, so ours does too: the correction is a
+// constant change of frame, not a change of animation.
+function __ptAdjust(prop, fn) {
+  if (prop.numKeys > 0) {
+    for (var i = 1; i <= prop.numKeys; i++) prop.setValueAtKey(i, fn(prop.keyValue(i)));
+    return prop.numKeys;
+  }
+  prop.setValue(fn(prop.value));
+  return 0;
+}
+
+function __ptExprDriven(prop) {
+  try { return !!prop.expressionEnabled; } catch (e) { return false; }
+}
+
 OPS.parent_layer = function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
-  if (args.parentLayerId === null) {
-    l.parent = null;
+  var newParent = null;
+  if (args.parentLayerId !== null && args.parentLayerId !== undefined) {
+    newParent = getLayerById(c, args.parentLayerId);
+  }
+  var preserve = args.preserveTransform !== false;
+
+  if (!preserve) {
+    l.parent = newParent;
+    var plain = __layerSummary(l);
+    plain.preserveTransform = false;
+    return plain;
+  }
+
+  var t = c.time;
+  var notes = [];
+  var before = __ptChain(l, t, 0);
+  var oldParent = __ptChain(l.parent, t, 0);
+  var posChildBefore = __ptV2(__ptProps(l).position.valueAtTime(t, false));
+
+  // The parenting itself always happens, whether or not we can check it.
+  l.parent = newParent;
+
+  var out = __layerSummary(l);
+  out.preserveTransform = true;
+  var corr = {
+    applied: false,
+    atTime: t,
+    positionDelta: null,
+    scaleDelta: null,
+    rotationDelta: null,
+    keysAdjusted: 0,
+    positionModel: null,
+    timeVarying: false,
+    notes: notes
+  };
+  out.correction = corr;
+
+  if (!before.ok || !oldParent.ok) {
+    notes.push("not corrected: " + (before.reason || oldParent.reason));
+    return out;
+  }
+  var after = __ptChain(newParent, t, 0);
+  if (!after.ok) {
+    notes.push("not corrected: " + after.reason);
+    return out;
+  }
+  var invAfter = __ptMInvert(after.m);
+  if (!invAfter) {
+    notes.push("not corrected: the new parent chain has a scale of 0 and cannot be inverted");
+    return out;
+  }
+  corr.timeVarying = !!(before.animated || after.animated);
+  if (corr.timeVarying) {
+    notes.push("a transform in the chain is keyframed or expression-driven, so the world transform varies over time; corrected at comp time " + t);
+  }
+
+  var props = __ptProps(l);
+  // The child's world anchor position before the assignment, under each of the
+  // two readings of what a child's Position means in its parent's space.
+  var waAnchorRel = __ptV2(before.wb);
+  var waLayerSpace = __ptMPoint(oldParent.m, posChildBefore);
+
+  // --- rotation and scale -------------------------------------------------
+  // The linear part of a world matrix is the product of R·S up the chain, which
+  // is the same under both readings of Position. This half is model-free.
+  //
+  // desired = inv(Lin(new parent chain)) · Lin(child's world before), i.e. the
+  // child's own R·S that reproduces the world it had. Split it back into a
+  // rotation and an axis-aligned scale: column 0 is R·(sx,0) and column 1 is
+  // R·(0,sy), so |column 0| is |sx| and its angle is the rotation. A mirrored
+  // layer can be written either as a negative sx or as a negative sy plus 180
+  // degrees, so we keep whichever sign the layer already carries rather than
+  // rewriting an equivalent transform for no reason.
+  var desired = __ptMMul(__ptMLinear(invAfter), __ptMLinear(before.m));
+  var scNow = __ptV2(props.scale.valueAtTime(t, false));
+  var col0x = desired[0], col0y = desired[1];
+  var negX = (scNow[0] < 0);
+  if (negX) { col0x = -col0x; col0y = -col0y; }
+  var sxNew = Math.sqrt(col0x * col0x + col0y * col0y);
+  if (negX) sxNew = -sxNew;
+  var theta = Math.atan2(col0y, col0x);
+  var cs = Math.cos(theta), sn = Math.sin(theta);
+  var skew = cs * desired[2] + sn * desired[3];
+  var syNew = -sn * desired[2] + cs * desired[3];
+  if (Math.abs(skew) > 1e-6) {
+    notes.push("the new parent shears the layer (non-uniform scale under rotation); position/scale/rotation cannot express it exactly, residual skew " + __ptR4(skew));
+  }
+
+  var rotNow = props.rotation.valueAtTime(t, false);
+  var rotDelta = __ptWrapDeg(theta * 180 / Math.PI - rotNow);
+  if (Math.abs(rotDelta) > __PT_TOL_ROT) {
+    if (__ptExprDriven(props.rotation)) {
+      notes.push("rotation is expression-driven; the " + __ptR4(rotDelta) + "deg correction was not written");
+    } else {
+      corr.keysAdjusted += __ptAdjust(props.rotation, function (v) { return v + rotDelta; });
+      corr.rotationDelta = rotDelta;
+      corr.applied = true;
+    }
+  }
+
+  var scTarget = [sxNew * 100, syNew * 100];
+  var dsx = scTarget[0] - scNow[0], dsy = scTarget[1] - scNow[1];
+  if (Math.abs(dsx) > __PT_TOL_SCALE || Math.abs(dsy) > __PT_TOL_SCALE) {
+    if (__ptExprDriven(props.scale)) {
+      notes.push("scale is expression-driven; the correction to [" + __ptR4(scTarget[0]) + ", " + __ptR4(scTarget[1]) + "] was not written");
+    } else if (Math.abs(scNow[0]) < 1e-9 || Math.abs(scNow[1]) < 1e-9) {
+      notes.push("scale is 0 on an axis, so it cannot be scaled back to [" + __ptR4(scTarget[0]) + ", " + __ptR4(scTarget[1]) + "]");
+    } else {
+      // Multiplicative, so a keyframed scale keeps the shape of its animation.
+      var fx = scTarget[0] / scNow[0], fy = scTarget[1] / scNow[1];
+      corr.keysAdjusted += __ptAdjust(props.scale, function (v) {
+        var o = [];
+        for (var i = 0; i < v.length; i++) {
+          var f = fy;
+          if (i === 0) f = fx;
+          o.push(v[i] * f);
+        }
+        return o;
+      });
+      corr.scaleDelta = [dsx, dsy];
+      corr.applied = true;
+    }
+  }
+
+  // --- position -----------------------------------------------------------
+  // Recomputed after the linear correction, since the child's own R·S does not
+  // affect where its anchor lands but AE may have rewritten Position too.
+  var pAfter = __ptV2(props.position.valueAtTime(t, false));
+  var candLayerSpace = __ptMPoint(invAfter, waLayerSpace);
+  var candAnchorRel = __ptMVec(invAfter, [waAnchorRel[0] - after.wb[0], waAnchorRel[1] - after.wb[1]]);
+  var hitLayerSpace = __ptNear(pAfter, candLayerSpace, __PT_TOL_POS);
+  var hitAnchorRel = __ptNear(pAfter, candAnchorRel, __PT_TOL_POS);
+  var ambiguous = !__ptNear(candLayerSpace, candAnchorRel, __PT_TOL_POS);
+
+  if (hitLayerSpace || hitAnchorRel) {
+    // AE placed it where one of the two readings says it belongs — nothing to
+    // fix. Learn the reading when the two candidates actually disagree.
+    if (ambiguous && hitLayerSpace !== hitAnchorRel) {
+      __PARENT_POS_MODEL = hitLayerSpace ? "layer-space" : "anchor-relative";
+    }
+    corr.positionModel = __PARENT_POS_MODEL;
   } else {
-    l.parent = getLayerById(c, args.parentLayerId);
+    var model = __PARENT_POS_MODEL || "layer-space";
+    var target = candLayerSpace;
+    if (model === "anchor-relative") target = candAnchorRel;
+    corr.positionModel = model;
+    if (ambiguous && !__PARENT_POS_MODEL) {
+      notes.push("the parent chain has a non-zero anchor point and this session has not yet seen AE agree with either reading of a child's Position, so the layer-space reading was assumed; the two differ by [" + __ptR4(candLayerSpace[0] - candAnchorRel[0]) + ", " + __ptR4(candLayerSpace[1] - candAnchorRel[1]) + "]");
+    }
+    var dx = target[0] - pAfter[0], dy = target[1] - pAfter[1];
+    if (__ptExprDriven(props.position)) {
+      notes.push("position is expression-driven; the [" + __ptR4(dx) + ", " + __ptR4(dy) + "] correction was not written");
+    } else {
+      corr.keysAdjusted += __ptAdjust(props.position, function (v) {
+        var o = [];
+        for (var i = 0; i < v.length; i++) {
+          var d = 0;
+          if (i === 0) d = dx;
+          else if (i === 1) d = dy;
+          o.push(v[i] + d);
+        }
+        return o;
+      });
+      corr.positionDelta = [dx, dy];
+      corr.applied = true;
+    }
   }
-  return __layerSummary(l);
+
+  return out;
 };
 
 OPS.reorder_layer = function (args) {
@@ -746,28 +1116,57 @@ OPS.set_effect_enabled = function (args) {
   return { ok: true };
 };
 
-OPS.list_available_effects = noUndo(function (args) {
+// Enumerating app.effects is very slow — around 250 entries in AE 26.3, slow
+// enough that a hand-rolled loop over it in run_jsx blocks the panel's socket
+// past the server's timeout and presents as a dead bridge (issue #26). The
+// table only changes when a plugin is installed, which needs an AE restart,
+// which reloads this bundle — so caching it for the life of the session is
+// exact, not merely close enough. Refreshing is available for the case where a
+// user swears they just installed something.
+var __availableEffects = null;
+
+function __enumerateEffects() {
   // app.effects is an array of {displayName, matchName, category, version} on modern AE.
-  var out = [];
+  var fx;
   try {
-    var fx = app.effects;
-    for (var i = 0; i < fx.length; i++) {
-      out.push({ displayName: fx[i].displayName, matchName: fx[i].matchName, category: fx[i].category });
-    }
+    fx = app.effects;
   } catch (e) {
-    // Fallback: return a curated subset of common match names.
-    out = [
-      { displayName: "Gaussian Blur", matchName: "ADBE Gaussian Blur 2", category: "Blur & Sharpen" },
-      { displayName: "Fast Box Blur", matchName: "ADBE Box Blur2", category: "Blur & Sharpen" },
-      { displayName: "Glow", matchName: "ADBE Glo2", category: "Stylize" },
-      { displayName: "Drop Shadow", matchName: "ADBE Drop Shadow", category: "Perspective" },
-      { displayName: "Curves", matchName: "ADBE CurvesCustom", category: "Color Correction" },
-      { displayName: "Levels", matchName: "ADBE Easy Levels2", category: "Color Correction" },
-      { displayName: "Fill", matchName: "ADBE Fill", category: "Generate" },
-      { displayName: "CC Light Sweep", matchName: "CC Light Sweep", category: "Generate" },
-    ];
+    fx = null;
+  }
+  if (!fx || fx.length === undefined) {
+    // No silent curated substitute here. Handing back eight effects that look
+    // like the whole list makes "not installed" indistinguishable from "not
+    // enumerated", and an agent then rules out an effect that is right there.
+    throw new Error(
+      "Cannot read app.effects on this After Effects build, so the installed-effect list is unavailable. " +
+        "Add effects by matchName directly — add_effect fails immediately and clearly on a wrong one. " +
+        "Common matchNames: ADBE Gaussian Blur 2 (Gaussian Blur), ADBE Box Blur2 (Fast Box Blur), " +
+        "ADBE Glo2 (Glow), ADBE Drop Shadow, ADBE CurvesCustom (Curves), ADBE Easy Levels2 (Levels), " +
+        "ADBE Fill, CC Light Sweep."
+    );
+  }
+  var out = [];
+  for (var i = 0; i < fx.length; i++) {
+    out.push({ displayName: fx[i].displayName, matchName: fx[i].matchName, category: fx[i].category });
   }
   return out;
+}
+
+OPS.list_available_effects = noUndo(function (args) {
+  if (!args) args = {};
+  // Only a successful enumeration is cached; a throw leaves the cache empty so
+  // the next call retries rather than repeating a stale failure.
+  if (args.refresh || !__availableEffects) __availableEffects = __enumerateEffects();
+  if (!args.filter) return __availableEffects;
+
+  var q = String(args.filter).toLowerCase();
+  var hits = [];
+  for (var i = 0; i < __availableEffects.length; i++) {
+    var entry = __availableEffects[i];
+    var hay = String(entry.displayName) + " " + String(entry.matchName) + " " + String(entry.category);
+    if (hay.toLowerCase().indexOf(q) !== -1) hits.push(entry);
+  }
+  return hits;
 });
 
 
@@ -775,6 +1174,16 @@ OPS.list_available_effects = noUndo(function (args) {
 
 // text.jsx — text layer styling.
 
+// Shared with create_text_layer, which implements `anchorAlign` as live
+// paragraph justification rather than a one-time anchor offset. One map so the
+// two cannot drift.
+var __JUSTIFICATION = {
+  left: ParagraphJustification.LEFT_JUSTIFY,
+  center: ParagraphJustification.CENTER_JUSTIFY,
+  right: ParagraphJustification.RIGHT_JUSTIFY,
+  full: ParagraphJustification.FULL_JUSTIFY_LASTLINE_LEFT,
+};
+
 OPS.set_text = function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
@@ -790,13 +1199,7 @@ OPS.set_text = function (args) {
   if (args.tracking !== undefined) td.tracking = args.tracking;
   if (args.leading !== undefined) td.leading = args.leading;
   if (args.justification !== undefined) {
-    var jmap = {
-      left: ParagraphJustification.LEFT_JUSTIFY,
-      center: ParagraphJustification.CENTER_JUSTIFY,
-      right: ParagraphJustification.RIGHT_JUSTIFY,
-      full: ParagraphJustification.FULL_JUSTIFY_LASTLINE_LEFT,
-    };
-    if (jmap[args.justification]) td.justification = jmap[args.justification];
+    if (__JUSTIFICATION[args.justification]) td.justification = __JUSTIFICATION[args.justification];
   }
   if (args.applyFill !== undefined) td.applyFill = args.applyFill;
   if (args.applyStroke !== undefined) td.applyStroke = args.applyStroke;
@@ -975,6 +1378,42 @@ OPS.add_shape_content = function (args) {
   }
 
   var node = parent.addProperty(match);
+
+  // Render order. addProperty always appends to the END of the group, and in a
+  // shape layer index 1 renders in FRONT — so an appended node lands at the back
+  // and the first thing added is the thing on top. That is the opposite of the
+  // layer stack, and building back-to-front silently produces a solid slab.
+  //
+  // "back" is therefore what already happened and needs no move. "front" is the
+  // only case that reorders, and moveTo is the only primitive AE offers for it —
+  // see the note in the tool description about nested renders. Do it here, on a
+  // node with nothing in it yet, so a failure costs an empty node and nothing
+  // else, and re-fetch afterwards: a structural change invalidates references
+  // into the group (the same trap that makes a Fill reference go stale when a
+  // Stroke is added beside it).
+  if (args.zOrder === "front" && node.propertyIndex !== 1) {
+    try {
+      node.moveTo(1);
+    } catch (eMove) {
+      try { node.remove(); } catch (eRm) {}
+      throw new Error(
+        "add_shape_content created the '" + type + "' node but could not move it to the front of the " +
+        "render stack: " + eMove.message + ". The node was removed, so nothing changed."
+      );
+    }
+    node = parent.property(1);
+    // Cheap identity check on the re-fetch. If moveTo ever lands the node
+    // somewhere other than index 1, setting properties on whatever is there
+    // would corrupt a node the caller never asked about.
+    if (!node || node.matchName !== match) {
+      throw new Error(
+        "add_shape_content moved the '" + type + "' node towards the front of the render stack but did not " +
+        "find it at index 1 afterwards. No properties were set on it. Read the layer back with get_layer_full " +
+        "before retrying, and add contents front-to-back instead of using zOrder."
+      );
+    }
+  }
+
   var applied = [];
   var failed = [];
 
@@ -1153,6 +1592,27 @@ function __clampDownsample(v) {
   return n > 8 ? 8 : n;
 }
 
+// The long edge we aim a screenshot at. ~1280px is still legible for checking
+// type and layout, and costs roughly 1.2k image tokens instead of the 11k a
+// full-resolution 4K frame costs.
+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.
+// 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);
+  if (!(n > 1)) return 1;
+  return n > 8 ? 8 : n;
+}
+
+function __resolveDownsample(comp, requested) {
+  if (requested === undefined || requested === null) return __autoDownsample(comp);
+  return __clampDownsample(requested);
+}
+
 // saveFrameToPng honours the comp's resolutionFactor, so AE can render the
 // 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
@@ -1176,7 +1636,7 @@ function __saveFrameAt(comp, time, file, factor) {
 OPS.screenshot_frame = noUndo(function (args) {
   var c = getCompById(args.compId);
   var t = (args.time !== undefined && args.time !== null) ? args.time : c.time;
-  var ds = __clampDownsample(args.downsample);
+  var ds = __resolveDownsample(c, args.downsample);
   var path = __tmpPngPath();
   var f = new File(path);
   // saveFrameToPng is async-ish; the panel polls the file's existence/size.
@@ -1201,7 +1661,7 @@ OPS.screenshot_layer = noUndo(function (args) {
     ll.solo = false;
   }
   l.solo = true;
-  var ds = __clampDownsample(args.downsample);
+  var ds = __resolveDownsample(c, args.downsample);
   var path = __tmpPngPath();
   var f = new File(path);
   try {
@@ -1222,6 +1682,399 @@ OPS.screenshot_layer = noUndo(function (args) {
 });
 
 
+// ===== footage.jsx =====
+
+// footage.jsx — import a file into the project, and refuse to hand back an
+// asset that After Effects imported wrongly.
+//
+// Import exists here for one reason: it is the only place a viewBox check has
+// to live. AE's SVG importer fabricates pixel dimensions for an SVG whose
+// viewBox uses a very large coordinate space, and then rasterizes nothing — no
+// error at any stage, a footage item that looks healthy in the project panel,
+// and an empty frame wherever it is placed (issue #33). The agent doing the
+// import is the only thing in the loop that knows an import happened, so a
+// guide can tell it what to compare; a tool can compare it.
+//
+// The check is the one from that report: the aspect ratio the SVG asks for
+// against the aspect ratio AE produced. It needs the file path and the
+// resulting item together, which is exactly and only what an import op has.
+
+var __SVG_ASPECT_TOLERANCE = 0.02; // 2% — comfortably past rounding, far short of the 3x that a broken import produces.
+var __SVG_SNIFF_BYTES = 16384;
+
+function __lowerExt(path) {
+  var dot = String(path).lastIndexOf(".");
+  if (dot < 0) return "";
+  return String(path).substring(dot + 1).toLowerCase();
+}
+
+/** First `max` bytes of a file as text, or null if it cannot be read. */
+function __readHead(file, max) {
+  var text = null;
+  try {
+    file.encoding = "UTF-8";
+    if (!file.open("r")) return null;
+    try { text = file.read(max); } finally { file.close(); }
+  } catch (e) { return null; }
+  return text;
+}
+
+/**
+ * viewBox / width / height off the root <svg> element. Deliberately a regex
+ * rather than a parser: we need four numbers out of the first tag, not a DOM,
+ * and ExtendScript has no XML reader that is worth the failure modes.
+ */
+function __parseSvgViewBox(text) {
+  if (!text) return null;
+  var m = text.match(/\bviewBox\s*=\s*["']([^"']+)["']/);
+  if (!m) return null;
+  var parts = m[1].replace(/,/g, " ").replace(/^\s+|\s+$/g, "").split(/\s+/);
+  if (parts.length < 4) return null;
+  var w = parseFloat(parts[2]);
+  var h = parseFloat(parts[3]);
+  if (!isFinite(w) || !isFinite(h) || w <= 0 || h <= 0) return null;
+  return { minX: parseFloat(parts[0]), minY: parseFloat(parts[1]), width: w, height: h, raw: m[1] };
+}
+
+/**
+ * Compare what the SVG asked for against what AE produced.
+ *
+ * Aspect ratio rather than absolute size on purpose: AE is entitled to pick the
+ * pixel dimensions for a vector file with no width/height, and does so
+ * sensibly for ordinary SVGs. What it is not entitled to do is change the
+ * shape, and in the broken case it does — the report's example asks for
+ * 278050x333334 (0.83) and gets 15906x5654 (2.81).
+ */
+function __validateSvgImport(item, file) {
+  var vb = __parseSvgViewBox(__readHead(file, __SVG_SNIFF_BYTES));
+  if (!vb) return { ok: true, checked: false, reason: "no viewBox on the root <svg> element; nothing to compare against" };
+
+  var w = item.width, h = item.height;
+  if (!(w > 0) || !(h > 0)) {
+    return {
+      ok: false, checked: true, viewBox: vb.raw, itemWidth: w, itemHeight: h,
+      reason: "After Effects imported this SVG with dimensions " + w + "x" + h + "."
+    };
+  }
+
+  var expected = vb.width / vb.height;
+  var actual = w / h;
+  var drift = Math.abs(actual - expected) / expected;
+  var out = {
+    checked: true,
+    viewBox: vb.raw,
+    expectedAspect: Math.round(expected * 10000) / 10000,
+    actualAspect: Math.round(actual * 10000) / 10000,
+    itemWidth: w,
+    itemHeight: h
+  };
+  if (drift <= __SVG_ASPECT_TOLERANCE) { out.ok = true; return out; }
+  out.ok = false;
+  out.reason =
+    "After Effects imported this SVG as " + w + "x" + h + " (aspect " + out.actualAspect + "), but its " +
+    "viewBox \"" + vb.raw + "\" asks for aspect " + out.expectedAspect + ". AE fabricates dimensions for an SVG " +
+    "with a very large viewBox coordinate space and then rasterizes nothing, so this item renders empty " +
+    "wherever it is placed, with no error.";
+  return out;
+}
+
+/** The advice is the same whichever way the item failed, so it is written once. */
+function __brokenSvgAdvice() {
+  return (
+    " Workarounds: for a simple flat SVG, read its path data and rebuild it as a shape layer with " +
+    "set_shape_path, scaling the coordinates down to a sane space (divide by 333.334 for a 1000px " +
+    "version) and setting ADBE Vector Fill Rule to 2 if the SVG says fill-rule=\"evenodd\" — that is " +
+    "pixel-accurate. For a complex one, normalise the viewBox to a small range or rasterize to PNG " +
+    "outside AE, then import that. Pass force:true to keep the item anyway."
+  );
+}
+
+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 opts = new ImportOptions(file);
+  if (args.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);
+
+  if (typeof args.name === "string" && args.name.length > 0) item.name = args.name;
+
+  var result = {
+    itemId: item.id,
+    name: item.name,
+    path: path,
+    width: item.width,
+    height: item.height,
+    duration: item.duration,
+    frameRate: (item.frameRate !== undefined) ? item.frameRate : null,
+    isStill: !!item.footageMissing ? null : (item.duration === 0),
+    footageMissing: !!item.footageMissing
+  };
+
+  if (__lowerExt(path) !== "svg") return result;
+
+  var v = __validateSvgImport(item, file);
+  result.validation = v;
+  if (v.ok) return result;
+
+  // A silently empty asset is the failure this whole op exists to prevent, so
+  // it is not something to return with a warning attached and hope is read.
+  // Remove what we created and say why — the same all-or-nothing stance
+  // add_shape_content takes when a key will not resolve.
+  if (args.force === true) {
+    result.warning = v.reason + __brokenSvgAdvice();
+    return result;
+  }
+  var name = item.name;
+  try { item.remove(); result.removed = true; }
+  catch (e) { result.removed = false; }
+  throw new Error(
+    v.reason + " The item (\"" + name + "\") has been removed from the project so nothing places it by mistake." +
+    __brokenSvgAdvice()
+  );
+};
+
+OPS.create_footage_layer = function (args) {
+  var comp = getCompById(args.compId);
+  var item = app.project.itemByID(args.itemId);
+  if (!item) throw new Error("No project item with id " + args.itemId);
+  if (item instanceof FolderItem) throw new Error("Item " + args.itemId + " (\"" + item.name + "\") is a folder, not footage");
+
+  var layer = comp.layers.add(item);
+  if (typeof args.name === "string" && args.name.length > 0) layer.name = args.name;
+  if (args.position !== undefined && args.position !== null) {
+    layer.property("Transform").property("Position").setValue(args.position);
+  }
+  if (args.startTime !== undefined && args.startTime !== null) layer.startTime = args.startTime;
+
+  return {
+    layerId: layer.id,
+    index: layer.index,
+    name: layer.name,
+    compId: comp.id,
+    itemId: item.id,
+    inPoint: layer.inPoint,
+    outPoint: layer.outPoint
+  };
+};
+
+
+// ===== mogrt.jsx =====
+
+// mogrt.jsx — export a comp as a Motion Graphics template without the three
+// modal dialogs that make a scripted export look like a hung bridge (issue #23).
+//
+// Measured against AE 26.3 rather than assumed, because the mechanism was
+// filed as untested:
+//
+//   * WITHOUT app.beginSuppressDialogs(), a comp using a non-Adobe font raises
+//     "The following 1 fonts were not synced from Adobe … Click OK to continue"
+//     and the export blocks. ExtendScript is single-threaded, so the panel
+//     cannot service its socket while that dialog is up: the call sat past 60s
+//     and no file was written until someone clicked OK.
+//   * WITH it, the same export returned in a couple of seconds and produced a
+//     valid .mogrt. So suppression is the thing that fixes it, and it is on by
+//     default here.
+//
+// The other two dialogs are handled by construction. `app.project.save()`
+// immediately before the export removes the "project needs to be saved" prompt
+// deterministically — and the export itself dirties the project, so saving once
+// at the start of a session is not enough, it has to be per export. The
+// "undo group mismatch" warning is a consequence of running a non-undoable
+// export inside dispatch()'s undo group, so this op opts out of the group
+// entirely via noUndo.
+//
+// Two traps that are not in the report, both found by measurement here:
+//
+//   * The output filename comes from `comp.motionGraphicsTemplateName`, NOT
+//     from the comp name, and it defaults to the literal "Untitled" for a
+//     template assembled by script. Left alone, every export from every comp in
+//     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.
+
+/** Distinct fonts used by the text layers in a comp, following nested comps. */
+function __collectFonts(comp, depth, seenComps, fonts) {
+  if (depth > 4) return;
+  for (var c = 0; c < seenComps.length; c++) { if (seenComps[c] === comp.id) return; }
+  seenComps.push(comp.id);
+
+  for (var i = 1; i <= comp.numLayers; i++) {
+    var layer = comp.layer(i);
+    try {
+      if (layer instanceof TextLayer) {
+        var doc = layer.property("Source Text").value;
+        var f = doc.font;
+        if (f) {
+          var have = false;
+          for (var k = 0; k < fonts.length; k++) { if (fonts[k] === f) { have = true; break; } }
+          if (!have) fonts.push(f);
+        }
+      } else if (layer.source && (layer.source instanceof CompItem)) {
+        __collectFonts(layer.source, depth + 1, seenComps, fonts);
+      }
+    } catch (e) {}
+  }
+}
+
+function __joinPath(dir, leaf) {
+  var d = String(dir);
+  if (d.charAt(d.length - 1) === "/" || d.charAt(d.length - 1) === "\\") d = d.substring(0, d.length - 1);
+  return d + "/" + leaf;
+}
+
+/** AE writes <motionGraphicsTemplateName>.mogrt into the folder it is given. */
+function __mogrtFileName(name) {
+  return String(name) + ".mogrt";
+}
+
+OPS.export_mogrt = noUndo(function (args) {
+  var comp = getCompById(args.compId);
+
+  // The save prompt is the first dialog, and the only way to remove it without
+  // guessing is to have somewhere to save to. A project that has never been
+  // saved has no file and no folder — the user has to do that once by hand,
+  // which is worth saying rather than raising a dialog they did not expect.
+  if (!app.project.file) {
+    throw new Error(
+      "This After Effects project has never been saved, so the export cannot save it first and " +
+      "After Effects would raise a modal 'save the project?' dialog that freezes this connection " +
+      "until someone clicks it. Ask the user to save the project once, 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) {}
+  if (!templateName) {
+    // 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;
+  }
+
+  var destDir = (typeof args.destDir === "string" && args.destDir.length > 0)
+    ? args.destDir
+    : app.project.file.parent.fsName;
+  var folder = new Folder(destDir);
+  var createdDir = false;
+  if (!folder.exists) {
+    if (!folder.create()) throw new Error("Could not create the destination folder " + destDir);
+    createdDir = true;
+  }
+
+  var outPath = __joinPath(folder.fsName, __mogrtFileName(templateName));
+  var outFile = new File(outPath);
+  var existed = outFile.exists;
+  if (existed && args.overwrite !== true) {
+    throw new Error(
+      "A template already exists at " + outPath + ". Pass overwrite: true to replace it, or a " +
+      "different `name`."
+    );
+  }
+
+  var fonts = [];
+  try { __collectFonts(comp, 0, [], fonts); } catch (eF) {}
+
+  if (templateName !== previousTemplateName) comp.motionGraphicsTemplateName = templateName;
+
+  // Saving is what removes the save prompt, and it has to happen per export:
+  // exporting dirties the project, so a project saved before the first export
+  // is dirty again before the second.
+  app.project.save();
+
+  // Everything the result needs, read *before* the export. See below.
+  var compId = comp.id;
+  var compName = comp.name;
+
+  var suppress = args.suppressDialogs !== false;
+  var suppressed = false;
+  var exported;
+  try {
+    if (suppress) { app.beginSuppressDialogs(); suppressed = true; }
+    exported = comp.exportAsMotionGraphicsTemplate(true, folder.fsName);
+  } finally {
+    // Unconditional: leaving dialogs suppressed would silence every warning in
+    // the rest of the user's session, including ones they need to see.
+    if (suppressed) { try { app.endSuppressDialogs(false); } catch (eS) {} }
+  }
+
+  // exportAsMotionGraphicsTemplate invalidates every object reference held
+  // across it — the CompItem, and `app.project` itself. Measured, not assumed:
+  // after a successful export, `comp.name` and a captured `app.project.file`
+  // both throw "Object is invalid", while a fresh `app.project.itemByID(id)`
+  // returns a working comp. Reading through a stale handle here would report a
+  // failure for an export that had already written a valid file, which is the
+  // same lie as swallowing an error, just pointing the other way.
+  comp = getCompById(compId);
+
+  // exportAsMotionGraphicsTemplate returns a boolean, and a false is the whole
+  // failure report AE offers. Check the file too — a truthy return with nothing
+  // on disk is exactly the kind of success-for-work-that-did-not-happen this
+  // 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 bytes = written.length;
+  if (!(bytes > 0)) throw new Error("The exported template at " + outPath + " is empty (0 bytes).");
+
+  var result = {
+    ok: true,
+    path: outPath,
+    bytes: bytes,
+    name: templateName,
+    compId: compId,
+    compName: compName,
+    replaced: existed,
+    createdDir: createdDir,
+    projectSaved: app.project.file.fsName,
+    dialogsSuppressed: suppress,
+    controllerCount: comp.motionGraphicsTemplateControllerCount,
+    fonts: fonts
+  };
+  if (!suppress) {
+    result.warning =
+      "Dialogs were not suppressed. If this call took a long time, a modal font warning was waiting " +
+      "in After Effects.";
+  }
+
+  // The thumbnail. AE has no scriptable poster time — CompItem.posterTime does
+  // not exist — and the export ignores comp.time, so thumb.png inside the
+  // .mogrt is whatever AE decided, usually black. Render the requested frame
+  // here and let the panel put it into the archive: ExtendScript can write a
+  // PNG but cannot rewrite a zip, and the panel is already the layer that
+  // post-processes files AE has just written.
+  if (args.posterTime !== undefined && args.posterTime !== null) {
+    var t = args.posterTime;
+    if (t < 0 || t > comp.duration) {
+      throw new Error(
+        "posterTime " + t + " is outside the comp's 0.." + comp.duration + "s. The template was still " +
+        "exported to " + outPath + " with After Effects' own thumbnail."
+      );
+    }
+    var posterPath = __tmpPngPath();
+    __saveFrameAt(comp, t, new File(posterPath), 1);
+    result.posterPngPath = posterPath;
+    result.posterTime = t;
+  }
+
+  return result;
+});
+
+
 // ===== style.jsx =====
 
 // style.jsx — the project's house style, read from and written to a plain
@@ -1440,7 +2293,46 @@ OPS._get_job = noUndo(function (args) {
 
 // explore.jsx — rich one-shot inspection. The whole reason this MCP exists.
 
-function __serializeProperty(p, deep) {
+// Which keyframes survive a cap, or null when none need to go. Keeping the
+// first few and the last few rather than a prefix means the shape of the
+// animation — where it starts, where it ends — is still readable.
+function __keyframeWindow(total, max) {
+  if (!(max > 0) || total <= max) return null;
+  var head = Math.ceil(max / 2);
+  return { head: head, tail: max - head, total: total, omitted: total - max };
+}
+
+// Truncation is never silent: an agent that cannot see what was dropped will
+// read a partial answer as the whole one.
+function __truncationNote(w) {
+  return "first " + w.head + " and last " + w.tail + " of " + w.total + " keyframes; " +
+    w.omitted + " omitted — raise maxKeyframes, or read them all with get_keyframes";
+}
+
+function __serializeKeyframe(p, k) {
+  var entry = { index: k, time: p.keyTime(k), value: p.keyValue(k) };
+  try {
+    entry["in"] = String(p.keyInInterpolationType(k));
+    entry["out"] = String(p.keyOutInterpolationType(k));
+  } catch (e1) {}
+  try {
+    var inE = p.keyInTemporalEase(k);
+    var outE = p.keyOutTemporalEase(k);
+    entry.easeIn = { influence: inE[0].influence, speed: inE[0].speed };
+    entry.easeOut = { influence: outE[0].influence, speed: outE[0].speed };
+  } catch (e2) {}
+  if (p.isSpatial) {
+    try {
+      entry.inTangent = p.keyInSpatialTangent(k);
+      entry.outTangent = p.keyOutSpatialTangent(k);
+    } catch (e3) {}
+  }
+  return entry;
+}
+
+// `opts.maxKeyframes` bounds the response; 0 or absent means every keyframe,
+// which is what every caller written before the cap existed gets.
+function __serializeProperty(p, opts) {
   var out = {
     name: p.name,
     matchName: p.matchName,
@@ -1451,49 +2343,66 @@ function __serializeProperty(p, deep) {
   try { out.value = p.value; } catch (e) {}
   if (p.canSetExpression && p.expression) out.expression = p.expression;
   if (p.numKeys > 0) {
+    var total = p.numKeys;
+    var w = __keyframeWindow(total, (opts && opts.maxKeyframes) ? opts.maxKeyframes : 0);
     out.keyframes = [];
-    for (var k = 1; k <= p.numKeys; k++) {
-      var entry = { index: k, time: p.keyTime(k), value: p.keyValue(k) };
-      try {
-        entry["in"] = String(p.keyInInterpolationType(k));
-        entry["out"] = String(p.keyOutInterpolationType(k));
-      } catch (e1) {}
-      try {
-        var inE = p.keyInTemporalEase(k);
-        var outE = p.keyOutTemporalEase(k);
-        entry.easeIn = { influence: inE[0].influence, speed: inE[0].speed };
-        entry.easeOut = { influence: outE[0].influence, speed: outE[0].speed };
-      } catch (e2) {}
-      if (p.isSpatial) {
-        try {
-          entry.inTangent = p.keyInSpatialTangent(k);
-          entry.outTangent = p.keyOutSpatialTangent(k);
-        } catch (e3) {}
-      }
-      out.keyframes.push(entry);
+    for (var k = 1; k <= total; k++) {
+      if (w && k > w.head && k <= total - w.tail) continue;
+      out.keyframes.push(__serializeKeyframe(p, k));
+    }
+    if (w) {
+      out.keyframeCount = w.total;
+      out.keyframesOmitted = w.omitted;
+      out.keyframesTruncated = __truncationNote(w);
     }
   }
   return out;
 }
 
-function __serializeTransformGroup(tg) {
+function __serializeTransformGroup(tg, opts) {
   var out = {};
   for (var i = 1; i <= tg.numProperties; i++) {
     var p = tg.property(i);
-    out[p.name] = __serializeProperty(p);
+    out[p.name] = __serializeProperty(p, opts);
   }
   return out;
 }
 
-function __serializeEffects(layer) {
+// The cap is applied after the fact rather than inside __serializeEffect,
+// which effects.jsx also uses for list_effects and add_effect — those return
+// one effect and have no size problem to solve.
+function __capEffectKeyframes(effects, max) {
+  if (!(max > 0)) return effects;
+  for (var i = 0; i < effects.length; i++) {
+    var params = effects[i].params;
+    for (var j = 0; j < params.length; j++) {
+      var keys = params[j].keyframes;
+      if (!keys) continue;
+      var w = __keyframeWindow(keys.length, max);
+      if (!w) continue;
+      var kept = [];
+      for (var k = 0; k < w.total; k++) {
+        if (k >= w.head && k < w.total - w.tail) continue;
+        kept.push(keys[k]);
+      }
+      params[j].keyframes = kept;
+      params[j].keyframeCount = w.total;
+      params[j].keyframesOmitted = w.omitted;
+      params[j].keyframesTruncated = __truncationNote(w);
+    }
+  }
+  return effects;
+}
+
+function __serializeEffects(layer, opts) {
   var fx = layer.property("Effects");
   if (!fx || fx.numProperties === 0) return [];
   var arr = [];
   for (var i = 1; i <= fx.numProperties; i++) arr.push(__serializeEffect(fx.property(i)));
-  return arr;
+  return __capEffectKeyframes(arr, (opts && opts.maxKeyframes) ? opts.maxKeyframes : 0);
 }
 
-function __serializeMasks(layer) {
+function __serializeMasks(layer, opts) {
   var masks = layer.property("Masks");
   if (!masks || masks.numProperties === 0) return [];
   var out = [];
@@ -1505,10 +2414,10 @@ function __serializeMasks(layer) {
       mode: String(m.maskMode),
       inverted: m.inverted,
     };
-    try { entry.shape = __serializeProperty(m.property("ADBE Mask Shape")); } catch (e1) {}
-    try { entry.opacity = __serializeProperty(m.property("ADBE Mask Opacity")); } catch (e2) {}
-    try { entry.expansion = __serializeProperty(m.property("ADBE Mask Offset")); } catch (e3) {}
-    try { entry.feather = __serializeProperty(m.property("ADBE Mask Feather")); } catch (e4) {}
+    try { entry.shape = __serializeProperty(m.property("ADBE Mask Shape"), opts); } catch (e1) {}
+    try { entry.opacity = __serializeProperty(m.property("ADBE Mask Opacity"), opts); } catch (e2) {}
+    try { entry.expansion = __serializeProperty(m.property("ADBE Mask Offset"), opts); } catch (e3) {}
+    try { entry.feather = __serializeProperty(m.property("ADBE Mask Feather"), opts); } catch (e4) {}
     out.push(entry);
   }
   return out;
@@ -1563,6 +2472,9 @@ function __serializeShapeContents(group, depth) {
     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);
+      // 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;
     } else {
       try { entry.value = p.value; } catch (e) {}
     }
@@ -1574,6 +2486,11 @@ function __serializeShapeContents(group, depth) {
 OPS.get_layer_full = noUndo(function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
+  // `include` bounds the response by section, `maxKeyframes` and `shapeDepth`
+  // bound the two things that make a single layer weigh 250KB. All three are
+  // absent by default, and absent means "everything", exactly as before.
+  var want = (args && args.include) ? args.include : null;
+  var opts = { maxKeyframes: (args && args.maxKeyframes > 0) ? args.maxKeyframes : 0 };
   var out = {
     id: l.id,
     index: l.index,
@@ -1592,44 +2509,69 @@ OPS.get_layer_full = noUndo(function (args) {
     preserveTransparency: l.preserveTransparency,
     parent: l.parent ? { layerId: l.parent.id, name: l.parent.name } : null,
     sourceType: __layerKind(l),
-    transform: __serializeTransformGroup(l.property("Transform")),
-    effects: __serializeEffects(l),
-    masks: __serializeMasks(l),
-    markers: __serializeMarkers(l),
   };
+  if (__wantsSection(want, "transform")) out.transform = __serializeTransformGroup(l.property("Transform"), opts);
+  if (__wantsSection(want, "effects")) out.effects = __serializeEffects(l, opts);
+  if (__wantsSection(want, "masks")) out.masks = __serializeMasks(l, opts);
+  if (__wantsSection(want, "markers")) out.markers = __serializeMarkers(l);
   // Visual bounds at the comp's current time — cheap to fetch and removes a
   // class of "I need to screenshot to know where this renders" round-trips.
   // Coordinates are in the layer's local space (origin at the Anchor Point).
-  try {
-    var __rect = l.sourceRectAtTime(c.time, false);
-    out.sourceRect = { left: __rect.left, top: __rect.top, width: __rect.width, height: __rect.height, time: c.time };
-  } catch (__e) {}
-  if (l instanceof TextLayer) out.text = __serializeText(l);
-  if (l instanceof ShapeLayer) {
-    try { out.shape = { contents: __serializeShapeContents(l.property("Contents"), 4) }; }
+  if (__wantsSection(want, "bounds")) {
+    try {
+      var __rect = l.sourceRectAtTime(c.time, false);
+      out.sourceRect = { left: __rect.left, top: __rect.top, width: __rect.width, height: __rect.height, time: c.time };
+    } catch (__e) {}
+  }
+  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) {}
   }
-  if (l.source && l.source instanceof CompItem) {
-    out.precomp = { compId: l.source.id, compName: l.source.name };
-    if (args.includeChildren) {
-      out.children = [];
-      for (var i = 1; i <= l.source.numLayers; i++) out.children.push(__layerSummary(l.source.layer(i)));
+  if (__wantsSection(want, "source")) {
+    if (l.source && l.source instanceof CompItem) {
+      out.precomp = { compId: l.source.id, compName: l.source.name };
+      if (args.includeChildren) {
+        out.children = [];
+        for (var i = 1; i <= l.source.numLayers; i++) out.children.push(__layerSummary(l.source.layer(i)));
+      }
+    } else if (l.source && l.source instanceof FootageItem) {
+      var src = l.source;
+      out.footage = {
+        itemId: src.id,
+        name: src.name,
+        hasAlpha: src.hasAlpha,
+        duration: src.duration,
+        width: src.width,
+        height: src.height,
+      };
+      try { if (src.file) out.footage.path = src.file.fsName; } catch (e2) {}
     }
-  } else if (l.source && l.source instanceof FootageItem) {
-    var src = l.source;
-    out.footage = {
-      itemId: src.id,
-      name: src.name,
-      hasAlpha: src.hasAlpha,
-      duration: src.duration,
-      width: src.width,
-      height: src.height,
-    };
-    try { if (src.file) out.footage.path = src.file.fsName; } catch (e2) {}
   }
+  // Echo the scoping back, so a bounded answer is never read as a full one.
+  if (want) out.included = want;
   return out;
 });
 
+// Project item kind. An if/else chain, not a chained ternary: this build of
+// ExtendScript parses `a ? x : b ? y : z` left-associatively, so the first
+// truthy branch became the next condition and every item fell through to
+// "folder" (issues #21/#22). tests/unit/jsx-ternary.mjs keeps it that way.
+// "solid" mirrors __layerKind in layers.jsx so an item and a layer that share a
+// source describe it with the same word.
+function __itemKind(it) {
+  if (it instanceof CompItem) return "comp";
+  if (it instanceof FolderItem) return "folder";
+  if (it instanceof FootageItem) {
+    try {
+      if (it.mainSource && it.mainSource.color !== undefined) return "solid";
+    } catch (e) {}
+    return "footage";
+  }
+  return "unknown";
+}
+
 OPS.get_project_summary = noUndo(function (args) {
   var p = app.project;
   var items = [];
@@ -1638,7 +2580,7 @@ OPS.get_project_summary = noUndo(function (args) {
     items.push({
       id: it.id,
       name: it.name,
-      type: (it instanceof CompItem) ? "comp" : (it instanceof FootageItem) ? "footage" : (it instanceof FolderItem) ? "folder" : "unknown",
+      type: __itemKind(it),
     });
   }
   return {
@@ -1690,29 +2632,117 @@ OPS.find_layers = noUndo(function (args) {
 
 // raw.jsx — escape hatch. Eval arbitrary ExtendScript and return the value.
 
-OPS.run_jsx = function (args) {
-  var code = args.code || "";
-  // We wrap in a function so `return` works.
-  var wrapper = "(function(){ " + code + " })()";
-  var result;
-  try { result = eval(wrapper); }
-  catch (e) { throw e; }
-  // ExtendScript objects can be unserializable; coerce sparingly.
-  if (typeof result === "undefined") return null;
-  if (result === null) return null;
-  var t = typeof result;
-  if (t === "number" || t === "string" || t === "boolean") return result;
-  if (result instanceof Array) return result;
-  // Object: pull plain own props
+// ---------- Result serialization ----------
+// The returned value has to survive JSON.stringify in the panel. Anything that
+// cannot be represented is replaced *in place* by a short marker string, never
+// dropped: the old coercion kept scalars only, so {done:[...], skipped:[...]}
+// came back as {} — indistinguishable from "the script did nothing" while its
+// mutations had already landed, which invites re-running a mutating script
+// (issue #31). An empty result must mean the script returned nothing.
+//
+// The walk is deliberately opt-in: only arrays and plain objects are recursed
+// into. Live AE objects (Layer, Property, CompItem …) have huge and partly
+// throwing property graphs, so they degrade to "[AVLayer \"name\"]" rather than
+// being walked.
+
+var __RJ_MAX_DEPTH = 12;
+var __RJ_MAX_NODES = 50000;
+
+function __rjIsPlainObject(v) {
+  try { if (v.constructor === Object) return true; } catch (e) {}
+  try { if (v.reflect && v.reflect.name === "Object") return true; } catch (e2) {}
+  return false;
+}
+
+function __rjTypeName(v) {
+  var n = null;
+  try { if (v.reflect && v.reflect.name) n = String(v.reflect.name); } catch (e) {}
+  if (!n) {
+    try {
+      n = String(v);
+      if (n.substring(0, 8) === "[object ") n = n.substring(8, n.length - 1);
+    } catch (e2) { n = "object"; }
+  }
+  if (n.length > 48) n = n.substring(0, 48);
+  return n;
+}
+
+// Short, identifiable stand-in for a value we refuse to walk. The name and id
+// are worth the two guarded reads: they are what turns "something was here"
+// into a handle the caller can pass to get_comp or get_layer_full.
+function __rjMarker(v) {
+  var extra = "";
+  try {
+    if (typeof v.name === "string" && v.name.length > 0 && v.name.length < 64) extra = ' "' + v.name + '"';
+  } catch (e) {}
+  try {
+    if (typeof v.id === "number") extra += " #" + v.id;
+  } catch (e2) {}
+  return "[" + __rjTypeName(v) + extra + "]";
+}
+
+// `stack` holds the ancestors currently being walked, so a repeated reference
+// that is not a cycle still serializes. ES3 has no Set — a linear scan over a
+// depth-limited stack is cheap enough.
+function __rjSerialize(v, depth, stack, budget) {
+  if (v === null) return null;
+  var t = typeof v;
+  if (t === "undefined") return "[undefined]";
+  if (t === "boolean" || t === "string") return v;
+  if (t === "number") {
+    if (isNaN(v)) return "[NaN]";
+    if (!isFinite(v)) return v > 0 ? "[Infinity]" : "[-Infinity]";
+    return v;
+  }
+  if (t === "function") return "[function]";
+  if (t !== "object") return "[" + t + "]";
+  if (v instanceof Date) return String(v);
+
+  budget.n += 1;
+  if (budget.n > __RJ_MAX_NODES) return "[truncated: node limit]";
+
+  var isArray = (v instanceof Array);
+  if (!isArray && !__rjIsPlainObject(v)) return __rjMarker(v);
+
+  for (var s = 0; s < stack.length; s++) { if (stack[s] === v) return "[circular]"; }
+  if (depth >= __RJ_MAX_DEPTH) return "[max depth]";
+
+  stack.push(v);
+  var out;
   try {
-    var out = {};
-    for (var k in result) {
-      if (result.hasOwnProperty(k)) {
-        var v = result[k];
-        var vt = typeof v;
-        if (v === null || vt === "number" || vt === "string" || vt === "boolean") out[k] = v;
+    if (isArray) {
+      out = [];
+      for (var i = 0; i < v.length; i++) out.push(__rjSerialize(v[i], depth + 1, stack, budget));
+    } else {
+      out = {};
+      for (var k in v) {
+        if (!v.hasOwnProperty(k)) continue;
+        var val;
+        try { val = v[k]; }
+        catch (eg) { out[k] = "[threw: " + (eg && eg.message ? eg.message : String(eg)) + "]"; continue; }
+        out[k] = __rjSerialize(val, depth + 1, stack, budget);
       }
     }
-    return out;
-  } catch (e2) { return String(result); }
-};
+  } finally {
+    stack.pop();
+  }
+  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 });
+}
+
+// undoGroup:false is a per-call opt-out, read by dispatch() through the
+// predicate form of __meta.noUndo. It exists because AE refuses copyToComp for
+// a layer with a parent or a linked expression while an undo group is open,
+// 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));
+});