davinci-resolve-mcp 4.11.1 → 4.13.0

package/CHANGELOG.md

@@ -2,6 +2,116 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v4.13.0 — Resolve 21.1 render-setting parity, `SetHighPriority(bool)`, and a project-destroying preset order
+
+Lands the three items queued for @legionsound in #207. The 21.1 behaviour
+below is **their measurement on Studio 21.1.0.14 / macOS**, recorded as
+*reported*; this machine runs 19.1.3.7 and did not reproduce it.
+
+### New
+
+- **`resolve_control set_high_priority` takes `high`** (alias
+  `high_priority`, default `true`), and there is a new granular
+  **`set_high_priority(high)`** tool. On 21.1+ it calls
+  `SetHighPriority(bool)`, which 21.1 types as script execution priority and
+  which is reversible there: `high=false` restores normal. The no-argument call
+  this server used to make returns `False` on 21.1 and does nothing. Builds
+  before 21.1 keep the no-argument call, and `high=false` is refused on them,
+  because they cannot lower priority without a restart. `high` is coerced
+  (`"false"` is false); anything that doesn't name a boolean is refused before
+  any call. No build has a getter, so results carry `readback: null` and claim
+  no readback. Registered as a write in both the destructive registry and the
+  lifecycle risk sets (MEDIUM).
+- **Compound render settings accept `AudioFormat` and `UseUniqueFilenames`.**
+  The compound whitelist held 31 of the 33 typed `RenderSettings` fields and
+  reported these two as ignored; granular already forwarded them. A test now
+  checks the whitelist against every field of the bundled 21.1 stub's
+  `RenderSettings`. `UseUniqueFilenames` is coerced on every path (compound
+  `set_settings`, `safe_set_render_settings`, `prepare_render_job`, granular
+  `set_render_settings`), and an unrecognised value is refused with
+  `INVALID_RENDER_SETTING`. `AudioFormat` with `ExportVideo: true` warns,
+  since the stub documents it for audio-only renders.
+
+### API truth ledger
+
+- **`Project.StartRendering` is state-dependent** (reported, 21.1.0.14):
+  freshly configured jobs sometimes return `False` and stay Ready, while an
+  identical later job completes. Direct official calls reproduced both
+  outcomes. Mapped to `render start`, so the fact rides on its results. Verify
+  job status and output; nothing retries automatically.
+- **Project-settings presets mutated before a project's first `SaveProject`
+  destroy the project** (reported, 21.1.0.14, reproduced twice): saving a
+  preset, changing resolution, then updating, applying or deleting the preset,
+  then saving and closing. Every call returned `True` and SQLite
+  `integrity_check` said `ok`, but `LoadProject` then failed with "DaVinci
+  Resolve failed to open project". Save the project once before any preset
+  write, and prove it survived only by reloading it. No preset-write wrappers
+  ship yet; this entry lands first on purpose.
+- The `Resolve.SetHighPriority` entry is now version-scoped: irreversible with
+  no argument before 21.1 (measured on 19.1.3.7), and a reversible boolean on
+  21.1 (reported).
+
+### Counts
+
+- Granular tools 389 → 390; compound stays at 37. Docs and generated agent
+  rules updated.
+
+## What's New in v4.12.0 — Live subtitle presets and title text across Fusion title tools
+
+Contributed by @sidevconcept (#281). The live behaviour below rests on their
+synthetic runs on **Resolve Studio 21.1.0.17 / Windows**; this release was not
+re-measured live here (the maintainer's machine runs 19.1.3.7).
+
+### New
+
+- **`timeline_ai(action="list_title_presets")`** inventories the installed
+  factory Fusion titles and subtitle presets: local archive, category and full
+  template ID. `templates_archive` points it at a custom installation. It is an
+  inventory, not a claim that each preset works live.
+- **`timeline_ai(action="set_subtitle_preset")`** applies an installed subtitle
+  preset and common literal style inputs (font, size, position and so on) to a
+  subtitle track while Resolve stays open. It writes a **new timeline
+  revision** and keeps the original, compares the edit inventory, and re-exports
+  through Resolve to confirm the preset and controls were kept. It restores the
+  original timeline on failure.
+  - `dry_run` / `dryRun` are coerced at the dispatcher, so `"true"` previews
+    and never imports. A preview that would need a live capture is refused.
+  - The result lists `verified_components` (track counts, item names and
+    bounds, media IDs, preset controls) and `unverified_components` (markers,
+    grades, other Fusion comps, audio). Native readback is not render
+    verification, and the revision is not certified as a full copy.
+  - Staging exports are removed on success and kept for diagnosis on failure
+    (`staging_retained`, `staging_directory`).
+- **`timeline.set_title_text` / `get_title_text` reach more than TextPlus.** The
+  Fusion-comp fallback now finds literal text on TextPlus, sText, Text3D and
+  MultiText (`TextN.StyledText` in native `TextOrder`). It follows
+  `StyledTextFollower` and `PublishText` without disconnecting animation, and it
+  skips connected, expression-driven, locked and disabled inputs rather than
+  flattening them. MultiText editing was validated only on Studio 21.1.0.17 /
+  Windows.
+- **`scripts/edit_subtitle_timeline.mjs`** (backed by
+  `resolve-advanced/server/subtitle-timeline.mjs`) inspects an exported
+  subtitle track, or writes a new file with a bundled preset reference
+  (`Word Highlight`, `Lollipop`) or a native subtitle-template reference applied.
+- Synthetic title-library validation scripts write private QA reports with
+  relative image links; `src/utils/qa_privacy.py` replaces host paths and
+  project/timeline names in saved records.
+
+### Docs
+
+- New guides: `docs/guides/title-library-automation.md` and
+  `docs/guides/subtitle-track-editing.md`.
+
+### Verification
+
+- Contributor (Studio 21.1.0.17 / Windows, synthetic media): all 134 installed
+  factory Fusion presets passed native application, literal text/property
+  readback and sampled rendered-frame checks; all 23 subtitle presets applied
+  without a restart.
+- Here: Python offline suite and Node advanced suite (fresh `npm ci`) green;
+  API parity, api-limitations, read/write symmetry, agent-rule drift and
+  `npm pack` clean.
+
 ## What's New in v4.11.1 — `.cube` input ranges, `"false"` import flags and the caption character cap
 
 Three fixes from @Dev-next-gen (#286, #287, #288), each with a reproduction and a

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.11.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.13.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 37 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 389 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 390 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -410,7 +410,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **37** compound / **389** granular (live server) |
+| MCP Tools | **37** compound / **390** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.11.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.13.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v4.11.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.13.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 37 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 389 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 390 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **37** 复合 / **389** 细粒度（实时服务器） |
+| MCP 工具 | **37** 复合 / **390** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -353,7 +353,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 37 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 389 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 390 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades
@@ -418,7 +418,22 @@ Operating rules an agent must know:
   `iConfirmProjectClosed:true`; every write auto-backs-up and read-back
   verifies. Resolve caches open projects in memory: after patching, fully QUIT
   and relaunch Resolve or the patch will not be visible.
-- **Subtitle DB edits**: `project_db` `list_captions` / `write_captions` /
+- **Live subtitle effects**: use `timeline_ai.set_subtitle_preset` with Resolve
+  open. `timeline_ai.list_title_presets` discovers installed title/subtitle names
+  and full IDs. `preset` accepts a bundled or installed subtitle preset; omit it
+  to adjust the existing effect. `inputs` accepts common literal font/style,
+  size/position and text RGBA; highlight/outline controls are Word Highlight-specific.
+  Native DRT export/edit/import creates and selects a recoverable revision,
+  preserving the original. Do not ask the user to quit or relaunch for effects.
+  Render frames to verify appearance; inventory/readback alone is insufficient.
+  Installed presets are captured through the native title API in a temporary
+  timeline, then applied to the subtitle track. Common controls also work for
+  Lollipop. Never guess unmapped effect controls. `preset_reference` accepts a
+  native subtitle DRT; unbundled dry runs require such a reference.
+  Ordinary title presets use `timeline.insert_fusion_title` with the full ID,
+  then scoped `fusion_comp` probes and input writes. See
+  [title library automation](guides/title-library-automation.md) for acceptance.
+- **Offline subtitle DB edits**: `project_db` `list_captions` / `write_captions` /
   `check_captions` cover text, bounds, explicit per-word timing, add and delete.
   `list_subtitle_presets` / `copy_subtitle_preset` / `set_subtitle_preset` handle
   animated Fusion holders separately from basic `list_subtitle_styles`.
@@ -781,6 +796,12 @@ Key actions:
   is fine. No connection needed, and it never launches Resolve
 - `get_page` / `open_page(page)` — read or switch the active page
 - `get_keyframe_mode` / `set_keyframe_mode(mode)`
+- `set_high_priority(high?)` — script execution priority (granular:
+  `set_high_priority`). `high` defaults to true; on Resolve 21.1+ it calls
+  `SetHighPriority(bool)` and `high=false` restores normal. Older builds take no
+  argument and cannot lower it again this session, so `high=false` is refused
+  there. No build has a getter — report the native return, never a confirmed
+  state. Only call when the user asked for it
 - `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight
   preset names
 - `list/save/load/delete/import/export_user_preferences_preset` — Resolve

package/docs/guides/subtitle-track-editing.md

@@ -1,5 +1,88 @@
 # Subtitle tracks: captions and animated presets
 
+## Live effects: keep Resolve open
+
+For routine video changes, use the live server's
+`timeline_ai(action="set_subtitle_preset", params={...})`. Do not route subtitle
+effect changes to `project_db` or ask the user to quit/relaunch Resolve.
+
+```json
+{
+  "action":"set_subtitle_preset",
+  "params":{
+    "track":1, "preset":"Word Highlight",
+    "inputs":{
+      "font":"Segoe UI", "fontStyle":"Black", "size":0.065,
+      "position":[0.5,0.4], "textRed":1, "textGreen":1, "textBlue":1,
+      "highlightRed":1, "highlightGreen":1, "highlightBlue":0,
+      "outlineEnabled":1, "outlineRed":0, "outlineGreen":0,
+      "outlineBlue":0, "thickness":0.1
+    }
+  }
+}
+```
+
+This exports the current native DRT, edits only its subtitle Fusion holder,
+then imports and selects a new timeline revision. The original timeline remains
+recoverable. Successful operations, including dry runs, delete their staging
+exports. Failures keep the staging folder for diagnosis and return
+`staging_retained:true` and `staging_directory`; remove that folder when diagnosis
+is complete because it contains full timeline exports. Cleanup failures also
+report the retained folder with a warning. It never edits the open database, changes source
+media or requires an application restart. `dry_run:true` prepares the exported
+revision without importing it. Omit `preset` to incrementally adjust the
+current Word Highlight instead of replacing it. `preset_reference` can name
+another native DRT, with `reference_track` selecting its subtitle track.
+`revision_name` is optional and must be unique in the current project.
+
+`preset:"Word Highlight"` applies a bundled native holder exported from the
+synthetic Studio 21.1.0.17 acceptance project. Its reference settings are Segoe
+UI Black, size 0.055, centred position, white text, yellow highlight, black
+outline and thickness 0.1; these are reference settings, not claims about UI
+defaults. Explicit `inputs` override them. No reference footage is bundled.
+`preset:"Lollipop"` applies the bundled native Lollipop. Other installed subtitle
+presets are discovered from the local `Templates.drfx`, captured by the running
+Resolve as a native title in an isolated temporary timeline, then applied to the
+subtitle track through native interchange. The temporary capture is removed
+after restoring the original timeline; the original edit remains recoverable.
+No additional vendor template files are redistributed. Use
+`timeline_ai(action="list_title_presets")` to discover names, full template IDs
+and categories. Supply `templates_archive` for a nonstandard installation.
+Full IDs disambiguate names such as the ordinary and animated `Statement`.
+
+All subtitle templates with the inspected `Template = TextPlus` layout accept
+the common literal `font`, `fontStyle`, `size`, `position`, `textRed`, `textGreen`,
+`textBlue`, and `textAlpha` controls. Highlight and outline mappings remain
+specific to Word Highlight. Connected/animated controls, different layouts and
+unmapped effect controls are refused. Do not guess their meanings. The live
+matrix is documented in [title library automation](title-library-automation.md).
+An alternate `preset_reference` can copy another decodable native holder.
+For an unbundled installed preset, a mutation-free dry run needs an existing
+`preset_reference`: discovering its native definition otherwise needs a temporary
+live title. `dry_run` never creates that temporary timeline.
+
+For gradient/image text fills (observed in Grey with Shadow), solid RGB inputs
+are dormant. The writer refuses a colour edit that would only change those
+invisible values. Pass `inputs.textFillMode:"solid"` explicitly to replace the
+fill mode, then supply the desired text RGBA. The stored gradient is retained,
+and the original timeline/reference remains recoverable. Font, size and position
+edits can preserve the gradient by omitting text colour inputs. Readback reports
+the effective `textFillMode`; absent Type1 uses the observed TextPlus solid default.
+
+The handler checks live track counts, item names/bounds and Media Pool media IDs
+against the original, then re-exports the imported timeline through Resolve and
+verifies that it retained the preset controls before selecting the revision.
+`verified_components` lists these checks. Markers, grades, other items' Fusion
+compositions and audio content are **not** compared; they are listed in
+`unverified_components`. This is not verification of a complete timeline copy.
+A failed import/check
+restores the previous active timeline and reports the retained failed revision.
+Resolve re-export readback plus edit inventory is not render verification: inspect rendered
+frames at word boundaries and across caption gaps. Native DRT import was tested
+on Studio 21.1.0.17/Windows without quitting Resolve. Changing sequence IDs in
+only the sequence XML loses subtitle tracks; cross-entry references must remain
+intact. Resolve remaps timeline IDs itself on import.
+
 The advanced server's `project_db` tool edits saved local SQLite projects.
 The live server can generate subtitles with `timeline_ai.create_subtitles`,
 enumerate their items, read names/bounds and delete items. It cannot edit caption
@@ -15,7 +98,13 @@ There are two independent kinds of subtitle styling:
   holder and composition. `set_subtitle_preset` edits named Word Highlight
   controls inside its nested compressed tool section.
 
-## Required workflow
+## Offline database workflow (explicit maintenance only)
+
+The following full-quit requirement belongs to direct database writes, not
+live effect automation. Keep the guard: bypassing it can lose edits. Caption
+text/word-timing DB writes still use this offline workflow; for restart-free
+caption corrections use the live Resolve UI. A generic `SetProperty` refusal
+does not establish that all subtitle workflows require a restart.
 
 1. Generate captions in Resolve and save the project. Inspect it with
    `list_captions`, `list_subtitle_presets` and `check_captions`.
@@ -152,8 +241,9 @@ use `set_subtitle_preset` with target selectors and `inputs`.
 Colour channels are 0–1, `outlineEnabled` is 0 or 1, `size` is Fusion's
 normalised text size (not points), `position` is Fusion Center `[x,y]`, and
 `thickness` is the template's HOutlineThickness value. Parameter editing is
-restricted to the inspected Word Highlight template and literal Template
-TextPlus inputs. Connected/animated inputs and unsupported layouts are refused.
+based on common literal Template TextPlus inputs for subtitle templates;
+highlight and outline controls are specific to Word Highlight.
+Connected/animated inputs and unsupported layouts are refused.
 Missing input values in the listing mean Resolve/template defaults, not zero.
 Other supported composition envelopes can be cloned unchanged, but cannot have
 their parameter meanings guessed. Preset holder Duration is preserved from the
@@ -225,3 +315,28 @@ whether/when UI edits are retimed on save, and SRT import preserving word
 timings on 21.1. A previously reported ImportMedia(SRT)+AppendToTimeline route
 on 21.0.4.5 is not evidence that SRT carries word timings on another build.
 Repeat the probe and render test after Resolve updates.
+
+## Restart-free acceptance (2026-10-08)
+
+`tests/live_subtitle_preset_validation.py` exercised the actual Python
+`timeline_ai.set_subtitle_preset` dispatcher on Studio 21.1.0.17/Windows in the
+disposable synthetic QA project, without launching, quitting or reopening
+Resolve. It removed the animation holder from an exported synthetic timeline,
+imported that bare-caption timeline, then applied the bundled Word Highlight.
+The live action verified seven captions and the video/audio bounds/media IDs,
+and native re-export retained the requested white text and magenta highlight.
+
+Three full-resolution 1080x1920 Resolve-rendered frames were visually inspected:
+at 108200 the first word was magenta and the second white; at 108220 those
+colours swapped; frame 108180 in the caption gap was black. This proves those
+sampled frames, not every frame or other templates/builds. The harness restores
+the previous timeline, playhead and page. Earlier live runs also demonstrated
+incremental colour, size and position edits, followed by a random-colour change
+requested as a demonstration. Random colours are not the bundled defaults.
+
+A subsequent Lollipop test on the same running Studio session applied the
+effect through the native UI, then through the updated MCP action using the
+bundled reference. Resolve's re-export confirmed
+`Templates/Edit/Titles/Subtitles/Animated/Lollipop`; a rendered frame showed its
+native yellow text and orange outline. No application restart was needed.
+This Windows acceptance does not establish Mac compatibility; repeat it there.

package/docs/guides/title-library-automation.md

@@ -0,0 +1,109 @@
+# Native title and subtitle library automation
+
+Keep Resolve Studio open. Discover the installed factory Fusion presets with
+`timeline_ai(action="list_title_presets", params={})`. The inventory names the
+local archive, category and full template ID; it does not imply live acceptance.
+Use `templates_archive` when automatic discovery cannot find a custom installation.
+Factory inventory does not enumerate third-party packs or the basic non-template
+Text/Scroll generators. Installed fonts and tool availability remain host-specific.
+
+## Ordinary Fusion titles
+
+Insert with `timeline(action="insert_fusion_title", params={"name":
+"Templates/Edit/Titles/Candy"})`, then identify the inserted clip and use
+`fusion_comp.probe_fusion_comp` / `probe_fusion_tool` with `clip_id` or an explicit
+timeline-item selector. Read the actual graph and controls before editing.
+`safe_set_inputs` can set literal inputs on the inspected tool, including text,
+font, size and colour. Many presets use TextPlus; others use sText or Text3D.
+Do not assume every template has a tool called `Template`, flatten connected
+animation controls, or overwrite text instances linked to another tool.
+
+`timeline.set_title_text` also supports literal TextPlus, sText, Text3D and
+MultiText inputs. For a connected StyledTextFollower it edits the modifier's
+literal `Text` input; for PublishText it uses `Value`. MultiText uses the native
+`TextN.StyledText` controls in native `TextOrder`; `TextValueN` changes list
+labels without changing rendered text. Expressions and
+unknown modifier chains are refused rather than flattened. The default text
+action edits the first supported text target; use explicit Fusion tools when
+changing multiple independent title lines. Render to verify the resulting text.
+MultiText editing was validated only on Studio 21.1.0.17 / Windows.
+
+Use the full template ID rather than a leaf name: `Statement` exists both as an
+ordinary title and an animated subtitle. Probe `comp.GetData("TEMPLATE_ID")`
+to confirm which template native insertion selected.
+
+## Subtitle-track presets
+
+```json
+{"action":"set_subtitle_preset","params":{
+  "preset":"Templates/Edit/Titles/Subtitles/Animated/Rotate",
+  "inputs":{"size":0.06,"position":[0.5,0.25],
+            "textRed":0.15,"textGreen":0.85,"textBlue":1}
+}}
+```
+
+The live helper captures the installed template in its own temporary timeline,
+exports its native composition, restores the working timeline and removes only
+that temporary capture. It swaps the exported subtitle holder composition,
+imports a recoverable revision, checks edit/media inventory and re-exports the
+revision to confirm native preset/control retention. The original timeline
+remains intact. The inventory compares track counts, item names/bounds and media
+IDs; it does not compare markers, grades, other Fusion compositions or audio
+content. Results list both verified and unverified components. Inspect the
+revision before relying on it as a complete copy.
+Successful operations, including previews, remove staging exports; failures
+retain them for diagnosis and report `staging_retained` and `staging_directory`.
+Cleanup failures warn and report the retained folder. These files contain full
+timeline exports and should be removed after diagnosis. It never writes an open
+Project.db or changes source files.
+
+Common mapped literal controls are `font`, `fontStyle`, `size`, `position`,
+`textRed`, `textGreen`, `textBlue` and `textAlpha`. Highlight/outline mappings are
+specific to Word Highlight. Unsupported controls/layouts and animated or
+connected input replacements are refused. An imported preset readback is not a
+rendered check. Inspect caption word phases, gaps and safe margins.
+
+Gradient/image fills do not render their dormant solid RGB values. A subtitle
+colour edit refuses that case unless `textFillMode:"solid"` explicitly requests
+replacement of the fill mode. Grey with Shadow uses a native gradient; preserve
+it when editing only font/size/position, or explicitly select solid fill when
+requesting a uniform colour. The gradient data/reference stays recoverable.
+For ordinary Fusion titles, inspect the active shading mode/gradient controls;
+a raw RGB readback alone does not establish the rendered fill colour.
+
+Word Highlight and Lollipop have bundled native references. Other factory
+subtitle presets require the local installation or an explicit native subtitle
+`preset_reference`. Unbundled dry runs require a pre-existing reference so no
+live temporary title is created during preview.
+
+## Repeatable acceptance
+
+The [Windows acceptance record](../notes/title-library-acceptance.md) documents
+134 final passing cases and an interrupted ordinary-title retest that required
+automatic Studio crash recovery. It does not establish universal restart-free
+reliability or Mac compatibility.
+
+`tests/live_title_library_validation.py` requires an already-open disposable
+`MCP_QA_*` project with the synthetic caption fixture. It refuses to launch
+Resolve, renders representative native frames, records property readback and
+pixel differences, persists every case, retains test timelines and restores the
+original timeline/page/playhead. Only synthetic project contents may be used.
+
+```powershell
+venv/Scripts/python.exe tests/live_title_library_validation.py --output-dir logs/title-library-full
+```
+
+The image metrics require Pillow and NumPy; `--image-python` can use an independent
+Python installation with those packages. It runs in isolated mode, avoiding
+Resolve's Python environment. `--only` selects exact names/IDs for a focused
+retest. `scripts/title_library_report.py` builds a local HTML matrix and contact
+sheets from one or more reports; a later retest replaces the same template's case.
+The HTML uses relative links to copied QA renders under its `frames/` folder;
+move the entire output folder to view it on another machine. Saved QA records
+replace host workspace/home paths with anonymous markers; they do not retain
+the local account name or workspace folder identity.
+
+Acceptance distinguishes native application, literal property readback and
+sampled rendered appearance. It does not certify all controls, every animation
+frame, third-party packs, or Mac compatibility. Test Mac separately before
+claiming cross-platform live acceptance.

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 37 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 389 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 390 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 389-tool server
+python src/server.py --full    # Launch full 390-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/kernels/audio-fairlight-kernel.md

@@ -1,7 +1,9 @@
 # Audio / Fairlight Kernel
 
-For caption text, per-word timing, additions/deletions and animated subtitle
-presets, use advanced `project_db` after saving and fully quitting Resolve.
+For animated subtitle effects use live `timeline_ai.set_subtitle_preset` with
+Resolve open. It applies/adjusts Word Highlight through native DRT interchange
+and selects a recoverable revision. For caption text/word timing use the live
+UI, or explicit offline advanced `project_db` maintenance after fully quitting.
 See [subtitle-track editing](../guides/subtitle-track-editing.md). The basic
 `set_subtitle_style` action does not edit animated Fusion presets.
 

package/docs/kernels/fusion-composition-kernel.md

@@ -1,5 +1,14 @@
 # Fusion Composition Kernel
 
+Subtitle-track animation holders do not enumerate as caption Fusion comps.
+For installed subtitle presets and common font, colour, size and position edits,
+use live `timeline_ai.set_subtitle_preset`; Word Highlight also has mapped
+highlight/outline controls. Discover presets with `timeline_ai.list_title_presets`.
+See [subtitle-track editing](../guides/subtitle-track-editing.md) and
+[title library automation](../guides/title-library-automation.md).
+Keep Resolve open. Generic caption `SetProperty`/`GetFusionCompByIndex` is not
+the route, and direct Project.db patching is reserved for explicit offline work.
+
 The Fusion Composition kernel expands `fusion_comp` into a safer graph
 inspection, tool creation, input write, connection, and boundary-report layer
 for timeline item Fusion comps and active Fusion page comps.

package/docs/notes/subtitle-live-automation-audit.md

@@ -0,0 +1,82 @@
+# Live subtitle automation audit — 2026-10-08
+
+The `feat/subtitle-track-support` branch added useful caption/preset codecs but
+routed effect edits only through Project.db. The subsequent full-quit guard was
+correct for that database route; it did not establish that a running Resolve
+could not apply the same effect through native interchange or its own UI.
+
+## Corrected paths
+
+| Finding | Correction |
+|---|---|
+| Word Highlight edits exposed only as offline DB actions | Live `timeline_ai.set_subtitle_preset` exports native DRT, changes the exported holder, imports/selects a new revision; original retained |
+| Applying an effect required a reference in another user project | Bundle a native holder from synthetic QA with explicit reference settings and no media |
+| Subtitle `SetProperty` refusal sent every request to full-quit DB patching | Error now routes effects to the live action; text/timing to live UI or explicit offline maintenance |
+| Skills and kernels directed animation work to the offline server | Updated audio/Fusion portable skills, kernels, operating reference, advanced README and subtitle guide |
+| Codec readback could report success before Resolve parsed the composition | Re-export the imported timeline and compare its retained controls; also compare live edit inventory |
+
+Direct DB-write safety guards remain intact. Never patch the database of an
+open project, including a project loaded earlier in the same Resolve session.
+Native interchange avoids that cache hazard by asking Resolve itself to import
+the changed content.
+
+## Evidence and limits
+
+Live validation on Studio 21.1.0.17/Windows exercised the public dispatcher,
+applied Word Highlight to a bare subtitle track and verified the imported
+controls through native re-export. Seven caption bounds, video/audio bounds and
+media IDs matched. Rendered frames showed the requested white/magenta word
+phases and a blank caption gap. Incremental colour, size and position edits also
+worked, including the user's random-colour demonstration, without a restart.
+See [subtitle-track editing](../guides/subtitle-track-editing.md) and the
+synthetic-only live acceptance script.
+
+That original acceptance certified Word Highlight and unchanged Lollipop
+application, not universal video automation. The subsequent installed-library
+expansion discovers presets, captures their native definitions without UI drags,
+and maps common literal subtitle font, size, position and text RGBA controls.
+Ordinary title text now includes shape/3D/MultiText and supported text modifiers
+without flattening their animation. See
+[title library automation](../guides/title-library-automation.md) for the test
+harness and its measured limits, and the subsequent
+[134-preset acceptance record](title-library-acceptance.md), including its
+ordinary-title crash/recovery. Unmapped subtitle effect controls and caption
+text/timing changes still need observed live UI automation unless another supported
+route is available. Current granular-only clients do not expose the new compound
+action; use the compound server or the shared Python helper. Installed fonts,
+templates, speech models and Resolve build differences remain capabilities to
+probe, not assumptions.
+
+Remaining full-quit references under extension-authoring, offline DB maintenance
+and crash recovery describe distinct operations. Newly installed Fuses and
+some extension categories genuinely have restart requirements. Routine video
+edits should use already available tools or native imported compositions rather
+than turn extension installation into a repeated step. Do not erase those
+constraints to promise "100% automated".
+
+Code already loaded in an MCP process does not automatically change after a
+Git update. Follow the installer/update instructions for the component being
+updated. Bridge-script installation may require Resolve to restart. This
+feature does not change the general launcher or installer lifecycle.
+
+## Validation record
+
+- 169 Python tests in the relevant subtitle, safety, connection, lifecycle,
+  dashboard and documentation suites: passed, one skipped. A subsequent focused
+  run of 53 tests included the added imported-control-loss regression and passed.
+- 28 Node subtitle codec/DB/native-timeline tests passed. The two new native
+  timeline tests also passed independently after the readback helper was added.
+- Native API parity audit passed (existing undocumented-method advisories only).
+- Generated API-limitations, read/write-symmetry and portable-agent assets checked.
+- NPM dry-run package inspection confirmed the live bridge, codec helper and
+  native reference asset are included.
+- Windows test-fixture corrections are split into a separate change: ps fixtures
+  select their intended platform, macOS path assertions normalize separators,
+  and dashboard temporary SQLite connections close before directory removal.
+
+The automation is reviewed separately from subtitle database editing. Studio
+stayed open during the original subtitle acceptance;
+the later full-library title test has the interruption documented above.
+Existing MCP processes still need to load the
+updated Python code to expose the new action; that is separate from restarting
+Resolve.