premiere-pro-mcp 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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
@@ -25,6 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - `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

package/README.md

@@ -129,13 +129,13 @@ The current source exposes 434 core tools for supported workflow steps spanning
 
 <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
@@ -253,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:
@@ -261,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
@@ -274,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.`
 
@@ -580,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.
 
@@ -622,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

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.23.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.23.0"/>
-    <Extension Id="com.mcp.aftereffects.bridge.headless" Version="1.23.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.23.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.23.0"/>
-    <Extension Id="com.mcp.premiere.bridge.headless" Version="1.23.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.23.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/updater.cjs

@@ -7,7 +7,7 @@
 })(this, function () {
   "use strict";
 
-  var CURRENT_VERSION = "1.23.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) {

package/dist/bridge/script-builder.js

@@ -118,6 +118,33 @@ function __isTrackLocked(track) {
   return false;
 }
 
+// Seconds used to put marks back. Exact tick-boundary seconds can floor one
+// media frame early on 26.5.2; write a quarter grid past the boundary.
+function __restoreSecondsFromTicks(ticks, gridTicks) {
+  var grid = parseFloat(gridTicks);
+  if (!isFinite(grid) || !(grid > 0)) grid = TICKS_PER_SECOND / 24;
+  return (parseFloat(ticks) + grid / 4) / TICKS_PER_SECOND;
+}
+
+function __restoreGridFromItem(item, mediaType) {
+  if (mediaType === 2) return TICKS_PER_SECOND / 48000;
+  try {
+    var fps = parseFloat(item.getFootageInterpretation().frameRate);
+    if (fps > 0) return TICKS_PER_SECOND / fps;
+  } catch (eGrid) {}
+  return TICKS_PER_SECOND / 24;
+}
+
+function __biasedDomMarks(marks, gridTicks) {
+  if (!marks) return marks;
+  return {
+    inTicks: marks.inTicks,
+    outTicks: marks.outTicks,
+    inSeconds: __restoreSecondsFromTicks(marks.inTicks, gridTicks),
+    outSeconds: __restoreSecondsFromTicks(marks.outTicks, gridTicks)
+  };
+}
+
 // Read the private source range before temporarily changing project-item marks.
 function __itemMarksForRestore(item, mediaType) {
   function domMarks() {
@@ -131,7 +158,7 @@ function __itemMarksForRestore(item, mediaType) {
   }
   var dom = domMarks(), xml = "";
   try { if (typeof item.getProjectMetadata === "function") xml = String(item.getProjectMetadata() || ""); } catch (metadataMarkError) { return null; }
-  if (!xml) return dom;
+  if (!xml) return __biasedDomMarks(dom, __restoreGridFromItem(item, mediaType));
   if (xml.length > 1000000) return null;
   function field(name, text) {
     var escaped = name.replace(/\\./g, "\\\\.");
@@ -192,7 +219,7 @@ function __itemMarksForRestore(item, mediaType) {
   }
   if (inBlock === null && outBlock === null) {
     if (xml.indexOf("Column.Intrinsic." + kind + "InPoint") >= 0 || xml.indexOf("Column.Intrinsic." + kind + "OutPoint") >= 0) return null;
-    return dom;
+    return __biasedDomMarks(dom, __restoreGridFromItem(item, mediaType));
   }
   var left = point(inBlock, kind === "Audio"), right = point(outBlock, kind === "Audio");
   // The private VideoOutPoint names the last frame (inclusive): a subclip made
@@ -200,7 +227,12 @@ function __itemMarksForRestore(item, mediaType) {
   if (right && kind !== "Audio") right.ticks += right.frameTicks;
   if (!left || !right || !isFinite(left.ticks) || !isFinite(right.ticks) || left.ticks < 0 || right.ticks > 9007199254740991 || right.ticks <= left.ticks || Math.abs(left.frameTicks - right.frameTicks) > 1) return null;
   var tolerance = Math.max(left.frameTicks, right.frameTicks);
-  if (dom && Math.abs(Number(dom.inTicks) - left.ticks) <= tolerance && Math.abs(Number(dom.outTicks) - right.ticks) <= tolerance) return dom;
+  // DOM already matches the private range. Still bias the write seconds: 26.5.2
+  // floors exact tick-boundary seconds one media frame early, which shrinks a
+  // normal clip after replace/unnest the same way it shrinks a soft subclip.
+  if (dom && Math.abs(Number(dom.inTicks) - left.ticks) <= tolerance && Math.abs(Number(dom.outTicks) - right.ticks) <= tolerance) {
+    return __biasedDomMarks(dom, tolerance);
+  }
   // Premiere floors a written mark to the media's frame (or sample) grid, so a
   // value exactly on the boundary can land one frame early (live 26.5.2: a
   // restored Out of 00:00:29:22 read back 00:00:29:21). Write a quarter frame
@@ -215,18 +247,43 @@ function __itemMarksForRestore(item, mediaType) {
 // empty first; overwrite never shifts neighbours but would replace them.
 // Returns { ok, attempted, marksRestored, error }. attempted=true means the
 // overwrite call ran (or threw), so the timeline may have changed.
+// Media/sample grid for a project-item mark write. Video uses footage fps;
+// audio uses 48 kHz when the host does not expose a rate. Fallback 24 fps is
+// smaller than one frame at 23.976–60 and still larger than float ulp.
+function __mediaGridTicks(item, mediaType) {
+  if (mediaType !== 2) {
+    try {
+      var fps = parseFloat(item.getFootageInterpretation().frameRate);
+      if (fps > 0) return TICKS_PER_SECOND / fps;
+    } catch (eInterp) {}
+    return TICKS_PER_SECOND / 24;
+  }
+  return TICKS_PER_SECOND / 48000;
+}
+
+function __biasedMarkSeconds(ticks, gridTicks) {
+  var grid = parseFloat(gridTicks);
+  if (!isFinite(grid) || !(grid > 0)) grid = TICKS_PER_SECOND / 24;
+  return (parseFloat(ticks) + grid / 4) / TICKS_PER_SECOND;
+}
+
 // Set a project item's In/Out marks, ordering the writes so the In never
 // passes the current Out, and report whether both read back within tolerance
-// ticks (default: exact).
+// ticks (default: exact). Write a quarter grid past the tick boundary: the
+// same 26.5.2 floor that shrinks restored soft-subclip marks also shortens
+// the temporary overwrite range (unnest/replace) when exact seconds are used.
 function __setItemMarks(item, wantIn, wantOut, mediaType, tolerance) {
   var tol = tolerance > __TICK_MATCH_TOL ? tolerance : __TICK_MATCH_TOL;
+  var grid = __mediaGridTicks(item, mediaType);
+  var inSeconds = __biasedMarkSeconds(wantIn, grid);
+  var outSeconds = __biasedMarkSeconds(wantOut, grid);
   var currentOut = parseFloat(item.getOutPoint(mediaType).ticks);
   if (parseFloat(wantIn) >= currentOut) {
-    item.setOutPoint(__ticksToSeconds(wantOut), mediaType);
-    item.setInPoint(__ticksToSeconds(wantIn), mediaType);
+    item.setOutPoint(outSeconds, mediaType);
+    item.setInPoint(inSeconds, mediaType);
   } else {
-    item.setInPoint(__ticksToSeconds(wantIn), mediaType);
-    item.setOutPoint(__ticksToSeconds(wantOut), mediaType);
+    item.setInPoint(inSeconds, mediaType);
+    item.setOutPoint(outSeconds, mediaType);
   }
   return Math.abs(parseFloat(item.getInPoint(mediaType).ticks) - parseFloat(wantIn)) <= tol &&
     Math.abs(parseFloat(item.getOutPoint(mediaType).ticks) - parseFloat(wantOut)) <= tol;

package/dist/platform-capabilities.d.ts

@@ -140,6 +140,7 @@ export declare function buildPlatformCapabilityReport(capabilities: CapabilityCo
                     cloudPublish: string;
                     contentCredentials: string;
                     renderAndReplace: string;
+                    captionTrackStyle: string;
                 };
             };
         };

package/dist/platform-capabilities.js

@@ -229,6 +229,7 @@ export function buildPlatformCapabilityReport(capabilities, platform = process.p
                         cloudPublish: "No documented Premiere automation API for publishing to cloud destinations.",
                         contentCredentials: "No documented Premiere automation API for configuring Content Credentials.",
                         renderAndReplace: "No documented Premiere ExtendScript or UXP Render and Replace API.",
+                        captionTrackStyle: "No documented Premiere ExtendScript, QE DOM, or UXP API creates, edits, or applies caption track styles; call get_caption_style_guidance for Properties-panel and Track Style steps to apply in the Premiere UI.",
                     },
                 },
             },

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

@@ -1,3 +1,4 @@
+import { type CaptionStylePreset } from "../ai/caption-authoring.js";
 export declare const MAX_INLINE_ARTIFACT_BYTES: number;
 /**
  * Resolves `output_path` to a writable location contained inside the approved
@@ -343,22 +344,178 @@ export declare function getCaptionAuthoringTools(): {
                     enum: ("podcast" | "clean" | "bold_pop" | "karaoke" | "lecture")[];
                     description: string;
                 };
+                custom_style: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly description: "Optional caption look to translate into concrete Premiere UI steps. Every field is optional; at least one is required. Values are documentation only and are never applied.";
+                    readonly properties: {
+                        readonly font_family: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 128;
+                            readonly description: "Font family name as shown in Premiere, e.g. Source Han Sans TW.";
+                        };
+                        readonly font_weight: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 64;
+                            readonly description: "Font weight or style name, e.g. Heavy or Bold.";
+                        };
+                        readonly font_size_px: {
+                            readonly type: "integer";
+                            readonly minimum: 8;
+                            readonly maximum: 400;
+                            readonly description: "Font size in Premiere's caption units (pixels).";
+                        };
+                        readonly fill_color: {
+                            readonly type: "string";
+                            readonly pattern: "^#[0-9A-Fa-f]{6}$";
+                            readonly description: "Text fill colour as #RRGGBB.";
+                        };
+                        readonly strokes: {
+                            readonly type: "array";
+                            readonly maxItems: 3;
+                            readonly description: "Up to three strokes in Premiere's Stroke list order; each stroke after the first is added with + next to Stroke. Layered outer strokes need increasing widths.";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly description: "One stroke.";
+                                readonly properties: {
+                                    readonly color: {
+                                        readonly type: "string";
+                                        readonly pattern: "^#[0-9A-Fa-f]{6}$";
+                                        readonly description: "Stroke colour as #RRGGBB.";
+                                    };
+                                    readonly width_px: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                        readonly maximum: 100;
+                                        readonly description: "Stroke width.";
+                                    };
+                                    readonly placement: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["outer", "inner", "center"];
+                                        readonly description: "Stroke placement (default outer).";
+                                    };
+                                };
+                                readonly required: readonly ["color", "width_px"];
+                            };
+                        };
+                        readonly shadow: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly description: "Drop shadow; omitted fields use the listed defaults.";
+                            readonly properties: {
+                                readonly color: {
+                                    readonly type: "string";
+                                    readonly pattern: "^#[0-9A-Fa-f]{6}$";
+                                    readonly description: "Shadow colour as #RRGGBB (default #000000).";
+                                };
+                                readonly opacity: {
+                                    type: string;
+                                    minimum: 0;
+                                    maximum: 100 | 200 | 360;
+                                    description: string;
+                                };
+                                readonly angle: {
+                                    type: string;
+                                    minimum: 0;
+                                    maximum: 100 | 200 | 360;
+                                    description: string;
+                                };
+                                readonly distance: {
+                                    type: string;
+                                    minimum: 0;
+                                    maximum: 100 | 200 | 360;
+                                    description: string;
+                                };
+                                readonly size: {
+                                    type: string;
+                                    minimum: 0;
+                                    maximum: 100 | 200 | 360;
+                                    description: string;
+                                };
+                                readonly blur: {
+                                    type: string;
+                                    minimum: 0;
+                                    maximum: 100 | 200 | 360;
+                                    description: string;
+                                };
+                            };
+                        };
+                        readonly zone: {
+                            readonly type: "string";
+                            readonly enum: readonly ["top_left", "top_center", "top_right", "middle_left", "middle_center", "middle_right", "bottom_left", "bottom_center", "bottom_right"];
+                            readonly description: "Caption region in Premiere's Align and Transform zone grid.";
+                        };
+                        readonly offset_x_px: {
+                            readonly type: "integer";
+                            readonly minimum: -2000;
+                            readonly maximum: 2000;
+                            readonly description: "Horizontal position offset from the zone in pixels.";
+                        };
+                        readonly offset_y_px: {
+                            readonly type: "integer";
+                            readonly minimum: -2000;
+                            readonly maximum: 2000;
+                            readonly description: "Vertical position offset from the zone in pixels; negative moves up.";
+                        };
+                        readonly track_style_name: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 80;
+                            readonly description: "Name for the saved Track Style (default Caption Track Style).";
+                        };
+                    };
+                };
             };
         };
-        handler: (args: {
-            preset?: string;
-        }) => Promise<{
+        handler: (args: Record<string, unknown>) => Promise<{
             success: boolean;
             data: {
-                style: import("../ai/caption-authoring.js").CaptionStyleDescriptor;
+                style: import("../ai/caption-authoring.js").CaptionStyleDescriptor | {
+                    custom_style: import("../ai/caption-authoring.js").CustomCaptionStyle;
+                    source: string;
+                    preset: CaptionStylePreset;
+                    font_family_suggestion: string;
+                    font_weight: string;
+                    font_size_percent_of_height: number;
+                    position: {
+                        x: number;
+                        y: number;
+                    };
+                    alignment: "center";
+                    stroke: boolean;
+                    background: boolean;
+                    word_highlight: boolean;
+                    uppercase_recommended: boolean;
+                    safe_zone_recommendation: Record<import("../ai/caption-authoring.js").SafeZonePlatform, {
+                        x: number;
+                        y: number;
+                    }>;
+                    note: string;
+                } | {
+                    custom_style: import("../ai/caption-authoring.js").CustomCaptionStyle;
+                    source: string;
+                    preset: null;
+                };
                 workflow: string[];
                 premiere_ui_steps: string[];
+                track_style: {
+                    name: string;
+                    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.")[];
+                warnings: string[];
+                applied: boolean;
                 mutation_refused: string;
                 safe_zones: Record<"x" | "tiktok" | "instagram_reels" | "youtube_shorts" | "instagram_feed" | "youtube" | "linkedin", {
                     x: number;
                     y: number;
                 }>;
-                routes: ("read_sequence_captions" | "transform_track_item_uxp" | "export_sequence_review_frames" | "create_caption_track" | "set_clip_position" | "inspect_caption_tracks_uxp")[];
+                routes: ("read_sequence_captions" | "transform_track_item_uxp" | "export_frame" | "export_sequence_review_frames" | "create_caption_track" | "set_clip_position" | "inspect_caption_tracks_uxp")[];
             };
             error?: undefined;
         } | {

package/dist/tools/caption-authoring.js

@@ -1,10 +1,63 @@
 import { createHash } from "node:crypto";
 import { existsSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { buildCaptionArtifact, CAPTION_AUTHORING_ROUTES, CAPTION_STYLE_PRESETS, checkCaptionSafeZone, describeCaptionStyle, MAX_EMPHASIS_WORDS, MAX_FILLER_TOKENS, MAX_FRAME_DIMENSION, MAX_SAFE_ZONE_ELEMENTS, MIN_FRAME_DIMENSION, SAFE_ZONE_ELEMENT_KINDS, SAFE_ZONE_PLATFORMS, SAFE_ZONE_ROUTES, } from "../ai/caption-authoring.js";
+import { buildCaptionArtifact, CAPTION_AUTHORING_ROUTES, CAPTION_SHADOW_DEFAULTS, CAPTION_STROKE_PLACEMENTS, CAPTION_STYLE_PRESETS, CAPTION_TRACK_STYLE_GUIDANCE, CAPTION_ZONES, buildCustomCaptionStyleSteps, buildPresetCaptionStyleSteps, captionSafeZoneRecommendation, checkCaptionSafeZone, CUSTOM_CAPTION_STYLE_LIMITS, customCaptionStyleWarnings, DEFAULT_TRACK_STYLE_NAME, describeCaptionStyle, MAX_CAPTION_STROKES, validateCustomCaptionStyle, MAX_EMPHASIS_WORDS, MAX_FILLER_TOKENS, MAX_FRAME_DIMENSION, MAX_SAFE_ZONE_ELEMENTS, MIN_FRAME_DIMENSION, SAFE_ZONE_ELEMENT_KINDS, SAFE_ZONE_PLATFORMS, SAFE_ZONE_ROUTES, } from "../ai/caption-authoring.js";
 import { WORD_TIMELINE_PARAMETER } from "../ai/word-timeline.js";
 export const MAX_INLINE_ARTIFACT_BYTES = 512 * 1024;
 const MAX_PATH_LENGTH = 4096;
+const CAPTION_STYLE_VERIFY_ROUTES = ["export_frame", "export_sequence_review_frames"];
+const HEX_COLOR_PATTERN = "^#[0-9A-Fa-f]{6}$";
+const LIMITS = CUSTOM_CAPTION_STYLE_LIMITS;
+const shadowNumber = (key, label) => ({
+    type: "number",
+    minimum: LIMITS.shadow[key].min,
+    maximum: LIMITS.shadow[key].max,
+    description: `${label} (default ${CAPTION_SHADOW_DEFAULTS[key]}).`,
+});
+const CUSTOM_STYLE_PARAMETER = {
+    type: "object",
+    additionalProperties: false,
+    description: "Optional caption look to translate into concrete Premiere UI steps. Every field is optional; at least one is required. Values are documentation only and are never applied.",
+    properties: {
+        font_family: { type: "string", minLength: 1, maxLength: LIMITS.font_family_max_length, description: "Font family name as shown in Premiere, e.g. Source Han Sans TW." },
+        font_weight: { type: "string", minLength: 1, maxLength: LIMITS.font_weight_max_length, description: "Font weight or style name, e.g. Heavy or Bold." },
+        font_size_px: { type: "integer", minimum: LIMITS.font_size_px.min, maximum: LIMITS.font_size_px.max, description: "Font size in Premiere's caption units (pixels)." },
+        fill_color: { type: "string", pattern: HEX_COLOR_PATTERN, description: "Text fill colour as #RRGGBB." },
+        strokes: {
+            type: "array",
+            maxItems: MAX_CAPTION_STROKES,
+            description: "Up to three strokes in Premiere's Stroke list order; each stroke after the first is added with + next to Stroke. Layered outer strokes need increasing widths.",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                description: "One stroke.",
+                properties: {
+                    color: { type: "string", pattern: HEX_COLOR_PATTERN, description: "Stroke colour as #RRGGBB." },
+                    width_px: { type: "number", minimum: LIMITS.stroke_width_px.min, maximum: LIMITS.stroke_width_px.max, description: "Stroke width." },
+                    placement: { type: "string", enum: [...CAPTION_STROKE_PLACEMENTS], description: "Stroke placement (default outer)." },
+                },
+                required: ["color", "width_px"],
+            },
+        },
+        shadow: {
+            type: "object",
+            additionalProperties: false,
+            description: "Drop shadow; omitted fields use the listed defaults.",
+            properties: {
+                color: { type: "string", pattern: HEX_COLOR_PATTERN, description: `Shadow colour as #RRGGBB (default ${CAPTION_SHADOW_DEFAULTS.color}).` },
+                opacity: shadowNumber("opacity", "Shadow opacity percent"),
+                angle: shadowNumber("angle", "Shadow angle in degrees"),
+                distance: shadowNumber("distance", "Shadow distance"),
+                size: shadowNumber("size", "Shadow size"),
+                blur: shadowNumber("blur", "Shadow blur"),
+            },
+        },
+        zone: { type: "string", enum: [...CAPTION_ZONES], description: "Caption region in Premiere's Align and Transform zone grid." },
+        offset_x_px: { type: "integer", minimum: LIMITS.offset_px.min, maximum: LIMITS.offset_px.max, description: "Horizontal position offset from the zone in pixels." },
+        offset_y_px: { type: "integer", minimum: LIMITS.offset_px.min, maximum: LIMITS.offset_px.max, description: "Vertical position offset from the zone in pixels; negative moves up." },
+        track_style_name: { type: "string", minLength: 1, maxLength: LIMITS.track_style_name_max_length, description: `Name for the saved Track Style (default ${DEFAULT_TRACK_STYLE_NAME}).` },
+    },
+};
 function absolutePath(value, label) {
     if (typeof value !== "string" || !value.trim() || value.length > MAX_PATH_LENGTH)
         throw new Error(`${label} must be a non-empty string of at most ${MAX_PATH_LENGTH} characters`);
@@ -195,22 +248,30 @@ export function getCaptionAuthoringTools() {
             },
         },
         get_caption_style_guidance: {
-            description: "Returns caption style presets (clean, bold_pop, karaoke, podcast, lecture) with font, position, and styling recommendations, plus Premiere UI steps for applying styles. Read-only guidance; NEVER modifies caption tracks. Use build_caption_artifact for SRT/VTT timing, then import via create_caption_track and apply styles manually in Premiere's UI.",
+            description: "Read-only caption style guidance: a preset (clean, bold_pop, karaoke, podcast, lecture) and/or a custom_style spec (font, size, fill, up to 3 strokes, shadow, zone, offsets) turned into Premiere 2024+ Properties-panel steps that save a reusable whole-track Track Style. NEVER modifies caption tracks; Premiere has no caption style API.",
             parameters: {
                 type: "object",
                 additionalProperties: false,
                 required: [],
                 properties: {
-                    preset: { type: "string", enum: [...CAPTION_STYLE_PRESETS], description: "Style preset to describe (default clean)." },
+                    preset: { type: "string", enum: [...CAPTION_STYLE_PRESETS], description: "Style preset to describe (default clean when custom_style is omitted)." },
+                    custom_style: CUSTOM_STYLE_PARAMETER,
                 },
             },
             handler: async (args) => {
                 try {
-                    const preset = (args.preset ?? "clean");
-                    if (!CAPTION_STYLE_PRESETS.includes(preset)) {
+                    if (!args || typeof args !== "object" || Array.isArray(args))
+                        throw new Error("arguments must be an object");
+                    if (args.preset !== undefined && (typeof args.preset !== "string" || !CAPTION_STYLE_PRESETS.includes(args.preset))) {
                         throw new Error(`preset must be one of: ${CAPTION_STYLE_PRESETS.join(", ")}`);
                     }
-                    const style = describeCaptionStyle(preset);
+                    const custom = args.custom_style === undefined ? undefined : validateCustomCaptionStyle(args.custom_style);
+                    const preset = (args.preset ?? (custom ? undefined : "clean"));
+                    const presetStyle = preset ? describeCaptionStyle(preset) : undefined;
+                    const style = custom
+                        ? { ...(presetStyle ?? { preset: null }), custom_style: custom, source: presetStyle ? "preset_with_custom_style" : "custom_style" }
+                        : presetStyle;
+                    const premiereUiSteps = custom ? buildCustomCaptionStyleSteps(custom, preset) : buildPresetCaptionStyleSteps(presetStyle);
                     return {
                         success: true,
                         data: {
@@ -220,29 +281,21 @@ export function getCaptionAuthoringTools() {
                                 "Step 2: Import the caption file into Premiere project",
                                 "Step 3: Call create_caption_track with action:import and the imported item_id",
                                 "Step 4: Inspect the track with read_sequence_captions or inspect_caption_tracks_uxp",
-                                "Step 5: Apply font/color/position/background styles manually in Premiere UI",
+                                "Step 5: Style one caption in Premiere's Properties panel and save it as a Track Style (premiere_ui_steps); it applies to the whole caption track",
                             ],
-                            premiere_ui_steps: [
-                                `1. Select the caption track in the timeline`,
-                                `2. Open Essential Graphics panel (Window > Essential Graphics)`,
-                                `3. In the Edit tab, adjust Text properties:`,
-                                `   - Font Family: ${style.font_family_suggestion}`,
-                                `   - Font Weight: ${style.font_weight}`,
-                                `   - Font Size: approximately ${style.font_size_percent_of_height}% of frame height`,
-                                `   - Position: x=${style.position.x * 100}%, y=${style.position.y * 100}% (normalized, center-anchored)`,
-                                `   - Alignment: ${style.alignment}`,
-                                `   - Stroke: ${style.stroke ? "enabled" : "disabled"}`,
-                                `   - Background: ${style.background ? "enabled with opacity" : "disabled"}`,
-                                ...(style.word_highlight
-                                    ? ["   - Word Highlight: enabled for karaoke-style progressive reveal"]
-                                    : []),
-                                ...(style.uppercase_recommended
-                                    ? ["   - Transform: uppercase recommended for this preset"]
-                                    : []),
-                            ],
-                            mutation_refused: "This tool provides guidance only. MCP for Adobe Premiere Pro does not expose a CaptionTrack style mutation API because Premiere does not expose one through documented ExtendScript, QE DOM, or UXP surfaces. Apply caption styles manually in the Essential Graphics panel.",
-                            safe_zones: style.safe_zone_recommendation,
-                            routes: [...CAPTION_AUTHORING_ROUTES, ...SAFE_ZONE_ROUTES],
+                            premiere_ui_steps: premiereUiSteps,
+                            track_style: {
+                                name: custom?.track_style_name ?? (custom ? DEFAULT_TRACK_STYLE_NAME : `${preset} captions`),
+                                scope: CAPTION_TRACK_STYLE_GUIDANCE.scope,
+                                reusable: CAPTION_TRACK_STYLE_GUIDANCE.reusable,
+                                project_item: CAPTION_TRACK_STYLE_GUIDANCE.project_item,
+                            },
+                            limitations: [...CAPTION_TRACK_STYLE_GUIDANCE.limitations],
+                            warnings: custom ? customCaptionStyleWarnings(custom) : [],
+                            applied: false,
+                            mutation_refused: "This tool provides guidance only. MCP for Adobe Premiere Pro does not expose a CaptionTrack style mutation API because Premiere does not expose one through documented ExtendScript, QE DOM, or UXP surfaces. Apply caption styles manually in Premiere's Properties panel (or Essential Graphics) and save them as a Track Style.",
+                            safe_zones: presetStyle?.safe_zone_recommendation ?? captionSafeZoneRecommendation(),
+                            routes: [...CAPTION_AUTHORING_ROUTES, ...SAFE_ZONE_ROUTES, ...CAPTION_STYLE_VERIFY_ROUTES],
                         },
                     };
                 }

package/dist/tools/health.d.ts

@@ -337,6 +337,7 @@ export declare function getHealthTools(bridgeOptions: BridgeOptions, capabilitie
                                 cloudPublish: string;
                                 contentCredentials: string;
                                 renderAndReplace: string;
+                                captionTrackStyle: string;
                             };
                         };
                     };

package/dist/tools/timeline.js

@@ -1654,13 +1654,15 @@ export function getTimelineTools(bridgeOptions, dependencies = {}) {
             if (Math.abs(parseFloat(cand.start.ticks) - oldStart) > __TICK_MATCH_TOL) continue;
             replacement = cand;
           }
-          // The item's Out mark can land up to one media frame early, and
-          // overwriteClip can place a clip a frame short (live 26.5.2). Extend
-          // the end into the empty remainder of the original span.
+          // The item's Out mark can land up to one media frame off the 25 fps
+          // span (early without write bias, or one media frame long when the
+          // closer media frame is past the tick boundary). Pull the placed end
+          // back onto the original span when the drift is within one media
+          // frame plus one sequence frame.
           var endCorrected = false;
           if (replacement) {
             var endGap = oldEnd - parseFloat(replacement.end.ticks);
-            if (endGap > __TICK_MATCH_TOL && endGap <= markTolerance + __sequenceFrameTicks(seq)) {
+            if (Math.abs(endGap) > __TICK_MATCH_TOL && Math.abs(endGap) <= markTolerance + __sequenceFrameTicks(seq)) {
               var endTime = new Time();
               endTime.ticks = String(oldEnd);
               try { replacement.end = endTime; endCorrected = true; } catch (eEnd) {}

package/docs/supported-actions.md

@@ -165,7 +165,7 @@ operation” when the tool has no enum-based mode.
 | `get_bin_contents` | Default profile | Single operation | Get detailed contents of a specific bin (folder) including all nested items, media paths, offline status, color labels, and metadata. Searches by bin name or node ID. |
 | `get_bridge_telemetry` | Default profile | Single operation | Inspect privacy-preserving aggregate bridge health: pending command/response counts, busy operations, queue age, and CEP heartbeat state without returning project or personal data. |
 | `get_capabilities` | Default profile | Single operation | Discover Premiere operations and report backend coverage, authority, and verification requirements. Use tool_query with task keywords (for example transcript, captions, or review frames) for ranked, bounded matches available in this session. Use tool_names for exact lookups or tool_offset/tool_limit for paging. Discovery never grants authority or proves a live host is ready. |
-| `get_caption_style_guidance` | Default profile | `preset`: `clean`, `bold_pop`, `karaoke`, `podcast`, `lecture` | Returns caption style presets (clean, bold_pop, karaoke, podcast, lecture) with font, position, and styling recommendations, plus Premiere UI steps for applying styles. Read-only guidance; NEVER modifies caption tracks. Use build_caption_artifact for SRT/VTT timing, then import via create_caption_track and apply styles manually in Premiere's UI. |
+| `get_caption_style_guidance` | Default profile | `preset`: `clean`, `bold_pop`, `karaoke`, `podcast`, `lecture` | Read-only caption style guidance: a preset (clean, bold_pop, karaoke, podcast, lecture) and/or a custom_style spec (font, size, fill, up to 3 strokes, shadow, zone, offsets) turned into Premiere 2024+ Properties-panel steps that save a reusable whole-track Track Style. NEVER modifies caption tracks; Premiere has no caption style API. |
 | `get_clip_adjustment_layer` | Default profile | Single operation | Check if a clip is an adjustment layer |
 | `get_clip_at_playhead` | Default profile | `track_type`: `video`, `audio`, `both` | Get all clips at the current playhead position across all tracks. |
 | `get_clip_at_position` | Default profile | `track_type`: `video`, `audio` | Get the clip at a specific time position on a track |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "premiere-pro-mcp",
   "mcpName": "io.github.leancoderkavy/premiere-pro",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "MCP server for Adobe Premiere Pro with 434 core AI video editing tools, a guarded After Effects MOGRT studio, and a capability-aware UXP bridge for supported Premiere workflows.",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",

package/public-product-manifest.json

@@ -10,7 +10,7 @@
     "name": "MCP for Adobe Premiere Pro",
     "mcpName": "io.github.leancoderkavy/premiere-pro",
     "npmPackage": "premiere-pro-mcp",
-    "version": "1.23.0",
+    "version": "1.24.0",
     "repository": "https://github.com/leancoderkavy/premiere-pro-mcp",
     "homepage": "https://premiere-pro-mcp.com/",
     "license": "MIT",

package/uxp-plugin/manifest.json

@@ -2,7 +2,7 @@
   "manifestVersion": 5,
   "id": "com.ppmcp.premiere.uxp",
   "name": "MCP for Adobe Premiere Pro",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "main": "index.html",
   "host": { "app": "premierepro", "minVersion": "25.6.0" },
   "entrypoints": [