premiere-pro-mcp 1.18.6 → 1.19.0

package/CHANGELOG.md

@@ -6,6 +6,84 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-10-02
+
+### Added
+
+- EXPERIMENTAL (QE DOM): `undo`, `redo`, and `multiple_undo` step Premiere's undo stack and verify each step against `undoStackIndex`. They stop when the stack stops moving, refuse on a host without `undoStackIndex`, and refuse when the stack has moved past `expected_undo_stack_index`. A step that moves the stack unexpectedly or leaves the index unreadable is reported as `committed_unverified` with a "Do not retry" warning. (#654)
+- `list_stock_titles` lists Premiere's bundled title templates, and `add_title` places a stock title with the text baked into a copy of the template, reading each line back from its own layer. (#648)
+
+### Changed
+
+- `undo`, `redo`, and `multiple_undo` now require `expected_undo_stack_index` and refuse if the host cannot read it. `rename_clip` rejects blank names, `set_playhead_position` rejects negative or nonfinite times and clamps excessive times to the readable sequence end. `set_clip_volume` reports the stored level and applied dB (or an unverified write when readback fails) instead of echoing the requested dB. Edit-plan previews bind tokens to stable project, sequence and target identities; apply rejects changed identities before sequence activation or mutation. Enum validation errors list allowed values. (#725)
+- QE and UXP effect-add receipts, plus UXP effect-removal receipts, now explicitly set `renderVerified: false`. A verified component readback does not establish that Premiere rendered the effect; confirm playback or exported output before delivery (#735).
+- Timeline clip-property writes, splits, and duplicates validate and read back their results. Unreadable requested property state returns `committed_unverified`, lists unverified fields, and reports an unknown timeline-change state instead of claiming nothing was applied (#702).
+- Legacy CEP inserts verify the requested source and insertion time for every media stream, and retain actual placement and undo data when Premiere diverts a stream to another track (#680).
+- Blend modes use the contributor-measured Premiere 25.2.3 index order and verify stored values; keyframe times convert clip-relative seconds through the source in-point, reject retimed clips, and preserve unreadable removal outcomes (#683, #693).
+- Audio level, mute, track lock, and video visibility writes validate arguments and read stored state back. Invalid or unreadable numeric/boolean states cannot certify success (#700, #705).
+- Marker receipts flag unreadable requested colors, and CEP/After Effects string escaping preserves control characters and lone UTF-16 surrogates (#688).
+- Effect removal recognizes the measured Spanish built-in component names and English/Spanish Balance names while retaining the refusal for unconfirmed locales (#692).
+- Experimental QE adjustment-layer creation verifies a new public adjustment-layer clip at the playhead and never retries after a throwing insert. Still-frame imports, edit navigation, and project-item markers read back results; unknown marker colors stay unverified and preserve the persistent undo barrier (#698).
+- Timeline marker requests refuse unsupported clip collections with source-time guidance only when the clip clock is known. Batch markers verify requested fields, keep unknown color state unverified, preserve partial writes and persistent undo guards, and retain uncertainty after a first throwing write (#699).
+- Playhead and sequence marks validate bounds before writing and read back observed positions. Source Monitor edits verify the displayed clip, preserve unreadable post-write outcomes, and detect replacement timing when the same source is overwritten at the same cut (#694).
+- Clip parameter, track rename, selected-clip removal, and project bin moves verify stored results. Numeric property reads retain unreadable outcomes, English and measured Spanish lookups remain supported, and clearing an Out mark cannot be certified without independent full-media duration evidence (#696).
+- Media imports confirm new items for every requested path; labels, footage interpretation, bin names, graphics white luminance, and bin moves read back stored results. Invalid numeric interpretation reads cannot certify writes. CEP relink retains its default refusal and unverified unsafe opt-in (#697).
+- Tools that declare parameters now reject unknown top-level arguments instead of ignoring them. A misspelled or renamed argument (for example `item_ID` for `item_id`, or `time_seconds` for `start_seconds`) used to be dropped silently, and the tool ran with its default. The call now fails before anything is sent to Premiere, and the error names the unknown arguments and lists the ones the tool accepts. Clients or saved prompts that send extra or renamed fields must be updated. Tools whose schema already sets `additionalProperties` or `patternProperties` are unchanged, and UXP tools already rejected unknown properties. Tools that declare no parameters (for example `ping` or `save_project`) still ignore extra arguments. A catalog test fails if a handler reads an argument its schema does not declare.
+- CEP tools that change the project report `undoSteps` and `undoStackIndex` when Premiere recorded undo entries for the call, so an agent can reverse exactly that call. Tracking covers every non-inspect call, never reads the stack for inspect-only tools, and is reset across project switches. UXP tools and multi-command workflows are not counted; the undo descriptions say so and recommend `expected_undo_stack_index`. `has_proxy`, `is_work_area_enabled`, `verify_premiere_connection`, and `match_frame` are classed as inspect. (#654)
+- `export_sequence` refuses an `output_path` that already exists unless `overwrite: true`, checks that the preset's extension matches the output file (the default H.264 preset writes `.mov`), supports in/out ranges, and verifies a non-empty file was written. (#648)
+- `apply_lut` refuses instead of reporting `lutApplied: true`: Premiere 25.2.3 did not render a LUT set by path, and the old result had no readback. (#648)
+- `delete_project_item` removes items through a temporary bin. It refuses when the item is used in a sequence unless `confirm_remove_from_sequences: true`, refuses when a bin with the temporary name exists, and reads back that both are gone. `organize_project_items_uxp` remove is named as the preferred route. (#648)
+- A CEP command whose busy file stops changing now fails with "CEP panel appears stuck; reload it in Premiere" once its timeout passes; the busy file is never deleted automatically. (#648)
+
+### Fixed
+
+- UXP point and color parameter reads normalize host arrays and native objects before guarded inspection and write readback. RGB arrays use opaque alpha; absent values report `UXP_VALUE_UNAVAILABLE`, while scalar and malformed values fail with type-specific host errors. Client write/snapshot schemas remain strict objects (#765).
+- CEP enabled-state readers use the TrackItem `disabled` property with a legacy method fallback; this release includes the source fix absent from npm 1.18.6 (#764).
+
+- `trim_clip` and `slip_edit` now require physical media-duration evidence from ffprobe before changing source ranges, reject out-of-media edits, and refuse unknown duration or linked partners with different unprobed media. Editable project In/Out marks are not used as media boundaries (#712).
+- CEP marker add, update, and delete attempts protect a project-document-ID undo boundary even when the QE index moves or cannot be read. Undo/redo calls refuse a count that crosses it before stepping; `acknowledge_untracked_markers: true` explicitly permits prior non-marker actions. Barriers persist in the CEP engine through MCP server/helper reloads, but do not account for unobserved UXP/manual UI/other-client marker writes or survive engine resets (#733).
+
+- Ingest-transcode, timeline-tab closure, and Creative Cloud Library MOGRT import receipts now distinguish a host request from independent verification. Native errors preserve possible mutation and Library failures include Premiere's error text and actionable causes (#641).
+- `save_project` now refuses an untitled project (no saved path) before calling Premiere, which would otherwise open a blocking Save dialog, and fails when the `.prproj` is missing or empty after `save()`. Verification requires fresh file size or modification evidence; an unchanged existing file or unreadable disk evidence reports `committed_unverified` with `saved: null`.
+- `export_sequence` `range: "work_area"` now fails closed unless the enabled state is readable and true, and finite work-area bounds cover only part of the sequence within its readable duration. Unset or full-sequence work areas previously still called `ENCODE_WORKAREA` and could write the entire timeline as a verified work-area export.
+- `import_media` now rejects missing paths before calling Premiere, avoiding a blocking host dialog that can wedge the CEP bridge (#713).
+- Audio keyframes, ducking, and spot scale motion convert clip-relative offsets through the source in-point and refuse speed-changed clips; audio Level keys use the measured +15 dB-normalized mapping (0 dB = 0.1778, maximum +15 dB = 1), and key readback no longer accepts missing or nonfinite values as verified. (#693, #701)
+- Transition edits validate inputs before dispatch, read stored placements and durations, distinguish partial writes from no-ops, and preserve mutation evidence if native writes or later readback throw. QE transition edits remain experimental. (#704)
+
+- `apply_edit_plan` confirmation tokens are now random, issued only by `preview_edit_plan`, valid for 30 minutes, and consumed before the host edit. The private bridge directory retains token state across server restarts, so an applied token cannot be replayed after Undo or a restart (#728).
+- `color_correct` requires Lumetri component and every requested property to read back before reporting success. Missing catalog entries, ignored QE insertion, localized or missing controls, and ignored setters fail honestly; receipts explicitly leave rendered output unverified (#720).
+- `roll_edit` and `slide_edit` require physical source-duration evidence for every affected clip, bind edits to inspected placement/media, and reject invalid source windows or unknown duration before mutation. Slide readback checks exact placement and preserved source windows. Failures after a linked edit starts return `committed_unverified` and warn against retrying (#718, #719).
+
+- Audio volume tools now recognize Premiere's Spanish `Volumen` and `Nivel` labels and locale-independent `Internal Volume` component match names, including bulk track volume changes and `setup_ducking` (#710).
+- Legacy CEP `relink_media` now refuses by default because `changeMediaPath` can wedge Premiere on a valid file. Its explicit unsafe opt-in preflights the file and reports only `committed_unverified`; use `relink_offline_media_uxp` for capability checks and media-path/online readback (#729).
+- `add_to_render_queue` can request AME batch start with `start_batch: true` after queueing. This starts all ready AME jobs, including unrelated jobs, so the default remains enqueue only. The receipt reports whether batch start was requested, rejected, or unavailable; it does not claim output creation (#687).
+- `remove_all_effects` and `remove_effect_by_name` keep a graphic's Shape layers by their `AE.ADBE Shape` match name (confirmed on Premiere 25.2.3 with a stock lower third). A localized Shape layer still counts as proof of a localized host, so those hosts still refuse while the Time Remapping and Panner match names are unconfirmed. (#674)
+- `apply_effect` and `apply_audio_effect` verify added components instead of trusting QE; missing readback returns `committed_unverified` with a warning to inspect the clip before retrying. An unchanged component count and undo index report `not_applied`, for example `Time Remapping`, which QE accepts but never adds. (#674)
+- `create_sequence` and `create_sequence_from_preset` normalize `preset_path` to native separators before the QE call and report a missing preset file precisely (#691, #714): QE `newSequence` silently ignores forward-slash paths on Windows, which used to surface as a bare "Failed to create sequence from preset" error.
+- `add_to_timeline_batch` now reads each inserted placement again after all later sync-locked inserts. If a later insert moves or splits an earlier clip, the result reports the final observed span as `committed_unverified` instead of retaining an earlier `verified: true` receipt (#721). Automated tests cover same-track stability and cross-track drift; live Premiere behavior remains to be checked.
+- `create_sequence_from_preset` no longer reports `created: true` when QE `newSequence` leaves the already-active same-name sequence in place. It now snapshots sequence IDs first, the same way `create_sequence` does, and fails closed unless a new ID appears in the project collection.
+- The four dedicated video Motion/Opacity setters recognize the measured Spanish (es-ES) built-in component and property names. Position and Scale retain readback, and Rotation and Opacity now read the stored value back before reporting verified success (#722). Automated tests do not establish live host compatibility.
+- `get_export_file_extension` uses the existing AME preset-folder format map to infer an extension when Premiere returns none, but only for an existing .epr in a recognized folder; its receipt marks the inference as unconfirmed. `set_metadata` rejects unqualified project column names before a write. `add_keyframe` warns when the stored keyframe is outside the clip's visible span (#734).
+- Insert helpers now make an experimental QE pre-razor attempt for a target clip that spans the insertion point before calling `Sequence.insertClip`. Required QE routes and the frame boundary are checked before mutation; the existing adjacent-tail readback still refuses false success if a host displaces a tail (#730). This workaround has only been exercised in automated host fakes and needs live Premiere verification.
+- Marker add, update, and delete receipts now report whether Premiere recorded an undo step. On hosts where marker writes leave the undo index unchanged, `undoTracked: false` warns that Undo would reverse an earlier action instead of the marker (#733).
+- `add_to_timeline` and `insert_from_source` detect a target-track split tail that Premiere moved away from the insert point. They report the changed timeline as `committed_unverified`, including the observed tail position, instead of claiming the insert was verified. The edit still needs inspection or Undo on affected hosts. (#730)
+- Dialogue UXP apply accepts the documented Project/Sequence `guid` property when identity methods are unavailable, while still refusing changed or unreadable project identities before mutation (#685).
+- AME queue handoff normalizes output/preset paths to native separators and checks both host paths before launching the encoder (#711). A job ID remains an unverified handoff.
+- Export preflight and standard-DOM effect enumeration now state their verification limits: passing timeline checks does not verify exporter initialization, and omitted QE effects do not prove absence (#687, #690).
+
+- Effect removal classifies built-in components by match name, which is the same in every host language: `AE.ADBE Opacity`, `AE.ADBE Motion`, a graphic's `AE.ADBE Graphic Group`, `AE.ADBE Text`, and `AE.ADBE Shape`, and the `Internal Volume …` / `Internal Channel Volume …` audio intrinsics (seen live on Premiere 25.2.3). #654 refused on every mono clip, because mono clips have Volume but no Channel Volume; that is fixed. A built-in picked by index or name is refused whatever its language. Hosts with localized component names still refuse, now detected by a confirmed built-in match name showing a non-English name, because the match names of Time Remapping and Panner are not confirmed and an unknown one could be removed. (#674, #679)
+- EXPERIMENTAL (QE DOM): `remove_effect`, `remove_effect_by_name`, and `remove_all_effects` could not remove anything on Premiere 25.2, which has no DOM `Component.remove()`. They now fall back to QE removal, resolve every target's removal path before removing anything, never remove built-in components (Motion, Opacity, Volume, Channel Volume), and verify the result against the clip's component list. On hosts whose built-in component names are localized they refuse with nothing removed (#674). (#654)
+- `stop_playback` accepts `target: "timeline" | "source"`. Premiere's ExtendScript and UXP APIs have no documented call that stops only the Source Monitor, so `target: "source"` now returns an error and stops nothing, instead of the argument being ignored and the timeline stopped. (#642)
+- `export_as_project` and `export_as_fcp_xml` no longer report `exported: true` after a host call that writes no file. They require a real parent directory, then fail when the output is missing, empty, or identical to a pre-existing file. (#673)
+- `save_project_as` no longer reports `saved: true` when Premiere leaves a pre-existing `.prproj` unchanged. It snapshots size and modification time first, requires a real parent directory, and fails closed if the file is missing, empty, or identical to the snapshot.
+- User text containing U+2028, U+2029 or other control characters (for example a clip or marker name pasted from a document) no longer breaks the generated ExtendScript. ES3 treats U+2028/U+2029 as line terminators, so Premiere rejected the whole script with "EvalScript error"; `escapeForExtendScript` now writes them as `\uXXXX` escapes.
+- `add_marker` and `update_marker` read the marker's name, comments, color and duration back and report `verified`; when Premiere ignores part of the request the error says the marker was still created or changed (`timelineChanged`). Marker times, durations and color indexes (0-7) are validated before a script is built.
+- `remove_from_timeline` and edit plans ripple through Premiere's sync-locked ripple instead of `TrackItem.remove(true, …)`, which never rippled and left gaps and stray audio while reporting success. Every linked partner is checked for locks before anything is removed. (#648)
+- Linked audio and video stay in sync across razor, trim, slip, roll, slide, and duration edits: partner positions are snapshotted before any write, and a trim or duration change applies the main clip's offset to each partner from that snapshot. (#648)
+- `lift_selection` used a QE method that does not exist; `delete_track` now identifies default track names in any language; `consolidate_and_transfer`, both scratch-disk setters, `import_fcp_xml`, the proxy toggle, `encode_file`, and the After Effects MOGRT export work on 25.2. (#648)
+- `normalize_loudness_file` uses two-pass linear loudnorm at the source sample rate instead of single-pass, which missed its target by 1.6 LU and resampled to 96 kHz. (#648)
+- Two regexes in generated ExtendScript lost their `\s` escapes, so a clip's own frame size was never read (anchor points on a 4K clip in a 1080p sequence used the sequence size) and default track-name matching was loose. `set_clip_properties_batch` also writes Scale Width when Uniform Scale is off, so scaling no longer stretches the picture. (#648 review)
+
 ## [1.18.6] - 2026-09-29
 
 ### Fixed

package/README.md

@@ -14,7 +14,7 @@ Free, MIT licensed, local-first, and published to npm as [`premiere-pro-mcp`](ht
 
 [Website](https://premiere-pro-mcp.com/) · [Recorded demo](https://premiere-pro-mcp.com/demo/) · [Compare servers](https://premiere-pro-mcp.com/compare/) · [Setup guides](https://premiere-pro-mcp.com/blog/how-to-set-up-premiere-pro-mcp/) · [Search tools](https://premiere-pro-mcp.com/tools/) · [Troubleshooting](https://premiere-pro-mcp.com/docs/troubleshooting/) · [Release facts](https://premiere-pro-mcp.com/facts/)
 
-Development source: 384 core tools across 57 modules, 4 resources, and 19 guided workflows. A connected UXP host adds 96 capability-gated tools.
+Development source: 386 core tools across 57 modules, 4 resources, and 19 guided workflows. A connected UXP host adds 96 capability-gated tools.
 
 The [completed AE render handoff](docs/after-effects-render-handoff.md) previews and confirms importing one finished render into an existing Premiere bin, with host and file rechecks and an import receipt.
 
@@ -106,14 +106,14 @@ and repository before configuring a client. The new
 VS Code, or Codex settings that point directly to this installation. It is a
 feature included in v1.15.1 and later.
 
-The current source exposes 384 core tools for supported workflow steps spanning the supported ExtendScript, QE DOM, local media and interchange analysis, revisioned project-context retrieval, safe edit-planning, project-intake preview, review handoff, connection verification, and guarded After Effects MOGRT authoring, batch, library, render-queue, inspection, and Premiere-handoff workflows. A compatible, authenticated UXP panel adds 96 documented, capability-gated tools without replacing the production CEP bridge.
+The current source exposes 386 core tools for supported workflow steps spanning the supported ExtendScript, QE DOM, local media and interchange analysis, revisioned project-context retrieval, safe edit-planning, project-intake preview, review handoff, connection verification, and guarded After Effects MOGRT authoring, batch, library, render-queue, inspection, and Premiere-handoff workflows. A compatible, authenticated UXP panel adds 96 documented, capability-gated tools without replacing the production CEP bridge.
 
 <a id="latest-release"></a>
 
-### Latest release: 1.18.5
+### Latest release: 1.19.0
 
-The published v1.18.5 npm artifact contains **384 core tools**, 382 in its default profile,
-and 478 with a compatible UXP connection. The development catalog above can include
+The published v1.19.0 npm artifact contains **386 core tools**, 384 in its default profile,
+and 480 with a compatible UXP connection. The development catalog above can include
 unreleased work. See the [versioned facts and package provenance](https://premiere-pro-mcp.com/facts/).
 
 ### Try a bounded workflow
@@ -162,7 +162,7 @@ if the connection is unavailable.
   local Premiere processes. See the generated [supported action catalog](docs/supported-actions.md)
   for individual capability and verification contracts.
 
-See the [v1.18.5 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.18.5)
+See the [v1.19.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.19.0)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ### Current MCP protocol support
@@ -210,7 +210,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > ### Install the published package (verify the name)
 >
 > ```bash
-> npm i -g premiere-pro-mcp@1.18.5
+> npm i -g premiere-pro-mcp@1.19.0
 > ```
 >
 > This repository publishes only **`premiere-pro-mcp`**. A differently named package (`adobe-premiere-pro-mcp`) may also declare a `premiere-pro-mcp` executable. Before configuring a client, confirm:
@@ -218,7 +218,7 @@ their bins, media rules, and organization rules before a facility uses one.
 > | Check | Expected |
 > | --- | --- |
 > | Package name | `premiere-pro-mcp` (not `adobe-premiere-pro-mcp`) |
-> | Version | `1.18.5` |
+> | Version | `1.19.0` |
 > | Homepage / repo | https://premiere-pro-mcp.com/ · https://github.com/leancoderkavy/premiere-pro-mcp |
 >
 > ```bash
@@ -231,9 +231,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.18.5/premiere-pro-mcp-1.18.5.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.19.0/premiere-pro-mcp-1.19.0.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.18.5/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.19.0/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.`
 
@@ -268,9 +268,13 @@ connector still need to be installed separately.
 
 - Node.js **20.19 or newer** on Windows or macOS.
 - Adobe Premiere Pro **2020–2026**. Keep Premiere, the CEP bridge, and your MCP client on the same computer for the recommended local setup.
-- Optional: [ffmpeg](https://ffmpeg.org/download.html) on `PATH` for `detect_silence`
-  (`brew install ffmpeg` on macOS or `winget install Gyan.FFmpeg` on Windows).
-  The production Docker image already includes it.
+- For `trim_clip` and `slip_edit`, install [FFmpeg](https://ffmpeg.org/download.html)
+  with `ffprobe` on `PATH` (`brew install ffmpeg` on macOS or
+  `winget install Gyan.FFmpeg` on Windows). These source-range edits are unavailable
+  without `ffprobe` and accessible media with readable timestamp clocks: they
+  refuse before mutation when physical source bounds cannot be verified.
+  FFmpeg also provides the optional `detect_silence` dependency. The production
+  Docker image already includes it.
 
 #### 1. Install
 
@@ -533,11 +537,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.18.5 --install-cep
+npx -y premiere-pro-mcp@1.19.0 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.18.5` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.19.0` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -575,7 +579,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.18.5 --install-cep
+npx -y premiere-pro-mcp@1.19.0 --install-cep
 ```
 
 The Claude Code package lives in
@@ -899,7 +903,7 @@ reports revision-bound notes, VFX state, change impact and turnover exceptions.
 It performs local inspection; host edits and exports use separate guarded tools.
 See [usage, example and remaining execution adapters](docs/film-editorial-workflows.md).
 
-## Tools (384 core total; 382 under the default profile; 478 with a connected UXP bridge)
+## Tools (386 core total; 384 under the default profile; 480 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`
@@ -974,6 +978,10 @@ the tables below are a shorter workflow-oriented overview.
 > or exported frames before delivery. On macOS, AME preset discovery scans each installed app
 > bundle's `Contents/MediaIO/systempresets`; prefer a Match Source preset for vertical projects.
 
+> **Host limits:** [The capability ledger](docs/host-api-limitations.md) distinguishes
+> unavailable APIs, unverified host requests, and property/structure readback.
+> A verified parameter or component does not establish rendered appearance.
+
 > **Verified track edits:** `add_track` and `add_tracks` validate requested counts and
 > return success only when the active sequence's track counts exactly match the request.
 > `overwrite_clip` validates both selected track indices and confirms the requested source
@@ -1384,7 +1392,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 384 tools, filtered by authority profile
+│   ├── server.ts                # MCP server — registers 386 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/after-effects-cep-plugin/CSXS/manifest.xml

@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.18.6" ExtensionBundleName="MCP for Adobe After Effects">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.19.0" ExtensionBundleName="MCP for Adobe After Effects">
   <ExtensionList>
-    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.18.6"/>
+    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.19.0"/>
+    <Extension Id="com.mcp.aftereffects.bridge.headless" Version="1.19.0"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>
@@ -34,5 +35,29 @@
         </UI>
       </DispatchInfo>
     </Extension>
+    <Extension Id="com.mcp.aftereffects.bridge.headless">
+      <DispatchInfo>
+        <Resources>
+          <MainPath>./index.html</MainPath>
+          <ScriptPath>./host.jsx</ScriptPath>
+          <CEFCommandLine>
+            <Parameter>--allow-file-access-from-files</Parameter>
+            <Parameter>--enable-nodejs</Parameter>
+          </CEFCommandLine>
+        </Resources>
+        <Lifecycle>
+          <AutoVisible>false</AutoVisible>
+          <StartOn>
+            <Event>com.adobe.csxs.events.ApplicationActivate</Event>
+            <Event>applicationActivate</Event>
+          </StartOn>
+        </Lifecycle>
+        <UI>
+          <Type>Custom</Type>
+          <Geometry><Size><Height>1</Height><Width>1</Width></Size></Geometry>
+          <Icons/>
+        </UI>
+      </DispatchInfo>
+    </Extension>
   </DispatchInfoList>
 </ExtensionManifest>

package/after-effects-cep-plugin/main.js

@@ -82,6 +82,11 @@
     }
   }
 
+  // The visible panel and the headless auto-start instance both run this file.
+  // The rename claim decides which one owns a command; each instance runs one
+  // command at a time because After Effects' scripting engine is stateful.
+  var commandInFlight = false;
+
   function processOne(fileName) {
     var source = path.join(tempDir, fileName);
     var claim = source + "." + engineId + ".claimed";
@@ -90,6 +95,7 @@
     try { script = fs.readFileSync(claim, "utf8"); } catch (error) { script = null; }
     try { if (fs.existsSync(claim)) fs.unlinkSync(claim); } catch (ignored) {}
     if (!script) return;
+    commandInFlight = true;
     var id = fileName.replace("cmd_", "").replace(".jsx", "");
     var busy = path.join(tempDir, "busy_" + id + ".json");
     var started = Date.now();
@@ -97,6 +103,7 @@
       try { fs.writeFileSync(busy, JSON.stringify({ id: id, elapsedMs: Date.now() - started }), "utf8"); } catch (ignored) {}
     }, 2000);
     cs.evalScript(script, function (result) {
+      commandInFlight = false;
       clearInterval(busyTimer);
       try { if (fs.existsSync(busy)) fs.unlinkSync(busy); } catch (ignored) {}
       writeFileAtomic(path.join(tempDir, "res_" + id + ".json"), replyFor(String(result || "")));
@@ -104,8 +111,9 @@
   }
 
   function processCommands() {
+    if (commandInFlight) return;
     var files = readCommandFiles();
-    for (var index = 0; index < files.length; index++) processOne(files[index]);
+    if (files.length > 0) processOne(files[0]);
   }
 
   function start() {
@@ -130,7 +138,8 @@
 
   function stop() {
     running = false;
-    heartbeat();
+    // Leave the last heartbeat alone: a headless instance may still be running,
+    // and its heartbeat must not be overwritten with "waiting" by this panel.
     if (pollTimer) clearInterval(pollTimer);
     if (heartbeatTimer) clearInterval(heartbeatTimer);
     pollTimer = null;
@@ -141,4 +150,7 @@
   var field = document.getElementById("tempDir");
   try { field.value = localStorage.getItem("after_effects_mcp_temp_dir") || tempDir; } catch (ignored) { field.value = tempDir; }
   document.getElementById("toggle").onclick = function () { if (running) stop(); else start(); };
+  // Start automatically: the headless instance (StartOn ApplicationActivate) has
+  // no one to click Start, so without this the connector never ran unattended.
+  setTimeout(start, 500);
 }());

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.18.6" ExtensionBundleName="MCP for Adobe Premiere Pro">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.19.0" ExtensionBundleName="MCP for Adobe Premiere Pro">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.18.6"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.18.6"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.19.0"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.19.0"/>
   </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">MCP updates</span>
-        <strong id="updateTitle">Version 1.18.6</strong>
+        <strong id="updateTitle">Version 1.19.0</strong>
         <span id="updateDetail">Checking the global MCP server and connector release…</span>
       </div>
       <button id="btnUpdate" class="button button-update" onclick="handleUpdateClick()" type="button" aria-describedby="updateDetail" disabled>

package/cep-plugin/main.js

@@ -358,8 +358,15 @@ function processOneCommand(cmdFileName) {
       }
     } catch (e) {
       // If result isn't JSON, wrap it
-      if (result && result.indexOf("Error") === 0) {
-        response = JSON.stringify({ success: false, error: result });
+      // "EvalScript error." is CEP's generic message when the host script throws
+      // outside its own try/catch or does not parse. It is a failure, not data.
+      if (result && (result.indexOf("Error") === 0 || /^EvalScript error/i.test(result))) {
+        response = JSON.stringify({
+          success: false,
+          error: /^EvalScript error/i.test(result)
+            ? "Premiere could not run the generated script (" + result + "). No result was produced; treat the command as failed."
+            : result,
+        });
         log("Result: " + result, "err");
       } else {
         response = JSON.stringify({ success: true, data: result });

package/cep-plugin/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.18.6";
+  var CURRENT_VERSION = "1.19.0";
   var PACKAGE_NAME = "premiere-pro-mcp";
   var LATEST_PACKAGE_API = "https://registry.npmjs.org/" + PACKAGE_NAME;
   var LATEST_RELEASE_API =

package/dist/ai/film-editorial.js

@@ -126,10 +126,21 @@ export function buildFilmEditorialPacket(document, raw) {
         const source = sources.get(occurrence.sourceId);
         const item = coverage.get(occurrence.coverageId);
         const record = evidence.get(occurrence.evidenceId);
-        if (!source || !item || item.sourceId !== occurrence.sourceId || !record || record.kind !== "timeline" ||
-            record.timelineItemId !== occurrence.id || record.sourceId !== occurrence.sourceId || record.sequenceId !== occurrence.sequenceId ||
-            record.timelineRevision !== occurrence.timelineRevision || (record.sourceRevision !== undefined && record.sourceRevision !== source.sourceRevision))
-            throw new Error(`Occurrence identity/revision mismatch: ${occurrence.id}`);
+        // Name the failing check: the combined "identity/revision mismatch" gave callers
+        // nothing to fix (live: occurrence id must be the evidence's timelineItemId).
+        const mismatch = !source ? `sourceId ${occurrence.sourceId} is not in sources`
+            : !item ? `coverageId ${occurrence.coverageId} is not in coverage`
+                : item.sourceId !== occurrence.sourceId ? `coverage ${item.id} is for source ${item.sourceId}, not ${occurrence.sourceId}`
+                    : !record ? `evidenceId ${occurrence.evidenceId} is not in the captured context`
+                        : record.kind !== "timeline" ? `evidence ${occurrence.evidenceId} is a ${record.kind} record, not a timeline record`
+                            : record.timelineItemId !== occurrence.id ? `id must be the evidence's timelineItemId (${record.timelineItemId})`
+                                : record.sourceId !== occurrence.sourceId ? `evidence source is ${record.sourceId}, not ${occurrence.sourceId}`
+                                    : record.sequenceId !== occurrence.sequenceId ? `evidence sequence is ${record.sequenceId}, not ${occurrence.sequenceId}`
+                                        : record.timelineRevision !== occurrence.timelineRevision ? `timelineRevision must be the evidence's timelineItemRevision (${record.timelineRevision})`
+                                            : record.sourceRevision !== undefined && record.sourceRevision !== source.sourceRevision ? `evidence sourceRevision ${record.sourceRevision} differs from the source's ${source.sourceRevision}`
+                                                : null;
+        if (mismatch || !source || !item || !record)
+            throw new Error(`Occurrence identity/revision mismatch: ${occurrence.id}: ${mismatch}`);
         validRange(occurrence.sourceRange, occurrence.id, source.durationFrames);
         validRange(occurrence.timelineRange, occurrence.id);
         const secondsPerFrame = occurrence.timebase.denominator / occurrence.timebase.numerator;

package/dist/ai/reaction-shorts.js

@@ -86,6 +86,8 @@ function joinCueText(words) {
     return sentenceCase(words.map((word) => word.text.trim()).filter(Boolean).join(" "));
 }
 function renderCueText(cue, mergeGap) {
+    if (cue.continuation)
+        return cue.words.map((word) => word.text.trim()).filter(Boolean).join(" ");
     if (cue.merged_cue_count <= 1)
         return joinCueText(cue.words);
     const parts = [];
@@ -203,6 +205,72 @@ function mergeMicroCues(cues, minSoloSeconds, combineGapSeconds) {
     }
     return merged;
 }
+/**
+ * Split cues that are too long to read as one caption. Live test: a welcome
+ * speech produced 139- and 150-character cues held for 10 s. Breaks prefer the
+ * end of a clause (punctuation) once the part is reasonably full, and each part
+ * keeps its own word timings.
+ */
+const DANGLING_WORDS = new Set([
+    "a", "an", "the", "to", "of", "in", "on", "at", "for", "with", "by", "from", "and", "or", "but", "as",
+    "that", "this", "our", "my", "your", "their", "its", "i", "we", "is", "are", "be",
+]);
+function splitLongCues(cues, maxChars, maxSeconds) {
+    const out = [];
+    for (const cue of cues) {
+        if (joinCueText(cue.words).length <= maxChars && cue.end_seconds - cue.start_seconds <= maxSeconds + EPSILON) {
+            out.push(cue);
+            continue;
+        }
+        // Aim for evenly sized parts instead of filling each to the limit, so a
+        // 140-character sentence becomes two ~70-character captions, not 83 + 57.
+        const totalChars = joinCueText(cue.words).length;
+        const parts = Math.max(Math.ceil(totalChars / maxChars), Math.ceil((cue.end_seconds - cue.start_seconds) / maxSeconds));
+        const targetChars = Math.min(maxChars, Math.ceil(totalChars / parts) + 8);
+        let part = [];
+        let clauseBreak = -1;
+        let first = true;
+        const flush = (words) => {
+            if (!words.length)
+                return;
+            out.push({
+                ...cue,
+                words,
+                start_seconds: words[0].start_seconds,
+                end_seconds: words[words.length - 1].end_seconds,
+                continuation: cue.continuation || !first,
+            });
+            first = false;
+        };
+        for (const word of cue.words) {
+            const candidate = [...part, word];
+            const tooLong = joinCueText(candidate).length > targetChars;
+            const tooSlow = part.length > 0 && word.end_seconds - part[0].start_seconds > maxSeconds + EPSILON;
+            if (part.length && (tooLong || tooSlow)) {
+                if (clauseBreak >= 0 && joinCueText(part.slice(0, clauseBreak + 1)).length >= targetChars * 0.5) {
+                    flush(part.slice(0, clauseBreak + 1));
+                    part = part.slice(clauseBreak + 1);
+                }
+                else {
+                    // Never leave a caption hanging on a function word ("…welcome to").
+                    let keep = part.length;
+                    while (keep > 1 && DANGLING_WORDS.has(part[keep - 1].text.trim().toLowerCase()))
+                        keep -= 1;
+                    flush(part.slice(0, keep));
+                    part = part.slice(keep);
+                }
+                clauseBreak = -1;
+                part.forEach((kept, index) => { if (/[,.;:!?]$/.test(kept.text.trim()))
+                    clauseBreak = index; });
+            }
+            part.push(word);
+            if (/[,.;:!?]$/.test(word.text.trim()))
+                clauseBreak = part.length - 1;
+        }
+        flush(part);
+    }
+    return out;
+}
 function assignStacks(cues, warnings) {
     const ordered = [...cues].sort((left, right) => left.start_seconds - right.start_seconds || left.end_seconds - right.end_seconds);
     let stacked = 0;
@@ -256,6 +324,7 @@ export function planReactionCaptions(input) {
     rejectUnknownKeys(input, [
         "word_timeline", "speaker_palette", "shot_changes", "frame_rate",
         "merge_gap_seconds", "min_solo_cue_seconds", "combine_gap_seconds", "min_hold_seconds",
+        "max_cue_chars", "max_cue_seconds",
     ], "arguments");
     const timeline = validateWordTimeline(input.word_timeline);
     const palette = parseSpeakerPalette(input.speaker_palette);
@@ -265,9 +334,11 @@ export function planReactionCaptions(input) {
     const minSolo = boundedNumber(input.min_solo_cue_seconds, "min_solo_cue_seconds", 0.15, 3, 0.45);
     const combineGap = boundedNumber(input.combine_gap_seconds, "combine_gap_seconds", 0, 5, 0.8);
     const minHold = boundedNumber(input.min_hold_seconds, "min_hold_seconds", 0.15, 3, 0.35);
+    const maxChars = boundedNumber(input.max_cue_chars, "max_cue_chars", 16, 400, 84, true);
+    const maxSeconds = boundedNumber(input.max_cue_seconds, "max_cue_seconds", 1, 30, 6);
     const warnings = [];
     const grouped = groupSpeakerCues(timeline.words, mergeGap);
-    const combined = mergeMicroCues(grouped, minSolo, combineGap);
+    const combined = splitLongCues(mergeMicroCues(grouped, minSolo, combineGap), maxChars, maxSeconds);
     alignCuesToShots(combined, shots, minHold, warnings);
     const stackedOverlapCount = assignStacks(combined, warnings);
     const uncertain = new Set();
@@ -310,6 +381,7 @@ export function planReactionCaptions(input) {
             "Overlapping different-speaker cues stack: the earlier in-point stays on the main (bottom) line; later talkers move up one slot.",
             "A caption never receives a guessed color. Missing palette entries stay uncertain until the editor names the speaker.",
             "Labeled shot changes clamp a matching speaker's in-point forward when that still leaves a readable hold.",
+            "Cues longer than max_cue_chars (default 84, two 42-character lines) or max_cue_seconds (default 6) split at word boundaries, preferring the end of a clause.",
         ],
         applied: false,
         apply_boundary: applyBoundary(),

package/dist/bridge/after-effects-bridge.js

@@ -25,6 +25,10 @@ export function sendAfterEffectsCommand(script, options = {}) {
         ...afterEffectsOptions,
         tempDir: getAfterEffectsTempDir(),
         helpers: AFTER_EFFECTS_BRIDGE_HELPERS,
+        hostLabel: "After Effects",
+        // The bundled AE panel always publishes a heartbeat; none means AE or the
+        // panel is not running, so fail now rather than after the full timeout.
+        requireHeartbeat: true,
     });
 }
 //# sourceMappingURL=after-effects-bridge.js.map

package/dist/bridge/after-effects-script-builder.js

@@ -4,6 +4,7 @@
  * assumptions from a different host in AE's long-lived ExtendScript engine.
  */
 import { createHash } from "node:crypto";
+import { escapeUnsafeLiteralCharacters } from "./script-builder.js";
 const HELPERS = `
 function __aeJsonStringify(value) {
   if (value === null) return "null";
@@ -46,12 +47,15 @@ export function buildAfterEffectsScript(code) {
     return `(function() {\n  try {\n    ${code}\n  } catch (error) {\n    return __aeError(error.toString());\n  }\n})();`;
 }
 export function escapeForAfterEffects(value) {
-    return value
+    // Same gap as escapeForExtendScript: U+2028/U+2029 end an ES3 string
+    // literal, and control characters or lone surrogates do not survive the
+    // command file, so they are written as \uXXXX escapes last.
+    return escapeUnsafeLiteralCharacters(value
         .replace(/\\/g, "\\\\")
         .replace(/"/g, '\\"')
         .replace(/'/g, "\\'")
         .replace(/\n/g, "\\n")
         .replace(/\r/g, "\\r")
-        .replace(/\t/g, "\\t");
+        .replace(/\t/g, "\\t"));
 }
 //# sourceMappingURL=after-effects-script-builder.js.map

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

@@ -7,6 +7,8 @@ export declare const BRIDGE_HEARTBEAT_STALE_MS = 3000;
 export interface BridgeOptions {
     tempDir?: string;
     timeoutMs?: number;
+    /** Host application named in timeout guidance (default "Premiere Pro"). */
+    hostLabel?: string;
     /**
      * Host-specific bootstrap contract. Premiere is the default; companion
      * bridges (such as After Effects) supply their own narrow helper surface.
@@ -18,6 +20,12 @@ export interface BridgeOptions {
      * A missing heartbeat remains compatible with older installed connectors.
      */
     failFastOnUnreadyHeartbeat?: boolean;
+    /**
+     * Treat a missing heartbeat as "connector not running" and fail at once.
+     * For connectors that always publish one (the bundled After Effects panel),
+     * so a closed host is reported immediately instead of after the full timeout.
+     */
+    requireHeartbeat?: boolean;
 }
 export interface BridgeHelpers {
     source: string;