premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/debug-qe-try-mutate.jsx

@@ -0,0 +1,305 @@
+// Command: debug-qe-try-mutate → ppb_debugQeTryMutate
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (ensureQEEnabled, ...)
+// are already defined there.
+//
+// TEMPORARY / EXPERIMENTAL — mutation test, not a supported panel feature.
+// Reflection (see ppb_debugQeInspect) revealed method NAMES on QE Clip
+// objects (remove, move, moveToTrack, ...) but no signatures — every
+// method's .reflect description/parameters came back empty on this build.
+// This tries a short list of plausible argument counts for `remove` and
+// `moveToTrack` against real clips and reports what happened, so the real
+// signature can be inferred from behavior instead of guessed blind.
+//
+// SAFETY GUARD: only runs if the *active* sequence's name exactly matches
+// args.sequenceName. Point this at a duplicate/throwaway sequence, never
+// at real project media — a wrong guess could ripple-shift or delete
+// clips on whatever sequence is active.
+function scanAudioClips(qeSeq, numAudioTracks) {
+  var clips = [];
+  var emptyTrackIndices = [];
+
+  for (var t = 0; t < numAudioTracks; t++) {
+    var track = qeSeq.getAudioTrackAt(t);
+    var numItems = track.numItems;
+    var allEmpty = true;
+
+    for (var i = 0; i < numItems; i++) {
+      var item = track.getItemAt(i);
+      if (item.type !== "Empty") {
+        allEmpty = false;
+        clips.push({ trackIndex: t, itemIndex: i, name: item.name, item: item });
+      }
+    }
+
+    if (allEmpty) {
+      emptyTrackIndices.push(t);
+    }
+  }
+
+  return { clips: clips, emptyTrackIndices: emptyTrackIndices };
+}
+
+function describeAudioTrack(qeSeq, trackIndex) {
+  var track = qeSeq.getAudioTrackAt(trackIndex);
+  var items = [];
+  for (var i = 0; i < track.numItems; i++) {
+    var item = track.getItemAt(i);
+    items.push({ index: i, type: item.type, name: item.type !== "Empty" ? item.name : "" });
+  }
+  return items;
+}
+
+function tryCallGuesses(fn, thisArg, guesses) {
+  var attempts = [];
+  var succeededWithArgs = null;
+
+  for (var g = 0; g < guesses.length; g++) {
+    var callArgs = guesses[g];
+    try {
+      fn.apply(thisArg, callArgs);
+      attempts.push({ args: describeArgsForLog(callArgs), success: true });
+      succeededWithArgs = describeArgsForLog(callArgs);
+      break;
+    } catch (e) {
+      attempts.push({ args: describeArgsForLog(callArgs), success: false, error: e.toString() });
+    }
+  }
+
+  return { attempts: attempts, succeededWithArgs: succeededWithArgs };
+}
+
+function describeArgsForLog(callArgs) {
+  var described = [];
+  for (var i = 0; i < callArgs.length; i++) {
+    var a = callArgs[i];
+    if (a && typeof a === "object" && typeof a.numItems !== "undefined") {
+      described.push("<Track>");
+    } else if (a && typeof a === "object" && typeof a.seconds !== "undefined") {
+      described.push("<Time seconds=" + a.seconds + ">");
+    } else {
+      described.push(a);
+    }
+  }
+  return described;
+}
+
+function ppb_debugQeTryMutate(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.sequenceName || typeof args.sequenceName !== "string") {
+      return JSON.stringify({ ok: false, error: "sequenceName is required (safety guard — must exactly match the active sequence's name)" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    try {
+      ensureQEEnabled();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.enableQE() 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() });
+    }
+
+    if (!qeSeq) {
+      return JSON.stringify({ ok: false, error: "no active sequence (open/select a sequence tab in Premiere)" });
+    }
+
+    if (qeSeq.name !== args.sequenceName) {
+      return JSON.stringify({
+        ok: false,
+        error: "active sequence is \"" + qeSeq.name + "\", expected \"" + args.sequenceName +
+          "\" — select the intended duplicate/test sequence's tab in Premiere before running this"
+      });
+    }
+
+    var numAudioTracks = qeSeq.numAudioTracks;
+    var scan = scanAudioClips(qeSeq, numAudioTracks);
+
+    if (scan.clips.length < 1) {
+      return JSON.stringify({
+        ok: true,
+        result: { note: "no audio clips found on any audio track — nothing to test on", numAudioTracks: numAudioTracks }
+      });
+    }
+
+    var result = { before: {}, removeTest: null, moveTest: null };
+    var skipRemoveTest = args.skipRemoveTest === true;
+    var removeTargetTrackIndex = null;
+
+    if (skipRemoveTest) {
+      result.removeTest = { skipped: true, reason: "skipRemoveTest was true" };
+    } else {
+      // --- remove() test ---
+      var removeTarget = scan.clips[0];
+      removeTargetTrackIndex = removeTarget.trackIndex;
+      result.before.removeTarget = { track: removeTarget.trackIndex, item: removeTarget.itemIndex, name: removeTarget.name };
+
+      var removeGuesses = [[], [true], [false], [true, true], [true, false], [false, true]];
+      var removeOutcome = tryCallGuesses(removeTarget.item.remove, removeTarget.item, removeGuesses);
+
+      result.removeTest = {
+        attempts: removeOutcome.attempts,
+        succeededWithArgs: removeOutcome.succeededWithArgs,
+        trackAfter: describeAudioTrack(qeSeq, removeTarget.trackIndex)
+      };
+    }
+
+    // --- moveToTrack() test — pick a clip on a DIFFERENT track than the
+    // remove target (if any), so the two tests don't interfere with each
+    // other's track-index bookkeeping.
+    var moveTarget = null;
+    for (var c = 0; c < scan.clips.length; c++) {
+      if (scan.clips[c].trackIndex !== removeTargetTrackIndex) {
+        moveTarget = scan.clips[c];
+        break;
+      }
+    }
+
+    if (!moveTarget) {
+      result.moveTest = { skipped: true, reason: "only one clip (or all clips on the same track) found; need a second clip on a distinct track" };
+      return JSON.stringify({ ok: true, result: result });
+    }
+
+    result.before.moveTarget = { track: moveTarget.trackIndex, item: moveTarget.itemIndex, name: moveTarget.name };
+
+    var destTrackIndex = null;
+    for (var e2 = 0; e2 < scan.emptyTrackIndices.length; e2++) {
+      if (scan.emptyTrackIndices[e2] !== moveTarget.trackIndex) {
+        destTrackIndex = scan.emptyTrackIndices[e2];
+        break;
+      }
+    }
+
+    if (destTrackIndex === null) {
+      result.moveTest = { skipped: true, reason: "no empty audio track available as a safe move destination" };
+      return JSON.stringify({ ok: true, result: result });
+    }
+
+    var destTrack = qeSeq.getAudioTrackAt(destTrackIndex);
+
+    // Prior runs: Track object at position 0 -> "Illegal Parameter type";
+    // plain number at position 0 with <3 total args -> "Not Enough
+    // Parameters" (count accepted, so a numeric track index IS the right
+    // type there). With >=3 plain-number/boolean args, every guess became
+    // "Illegal Parameter type" instead -- count is satisfied but some
+    // position now fails type-checking. Likely candidate: a "position"
+    // argument wants a real Time object, not a raw number. Try constructing
+    // one via the global `Time` class (shared with the standard Premiere
+    // DOM) and via reusing the moved clip's own `.start` (already a
+    // confirmed-valid QETime instance) in that slot instead of `0`.
+    var zeroTime = null;
+    try {
+      zeroTime = new Time();
+      zeroTime.seconds = 0;
+    } catch (e) {
+      zeroTime = null;
+    }
+
+    var clipStartTime = null;
+    try {
+      clipStartTime = moveTarget.item.start;
+    } catch (e) {
+      clipStartTime = null;
+    }
+
+    var moveGuesses = [];
+    if (zeroTime !== null) {
+      moveGuesses.push([destTrackIndex, zeroTime, 0]);
+      moveGuesses.push([destTrackIndex, zeroTime, true]);
+      moveGuesses.push([destTrackIndex, zeroTime, false]);
+      moveGuesses.push([moveTarget.trackIndex, destTrackIndex, zeroTime]);
+    }
+    if (clipStartTime !== null) {
+      moveGuesses.push([destTrackIndex, clipStartTime, 0]);
+      moveGuesses.push([destTrackIndex, clipStartTime, true]);
+      moveGuesses.push([moveTarget.trackIndex, destTrackIndex, clipStartTime]);
+    }
+    // Fallbacks in case neither Time construction path is available.
+    moveGuesses.push([destTrackIndex, 0, 0]);
+    moveGuesses.push([destTrackIndex, 0, true]);
+
+    result.moveTest_zeroTimeConstructed = zeroTime !== null;
+    result.moveTest_clipStartTimeReadable = clipStartTime !== null;
+
+    var moveOutcome = tryCallGuesses(moveTarget.item.moveToTrack, moveTarget.item, moveGuesses);
+
+    result.moveTest = {
+      destTrackIndex: destTrackIndex,
+      attempts: moveOutcome.attempts,
+      succeededWithArgs: moveOutcome.succeededWithArgs,
+      sourceTrackAfter: describeAudioTrack(qeSeq, moveTarget.trackIndex),
+      destTrackAfter: describeAudioTrack(qeSeq, destTrackIndex)
+    };
+
+    // --- Alternative to moveToTrack(): place a NEW instance of the same
+    // source clip directly onto the destination track via Track-level
+    // insert()/overwrite(), mirroring the standard DOM's documented
+    // Track.insertClip(projectItem, time) / overwriteClip(projectItem, time).
+    // Doesn't require moving the existing TrackItem at all.
+    var projectItem = null;
+    try {
+      projectItem = moveTarget.item.getProjectItem();
+    } catch (e) {
+      result.insertOverwriteTest = { skipped: true, reason: "getProjectItem() failed: " + e.toString() };
+      return JSON.stringify({ ok: true, result: result });
+    }
+
+    if (!projectItem) {
+      result.insertOverwriteTest = { skipped: true, reason: "getProjectItem() returned nothing" };
+      return JSON.stringify({ ok: true, result: result });
+    }
+
+    var insertGuesses = [
+      [projectItem, zeroTime],
+      [projectItem, 0],
+      [projectItem],
+      [projectItem, zeroTime, 0],
+      [projectItem, zeroTime, true]
+    ];
+    var insertOutcome = tryCallGuesses(destTrack.insert, destTrack, insertGuesses);
+
+    var insertResult = {
+      attempts: insertOutcome.attempts,
+      succeededWithArgs: insertOutcome.succeededWithArgs,
+      destTrackAfterInsert: describeAudioTrack(qeSeq, destTrackIndex)
+    };
+
+    // Only try overwrite() if insert() didn't already place something —
+    // avoids stacking two clips onto the same (short) destination track.
+    if (insertOutcome.succeededWithArgs === null) {
+      var overwriteGuesses = [
+        [projectItem, zeroTime],
+        [projectItem, 0],
+        [projectItem]
+      ];
+      var overwriteOutcome = tryCallGuesses(destTrack.overwrite, destTrack, overwriteGuesses);
+      insertResult.overwriteAttempts = overwriteOutcome.attempts;
+      insertResult.overwriteSucceededWithArgs = overwriteOutcome.succeededWithArgs;
+      insertResult.destTrackAfterOverwrite = describeAudioTrack(qeSeq, destTrackIndex);
+    }
+
+    result.insertOverwriteTest = insertResult;
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/delete-marker.jsx

@@ -0,0 +1,178 @@
+// Command: delete-marker → ppb_deleteMarker
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND,
+// findSequenceByName, timeValueToSeconds, ...) are already defined there.
+//
+// Ported from leancoderkavy's premiere-pro-mcp delete_marker tool, but
+// re-addressed like update-marker.jsx: identifies the target by .guid
+// rather than matching a time value within a tolerance window. Deletion
+// itself is markers.deleteMarker(marker) per PREMIERE_API_NOTES.md.
+//
+// Also accepts PROJECT-ITEM addressing (nodeId or itemName instead of
+// sequenceName) to delete markers created by add-marker-to-project-item —
+// needed because undo is non-functional on this Premiere 2026 build
+// (app.project.undo missing; qe.project.undo is a confirmed silent no-op),
+// so item markers would otherwise be undeletable from the bridge.
+//
+// MUTATION RULE: verified by comparing the collection's total marker count
+// before and after (must drop by exactly one) AND confirming the guid no
+// longer appears in a fresh getFirstMarker()/getNextMarker() walk — never
+// trusting deleteMarker()'s own (lack of a) return value.
+
+function ppbDeleteMarker_findByGuidAndCount(markerCollection, guid, markerName) {
+  var found = null;
+  var matches = 0;
+  var count = 0;
+  var m = markerCollection.getFirstMarker();
+  var iterations = 0;
+  while (m !== null && typeof m !== "undefined" && iterations < 10000) {
+    count++;
+    var thisGuid = null;
+    var thisName = null;
+    try { thisGuid = m.guid; } catch (e) { thisGuid = null; }
+    try { thisName = m.name; } catch (e) { thisName = null; }
+    var isMatch = (guid !== null && thisGuid === guid) ||
+                  (guid === null && markerName !== null && thisName === markerName);
+    if (isMatch) {
+      found = m;
+      matches++;
+    }
+    m = markerCollection.getNextMarker(m);
+    iterations++;
+  }
+  return { found: found, count: count, matches: matches };
+}
+
+// Depth-first project-item lookup by nodeId or exact name (same approach
+// as get-project-item-info's walker: recurse on children presence, NOT on
+// isBin — the root item's type is ROOT).
+function ppbDeleteMarker_findItem(item, nodeId, name, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (nodeId !== null && item.nodeId === nodeId) {
+      return item;
+    }
+    if (name !== null && item.name === name && item.type !== ProjectItemType.BIN && item.type !== ProjectItemType.ROOT) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbDeleteMarker_findItem(item.children[i], nodeId, name, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppb_deleteMarker(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var hasGuid = typeof args.guid === "string" && args.guid.length > 0;
+    var hasMarkerName = typeof args.markerName === "string" && args.markerName.length > 0;
+    if (!hasGuid && !hasMarkerName) {
+      return JSON.stringify({ ok: false, error: "one of guid or markerName is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var hasItemAddress = (typeof args.nodeId === "string" && args.nodeId.length > 0) ||
+                         (typeof args.itemName === "string" && args.itemName.length > 0);
+
+    var markerCollection = null;
+    var scopeLabel = null;
+
+    if (hasItemAddress) {
+      // Project-item marker deletion
+      var item = ppbDeleteMarker_findItem(
+        app.project.rootItem,
+        (typeof args.nodeId === "string" && args.nodeId.length > 0) ? args.nodeId : null,
+        (typeof args.itemName === "string" && args.itemName.length > 0) ? args.itemName : null,
+        0
+      );
+      if (!item) {
+        return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/itemName" });
+      }
+      try {
+        markerCollection = item.getMarkers();
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: "getMarkers() failed on the project item: " + e.toString() });
+      }
+      scopeLabel = item.name;
+    } else {
+      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" });
+        }
+      }
+      markerCollection = seq.markers;
+      scopeLabel = seq.name;
+    }
+
+    var guidArg = hasGuid ? args.guid : null;
+    var nameArg = hasMarkerName ? args.markerName : null;
+    var before = ppbDeleteMarker_findByGuidAndCount(markerCollection, guidArg, nameArg);
+    if (!before.found) {
+      return JSON.stringify({ ok: false, error: "no marker found matching " + (hasGuid ? "guid \"" + args.guid + "\"" : "name \"" + args.markerName + "\"") + " on " + scopeLabel });
+    }
+    if (!hasGuid && before.matches > 1) {
+      return JSON.stringify({ ok: false, error: before.matches + " markers named \"" + args.markerName + "\" on " + scopeLabel + " — use --guid to disambiguate" });
+    }
+
+    try {
+      markerCollection.deleteMarker(before.found);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "deleteMarker failed: " + e.toString() });
+    }
+
+    var after = ppbDeleteMarker_findByGuidAndCount(markerCollection, guidArg, nameArg);
+
+    var deleted = after.found === null && after.count === before.count - 1;
+
+    if (!deleted) {
+      return JSON.stringify({
+        ok: false,
+        error: "deleteMarker did not throw, but the marker count/guid check afterward doesn't confirm deletion",
+        countBefore: before.count,
+        countAfter: after.count,
+        stillPresent: after.found !== null
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        scope: hasItemAddress ? "projectItem" : "sequence",
+        scopeName: scopeLabel,
+        deleted: true,
+        guid: hasGuid ? args.guid : null,
+        markerName: hasMarkerName ? args.markerName : null,
+        markerCountBefore: before.count,
+        markerCountAfter: after.count
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/deselect-all-clips.jsx

@@ -0,0 +1,98 @@
+// Command: deselect-all-clips → ppb_deselectAllClips
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (findSequenceByName,
+// timeValueToSeconds, ...) are already defined there.
+//
+// Standard-DOM only (clip.setSelected(false, true)) — no QE needed. Ported
+// from leancoderkavy's premiere-pro-mcp `deselect_all_clips` tool
+// (selection.ts). Mutation — verified via seq.getSelection() afterward
+// (expected to read back empty).
+
+function ppb_deselectAllClipsCollectSelection(seq) {
+  var sel = null;
+  try {
+    sel = seq.getSelection();
+  } catch (e) {
+    sel = null;
+  }
+  var selCount = 0;
+  if (sel) {
+    if (typeof sel.numItems === "number") {
+      selCount = sel.numItems;
+    } else if (typeof sel.length === "number") {
+      selCount = sel.length;
+    }
+  }
+  var selectedClips = [];
+  var cap = selCount > 20 ? 20 : selCount;
+  for (var i = 0; i < cap; i++) {
+    var item = sel[i];
+    var entry = { name: null, mediaType: null, startSeconds: null, endSeconds: null, nodeId: null };
+    try { entry.name = item.name; } catch (e) { entry.name = null; }
+    try { entry.mediaType = item.mediaType; } catch (e) { entry.mediaType = null; }
+    try { entry.startSeconds = timeValueToSeconds(item.start); } catch (e) { entry.startSeconds = null; }
+    try { entry.endSeconds = timeValueToSeconds(item.end); } catch (e) { entry.endSeconds = null; }
+    try { entry.nodeId = item.nodeId; } catch (e) { entry.nodeId = null; }
+    selectedClips.push(entry);
+  }
+  var result = { selectedCount: selCount, selectedClips: selectedClips };
+  if (selCount > 20) {
+    result.truncated = true;
+  }
+  return result;
+}
+
+function ppb_deselectAllClips(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    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" });
+      }
+    }
+
+    function deselectAllInTracks(tracks) {
+      for (var t = 0; t < tracks.numTracks; t++) {
+        var track = tracks[t];
+        for (var c = 0; c < track.clips.numItems; c++) {
+          try { track.clips[c].setSelected(false, true); } catch (e) { /* best-effort */ }
+        }
+      }
+    }
+
+    deselectAllInTracks(seq.videoTracks);
+    deselectAllInTracks(seq.audioTracks);
+
+    var selectionResult = ppb_deselectAllClipsCollectSelection(seq);
+
+    var result = {
+      sequenceName: seq.name
+    };
+    result.selectedCount = selectionResult.selectedCount;
+    result.selectedClips = selectionResult.selectedClips;
+    if (selectionResult.truncated) {
+      result.truncated = true;
+    }
+
+    return JSON.stringify({ ok: true, result: result });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/detach-proxy.jsx

@@ -0,0 +1,116 @@
+// Command: detach-proxy → ppb_detachProxy
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (TICKS_PER_SECOND, ...)
+// are already defined there.
+//
+// Ports the reference project's media.ts detach_proxy tool. Item
+// resolution by nodeId/name uses children-presence recursion (NOT an
+// isBin() gate), per get-project-item-info.jsx's live-debugged finding.
+// Checks hasProxy() first and fails honestly if no proxy is attached,
+// rather than calling detachProxy() unconditionally. Verified via a
+// hasProxy() read-back (expected false afterward).
+
+function ppbDetachProxy_findByNodeId(item, nodeId, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.nodeId === nodeId) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbDetachProxy_findByNodeId(item.children[i], nodeId, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppbDetachProxy_findByName(item, name, depth) {
+  if (depth > 32) {
+    return null;
+  }
+  try {
+    if (item.name === name) {
+      return item;
+    }
+  } catch (e) {
+    // fall through
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      var found = ppbDetachProxy_findByName(item.children[i], name, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}
+
+function ppb_detachProxy(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" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var item = hasNodeId
+      ? ppbDetachProxy_findByNodeId(app.project.rootItem, args.nodeId, 0)
+      : ppbDetachProxy_findByName(app.project.rootItem, args.name, 0);
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no project item found matching the given nodeId/name" });
+    }
+
+    var hadProxy = null;
+    try { hadProxy = item.hasProxy(); } catch (e) { hadProxy = null; }
+    if (hadProxy === false) {
+      return JSON.stringify({
+        ok: false,
+        error: "hasProxy() returned false — no proxy is attached to this item",
+        nodeId: item.nodeId,
+        name: item.name
+      });
+    }
+
+    try {
+      item.detachProxy();
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "detachProxy() failed: " + e.toString() });
+    }
+
+    var hasProxyAfter = null;
+    try { hasProxyAfter = item.hasProxy(); } catch (e) { hasProxyAfter = null; }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        nodeId: item.nodeId,
+        name: item.name,
+        hadProxy: hadProxy,
+        hasProxyAfter: hasProxyAfter,
+        verified: hasProxyAfter === false
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}