@synthetic-ai/premiere-mcp 2.0.0 → 2.2.0

package/dist/bridge/script-builder.js

@@ -2,389 +2,389 @@
  * Builds ExtendScript strings with helper functions prepended.
  * All generated code must be ES3-compatible (var, no arrow functions, no let/const).
  */
-const HELPERS = `
-// === MCP Bridge Helpers (auto-prepended) ===
-
-var TICKS_PER_SECOND = 254016000000;
-
-function __ticksToSeconds(ticks) {
-  return parseFloat(ticks) / TICKS_PER_SECOND;
-}
-
-function __secondsToTicks(seconds) {
-  return Math.round(parseFloat(seconds) * TICKS_PER_SECOND);
-}
-
-function __ticksToTimecode(ticks, fps) {
-  var totalSeconds = __ticksToSeconds(ticks);
-  var hours = Math.floor(totalSeconds / 3600);
-  var minutes = Math.floor((totalSeconds % 3600) / 60);
-  var secs = Math.floor(totalSeconds % 60);
-  var frames = Math.floor((totalSeconds % 1) * fps);
-  return __pad(hours) + ":" + __pad(minutes) + ":" + __pad(secs) + ":" + __pad(frames);
-}
-
-function __pad(n) {
-  return n < 10 ? "0" + n : "" + n;
-}
-
-function __findSequence(idOrName) {
-  var project = app.project;
-  for (var i = 0; i < project.sequences.numSequences; i++) {
-    var seq = project.sequences[i];
-    if (seq.sequenceID === idOrName || seq.name === idOrName) {
-      return seq;
-    }
-  }
-  return null;
-}
-
-function __findProjectItem(nodeIdOrName, rootItem) {
-  if (!rootItem) rootItem = app.project.rootItem;
-  for (var i = 0; i < rootItem.children.numItems; i++) {
-    var item = rootItem.children[i];
-    if (item.nodeId === nodeIdOrName || item.name === nodeIdOrName) {
-      return item;
-    }
-    if (item.type === 2) { // Bin
-      var found = __findProjectItem(nodeIdOrName, item);
-      if (found) return found;
-    }
-  }
-  return null;
-}
-
-function __findClip(nodeId) {
-  var seq = app.project.activeSequence;
-  if (!seq) return null;
-
-  // Search video tracks
-  for (var t = 0; t < seq.videoTracks.numTracks; t++) {
-    var track = seq.videoTracks[t];
-    for (var c = 0; c < track.clips.numItems; c++) {
-      var clip = track.clips[c];
-      if (clip.nodeId === nodeId) {
-        return { clip: clip, trackIndex: t, clipIndex: c, trackType: "video" };
-      }
-    }
-  }
-
-  // Search audio tracks
-  for (var t = 0; t < seq.audioTracks.numTracks; t++) {
-    var track = seq.audioTracks[t];
-    for (var c = 0; c < track.clips.numItems; c++) {
-      var clip = track.clips[c];
-      if (clip.nodeId === nodeId) {
-        return { clip: clip, trackIndex: t, clipIndex: c, trackType: "audio" };
-      }
-    }
-  }
-
-  return null;
-}
-
-function __getAllClips(seq) {
-  if (!seq) seq = app.project.activeSequence;
-  if (!seq) return [];
-  var clips = [];
-
-  for (var t = 0; t < seq.videoTracks.numTracks; t++) {
-    var track = seq.videoTracks[t];
-    for (var c = 0; c < track.clips.numItems; c++) {
-      var clip = track.clips[c];
-      clips.push({
-        nodeId: clip.nodeId,
-        name: clip.name,
-        trackIndex: t,
-        trackType: "video",
-        inPoint: __ticksToSeconds(clip.inPoint.ticks),
-        outPoint: __ticksToSeconds(clip.outPoint.ticks),
-        start: __ticksToSeconds(clip.start.ticks),
-        end: __ticksToSeconds(clip.end.ticks),
-        duration: __ticksToSeconds(clip.duration.ticks),
-        mediaType: clip.mediaType
-      });
-    }
-  }
-
-  for (var t = 0; t < seq.audioTracks.numTracks; t++) {
-    var track = seq.audioTracks[t];
-    for (var c = 0; c < track.clips.numItems; c++) {
-      var clip = track.clips[c];
-      clips.push({
-        nodeId: clip.nodeId,
-        name: clip.name,
-        trackIndex: t,
-        trackType: "audio",
-        inPoint: __ticksToSeconds(clip.inPoint.ticks),
-        outPoint: __ticksToSeconds(clip.outPoint.ticks),
-        start: __ticksToSeconds(clip.start.ticks),
-        end: __ticksToSeconds(clip.end.ticks),
-        duration: __ticksToSeconds(clip.duration.ticks),
-        mediaType: clip.mediaType
-      });
-    }
-  }
-
-  return clips;
-}
-
-// Recursively coerce undefined to null in an object tree so that the result
-// can be passed to ExtendScript's JSON.stringify safely. ExtendScript's
-// JSON.stringify (a) does not honor the 'replacer' parameter and (b) emits the
-// bare token 'undefined' for undefined values, which is invalid JSON and
-// crashes the CEP-side JSON.parse. Pre-sanitizing is the only reliable fix.
-function __sanitizeForJSON(obj) {
-  if (obj === undefined || obj === null) return null;
-  // ExtendScript also emits NaN / Infinity literals which are not valid JSON.
-  // Coerce them to null so the CEP-side JSON.parse always succeeds.
-  if (typeof obj === "number") {
-    if (isNaN(obj) || obj === Infinity || obj === -Infinity) return null;
-    return obj;
-  }
-  if (typeof obj !== "object") return obj;
-  if (obj instanceof Array) {
-    var arr = [];
-    for (var i = 0; i < obj.length; i++) arr.push(__sanitizeForJSON(obj[i]));
-    return arr;
-  }
-  // Don't recurse into Premiere host objects (Time, ProjectItem, etc.) — they
-  // serialize as [object Object] and have inaccessible internals. Detect them
-  // by lack of plain-object constructor.
-  try {
-    if (obj.constructor && obj.constructor !== Object && obj.constructor !== Array) {
-      // For host objects, fall back to their toString / accessible primitive
-      return obj.toString ? String(obj.toString()) : "[object]";
-    }
-  } catch (e) { /* fall through */ }
-  var out = {};
-  for (var k in obj) {
-    if (obj.hasOwnProperty(k)) out[k] = __sanitizeForJSON(obj[k]);
-  }
-  return out;
-}
-
-function __jsonStringify(obj) {
-  // ES3-compatible JSON stringify. ExtendScript's JSON.stringify emits the
-  // literal token 'undefined' for undefined values (vs Node/Browser which omit
-  // them) AND ignores the replacer parameter, making the produced string
-  // invalid JSON and crashing the CEP-side JSON.parse. Sanitize first.
-  if (typeof JSON !== "undefined" && JSON.stringify) {
-    return JSON.stringify(__sanitizeForJSON(obj));
-  }
-  // Fallback for very old ExtendScript
-  if (obj === null) return "null";
-  if (obj === undefined) return "undefined";
-  if (typeof obj === "string") return '"' + obj.replace(/\\\\/g, "\\\\\\\\").replace(/"/g, '\\\\"').replace(/\\n/g, "\\\\n") + '"';
-  if (typeof obj === "number" || typeof obj === "boolean") return String(obj);
-  if (obj instanceof Array) {
-    var arr = [];
-    for (var i = 0; i < obj.length; i++) {
-      arr.push(__jsonStringify(obj[i]));
-    }
-    return "[" + arr.join(",") + "]";
-  }
-  if (typeof obj === "object") {
-    var parts = [];
-    for (var k in obj) {
-      if (obj.hasOwnProperty(k)) {
-        parts.push(__jsonStringify(k) + ":" + __jsonStringify(obj[k]));
-      }
-    }
-    return "{" + parts.join(",") + "}";
-  }
-  return String(obj);
-}
-
-function __result(data) {
-  return __jsonStringify({ success: true, data: data });
-}
-
-function __error(msg) {
-  return __jsonStringify({ success: false, error: String(msg) });
-}
-
-// --- Locale & version resilient lookups -------------------------------------
-
-// Candidate matchNames for Premiere's intrinsic (fixed) effects. matchName is
-// locale-INDEPENDENT, so trying these first makes tools work on any language
-// install. displayName fallbacks are language-specific and only a last resort.
-var __INTRINSIC = {
-  motion:   { match: ["AE.ADBE Motion", "ADBE Motion", "motionControlEffect"], display: ["Motion", "Movimiento", "Bewegung", "Mouvement"] },
-  opacity:  { match: ["AE.ADBE Opacity", "ADBE Opacity", "opacityEffect"], display: ["Opacity", "Opacidad", "Deckkraft", "Opacité"] },
-  volume:   { match: ["AE.ADBE Audio Levels", "audioVolume", "audioGain", "ADBE Audio Levels"], display: ["Volume", "Volumen", "Lautstärke"] },
-  panner:   { match: ["AE.ADBE Pan", "audioPanner", "ADBE Pan"], display: ["Panner", "Panoramización", "Balance"] },
-  lumetri:  { match: ["AE.ADBE Lumetri", "ADBE Lumetri", "PR.ADBE Lumetri"], display: ["Lumetri Color", "Color Lumetri", "Lumetri-Farbe"] },
-  timeRemap:{ match: ["AE.ADBE Time Remapping", "ADBE Time Remapping"], display: ["Time Remapping", "Reasignación de tiempo"] }
-};
-
-// Find a component on a clip by trying matchName candidates then displayName candidates.
-// matchNames/displayNames are arrays of strings. Returns the component or null.
-function __findComponent(clip, matchNames, displayNames) {
-  if (!clip || !clip.components) return null;
-  var i, c, k;
-  if (matchNames) {
-    for (i = 0; i < clip.components.numItems; i++) {
-      c = clip.components[i];
-      for (k = 0; k < matchNames.length; k++) {
-        if (c.matchName === matchNames[k]) return c;
-      }
-    }
-  }
-  if (displayNames) {
-    for (i = 0; i < clip.components.numItems; i++) {
-      c = clip.components[i];
-      for (k = 0; k < displayNames.length; k++) {
-        if (c.displayName === displayNames[k]) return c;
-      }
-    }
-  }
-  return null;
-}
-
-// Shorthand: find an intrinsic component by key from the __INTRINSIC table.
-function __findIntrinsic(clip, key) {
-  var def = __INTRINSIC[key];
-  if (!def) return null;
-  return __findComponent(clip, def.match, def.display);
-}
-
-// Find a property inside a component by displayName candidates, descending one
-// level into nested property groups (needed for Lumetri's grouped params).
-function __findProp(comp, names) {
-  if (!comp || !comp.properties) return null;
-  var p, n, prop, sp, sub;
-  for (p = 0; p < comp.properties.numItems; p++) {
-    prop = comp.properties[p];
-    for (n = 0; n < names.length; n++) {
-      if (prop.displayName === names[n]) return prop;
-    }
-  }
-  // second pass: nested groups
-  for (p = 0; p < comp.properties.numItems; p++) {
-    prop = comp.properties[p];
-    if (prop.properties && prop.properties.numItems) {
-      for (sp = 0; sp < prop.properties.numItems; sp++) {
-        sub = prop.properties[sp];
-        for (n = 0; n < names.length; n++) {
-          if (sub.displayName === names[n]) return sub;
-        }
-      }
-    }
-  }
-  return null;
-}
-
-// Locale-aware aliases for common Premiere Pro transition names. matchName
-// would be ideal but QE's transition objects don't reliably expose it, so we
-// map the English canonical name to localized displayNames seen in the wild.
-var __TRANSITION_ALIASES = {
-  "Cross Dissolve":      ["Cross Dissolve", "Disolvencia cruzada", "Fondu enchaîné", "Weiche Blende"],
-  "Dip to Black":        ["Dip to Black", "Inmersión a negro", "Fondu au noir", "Schwarzblende"],
-  "Dip to White":        ["Dip to White", "Inmersión a blanco", "Fondu au blanc", "Weißblende"],
-  "Film Dissolve":       ["Film Dissolve", "Disolvencia de película"],
-  "Additive Dissolve":   ["Additive Dissolve", "Disolvencia aditiva"],
-  "Morph Cut":           ["Morph Cut", "Corte por transformación"],
-  "Constant Power":      ["Constant Power", "Potencia constante"],
-  "Constant Gain":       ["Constant Gain", "Ganancia constante"],
-  "Exponential Fade":    ["Exponential Fade", "Fundido exponencial"]
-};
-
-// Resolve a transition by name from a QE transition list, locale-resilient.
-// First tries qe.project.getVideoTransitionByName / getAudioTransitionByName,
-// then iterates the list matching the requested name OR any localized alias.
-// kind: "video" | "audio". Returns the QE transition object or null.
-function __findTransition(name, kind) {
-  try { app.enableQE(); } catch (e) {}
-  if (typeof qe === "undefined" || !qe.project) return null;
-  var direct = null;
-  try {
-    if (kind === "audio" && qe.project.getAudioTransitionByName) {
-      direct = qe.project.getAudioTransitionByName(name);
-    } else if (qe.project.getVideoTransitionByName) {
-      direct = qe.project.getVideoTransitionByName(name);
-    }
-  } catch (e) {}
-  if (direct) return direct;
-  var list = null;
-  try {
-    list = (kind === "audio") ? qe.project.getAudioTransitionList() : qe.project.getVideoTransitionList();
-  } catch (e) { list = null; }
-  if (!list || !list.numItems) return null;
-  // Candidate names: the requested name, plus aliases for it (forward map),
-  // plus the canonical name if the request matches any alias (reverse map).
-  var candidates = [name];
-  var k, j, aliases;
-  if (__TRANSITION_ALIASES[name]) {
-    aliases = __TRANSITION_ALIASES[name];
-    for (j = 0; j < aliases.length; j++) candidates.push(aliases[j]);
-  }
-  for (k in __TRANSITION_ALIASES) {
-    if (__TRANSITION_ALIASES.hasOwnProperty(k)) {
-      aliases = __TRANSITION_ALIASES[k];
-      for (j = 0; j < aliases.length; j++) {
-        if (aliases[j] === name) {
-          candidates.push(k);
-          for (var jj = 0; jj < aliases.length; jj++) candidates.push(aliases[jj]);
-        }
-      }
-    }
-  }
-  for (var i = 0; i < list.numItems; i++) {
-    var t = list[i];
-    var tName = t.name;
-    var tMatch = t.matchName;
-    for (var c = 0; c < candidates.length; c++) {
-      if (tName === candidates[c]) return t;
-      if (tMatch && tMatch === candidates[c]) return t;
-    }
-  }
-  return null;
-}
-
-// Resolve an ID that could be either a project item nodeId/name OR a timeline
-// clip nodeId, to a ProjectItem. Used by tools whose schema says "project item
-// node_id or name" but where callers commonly pass timeline clip nodeIds
-// (which come from get_active_sequence / list_sequence_tracks).
-// Returns the ProjectItem or null.
-function __resolveProjectItemOrTimelineClip(idOrName) {
-  if (!idOrName) return null;
-  // First try the project tree
-  var pi = __findProjectItem(idOrName);
-  if (pi) return pi;
-  // Fall back: treat as timeline clip nodeId, resolve to its projectItem
-  try {
-    var r = __findClip(idOrName);
-    if (r && r.clip && r.clip.projectItem) return r.clip.projectItem;
-  } catch (e) {}
-  return null;
-}
-
-// Read a member that some Premiere versions expose as a property and others as
-// a zero-arg method (e.g. isMuted, isSelected, isOffline, isSequence). Returns
-// the resolved value, or the provided default if it cannot be read.
-function __readMaybe(obj, name, dflt) {
-  try {
-    var v = obj[name];
-    if (typeof v === "function") return v.call(obj);
-    if (v === undefined) return dflt;
-    return v;
-  } catch(e) { return dflt; }
-}
-
-// === End MCP Bridge Helpers ===
+const HELPERS = `
+// === MCP Bridge Helpers (auto-prepended) ===
+
+var TICKS_PER_SECOND = 254016000000;
+
+function __ticksToSeconds(ticks) {
+  return parseFloat(ticks) / TICKS_PER_SECOND;
+}
+
+function __secondsToTicks(seconds) {
+  return Math.round(parseFloat(seconds) * TICKS_PER_SECOND);
+}
+
+function __ticksToTimecode(ticks, fps) {
+  var totalSeconds = __ticksToSeconds(ticks);
+  var hours = Math.floor(totalSeconds / 3600);
+  var minutes = Math.floor((totalSeconds % 3600) / 60);
+  var secs = Math.floor(totalSeconds % 60);
+  var frames = Math.floor((totalSeconds % 1) * fps);
+  return __pad(hours) + ":" + __pad(minutes) + ":" + __pad(secs) + ":" + __pad(frames);
+}
+
+function __pad(n) {
+  return n < 10 ? "0" + n : "" + n;
+}
+
+function __findSequence(idOrName) {
+  var project = app.project;
+  for (var i = 0; i < project.sequences.numSequences; i++) {
+    var seq = project.sequences[i];
+    if (seq.sequenceID === idOrName || seq.name === idOrName) {
+      return seq;
+    }
+  }
+  return null;
+}
+
+function __findProjectItem(nodeIdOrName, rootItem) {
+  if (!rootItem) rootItem = app.project.rootItem;
+  for (var i = 0; i < rootItem.children.numItems; i++) {
+    var item = rootItem.children[i];
+    if (item.nodeId === nodeIdOrName || item.name === nodeIdOrName) {
+      return item;
+    }
+    if (item.type === 2) { // Bin
+      var found = __findProjectItem(nodeIdOrName, item);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function __findClip(nodeId) {
+  var seq = app.project.activeSequence;
+  if (!seq) return null;
+
+  // Search video tracks
+  for (var t = 0; t < seq.videoTracks.numTracks; t++) {
+    var track = seq.videoTracks[t];
+    for (var c = 0; c < track.clips.numItems; c++) {
+      var clip = track.clips[c];
+      if (clip.nodeId === nodeId) {
+        return { clip: clip, trackIndex: t, clipIndex: c, trackType: "video" };
+      }
+    }
+  }
+
+  // Search audio tracks
+  for (var t = 0; t < seq.audioTracks.numTracks; t++) {
+    var track = seq.audioTracks[t];
+    for (var c = 0; c < track.clips.numItems; c++) {
+      var clip = track.clips[c];
+      if (clip.nodeId === nodeId) {
+        return { clip: clip, trackIndex: t, clipIndex: c, trackType: "audio" };
+      }
+    }
+  }
+
+  return null;
+}
+
+function __getAllClips(seq) {
+  if (!seq) seq = app.project.activeSequence;
+  if (!seq) return [];
+  var clips = [];
+
+  for (var t = 0; t < seq.videoTracks.numTracks; t++) {
+    var track = seq.videoTracks[t];
+    for (var c = 0; c < track.clips.numItems; c++) {
+      var clip = track.clips[c];
+      clips.push({
+        nodeId: clip.nodeId,
+        name: clip.name,
+        trackIndex: t,
+        trackType: "video",
+        inPoint: __ticksToSeconds(clip.inPoint.ticks),
+        outPoint: __ticksToSeconds(clip.outPoint.ticks),
+        start: __ticksToSeconds(clip.start.ticks),
+        end: __ticksToSeconds(clip.end.ticks),
+        duration: __ticksToSeconds(clip.duration.ticks),
+        mediaType: clip.mediaType
+      });
+    }
+  }
+
+  for (var t = 0; t < seq.audioTracks.numTracks; t++) {
+    var track = seq.audioTracks[t];
+    for (var c = 0; c < track.clips.numItems; c++) {
+      var clip = track.clips[c];
+      clips.push({
+        nodeId: clip.nodeId,
+        name: clip.name,
+        trackIndex: t,
+        trackType: "audio",
+        inPoint: __ticksToSeconds(clip.inPoint.ticks),
+        outPoint: __ticksToSeconds(clip.outPoint.ticks),
+        start: __ticksToSeconds(clip.start.ticks),
+        end: __ticksToSeconds(clip.end.ticks),
+        duration: __ticksToSeconds(clip.duration.ticks),
+        mediaType: clip.mediaType
+      });
+    }
+  }
+
+  return clips;
+}
+
+// Recursively coerce undefined to null in an object tree so that the result
+// can be passed to ExtendScript's JSON.stringify safely. ExtendScript's
+// JSON.stringify (a) does not honor the 'replacer' parameter and (b) emits the
+// bare token 'undefined' for undefined values, which is invalid JSON and
+// crashes the CEP-side JSON.parse. Pre-sanitizing is the only reliable fix.
+function __sanitizeForJSON(obj) {
+  if (obj === undefined || obj === null) return null;
+  // ExtendScript also emits NaN / Infinity literals which are not valid JSON.
+  // Coerce them to null so the CEP-side JSON.parse always succeeds.
+  if (typeof obj === "number") {
+    if (isNaN(obj) || obj === Infinity || obj === -Infinity) return null;
+    return obj;
+  }
+  if (typeof obj !== "object") return obj;
+  if (obj instanceof Array) {
+    var arr = [];
+    for (var i = 0; i < obj.length; i++) arr.push(__sanitizeForJSON(obj[i]));
+    return arr;
+  }
+  // Don't recurse into Premiere host objects (Time, ProjectItem, etc.) — they
+  // serialize as [object Object] and have inaccessible internals. Detect them
+  // by lack of plain-object constructor.
+  try {
+    if (obj.constructor && obj.constructor !== Object && obj.constructor !== Array) {
+      // For host objects, fall back to their toString / accessible primitive
+      return obj.toString ? String(obj.toString()) : "[object]";
+    }
+  } catch (e) { /* fall through */ }
+  var out = {};
+  for (var k in obj) {
+    if (obj.hasOwnProperty(k)) out[k] = __sanitizeForJSON(obj[k]);
+  }
+  return out;
+}
+
+function __jsonStringify(obj) {
+  // ES3-compatible JSON stringify. ExtendScript's JSON.stringify emits the
+  // literal token 'undefined' for undefined values (vs Node/Browser which omit
+  // them) AND ignores the replacer parameter, making the produced string
+  // invalid JSON and crashing the CEP-side JSON.parse. Sanitize first.
+  if (typeof JSON !== "undefined" && JSON.stringify) {
+    return JSON.stringify(__sanitizeForJSON(obj));
+  }
+  // Fallback for very old ExtendScript
+  if (obj === null) return "null";
+  if (obj === undefined) return "undefined";
+  if (typeof obj === "string") return '"' + obj.replace(/\\\\/g, "\\\\\\\\").replace(/"/g, '\\\\"').replace(/\\n/g, "\\\\n") + '"';
+  if (typeof obj === "number" || typeof obj === "boolean") return String(obj);
+  if (obj instanceof Array) {
+    var arr = [];
+    for (var i = 0; i < obj.length; i++) {
+      arr.push(__jsonStringify(obj[i]));
+    }
+    return "[" + arr.join(",") + "]";
+  }
+  if (typeof obj === "object") {
+    var parts = [];
+    for (var k in obj) {
+      if (obj.hasOwnProperty(k)) {
+        parts.push(__jsonStringify(k) + ":" + __jsonStringify(obj[k]));
+      }
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  return String(obj);
+}
+
+function __result(data) {
+  return __jsonStringify({ success: true, data: data });
+}
+
+function __error(msg) {
+  return __jsonStringify({ success: false, error: String(msg) });
+}
+
+// --- Locale & version resilient lookups -------------------------------------
+
+// Candidate matchNames for Premiere's intrinsic (fixed) effects. matchName is
+// locale-INDEPENDENT, so trying these first makes tools work on any language
+// install. displayName fallbacks are language-specific and only a last resort.
+var __INTRINSIC = {
+  motion:   { match: ["AE.ADBE Motion", "ADBE Motion", "motionControlEffect"], display: ["Motion", "Movimiento", "Bewegung", "Mouvement"] },
+  opacity:  { match: ["AE.ADBE Opacity", "ADBE Opacity", "opacityEffect"], display: ["Opacity", "Opacidad", "Deckkraft", "Opacité"] },
+  volume:   { match: ["AE.ADBE Audio Levels", "audioVolume", "audioGain", "ADBE Audio Levels"], display: ["Volume", "Volumen", "Lautstärke"] },
+  panner:   { match: ["AE.ADBE Pan", "audioPanner", "ADBE Pan"], display: ["Panner", "Panoramización", "Balance"] },
+  lumetri:  { match: ["AE.ADBE Lumetri", "ADBE Lumetri", "PR.ADBE Lumetri"], display: ["Lumetri Color", "Color Lumetri", "Lumetri-Farbe"] },
+  timeRemap:{ match: ["AE.ADBE Time Remapping", "ADBE Time Remapping"], display: ["Time Remapping", "Reasignación de tiempo"] }
+};
+
+// Find a component on a clip by trying matchName candidates then displayName candidates.
+// matchNames/displayNames are arrays of strings. Returns the component or null.
+function __findComponent(clip, matchNames, displayNames) {
+  if (!clip || !clip.components) return null;
+  var i, c, k;
+  if (matchNames) {
+    for (i = 0; i < clip.components.numItems; i++) {
+      c = clip.components[i];
+      for (k = 0; k < matchNames.length; k++) {
+        if (c.matchName === matchNames[k]) return c;
+      }
+    }
+  }
+  if (displayNames) {
+    for (i = 0; i < clip.components.numItems; i++) {
+      c = clip.components[i];
+      for (k = 0; k < displayNames.length; k++) {
+        if (c.displayName === displayNames[k]) return c;
+      }
+    }
+  }
+  return null;
+}
+
+// Shorthand: find an intrinsic component by key from the __INTRINSIC table.
+function __findIntrinsic(clip, key) {
+  var def = __INTRINSIC[key];
+  if (!def) return null;
+  return __findComponent(clip, def.match, def.display);
+}
+
+// Find a property inside a component by displayName candidates, descending one
+// level into nested property groups (needed for Lumetri's grouped params).
+function __findProp(comp, names) {
+  if (!comp || !comp.properties) return null;
+  var p, n, prop, sp, sub;
+  for (p = 0; p < comp.properties.numItems; p++) {
+    prop = comp.properties[p];
+    for (n = 0; n < names.length; n++) {
+      if (prop.displayName === names[n]) return prop;
+    }
+  }
+  // second pass: nested groups
+  for (p = 0; p < comp.properties.numItems; p++) {
+    prop = comp.properties[p];
+    if (prop.properties && prop.properties.numItems) {
+      for (sp = 0; sp < prop.properties.numItems; sp++) {
+        sub = prop.properties[sp];
+        for (n = 0; n < names.length; n++) {
+          if (sub.displayName === names[n]) return sub;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// Locale-aware aliases for common Premiere Pro transition names. matchName
+// would be ideal but QE's transition objects don't reliably expose it, so we
+// map the English canonical name to localized displayNames seen in the wild.
+var __TRANSITION_ALIASES = {
+  "Cross Dissolve":      ["Cross Dissolve", "Disolvencia cruzada", "Fondu enchaîné", "Weiche Blende"],
+  "Dip to Black":        ["Dip to Black", "Inmersión a negro", "Fondu au noir", "Schwarzblende"],
+  "Dip to White":        ["Dip to White", "Inmersión a blanco", "Fondu au blanc", "Weißblende"],
+  "Film Dissolve":       ["Film Dissolve", "Disolvencia de película"],
+  "Additive Dissolve":   ["Additive Dissolve", "Disolvencia aditiva"],
+  "Morph Cut":           ["Morph Cut", "Corte por transformación"],
+  "Constant Power":      ["Constant Power", "Potencia constante"],
+  "Constant Gain":       ["Constant Gain", "Ganancia constante"],
+  "Exponential Fade":    ["Exponential Fade", "Fundido exponencial"]
+};
+
+// Resolve a transition by name from a QE transition list, locale-resilient.
+// First tries qe.project.getVideoTransitionByName / getAudioTransitionByName,
+// then iterates the list matching the requested name OR any localized alias.
+// kind: "video" | "audio". Returns the QE transition object or null.
+function __findTransition(name, kind) {
+  try { app.enableQE(); } catch (e) {}
+  if (typeof qe === "undefined" || !qe.project) return null;
+  var direct = null;
+  try {
+    if (kind === "audio" && qe.project.getAudioTransitionByName) {
+      direct = qe.project.getAudioTransitionByName(name);
+    } else if (qe.project.getVideoTransitionByName) {
+      direct = qe.project.getVideoTransitionByName(name);
+    }
+  } catch (e) {}
+  if (direct) return direct;
+  var list = null;
+  try {
+    list = (kind === "audio") ? qe.project.getAudioTransitionList() : qe.project.getVideoTransitionList();
+  } catch (e) { list = null; }
+  if (!list || !list.numItems) return null;
+  // Candidate names: the requested name, plus aliases for it (forward map),
+  // plus the canonical name if the request matches any alias (reverse map).
+  var candidates = [name];
+  var k, j, aliases;
+  if (__TRANSITION_ALIASES[name]) {
+    aliases = __TRANSITION_ALIASES[name];
+    for (j = 0; j < aliases.length; j++) candidates.push(aliases[j]);
+  }
+  for (k in __TRANSITION_ALIASES) {
+    if (__TRANSITION_ALIASES.hasOwnProperty(k)) {
+      aliases = __TRANSITION_ALIASES[k];
+      for (j = 0; j < aliases.length; j++) {
+        if (aliases[j] === name) {
+          candidates.push(k);
+          for (var jj = 0; jj < aliases.length; jj++) candidates.push(aliases[jj]);
+        }
+      }
+    }
+  }
+  for (var i = 0; i < list.numItems; i++) {
+    var t = list[i];
+    var tName = t.name;
+    var tMatch = t.matchName;
+    for (var c = 0; c < candidates.length; c++) {
+      if (tName === candidates[c]) return t;
+      if (tMatch && tMatch === candidates[c]) return t;
+    }
+  }
+  return null;
+}
+
+// Resolve an ID that could be either a project item nodeId/name OR a timeline
+// clip nodeId, to a ProjectItem. Used by tools whose schema says "project item
+// node_id or name" but where callers commonly pass timeline clip nodeIds
+// (which come from get_active_sequence / list_sequence_tracks).
+// Returns the ProjectItem or null.
+function __resolveProjectItemOrTimelineClip(idOrName) {
+  if (!idOrName) return null;
+  // First try the project tree
+  var pi = __findProjectItem(idOrName);
+  if (pi) return pi;
+  // Fall back: treat as timeline clip nodeId, resolve to its projectItem
+  try {
+    var r = __findClip(idOrName);
+    if (r && r.clip && r.clip.projectItem) return r.clip.projectItem;
+  } catch (e) {}
+  return null;
+}
+
+// Read a member that some Premiere versions expose as a property and others as
+// a zero-arg method (e.g. isMuted, isSelected, isOffline, isSequence). Returns
+// the resolved value, or the provided default if it cannot be read.
+function __readMaybe(obj, name, dflt) {
+  try {
+    var v = obj[name];
+    if (typeof v === "function") return v.call(obj);
+    if (v === undefined) return dflt;
+    return v;
+  } catch(e) { return dflt; }
+}
+
+// === End MCP Bridge Helpers ===
 `;
 /**
  * Build a complete ExtendScript by wrapping user code in an IIFE with helpers.
  */
 export function buildScript(code) {
-    return `${HELPERS}
-(function() {
-  try {
-    ${code}
-  } catch(e) {
-    return __error(e.toString());
-  }
+    return `${HELPERS}
+(function() {
+  try {
+    ${code}
+  } catch(e) {
+    return __error(e.toString());
+  }
 })();`;
 }
 /**