davinci-resolve-mcp 2.98.8 → 2.99.1

package/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 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.1
+
+**`bulk_set_item_properties` could not set a clip colour on its own.** Reported
+and fixed in [#157](https://github.com/samuelgursky/davinci-resolve-mcp/pull/157)
+by @matoberuc-afk.
+
+The action documents `clip_color` and `enabled` as per-op keys and has code to
+apply both — but that code was unreachable for the op shape that needs it most.
+The payload is built by `_merge_property_groups`, which merges only
+`properties`/`transform`/`crop`/`composite`/`audio` and the duplicate-keyframe
+keys. `clip_color` and `enabled` are not `SetProperty` keys, so they never landed
+in that dict, and the `if not properties: continue` guard above returned early —
+leaving the `clip_color` branch twenty-five lines below dead on exactly the ops
+that carry no transform. Colour triage in one round trip is the main reason to
+call a *bulk* setter, and it was the one shape that could not work.
+
+### Fixed
+
+- **A colour-only or enabled-only op is now accepted** and applied.
+- **A colour-only op could not fail.** Per-op success was
+  `all(row.get("success") for row in ...properties.values())`, and `all([])` is
+  `True` — with no property rows the op passed regardless of what `SetClipColor`
+  returned. Every branch that runs now votes.
+- **The bulk path trusted the bare bool.** It called `item.SetClipColor` directly,
+  bypassing `_set_clip_color_checked` — the helper added for
+  [#124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124) that the
+  single-item path already used, because that bool lies twice: a name outside the
+  16-name Edit-page palette is refused with a bare `False`, and a generator or
+  title takes the call, returns `True`, and drops the colour. A failure now
+  carries `clip_color_detail`.
+- `dry_run` reports `would_set_clip_color` / `would_set_enabled`, and the
+  `action_help` example shows the triage shape instead of a `properties`
+  dict with a `ClipColor` key that was never a valid `SetProperty` target.
+
+### Live validation
+
+Studio 19.1.3.7: three colour-only ops in one call, live readback
+`['Apricot', 'Chocolate', 'Purple']` on the timeline items; a refused colour
+returns `success: false` instead of passing on the empty-list vote.
+
+## 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

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.98.8-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.1-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.8-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.99.1-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.8 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.99.1 版 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
@@ -1393,7 +1410,11 @@ Key actions:
   `track_index?` (default 1), so multicam angles can be rebuilt onto V2/V3
   rather than collapsing onto V1; missing tracks are added
 - `bulk_set_item_properties(ops, dry_run?, readback?)` — apply transforms,
-  crop/composite/audio/property groups to many timeline items in one call
+  crop/composite/audio/property groups to many timeline items in one call. An op
+  may carry `clip_color` and/or `enabled` with nothing else, which is the triage
+  shape: paint a whole selection in one round trip. A colour is verified by
+  readback, so a name outside the Edit-page palette and the generator/title case
+  that returns True and drops the colour both fail the op instead of passing
 - `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a
   normalized CDL and/or copy a source grade to multiple video items
 - `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve
@@ -1403,7 +1424,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 +1627,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`,
@@ -2118,6 +2148,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
@@ -350,9 +366,9 @@ values, or automation-hostile modal prompts.
 ### 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.8"
+VERSION = "2.99.1"
 # 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.8",
+  "version": "2.99.1",
   "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.8"
+VERSION = "2.99.1"
 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()