premiere-pro-mcp 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-10-11
+
+### Added
+
+- `get_caption_style_guidance` accepts an optional, bounded `custom_style` (font family/weight, font size 8-400 px, `#RRGGBB` fill, up to three strokes with width and outer/inner/center placement, drop shadow, one of nine zones, X/Y offsets, Track Style name) and returns that spec with numbered Premiere UI steps carrying the exact values. Each extra stroke is added with + next to Stroke, and the look is saved via Track Style > + Create style. Preset steps use the same workflow. Results add `track_style` (whole-track scope, reuse from the Track Style dropdown in other sequences, project item in the Project panel), `limitations`, `warnings` (for example, layered outer strokes that do not grow wider) and `applied: false`. It is still guidance only: Premiere exposes no caption style API, so nothing is applied. Verify the look with `export_frame` or `export_sequence_review_frames`. Calls that pass only `preset` keep their `style` fields.
+- The platform capability report lists `captionTrackStyle` under the CEP `unsupported` map, so clients see that caption track styling cannot be automated and are pointed to `get_caption_style_guidance`.
+
+### Fixed
+
+- `__setItemMarks` now writes the same quarter-grid-biased seconds when applying a temporary overwrite range. Premiere 26.5.2 can floor exact tick-boundary seconds one media frame early, so `unnest_sequence` (16-tick default tolerance) refused a valid nest, or `replace_clip` placed a clip one frame short after the original was already removed. `replace_clip` also pulls a placed end that overshoots the original span by less than one media frame back onto that span.
+
+- `__itemMarksForRestore` now applies that same write bias when it returns DOM marks (no private metadata, or DOM already matching the private range). Those paths previously handed exact tick-boundary seconds to restore, so a normal clip could shrink one media frame after replace/unnest on 26.5.2.
+
+## [1.23.0] - 2026-10-11
+
+### Added
+
+- 41 bounded core tools and five guided workflow routes from the [52-item Filmcraft implementation ledger](docs/filmcraft-improvements.md). The source catalog now declares 434 core tools, 432 under default authority and 528 with 96 capability-gated UXP additions.
+- Guarded execution and recovery with a private shared host lease, expected project/sequence targets, structured mutation receipts, cancellation/progress context, durable hashed UXP replay reservations and versioned command/receipt contracts. UXP writes require native cryptographic entropy and compatible durable replay storage; older unversioned panels remain read-only.
+- Exact tick/rate timeline models, typed compound edit previews, sync and stacked-camera planning, transcript/caption/music/scene review, provenance, checkpoints and bounded edit-property fixtures.
+- Bounded OTIO/XML inspection and loss reports, ALE/CSV adapters and audio-post turnover plans. Unsupported native round trips and opaque serializers remain explicit rather than being reported as completed exports.
+- Verified delivery, checksum-pinned review artifacts, local job inspection/cancellation, rendered scopes and actual multi-frame RGB/ROI/PCM evidence tools, plus opt-in analysis caching, performance diagnostics and licensed-host fixture/report helpers.
+
+### Fixed
+
+- Folder imports now verify Premiere project-item readback instead of treating an accepted import call as proof that all requested media was imported. Counts and partial outcomes describe the observed project state.
+- Caption imports validate supported formats before dispatch, preserve mutation readback and reject counts outside the safe integer range.
+
+- Registered tools accept optional request-scoped `expected_project_path`; generated CEP commands refuse a different, missing or unsaved active project before the tool body. UXP and After Effects refuse this CEP-only guard. Omitting the guard preserves existing behavior.
+
+- `unnest_sequence` now refuses, before removing the nested clip, any inner item that also carries the other media type. Premiere 26.5.2's `Track.overwriteClip` places that media on the matching track and overwrites the clips there. Same guard as `replace_clip`. Unnest a nest of video-only or audio-only items, or use Premiere's Unnest command.
+- Shared project-item mark restore after `replace_clip`, `unnest_sequence`, and other `Track.overwriteClip` helpers now writes the quarter-frame-biased seconds from `__itemMarksForRestore`. Writing the exact tick boundary as seconds can floor one media frame early on Premiere 26.5.2 (a soft-subclip Out of `00:00:29:22` stored as `00:00:29:21`), shrinking the source item. `duplicate_clip` and `set_item_in_out` already used those seconds.
+
+- `export_sequence` without `preset_path` no longer exports at proxy resolution when Media Encoder is not installed. Preset discovery only searched Premiere's `Settings/IngestPresets`, so the default became `IngestPresets/Proxy/00_1024x540 H.264.epr` and a 1080x1920 sequence was exported at 1024x540 while reporting `verified: true` (Premiere 24.0, macOS). Preset discovery now also searches Premiere's own `MediaIO/systempresets` when no Media Encoder presets exist, and the default never comes from `IngestPresets`; if no other H.264 preset is found, the tool asks for `preset_path`.
+
+### Compatibility and evidence
+
+CEP remains the production bridge; failed UXP mutations never fall back to CEP or QE. Recovery preserves unknown and partial outcomes. Native multicam switching, nonlinear/nested retime mapping, DSP music rendering, OCR and accepted-native-job cancellation remain unsupported. Local decoder tests establish artifact behavior, while licensed Premiere playback, Undo/reopen and native round-trip validation remain `not_run`.
+
 ## [1.22.0] - 2026-10-08
 
 ### 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: 393 core tools across 60 modules, 4 resources, and 24 guided workflows. A connected UXP host adds 96 capability-gated tools.
+Development source: 434 core tools across 67 modules, 4 resources, and 29 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.
 
@@ -125,17 +125,17 @@ 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 393 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 434 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.22.0
+### Latest release: 1.24.0
 
-The published v1.22.0 npm artifact contains **393 core tools**, 391 in its default profile,
-and 487 with a compatible UXP connection. The development catalog above can include
+The published v1.24.0 npm artifact contains **434 core tools**, 432 in its default profile,
+and 528 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/).
 
-GitHub releases use `v<SemVer>` for both title and tag, such as `v1.22.0`.
+GitHub releases use `v<SemVer>` for both title and tag, such as `v1.24.0`.
 See [release naming and version conventions](docs/release-conventions.md).
 
 ### Try a bounded workflow
@@ -154,6 +154,12 @@ if the connection is unavailable.
 
 ### Release highlights
 
+- **1.24.0 mark-write fixes:** temporary overwrite marks and restored project-item marks are written a quarter media frame past the tick boundary, so Premiere 26.5.2 no longer floors them one frame early in `unnest_sequence`, `replace_clip` and `duplicate_clip`.
+- **1.24.0 caption style guidance:** `get_caption_style_guidance` accepts a bounded `custom_style` and returns Properties panel and Track Style steps; it is guidance only and applies nothing.
+- **1.23.0 bounded workflows:** 41 added core tools and five guided routes cover exact timeline planning, editorial review, interchange/turnover and guarded delivery. The [52-item implementation ledger](docs/filmcraft-improvements.md) records each supported subset and host limit.
+- **1.23.0 execution and recovery:** cooperating processes serialize protected edits, retain recovery for uncertain outcomes and report cancellation/partial work explicitly. UXP writes require the matching updated panel; older unversioned panels remain read-only.
+- **1.23.0 artifact evidence:** review and delivery checks pin source checksums, inspect actual decoded frames/audio and preserve unknown native-job completion. Local decoder checks do not establish Premiere playback or native round-trip compatibility.
+- **1.23.0 import fixes:** folder imports verify actual project-item readback; caption imports validate formats and counts and preserve mutation readback. Export preset discovery avoids proxy ingest presets, and unnesting refuses mixed-media overwrite hazards.
 - **1.22.0 readback receipts:** effect writes, stabilization, smart bins, proxies, folder imports, sequence creation, marker deletion and clip selection report what Premiere applied as `verified`, `committed_unverified` or `failed`; `create_subclip`, `add_title` and `update_marker` report the stored values; `set_sequence_frame_rate` lists clips Premiere re-snapped.
 - **1.22.0 display codes and proxies:** `set_sequence_display_format` writes Premiere's real display codes (video 100-113, audio 200-201) and maps the older 0-11 and 0-1 inputs onto them; `manage_proxies` toggle can set a known proxy display state; the Windows ACL check waits up to 30 seconds for PowerShell.
 - **1.21.0 Claude Desktop startup fix:** the extension starts when optional settings are blank, and Desktop's discover-only probe no longer holds the UXP port, so the real server keeps its UXP tools.
@@ -195,7 +201,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.22.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.22.0)
+See the [v1.24.0 release notes](https://github.com/leancoderkavy/premiere-pro-mcp/releases/tag/v1.24.0)
 for complete details. Live installation in Premiere Pro still requires host verification.
 
 ### Current MCP protocol support
@@ -213,6 +219,16 @@ handshake only; leave it unset (or `auto`) for modern MCP capabilities.
 
 ---
 
+### Guarding multi-project CEP sessions
+
+Every registered tool accepts optional `expected_project_path`, an absolute path to the intended saved Premiere project. Generated CEP scripts compare the active project's host-normalized file path before the tool body; a different, missing or unsaved project refuses without running that body. The guard is scoped to the request and checked for every generated command in a multi-command tool. Omitting it preserves existing behavior.
+
+```json
+{"name":"get_project_info","arguments":{"expected_project_path":"/Projects/Film.prproj"}}
+```
+
+This protects against accidental active-project switches, not deliberate project switching inside unsafe scripts. It does not select a project or prove media identity. Paths remain in request context and are not telemetry. UXP and After Effects commands refuse this CEP-only guard; UXP workflows use their `expected_snapshot` identity contracts. Local-only tools do not inspect Premiere. Filesystem aliases are not resolved as a claim of project identity.
+
 ## For editors evaluating an AI workflow
 
 Before an assistant changes an active project, use the
@@ -243,7 +259,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.22.0
+> npm i -g premiere-pro-mcp@1.24.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:
@@ -251,7 +267,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.22.0` |
+> | Version | `1.24.0` |
 > | Homepage / repo | https://premiere-pro-mcp.com/ · https://github.com/leancoderkavy/premiere-pro-mcp |
 >
 > ```bash
@@ -264,9 +280,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.22.0/premiere-pro-mcp-1.22.0.mcpb).
+1. Download the current [Claude Desktop bundle (`.mcpb`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.24.0/premiere-pro-mcp-1.24.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.22.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.
+3. Download the separate [signed Premiere connector (`.zxp`)](https://github.com/leancoderkavy/premiere-pro-mcp/releases/download/v1.24.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.`
 
@@ -570,11 +586,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.22.0 --install-cep
+npx -y premiere-pro-mcp@1.24.0 --install-cep
 ```
 
 Restart Premiere Pro and start a new Codex session after installation. The plugin
-launches `premiere-pro-mcp@1.22.0` through `npx`; the separate CEP installation is
+launches `premiere-pro-mcp@1.24.0` through `npx`; the separate CEP installation is
 required because the MCP server communicates with the running Premiere host through
 the local bridge.
 
@@ -612,7 +628,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.22.0 --install-cep
+npx -y premiere-pro-mcp@1.24.0 --install-cep
 ```
 
 The Claude Code package lives in
@@ -829,7 +845,7 @@ PREMIERE_UXP_TOKEN="replace-with-a-long-random-secret" premiere-pro-mcp
 
 Generate that secret yourself and enter the same value in the UXP panel (**Window → UXP Plugins**, not the CEP Connector). CEP-only setups do not use a token. 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 91 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, guarded sequence-range updates, guarded source-media start timing, and guarded source-media frame-rate/pixel-aspect overrides 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, native video-transition listing and guarded transactions, native active and explicit-GUID sequence timing inspection, opt-in installed-MOGRT directory inspection without filesystem enumeration, bounded native timeline structure inspection with opt-in source IDs, classification, and broad content category, guarded sequence display-format updates, a capped native Project-panel tree, a double-read Project-panel insertion-bin snapshot, guarded empty/default sequence creation, bounded native Project-panel schema/item-column metadata inspection, guarded direct Project-panel metadata replacements with exact state/readback guards, guarded typed Project metadata schema-field creation with non-field-level readback, guarded direct updates to three named application preferences, guarded transcript JSON replacement for one exact source clip, direct active-track-item identity readback, guarded source-only slips, guarded contiguous three-item slides, guarded append-only timeline duplicates, guarded contiguous same-track ripple deletes, guarded source-project-item color labels resolved from one timeline coordinate, guarded explicit-sequence preview-frame rectangle updates, explicit opt-in source-media provenance paths with bounded double resolution, bounded source-proxy readiness with an explicit attached-path disclosure, guarded static effect-parameter PointF x/y updates, bounded effect-parameter descriptor catalogs, bounded project/sequence Object Mask audits, native FrameRate/TickTime frame-alignment inspection with caller-owned inputs and tick readback, and native TickTime arithmetic over caller-owned canonical tick strings; it does not claim direct empty-track create/delete, global redo support, playback proof, Object Mask counts or visual validity, an atomic Project-panel metadata compare-and-set, app-preference Undo, installed-template availability or compatibility, imported transcript persistence, override-presence/clear semantics, path existence, source lineage or rights, proxy compatibility, general or keyframed effect-parameter value readback, rendered-frame correctness, linked-item sync, or licensed-host validation. 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), [the next-ten workflow matrix](docs/uxp-next-ten-workflows.md), [the guarded-slip workflow notes](docs/uxp-slip-workflows.md), [the guarded-slide workflow notes](docs/uxp-slide-workflows.md), [the guarded-duplicate workflow notes](docs/uxp-clone-workflows.md), and [the guarded-ripple-delete workflow notes](docs/uxp-ripple-delete-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 96 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, guarded sequence-range updates, guarded source-media start timing, and guarded source-media frame-rate/pixel-aspect overrides 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, native video-transition listing and guarded transactions, native active and explicit-GUID sequence timing inspection, opt-in installed-MOGRT directory inspection without filesystem enumeration, bounded native timeline structure inspection with opt-in source IDs, classification, and broad content category, guarded sequence display-format updates, a capped native Project-panel tree, a double-read Project-panel insertion-bin snapshot, guarded empty/default sequence creation, bounded native Project-panel schema/item-column metadata inspection, guarded direct Project-panel metadata replacements with exact state/readback guards, guarded typed Project metadata schema-field creation with non-field-level readback, guarded direct updates to three named application preferences, guarded transcript JSON replacement for one exact source clip, direct active-track-item identity readback, guarded source-only slips, guarded contiguous three-item slides, guarded append-only timeline duplicates, guarded contiguous same-track ripple deletes, guarded source-project-item color labels resolved from one timeline coordinate, guarded explicit-sequence preview-frame rectangle updates, explicit opt-in source-media provenance paths with bounded double resolution, bounded source-proxy readiness with an explicit attached-path disclosure, guarded static effect-parameter PointF x/y updates, bounded effect-parameter descriptor catalogs, bounded project/sequence Object Mask audits, native FrameRate/TickTime frame-alignment inspection with caller-owned inputs and tick readback, and native TickTime arithmetic over caller-owned canonical tick strings; it does not claim direct empty-track create/delete, global redo support, playback proof, Object Mask counts or visual validity, an atomic Project-panel metadata compare-and-set, app-preference Undo, installed-template availability or compatibility, imported transcript persistence, override-presence/clear semantics, path existence, source lineage or rights, proxy compatibility, general or keyframed effect-parameter value readback, rendered-frame correctness, linked-item sync, or licensed-host validation. 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), [the next-ten workflow matrix](docs/uxp-next-ten-workflows.md), [the guarded-slip workflow notes](docs/uxp-slip-workflows.md), [the guarded-slide workflow notes](docs/uxp-slide-workflows.md), [the guarded-duplicate workflow notes](docs/uxp-clone-workflows.md), and [the guarded-ripple-delete workflow notes](docs/uxp-ripple-delete-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. UXP edits require a matching command-schema/receipt version, durable panel ledger storage and native cryptographic entropy; older unversioned panels remain read-only until the matching panel is installed.
 
 The bounded UXP migration surface also exposes a read-only animated-PointF endpoint-displacement inspection through `automate_effect_parameters_uxp`. It requires one exact component and parameter target plus a strictly increasing time interval, double-reads native endpoint values and their distance, and refuses static, malformed, or changed parameter state. It does not modify Premiere or prove rendered appearance, playback, persistence, Undo, or licensed-host behavior.
 
@@ -938,7 +954,10 @@ See [usage, example and remaining execution adapters](docs/film-editorial-workfl
 
 Reviewed assistant-editing tools now provide dialogue candidate decisions, quote paper-edit CSV, batch copy previews, sync-evidence triage, and owned-footage B-roll review. These are local evidence reviews, not new host engines. See [review workflow contracts](docs/editorial-review-workflows.md).
 
-## Tools (393 core total; 391 under the default profile; 487 with a connected UXP bridge)
+See [Filmcraft improvement ledger](docs/filmcraft-improvements.md) for exact-time
+planning, recovery, job observation, temporal evidence and facility workflows.
+
+## Tools (434 core total; 432 under the default profile; 528 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`
@@ -1090,9 +1109,11 @@ adjusted. This is a CEP contract check, not validation in a licensed Premiere Pr
 | `encode_project_item` / `encode_file` | Direct encoding |
 | `start_batch_encode` | Start render queue |
 
-Premiere's documented automation surfaces do not currently expose OTIO or native
-EDL interchange, Render and Replace, cloud publishing, or Content Credentials
-export configuration. `export_sequence_edl` therefore builds the CMX 3600 list
+Documented Premiere UXP exposes format-specific OTIO import/export through
+runtime-probed `export_interchange_uxp` and `import_interchange_uxp`. CEP has no
+documented native OTIO route. Native EDL, Render and Replace, cloud publishing
+and Content Credentials export configuration remain unavailable through the
+supported automation contracts. `export_sequence_edl` therefore builds the CMX 3600 list
 locally from the clips Premiere reads back and validates it with the same parser
 used by `inspect_cmx3600_edl`; it is not a Premiere-native export.
 `get_capabilities` reports the remaining delivery gaps explicitly rather than
@@ -1427,7 +1448,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 393 tools, filtered by authority profile
+│   ├── server.ts                # MCP server — registers 434 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,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.22.0" ExtensionBundleName="MCP for Adobe After Effects">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.aftereffects.bridge" ExtensionBundleVersion="1.24.0" ExtensionBundleName="MCP for Adobe After Effects">
   <ExtensionList>
-    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.22.0"/>
-    <Extension Id="com.mcp.aftereffects.bridge.headless" Version="1.22.0"/>
+    <Extension Id="com.mcp.aftereffects.bridge.panel" Version="1.24.0"/>
+    <Extension Id="com.mcp.aftereffects.bridge.headless" Version="1.24.0"/>
   </ExtensionList>
   <ExecutionEnvironment>
     <HostList>

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.22.0" ExtensionBundleName="MCP for Adobe Premiere Pro">
+<ExtensionManifest Version="7.0" ExtensionBundleId="com.mcp.premiere.bridge" ExtensionBundleVersion="1.24.0" ExtensionBundleName="MCP for Adobe Premiere Pro">
   <ExtensionList>
-    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.22.0"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.22.0"/>
+    <Extension Id="com.mcp.premiere.bridge.panel" Version="1.24.0"/>
+    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.24.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.22.0</strong>
+        <strong id="updateTitle">Version 1.24.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

@@ -248,6 +248,8 @@ function writeBridgeHeartbeat() {
   try {
     fs.writeFileSync(stagedPath, JSON.stringify({
       protocolVersion: 1,
+      commandSchemaVersion: 1,
+      receiptVersion: 1,
       state: bridgeRunning ? "running" : "waiting"
     }), "utf-8");
     fs.renameSync(stagedPath, heartbeatPath);

package/cep-plugin/updater.cjs

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

package/dist/ai/caption-authoring.d.ts

@@ -103,6 +103,101 @@ type PlatformProfile = {
 /** Approximate platform UI occlusion zones as normalized rects (x, y top-left). Verify against current platform overlay guides. */
 export declare const PLATFORM_SAFE_ZONES: Record<SafeZonePlatform, PlatformProfile>;
 export declare function describeCaptionStyle(preset: CaptionStylePreset): CaptionStyleDescriptor;
+export declare const CAPTION_ZONES: readonly ["top_left", "top_center", "top_right", "middle_left", "middle_center", "middle_right", "bottom_left", "bottom_center", "bottom_right"];
+export type CaptionZone = (typeof CAPTION_ZONES)[number];
+export declare const CAPTION_STROKE_PLACEMENTS: readonly ["outer", "inner", "center"];
+export type CaptionStrokePlacement = (typeof CAPTION_STROKE_PLACEMENTS)[number];
+export declare const MAX_CAPTION_STROKES = 3;
+export declare const CUSTOM_CAPTION_STYLE_LIMITS: {
+    readonly font_family_max_length: 128;
+    readonly font_weight_max_length: 64;
+    readonly track_style_name_max_length: 80;
+    readonly font_size_px: {
+        readonly min: 8;
+        readonly max: 400;
+    };
+    readonly stroke_width_px: {
+        readonly min: 0;
+        readonly max: 100;
+    };
+    readonly offset_px: {
+        readonly min: -2000;
+        readonly max: 2000;
+    };
+    readonly shadow: {
+        readonly opacity: {
+            readonly min: 0;
+            readonly max: 100;
+        };
+        readonly angle: {
+            readonly min: 0;
+            readonly max: 360;
+        };
+        readonly distance: {
+            readonly min: 0;
+            readonly max: 200;
+        };
+        readonly size: {
+            readonly min: 0;
+            readonly max: 100;
+        };
+        readonly blur: {
+            readonly min: 0;
+            readonly max: 100;
+        };
+    };
+};
+export declare const CAPTION_SHADOW_DEFAULTS: {
+    readonly color: "#000000";
+    readonly opacity: 75;
+    readonly angle: 135;
+    readonly distance: 7;
+    readonly size: 0;
+    readonly blur: 40;
+};
+export declare const DEFAULT_TRACK_STYLE_NAME = "Caption Track Style";
+export type CaptionStroke = {
+    color: string;
+    width_px: number;
+    placement: CaptionStrokePlacement;
+};
+export type CaptionShadow = {
+    color: string;
+    opacity: number;
+    angle: number;
+    distance: number;
+    size: number;
+    blur: number;
+};
+export type CustomCaptionStyle = {
+    font_family?: string;
+    font_weight?: string;
+    font_size_px?: number;
+    fill_color?: string;
+    strokes?: CaptionStroke[];
+    shadow?: CaptionShadow;
+    zone?: CaptionZone;
+    offset_x_px?: number;
+    offset_y_px?: number;
+    track_style_name?: string;
+};
+export declare function validateCustomCaptionStyle(value: unknown): CustomCaptionStyle;
+/** Warnings about a custom style that Premiere will accept but that may not render as intended. */
+export declare function customCaptionStyleWarnings(style: CustomCaptionStyle): string[];
+/** Premiere 2024+ Properties-panel / Track Style steps for a custom caption style. */
+export declare function buildCustomCaptionStyleSteps(style: CustomCaptionStyle, preset?: CaptionStylePreset): string[];
+/** Premiere 2024+ Properties-panel / Track Style steps for a built-in preset. */
+export declare function buildPresetCaptionStyleSteps(style: CaptionStyleDescriptor): string[];
+export declare const CAPTION_TRACK_STYLE_GUIDANCE: {
+    readonly scope: "A Track Style applies to every caption on the caption track. Style one caption, save it with Track Style > + Create style, and the whole track updates; no multi-select is needed.";
+    readonly reusable: "A saved Track Style can be applied to the caption track of any other sequence in the project from the Track Style dropdown.";
+    readonly project_item: "Each Track Style is stored as a project item in the Project panel; keep it in a shared bin so it can be found and reused.";
+    readonly limitations: readonly ["Premiere Pro exposes no documented ExtendScript, QE DOM, or UXP API that creates, edits, or applies caption styles, so these steps must be performed in the Premiere UI.", "These steps target Premiere Pro 2024 and later. Earlier versions lack the Track Style workflow described here and were not checked; panel labels can also differ between versions and UI languages.", "Verify the rendered result with export_frame or export_sequence_review_frames; this tool cannot read the applied style back."];
+};
+export declare function captionSafeZoneRecommendation(): Record<SafeZonePlatform, {
+    x: number;
+    y: number;
+}>;
 export declare function formatCaptionTimestamp(ms: number, format: CaptionFormat): string;
 /** Greedy word wrap that never splits a word; a single word longer than the width occupies its own line. */
 export declare function wrapCaptionWords(words: readonly string[], maxChars: number): string[][];

package/dist/ai/caption-authoring.js

@@ -154,6 +154,219 @@ export function describeCaptionStyle(preset) {
         note: "Documentation only. SRT/VTT artifacts carry timing and text; apply visual styling in Premiere's caption track style after import.",
     };
 }
+// ---------------------------------------------------------------------------
+// Custom caption track style (documentation only)
+// ---------------------------------------------------------------------------
+export const CAPTION_ZONES = ["top_left", "top_center", "top_right", "middle_left", "middle_center", "middle_right", "bottom_left", "bottom_center", "bottom_right"];
+export const CAPTION_STROKE_PLACEMENTS = ["outer", "inner", "center"];
+export const MAX_CAPTION_STROKES = 3;
+export const CUSTOM_CAPTION_STYLE_LIMITS = {
+    font_family_max_length: 128,
+    font_weight_max_length: 64,
+    track_style_name_max_length: 80,
+    font_size_px: { min: 8, max: 400 },
+    stroke_width_px: { min: 0, max: 100 },
+    offset_px: { min: -2000, max: 2000 },
+    shadow: {
+        opacity: { min: 0, max: 100 },
+        angle: { min: 0, max: 360 },
+        distance: { min: 0, max: 200 },
+        size: { min: 0, max: 100 },
+        blur: { min: 0, max: 100 },
+    },
+};
+export const CAPTION_SHADOW_DEFAULTS = { color: "#000000", opacity: 75, angle: 135, distance: 7, size: 0, blur: 40 };
+export const DEFAULT_TRACK_STYLE_NAME = "Caption Track Style";
+const CUSTOM_STYLE_KEYS = ["font_family", "font_weight", "font_size_px", "fill_color", "strokes", "shadow", "zone", "offset_x_px", "offset_y_px", "track_style_name"];
+const STROKE_KEYS = ["color", "width_px", "placement"];
+const SHADOW_KEYS = ["color", "opacity", "angle", "distance", "size", "blur"];
+const HEX_COLOR = /^#[0-9A-Fa-f]{6}$/;
+function plainObject(value, label, allowed) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(`${label} must be an object`);
+    const record = value;
+    const unknown = Object.keys(record).find((key) => !allowed.includes(key));
+    if (unknown)
+        fail(`${label} has an unknown field: ${unknown}`);
+    return record;
+}
+function boundedText(value, label, maxLength) {
+    if (typeof value !== "string" || !value.trim() || value.length > maxLength)
+        fail(`${label} must be a non-empty string of at most ${maxLength} characters`);
+    return value.trim();
+}
+function hexColor(value, label) {
+    if (typeof value !== "string" || !HEX_COLOR.test(value))
+        fail(`${label} must be a hex colour in the form #RRGGBB`);
+    return value.toUpperCase();
+}
+function rangedNumber(value, label, range, integer = false) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        fail(`${label} must be a finite number`);
+    if (integer && !Number.isInteger(value))
+        fail(`${label} must be an integer`);
+    if (value < range.min || value > range.max)
+        fail(`${label} must be between ${range.min} and ${range.max}`);
+    return value;
+}
+export function validateCustomCaptionStyle(value) {
+    const raw = plainObject(value, "custom_style", CUSTOM_STYLE_KEYS);
+    if (!Object.keys(raw).length)
+        fail("custom_style must set at least one field");
+    const limits = CUSTOM_CAPTION_STYLE_LIMITS;
+    const style = {};
+    if (raw.font_family !== undefined)
+        style.font_family = boundedText(raw.font_family, "custom_style.font_family", limits.font_family_max_length);
+    if (raw.font_weight !== undefined)
+        style.font_weight = boundedText(raw.font_weight, "custom_style.font_weight", limits.font_weight_max_length);
+    if (raw.font_size_px !== undefined)
+        style.font_size_px = rangedNumber(raw.font_size_px, "custom_style.font_size_px", limits.font_size_px, true);
+    if (raw.fill_color !== undefined)
+        style.fill_color = hexColor(raw.fill_color, "custom_style.fill_color");
+    if (raw.strokes !== undefined) {
+        if (!Array.isArray(raw.strokes) || raw.strokes.length > MAX_CAPTION_STROKES)
+            fail(`custom_style.strokes must be an array of at most ${MAX_CAPTION_STROKES} strokes`);
+        style.strokes = raw.strokes.map((item, index) => {
+            const label = `custom_style.strokes[${index}]`;
+            const stroke = plainObject(item, label, STROKE_KEYS);
+            const placement = stroke.placement === undefined ? "outer" : stroke.placement;
+            if (typeof placement !== "string" || !CAPTION_STROKE_PLACEMENTS.includes(placement))
+                fail(`${label}.placement must be one of: ${CAPTION_STROKE_PLACEMENTS.join(", ")}`);
+            return {
+                color: hexColor(stroke.color, `${label}.color`),
+                width_px: rangedNumber(stroke.width_px, `${label}.width_px`, limits.stroke_width_px),
+                placement: placement,
+            };
+        });
+    }
+    if (raw.shadow !== undefined) {
+        const shadow = plainObject(raw.shadow, "custom_style.shadow", SHADOW_KEYS);
+        const numberOr = (key) => shadow[key] === undefined ? CAPTION_SHADOW_DEFAULTS[key] : rangedNumber(shadow[key], `custom_style.shadow.${key}`, limits.shadow[key]);
+        style.shadow = {
+            color: shadow.color === undefined ? CAPTION_SHADOW_DEFAULTS.color : hexColor(shadow.color, "custom_style.shadow.color"),
+            opacity: numberOr("opacity"),
+            angle: numberOr("angle"),
+            distance: numberOr("distance"),
+            size: numberOr("size"),
+            blur: numberOr("blur"),
+        };
+    }
+    if (raw.zone !== undefined) {
+        if (typeof raw.zone !== "string" || !CAPTION_ZONES.includes(raw.zone))
+            fail(`custom_style.zone must be one of: ${CAPTION_ZONES.join(", ")}`);
+        style.zone = raw.zone;
+    }
+    if (raw.offset_x_px !== undefined)
+        style.offset_x_px = rangedNumber(raw.offset_x_px, "custom_style.offset_x_px", limits.offset_px, true);
+    if (raw.offset_y_px !== undefined)
+        style.offset_y_px = rangedNumber(raw.offset_y_px, "custom_style.offset_y_px", limits.offset_px, true);
+    if (raw.track_style_name !== undefined)
+        style.track_style_name = boundedText(raw.track_style_name, "custom_style.track_style_name", limits.track_style_name_max_length);
+    return style;
+}
+const ordinal = (index) => ["first", "second", "third"][index] ?? `#${index + 1}`;
+const zoneLabel = (zone) => zone.replace("_", "-");
+/** Warnings about a custom style that Premiere will accept but that may not render as intended. */
+export function customCaptionStyleWarnings(style) {
+    const warnings = [];
+    const outer = (style.strokes ?? []).filter((stroke) => stroke.placement === "outer");
+    for (let index = 1; index < outer.length; index += 1) {
+        if (outer[index].width_px <= outer[index - 1].width_px)
+            warnings.push(`outer stroke ${index + 1} (${outer[index].width_px} px) is not wider than outer stroke ${index} (${outer[index - 1].width_px} px), so it may be hidden behind it; layered outer strokes need increasing widths`);
+    }
+    if (style.shadow && style.shadow.opacity === 0)
+        warnings.push("shadow opacity is 0, so the shadow will not be visible");
+    if (style.strokes?.some((stroke) => stroke.width_px === 0))
+        warnings.push("a stroke with width 0 will not be visible");
+    return warnings;
+}
+const TRACK_STYLE_SELECT_STEPS = [
+    "Select one caption on the caption track in the timeline. One caption is enough: a Track Style applies to every caption on the track, so no multi-select is needed.",
+    "Open the Properties panel (Window > Properties). If your Premiere version has no Properties panel, use Window > Essential Graphics > Edit, which shows the same caption sections.",
+];
+function trackStyleSaveSteps(name) {
+    return [
+        `Track Style: open the Track Style dropdown in the Properties panel, choose "+ Create style", and name it "${name}". The style now applies to the whole caption track.`,
+        "Scrub through the track and confirm that the other captions show the new style.",
+        `Reuse: select a caption on the caption track in another sequence and pick "${name}" from the Track Style dropdown.`,
+        `The style is a project item in the Project panel. Move "${name}" into a shared bin (for example "Caption Styles") so other sequences and projects can reuse it.`,
+        "Verify the rendered look with export_frame or export_sequence_review_frames.",
+    ];
+}
+const numbered = (steps) => steps.map((step, index) => `${index + 1}. ${step}`);
+/** Premiere 2024+ Properties-panel / Track Style steps for a custom caption style. */
+export function buildCustomCaptionStyleSteps(style, preset) {
+    const fallback = preset ? describeCaptionStyle(preset) : undefined;
+    const steps = [...TRACK_STYLE_SELECT_STEPS];
+    const text = [];
+    const family = style.font_family ?? fallback?.font_family_suggestion;
+    const weight = style.font_weight ?? fallback?.font_weight;
+    if (family)
+        text.push(`font family "${family}"`);
+    if (weight)
+        text.push(`font weight/style "${weight}"`);
+    if (style.font_size_px !== undefined)
+        text.push(`font size ${style.font_size_px}`);
+    else if (fallback)
+        text.push(`font size about ${fallback.font_size_percent_of_height}% of the frame height`);
+    if (text.length)
+        steps.push(`Text: set ${text.join(", ")}.`);
+    if (style.fill_color)
+        steps.push(`Appearance > Fill: turn Fill on and set the colour to ${style.fill_color}.`);
+    if (style.strokes) {
+        if (!style.strokes.length)
+            steps.push("Appearance > Stroke: turn Stroke off.");
+        style.strokes.forEach((stroke, index) => {
+            const values = `colour ${stroke.color}, width ${stroke.width_px}, ${stroke.placement} stroke`;
+            steps.push(index === 0
+                ? `Appearance > Stroke: turn Stroke on and set the ${ordinal(index)} stroke to ${values}.`
+                : `Appearance > Stroke: press + next to Stroke to add stroke ${index + 1}, then set it to ${values}.`);
+        });
+    }
+    else if (fallback) {
+        steps.push(`Appearance > Stroke: ${fallback.stroke ? "turn Stroke on" : "leave Stroke off"} (preset ${fallback.preset}).`);
+    }
+    if (style.shadow) {
+        const shadow = style.shadow;
+        steps.push(`Appearance > Shadow: turn Shadow on and set colour ${shadow.color}, Opacity ${shadow.opacity}%, Angle ${shadow.angle}°, Distance ${shadow.distance}, Size ${shadow.size}, Blur ${shadow.blur}.`);
+    }
+    if (style.zone)
+        steps.push(`Align and Transform: choose the ${zoneLabel(style.zone)} cell in the caption region (zone) grid.`);
+    else if (fallback)
+        steps.push(`Align and Transform: place the caption centre near x=${fallback.position.x * 100}%, y=${fallback.position.y * 100}% of the frame (preset ${fallback.preset}).`);
+    if (style.offset_x_px !== undefined || style.offset_y_px !== undefined) {
+        steps.push(`Align and Transform: set the position offset to X ${style.offset_x_px ?? 0} and Y ${style.offset_y_px ?? 0} (pixels relative to the chosen zone; negative Y moves the caption up).`);
+    }
+    steps.push(...trackStyleSaveSteps(style.track_style_name ?? DEFAULT_TRACK_STYLE_NAME));
+    return numbered(steps);
+}
+/** Premiere 2024+ Properties-panel / Track Style steps for a built-in preset. */
+export function buildPresetCaptionStyleSteps(style) {
+    const steps = [
+        ...TRACK_STYLE_SELECT_STEPS,
+        `Text: set font family "${style.font_family_suggestion}", font weight ${style.font_weight}, and a font size of about ${style.font_size_percent_of_height}% of the frame height.`,
+        `Appearance > Stroke: ${style.stroke ? "turn Stroke on (press + next to Stroke for a second, wider outer stroke if you want a layered outline)" : "leave Stroke off"}.`,
+        `Appearance > Background: ${style.background ? "turn Background on and lower its opacity so the video stays visible" : "leave Background off"}.`,
+        `Align and Transform: centre-align the text and place the caption centre near x=${style.position.x * 100}%, y=${style.position.y * 100}% of the frame (normalized, centre-anchored).`,
+        ...(style.word_highlight ? ["Word highlight: enable word highlighting for a karaoke-style progressive reveal where your Premiere version offers it."] : []),
+        ...(style.uppercase_recommended ? ["Text: uppercase is recommended for this preset (use the All Caps option or the build_caption_artifact uppercase flag)."] : []),
+        ...trackStyleSaveSteps(`${style.preset} captions`),
+    ];
+    return numbered(steps);
+}
+export const CAPTION_TRACK_STYLE_GUIDANCE = {
+    scope: "A Track Style applies to every caption on the caption track. Style one caption, save it with Track Style > + Create style, and the whole track updates; no multi-select is needed.",
+    reusable: "A saved Track Style can be applied to the caption track of any other sequence in the project from the Track Style dropdown.",
+    project_item: "Each Track Style is stored as a project item in the Project panel; keep it in a shared bin so it can be found and reused.",
+    limitations: [
+        "Premiere Pro exposes no documented ExtendScript, QE DOM, or UXP API that creates, edits, or applies caption styles, so these steps must be performed in the Premiere UI.",
+        "These steps target Premiere Pro 2024 and later. Earlier versions lack the Track Style workflow described here and were not checked; panel labels can also differ between versions and UI languages.",
+        "Verify the rendered result with export_frame or export_sequence_review_frames; this tool cannot read the applied style back.",
+    ],
+};
+export function captionSafeZoneRecommendation() {
+    return safeZoneRecommendation();
+}
 const toMs = (seconds) => Math.round(seconds * 1000);
 const msToSeconds = (ms) => Number((ms / 1000).toFixed(3));
 function pad(value, width) {