davinci-resolve-mcp 2.98.7 → 2.99.0

package/CHANGELOG.md

@@ -2,6 +2,136 @@
 
 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 v2.99.0
+
+**`timeline.ripple_insert`, and a verified-delete gate on `move_clips`.**
+Contributed in [#156](https://github.com/samuelgursky/davinci-resolve-mcp/pull/156)
+by @handst97, driven by a real data-loss incident: a session used `move_clips`
+with a record offset smaller than the item duration to "open a gap",
+`AppendToTimeline` returned items whose ids could not be read, the code counted
+them as successful duplicates, and the delete phase removed 26 source clips.
+
+### Added
+
+- **`timeline.ripple_insert`** — insert media-pool source ranges at a record
+  point and shift all later video/audio items right. There is no ripple-insert
+  primitive in the scripting API, and duplicate-then-delete corrupts the timeline
+  when the shift is smaller than an item. This plans a rebuild instead: capture
+  every tail item's pool media and source trim, delete the tail (verified),
+  re-append it shifted, then place the inserts into the opened gap — **tail
+  first, so the worst mid-failure state is a gap, never lost content**. Dry-run
+  by default, with straddler / blocker / locked-track / subtitle detection;
+  executing is confirm-token gated and archives the timeline first. Shifted items
+  are re-created from pool media with transform/crop/composite/retime re-applied;
+  grades, keyframes, transitions and link state are NOT preserved (the archive
+  keeps them).
+
+### Fixed
+
+- **`move_clips` no longer deletes a source it could not verify.** Each duplicate
+  now carries `duplicate_verified` — a live item or a real id recovered from the
+  timeline — and sources are deleted only when every duplicate, primary and
+  linked, verified. Null-id appends keep the source with an explicit warning.
+- **`safe_set_cdl` / `apply_look_to_items` preflight the node.** `NodeIndex` is
+  1-based and there is no `GetCDL`, so a bare `False` was undiagnosable; the node
+  count is now read before `SetCDL` and a failure comes back with a structured
+  reason and a clip-type-aware diagnosis.
+- **Magic Mask reports the human step instead of a bare false.** Magic Mask v2
+  isolates via operator clicks and the API cannot place them, so `CreateMagicMask`
+  on a fresh item can only return `False`. It now returns `needs_hitl` with the
+  exact Color-page steps, and the mode aliases (`'Forward'` → `'F'`) are
+  normalized — the granular `ti_create_magic_mask` defaulted to a spelling
+  Resolve rejects.
+
+### Fixed in review
+
+Three defects found reviewing #156, each with a test that fails without the fix:
+
+- **A dry-run plan archived a timeline version.** `ripple_insert` is the only
+  destructive action whose *default* call mutates nothing, and the pending-confirm
+  skip only fires while the confirm-token preference is on — so with it off,
+  routine planning calls littered the version chain.
+- **Asymmetric per-track insert durations left an unreported gap.** Every track
+  shifts by the longest inserted run, so a shorter insert leaves a hole the
+  readback structurally cannot see — it only checks the positions it placed. The
+  plan and the result now carry `gap_frames_by_track` and a warning.
+- **Subtitle straddlers passed the feasibility check.** Video and audio
+  straddlers already refuse the plan; a subtitle across the insert point stayed
+  put while the picture under it moved.
+
+### Live validation
+
+Verified on Studio 19.1.3.7 via `tests/live_ripple_insert_validation.py`:
+dry-run plan exact (insert@86448, shift 24, tail 2, no straddlers), confirm-token
+round-trip, post-insert layout `[(86400,48),(86448,24),(86472,48),(86520,48)]`,
+`readback.missing=[]`, and ZoomX/Y=0.5 surviving the shift with
+`property_restore_failures=0`.
+
+### A note on the Fusion measurement in #156
+
+The PR proposed recording that whether an API-created Fusion comp renders is
+Resolve-version-dependent, from a 21.0.4 run where a wired comp delivered a render
+bit-identical to the baseline. That reading does not survive: those comps were
+built and set through this server, and the v2.98.5 comp-lock bug produced exactly
+that symptom on any build. Running the PR's own phase-2 harness unchanged against
+the fixed code now reports **RENDERED** (Blur 24.38 dB, Transform 7.95 dB) where
+it previously reported IGNORED. The `AddFusionComp` entry records the 21.0.4
+observation as independent evidence that the lock bug is not specific to
+19.1.3.7 — the one thing this machine cannot test.
+
+## What's New in v2.98.8
+
+**The comp-lock mechanism, settled — and the v2.98.6 scope correction was itself
+wrong.** Chasing why `add_fusion_mask` and `set_text_plus` escaped the bug found
+that they don't. Their test cases were priming the comp and could not have
+failed.
+
+### The mechanism
+
+| | |
+| --- | --- |
+| **Precondition** | The comp's graph was built through lock-wrapped `AddTool`/`ConnectInput`. The same locked write against a graph wired by plain attribute assignment renders normally. |
+| **Trigger** | The locked write is the **first value write to that comp** since the build. |
+| **Primes it away** | **Any** unlocked value write anywhere in the comp — even writing a *default* value to an *unrelated* tool. Also `StartUndo`/`EndUndo` around the write. |
+| **Does not** | A structural `ConnectInput` inside the same lock; a `GetInput` readback after `Unlock`. |
+
+Priming is why every raw-API attempt to reproduce the bug kept coming back green,
+and why a control that was supposed to fail didn't.
+
+### The corrected scope
+
+| path | locked write |
+| --- | --- |
+| `set_input` | **suppressed** |
+| `safe_set_inputs` | **suppressed** |
+| `set_text_plus` | **suppressed** |
+| `add_fusion_mask` | **suppressed** |
+| `bulk_set_inputs` | escapes — wrapped in `StartUndo`/`EndUndo` |
+| `bulk_set_expressions` | escapes — wrapped in `StartUndo`/`EndUndo` |
+
+So **four of six** paths were genuinely broken, not two. v2.98.5's original
+"all six were the same bug" was closer to right than v2.98.6's correction of it;
+the two real escapes are explained by their undo wrapper.
+
+### Fixed in the tests
+
+`tests/live_fusion_value_write_validation.py` had two cases that could not fail.
+Both set up their graph with plain `SetInput` calls — a text `Size`, a blur
+amount — before the call under test, which primed the comp. Removing that:
+
+- the `set_text_plus` case now builds its rooted graph and writes **nothing**
+  before the call, leaving the Text+ at its default size;
+- the `add_fusion_mask` case composites a **Background** rather than making a
+  Blur visible, because a Background is visible at its defaults and needs no
+  setup write.
+
+Both now report `PSNR inf -> IGNORED at render` with the lock reintroduced, and
+13–17 dB APPLIED without it. The header carries a standing rule: a case in that
+file must perform no value write of any kind before the call it is testing.
+
+No production code changed. The v2.98.5 fix has been correct throughout; this is
+the third and final correction to the *description* of what it fixed.
+
 ## What's New in v2.98.7
 
 **Identifying the mechanism behind the Fusion comp-lock bug — and correcting the
@@ -61,6 +191,11 @@ it. What changed is the explanation, in `api_truth` and the harness docs.
 
 ## What's New in v2.98.6
 
+> **Corrected in v2.98.8.** The table below says four of six paths escape the
+> bug. Two of those four — `set_text_plus` and `add_fusion_mask` — do not; their
+> test cases primed the comp with setup writes and could not fail. Only
+> `bulk_set_inputs` and `bulk_set_expressions` genuinely escape.
+
 **Correcting the scope of the v2.98.5 Fusion fix, and covering all six paths
 with a render.** v2.98.5 removed a `Comp.Lock()` from six Fusion value writes and
 described all six as the same bug. Only two of them were proven with a render at

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.98.7-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.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-35%20(353%20full)-blue.svg)](#server-modes)
@@ -211,7 +211,7 @@ The open-source servers are complete and fully functional on their own.
 | App and project control | Launch/reconnect, page switching, project CRUD, project folders, databases, cloud project wrappers, settings, presets, archives |
 | Media pool and ingest | Safe import, image sequences, multicam prep timelines, bin organization, metadata normalization, metadata field inventory, marks, annotations, relink/proxy/full-resolution guards |
 | Media analysis | Source-safe file/clip/bin/project analysis, 2-pop/slate-clap sync-event detection, default Resolve metadata and Media Pool marker writeback, persisted analysis artifacts, existing-report reuse, host_chat_paths visual analysis (finalized per clip with `commit_vision`, works with any vision-capable MCP client) with opt-out, transcription with opt-out |
-| Timeline editing and conform | Track/item probing, title text key scans/writes, copy/move/duplicate helpers, range operations, gaps/overlaps, source ranges, checked interchange exports/imports |
+| Timeline editing and conform | Track/item probing, title text key scans/writes, copy/move/duplicate helpers, ripple insert, range operations, gaps/overlaps, source ranges, checked interchange exports/imports |
 | Review annotations | Timeline/item/clip markers, custom data, flags, clip color, copy/move/sync cleanup, review reports, marker thumbnail review |
 | Color and grading | Node graph probing, CDL validation, grade copy, DRX/LUT helpers, versions, Gallery stills, color groups |
 | Fusion | Timeline-item comps, safe tool creation, input writes, port inspection, validated connections, scoped bulk writes |

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.98.7-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.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-35%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![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)
 
-> 本翻译对应 v2.98.7 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.99.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -142,7 +142,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 | 应用与项目控制 | 启动/重连、页面切换、项目增删改查、项目文件夹、数据库、云项目封装、设置、预设、归档 |
 | 媒体池与摄入 | 安全导入、图像序列、多机位预备时间线、bin 整理、元数据规范化、元数据字段清单、标记、注释、重链/代理/全分辨率护栏 |
 | 媒体分析 | 源媒体安全的文件/片段/bin/项目分析，2-pop/场记板同步事件检测，默认写回 Resolve 元数据与媒体池标记，持久化分析产物，复用既有报告，host_chat_paths 视觉分析（每个片段以 `commit_vision` 定稿，任何具备视觉能力的 MCP 客户端都可用）可选退出，转写可选退出 |
-| 时间线剪辑与套底 | 轨道/条目探测、标题文字键扫描/写入、复制/移动/克隆助手、区间操作、缝隙/重叠、源范围、带检查的交换格式导入导出 |
+| 时间线剪辑与套底 | 轨道/条目探测、标题文字键扫描/写入、复制/移动/克隆助手、波纹插入、区间操作、缝隙/重叠、源范围、带检查的交换格式导入导出 |
 | 审阅注释 | 时间线/条目/片段标记、自定义数据、旗标、片段颜色、复制/移动/同步清理、审阅报告、标记缩略图审阅 |
 | 调色 | 节点图探测、CDL 校验、调色复制、DRX/LUT 助手、版本、Gallery 静帧、调色组 |
 | Fusion | 时间线条目合成、安全工具创建、输入写入、端口检查、带校验的连接、限定范围的批量写入 |

package/docs/SKILL.md

@@ -444,7 +444,11 @@ same timecodes, then restore the previous active version or node-enabled state
 after any temporary bypass capture. Treat untreated frames as diagnostic
 evidence, not as permission to discard an existing creative grade.
 
-Prefer `safe_set_cdl` for small reversible primary corrections. Use DRX/stills
+Prefer `safe_set_cdl` for small reversible primary corrections. `SetCDL`'s
+`NodeIndex` is 1-BASED (scripting README line 6) and there is no `GetCDL`
+readback — `safe_set_cdl` and `apply_look_to_items` now read the node graph's
+`GetNumNodes` first and return a structured reason/diagnosis on a false
+`SetCDL` instead of a bare boolean. Use DRX/stills
 or grade copy only when the user accepts whole-grade replacement/transfer
 semantics. Use DCTL/LUT authoring only for reusable mathematical transforms, not
 as a substitute for hand-built windows, qualifiers, or tracked secondaries. Do
@@ -1377,7 +1381,20 @@ Key actions:
   unsupported because Resolve's public scripting API does not expose transition
   cloning. `copy_keyframes=True` adds the `keyframes` group.
 - `copy_clips(...)` / `move_clips(...)` — same safe append path; `move_clips`
-  deletes successfully duplicated source items afterward
+  deletes only sources whose duplicate was VERIFIED live on the timeline
+  (AppendToTimeline can return null-id items — e.g. into an occupied span — and
+  unverified sources are kept with a warning; see api_truth
+  'AppendToTimeline null-id'). NEVER use `move_clips` to open a gap for an
+  insert; that is `ripple_insert`'s job.
+- `ripple_insert(clip_infos, record_frame|record_timecode, record_frame_mode?,
+  dry_run?, confirm_token?)` — insert media-pool source ranges at a record point
+  and shift ALL later video/audio items right. DRY-RUN by default (full plan
+  with straddler/blocker detection); executing is confirm-token gated and
+  archives the timeline first. Shifted items are re-created from pool media
+  with transform/crop/composite/retime re-applied; grades, keyframes,
+  transitions, and link state on shifted items are NOT preserved (the archive
+  keeps them). Refuses mid-item insert points, non-pool items in the tail
+  (titles/generators/Fusion comps), subtitle shifts, and locked tracks.
 - `copy_range` / `duplicate_range` — copy exact video/audio source segments
   from `start_frame`/`end_frame` or mark in/out to `record_frame`
 - `overwrite_range` — delete whole destination overlaps, then copy the exact
@@ -1403,7 +1420,11 @@ Key actions:
   page and only while it is frontmost; the tool switches page automatically and
   restores the previous one. Expect a page flash in the GUI,
   and note that landing on Color can kick off cache/render work for the current
-  clip — on a large timeline the switch is not free
+  clip — on a large timeline the switch is not free.
+  NOT WYSIWYG for Fusion: thumbnails do not reflect Fusion composition output
+  (a warp demo read as identical before/after from a contact sheet,
+  2026-08-19). Prove Fusion/grade claims with `gallery_stills grab_and_export`
+  or an extracted RENDERED frame, never a thumbnail
 - `edit_kernel_capabilities` — report supported, partially supported, and
   unsupported timeline edit kernel behavior
 - `probe_edit_kernel_item(clip_ids? selected? timeline_item?)` — read-only
@@ -1602,7 +1623,12 @@ Key actions:
   clip version
 - `stabilize`, `smart_reframe`
 - `create_magic_mask(mode)` — mode: `"F"` forward, `"B"` backward, `"BI"` bidirectional
-  (requires DaVinci Neural Engine and Color page)
+  (requires DaVinci Neural Engine and Color page). Magic Mask v2 isolates via
+  operator CLICKS on the subject (manual ch. 139; strokes are legacy v1) and
+  the API cannot place clicks — with none present this returns
+  `{needs_hitl: true, hitl: {steps...}}` instead of a bare false. Never call it
+  as if it isolates a subject unattended; prove any isolation with a rendered
+  frame (`gallery_stills grab_and_export`).
 
 Color / Grade kernel actions (v2.11.0+) add safer grade inspection and
 boundary helpers: `grade_capabilities`, `probe_grade_item`,
@@ -1691,13 +1717,13 @@ Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, o
 page comp (omit timeline scope).
 
 READBACK IS NOT PROOF FOR FUSION PARAMETERS. Up to v2.98.4 every value write
-here ran inside a `Comp.Lock()`. For `set_input` and `safe_set_inputs` that was
-load-bearing: the value is stored in the graph and returned by `get_input` while
-the RENDER ignores it entirely (Studio 19.1.3.7: PSNR inf vs the no-comp
-baseline — the delivered file was bit-identical to no comp at all). The other
-four locked paths did not reproduce it, so the blast radius was narrower than
-first reported; the locks came off all six regardless. Fixed in v2.98.5
-(measurement corrected in v2.98.6), and guarded by
+here ran inside a `Comp.Lock()`, and a value written under a comp lock is stored
+in the graph and returned by `get_input` while the RENDER ignores it entirely
+(Studio 19.1.3.7: PSNR inf vs the no-comp baseline). Four of the six affected
+paths — `set_input`, `safe_set_inputs`, `set_text_plus`, `add_fusion_mask` — were
+confirmed broken by rendering; `bulk_set_inputs` and `bulk_set_expressions`
+escape because they wrap their write in `StartUndo`/`EndUndo`. Fixed in v2.98.5,
+mechanism settled in v2.98.8, and guarded by
 `tests/test_fusion_value_write_lock.py` plus the rendered-frame harness
 `tests/live_fusion_value_write_validation.py`. The lesson outlives the bug: a
 Fusion parameter that reads back correctly has proven nothing about the output,
@@ -2118,6 +2144,18 @@ The server provides several mechanisms to inspect a frame as Resolve has process
 it, including color grading, effects, and compositing — not just the raw source
 file.
 
+WYSIWYG hierarchy (live-verified 2026-08-20): a `grab_and_export` gallery still
+faithfully reflects edit sizing (Inspector transforms) and grades; media-pool
+thumbnails and `thumbnail_contact_sheet` output do NOT reflect Fusion
+composition output. Also note that whether an API-created Fusion comp is
+honoured at render is Resolve-version-dependent: a wired comp rendered on
+Studio 19.1.3.7, but on Studio 21.0.4 the same Blur configuration and a
+Transform variant both rendered bit-identical to the no-comp baseline, and no
+API selects an item's active composition (api_truth
+'AddFusionComp'). The only acceptable proof of a Fusion or grade claim is a
+rendered frame: `grab_and_export`, an exported gallery still, or a frame
+extracted from a delivered render.
+
 **Start here: `timeline_frame(action="capture")`** — Returns the frame at the
 playhead (or at any `timecode`/`frame` you name) as MCP image content, so a
 multimodal assistant can simply look at it. It renders that one frame, which is

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 27 missing capabilities, 36 bugs / unreliable behaviors.
+**Totals:** 29 missing capabilities, 37 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -239,6 +239,22 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Check GetRenderCodecs(format) first; when it is empty, treat the format as unreachable through this API rather than guessing a codec value. Render audio-only via ExportVideo=False on a format that does expose codecs, or drive it from a saved render preset.
 - **Tags:** render, deliver, audio, unsupported
 
+### TimelineItem.CreateMagicMask (needs operator clicks)
+
+- **Object:** `TimelineItem`
+- **Signature:** `(mode) -> bool`
+- **Behavior:** Returns False when the item carries no Magic Mask clicks. Magic Mask v2 is click-driven (manual ch. 139; strokes are the legacy v1 interface) and the scripting API has no way to place a click, so on a fresh item the call can never isolate anything — it only tracks a mask the operator already seeded. Mode strings are 'F', 'B', 'BI'; long spellings like 'Forward' are rejected.
+- **Workaround / current handling:** Treat CreateMagicMask as track-only: have the operator click the subject (Color page > Magic Mask palette) and then call it, or surface the HITL steps instead of a bare False. Verify isolation with a rendered frame (gallery_stills grab_and_export), never a thumbnail.
+- **Tags:** ai, magic-mask, hitl, silent-failure
+
+### TimelineItem.SetCDL (write-only, no GetCDL)
+
+- **Object:** `TimelineItem`
+- **Signature:** `({NodeIndex, Slope, Offset, Power, Saturation}) -> bool`
+- **Behavior:** There is no GetCDL, so applied CDL values cannot be read back; the bool is the only signal and it returns False with no reason (missing node, still/generator item, values silently rejected). NodeIndex is 1-based (README line 6) and must not exceed Graph.GetNumNodes() — note TimelineItem.GetNumNodes is deprecated; the count lives on item.GetNodeGraph().
+- **Workaround / current handling:** Read item.GetNodeGraph().GetNumNodes() before SetCDL and diagnose a False against the node count and clip type. Prove the applied look with a rendered frame (gallery_stills grab_and_export or Project.ExportCurrentFrameAsStill), not the return value.
+- **Tags:** color, cdl, readback, silent-failure
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -343,16 +359,16 @@ values, or automation-hostile modal prompts.
 
 - **Object:** `Composition (Fusion, via TimelineItem comps)`
 - **Signature:** `Lock() / Unlock()`
-- **Behavior:** A numeric tool.SetInput() performed between Comp.Lock() and Comp.Unlock(), when that write is the only thing the call does, is stored in the graph and reads back correctly from GetInput() but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code. PRECONDITION (2026-08-22): the suppression only reproduces on a graph that was BUILT through lock-wrapped AddTool/ConnectInput calls. The same locked write against a graph wired by plain attribute assignment renders normally, so 'a lock around a value write' is necessary but not sufficient — the comp has to have been through prior lock cycles. RESCUERS, each verified by rendering: Comp.EndUndo() after the locked write restores it, and so does any subsequent UNLOCKED value write. NOT rescuers: a structural ConnectInput inside the same lock, and a GetInput readback after the Unlock — both still render the stale frame. This explains why undo-wrapped bulk writes escape the bug; two further call shapes (a mask whose inputs are written right after AddTool, and a StyledText string write) escape it for reasons still unidentified. Keep value writes outside the lock everywhere rather than relying on an escape.
+- **Behavior:** A numeric tool.SetInput() performed between Comp.Lock() and Comp.Unlock(), when that write is the only thing the call does, is stored in the graph and reads back correctly from GetInput() but is NOT applied when the timeline is rendered. Measured live on Studio 19.1.3.7 (2026-08-21) with MediaIn -> Blur(XBlurSize 20) -> MediaOut on a media-backed clip: written under the lock the delivered H.264 render is bit-identical to the no-comp baseline (ffmpeg PSNR inf); the identical write with the lock removed renders at PSNR 24.38 dB and the file shrinks 2.0 MB -> 727 KB, as a blur should. The variable was isolated against the comp handle (AddFusionComp, GetFusionCompByIndex and GetFusionCompByName all render), the node name, and the write form (attribute assignment and SetInput both render unlocked). STRUCTURAL edits are unaffected: AddTool and ConnectInput inside a lock render normally, so the lock is not broadly unsafe — it suppresses the parameter-change invalidation that a value write depends on. Lock() is widely recommended for batching Fusion edits, which is how this reaches production code. MECHANISM (settled 2026-08-22). PRECONDITION: it only reproduces on a comp whose graph was BUILT through lock-wrapped AddTool/ConnectInput; the same locked write against a graph wired by plain attribute assignment renders normally. TRIGGER: the locked write is lost when it is the FIRST value write to that comp since the build. PRIMING: any unlocked value write anywhere in the comp clears the condition permanently — even writing a DEFAULT value to an unrelated tool — and so does StartUndo/EndUndo around the write. A structural ConnectInput inside the same lock does NOT clear it, and neither does a GetInput readback. Priming makes false negatives easy: a test that sets anything up with a plain SetInput before the call under test will pass even with the bug present.
 - **Workaround / current handling:** Never hold a comp lock across a value write. Lock only structural work (AddTool/ConnectInput) and set inputs outside it. Because every readback the API offers agrees with the value that was written, this failure is invisible without a render — prove Fusion parameter changes with a delivered frame or gallery_stills grab_and_export, never with GetInput.
 - **Tags:** fusion, silent-failure, render, readback
 
 ### TimelineItem.AddFusionComp / LoadFusionCompByName
 
 - **Object:** `TimelineItem (media-backed clip)`
-- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side.
-- **Workaround / current handling:** Wire the graph so MediaOut descends from MediaIn — that is the difference between a comp that renders and one that is silently bypassed, and it is what made this look like 'Fusion never renders from the API'. Never leave a tool unrooted: a MediaOut fed by a tool with no source failed the render job outright. For text or effects over picture, insert a Fusion title/generator as its own timeline clip and set its Text+ (fusion_comp set_text_plus), rather than attaching a comp to the media clip. Note the destination track cannot be chosen from the API (see the Track Selector entry), so overlaying onto an existing clip's track is not currently reachable end-to-end. Building the comp in the Fusion page UI works; only the API-created comp is ignored.
-- **Tags:** fusion, silent-failure, render
+- **Behavior:** A Fusion composition created on a media clip through the API is not applied at render WHEN MEDIAOUT HAS NO PATH FROM MEDIAIN. The original blanket form of this entry — 'never applied at render' — was too broad and was corrected on 2026-08-02: a comp wired MediaIn -> Blur -> MediaOut, created entirely through the API on an ordinary media clip, DOES render. PSNR between the plain and Fusion renders of the same timeline was 22.7 dB (identical would be infinite), the file shrank 22.5 MB -> 14.8 MB as a blur should, and the output was frame-for-frame identical in GUI and headless. A first attempt that wired ONLY MediaOut -> Blur, leaving the Blur with no source, made the render job come back 'Failed' with an 887-byte file — so an unrooted graph does not merely get bypassed, it can take the render down. What still stands is the original observation for the configuration it actually tested, which is retained below and has NOT been re-measured: AddFusionComp() returns the comp, AddTool/Connect/SetInput all succeed, and the whole graph reads back correctly (GetCompCount 1, MediaOut1.Input wired to the new tool, StyledText returning the value just set) — but the rendered output is byte-for-byte the untouched source media. Verified live on Studio 19.1.3.7 with the strongest form of the test: MediaOut1 fed ONLY by a Text+, with no path from MediaIn at all, still rendered the unmodified clip. LoadFusionCompByName on the sole comp does not activate it either. Contrast InsertFusionTitleIntoTimeline, whose comp DOES render — text set via SetInput('StyledText') appears in the output — so this is specific to comps attached to media-backed clips, not to Fusion through the API generally. REPRODUCED 2026-08-21 on Studio 19.1.3.7: a rooted MediaIn -> Blur -> MediaOut comp built entirely through the API renders (PSNR 24.38 dB vs the no-comp baseline), so the 2026-08-02 correction stands. Note that an important share of 'the comp was ignored' readings are NOT this entry at all but the Composition.Lock bug above — a parameter written under a comp lock reads back correctly and never reaches the render, which looks identical from the API side. That is what an independent 2026-08-20 report on Studio 21.0.4.5 was measuring: a wired MediaIn -> Blur -> MediaOut comp, and a Transform variant, both delivered renders bit-identical to the no-comp baseline (PSNR inf) when built and set through this server. It was read at the time as a version regression (19.1.3.7 honours a wired comp, 21.0.4.5 does not); with the lock bug identified, the simpler reading is that the same defect reproduces on 21.0.4.5 — and since the lock bug has only been isolated on 19.1.3.7, that report is the only evidence it is not build-specific. Treat 'a wired comp renders' as established for 19.1.3.7 and unverified elsewhere.
+- **Workaround / current handling:** Wire the graph so MediaOut descends from MediaIn — that is the difference between a comp that renders and one that is silently bypassed, and it is what made this look like 'Fusion never renders from the API'. Never leave a tool unrooted: a MediaOut fed by a tool with no source failed the render job outright. For text or effects over picture, insert a Fusion title/generator as its own timeline clip and set its Text+ (fusion_comp set_text_plus), rather than attaching a comp to the media clip. Note the destination track cannot be chosen from the API (see the Track Selector entry), so overlaying onto an existing clip's track is not currently reachable end-to-end. Building the comp in the Fusion page UI works; only the API-created comp is ignored. Never claim a Fusion effect from comp readback alone — prove it with a rendered frame (gallery_stills grab_and_export before/after, or a delivered render). On setups where even the wired comp does not render (see the 2026-08-20 measurement), treat per-item Fusion effects as HITL (a human builds or activates the comp in the UI) and bake stills motion with ffmpeg when unattended output is required.
+- **Tags:** fusion, silent-failure, render, readback, hitl
 
 ### Composition.Paste
 
@@ -532,3 +548,11 @@ values, or automation-hostile modal prompts.
 - **Behavior:** PANEL-dependent, not mode-dependent — and the distinction took three revisions of this entry to pin down, so the evidence is recorded rather than summarised. Across four controlled 92-probe sweeps (2 GUI, 2 headless, 2026-08-01) it returned False and wrote nothing in ALL FOUR, while Timeline.GrabStill() succeeded in all four — so it is not being handed an empty still. In one earlier GUI session it DID work, returning True and writing 2 files. The variable that differed is not the mode: it is whether the Gallery panel was visible on the Color page, which depends on the restored workspace layout and which the harness does not control. A headless session can never satisfy it, so in practice the call never works headless; a GUI session satisfies it only sometimes. Project.ExportCurrentFrameAsStill worked in all four runs in both modes.
 - **Workaround / current handling:** Do not use ExportStills unattended in either mode — a GUI session is not sufficient, only a GUI session with the Gallery panel open. Use Project.ExportCurrentFrameAsStill for pixels (verified in both modes, four for four) or drp.extract_node_graphs for grades. If ExportStills must be used, have the user open Workspace > Gallery first and verify the written files rather than trusting the return.
 - **Tags:** gallery, stills, headless, unreliable-return
+
+### MediaPool.AppendToTimeline (null-id timeline items)
+
+- **Object:** `MediaPool`
+- **Signature:** `([{clipInfo}, ...]) -> [TimelineItem]`
+- **Behavior:** The returned TimelineItem objects can have an unreadable/empty GetUniqueId, notably when the clipInfo recordFrame lands in a span still occupied by another item (any duplicate-then-delete 'move' whose offset is smaller than the item duration hits this). The item may not actually exist on the timeline. A session that trusted the non-empty return and deleted the sources lost 26 clips (Portugal timeline, 2026-08-19).
+- **Workaround / current handling:** Never treat AppendToTimeline's return as proof of placement. Re-enumerate the track and match on record frame + duration before any dependent delete; never shift items by duplicate-then-delete into occupied spans — use timeline.ripple_insert, which rebuilds the tail into free space and verifies by readback.
+- **Tags:** editorial, silent-failure, unreliable-return, timeline

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.98.7"
+VERSION = "2.99.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.98.7",
+  "version": "2.99.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.98.7"
+VERSION = "2.99.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/timeline_item.py

@@ -1926,17 +1926,34 @@ def ti_load_burn_in_preset(preset_name: str, item_index: int = 0, track_type: st
 
 
 @mcp.tool()
-def ti_create_magic_mask(mode: str = "Forward", item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
+def ti_create_magic_mask(mode: str = "F", item_index: int = 0, track_type: str = "video", track_index: int = 1) -> Dict[str, Any]:
     """Create a Magic Mask on a timeline item.
 
+    Magic Mask v2 needs operator CLICKS on the subject (Color page > Magic Mask
+    palette > click subject > Track Forward); the API cannot place them, so with
+    no clicks present Resolve returns False and no isolation exists.
+
     Args:
-        mode: 'Forward' or 'Backward'. Default: 'Forward'.
+        mode: 'F' (forward), 'B' (backward), or 'BI' (bidirection) per the
+            scripting README ('Forward'/'Backward' are accepted as aliases).
         item_index: 0-based item index. Default: 0.
     """
+    aliases = {"F": "F", "FORWARD": "F", "B": "B", "BACKWARD": "B",
+               "BI": "BI", "BIDIRECTION": "BI", "BIDIRECTIONAL": "BI"}
+    normalized = aliases.get(str(mode).strip().upper())
+    if not normalized:
+        return {"error": "mode must be 'F', 'B', or 'BI'"}
     item, err = _get_timeline_item(track_type, track_index, item_index)
     if err:
         return err
-    return {"success": bool(item.CreateMagicMask(mode))}
+    if bool(item.CreateMagicMask(normalized)):
+        return {"success": True, "mode": normalized}
+    return {
+        "success": False,
+        "needs_hitl": True,
+        "hitl": "No Magic Mask clicks on this item — a human must click the subject "
+                "on the Color page Magic Mask palette, then press Track Forward.",
+    }
 
 
 @mcp.tool()