premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/replace-clip-media.jsx

@@ -0,0 +1,140 @@
+// Command: replace-clip-media → ppb_replaceClipMedia
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use.
+//
+// Named after leancoderkavy's premiere-pro-mcp clipboard.ts
+// replace_clip_media, but DELIBERATELY implemented differently: that
+// reference tool's replace_clip_media is actually just a timeline
+// seq.overwriteClip() at a clip's start time with a different project
+// item — functionally identical to this panel's own pre-existing
+// replace-clip command (host/commands/replace-clip.jsx), which already
+// covers that behavior. Porting it again under a new name would just
+// duplicate replace-clip.
+//
+// Instead this command does what its name actually promises — replaces a
+// PROJECT ITEM's underlying media FILE via the item-level API
+// PREMIERE_API_NOTES.md documents: item.canChangeMediaPath() /
+// item.changeMediaPath(newPath, /*overrideChecks*/true). This swaps the
+// source file for every clip referencing that project item throughout the
+// whole project (not just one timeline clip), which is a materially
+// different and more powerful operation than replace-clip's per-clip
+// swap.
+//
+// Destructive-ish: undo is non-functional on this build (see the `undo`
+// command's notes) — previousMediaPath is the only path to manually
+// revert via a second call.
+function ppbFindItemReplaceClipMedia_walk(item, args, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  var isBin = false;
+  try {
+    isBin = typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    isBin = false;
+  }
+  var matched = false;
+  if (args.nodeId !== null) {
+    try { matched = item.nodeId === args.nodeId; } catch (e) { matched = false; }
+  } else if (args.name !== null) {
+    try { matched = item.name === args.name; } catch (e) { matched = false; }
+  }
+  if (matched) {
+    return item;
+  }
+  if (isBin && item.children) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbFindItemReplaceClipMedia_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemReplaceClipMedia_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemReplaceClipMedia_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_replaceClipMedia(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasNodeId = typeof args.nodeId === "string" && args.nodeId.length > 0;
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    if (!hasNodeId && !hasName) {
+      return JSON.stringify({ ok: false, error: "either nodeId or name is required to identify the project item" });
+    }
+    if (typeof args.newMediaPath !== "string" || !args.newMediaPath) {
+      return JSON.stringify({ ok: false, error: "newMediaPath is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = ppbFindItemReplaceClipMedia_resolve({
+      nodeId: hasNodeId ? args.nodeId : null,
+      name: hasNodeId ? null : args.name
+    });
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/name" });
+    }
+
+    var itemName = null;
+    var itemNodeId = null;
+    try { itemName = item.name; } catch (e2) { itemName = null; }
+    try { itemNodeId = item.nodeId; } catch (e3) { itemNodeId = null; }
+
+    var canChange = null;
+    try {
+      canChange = item.canChangeMediaPath();
+    } catch (e4) {
+      canChange = null;
+    }
+    if (canChange === false) {
+      return JSON.stringify({ ok: false, error: "item.canChangeMediaPath() returned false — this item's media path cannot be changed", name: itemName, nodeId: itemNodeId });
+    }
+
+    var previousMediaPath = null;
+    try { previousMediaPath = item.getMediaPath(); } catch (e5) { previousMediaPath = null; }
+
+    try {
+      item.changeMediaPath(args.newMediaPath, true);
+    } catch (e6) {
+      return JSON.stringify({ ok: false, error: "item.changeMediaPath() failed: " + e6.toString(), name: itemName, nodeId: itemNodeId, previousMediaPath: previousMediaPath });
+    }
+
+    var newMediaPath = null;
+    try { newMediaPath = item.getMediaPath(); } catch (e7) { newMediaPath = null; }
+
+    var verified = newMediaPath !== null && newMediaPath === args.newMediaPath;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        name: itemName,
+        nodeId: itemNodeId,
+        canChangeMediaPath: canChange,
+        previousMediaPath: previousMediaPath,
+        requestedMediaPath: args.newMediaPath,
+        newMediaPath: newMediaPath,
+        verified: verified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/replace-clip.jsx

@@ -0,0 +1,188 @@
+// Command: replace-clip → ppb_replaceClip
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// resolveTimelineClip, serializeTrackItem, secondsToTicksString,
+// timeValueToSeconds, ...) are already defined there.
+//
+// DESTRUCTIVE: removes the addressed clip (clip.remove(false, false) —
+// lift, not ripple, so the timeline position it occupied is preserved)
+// and re-inserts the replacement projectItem at that same start time via
+// seq.insertClip() — ported from leancoderkavy's premiere-pro-mcp
+// replace_clip tool, re-addressed to this panel's
+// trackType/trackIndex/clipIndex convention and given its own project-
+// item addressing (nodeId/name) for the replacement, matching
+// get-item-metadata's convention. Undo is NON-FUNCTIONAL on this build —
+// if the replacement projectItem is wrong, the ORIGINAL clip's own
+// details (returned as `before`) are the only path to manually reinsert
+// it.
+//
+// MUTATION RULE: verified by re-finding a clip at the same start time on
+// the same track afterward and confirming its projectItem's name/media
+// path changed to the replacement's.
+
+function ppbFindItemReplaceClip_walk(item, args, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  var isBin = false;
+  try {
+    isBin = typeof ProjectItemType !== "undefined" && item.type === ProjectItemType.BIN;
+  } catch (e) {
+    isBin = false;
+  }
+  var matched = false;
+  if (args.nodeId !== null) {
+    try { matched = item.nodeId === args.nodeId; } catch (e) { matched = false; }
+  } else if (args.name !== null) {
+    try { matched = item.name === args.name; } catch (e) { matched = false; }
+  }
+  if (matched) {
+    return item;
+  }
+  if (isBin && item.children) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbFindItemReplaceClip_walk(item.children[i], args, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbFindItemReplaceClip_resolve(args) {
+  var root = app.project.rootItem;
+  for (var i = 0; i < root.children.numItems; i++) {
+    var found = ppbFindItemReplaceClip_walk(root.children[i], args, 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function ppb_replaceClip(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (args.trackType !== "video" && args.trackType !== "audio") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" or \"audio\"" });
+    }
+    if (typeof args.trackIndex !== "number" || typeof args.clipIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "trackIndex and clipIndex are required" });
+    }
+    var hasNodeId = typeof args.replacementNodeId === "string" && args.replacementNodeId.length > 0;
+    var hasName = typeof args.replacementName === "string" && args.replacementName.length > 0;
+    if (!hasNodeId && !hasName) {
+      return JSON.stringify({ ok: false, error: "either replacementNodeId or replacementName is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var seq = null;
+    if (args.sequenceName && typeof args.sequenceName === "string") {
+      seq = findSequenceByName(args.sequenceName);
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no sequence named \"" + args.sequenceName + "\" is open" });
+      }
+    } else {
+      seq = app.project.activeSequence;
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no active sequence, and no sequenceName given" });
+      }
+    }
+
+    var resolved = resolveTimelineClip(seq, args.trackType, args.trackIndex, args.clipIndex);
+    if (resolved.error) {
+      return JSON.stringify({ ok: false, error: resolved.error });
+    }
+    var clip = resolved.clip;
+
+    var replacementItem = ppbFindItemReplaceClip_resolve({
+      nodeId: hasNodeId ? args.replacementNodeId : null,
+      name: hasNodeId ? null : args.replacementName
+    });
+    if (!replacementItem) {
+      return JSON.stringify({ ok: false, error: "no replacement project item found matching the given replacementNodeId/replacementName" });
+    }
+
+    var before = serializeTrackItem(clip, args.trackIndex, args.clipIndex);
+    if (before.startSeconds === null) {
+      return JSON.stringify({ ok: false, error: "could not read the clip's own start time — refusing to remove it without a safe reinsertion point", removedClip: null });
+    }
+    var startSeconds = before.startSeconds;
+
+    var trackCollection = args.trackType === "video" ? seq.videoTracks : seq.audioTracks;
+    var track = trackCollection[args.trackIndex];
+
+    try {
+      clip.remove(false, false);
+    } catch (e2) {
+      return JSON.stringify({ ok: false, error: "clip.remove() failed while removing the original clip: " + e2.toString(), previousValue: before });
+    }
+
+    var vIdx = args.trackType === "video" ? args.trackIndex : -1;
+    var aIdx = args.trackType === "audio" ? args.trackIndex : -1;
+    var startTicks = secondsToTicksString(startSeconds);
+
+    try {
+      seq.insertClip(replacementItem, startTicks, vIdx, aIdx);
+    } catch (e3) {
+      return JSON.stringify({
+        ok: false,
+        error: "the original clip was already removed but seq.insertClip() of the replacement failed: " + e3.toString() + " — the track now has a gap; previousValue below is the only path to manually reinsert the original",
+        previousValue: before
+      });
+    }
+
+    var replacementNodeId = null;
+    try { replacementNodeId = replacementItem.nodeId; } catch (e4) { replacementNodeId = null; }
+
+    var newClip = null;
+    var toleranceSeconds = 0.1;
+    try {
+      for (var c = 0; c < track.clips.numItems; c++) {
+        var candidate = track.clips[c];
+        var candNodeId = null;
+        try { candNodeId = candidate.projectItem.nodeId; } catch (e5) { candNodeId = null; }
+        if (candNodeId !== replacementNodeId) {
+          continue;
+        }
+        var candStart = null;
+        try { candStart = timeValueToSeconds(candidate.start); } catch (e6) { candStart = null; }
+        if (candStart !== null && Math.abs(candStart - startSeconds) <= toleranceSeconds) {
+          newClip = serializeTrackItem(candidate, args.trackIndex, c);
+          break;
+        }
+      }
+    } catch (e7) {
+      newClip = null;
+    }
+
+    var verified = newClip !== null && newClip.mediaPath !== null &&
+      (function () { try { return newClip.mediaPath === replacementItem.getMediaPath(); } catch (e) { return false; } })();
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: args.trackType,
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        previousValue: before,
+        newValue: newClip,
+        replacementItem: { name: (function () { try { return replacementItem.name; } catch (e) { return null; } })(), nodeId: replacementNodeId },
+        verified: verified
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/reverse-clip.jsx

@@ -0,0 +1,187 @@
+// Command: reverse-clip → ppb_reverseClip
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ensureQEEnabled, activateSequenceForQE, resolveTimelineClip,
+// resolveQeClip, TICKS_PER_SECOND, ...) are already defined there.
+//
+// Reverses (or un-reverses) a clip's playback direction. REWRITTEN
+// 2026-07-17 after the probe session (see BUILD_FINDINGS.md corrections):
+// the working route on this build is the live-calibrated 5-arg
+//   qeClip.setSpeed(speedMultiplier, ticksString, reverse, false, false)
+// whose THIRD argument is the reverse flag (verified via
+// isSpeedReversed()). Negative speeds do NOT reverse — they clamp to a
+// degenerate state — so the current speed magnitude is preserved and
+// only the flag flips. setReverse() is still tried first in case a
+// future build grows it (it did not exist on 26.3.0).
+//
+// getSpeed()/setSpeed speeds are MULTIPLIERS on this build (1 = 100%).
+// Verified via the standard DOM's clip.isSpeedReversed() read-back —
+// never via either QE call's own return value.
+
+function ppb_reverseClip(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (args.trackType !== "video" && args.trackType !== "audio") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" or \"audio\"" });
+    }
+    if (typeof args.trackIndex !== "number" || args.trackIndex < 0 || Math.floor(args.trackIndex) !== args.trackIndex) {
+      return JSON.stringify({ ok: false, error: "trackIndex must be a non-negative integer" });
+    }
+    if (typeof args.clipIndex !== "number" || args.clipIndex < 0 || Math.floor(args.clipIndex) !== args.clipIndex) {
+      return JSON.stringify({ ok: false, error: "clipIndex must be a non-negative integer" });
+    }
+    var reverse = args.reverse !== false; // default true, matching the reference tool
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var seq = null;
+    if (args.sequenceName && typeof args.sequenceName === "string") {
+      seq = findSequenceByName(args.sequenceName);
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no sequence named \"" + args.sequenceName + "\" is open" });
+      }
+    } else {
+      seq = app.project.activeSequence;
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no active sequence, and no sequenceName given" });
+      }
+    }
+
+    var resolved = resolveTimelineClip(seq, args.trackType, args.trackIndex, args.clipIndex);
+    if (resolved.error) {
+      return JSON.stringify({ ok: false, error: resolved.error });
+    }
+    var clip = resolved.clip;
+    var clipName = null;
+    try { clipName = clip.name; } catch (e) { clipName = null; }
+
+    var previousReversed = null;
+    try { previousReversed = clip.isSpeedReversed() == 1; } catch (e) { previousReversed = null; }
+    var previousSpeed = null;
+    try { previousSpeed = clip.getSpeed(); } catch (e) { previousSpeed = null; }
+
+    if (previousReversed === reverse) {
+      return JSON.stringify({
+        ok: true,
+        result: {
+          sequenceName: seq.name,
+          trackType: args.trackType,
+          trackIndex: args.trackIndex,
+          clipIndex: args.clipIndex,
+          clipName: clipName,
+          requestedReversed: reverse,
+          previousReversed: previousReversed,
+          newReversed: previousReversed,
+          alreadyInRequestedState: true,
+          verified: true
+        }
+      });
+    }
+
+    // setSpeed's ticks argument must be a plausible value — the clip's
+    // own current timeline duration (garbage there collapses the clip to
+    // one frame, per the calibration notes).
+    var durTicks = null;
+    try {
+      durTicks = String(Math.round((clip.end.seconds - clip.start.seconds) * TICKS_PER_SECOND));
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "could not read the clip's duration for setSpeed's ticks argument: " + e.toString() });
+    }
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation failed: " + e.toString() });
+    }
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available after enableQE()" });
+    }
+
+    var qeSeq;
+    try {
+      qeSeq = qe.project.getActiveSequence();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() failed: " + e.toString() });
+    }
+    var qeResolved = resolveQeClip(qeSeq, args.trackType, args.trackIndex, args.clipIndex);
+    if (qeResolved.error) {
+      return JSON.stringify({ ok: false, error: qeResolved.error });
+    }
+    var qeClip = qeResolved.qeClip;
+
+    var attempts = [];
+    var succeeded = false;
+    var formUsed = null;
+
+    // setReverse() did not exist on 26.3.0 — kept as a cheap first probe
+    // in case a future build grows it.
+    if (typeof qeClip.setReverse === "function") {
+      try {
+        qeClip.setReverse(reverse);
+        attempts.push({ form: "setReverse(bool)", success: true });
+        succeeded = true;
+        formUsed = "setReverse(bool)";
+      } catch (e) {
+        attempts.push({ form: "setReverse(bool)", success: false, error: e.toString() });
+      }
+    }
+
+    if (!succeeded && typeof qeClip.setSpeed === "function") {
+      // preserve the current speed magnitude; getSpeed() is a multiplier
+      var magnitude = (previousSpeed !== null && previousSpeed !== 0) ? Math.abs(previousSpeed) : 1;
+      try {
+        qeClip.setSpeed(magnitude, durTicks, reverse, false, false);
+        attempts.push({ form: "setSpeed(multiplier, ticksString, reverse, false, false)", success: true });
+        succeeded = true;
+        formUsed = "setSpeed(multiplier, ticksString, reverse, false, false)";
+      } catch (e) {
+        attempts.push({ form: "setSpeed(multiplier, ticksString, reverse, false, false)", success: false, error: e.toString() });
+      }
+    }
+
+    if (!succeeded) {
+      return JSON.stringify({
+        ok: false,
+        error: "could not reverse the clip with setReverse() or the calibrated setSpeed() form",
+        attempts: attempts
+      });
+    }
+
+    var newReversed = null;
+    try { newReversed = clip.isSpeedReversed() == 1; } catch (e) { newReversed = null; }
+    var newSpeed = null;
+    try { newSpeed = clip.getSpeed(); } catch (e) { newSpeed = null; }
+
+    var result = {
+      sequenceName: seq.name,
+      trackType: args.trackType,
+      trackIndex: args.trackIndex,
+      clipIndex: args.clipIndex,
+      clipName: clipName,
+      requestedReversed: reverse,
+      formUsed: formUsed,
+      attempts: attempts,
+      previousReversed: previousReversed,
+      newReversed: newReversed,
+      previousSpeed: previousSpeed,
+      newSpeed: newSpeed,
+      verified: newReversed === reverse
+    };
+    if (newReversed === null) {
+      result.note = "clip.isSpeedReversed() was not readable on this build — the QE call did not throw, but the result is unverified.";
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/ripple-delete-clip.jsx

@@ -0,0 +1,156 @@
+// Command: ripple-delete-clip → ppb_rippleDeleteClip
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// ensureQEEnabled, activateSequenceForQE, resolveTimelineClip,
+// resolveQeClip, serializeTrackItem, ...) are already defined there.
+//
+// **Destructive.** Ripple-deletes ONE clip (removes it and closes the
+// gap, shifting later clips earlier) — the single-clip counterpart of
+// remove-track-intervals' batch interval removal. Ported from
+// leancoderkavy's premiere-pro-mcp `ripple_delete` tool (advanced.ts),
+// which calls `qeClip.rippleDelete()` unconditionally and trusts it.
+// Per this bridge's MUTATION RULE, success is instead judged the same way
+// remove-track-intervals' findAndRemoveInRange does: an actual numItems
+// drop on the QE track, with a `remove(bool, bool)` attempts fallback if
+// rippleDelete() didn't move the needle (both calls are unreliable in
+// practice on this build — neither's own return value nor the absence of
+// a thrown exception is trustworthy). Undo is non-functional on this
+// build (see README), so there is no way back from this command short of
+// re-inserting the clip's source media by hand.
+
+function ppb_rippleDeleteClip(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (args.trackType !== "video" && args.trackType !== "audio") {
+      return JSON.stringify({ ok: false, error: "trackType must be \"video\" or \"audio\"" });
+    }
+    if (typeof args.trackIndex !== "number" || args.trackIndex < 0 || Math.floor(args.trackIndex) !== args.trackIndex) {
+      return JSON.stringify({ ok: false, error: "trackIndex must be a non-negative integer" });
+    }
+    if (typeof args.clipIndex !== "number" || args.clipIndex < 0 || Math.floor(args.clipIndex) !== args.clipIndex) {
+      return JSON.stringify({ ok: false, error: "clipIndex must be a non-negative integer" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var seq = null;
+    if (args.sequenceName && typeof args.sequenceName === "string") {
+      seq = findSequenceByName(args.sequenceName);
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no sequence named \"" + args.sequenceName + "\" is open" });
+      }
+    } else {
+      seq = app.project.activeSequence;
+      if (!seq) {
+        return JSON.stringify({ ok: false, error: "no active sequence, and no sequenceName given" });
+      }
+    }
+
+    var resolved = resolveTimelineClip(seq, args.trackType, args.trackIndex, args.clipIndex);
+    if (resolved.error) {
+      return JSON.stringify({ ok: false, error: resolved.error });
+    }
+    var before = serializeTrackItem(resolved.clip, args.trackIndex, args.clipIndex);
+
+    try {
+      ensureQEEnabled();
+      activateSequenceForQE(seq);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE()/sequence activation failed: " + e.toString() });
+    }
+    if (typeof qe === "undefined" || !qe.project) {
+      return JSON.stringify({ ok: false, error: "QE DOM not available after enableQE()" });
+    }
+
+    var qeSeq;
+    try {
+      qeSeq = qe.project.getActiveSequence();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "qe.project.getActiveSequence() failed: " + e.toString() });
+    }
+    var qeResolved = resolveQeClip(qeSeq, args.trackType, args.trackIndex, args.clipIndex);
+    if (qeResolved.error) {
+      return JSON.stringify({ ok: false, error: qeResolved.error });
+    }
+    var qeClip = qeResolved.qeClip;
+    var qeTrack = qeResolved.qeTrack;
+
+    var previousItemCount = qeTrack.numItems;
+    var removed = false;
+    var method = null;
+
+    if (typeof qeClip.rippleDelete === "function") {
+      try {
+        qeClip.rippleDelete();
+      } catch (e) {
+        // fall through to the numItems check regardless — this call's
+        // own return value/thrown-ness is not trustworthy on this build
+      }
+      removed = qeTrack.numItems < previousItemCount;
+      if (removed) {
+        method = "rippleDelete";
+      }
+    }
+
+    if (!removed && typeof qeClip.remove === "function") {
+      // remove()'s two boolean params are undocumented — try plausible
+      // combinations, same fallback order as remove-track-intervals.
+      var attempts = [[true, false], [true, true], [false, true], [false, false]];
+      for (var a = 0; a < attempts.length && !removed; a++) {
+        var countBeforeAttempt = qeTrack.numItems;
+        try {
+          qeClip.remove(attempts[a][0], attempts[a][1]);
+        } catch (e) {
+          // fall through to the numItems check below regardless
+        }
+        if (qeTrack.numItems < countBeforeAttempt) {
+          removed = true;
+          method = "remove(" + attempts[a][0] + ", " + attempts[a][1] + ")";
+        }
+      }
+    }
+
+    var newItemCount = qeTrack.numItems;
+
+    if (!removed) {
+      return JSON.stringify({
+        ok: false,
+        error: "clip could not be ripple-deleted — neither rippleDelete() nor remove() with any boolean combination reduced the QE track's item count",
+        result: {
+          sequenceName: seq.name,
+          trackType: args.trackType,
+          trackIndex: args.trackIndex,
+          clipIndex: args.clipIndex,
+          clip: before,
+          previousItemCount: previousItemCount,
+          newItemCount: newItemCount
+        }
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        trackType: args.trackType,
+        trackIndex: args.trackIndex,
+        clipIndex: args.clipIndex,
+        removedClip: before,
+        method: method,
+        previousItemCount: previousItemCount,
+        newItemCount: newItemCount,
+        verified: newItemCount < previousItemCount
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}