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

package/panel/jsx/bundle.jsx

@@ -295,10 +295,68 @@ OPS.set_comp = function (args) {
   return __compSummary(c);
 };
 
+// A solid layer's source is a FootageItem in the project's Solids folder, and
+// removing the comp removes the layer, not the item (issue #83). The solids
+// this comp used are collected from ITS OWN layers before the removal and
+// nothing else — deleting comp A must never reach a solid that only some other
+// comp uses — and after it, `usedIn` decides: an item some other comp still
+// places is kept and reported with the comps using it. The helpers live in
+// footage.jsx beside purge_unused_footage, the project-wide sweep.
 OPS.delete_comp = function (args) {
   var c = getCompById(args.compId);
+  var compId = c.id;
+  var compName = c.name;
+  var purge = (args.purgeUnusedSolids === true);
+
+  var solids = __solidItemsOf(c);
+
   c.remove();
-  return { ok: true };
+
+  var out = { ok: true, compId: compId, name: compName };
+  var kept = [];
+  var toRemove = [];
+  var gone = [];
+  for (var i = 0; i < solids.length; i++) {
+    // Re-fetched by id after the removal rather than held across it — the
+    // handle staleness this repo has measured elsewhere is not worth risking
+    // for one lookup per solid.
+    var item = app.project.itemByID(solids[i].id);
+    if (!item) { gone.push(solids[i]); continue; }
+    var uses = __usedInList(item);
+    if (uses.length > 0) {
+      kept.push({ id: item.id, name: item.name, usedIn: uses });
+      continue;
+    }
+    toRemove.push({ item: item, id: item.id, name: item.name, kind: "solid" });
+  }
+  if (gone.length > 0) out.solidsAlreadyGone = gone;
+
+  if (!purge) {
+    out.unusedSolidsLeft = toRemove.length;
+    if (toRemove.length > 0) {
+      out.note = toRemove.length + " solid item(s) this comp used are now used by nothing and remain in the project's Solids folder. " +
+        "Pass purgeUnusedSolids:true to remove them with the comp, or purge_unused_footage to sweep the whole project.";
+    }
+    return out;
+  }
+
+  var r = __removeItems(toRemove);
+  out.removedSolids = r.removed;
+  out.keptSolids = kept;
+  if (r.failed) {
+    var msg = "delete_comp removed comp \"" + compName + "\" (id " + compId + "), then failed purging its solids at \"" +
+      r.failed.name + "\" (id " + r.failed.id + "): " + r.error + ".";
+    if (r.removed.length > 0) msg += " Removed before it: " + __nameList(r.removed, 20) + ".";
+    else msg += " No solid had been removed yet.";
+    if (r.notAttempted.length > 0) msg += " Not attempted: " + __nameList(r.notAttempted, 20) + ".";
+    msg += " The comp is gone, so do not call delete_comp for it again. One Undo in After Effects restores the comp and " +
+      "these solids together; purge_unused_footage removes whatever is still left.";
+    throw new Error(msg);
+  }
+  if (kept.length > 0) {
+    out.note = kept.length + " solid item(s) were kept because another comp still uses them; see keptSolids.usedIn.";
+  }
+  return out;
 };
 
 // ---------------------------------------------------------------------------
@@ -377,20 +435,24 @@ function __dupRepoint(comp, opts, depth) {
   }
 }
 
+// A `folderId` argument resolved to a FolderItem, or a thrown error naming the
+// id and what it actually is. Shared by duplicate_comp and purge_unused_footage.
+function __folderArg(id) {
+  var f = app.project.itemByID(id);
+  if (!f) throw new Error("No project item with id " + id + " to use as folderId");
+  if (!(f instanceof FolderItem)) {
+    throw new Error(
+      "folderId " + id + ' ("' + f.name + '") is a ' + __itemKind(f) +
+      ", not a project folder. Pass the id of a folder from get_project_summary, or omit folderId."
+    );
+  }
+  return f;
+}
+
 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;
-  }
+  if (args.folderId !== undefined && args.folderId !== null) folder = __folderArg(args.folderId);
 
   var opts = { seen: {}, created: [], repointed: 0, nameSuffix: null };
   if (args.nameSuffix) opts.nameSuffix = args.nameSuffix;
@@ -553,15 +615,33 @@ OPS.create_text_layer = function (args) {
   var align = args.anchorAlign === undefined ? "left" : args.anchorAlign;
   var wantJustify = align !== "none" && __JUSTIFICATION[align] !== undefined;
   var wantTracking = args.tracking !== undefined || align !== "none";
+  var verified = null;
   if (args.font || args.size || args.color || wantJustify || wantTracking) {
     var srcText = l.property("Source Text");
     var td = srcText.value;
+    // The same TextDocument round trip set_text does, so the same read-back
+    // (issue #93 / #94, see __verifyJustification in text.jsx): the requested
+    // justification if there is one, otherwise whatever addText() gave the
+    // layer — 'none' promised to leave it alone, and that is checked too.
+    var justificationWanted = wantJustify ? __JUSTIFICATION[align] : td.justification;
     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];
+    if (wantJustify) td.justification = justificationWanted;
     srcText.setValue(td);
+    try {
+      verified = __verifyJustification(srcText, justificationWanted);
+    } catch (e) {
+      // A throw here would leave a layer the caller has no id for, and the
+      // natural next move — call again — makes two. Same rule as
+      // add_shape_content: take the node back, then say so. The message is
+      // amended on the same Error object so nothing about it is lost.
+      try { l.remove(); } catch (e2) {}
+      e.message = String(e.message) + " The new layer was removed, so nothing was created; " +
+        "create it with anchorAlign:\"none\" and set the alignment afterwards with set_text.";
+      throw e;
+    }
   }
   if (align !== "none") {
     l.property("Transform").property("Anchor Point").setValue([0, 0, 0]);
@@ -570,7 +650,12 @@ OPS.create_text_layer = function (args) {
     var p = args.position;
     l.property("Transform").property("Position").setValue(p.length === 3 ? p : [p[0], p[1]]);
   }
-  return __layerSummary(l);
+  var out = __layerSummary(l);
+  if (verified) {
+    out.justification = __justificationName(verified.justification);
+    out.justificationReasserted = verified.reasserted;
+  }
+  return out;
 };
 
 OPS.create_solid_layer = function (args) {
@@ -1973,11 +2058,54 @@ OPS.set_spatial_tangents = function (args) {
 
 // expressions.jsx — get/set/toggle/clear expressions on any property.
 
+// After Effects reports a broken expression on `Property.expressionError` and
+// nowhere a script can otherwise see: assigning `.expression` succeeds whatever
+// the text says, and the failure is a warning banner in the UI (issue #97).
+// The field is filled in when the expression is *evaluated*, which a bare
+// assignment does not necessarily do — so the value is read first, inside a
+// try, purely to force one evaluation. Whether AE would populate the field
+// without that nudge cannot be settled offline; forcing it costs one evaluation
+// and makes the answer independent of the question. `.value` throws on a
+// property that has none (a group), which is also not an expression error.
+function __expressionError(prop) {
+  try { var forced = prop.value; } catch (e) {}
+  var err = "";
+  try { err = prop.expressionError; } catch (e2) { err = ""; }
+  return err ? String(err) : "";
+}
+
+function __propertyPathLabel(path) {
+  var parts = [];
+  for (var i = 0; i < path.length; i++) parts.push(String(path[i]));
+  return parts.join(" > ");
+}
+
+// Throws if the expression on `prop` does not evaluate, naming the property,
+// AE's own message and both ways forward. The expression stays written — the
+// message says so — because nothing here rolls back and a caller fixing a
+// typo wants the property it was aimed at, not a cleared one.
+function __assertExpressionEvaluates(prop, path, verb) {
+  var err = __expressionError(prop);
+  if (!err) return;
+  var enabledNow;
+  try { enabledNow = !!prop.expressionEnabled; } catch (e) { enabledNow = null; }
+  throw new Error(
+    "Expression on " + __propertyPathLabel(path) + " was " + verb +
+    " but After Effects cannot evaluate it: " + err +
+    (enabledNow === false ? " (After Effects has disabled it.)" : "") +
+    " Fix the expression and call set_expression again, or clear_expression to remove it."
+  );
+}
+
 OPS.get_expression = noUndo(function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
   var prop = walkProperty(l, args.propertyPath);
-  return { expression: prop.expression || "", enabled: !!prop.expressionEnabled };
+  return {
+    expression: prop.expression || "",
+    enabled: !!prop.expressionEnabled,
+    expressionError: __expressionError(prop),
+  };
 });
 
 OPS.set_expression = function (args) {
@@ -1986,6 +2114,7 @@ OPS.set_expression = function (args) {
   var prop = walkProperty(l, args.propertyPath);
   prop.expression = args.expression || "";
   prop.expressionEnabled = true;
+  __assertExpressionEvaluates(prop, args.propertyPath, "written");
   return { ok: true };
 };
 
@@ -1994,6 +2123,9 @@ OPS.toggle_expression = function (args) {
   var l = getLayerById(c, args.layerId);
   var prop = walkProperty(l, args.propertyPath);
   prop.expressionEnabled = !!args.enabled;
+  // Disabling cannot fail this way; enabling can surface an error that has
+  // been sitting on the property since it was disabled.
+  if (args.enabled) __assertExpressionEvaluates(prop, args.propertyPath, "enabled");
   return { ok: true };
 };
 
@@ -2147,12 +2279,63 @@ var __JUSTIFICATION = {
   full: ParagraphJustification.FULL_JUSTIFY_LASTLINE_LEFT,
 };
 
+// The name for an enum value, for results and errors. AE has more FULL_JUSTIFY
+// variants than the map offers, so a value the map does not know comes back as
+// its number rather than as the nearest name.
+function __justificationName(v) {
+  for (var k in __JUSTIFICATION) {
+    if (__JUSTIFICATION.hasOwnProperty(k) && __JUSTIFICATION[k] === v) return k;
+  }
+  return String(v);
+}
+
+// Issue #93: on AE 26.3 the TextDocument round trip — read `.value`, change
+// `.text`, `setValue()` — has come back with justification reset to CENTER
+// even though the document that went in still said LEFT; issue #94 reports the
+// setter storing RIGHT when handed CENTER from a script. Nothing raises in
+// either case and the mechanism is unknown, so the only guard that can be built
+// blind is the one this repo asks for anyway: read the property back and
+// compare with what should be there. A second write of the justification alone
+// has been seen to land (`set_text({justification})` on its own always did), so
+// one re-assert is tried before giving up. If that also disagrees, the caller
+// is told what was expected and what the layer actually shows — a text layer
+// that silently re-centres is the failure this codebase refuses everywhere.
+//
+// `expected` is an enum value: the requested one, or the one read before the
+// mutation. Returns {justification, reasserted}; throws when it cannot deliver.
+function __verifyJustification(src, expected) {
+  var actual = src.value.justification;
+  if (actual === expected) return { justification: actual, reasserted: false };
+  var again = src.value;
+  again.justification = expected;
+  src.setValue(again);
+  actual = src.value.justification;
+  if (actual === expected) return { justification: actual, reasserted: true };
+  throw new Error(
+    "Source Text justification did not land: expected " + __justificationName(expected) +
+    " (" + String(expected) + "), the layer reads " + __justificationName(actual) +
+    " (" + String(actual) + ") after a second write. The other fields were written. " +
+    "Read the layer back with get_layer_full include:[\"text\"] before relying on its alignment."
+  );
+}
+
 OPS.set_text = function (args) {
   var c = getCompById(args.compId);
   var l = getLayerById(c, args.layerId);
   if (!(l instanceof TextLayer)) throw new Error("Layer is not a TextLayer");
   var src = l.property("Source Text");
   var td = src.value;
+  // Captured before anything is touched: "undefined fields unchanged" is a
+  // claim about this value, and it is what the read-back is checked against
+  // when no justification was asked for.
+  var justificationBefore = td.justification;
+  var justificationWanted = justificationBefore;
+  if (args.justification !== undefined) {
+    if (__JUSTIFICATION[args.justification] === undefined) {
+      throw new Error("Unknown justification '" + String(args.justification) + "'; expected one of left, center, right, full. Nothing was changed.");
+    }
+    justificationWanted = __JUSTIFICATION[args.justification];
+  }
   if (args.text !== undefined) td.text = args.text;
   if (args.font !== undefined) td.font = args.font;
   if (args.size !== undefined) td.fontSize = args.size;
@@ -2161,9 +2344,7 @@ OPS.set_text = function (args) {
   if (args.strokeWidth !== undefined) td.strokeWidth = args.strokeWidth;
   if (args.tracking !== undefined) td.tracking = args.tracking;
   if (args.leading !== undefined) td.leading = args.leading;
-  if (args.justification !== undefined) {
-    if (__JUSTIFICATION[args.justification]) td.justification = __JUSTIFICATION[args.justification];
-  }
+  if (args.justification !== undefined) td.justification = justificationWanted;
   if (args.applyFill !== undefined) td.applyFill = args.applyFill;
   if (args.applyStroke !== undefined) td.applyStroke = args.applyStroke;
   if (args.fauxBold !== undefined) td.fauxBold = args.fauxBold;
@@ -2172,7 +2353,12 @@ OPS.set_text = function (args) {
   if (args.smallCaps !== undefined) td.smallCaps = args.smallCaps;
   if (args.baselineShift !== undefined) td.baselineShift = args.baselineShift;
   src.setValue(td);
-  return { ok: true };
+  var verified = __verifyJustification(src, justificationWanted);
+  return {
+    ok: true,
+    justification: __justificationName(verified.justification),
+    justificationReasserted: verified.reasserted,
+  };
 };
 
 OPS.add_text_animator = function (args) {
@@ -2921,6 +3107,221 @@ OPS.create_footage_layer = function (args) {
   };
 };
 
+// ---------------------------------------------------------------------------
+// Unused footage, and the solids delete_comp leaves behind (issue #83)
+// ---------------------------------------------------------------------------
+// A solid layer's source is a FootageItem in the project's Solids folder, not
+// something the comp owns. Deleting the comp (or the layer) deletes the layer
+// and leaves the item: nothing in AE's DOM ties the two lifetimes together and
+// nothing warns, so a session that builds and discards comps grows the project
+// bin without bound — a verification pass had to sweep 1,863 of them out by
+// name. Once orphaned they are indistinguishable from solids still in use
+// unless something reads `usedIn`, which is what everything below does.
+//
+// Two ops share these helpers. `delete_comp` (comps.jsx) can purge the solids
+// the deleted comp referenced — only those, and only the ones nothing else
+// still uses — and `purge_unused_footage` is the project-wide sweep: AE's own
+// Remove Unused Footage, with a dryRun and a report of what went.
+
+/** The item behind a solid or adjustment layer: a FootageItem whose source is a SolidSource. */
+function __isSolidItem(it) {
+  if (!(it instanceof FootageItem)) return false;
+  var src = null;
+  try { src = it.mainSource; } catch (e) { return false; }
+  if (!src) return false;
+  return (src instanceof SolidSource);
+}
+
+/** "solid" | "placeholder" | "footage". Only ever called on a FootageItem — a comp or folder is never footage. */
+function __footageKind(it) {
+  if (__isSolidItem(it)) return "solid";
+  try {
+    if (typeof PlaceholderSource !== "undefined" && it.mainSource instanceof PlaceholderSource) return "placeholder";
+  } catch (e) {}
+  return "footage";
+}
+
+/**
+ * The comps an item is placed in, as {id, name}. Read from After Effects on
+ * every call rather than inferred from anything this bundle remembers — the
+ * whole safety of a purge is that the answer is AE's, at the moment of asking.
+ */
+function __usedInList(it) {
+  var out = [];
+  var comps = null;
+  try { comps = it.usedIn; } catch (e) { comps = null; }
+  if (!comps) return out;
+  for (var i = 0; i < comps.length; i++) {
+    var c = comps[i];
+    if (!c) continue;
+    out.push({ id: c.id, name: c.name });
+  }
+  return out;
+}
+
+/** True when `it` sits in `folder` or in any folder nested under it. */
+function __isInFolder(it, folder) {
+  var cur = null;
+  try { cur = it.parentFolder; } catch (e) { return false; }
+  for (var depth = 0; cur && depth < 64; depth++) {
+    if (cur.id === folder.id) return true;
+    var next = null;
+    try { next = cur.parentFolder; } catch (e2) { next = null; }
+    cur = next;
+  }
+  return false;
+}
+
+/** The distinct solid items this comp's own layers point at, as {id, name}. Nothing from any other comp. */
+function __solidItemsOf(comp) {
+  var out = [];
+  var seen = {};
+  for (var i = 1; i <= comp.numLayers; i++) {
+    var l = comp.layer(i);
+    if (!(l instanceof AVLayer)) continue;
+    var src = null;
+    try { src = l.source; } catch (e) { continue; }
+    if (!src || !__isSolidItem(src)) continue;
+    var key = "I" + src.id;
+    if (seen.hasOwnProperty(key)) continue;
+    seen[key] = true;
+    out.push({ id: src.id, name: src.name });
+  }
+  return out;
+}
+
+function __itemReport(entry) {
+  var r = { id: entry.id, name: entry.name, kind: entry.kind };
+  if (entry.footageMissing) r.footageMissing = true;
+  return r;
+}
+
+function __nameList(reports, cap) {
+  var names = [];
+  for (var i = 0; i < reports.length && i < cap; i++) names.push("\"" + reports[i].name + "\" (id " + reports[i].id + ")");
+  var s = names.join(", ");
+  if (reports.length > cap) s += " and " + (reports.length - cap) + " more";
+  return s;
+}
+
+/**
+ * Remove a list of project items. Entries are {item, id, name, kind, index?}.
+ *
+ * Highest project index first when indices are known, so no removal shifts an
+ * item still to be visited — the entries were collected in one pass over
+ * app.project.item(i) and removed in a second, never removed mid-walk. It stops
+ * at the first failure: nothing rolls back, so the caller is handed what went
+ * before the failure and what was never attempted, and reports that, rather
+ * than a sweep that claims to have finished.
+ */
+function __removeItems(entries) {
+  var ordered = entries.slice(0);
+  ordered.sort(function (a, b) { return (b.index || 0) - (a.index || 0); });
+  var removed = [];
+  for (var i = 0; i < ordered.length; i++) {
+    var entry = ordered[i];
+    try {
+      entry.item.remove();
+    } catch (e) {
+      var pending = [];
+      for (var j = i + 1; j < ordered.length; j++) pending.push(__itemReport(ordered[j]));
+      return {
+        removed: removed,
+        failed: __itemReport(entry),
+        error: (e && e.message) ? String(e.message) : String(e),
+        notAttempted: pending
+      };
+    }
+    removed.push(__itemReport(entry));
+  }
+  return { removed: removed, failed: null, error: null, notAttempted: [] };
+}
+
+OPS.purge_unused_footage = noUndoWhen(
+  // A dry run is not an undo step. A sweep that changed nothing appearing in
+  // the user's undo history would make "this changed nothing" false in the one
+  // place they can see it — the same stance place_audio_cues takes.
+  function (args) { return !!(args && args.dryRun === true); },
+  function (args) {
+    args = args || {};
+    var solidsOnly = (args.solidsOnly !== false);
+    var dryRun = (args.dryRun === true);
+    var folder = null;
+    if (args.folderId !== undefined && args.folderId !== null) folder = __folderArg(args.folderId);
+    var what = "footage item";
+    if (solidsOnly) what = "solid";
+
+    // One pass to decide, a second to remove. Removing inside the walk would
+    // shift every index above the removed item under the loop's feet.
+    var candidates = [];
+    var scanned = 0;
+    var inUse = 0;
+    var proj = app.project;
+    for (var i = 1; i <= proj.numItems; i++) {
+      var it = proj.item(i);
+      // A comp is an AVItem with a usedIn of its own, and a nested comp nothing
+      // uses any more is exactly what a naive sweep would delete. Only footage.
+      if (!(it instanceof FootageItem)) continue;
+      if (solidsOnly && !__isSolidItem(it)) continue;
+      if (folder && !__isInFolder(it, folder)) continue;
+      scanned += 1;
+      if (__usedInList(it).length > 0) { inUse += 1; continue; }
+      var missing = false;
+      try { missing = !!it.footageMissing; } catch (eMissing) {}
+      candidates.push({ item: it, id: it.id, name: it.name, kind: __footageKind(it), index: i, footageMissing: missing });
+    }
+    // Sorted here, once, so a dry run lists items in exactly the order a real
+    // run removes them — the plan has to be the truth about order too.
+    candidates.sort(function (a, b) { return b.index - a.index; });
+
+    var out = { solidsOnly: solidsOnly, scanned: scanned, inUse: inUse };
+    var where = "in the project";
+    if (folder) {
+      out.folderId = folder.id;
+      out.folderName = folder.name;
+      where = "in folder \"" + folder.name + "\"";
+    }
+    var nothingWhy = "every " + what + " " + where + " is still used in a comp";
+    if (scanned === 0) nothingWhy = "no " + what + "s " + where;
+
+    if (dryRun) {
+      var would = [];
+      for (var w = 0; w < candidates.length; w++) would.push(__itemReport(candidates[w]));
+      out.dryRun = true;
+      out.wouldRemove = would;
+      out.wouldRemoveCount = would.length;
+      if (would.length === 0) {
+        out.note = "Nothing to remove: " + nothingWhy + ". Nothing was changed and this call is not an undo step.";
+      } else {
+        out.note = "Nothing was removed and this call is not an undo step. Call again without dryRun to remove these " +
+          would.length + " " + what + (would.length === 1 ? "" : "s") + " " + where + ".";
+      }
+      return out;
+    }
+
+    var r = __removeItems(candidates);
+    out.removed = r.removed;
+    out.removedCount = r.removed.length;
+    if (r.failed) {
+      var msg = "purge_unused_footage stopped at \"" + r.failed.name + "\" (id " + r.failed.id + ", " + r.failed.kind + "): " + r.error + ".";
+      if (r.removed.length > 0) {
+        msg += " " + r.removed.length + " item(s) were removed before it: " + __nameList(r.removed, 20) + ".";
+      } else {
+        msg += " Nothing had been removed yet.";
+      }
+      msg += " " + r.notAttempted.length + " unused item(s) were not attempted." +
+        " Nothing rolls back; one Undo in After Effects restores what this call removed. Run again, or with dryRun:true, to see what is left.";
+      throw new Error(msg);
+    }
+    if (r.removed.length === 0) {
+      out.note = "Nothing to remove: " + nothingWhy + ".";
+    } else {
+      out.note = "Removed " + r.removed.length + " unused " + what + (r.removed.length === 1 ? "" : "s") + " " + where + ", as one undo step.";
+    }
+    return out;
+  }
+);
+
 
 // ===== audio.jsx =====
 
@@ -2946,10 +3347,21 @@ OPS.create_footage_layer = function (args) {
 //     .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.
+//
+// Three per-cue options (issue #85) — `loop`, `fadeIn`/`fadeOut`, `stretch` —
+// are the patterns every scoring pass used to re-implement in a run_jsx
+// follow-up. Each one moves something After Effects then quietly resets, so
+// the order inside __placeAudioCue is load-bearing; see the comment there.
 
 var __MAX_AUDIO_CUES = 200;
 var __CUE_TIME_EPS = 1e-6;
 
+// The level a fade starts from and ends at when the caller gives none. -48 dB
+// is the bottom of the range After Effects' own Audio Levels slider offers, and
+// 1/256 of the recorded amplitude — near-silence for a fade to begin from while
+// staying inside the range a user can drag the property through by hand.
+var __DEFAULT_FADE_FLOOR_DB = -48;
+
 // 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".
@@ -2998,6 +3410,10 @@ function __stripExtension(name) {
   return s;
 }
 
+function __isFiniteNumber(v) {
+  return typeof v === "number" && isFinite(v);
+}
+
 /**
  * The Audio Levels property of a layer.
  *
@@ -3019,6 +3435,21 @@ function __audioLevelsProperty(layer) {
   return p;
 }
 
+/**
+ * The Time Remap property of a layer that has remapping enabled. Same shape of
+ * trap as Audio Levels: `layer.property("ADBE Time Remap")` is null on an
+ * audio layer even after `timeRemapEnabled = true`, and the shortcut
+ * `layer.timeRemap` is the handle that answers. The match-name lookup is kept
+ * only as a fallback; a null from both is reported, never worked around.
+ */
+function __timeRemapProperty(layer) {
+  var p = null;
+  try { p = layer.timeRemap; } catch (e) {}
+  if (p) return p;
+  try { p = layer.property("ADBE Time Remapping"); } 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";
@@ -3034,6 +3465,84 @@ function __sourceReport(item, path) {
   return { itemId: item.id, name: item.name, path: path };
 }
 
+/** The duration of a project item, or null when it does not say. */
+function __itemDuration(item) {
+  if (!item) return null;
+  var d = null;
+  try { d = item.duration; } catch (e) {}
+  if (__isFiniteNumber(d)) return d;
+  return null;
+}
+
+/**
+ * Where a planned cue's layer will start and end, in comp time, given what is
+ * known about its source. `end` is null when it cannot be known yet — an
+ * unlooped cue on a file that has not been imported, with no outPoint to cap
+ * it — and the caller decides what to do with that.
+ */
+function __cueExtent(p, itemDuration) {
+  var start = p.time;
+  if (p.inPoint !== null) start = p.inPoint;
+  var end = null;
+  if (p.loop) {
+    // A loop has no natural end, so its end is the one the caller gave or the
+    // comp's, whichever the planner settled on.
+    end = p.loopEnd;
+  } else {
+    var natural = null;
+    if (__isFiniteNumber(itemDuration)) natural = p.time + itemDuration * p.stretchFactor;
+    end = p.outPoint;
+    // AE clamps an out point to what the source can supply, so a requested
+    // outPoint past the file's end is not where the layer will end.
+    if (end === null || (natural !== null && natural < end)) end = natural;
+  }
+  return { start: start, end: end };
+}
+
+function __fmtSeconds(n) {
+  // Rounded for prose only; nothing downstream reads these numbers back.
+  return String(Math.round(n * 1000) / 1000) + "s";
+}
+
+/**
+ * null when the cue's fades fit inside its extent; a reason string when they
+ * do not; and the string "unknown" when the extent cannot be computed yet.
+ * Pure — used at plan time and again after the imports, on the same plan.
+ */
+function __fadeFitProblem(p, extent) {
+  var total = p.fadeIn + p.fadeOut;
+  if (total <= 0 && !p.loop) return null;
+  if (extent.end === null) {
+    if (total <= 0) return null;
+    return "unknown";
+  }
+  var dur = extent.end - extent.start;
+  var span = " (from " + __fmtSeconds(extent.start) + " to " + __fmtSeconds(extent.end) + ")";
+  if (dur <= __CUE_TIME_EPS) {
+    if (p.loop) {
+      var why = "the comp's end, since no outPoint was given";
+      if (p.outPoint !== null) why = "its outPoint";
+      return "inPoint " + __fmtSeconds(extent.start) + " is not before the end of the loop at " + __fmtSeconds(extent.end) + " (" + why + ")";
+    }
+    return "inPoint " + __fmtSeconds(extent.start) + " is past where the cue ends" + span;
+  }
+  if (total <= 0) return null;
+  if (total > dur + __CUE_TIME_EPS) {
+    var what;
+    if (p.fadeIn > 0 && p.fadeOut > 0) {
+      what = "fadeIn " + __fmtSeconds(p.fadeIn) + " + fadeOut " + __fmtSeconds(p.fadeOut) + " = " + __fmtSeconds(total);
+    } else if (p.fadeIn > 0) {
+      what = "fadeIn " + __fmtSeconds(p.fadeIn);
+    } else {
+      what = "fadeOut " + __fmtSeconds(p.fadeOut);
+    }
+    var tail = "";
+    if (!p.loop && p.outPoint === null) tail = " — the file's own length, with no outPoint to extend it and no loop";
+    return what + " is longer than the cue, which runs " + __fmtSeconds(dur) + span + tail;
+  }
+  return null;
+}
+
 /**
  * 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
@@ -3055,6 +3564,15 @@ function __planAudioCues(comp, args) {
   var prefix = "SFX_";
   if (typeof args.namePrefix === "string") prefix = args.namePrefix;
 
+  // One floor for the whole list: it is a property of the mix, not of a cue.
+  var floorDb = __DEFAULT_FADE_FLOOR_DB;
+  if (args.fadeFloorDb !== undefined && args.fadeFloorDb !== null) {
+    if (!__isFiniteNumber(args.fadeFloorDb)) {
+      throw new Error("fadeFloorDb must be a number of decibels (the default is " + __DEFAULT_FADE_FLOOR_DB + "); got " + String(args.fadeFloorDb));
+    }
+    floorDb = args.fadeFloorDb;
+  }
+
   var byPath = __itemPathMap();
   var problems = [];
   var planned = [];
@@ -3071,7 +3589,7 @@ function __planAudioCues(comp, args) {
     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)) {
+    if (!__isFiniteNumber(time)) {
       problems.push({ cue: i, reason: "time must be a number of seconds; got " + String(time) });
       continue;
     }
@@ -3082,7 +3600,7 @@ function __planAudioCues(comp, args) {
 
     var levelDb = 0;
     if (cue.levelDb !== undefined && cue.levelDb !== null) {
-      if (typeof cue.levelDb !== "number" || !isFinite(cue.levelDb)) {
+      if (!__isFiniteNumber(cue.levelDb)) {
         problems.push({ cue: i, reason: "levelDb must be a number of decibels (0 is unedited); got " + String(cue.levelDb) });
         continue;
       }
@@ -3093,7 +3611,7 @@ function __planAudioCues(comp, args) {
     var outPoint = null;
     var trimBad = false;
     if (cue.inPoint !== undefined && cue.inPoint !== null) {
-      if (typeof cue.inPoint !== "number" || !isFinite(cue.inPoint)) {
+      if (!__isFiniteNumber(cue.inPoint)) {
         problems.push({ cue: i, reason: "inPoint must be a comp time in seconds; got " + String(cue.inPoint) });
         trimBad = true;
       } else {
@@ -3101,7 +3619,7 @@ function __planAudioCues(comp, args) {
       }
     }
     if (!trimBad && cue.outPoint !== undefined && cue.outPoint !== null) {
-      if (typeof cue.outPoint !== "number" || !isFinite(cue.outPoint)) {
+      if (!__isFiniteNumber(cue.outPoint)) {
         problems.push({ cue: i, reason: "outPoint must be a comp time in seconds; got " + String(cue.outPoint) });
         trimBad = true;
       } else {
@@ -3132,6 +3650,53 @@ function __planAudioCues(comp, args) {
       }
     }
 
+    // The #85 options. Type-checked here, before the source is resolved, so a
+    // cue with a bad stretch AND a missing file reports the first of the two
+    // it hits — every cue still gets a line, which is what matters.
+    var loop = false;
+    if (cue.loop !== undefined && cue.loop !== null) {
+      if (cue.loop !== true && cue.loop !== false) {
+        problems.push({ cue: i, reason: "loop must be true or false; got " + String(cue.loop) });
+        continue;
+      }
+      loop = cue.loop;
+    }
+    var stretch = null;
+    if (cue.stretch !== undefined && cue.stretch !== null) {
+      if (!__isFiniteNumber(cue.stretch) || cue.stretch <= 0) {
+        problems.push({ cue: i, reason: "stretch must be a percentage greater than 0 (100 is unchanged, 200 is half speed); got " + String(cue.stretch) });
+        continue;
+      }
+      stretch = cue.stretch;
+    }
+    var fadeIn = 0;
+    var fadeOut = 0;
+    var fadeBad = false;
+    if (cue.fadeIn !== undefined && cue.fadeIn !== null) {
+      if (!__isFiniteNumber(cue.fadeIn) || cue.fadeIn < 0) {
+        problems.push({ cue: i, reason: "fadeIn must be a number of seconds, 0 or more; got " + String(cue.fadeIn) });
+        fadeBad = true;
+      } else {
+        fadeIn = cue.fadeIn;
+      }
+    }
+    if (!fadeBad && cue.fadeOut !== undefined && cue.fadeOut !== null) {
+      if (!__isFiniteNumber(cue.fadeOut) || cue.fadeOut < 0) {
+        problems.push({ cue: i, reason: "fadeOut must be a number of seconds, 0 or more; got " + String(cue.fadeOut) });
+        fadeBad = true;
+      } else {
+        fadeOut = cue.fadeOut;
+      }
+    }
+    if (fadeBad) continue;
+    if ((fadeIn > 0 || fadeOut > 0) && floorDb >= levelDb) {
+      problems.push({
+        cue: i,
+        reason: "fadeFloorDb " + floorDb + " is not below the cue's level " + levelDb + " dB, so its fade would go nowhere — lower the floor or raise the level"
+      });
+      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.
@@ -3169,44 +3734,85 @@ function __planAudioCues(comp, args) {
     var name = prefix + __stripExtension(defaultName);
     if (typeof cue.name === "string" && cue.name.length > 0) name = cue.name;
 
-    planned.push({
+    var stretchFactor = 1;
+    if (stretch !== null) stretchFactor = stretch / 100;
+    // A looped cue needs an end, because a loop has none of its own.
+    var loopEnd = null;
+    if (loop) {
+      loopEnd = comp.duration;
+      if (outPoint !== null) loopEnd = outPoint;
+    }
+
+    var p = {
       index: i, name: name, time: time, levelDb: levelDb,
-      inPoint: inPoint, outPoint: outPoint, label: label, source: source
-    });
+      inPoint: inPoint, outPoint: outPoint, label: label, source: source,
+      loop: loop, loopEnd: loopEnd, stretch: stretch, stretchFactor: stretchFactor,
+      fadeIn: fadeIn, fadeOut: fadeOut,
+      // true when the fade could not be measured against the file yet
+      fadeUnchecked: false
+    };
+
+    // Does the cue fit? Known now for a loop (its end is chosen here), for a
+    // footageId or reused item (After Effects reports its duration) and for a
+    // capped outPoint; not yet for an unlooped cue on a file still to import.
+    var fit = __fadeFitProblem(p, __cueExtent(p, __itemDuration(source.item)));
+    if (fit === "unknown") {
+      p.fadeUnchecked = true;
+    } else if (fit !== null) {
+      problems.push({ cue: i, reason: fit });
+      continue;
+    }
+
+    planned.push(p);
   }
 
-  return { prefix: prefix, planned: planned, problems: problems, toImport: toImport };
+  return { prefix: prefix, planned: planned, problems: problems, toImport: toImport, floorDb: floorDb };
 }
 
-function __audioProblemMessage(problems, total) {
+function __audioProblemLines(problems) {
   var lines = [];
   for (var i = 0; i < problems.length; i++) {
     lines.push("cue " + problems[i].cue + ": " + problems[i].reason);
   }
+  return lines.join("; ");
+}
+
+function __audioProblemMessage(problems, total) {
   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 " +
+    __audioProblemLines(problems) + ". 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."
   );
 }
 
+/**
+ * Counts and the two lists a caller cannot work out alone — what would be
+ * imported and what is already there — plus the failing cues. Never the
+ * resolved list: a 7-cue "all fine" used to cost ~1.5k tokens of echo (#88).
+ */
 function __audioDryRunReport(comp, plan, total) {
-  var cues = [];
+  var wouldImport = [];
+  for (var j = 0; j < plan.toImport.length; j++) wouldImport.push(plan.toImport[j].path);
+
+  var wouldReuse = [];
+  var reuseSeen = {};
+  var looped = 0;
+  var faded = 0;
+  var stretched = 0;
+  var fadesUnchecked = 0;
   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.item && !reuseSeen.hasOwnProperty(String(p.source.item.id))) {
+      reuseSeen[String(p.source.item.id)] = true;
+      var r = { itemId: p.source.item.id, name: p.source.item.name };
+      if (p.source.path) r.path = p.source.path;
+      wouldReuse.push(r);
     }
-    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
-    });
+    if (p.loop) looped++;
+    if (p.fadeIn > 0 || p.fadeOut > 0) faded++;
+    if (p.stretch !== null) stretched++;
+    if (p.fadeUnchecked) fadesUnchecked++;
   }
-  var wouldImport = [];
-  for (var j = 0; j < plan.toImport.length; j++) wouldImport.push(plan.toImport[j].path);
 
   var out = {
     dryRun: true,
@@ -3214,17 +3820,24 @@ function __audioDryRunReport(comp, plan, total) {
     compId: comp.id,
     compName: comp.name,
     cueCount: total,
-    wouldPlace: cues.length,
+    wouldPlace: plan.planned.length,
     wouldImport: wouldImport,
+    wouldReuse: wouldReuse,
     problems: plan.problems,
-    cues: cues,
     note: "Nothing was imported, created or changed, and this call is not an undo step."
   };
+  if (looped > 0) out.looped = looped;
+  if (faded > 0) out.faded = faded;
+  if (stretched > 0) out.stretched = stretched;
   if (wouldImport.length > 0) {
+    var fadeNote = "";
+    if (fadesUnchecked > 0) {
+      fadeNote = " — and, for " + fadesUnchecked + " cue(s) with a fade, whether the fade fits the file's length —";
+    }
     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.";
+      "carries an audio track" + fadeNote + " 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;
 }
@@ -3239,16 +3852,40 @@ function __rollbackAudioCues(layers, items) {
   }
 }
 
+/**
+ * The Time Remap expression that loops a cue. It is the pattern measured in
+ * issue #85 — comp time since the layer began, wrapped at the file's length —
+ * with two substitutions: `startTime` rather than `inPoint`, so trimming the
+ * in point hides the front of the file the way it does on every other layer
+ * instead of delaying it; and the source's duration read live off the layer,
+ * so a relinked file keeps looping. An expression cannot read a layer's
+ * stretch, so a stretched cue has its factor baked in, and that constant goes
+ * stale if the stretch is changed by hand afterwards.
+ */
+function __loopExpression(p) {
+  var elapsed = "(time - startTime)";
+  if (p.stretch !== null && p.stretch !== 100) elapsed = "((time - startTime) * 100 / " + p.stretch + ")";
+  return elapsed + " % thisLayer.source.duration";
+}
+
 /**
  * `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.
+ *
+ * The order after that is not free to change. Each of the #85 options moves
+ * something After Effects then resets: `stretch` moves startTime, so startTime
+ * is set after it; enabling time remap resets the out point, so the extent is
+ * set after that; and the fade keys sit at the in/out the layer actually has,
+ * so they go last. Out point before in point throughout — extending first is
+ * what lets an in point past the file's natural end land on a looped layer.
  */
-function __placeAudioCue(comp, p, item, created) {
+function __placeAudioCue(comp, p, item, created, floorDb) {
   var layer = comp.layers.add(item);
   created.push(layer);
   layer.name = p.name;
+  if (p.stretch !== null) layer.stretch = p.stretch;
   // startTime first: it slides the whole layer and would drag any trim with it.
   layer.startTime = p.time;
   var levels = __audioLevelsProperty(layer);
@@ -3257,14 +3894,81 @@ function __placeAudioCue(comp, p, item, created) {
       "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;
+
+  if (p.loop) {
+    // `=== false`, as with hasAudio: a layer that does not answer the question
+    // is not refused on the strength of a missing property.
+    if (layer.canSetTimeRemapEnabled === false) {
+      throw new Error(
+        "After Effects reports that time remapping cannot be enabled on the layer created for \"" + item.name + "\", so it cannot loop"
+      );
+    }
+    layer.timeRemapEnabled = true;
+    var remap = __timeRemapProperty(layer);
+    if (!remap) {
+      throw new Error(
+        "time remapping was enabled on the layer created for \"" + item.name + "\" but its Time Remap property could not be found, so the loop expression could not be set"
+      );
+    }
+    // The two keyframes AE created when remapping was enabled stay exactly
+    // where they are. Removing them hides the property, and the next write to
+    // it throws (issue #86); the expression overrides them anyway.
+    remap.expression = __loopExpression(p);
+    layer.outPoint = p.loopEnd;
+    if (p.inPoint !== null) layer.inPoint = p.inPoint;
+  } else {
+    if (p.outPoint !== null) layer.outPoint = p.outPoint;
+    if (p.inPoint !== null) layer.inPoint = p.inPoint;
+  }
+
+  // AE's Audio Levels is itself in decibels, one entry per channel.
+  var level = [p.levelDb, p.levelDb];
+  if (p.fadeIn > 0 || p.fadeOut > 0) {
+    var inP = layer.inPoint;
+    var outP = layer.outPoint;
+    var dur = outP - inP;
+    // The planner measured the fade against what it could know; this is the
+    // extent After Effects actually gave the layer, and the last line.
+    if (p.fadeIn + p.fadeOut > dur + __CUE_TIME_EPS) {
+      throw new Error(
+        "its fades (" + __fmtSeconds(p.fadeIn) + " in, " + __fmtSeconds(p.fadeOut) + " out) are longer than the " +
+        __fmtSeconds(dur) + " After Effects gave the layer (" + __fmtSeconds(inP) + " to " + __fmtSeconds(outP) + ")"
+      );
+    }
+    var floor = [floorDb, floorDb];
+    if (p.fadeIn > 0) {
+      levels.setValueAtTime(inP, floor);
+      levels.setValueAtTime(inP + p.fadeIn, level);
+    }
+    if (p.fadeOut > 0) {
+      levels.setValueAtTime(outP - p.fadeOut, level);
+      levels.setValueAtTime(outP, floor);
+    }
+  } else {
+    levels.setValue(level);
+  }
   return layer;
 }
 
+/**
+ * What the caller gets back per cue: the id it has to carry forward, the name,
+ * the time, and — only where an option could have changed it — what After
+ * Effects actually did. Never an echo of the request.
+ */
+function __placedEntry(layer, p) {
+  var entry = { layerId: layer.id, name: layer.name, time: p.time };
+  // 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.
+  if (p.inPoint !== null) entry.inPoint = layer.inPoint;
+  if (p.outPoint !== null || p.loop || p.stretch !== null) entry.outPoint = layer.outPoint;
+  if (p.loop) entry.looped = true;
+  if (p.stretch !== null) entry.stretch = layer.stretch;
+  if (p.fadeIn > 0) entry.fadeIn = p.fadeIn;
+  if (p.fadeOut > 0) entry.fadeOut = p.fadeOut;
+  return entry;
+}
+
 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
@@ -3285,6 +3989,7 @@ OPS.place_audio_cues = noUndoWhen(
     var reusedReport = [];
     var reusedSeen = {};
     var placed = [];
+    var anyFade = false;
 
     try {
       // One import per distinct file, before any layer exists, so a bad file
@@ -3300,6 +4005,26 @@ OPS.place_audio_cues = noUndoWhen(
         importedReport.push(__sourceReport(newItem, spec.path));
       }
 
+      // The fades the planner could not measure — on files it had not seen —
+      // are measured now, with every duration known and no layer yet made, so
+      // a misfit still names every offending cue at once and costs only the
+      // imports, which the rollback takes back.
+      var lateProblems = [];
+      for (var f = 0; f < plan.planned.length; f++) {
+        var pf = plan.planned[f];
+        if (!pf.fadeUnchecked) continue;
+        var fit = __fadeFitProblem(pf, __cueExtent(pf, __itemDuration(imported[pf.source.fsName])));
+        if (fit === "unknown") {
+          fit = "After Effects did not report a duration for the imported " + pf.source.path + ", so its fade cannot be checked";
+        }
+        if (fit !== null) lateProblems.push({ cue: pf.index, reason: fit });
+      }
+      if (lateProblems.length > 0) {
+        throw new Error(
+          "the fades on " + lateProblems.length + " cue(s) do not fit the files once imported — " + __audioProblemLines(lateProblems)
+        );
+      }
+
       for (var k = 0; k < plan.planned.length; k++) {
         var p = plan.planned[k];
         var item = p.source.item;
@@ -3310,23 +4035,12 @@ OPS.place_audio_cues = noUndoWhen(
         }
         var layer;
         try {
-          layer = __placeAudioCue(comp, p, item, createdLayers);
+          layer = __placeAudioCue(comp, p, item, createdLayers, plan.floorDb);
         } 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
-        });
+        if (p.fadeIn > 0 || p.fadeOut > 0) anyFade = true;
+        placed.push(__placedEntry(layer, p));
       }
     } catch (e) {
       __rollbackAudioCues(createdLayers, importedItems);
@@ -3337,13 +4051,15 @@ OPS.place_audio_cues = noUndoWhen(
       );
     }
 
-    return {
+    var out = {
       compId: comp.id,
       placed: placed,
       count: placed.length,
       sources: { imported: importedReport, reused: reusedReport },
       levelUnit: "dB"
     };
+    if (anyFade) out.fadeFloorDb = plan.floorDb;
+    return out;
   }
 );
 
@@ -3841,6 +4557,11 @@ OPS.set_house_style = noUndo(function (args) {
   }
 
   file.encoding = "UTF-8";
+  // ExtendScript's default lineFeed on macOS is "Macintosh", which turns every
+  // "\n" into a bare "\r" on disk (measured on 26.3: a guide written through
+  // this op read back fine, because File.read normalises, but opened as one
+  // long line in a text editor). The file is meant to be hand-edited.
+  file.lineFeed = "Unix";
   if (!file.open("w")) throw new Error("Could not open " + file.fsName + " for writing");
   try {
     if (!file.write(content)) throw new Error("Write failed for " + file.fsName);
@@ -4654,7 +5375,16 @@ OPS.get_project_summary = noUndo(function (args) {
   };
 });
 
+// A search, so the default is the opposite of list_layers: absent `include`
+// means the core alone — id/index/name/sourceType plus the comp — because the
+// reason to call this is to learn which layers exist and what to address them
+// by, not to read them (issue #87: nine matches cost ~2k tokens, re-sent on
+// every later request). `include: []` and omitting it are therefore the same
+// here, and the section names are list_layers' own, read through the same
+// __layerSummary. What was included is echoed, so a bounded answer is never
+// read as a full one.
 OPS.find_layers = noUndo(function (args) {
+  var sections = (args && args.include) ? args.include : [];
   var out = [];
   var comps = [];
   if (args.compId) comps.push(getCompById(args.compId));
@@ -4681,13 +5411,13 @@ OPS.find_layers = noUndo(function (args) {
         }
         if (!hit) continue;
       }
-      var s = __layerSummary(l);
+      var s = __layerSummary(l, sections);
       s.compId = c.id;
       s.compName = c.name;
       out.push(s);
     }
   }
-  return out;
+  return { matches: out, count: out.length, compsSearched: comps.length, included: sections };
 });