jhonny-editor/code/docs/uxp-stable-workflows.md

Stable Premiere UXP workflow expansion

• Research refresh: 2026-08-15
• Research method: Tavily discovery restricted to official Adobe sources, then checked against the installed stable declaration package
• Declaration baseline: @adobe/premierepro@26.3.0
• Runtime policy: method probes from the connected host are authoritative
• Evidence: automated contract tests complete; live Premiere verification not run

Why these workflows

The existing MCP catalog already covers broad CEP and QE automation. This expansion uses Adobe's documented stable UXP surface where it can improve transaction discipline, selection performance, readback evidence, and filesystem authority. It does not remove or silently replace the production CEP path. A failed UXP mutation is returned to the caller and is never replayed automatically through CEP.

The public MCP surface adds consolidated tools. Each maps to smaller protocol commands so capabilities.get can report the exact methods available in the running Premiere build.

Improvement	Public MCP tool	UXP commands	Host evidence
Native effects pipeline	manage_clip_effects_uxp	effects.catalog, effects.chain.get, effects.chain.add, effects.chain.remove	Effect catalog allowlist; component-chain count and component readback after an action transaction
Bounded effect-parameter catalog	inspect_effect_parameter_catalog_uxp	parameters.catalog.inspect	One active audio/video coordinate resolves at most 64 component-parameter index/name/animation descriptors twice; no raw Color, PointF, or other parameter values are read
Native track-item identity	inspect_track_item_identity_uxp	trackItem.identity.inspect	One bounded audio/video coordinate resolves documented match name, item/media type, track index, and selected state only after the active sequence identity is re-read
Native TickTime arithmetic	calculate_tick_time_uxp	time.tickArithmetic.inspect	Canonical caller-supplied ticks use documented native add/subtract/multiply/divide and return only ticks/seconds; no frame alignment, timecode, sequence/project access, rendering, playback, or licensed-host claim
Guarded timeline source label	manage_timeline_source_label_uxp	timeline.sourceLabel.inspect, timeline.sourceLabel.update	A bounded active audio/video coordinate resolves its source ClipProjectItem; update requires the complete snapshot, confirmation, operation ID, per-source serialization, one transaction, and source-label readback. The label is project-global rather than timeline-instance state.
Guarded sequence preview frame	manage_sequence_preview_frame_uxp	sequence.previewFrame.inspect, sequence.previewFrame.update	One explicit sequence GUID returns its documented native preview-frame width/height twice; update requires that full snapshot, confirmation, and operation ID, serializes bridge updates by project/sequence, commits one settings transaction, then reads the same sequence back. It does not set video dimensions or prove preview rendering.
Bounded source-media provenance	inspect_source_media_provenance_uxp	source.provenance.inspect	One exact media-backed Project-item ID plus at least one explicit path-disclosure flag returns only the selected documented media-file and/or originating-project path. It resolves the item through a capped tree twice and rejects a changed project, target, or selected path; it never returns a project tree, reads a file, validates a path, establishes source lineage or rights, or proves licensed-host behavior.
Bounded source-proxy readiness	inspect_source_proxy_uxp	source.proxy.inspect	One exact media-backed Project-item ID returns documented proxy availability, attachment, offline, and path-change capability state twice. A native proxy path is read only with explicit opt-in and only when a proxy is attached; it never accesses the filesystem, attaches/relinks proxy media, proves proxy compatibility, or proves licensed-host behavior.
Selection compound batch	batch_selected_clips_uxp	selection.inspect, effects.selection.add, effects.selection.remove	Preflight all selected items, then commit one action group and read every chain count back
Deterministic timeline selection	manage_timeline_selection_uxp	selection.fingerprints.inspect, selection.targets.inspect, selection.update	Current or coordinate-resolved clips return active-sequence GUID and project-item/time fingerprints; mutations check them before one native selection update and exact readback
Scene-edit detection	detect_scene_edits_uxp	sceneEdit.detect	createMarkers requires selected project-item marker-GUID growth; cut/subclip modes return only Adobe's host result and selected-item count
Proxy and ingest controller	manage_proxy_ingest_uxp	proxy.inspect, proxy.attach, ingest.get, ingest.configure	Proxy path/attachment readback; ingest state readback after transaction
Offline relink repair	relink_offline_media_uxp	media.relink	Expected old path, offline default, capability check, then media-path and online-state readback
Transactional metadata	manage_metadata_uxp	metadata.get, metadata.update	Project metadata and XMP are committed together and read back; each payload is size bounded
Project-panel metadata inspection	inspect_project_panel_metadata_uxp	metadata.columns.get, metadata.projectPanel.get	Read one native item-column or active-project panel-metadata string, bounded to 350,000 characters and a 900,000-byte serialized result; no schema or metadata writes are exposed
Guarded Project-panel metadata replacement	manage_project_panel_metadata_uxp	metadata.projectPanel.get, metadata.projectPanel.update	Require the exact inspected project GUID and XML, confirmation, operation ID, local per-project serialization, then exact native readback; the direct setter is non-undoable and no atomic compare-and-set is claimed
Guarded Project metadata schema field creation	create_project_metadata_field_uxp	metadata.projectSchema.inspect, metadata.projectSchema.create	Require the exact inspected project GUID and bounded panel XML, typed name/label, confirmation, operation ID, and shared per-project serialization; native acceptance and panel-XML change are observable but Adobe exposes no atomic compare-and-set or field-level getter, so creation is always committed_unverified
Guarded app preferences	manage_app_preferences_uxp	preferences.inspect, preferences.set	Inspect only Adobe's three named application preferences; direct string writes require stale value, persistence, confirmation, operation ID, per-key serialization, and exact native-string readback; no transaction or Undo claim
Installed MOGRT-directory inspection	inspect_installed_mogrt_directory_uxp	graphics.mogrtPath.inspect	Return only documented installed-directory availability by default. A caller must explicitly request the bounded native path; the bridge does not enumerate it, read templates, or import MOGRTs.
Bounded Object Mask audit	audit_object_masks_uxp	objectMask.audit	Up to 64 exact sequences (or an entire project under that cap) are re-resolved with the active-project identity and every yes/no Object Mask result double-read before a response is returned.
Color and conformance	manage_color_conformance_uxp	color.preflight, footage.conform	Project graphics-white values, embedded/input LUT IDs, and requested footage fields read back
Source Monitor audition	audition_source_monitor_uxp	sourceMonitor.state, sourceMonitor.open, sourceMonitor.position.set, sourceMonitor.play, sourceMonitor.close	Project-item and position readback where Adobe exposes it; file open/play rely on explicit host returns
Productions and storage	preflight_production_storage_uxp	storage.preflight, scratch.configure	Project/Production scratch snapshots and project action-transaction result
Least-privilege workspace	get_uxp_workspace_access	workspace.status	Redacted persistent capability state; native path and token never cross the bridge

Performance and transaction design

• Selection batches use Sequence.getSelection() and TrackItemSelection instead of traversing the project tree. Classification reads only each selected item's reported track and caches repeated track lookups. Batches are capped at 64 clips and reject mixed or unclassified media types before creating any action.
• Selection management resolves every requested video/audio clip before changing host state, caps the resulting set at 64 clips, and rejects changed sequence, project-item, or timeline-time fingerprints. It accepts both the Promise form of Sequence.setSelection() in 25.6-26.2 and the synchronous boolean form in 26.3.
• Effect factories run during preflight. All component-chain actions are created synchronously inside Project.lockedAccess() and consumed by one Project.executeTransaction() call.
• Metadata project/XMP changes share one transaction. Footage interpretation and input-LUT actions also share one transaction.
• Proxy attachment, relink, scene detection, Source Monitor calls, and other direct host APIs are not described as atomic action transactions. Their result envelopes identify the narrower verification boundary.
• Completed mutating protocol calls may use operation_id replay protection for the current panel session. Inputs remain bounded before a host call.

These choices reduce redundant project traversal and transaction overhead by construction. They are not a measured latency claim. A real Premiere benchmark is still required before publishing p50 or p95 improvements.

Non-undoable confirmations

ClipProjectItem.attachProxy() and ClipProjectItem.changeMediaFilePath() are documented as non-undoable. Their MCP workflows require confirm_non_undoable: true. Relink additionally defaults to require_offline: true and supports expected_current_path as a stale-state guard. Setting override_compatibility_check remains opt-in.

SequenceUtils.performSceneEditDetectionOnSelection() is also kept outside the action-transaction claim. For createMarkers, the workflow snapshots each selected item's project-item marker GUIDs and returns verified only when at least one GUID is added. Cut and subclip modes return committed_unverified after Adobe's positive host result because the API does not return the number or identities of created cuts or subclips.

Filesystem authority

The UXP manifest now declares localFileSystem: "request", replacing "fullAccess". The operator chooses one root in the panel. The panel persists Adobe's opaque folder token in plugin data and restores it with getEntryForPersistentToken().

The workspace broker applies these rules:

1. A file path must be absolute, at most 4096 characters, and free of NUL bytes.
2. . and .. segments are normalized before containment is checked.
3. Windows drive and UNC paths compare case-insensitively; prefix-only siblings such as Filmography do not match an approved Film folder.
4. Windows device names, alternate-data-stream colons, and trailing dot/space aliases are rejected before containment checks.
5. Proxy, relink, Source Monitor file, frame, interchange, AAF, and preset paths are rejected outside the approved root.
6. The status command returns only folder display name, access mode, and persistence state. It never returns the native root or persistent token.

Containment is a bridge policy, not an operating-system sandbox. The broker does not recursively enumerate the selected folder, so the live-host gate must confirm how Premiere resolves symlinks and Windows reparse points. Operators should not put links to unrelated data inside an approved workspace.

The panel's bridge URL is separately restricted to ws://127.0.0.1:<port>/uxp or ws://localhost:<port>/uxp. The manifest uses Adobe's compatible domains: "all" declaration because Premiere 26.3 rejects the narrower WebSocket list; the panel's runtime validator is the loopback-only authority and rejects remote hosts, credentials, fragments, and non-/uxp paths.

Public action contracts

manage_clip_effects_uxp

• catalog: list video match names and display names or audio display names.
• inspect: require media_type, track_index, and clip_index.
• add: additionally require effect_id; optional insertion_index.
• remove: additionally require component_index and expected_effect_id from a recent inspection. The command rejects a stale or changed component chain.

Video additions accept only a match name returned by VideoFilterFactory. Audio additions accept only a display name returned by AudioFilterFactory.

inspect_effect_parameter_catalog_uxp

Require one media_type, track_index, clip_index, and component_index. The panel resolves that active-sequence coordinate and returns no more than 64 parameter descriptors: the zero-based index, native display name, whether keyframes are supported, and whether the parameter is currently time-varying. It never reads a parameter value, including PointF or Color data. Optional expected_sequence_guid and expected_component_id reject a changed target before the final result. The complete catalog is read twice, so a changed active project, sequence, component identity, or descriptor set rejects rather than returning a mixed result. This remains a read-only contract check, not evidence of parameter editability, rendered output, playback, persistence, Undo, or a licensed Premiere host.

inspect_track_item_identity_uxp

Require one media_type, track_index, and clip_index; callers may provide expected_sequence_guid from a recent result. The read returns only the host's track-item match name, numeric item type, media UUID, reported track index, and selected state. It rejects a changed active sequence before returning. It neither reads source paths nor effect values and is not visual, playback, persistence, or licensed-host proof.

audit_object_masks_uxp

This is a read-only bounded audit over documented ObjectMaskUtils.hasObjectMask() calls. It accepts an optional active-project GUID and either one to 64 exact sequence GUIDs or, if no selectors are supplied, audits the whole active project only when it has at most 64 sequences. The bridge sorts stable sequence identities, reads the project aggregate and every selected sequence boolean, resolves the same targets a second time, and rejects any changed active project, sequence identity/name, aggregate boolean, or per-sequence boolean rather than returning a mixed result.

Adobe's API exposes only presence. The audit does not return mask counts, locations, selection, tracking state, editability, source items, render output, playback results, or licensed-host evidence. The double read is not an atomic host snapshot: a change that occurs and returns to the identical values between reads is outside this boundary.

inspect_installed_mogrt_directory_uxp

The documented SequenceEditor.getInstalledMogrtPath() getter is called only through the authenticated bridge. The result is a bounded string and stays redacted unless include_path: true. The command never enumerates, reads, or imports from that directory, so a returned path is not evidence of installed templates, compatibility, successful insertion, rendering, or licensed-host behavior.

batch_selected_clips_uxp

• inspect: return up to 64 current selection entries.
• add_effect: require one media type and effect ID.
• remove_effect: require one media type, component index, and expected effect ID.

Every selection entry must resolve to the requested media type. Validation and component creation complete before the single mutation transaction begins.

manage_timeline_selection_uxp

• inspect: return the active sequence GUID and zero to 64 current video/audio selection entries, including track/clip coordinates, project-item ID, and start/end seconds.
• inspect_targets: resolve one to 64 unselected or selected video/audio selection_targets by track/clip coordinate and return the same mutation-ready fingerprints without changing selection.
• replace, add, and remove: require expected_sequence_guid plus one to 64 selection_items copied from a recent inspect or inspect_targets result.
• clear: require expected_sequence_guid and omit selection_items.

All mutation targets are resolved and fingerprinted before the single native selection call. The command rebuilds the desired selection with TrackItemSelection.createEmptySelection() and addItem(), or calls Sequence.clearSelection() for an empty result. It then reads the selected set back and rejects mismatches. Timeline selection changes are not project mutations and do not claim Premiere Undo support; mutation actions still require MCP edit authority and may use operation_id replay protection.

detect_scene_edits_uxp

mode is apply_cuts, create_markers, or create_subclips. The command passes Adobe's corresponding SequenceUtils constant and the current native selection.

manage_proxy_ingest_uxp

Actions are inspect_proxy, attach_proxy, get_ingest, and set_ingest. Attaching media requires an approved path and explicit non-undoable confirmation. Replacing a different existing proxy additionally requires replace_existing_proxy: true. Ingest updates use ProjectSettings.createSetIngestSettingsAction().

manage_metadata_uxp

Actions are get and update. Project metadata requires 1-128 exact updated_fields. Project and XMP strings are each capped at 350,000 characters, and their combined serialized UTF-8 readback is capped at 900,000 bytes so the complete response remains below the bridge's 1 MiB frame limit.

inspect_project_panel_metadata_uxp

Actions are panel and item_columns. panel returns the active project's native Project-panel metadata; item_columns uses the established exact project-item ID, name, or singleton-selection resolution rules, then returns that item's native column metadata. Both strings may be empty but are capped at 350,000 characters and a 900,000-byte serialized result. This tool is read-only: it does not create metadata schema fields or invoke setProjectPanelMetadata(), whose documented setter has no project-targeted action or transaction boundary that could truthfully guard it across an awaited call. The result is a current-host read, not an atomic project revision, persistence, or licensed-host proof.

manage_project_panel_metadata_uxp

inspect returns the same active-project panel metadata as the read-only tool. update requires the exact expected_project_guid and expected_project_panel_metadata returned by inspection, the complete replacement project_panel_metadata, confirm_update: true, and a bounded operation_id. Both XML strings are limited to 12 KiB UTF-8 at the host boundary because two exact XML values can expand when serialized in the bridge request. The panel serializes this bridge's updates per project and performs the final async snapshot/stale check immediately before it starts the documented direct setter under lockedAccess(). Premiere exposes no atomic compare-and-set and another extension or the user interface may still race that direct call. The setter is non-undoable and has no cancellation claim. The result is verified only if an active-project exact XML readback matches; a completed call with another project or XML is committed_unverified. Operation-ID replay is scoped to the connected panel session. Automated contracts do not prove host acceptance, persistence, UI effects, Undo, or licensed-host behavior.

manage_app_preferences_uxp

inspect returns just the native string values of the documented auto_peak_generation, import_workspace, and show_quickstart_dialog keys. set accepts one allow-listed key plus the exact inspected string, a requested string value (each capped at 1024 characters), explicit persistence, confirmation, and an operation ID. The panel keeps all snapshot/stale-check/set/readback work for that key within its per-key exclusion boundary. AppPreference.setValue() is a direct application-state call rather than a project action, so this tool makes no claim of a project transaction, cancellation, Undo, durable persistence, or licensed-host validation.

manage_color_conformance_uxp

preflight returns graphics-white support, LUT IDs, and footage interpretation. update allowlists frame rate, pixel aspect ratio, field/alpha flags, VR layout and view fields, and input LUT ID. Numeric values are finite and range bounded.

audition_source_monitor_uxp

Actions are state, open_project_item, open_file, set_position, play, close, and close_all. File open is workspace-contained. Playback speed is bounded from -16 through 16.

preflight_production_storage_uxp

preflight reads project scratch/ingest state and, on Premiere 26.2+, active Production scratch state. configure_project changes only the active project's documented scratch categories to same_as_project or my_documents; there is no claim that UXP exposes an equivalent Production mutation API.

Automated evidence

• tests/uxp/stable-workflows.test.ts exercises the workflow-module host paths against a deterministic mock Premiere surface, including transaction and readback behavior.
• tests/uxp/workspace.test.ts exercises token persistence, path normalization, containment, redaction, restore, and revoke behavior.
• tests/tools/uxp-workflows.test.ts checks the workflow-module public schemas and snake-case to protocol argument translation.
• tests/uxp/commands.test.ts exercises the command-registry AppPreference contract, including allowlisted keys, stale reads, direct-set rejection, exact readback, replay, and competing operation IDs.
• tests/adobe-uxp-coverage.test.ts keeps the official-source coverage manifest machine validated.

These tests do not prove that Premiere loaded the panel or performed a real edit. All added coverage entries therefore retain liveHostVerificationStatus: not_run.

Live-host gate

Before release promotion, run the packaged panel in exact Windows and macOS stable Premiere versions and record the host version and artifact hash. At minimum:

1. Add, insert, and remove representative video and audio effects; inspect results and verify one Undo removes the whole selection batch.
2. Inspect an empty selection, then replace, add, remove, and clear mixed video/audio clip selections. Repeat on 25.6 and 26.3 to cover both setSelection return forms, and confirm stale sequence and clip fingerprints fail before changing selection.
3. Run every scene-detection mode on known footage and record created objects.
4. Attach proxy and high-resolution media, toggle ingest, and validate persistence across save/reopen.
5. Relink an intentionally offline item with and without compatibility override.
6. Round-trip representative project metadata and XMP, including Unicode and an unchanged-field case; verify Undo.
7. Conform frame rate, PAR, alpha/field settings, and input LUT; verify both readback and Undo.
8. Open project items and workspace files in Source Monitor, seek, play forward and reverse, and close them.
9. Exercise project scratch settings both inside and outside a Production and verify Undo and saved state.
10. Revoke the workspace token and confirm every path-based call fails before a host mutation; re-grant after restart and confirm restoration.

Primary Adobe references

• Premiere UXP changelog
• Component and effect APIs
• Sequence selection controls
• TrackItemSelection
• SequenceUtils scene detection
• ClipProjectItem proxy, relink, LUT, and footage APIs
• ProjectSettings
• Metadata
• ProjectColorSettings
• SourceMonitor
• PRProduction
• UXP filesystem operations