premiere-cli 0.2.0__py3-none-any.whl

premiere_cli/panel/host/commands/import-media.jsx

@@ -0,0 +1,217 @@
+// Command: import-media → ppb_importMedia
+// 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 import_media tool. Per
+// PREMIERE_API_NOTES.md's "Project / bins / import" section:
+// app.project.importFiles()'s own return value is unreliable, and an
+// unsupported/unrecognized file extension can pop a BLOCKING modal dialog
+// that freezes the whole CEP bridge — so files are pre-filtered against a
+// safe extension allowlist below, and success is verified by diffing
+// nodeId snapshots of the whole project tree before/after the import call,
+// never by trusting importFiles()'s return value. Helper names are
+// prefixed ppbImportMedia_ to avoid colliding with same-purpose helpers in
+// other lazily-loaded command files evaluated into this same global
+// context (import-folder.jsx and import-image-sequence.jsx duplicate this
+// allowlist/snapshot logic under their own prefixes for the same reason).
+
+var PPB_IMPORT_MEDIA_ALLOWED_EXTENSIONS = [
+  // video
+  "mp4", "mov", "avi", "mkv", "webm", "mxf", "m4v", "wmv", "mpg", "mpeg",
+  // audio
+  "wav", "mp3", "aac", "m4a", "aif", "aiff", "flac", "ogg",
+  // image
+  "png", "jpg", "jpeg", "gif", "tiff", "tif", "bmp", "psd", "tga", "exr", "dpx", "webp",
+  // project
+  "prproj"
+];
+
+function ppbImportMedia_extensionOf(path) {
+  var lastDot = path.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === path.length - 1) {
+    return "";
+  }
+  return path.substring(lastDot + 1).toLowerCase();
+}
+
+function ppbImportMedia_isAllowedExtension(path) {
+  var ext = ppbImportMedia_extensionOf(path);
+  for (var i = 0; i < PPB_IMPORT_MEDIA_ALLOWED_EXTENSIONS.length; i++) {
+    if (ext === PPB_IMPORT_MEDIA_ALLOWED_EXTENSIONS[i]) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Depth-capped (32) recursive walk collecting every nodeId currently in the
+// project, keyed in a plain object for O(1) diffing. Recurses on
+// children-presence (item.children truthy), NOT an isBin() gate — the
+// ROOT item's type is ROOT, not BIN, and per get-project-item-info.jsx's
+// live-debugged finding, an isBin() gate here would silently stop any
+// walk that starts at the root itself. Snapshot walks in this file always
+// start at rootItem.children, but the same helper is reused by the
+// resolveBinPath below which DOES start at rootItem, so the non-gated
+// form is used uniformly.
+function ppbImportMedia_snapshotNodeIds(item, depth, seen) {
+  if (depth > 32) {
+    return;
+  }
+  try {
+    if (item.nodeId) {
+      seen[item.nodeId] = true;
+    }
+  } catch (e) {
+    // ignore
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      ppbImportMedia_snapshotNodeIds(item.children[i], depth + 1, seen);
+    }
+  }
+}
+
+function ppbImportMedia_takeSnapshot() {
+  var seen = {};
+  var root = app.project.rootItem;
+  ppbImportMedia_snapshotNodeIds(root, 0, seen);
+  return seen;
+}
+
+// Finds every item in the current project whose nodeId isn't in
+// `beforeSnapshot` — the newly-imported items. Depth-capped the same way.
+function ppbImportMedia_collectNew(item, depth, beforeSnapshot, out) {
+  if (depth > 32) {
+    return;
+  }
+  try {
+    if (item.nodeId && !beforeSnapshot[item.nodeId]) {
+      var entry = { name: null, nodeId: null, treePath: null, mediaPath: null };
+      try { entry.name = item.name; } catch (e) { entry.name = null; }
+      try { entry.nodeId = item.nodeId; } catch (e) { entry.nodeId = null; }
+      try { entry.treePath = item.treePath; } catch (e) { entry.treePath = null; }
+      try { entry.mediaPath = item.getMediaPath(); } catch (e) { entry.mediaPath = null; }
+      out.push(entry);
+    }
+  } catch (e) {
+    // ignore
+  }
+  if (item.children && item.children.numItems > 0) {
+    for (var i = 0; i < item.children.numItems; i++) {
+      ppbImportMedia_collectNew(item.children[i], depth + 1, beforeSnapshot, out);
+    }
+  }
+}
+
+// Resolves (but does NOT create) a '/'-separated bin path against the
+// project's root bin. Returns {bin} on success or {error} if any segment
+// is missing.
+function ppbImportMedia_resolveBinPath(binPath) {
+  var segments = binPath.split("/").filter(function (s) { return s.length > 0; });
+  var current = app.project.rootItem;
+  for (var i = 0; i < segments.length; i++) {
+    var found = null;
+    for (var j = 0; j < current.children.numItems; j++) {
+      var child = current.children[j];
+      if (child.name === segments[i] && typeof ProjectItemType !== "undefined" && child.type === ProjectItemType.BIN) {
+        found = child;
+        break;
+      }
+    }
+    if (!found) {
+      return { error: "bin path segment \"" + segments[i] + "\" not found in \"" + binPath + "\" (target bin must already exist)" };
+    }
+    current = found;
+  }
+  return { bin: current };
+}
+
+function ppb_importMedia(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    var filePaths = null;
+    if (typeof args.filePaths === "string" && args.filePaths.length > 0) {
+      try {
+        filePaths = JSON.parse(args.filePaths);
+      } catch (e) {
+        return JSON.stringify({ ok: false, error: "filePaths must be a JSON array string: " + e.toString() });
+      }
+    } else if (args.filePaths instanceof Array) {
+      filePaths = args.filePaths;
+    } else if (typeof args.filePath === "string" && args.filePath.length > 0) {
+      filePaths = [args.filePath];
+    }
+
+    if (!filePaths || !(filePaths instanceof Array) || filePaths.length === 0) {
+      return JSON.stringify({ ok: false, error: "either filePath (string) or filePaths (JSON array) is required" });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+
+    var refused = [];
+    for (var i = 0; i < filePaths.length; i++) {
+      if (!ppbImportMedia_isAllowedExtension(filePaths[i])) {
+        refused.push(filePaths[i]);
+      }
+    }
+    if (refused.length > 0) {
+      return JSON.stringify({
+        ok: false,
+        error: "refusing to import file(s) with an unrecognized extension — an unsupported format can pop a " +
+          "BLOCKING dialog that freezes the Premiere Bridge panel: " + refused.join(", "),
+        refused: refused,
+        allowedExtensions: PPB_IMPORT_MEDIA_ALLOWED_EXTENSIONS
+      });
+    }
+
+    var targetBin = app.project.rootItem;
+    if (typeof args.targetBinPath === "string" && args.targetBinPath.length > 0) {
+      var resolved = ppbImportMedia_resolveBinPath(args.targetBinPath);
+      if (resolved.error) {
+        return JSON.stringify({ ok: false, error: resolved.error });
+      }
+      targetBin = resolved.bin;
+    }
+
+    var before = ppbImportMedia_takeSnapshot();
+
+    try {
+      app.project.importFiles(filePaths, true, targetBin, false);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "app.project.importFiles() threw: " + e.toString() });
+    }
+
+    var imported = [];
+    ppbImportMedia_collectNew(app.project.rootItem, 0, before, imported);
+
+    if (imported.length === 0) {
+      return JSON.stringify({
+        ok: false,
+        error: "importFiles() did not throw, but no new project item appeared (nodeId-diff found nothing) — " +
+          "the file(s) may already be in the project, or the import silently failed",
+        requestedFiles: filePaths
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        requestedFiles: filePaths,
+        targetBinPath: args.targetBinPath || null,
+        importedCount: imported.length,
+        imported: imported
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/import-mogrt-from-library.jsx

@@ -0,0 +1,105 @@
+// Command: import-mogrt-from-library → ppb_importMogrtFromLibrary
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — findSequenceByName,
+// secondsToTicksString are already defined there.
+//
+// Ported from leancoderkavy's premiere-pro-mcp text.ts
+// import_mogrt_from_library, WITH ONE DELIBERATE CORRECTION: that
+// reference tool calls seq.importMGTFromLibrary(mogrtName, startTicks,
+// trackIndex, trackIndex) — omitting a library name entirely — but
+// PREMIERE_API_NOTES.md documents the real signature as
+// seq.importMGTFromLibrary(libName, mogrtName, ticks, v, a), five
+// arguments with the library name first. The reference's own call would
+// pass a mogrt name where the library name belongs, which reads like a
+// bug in that repo rather than an intentional simplification — this port
+// follows PREMIERE_API_NOTES.md's documented signature instead, adding a
+// required libraryName argument the reference's own tool lacks.
+//
+// MUTATION RULE: same as import-mogrt — verified via the target video
+// track's own clip count before/after, never the call's return value
+// (same ambiguous-return-type caveat).
+function ppb_importMogrtFromLibrary(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (typeof args.libraryName !== "string" || !args.libraryName) {
+      return JSON.stringify({ ok: false, error: "libraryName is required (PREMIERE_API_NOTES.md documents importMGTFromLibrary as (libName, mogrtName, ticks, v, a) — the reference tool this ports omits it, which this command does not follow)" });
+    }
+    if (typeof args.mogrtName !== "string" || !args.mogrtName) {
+      return JSON.stringify({ ok: false, error: "mogrtName is required" });
+    }
+    if (typeof args.startSeconds !== "number") {
+      return JSON.stringify({ ok: false, error: "startSeconds is required" });
+    }
+    if (typeof args.videoTrackIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "videoTrackIndex is required" });
+    }
+    if (typeof args.audioTrackIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "audioTrackIndex 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 numVideoTracks;
+    try { numVideoTracks = seq.videoTracks.numTracks; } catch (e2) { numVideoTracks = 0; }
+    if (args.videoTrackIndex >= numVideoTracks) {
+      return JSON.stringify({ ok: false, error: "videoTrackIndex " + args.videoTrackIndex + " is out of range — sequence has " + numVideoTracks + " video track(s)" });
+    }
+    var videoTrack = seq.videoTracks[args.videoTrackIndex];
+    var trackClipCountBefore = null;
+    try { trackClipCountBefore = videoTrack.clips.numItems; } catch (e3) { trackClipCountBefore = null; }
+
+    var startTicks = secondsToTicksString(args.startSeconds);
+    var importResult = null;
+    try {
+      importResult = seq.importMGTFromLibrary(args.libraryName, args.mogrtName, startTicks, args.videoTrackIndex, args.audioTrackIndex);
+    } catch (e4) {
+      return JSON.stringify({ ok: false, error: "seq.importMGTFromLibrary() failed: " + e4.toString() });
+    }
+
+    var trackClipCountAfter = null;
+    try { trackClipCountAfter = videoTrack.clips.numItems; } catch (e5) { trackClipCountAfter = null; }
+
+    var placed = trackClipCountBefore !== null && trackClipCountAfter !== null && trackClipCountAfter > trackClipCountBefore;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        libraryName: args.libraryName,
+        mogrtName: args.mogrtName,
+        startSeconds: args.startSeconds,
+        videoTrackIndex: args.videoTrackIndex,
+        audioTrackIndex: args.audioTrackIndex,
+        trackClipCountBefore: trackClipCountBefore,
+        trackClipCountAfter: trackClipCountAfter,
+        placed: placed,
+        verified: placed,
+        importReturnValueTruthy: !!importResult,
+        note: "libraryName argument added per PREMIERE_API_NOTES.md's documented 5-arg signature — the ported reference tool's own call omits it (see file header comment)."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/import-mogrt.jsx

@@ -0,0 +1,111 @@
+// Command: import-mogrt → ppb_importMogrt
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — findSequenceByName,
+// secondsToTicksString, timeValueToSeconds are already defined there.
+//
+// Ported from leancoderkavy's premiere-pro-mcp text.ts import_mogrt.
+// Imports a .mogrt file directly onto the timeline via
+// seq.importMGT(mogrtPath, startTicksString, videoTrackIndex,
+// audioTrackIndex).
+//
+// ⚠️ RETURN-VALUE DISCREPANCY: text.ts treats importMGT()'s return value
+// as a boolean ("if (!success) return __error(...)"), but
+// PREMIERE_API_NOTES.md documents it as returning a trackItem object
+// ("seq.importMGT(...) → trackItem"). Both are handled defensively here —
+// the raw return value's type is reported, and if it looks like a
+// trackItem (a non-null object with a readable .name), that's surfaced
+// too — but the PRIMARY verification is independent of either claim: the
+// target video track's own clip count before/after, same MUTATION RULE
+// every other placement command in this panel follows (add-to-timeline,
+// duplicate-clip, ...) rather than trusting an ambiguous return value.
+function ppb_importMogrt(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (typeof args.mogrtPath !== "string" || !args.mogrtPath) {
+      return JSON.stringify({ ok: false, error: "mogrtPath is required" });
+    }
+    if (typeof args.startSeconds !== "number") {
+      return JSON.stringify({ ok: false, error: "startSeconds is required" });
+    }
+    if (typeof args.videoTrackIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "videoTrackIndex is required" });
+    }
+    if (typeof args.audioTrackIndex !== "number") {
+      return JSON.stringify({ ok: false, error: "audioTrackIndex 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 numVideoTracks;
+    try { numVideoTracks = seq.videoTracks.numTracks; } catch (e2) { numVideoTracks = 0; }
+    if (args.videoTrackIndex >= numVideoTracks) {
+      return JSON.stringify({ ok: false, error: "videoTrackIndex " + args.videoTrackIndex + " is out of range — sequence has " + numVideoTracks + " video track(s)" });
+    }
+    var videoTrack = seq.videoTracks[args.videoTrackIndex];
+    var trackClipCountBefore = null;
+    try { trackClipCountBefore = videoTrack.clips.numItems; } catch (e3) { trackClipCountBefore = null; }
+
+    var startTicks = secondsToTicksString(args.startSeconds);
+    var importResult = null;
+    try {
+      importResult = seq.importMGT(args.mogrtPath, startTicks, args.videoTrackIndex, args.audioTrackIndex);
+    } catch (e4) {
+      return JSON.stringify({ ok: false, error: "seq.importMGT() failed: " + e4.toString() });
+    }
+
+    var trackClipCountAfter = null;
+    try { trackClipCountAfter = videoTrack.clips.numItems; } catch (e5) { trackClipCountAfter = null; }
+
+    var placed = trackClipCountBefore !== null && trackClipCountAfter !== null && trackClipCountAfter > trackClipCountBefore;
+
+    var returnValueType = typeof importResult;
+    var returnValueIsObject = importResult !== null && typeof importResult === "object";
+    var returnValueName = null;
+    if (returnValueIsObject) {
+      try { returnValueName = importResult.name; } catch (e6) { returnValueName = null; }
+    }
+    var returnValueTruthy = !!importResult;
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        mogrtPath: args.mogrtPath,
+        startSeconds: args.startSeconds,
+        videoTrackIndex: args.videoTrackIndex,
+        audioTrackIndex: args.audioTrackIndex,
+        trackClipCountBefore: trackClipCountBefore,
+        trackClipCountAfter: trackClipCountAfter,
+        placed: placed,
+        verified: placed,
+        importReturnValueType: returnValueType,
+        importReturnValueTruthy: returnValueTruthy,
+        importReturnValueName: returnValueName,
+        note: "verified via the target video track's clip count, not importMGT()'s own return value — text.ts treats that return as a boolean while PREMIERE_API_NOTES.md documents it as a trackItem; both are reported above but neither is trusted for verification."
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/import-sequences-from-project.jsx

@@ -0,0 +1,80 @@
+// Command: import-sequences-from-project → ppb_importSequencesFromProject
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context.
+//
+// Ported from leancoderkavy/premiere-pro-mcp's project.ts
+// import_sequences. Calls app.project.importSequences(prprojPath,
+// [seqIds]) per PREMIERE_API_NOTES.md's Sequences table; if sequenceIds
+// is omitted, calls the one-arg form (documented by the reference tool
+// as "imports all sequences"). File-exists check on projectPath first,
+// same cheap guard as open-project.jsx. Verified by a project sequence-
+// count increase (never trusting the call's own return value) — cannot
+// name which sequences were imported beyond that (importSequences has no
+// documented return value naming them).
+
+function ppb_importSequencesFromProject(argsJson) {
+  try {
+    var args;
+    try {
+      args = JSON.parse(argsJson);
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "invalid args JSON: " + e.toString() });
+    }
+
+    if (!args.projectPath || typeof args.projectPath !== "string") {
+      return JSON.stringify({ ok: false, error: "projectPath is required" });
+    }
+
+    var file = new File(args.projectPath);
+    if (!file.exists) {
+      return JSON.stringify({ ok: false, error: "no file exists at projectPath: " + args.projectPath });
+    }
+
+    if (!app.project) {
+      return JSON.stringify({ ok: false, error: "no project open" });
+    }
+    if (typeof app.project.importSequences !== "function") {
+      return JSON.stringify({ ok: false, error: "importSequences is not available on this Premiere build" });
+    }
+
+    var hasIds = Object.prototype.toString.call(args.sequenceIds) === "[object Array]" && args.sequenceIds.length > 0;
+
+    var countBefore = app.project.sequences.numSequences;
+
+    try {
+      if (hasIds) {
+        app.project.importSequences(args.projectPath, args.sequenceIds);
+      } else {
+        app.project.importSequences(args.projectPath);
+      }
+    } catch (e) {
+      return JSON.stringify({ ok: false, error: "importSequences() failed: " + e.toString() });
+    }
+
+    var countAfter = app.project.sequences.numSequences;
+    var imported = countAfter > countBefore;
+
+    if (!imported) {
+      return JSON.stringify({
+        ok: false,
+        error: "importSequences() did not throw, but the project's sequence count did not increase",
+        countBefore: countBefore,
+        countAfter: countAfter
+      });
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        imported: true,
+        projectPath: args.projectPath,
+        sequenceIds: hasIds ? args.sequenceIds : null,
+        allSequences: !hasIds,
+        countBefore: countBefore,
+        countAfter: countAfter
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}

premiere_cli/panel/host/commands/insert-from-source.jsx

@@ -0,0 +1,162 @@
+// Command: insert-from-source → ppb_insertFromSource
+// Loaded lazily by ppb_dispatch (host/index.jsx) on first use, into the
+// same global ExtendScript context — shared helpers (secondsToTicksString,
+// timeValueToSeconds, serializeTrackItem, findSequenceByName,
+// ppbAddToTimeline_cleanupLinkedAudio) are already defined there.
+//
+// Ported from leancoderkavy's premiere-pro-mcp source-monitor.ts
+// insert_from_source — a 3-point insert edit of whatever clip is open in
+// the Source Monitor (its own in/out points, set via set-source-in-out,
+// combine with the sequence's insertClip() call) at either the given
+// atSeconds or the sequence's current playhead. -1 is passed for the
+// non-addressed track index, same convention as add-to-timeline.
+//
+// ⚠️ Same auto-linked-audio trap as add-to-timeline: a video placement
+// whose source item also carries audio can silently land linked audio on
+// some audio track even with audioTrackIndex -1. The shared cleanup
+// helper (ppbAddToTimeline_cleanupLinkedAudio, host/index.jsx) is reused
+// here unchanged for video placements.
+//
+// MUTATION RULE: verified the same way as add-to-timeline — never trust
+// insertClip()'s own return value. LIVE FINDING (add-to-timeline,
+// 2026-07-17): insertClip/overwriteClip IGNORE their track index argument
+// on this build, so the actual landing track is discovered by re-scanning
+// the timeline afterward and reported alongside trackHonored, exactly like
+// add-to-timeline.
+function ppb_insertFromSource(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") {
+      return JSON.stringify({ ok: false, error: "trackIndex 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 item = null;
+    try {
+      item = app.sourceMonitor.getProjectItem();
+    } catch (e2) {
+      return JSON.stringify({ ok: false, error: "app.sourceMonitor.getProjectItem() failed: " + e2.toString() });
+    }
+    if (!item) {
+      return JSON.stringify({ ok: false, error: "no clip open in Source Monitor" });
+    }
+    var itemNodeId = null;
+    try { itemNodeId = item.nodeId; } catch (e3) { itemNodeId = null; }
+
+    var atSeconds = null;
+    var posTicks = null;
+    if (typeof args.atSeconds === "number" && !isNaN(args.atSeconds)) {
+      atSeconds = args.atSeconds;
+      posTicks = secondsToTicksString(atSeconds);
+    } else {
+      try {
+        var playerPos = seq.getPlayerPosition();
+        posTicks = playerPos.ticks;
+        atSeconds = timeValueToSeconds(playerPos);
+      } catch (e4) {
+        return JSON.stringify({ ok: false, error: "atSeconds was not given and seq.getPlayerPosition() failed: " + e4.toString() });
+      }
+    }
+
+    var trackCollection = args.trackType === "video" ? seq.videoTracks : seq.audioTracks;
+    var numTracks;
+    try { numTracks = trackCollection.numTracks; } catch (e5) { numTracks = 0; }
+    if (args.trackIndex >= numTracks) {
+      return JSON.stringify({ ok: false, error: "trackIndex " + args.trackIndex + " is out of range — sequence has " + numTracks + " " + args.trackType + " track(s)" });
+    }
+    var targetTrack = trackCollection[args.trackIndex];
+    var trackClipCountBefore = null;
+    try { trackClipCountBefore = targetTrack.clips.numItems; } catch (e6) { trackClipCountBefore = null; }
+
+    var vIdx = args.trackType === "video" ? args.trackIndex : -1;
+    var aIdx = args.trackType === "audio" ? args.trackIndex : -1;
+
+    try {
+      seq.insertClip(item, posTicks, vIdx, aIdx);
+    } catch (e7) {
+      return JSON.stringify({ ok: false, error: "seq.insertClip() failed: " + e7.toString() });
+    }
+
+    var trackClipCountAfter = null;
+    try { trackClipCountAfter = targetTrack.clips.numItems; } catch (e8) { trackClipCountAfter = null; }
+
+    var toleranceSeconds = 0.1;
+    function ppbInsertFromSource_locate() {
+      try {
+        for (var t2 = 0; t2 < trackCollection.numTracks; t2++) {
+          var scanTrack = trackCollection[t2];
+          for (var c2 = 0; c2 < scanTrack.clips.numItems; c2++) {
+            var candidate = scanTrack.clips[c2];
+            var candNodeId = null;
+            try { candNodeId = candidate.projectItem.nodeId; } catch (e9) { candNodeId = null; }
+            if (candNodeId !== itemNodeId) {
+              continue;
+            }
+            var candStart = null;
+            try { candStart = timeValueToSeconds(candidate.start); } catch (e10) { candStart = null; }
+            if (candStart !== null && Math.abs(candStart - atSeconds) <= toleranceSeconds) {
+              return serializeTrackItem(candidate, t2, c2);
+            }
+          }
+        }
+      } catch (e11) {
+        // fall through
+      }
+      return null;
+    }
+
+    var placedClip = ppbInsertFromSource_locate();
+    var trackHonored = placedClip !== null && placedClip.trackIndex === args.trackIndex;
+
+    var linkedAudioCleanup = { performed: false, removedCount: 0, removed: [] };
+    if (args.trackType === "video") {
+      var removedList = ppbAddToTimeline_cleanupLinkedAudio(seq, itemNodeId, atSeconds, toleranceSeconds);
+      linkedAudioCleanup = { performed: true, removedCount: removedList.length, removed: removedList };
+    }
+
+    return JSON.stringify({
+      ok: true,
+      result: {
+        sequenceName: seq.name,
+        inserted: true,
+        trackType: args.trackType,
+        requestedTrackIndex: args.trackIndex,
+        actualTrackIndex: placedClip !== null ? placedClip.trackIndex : null,
+        trackHonored: trackHonored,
+        atSeconds: atSeconds,
+        item: { name: (function () { try { return item.name; } catch (e) { return null; } })(), nodeId: itemNodeId },
+        placedClip: placedClip,
+        trackClipCountBefore: trackClipCountBefore,
+        trackClipCountAfter: trackClipCountAfter,
+        linkedAudioCleanup: linkedAudioCleanup
+      }
+    });
+  } catch (e) {
+    return JSON.stringify({ ok: false, error: e.toString() });
+  }
+}