premiere-pro-mcp 1.14.4 → 1.14.6

package/CHANGELOG.md

@@ -6,6 +6,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.14.6] - 2026-09-02
+
+### Added
+
+- Added `create_editorial_context_pack`, a review-only, revision-aware Markdown
+  reading view for explicitly captured transcript, shot, audio, source,
+  timeline, and editor-note context. It is bounded by entry and character
+  limits and never invokes a provider, Premiere bridge, or project mutation.
+- Added guarded UXP workflows for sequence playhead and range updates, marker
+  batch removal, native transition application, caption-track inventory,
+  silence-cut stringouts, atomic split edits, and beat-grid markers.
+- Added local-only delivery conformance, sampled video scopes and motion
+  analysis, Warp Stabilizer status inspection, and shot-match planning.
+- Added source-backed inventories for documented UXP, CEP, ExtendScript, and
+  native SDK integration surfaces.
+
+### Fixed
+
+- Made unsupported sequence pixel-aspect ratios, partial transitions,
+  unavailable media timing readback, and incomplete delivery probes fail
+  closed instead of reporting unverified success.
+- Corrected marker, encoder, duplicate-media, caption, and capability
+  inference contracts, with expanded mutation verification coverage.
+
+## [1.14.5] - 2026-08-31
+
+### Added
+
+- Added safe user update commands for global npm installations and guarded
+  source check/update scripts. Global updates refresh the CEP connector after
+  npm succeeds; source updates require a clean fast-forwardable checkout.
+
+### Fixed
+
+- Corrected macOS bridge-directory handling when `TMPDIR` is set and made QE
+  transition writes target the intended clip on current Premiere builds.
+
 ## [1.14.4] - 2026-08-29
 
 ### Fixed

package/README.md

@@ -8,7 +8,7 @@
 
 **Give compatible AI assistants structured control over supported Adobe Premiere Pro workflows.**
 
-321 core tools across 37 modules, 14 resources, and 11 guided workflows. A connected UXP host adds 54 capability-gated tools.
+327 core tools across 37 modules, 4 resources, and 11 guided workflows. A connected UXP host adds 61 capability-gated tools.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-20.19%2B-green.svg)](https://nodejs.org)
@@ -31,22 +31,22 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that l
 "Add the B-roll clips to V2, apply a cross dissolve between each, color correct them to match the A-roll, and export a 1080p ProRes."
 ```
 
-The AI handles the entire workflow through 321 core tools spanning the supported ExtendScript, QE DOM, local media and interchange analysis, revisioned project-context retrieval, safe edit-planning, project-intake preview, review handoff, and connection-verification surfaces. A compatible, authenticated UXP panel adds 54 documented, capability-gated tools without replacing the production CEP bridge.
+The AI handles the entire workflow through 327 core tools spanning the supported ExtendScript, QE DOM, local media and interchange analysis, revisioned project-context retrieval, safe edit-planning, project-intake preview, review handoff, and connection-verification surfaces. A compatible, authenticated UXP panel adds 56 documented, capability-gated tools without replacing the production CEP bridge.
 
-### Latest release: 1.14.4
+### Latest release: 1.14.6
 
-- **Verified editing semantics:** QE razor operations use sequence timecode and
-  batch effect application preflights every target before reporting a verified
-  component readback.
-- **Honest playback state:** legacy playback tools report an accepted request,
-  not movement or stoppage, until a separate position readback confirms it.
-- **Fail-closed catalogs:** empty QE audio-transition catalogs are errors, and
-  effect fallback results are explicitly bounded and partial.
+- **Guarded UXP editing:** compatible hosts can use verified sequence ranges,
+  playhead, marker, transition, caption, silence-cut, and split-edit workflows.
+- **Review-first evidence:** local delivery checks, sampled media analysis, and
+  editorial context packs remain bounded and avoid unapproved provider writes.
+- **Narrowed host behavior:** unsupported sequence pixel-aspect ratios and
+  partial UXP transition writes fail closed; other mutations retain their
+  documented verified or explicitly `committed_unverified` outcome.
 - **Explicit boundary:** the hosted endpoint remains an operator-managed MCP
   service; unauthenticated callers are rejected and it does not pair users to
   local Premiere processes.
 
-See the [v1.14.4 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.14.4)
+See the [v1.14.6 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.14.6)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ### Current MCP protocol support
@@ -88,9 +88,9 @@ their bins, media rules, and organization rules before a facility uses one.
 
 ### Easiest supported path: Claude Desktop
 
-1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.14.4/premiere-pro-mcp-1.14.4.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.14.6/premiere-pro-mcp-1.14.6.mcpb).
 2. In Claude Desktop, open **Settings > Extensions > Advanced settings > Install Extension**, select the downloaded bundle, and restart Claude Desktop.
-3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.14.4/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
+3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.14.6/MCPBridgeCEP.zxp). Open it with your trusted ZXP installer. If your computer has no ZXP installer, use the npm connector installer in **Advanced setup** below.
 4. Restart Premiere, open a project, then open **Window > Extensions > MCP for Adobe Premiere Pro**.
 5. In Claude, enter: `Safely check my Premiere connection with verify_premiere_connection. Make no changes.`
 
@@ -165,6 +165,38 @@ premiere-pro-mcp --doctor
 
 Then ask your MCP client to run `verify_premiere_connection`. The check is read-only.
 
+#### Update an existing installation
+
+New **releases** update the local server and Premiere connector; a deployment of
+the hosted MCP service does not replace software on your computer. Fully quit
+Premiere before updating the connector.
+
+**Installed globally from npm:**
+
+```bash
+premiere-pro-mcp --check-update
+premiere-pro-mcp --update
+```
+
+`--update` only changes a global npm installation. It installs the published
+`latest` package, refreshes the bundled CEP connector, and leaves your MCP
+client configuration and projects untouched. Restart Premiere and your MCP
+client afterward, then run `verify_premiere_connection` before editing.
+
+**Installed from a Git clone:**
+
+```bash
+npm run check-update:source
+npm run update:source
+```
+
+The source updater refuses a checkout with uncommitted files or local commits,
+fast-forwards only to its configured upstream, runs `npm ci` and the production
+build, then refreshes the CEP connector. This avoids silently overwriting local
+code. If you installed the Claude Desktop `.mcpb` bundle, download and install
+the newer bundle from the GitHub release instead; Claude controls extension
+updates.
+
 #### Remove the CEP connector
 
 Fully quit Premiere, then remove only this connector:
@@ -325,7 +357,7 @@ Add to your VS Code MCP server configuration:
 4. Ask your AI assistant to run `get_capabilities`, then `ping`, with Premiere open.
 5. For a safe first request, ask: *"What is my current Premiere Pro project and active sequence? Do not make changes."*
 
-The default bridge directory is derived from the operating system on both sides, so most local setups should not set `PREMIERE_TEMP_DIR`. If you override it, use the same absolute path in the MCP server and CEP panel; Windows and macOS paths are not interchangeable.
+The default bridge directory is derived from the operating system on both sides, so most local setups should not set `PREMIERE_TEMP_DIR`. On macOS, the server resolves the per-user system temporary directory even when a GUI-launched client strips `TMPDIR`, keeping it aligned with Premiere's CEP panel. If you override it, use the same absolute path in the MCP server and CEP panel; Windows and macOS paths are not interchangeable.
 
 ### Codex plugin
 
@@ -337,11 +369,11 @@ From a clone of this repository:
 ```bash
 codex plugin marketplace add .
 codex plugin add premiere-pro@premiere-pro-mcp
-npx -y premiere-pro-mcp@1.14.4 --install-cep
+npx -y premiere-pro-mcp@1.14.6 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.14.4` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.14.6` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -361,7 +393,7 @@ For Claude Code, add this repository as a marketplace and install the plugin:
 Then install the Premiere bridge and start a new Claude Code session:
 
 ```bash
-npx -y premiere-pro-mcp@1.14.4 --install-cep
+npx -y premiere-pro-mcp@1.14.6 --install-cep
 ```
 
 The Claude Code package lives in
@@ -400,7 +432,7 @@ installed separately.
 QE-backed tools are reported as `experimental` because QE is undocumented and can vary between Premiere builds. Authority availability is reported separately from implementation support, so disabling `edit`, for example, does not incorrectly label editing tools as unsupported. Static metadata never claims that a Premiere operation succeeded; use `ping` and inspect each tool result for runtime evidence.
 
 MCP `tools/list` is filtered to the active authority profile. The default
-`inspect,edit,export,filesystem` profile advertises 319 of the 321 registered
+`inspect,edit,export,filesystem` profile advertises 325 of the 327 registered
 tools and omits `execute_extendscript` and `evaluate_expression`, which require
 explicit `unsafe-script` authority. `ping` and `get_capabilities` remain visible
 under every profile so a restricted or misconfigured server can still explain
@@ -503,7 +535,7 @@ PREMIERE_UXP_TOKEN="replace-with-a-long-random-secret" premiere-pro-mcp
 
 Enter the same token in the UXP panel. The listener binds only to `127.0.0.1:7777`, authenticates the WebSocket upgrade, requires a versioned capability handshake, correlates concurrent requests, and fails pending work on timeout or disconnect. Set `PREMIERE_UXP_PORT` to use another loopback port.
 
-When enabled, MCP discovery includes 54 capability-gated UXP additions. The first expansion covers effects, deterministic timeline selection, selection batches, scene detection, proxy/ingest, relink, metadata, color conformance, Source Monitor audition, storage, and least-privilege workspace access. The second adds Project-panel selection, marker CRUD, bin organization, sequence settings, imports, typed effect parameters/keyframes, track-item transforms, SequenceEditor timeline edits, sequence lifecycle, and AME encoding. The third wave begins with a redacted event journal, conservative AME terminal receipts, explicit host-readiness gates, safe multi-project sessions, lease-based growing-media control, namespaced workflow checkpoints, bounded media-health maintenance, caption-aware track mute state, and transactional source trim/framing documented in [the third-wave workflow matrix](docs/third-wave-uxp-workflows.md). The bounded migration surface also includes a non-ripple selected-item lift plus native video-transition listing and transactions; it does not claim direct empty-track create/delete or global redo support. A separate [hybrid benchmark gate](docs/uxp-hybrid-benchmark.md) keeps native acceleration disabled until reproducible cross-platform evidence exists. See also [the first stable workflow matrix](docs/uxp-stable-workflows.md) and [the next-ten workflow matrix](docs/uxp-next-ten-workflows.md). Commands are advertised only while the authenticated local UXP bridge is connected; the host capability handshake remains the authority for support in the running Premiere build. A failed UXP command is never silently retried through CEP because the first operation may have partially succeeded.
+When enabled, MCP discovery includes 61 capability-gated UXP additions. The first expansion covers effects, deterministic timeline selection, selection batches, scene detection, proxy/ingest, relink, metadata, color conformance, read-only Premiere/After Effects environment inspection, Source Monitor audition, storage, and least-privilege workspace access. The second adds Project-panel selection, marker CRUD, single-transaction undoable beat-grid marker application, bin organization, sequence settings, imports, typed effect parameters/keyframes, track-item transforms, atomic J/L split edits, SequenceEditor timeline edits, sequence lifecycle, and AME encoding. The third wave begins with a redacted event journal, conservative AME terminal receipts, explicit host-readiness gates, safe multi-project sessions, lease-based growing-media control, namespaced workflow checkpoints, bounded media-health maintenance, caption-aware track mute state, transactional source trim/framing, and guarded sequence-range updates documented in [the third-wave workflow matrix](docs/third-wave-uxp-workflows.md). The bounded migration surface also includes a non-ripple selected-item lift plus native video-transition listing, target inspection, and guarded transactions; it does not claim direct empty-track create/delete or global redo support. A separate [hybrid benchmark gate](docs/uxp-hybrid-benchmark.md) keeps native acceleration disabled until reproducible cross-platform evidence exists. See also [the first stable workflow matrix](docs/uxp-stable-workflows.md) and [the next-ten workflow matrix](docs/uxp-next-ten-workflows.md). Commands are advertised only while the authenticated local UXP bridge is connected; the host capability handshake remains the authority for support in the running Premiere build. A failed UXP command is never silently retried through CEP because the first operation may have partially succeeded.
 
 The panel now requests access to one operator-selected workspace instead of declaring full filesystem access. Choose the folder in the panel before invoking a path-based UXP workflow. Media, relink, preset, export, and Source Monitor file paths must remain inside it; the persistent capability token and native root path are never returned over MCP. Lexical containment alone cannot exclude symlink, junction, or reparse-point escapes, and Adobe's request-scoped UXP filesystem API does not document canonical-path resolution. Builds without a host-supplied canonical resolver therefore advertise path-based UXP commands as unsupported and fail closed at invocation; use the existing CEP fallback for those operations.
 
@@ -527,6 +559,16 @@ coverage matrix](docs/adobe-uxp-26.3-coverage.md) and [the UXP capability
 foundation](docs/uxp-capability-foundation.md) for the command matrix and live-host
 validation boundary.
 
+The [Premiere surface registry](docs/premiere-surface-registry.md) separately
+tracks the Premiere DOM, general UXP JavaScript, HTML/CSS, Spectrum, plugin
+guides, UXP Hybrid C++, the standalone Premiere C++ PrSDK, CEP/ExtendScript,
+the CEP platform, QE, and pinned competitor sources. The exhaustive
+[general UXP JavaScript inventory](docs/uxp-js-api-inventory.md) is generated
+from Adobe's pinned declarations, while the exhaustive
+[Premiere documentation inventory](docs/premiere-doc-inventory.md) tracks every
+page in Adobe's live sitemap. This keeps declaration and documentation
+inventory distinct from implementation and licensed-host coverage.
+
 The stable workflow expansion adds native component-chain effects, deterministic
 timeline selection, compound selection batches, scene-edit detection, proxy/ingest control, guarded offline
 relink, transactional project/XMP metadata, color and footage-conformance
@@ -578,11 +620,11 @@ The file-based IPC bridge is simple, reliable, and works across macOS and Window
 
 ---
 
-## Tools (321 core total; 319 under the default profile; 373 with a connected UXP bridge)
+## Tools (327 core total; 325 under the default profile; 386 with a connected UXP bridge)
 
 The [complete supported-actions catalog](docs/supported-actions.md) lists every
 registered core tool, the two tools restricted behind explicit `unsafe-script`
-authority, and all 54 authenticated UXP additions with their current action or mode
+authority, and all 61 authenticated UXP additions with their current action or mode
 values. It is generated from the same MCP registration surface returned to clients;
 the tables below are a shorter workflow-oriented overview.
 
@@ -635,12 +677,14 @@ the tables below are a shorter workflow-oriented overview.
 > (`ripple_delete`, razor/split) and existing effect-parameter writes. These tools now verify
 > the resulting sequence state and return an error instead of a false success. For structural
 > edits, rebuild the wanted source ranges into a new sequence with `create_sequence` and
-> `add_to_timeline`. Native transitions are unavailable when the host does not expose
-> `qeTrack.addTransition`; overlay clips remain a workaround for transitions that do not need
-> to blend adjacent source frames. See [issue #21](https://github.com/leancoderkavy/premiere-pro-mcp/issues/21).
-
-> **Speed, caption, and visual-keyframe boundaries:** Premiere Pro 26.3 exposes no supported
-> scripting setter or Time Remapping component for timeline-clip speed or direction. `reverse_clip`,
+> `add_to_timeline`. The legacy CEP transition path targets `qeClip.addTransition` (not the
+> QE track) and reports success only after DOM transition-count readback. Prefer the connected
+> UXP transition tools where available; overlay clips remain a workaround when a legacy QE
+> write is rejected or not verified. See [issue #21](https://github.com/leancoderkavy/premiere-pro-mcp/issues/21).
+
+> **Speed, caption, and visual-keyframe boundaries:** Premiere Pro 26.3 may reflect legacy QE
+> speed/direction methods, but exposes no supported scripting setter or Time Remapping component
+> for timeline-clip speed or direction. `reverse_clip`,
 > `speed_change`, `set_clip_speed_qe`, and `set_clip_properties` with `speed` now stop before host mutation;
 > use the Speed/Duration UI or pre-render retimed media. `add_text_overlay` likewise stops
 > before mutation because a raw-text-to-caption API is not exposed; import an `.srt`/`.vtt`
@@ -898,7 +942,7 @@ user/device authorization are implemented.
 
 | Variable | Description | Default |
 | :------- | :---------- | :------ |
-| `PREMIERE_TEMP_DIR` | Shared temp directory for MCP ↔ CEP communication | OS temp dir + `/premiere-mcp-bridge` |
+| `PREMIERE_TEMP_DIR` | Shared temp directory for MCP ↔ CEP communication | OS user temp dir + `/premiere-mcp-bridge` (macOS fallback is independent of `TMPDIR`) |
 | `PREMIERE_TIMEOUT_MS` | Command timeout in milliseconds | `30000` |
 | `PREMIERE_DEFAULT_SEQUENCE_PRESET` | Override the auto-discovered `.sqpreset` used by `create_sequence` | auto-discovered |
 | `PREMIERE_MCP_CAPABILITIES` | Comma-separated authority profile; add `unsafe-script` only when raw scripting is required | `inspect,edit,export,filesystem` |
@@ -952,7 +996,7 @@ premiere-pro-mcp/
 ├── src/
 │   ├── index.ts                 # Entry point — stdio transport setup
 │   ├── http-server.ts           # Entry point — HTTP/SSE transport (Fly.io / remote)
-│   ├── server.ts                # MCP server — registers 321 tools, filtered by authority profile
+│   ├── server.ts                # MCP server — registers 327 tools, filtered by authority profile
 │   ├── bridge/
 │   │   ├── file-bridge.ts       # File-based IPC (write .jsx, poll .json)
 │   │   └── script-builder.ts    # ExtendScript generator with ES3 helpers

package/cep-plugin/CSXS/manifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.14.4" ExtensionBundleName="MCP for Adobe Premiere Pro">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.14.6" ExtensionBundleName="MCP for Adobe Premiere Pro">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.14.4"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.14.4"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.14.6"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.14.6"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

package/cep-plugin/index.html

@@ -81,7 +81,7 @@
     <section class="update-section" aria-live="polite">
       <div class="update-copy">
         <span class="section-label">Connector updates</span>
-        <strong id="updateTitle">Version 1.14.4</strong>
+        <strong id="updateTitle">Version 1.14.6</strong>
         <span id="updateDetail">Checking for updates…</span>
       </div>
       <button id="btnUpdate" class="button button-update" onclick="handleUpdateClick()" type="button" disabled>

package/cep-plugin/main.js

@@ -61,16 +61,18 @@ function refreshConnectionCenter() {
   setConnectionCheck("checkProject", "waiting", "Checking…");
   setConnectionCheck("checkSequence", "waiting", "Checking…");
   cs.evalScript(
-    '(function(){var p=app&&app.project;return JSON.stringify({projectOpen:!!(p&&typeof p.name!=="undefined"),sequenceOpen:!!(p&&p.activeSequence)});}())',
+    '(function(){var p=app&&app.project;return "mcpstate:"+(p&&typeof p.name!=="undefined"?"1":"0")+","+(p&&p.activeSequence?"1":"0");}())',
     function (raw) {
-      try {
-        var state = JSON.parse(raw || "{}");
-        setConnectionCheck("checkProject", state.projectOpen ? "ready" : "needs-attention", state.projectOpen ? "Project open" : "Open a project in Premiere Pro");
-        setConnectionCheck("checkSequence", state.sequenceOpen ? "ready" : "needs-attention", state.sequenceOpen ? "Active sequence open" : "Open a sequence in Premiere Pro");
-      } catch (e) {
+      var match = /^mcpstate:([01]),([01])$/.exec(String(raw || ""));
+      if (!match) {
         setConnectionCheck("checkProject", "needs-attention", "Could not read Premiere state");
         setConnectionCheck("checkSequence", "needs-attention", "Could not read Premiere state");
+        return;
       }
+      var projectOpen = match[1] === "1";
+      var sequenceOpen = match[2] === "1";
+      setConnectionCheck("checkProject", projectOpen ? "ready" : "needs-attention", projectOpen ? "Project open" : "Open a project in Premiere Pro");
+      setConnectionCheck("checkSequence", sequenceOpen ? "ready" : "needs-attention", sequenceOpen ? "Active sequence open" : "Open a sequence in Premiere Pro");
     }
   );
 }
@@ -95,7 +97,17 @@ var fs = nodeRequire("fs");
 var path = nodeRequire("path");
 var os = nodeRequire("os");
 var https = nodeRequire("https");
-tempDir = path.join(os.tmpdir(), "premiere-mcp-bridge");
+function defaultBridgeDirectory() {
+  try {
+    var nodeProcess = nodeRequire("process");
+    var configured = nodeProcess && nodeProcess.env && nodeProcess.env.PREMIERE_TEMP_DIR;
+    if (typeof configured === "string" && configured.trim()) return configured.trim();
+  } catch (e) {
+    // The panel still has a safe OS temporary-directory fallback.
+  }
+  return path.join(os.tmpdir(), "premiere-mcp-bridge");
+}
+tempDir = defaultBridgeDirectory();
 var latestUpdate = null;
 
 function ensureDir(dir) {

package/cep-plugin/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.14.4";
+  var CURRENT_VERSION = "1.14.6";
   var LATEST_RELEASE_API =
     "https://api.github.com/repos/leancoderkavy/premiere-pro-mcp/releases/latest";
   var RELEASES_URL =

package/dist/ai/editorial-context-pack.d.ts

@@ -0,0 +1,53 @@
+import { type ProjectContextDocument, type ProjectContextKind, type ProjectContextSearchResult } from "../context/project-context-store.js";
+export declare const EDITORIAL_CONTEXT_PACK_SCHEMA_VERSION = 1;
+export declare const DEFAULT_EDITORIAL_CONTEXT_PACK_ENTRIES = 12;
+export declare const MAX_EDITORIAL_CONTEXT_PACK_ENTRIES = 50;
+export declare const DEFAULT_EDITORIAL_CONTEXT_PACK_CHARACTERS = 12000;
+export declare const MIN_EDITORIAL_CONTEXT_PACK_CHARACTERS = 1024;
+export declare const MAX_EDITORIAL_CONTEXT_PACK_CHARACTERS = 24000;
+export interface EditorialContextPackEvidence {
+    evidenceId: string;
+    kind: ProjectContextKind;
+    name: string;
+    score: number;
+    matchedTerms: string[];
+    textExcerpt: string;
+    textTruncated: boolean;
+    sequenceId?: string;
+    sourceId?: string;
+    timelineItemId?: string;
+    startSeconds?: number;
+    endSeconds?: number;
+    sourceRevision?: string;
+    timelineRevision?: string;
+}
+export interface EditorialContextPack {
+    schemaVersion: typeof EDITORIAL_CONTEXT_PACK_SCHEMA_VERSION;
+    projectId: string;
+    projectName: string;
+    intent: string;
+    expectedContextRevision: string;
+    expectedSourceRevision: string;
+    expectedTimelineRevision: string;
+    evidence: EditorialContextPackEvidence[];
+    omittedEvidenceCount: number;
+    truncated: boolean;
+    markdown: string;
+    applied: false;
+}
+export interface BuildEditorialContextPackOptions {
+    intent: string;
+    results: ProjectContextSearchResult[];
+    /** Exact pre-limit relevant-match count used for honest truncation metadata. */
+    totalResultCount?: number;
+    maxEntries?: number;
+    maxCharacters?: number;
+}
+/**
+ * Produces a compact reading surface from evidence already captured in the
+ * local project-context store. It intentionally knows nothing about Premiere's
+ * private transcript JSON shape: callers must explicitly enrich context with
+ * the transcript passages or other analysis they want to expose.
+ */
+export declare function buildEditorialContextPack(document: ProjectContextDocument, options: BuildEditorialContextPackOptions): EditorialContextPack;
+//# sourceMappingURL=editorial-context-pack.d.ts.map

package/dist/ai/editorial-context-pack.js

@@ -0,0 +1,133 @@
+import { normalizeContextText, } from "../context/project-context-store.js";
+export const EDITORIAL_CONTEXT_PACK_SCHEMA_VERSION = 1;
+export const DEFAULT_EDITORIAL_CONTEXT_PACK_ENTRIES = 12;
+export const MAX_EDITORIAL_CONTEXT_PACK_ENTRIES = 50;
+export const DEFAULT_EDITORIAL_CONTEXT_PACK_CHARACTERS = 12_000;
+export const MIN_EDITORIAL_CONTEXT_PACK_CHARACTERS = 1_024;
+export const MAX_EDITORIAL_CONTEXT_PACK_CHARACTERS = 24_000;
+function boundedInteger(value, fallback, minimum, maximum, label) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || typeof value !== "number" || value < minimum || value > maximum) {
+        throw new Error(`${label} must be an integer from ${minimum} through ${maximum}`);
+    }
+    return value;
+}
+function finiteSeconds(value) {
+    return typeof value === "number" && Number.isFinite(value) ? Number(value.toFixed(3)) : undefined;
+}
+function compactText(value, maximum) {
+    return value.length <= maximum ? value : `${value.slice(0, maximum - 1).trimEnd()}…`;
+}
+function sourceRange(record) {
+    const startSeconds = finiteSeconds(record.startSeconds);
+    const endSeconds = finiteSeconds(record.endSeconds);
+    if (startSeconds === undefined || endSeconds === undefined)
+        return undefined;
+    return `${startSeconds.toFixed(3)}s–${endSeconds.toFixed(3)}s`;
+}
+function evidenceHeader(index, record, score, matchedTerms) {
+    const facts = [
+        `evidence ${compactText(record.id, 96)}`,
+        `score ${Number(score.toFixed(3))}`,
+        record.sourceId ? `source ${compactText(record.sourceId, 96)}` : undefined,
+        record.sequenceId ? `sequence ${compactText(record.sequenceId, 96)}` : undefined,
+        sourceRange(record),
+        matchedTerms.length ? `matched ${compactText(matchedTerms.join(", "), 160)}` : undefined,
+    ].filter(Boolean).join(" · ");
+    return `## ${String(index + 1).padStart(2, "0")} · ${record.kind} · ${compactText(record.name, 160)}\n${facts}`;
+}
+function entryText(header, text) {
+    return `${header}\n${text}`;
+}
+function truncateTextToFit(header, text, availableCharacters) {
+    const prefix = `${header}\n`;
+    if (availableCharacters < prefix.length + 32)
+        return undefined;
+    const suffix = " … [excerpt truncated]";
+    const textBudget = availableCharacters - prefix.length - suffix.length;
+    if (textBudget < 1)
+        return undefined;
+    return `${prefix}${text.slice(0, textBudget).trimEnd()}${suffix}`;
+}
+function evidenceFromResult(result, textExcerpt, textTruncated) {
+    const { record } = result;
+    return {
+        evidenceId: record.id,
+        kind: record.kind,
+        name: record.name,
+        score: Number(result.score.toFixed(3)),
+        matchedTerms: [...result.matchedTerms],
+        textExcerpt,
+        textTruncated,
+        ...(record.sequenceId ? { sequenceId: record.sequenceId } : {}),
+        ...(record.sourceId ? { sourceId: record.sourceId } : {}),
+        ...(record.timelineItemId ? { timelineItemId: record.timelineItemId } : {}),
+        ...(finiteSeconds(record.startSeconds) === undefined ? {} : { startSeconds: finiteSeconds(record.startSeconds) }),
+        ...(finiteSeconds(record.endSeconds) === undefined ? {} : { endSeconds: finiteSeconds(record.endSeconds) }),
+        ...(record.sourceRevision ? { sourceRevision: record.sourceRevision } : {}),
+        ...(record.timelineRevision ? { timelineRevision: record.timelineRevision } : {}),
+    };
+}
+/**
+ * Produces a compact reading surface from evidence already captured in the
+ * local project-context store. It intentionally knows nothing about Premiere's
+ * private transcript JSON shape: callers must explicitly enrich context with
+ * the transcript passages or other analysis they want to expose.
+ */
+export function buildEditorialContextPack(document, options) {
+    const intent = normalizeContextText(options.intent).slice(0, 1_000);
+    if (!intent)
+        throw new Error("intent must not be empty");
+    const maxEntries = boundedInteger(options.maxEntries, DEFAULT_EDITORIAL_CONTEXT_PACK_ENTRIES, 1, MAX_EDITORIAL_CONTEXT_PACK_ENTRIES, "max_entries");
+    const maxCharacters = boundedInteger(options.maxCharacters, DEFAULT_EDITORIAL_CONTEXT_PACK_CHARACTERS, MIN_EDITORIAL_CONTEXT_PACK_CHARACTERS, MAX_EDITORIAL_CONTEXT_PACK_CHARACTERS, "max_characters");
+    const selected = options.results.slice(0, maxEntries);
+    const totalResultCount = Math.max(options.results.length, Math.trunc(options.totalResultCount ?? options.results.length));
+    const header = [
+        "# Premiere editorial context pack",
+        `Project: ${compactText(document.projectName, 120)}`,
+        `Intent: ${compactText(intent, 240)}`,
+        `Context revision: ${compactText(document.revision, 64)}`,
+        `Source revision: ${compactText(document.sourceRevision, 64)}`,
+        `Timeline revision: ${compactText(document.timelineRevision, 64)}`,
+        "",
+        "Review this evidence before proposing an edit. It is local context, not authority to mutate Premiere.",
+    ].join("\n");
+    let markdown = header;
+    const evidence = [];
+    let truncated = false;
+    for (const [index, result] of selected.entries()) {
+        const text = normalizeContextText(result.record.text);
+        const block = entryText(evidenceHeader(index, result.record, result.score, result.matchedTerms), text);
+        const separator = markdown.length ? "\n\n" : "";
+        const availableCharacters = maxCharacters - markdown.length - separator.length;
+        if (block.length <= availableCharacters) {
+            markdown += `${separator}${block}`;
+            evidence.push(evidenceFromResult(result, text, false));
+            continue;
+        }
+        const partial = truncateTextToFit(evidenceHeader(index, result.record, result.score, result.matchedTerms), text, availableCharacters);
+        if (partial) {
+            const excerpt = partial.slice(partial.lastIndexOf("\n") + 1).replace(/ … \[excerpt truncated\]$/, "");
+            markdown += `${separator}${partial}`;
+            evidence.push(evidenceFromResult(result, excerpt, true));
+        }
+        truncated = true;
+        break;
+    }
+    return {
+        schemaVersion: EDITORIAL_CONTEXT_PACK_SCHEMA_VERSION,
+        projectId: document.projectId,
+        projectName: document.projectName,
+        intent,
+        expectedContextRevision: document.revision,
+        expectedSourceRevision: document.sourceRevision,
+        expectedTimelineRevision: document.timelineRevision,
+        evidence,
+        omittedEvidenceCount: Math.max(0, totalResultCount - evidence.length),
+        truncated: truncated || totalResultCount > selected.length,
+        markdown,
+        applied: false,
+    };
+}
+//# sourceMappingURL=editorial-context-pack.js.map

package/dist/bridge/file-bridge.d.ts

@@ -1,3 +1,5 @@
+export declare function getDarwinUserTempDirectory(): string | null;
+export declare function getDefaultBridgeTempDir(platform?: NodeJS.Platform, fallbackTempDirectory?: string, readDarwinUserTempDirectory?: () => string | null, environment?: NodeJS.ProcessEnv): string;
 export declare const BRIDGE_HEARTBEAT_FILE = "bridge-heartbeat.json";
 export declare const BRIDGE_HEARTBEAT_STALE_MS = 3000;
 export interface BridgeOptions {

package/dist/bridge/file-bridge.js

@@ -1,9 +1,31 @@
 import { mkdirSync, writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync, renameSync, statSync, chmodSync, watch } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { getHelpersSource, helpersFileName, buildBootstrap } from "./script-builder.js";
-const DEFAULT_TEMP_DIR = join(tmpdir(), "premiere-mcp-bridge");
+export function getDarwinUserTempDirectory() {
+    try {
+        // GUI-launched MCP clients can omit TMPDIR. On macOS, getconf still returns
+        // the same per-user temporary root inherited by Premiere's CEP process.
+        const value = execFileSync("/usr/bin/getconf", ["DARWIN_USER_TEMP_DIR"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return value && isAbsolute(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getDefaultBridgeTempDir(platform = process.platform, fallbackTempDirectory = tmpdir(), readDarwinUserTempDirectory = getDarwinUserTempDirectory, environment = process.env) {
+    const hasConfiguredNodeTempDirectory = Boolean(environment.TMPDIR || environment.TMP || environment.TEMP);
+    const temporaryRoot = platform === "darwin" && !hasConfiguredNodeTempDirectory
+        ? readDarwinUserTempDirectory() ?? fallbackTempDirectory
+        : fallbackTempDirectory;
+    return join(temporaryRoot, "premiere-mcp-bridge");
+}
+const DEFAULT_TEMP_DIR = getDefaultBridgeTempDir();
 const POLL_FALLBACK_MS = 250;
 const DEFAULT_TIMEOUT_MS = 30000;
 export const BRIDGE_HEARTBEAT_FILE = "bridge-heartbeat.json";

package/dist/bridge/script-builder.js

@@ -141,6 +141,27 @@ function __findClip(nodeId) {
   return null;
 }
 
+// QE tracks include gaps and transitions in addition to clips, so a DOM clip
+// index cannot safely be passed to qeTrack.getItemAt(). Resolve a QE clip by
+// its timeline start instead. Return null rather than a nearest candidate: a
+// mutation must never be redirected to a neighbouring clip.
+function __findQeClipByDomClip(qeTrack, domClip) {
+  if (!qeTrack || !domClip) return null;
+  var wantedStart = null;
+  try { wantedStart = parseFloat(domClip.start.ticks); } catch (eStart) {}
+  if (wantedStart === null || isNaN(wantedStart)) return null;
+
+  for (var qi = 0; qi < qeTrack.numItems; qi++) {
+    var candidate = null;
+    try { candidate = qeTrack.getItemAt(qi); } catch (eItem) {}
+    if (!candidate || String(candidate.type) !== "Clip") continue;
+    try {
+      if (Math.abs(parseFloat(candidate.start.ticks) - wantedStart) < 1) return candidate;
+    } catch (eCandidate) {}
+  }
+  return null;
+}
+
 // CEP's legacy QE path can enumerate a host's effect catalog before adding an
 // effect to a timeline clip. Recent Premiere builds can expose QE yet return an
 // empty catalog, so distinguish that host limitation from a misspelled effect

package/dist/context/project-context-store.d.ts

@@ -71,6 +71,8 @@ export interface ProjectContextSearchResult {
     record: ProjectContextRecord;
     matchedTerms: string[];
 }
+/** Counts exact keyword-relevant records without materializing their evidence. */
+export declare function countProjectContextMatches(document: ProjectContextDocument, options: Omit<ProjectContextSearchOptions, "limit">): number;
 export declare function searchProjectContext(document: ProjectContextDocument, options: ProjectContextSearchOptions): ProjectContextSearchResult[];
 export declare function contextRevision(sourceRevision: string, timelineRevision: string, records: ProjectContextRecord[]): string;
 export declare function stableContextId(...parts: unknown[]): string;