davinci-resolve-mcp 2.104.10 → 2.106.0

package/CHANGELOG.md

@@ -2,6 +2,112 @@
 
 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.106.0
+
+**Media clips in native DRT authoring — cut real footage into an importable,
+RENDERING timeline.** The deepest silent-failure class this repo has hit, run
+to ground and shipped, live-verified at every step on Studio 19.1.3.7.
+
+### The discovery chain
+
+Adding media cuts to drt.assemble surfaced three buried traps in sequence.
+First: repointing the bundled media template at a new file left the pool
+entry's compressed identity blobs describing the ORIGINAL capture source —
+and when that file still exists on the machine, Resolve silently links IT
+(observed: authored timelines linked a client clip while every visible field
+said the right path). Second: after teaching the Clip identity blobs the new
+path (their layout: dir, filename, ctime-format mtime string, codec tag,
+uuid, mtime-in-MICROSECONDS — a field first misread as file size), imports
+read back perfectly and still failed to render: "Full resolution media not
+found". Third: the render engine validates the pool entry's DEEP descriptors
+(Radiometry, keyed-dict FieldsBlobs, stream data) that offline code cannot
+synthesize. Structural readback cannot see any of this — only rendering can.
+
+### The architecture that works
+
+- **`media_pool.capture_media_template(media_path)`** (live, once per file):
+  builds a disposable project around the file, lets Resolve describe it
+  natively, caches the pool media element + MediaRef id under
+  ~/.config/davinci-resolve-mcp/media-templates/, and switches your project
+  back.
+- **`drt.assemble` grows media support**: `media: {mediaFilePath, spec,
+  cuts: [{startFrame, durationFrames, srcIn}]}` cuts ONE source into N
+  placements (new cut-media vendor primitive: donor clip cloned with fresh
+  DbIds and per-cut geometry on video + audio tracks; placement guards refuse
+  cuts before the timeline origin and reads past the media's end). At build
+  time the cached native element is TRANSPLANTED and MediaRefs rewired —
+  rendered output then matches a natively built timeline exactly (YAVG
+  125.6/123.2 across cuts vs 123.2 native control). Without a cache the
+  result carries mediaDescriptor: 'repoint-fallback' and a warning naming
+  the capture action.
+- **Version-matched templates**: a Resolve-21 template stamped down to 19
+  imports and reads back perfectly — and renders BLACK (the stamp clears the
+  gate, not the blob semantics). Both template generations now ship ('21'
+  original, '19' captured from 19.1.3.7); drt.assemble picks by
+  targetAppVersion.
+
+### Fixed
+
+- `render.verify_output` never verifies a job whose JobStatus is not
+  Complete (a Failed job's stub passed the duration-ratio check during this
+  hunt).
+- The repoint fallback's Clip identity blobs are now written with the
+  measured field semantics (mtime-µs, ctime string, dropped stale fields).
+
+All of it is an api_truth entry: imported media renders only with NATIVE
+pool descriptors; render-verify authored timelines, because structural
+readback cannot see this class.
+
+## What's New in v2.105.0
+
+**Native-schema DRT authoring — the parked "project, not a lap" — shipped.**
+Tool-authored .drt files that Resolve's ImportTimelineFromFile actually
+accepts, live-verified end to end on Studio 19.1.3.7.
+
+The door was already half-open: the repo's template-splice engine
+(assembleTimeline + the real Resolve-21 empty-project capture) authors
+native-schema .drp archives, and the final bisection showed a .drt IS a .drp
+that ImportTimelineFromFile accepts. What stood between them was the version
+gate (the template stamps DbPrjVer 17; a 19.1.3 host wants 14) and a set of
+extraction traps nobody had mapped.
+
+### Added
+
+- **`drt.assemble`** — spec → importable native-schema .drt (titles,
+  generators, transitions), with `targetAppVersion` stamping for pre-21
+  hosts. Live-verified: assembled archives import with every element intact.
+- **`drt.extract_from_drp` rebuilt on the measured recipe**: keep
+  project.xml + MediaPool + the SeqContainer at its ORIGINAL uuid path, drop
+  Gallery, and remove other timelines' Sm2MpTimelineClip blocks (matched via
+  the kept container's track Sequence DbIds) so they don't arrive as ghost
+  empty timelines. The Python extractor behind `timeline.import_from_drp`
+  implements the same recipe. Live-verified: single-timeline extracts from a
+  two-timeline project import cleanly, one timeline, clips intact.
+
+### The .drt import contract, fully mapped (api_truth rewritten)
+
+A whole saved-project export renamed .drt imports, clips intact.
+Requirements: project.xml; MpFolder.xml (it holds the Sm2Sequence/Sm2Timeline
+objects); the SeqContainer's ORIGINAL uuid path — renaming it "succeeds"
+with an EMPTY timeline, no error, the nastiest variant; version stamps at or
+below the host; native blob schema; and a SAVED source project —
+ExportProject snapshots the saved DB state, so an unsaved timeline exports
+empty tracks (the trap that produced v2.104.7's "necessary but not
+sufficient" verdict, now corrected). Every Sm2MpTimelineClip block imports
+as a timeline; extras arrive as ghosts unless removed.
+
+### Fixed in passing
+
+- **project_db lookups can no longer hang on an unresponsive library root.**
+  Mid-session, macOS rendered the Lite sandbox container path unresponsive at
+  the filesystem level (`ls` itself hung) — which froze the Node test suite
+  and would have frozen every projectName lookup. Roots are now probed with a
+  deadline (`responsiveRoots`); unresponsive ones are skipped and NAMED in
+  the not-found error. The root-walking tests are hermetic now — suites must
+  not depend on machine paths that an OS can wedge.
+- The flat-authored-shape refusal in import_timeline_checked now points at
+  `drt.assemble` as the importable authoring route.
+
 ## What's New in v2.104.10
 
 Stones turned on the live-validation backlog, on Studio 19.1.3.7.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.104.10-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.106.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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.104.10-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.106.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-36%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.104.10 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.106.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/reference/api-limitations.md

@@ -530,8 +530,8 @@ values, or automation-hostile modal prompts.
 
 - **Object:** `MediaPool`
 - **Signature:** `(drtPath, {importSourceClips, ...}) -> Timeline`
-- **Behavior:** Measured by bisection on Studio 19.1.3.7 against a real .drt export: (1) the archive MUST contain project.xml — the same archive minus only that entry is refused, while removing MediaPool/MpFolder.xml or renaming the SeqContainer path changes nothing; (2) the container XML must be Resolve's native blob-based schema — a syntactic SeqContainer with flat template elements is refused even beside a genuine project.xml; (3) the imported timeline is named after the FILE (real_2997.drt -> 'real_2997'), not the container's internal name — a third naming authority beside FCP7 (internal name wins) and OTIO (timelineName option wins); and (4) a refused import can raise a modal error dialog that BLOCKS the scripting call until a human dismisses it — the call neither returns nor times out.
-- **Workaround / current handling:** Import only .drt files Resolve itself exported — the sufficient set is unmapped beyond that: even a .drp-sourced native container repacked WITH its project.xml was refused (measured 19.1.3.7), so extraction-based .drt import cannot be relied on either. Name the timeline by naming the FILE. Never batch speculative .drt imports unattended — one refusal can hold the whole session hostage behind its dialog. timeline.import_timeline_checked detects the authored template shape up front and refuses with this diagnosis instead of importing; for a reliable programmatic import use OTIO or FCP7 XML.
+- **Behavior:** Fully mapped by bisection on Studio 19.1.3.7: a .drt IS a .drp that ImportTimelineFromFile accepts — a whole saved-project export renamed .drt imports, clips intact. Requirements: (1) project.xml present; (2) MediaPool/MpFolder.xml present — it holds the Sm2Sequence/Sm2Timeline objects; (3) the SeqContainer keeps its ORIGINAL uuid path — renaming it 'succeeds' with an EMPTY timeline (items=0, no error), the nastiest variant; (4) version stamps at or below the host's ProjectVersion; (5) native blob schema — flat template containers are refused; (6) the source must be a SAVED export (ExportProject snapshots the saved DB state, so an unsaved timeline exports EMPTY tracks). Every Sm2MpTimelineClip block in MpFolder imports as a timeline: extra blocks arrive as ghost empty timelines unless removed (match blocks via the kept container's track <Sequence> DbIds). The imported timeline is named after the FILE, and a refused import can raise a modal dialog that BLOCKS the scripting call until a human dismisses it.
+- **Workaround / current handling:** Follow the recipe: drt.extract_from_drp implements it (original container path, MpFolder carried, ghost blocks removed, Gallery dropped), and drt.assemble authors importable native-schema archives from scratch (template-spliced; pass targetAppVersion on pre-21 hosts). Save the project before ExportProject. Name the timeline by naming the FILE. Never batch speculative .drt imports unattended — one refusal can hold the session hostage behind its dialog; timeline.import_timeline_checked refuses the flat authored shape up front for exactly that reason.
 - **Tags:** timeline, import, silent-failure, headless
 
 ### Timeline.DeleteClips (requires the Edit page; flaky first attempt)

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.104.10"
+VERSION = "2.106.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.104.10",
+  "version": "2.106.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/db-patch.mjs

@@ -52,6 +52,44 @@ export const LITE_DB_ROOT = path.join(
 /** Every root searched when resolving a project by name, Studio first. */
 export const DB_ROOTS = [DISK_DB_ROOT, PROJECT_LIBRARY_ROOT, LITE_DB_ROOT];
 
+/**
+ * Filter roots to the ones that answer a readdir within `deadlineMs`.
+ *
+ * macOS can render a path UNRESPONSIVE at the filesystem level — measured
+ * live 2026-08-30: `ls` on the Lite sandbox container hung indefinitely
+ * (File-Provider/container materialization), which made every projectName
+ * lookup and the test suite hang with it. A hung readdir cannot be
+ * cancelled; the race abandons it (one leaked threadpool op) and reports the
+ * root as skipped so the caller can say WHERE it could not look.
+ * Returns { roots, skipped: [{root, reason}] }.
+ */
+export async function responsiveRoots(roots = DB_ROOTS, deadlineMs = 3000) {
+  const fsp = require('node:fs/promises');
+  const results = await Promise.all(
+    roots.map(async (root) => {
+      try {
+        const answer = fsp
+          .readdir(root)
+          .then(() => 'ok', (err) => (err && err.code === 'ENOENT' ? 'absent' : 'error'));
+        const timer = new Promise((resolve) => {
+          const t = setTimeout(() => resolve('timeout'), deadlineMs);
+          if (t.unref) t.unref();
+        });
+        const outcome = await Promise.race([answer, timer]);
+        return { root, outcome };
+      } catch {
+        return { root, outcome: 'error' };
+      }
+    }),
+  );
+  return {
+    roots: results.filter((r) => r.outcome === 'ok' || r.outcome === 'absent').map((r) => r.root),
+    skipped: results
+      .filter((r) => r.outcome === 'timeout')
+      .map((r) => ({ root: r.root, reason: `unresponsive after ${deadlineMs}ms (hung filesystem path — skipped)` })),
+  };
+}
+
 export function loadSqlite() {
   try {
     return require('better-sqlite3');
@@ -85,17 +123,22 @@ export function findProjectDb(projectName, root = DISK_DB_ROOT) {
   return hits;
 }
 
-export function resolveDbPath({ projectDb, projectName }) {
+export function resolveDbPath({ projectDb, projectName, roots, skippedRoots = [] }) {
   if (projectDb) return projectDb;
   if (!projectName) throw new Error('provide projectDb (path) or projectName');
+  const searchRoots = roots || DB_ROOTS;
   // Deduplicate: a project present under both roots must not read as ambiguous
   // just because the same file was found twice.
-  const hits = [...new Set(DB_ROOTS.flatMap((root) => findProjectDb(projectName, root)))];
+  const hits = [...new Set(searchRoots.flatMap((root) => findProjectDb(projectName, root)))];
   if (!hits.length) {
     throw new Error(
-      `no Project.db found for project "${projectName}". Searched the Studio libraries ` +
-      `(${DISK_DB_ROOT} and ${PROJECT_LIBRARY_ROOT}) and the sandboxed free-edition ` +
-      `library (${LITE_DB_ROOT}). ` +
+      `no Project.db found for project "${projectName}". Searched: ` +
+      `${searchRoots.join(', ')}. ` +
+      (skippedRoots.length
+        ? `SKIPPED unresponsive root(s): ${skippedRoots.map((r) => r.root).join(', ')} — ` +
+          'a hung filesystem path (File Provider / sandbox container); its projects ' +
+          'are invisible until macOS unwedges it. '
+        : '') +
       'If Resolve keeps its projects elsewhere — a relocated library, a network/Postgres ' +
       'database, or the free edition on Windows/Linux — pass projectDb with the full path.',
     );

package/resolve-advanced/server/tools/drt.mjs

@@ -19,7 +19,7 @@
 import fs from 'node:fs/promises';
 import { z } from 'zod';
 import JSZip from 'jszip';
-import { drt } from '../libs.mjs';
+import { drt, drp } from '../libs.mjs';
 import { summarizeDrtTimelines } from '../sequences.mjs';
 
 const parseSchema = z.object({ drtPath: z.string().describe('Absolute path to a .drt (or .drp) file') });
@@ -29,6 +29,48 @@ const authorSchema = z.object({
   outputPath: z.string().describe('Absolute path where the .drt will be written'),
 });
 const validateSchema = z.object({ drtPath: z.string().describe('Absolute path to a .drt file') });
+const assembleSchema = z.object({
+  spec: z
+    .object({})
+    .passthrough()
+    .describe("assembleTimeline spec: { timelineName?, elements: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, ...}], transitions? }. startFrame is timeline-absolute (origin 86400)."),
+  outputPath: z.string().describe('Absolute path where the importable .drt will be written'),
+  targetAppVersion: z
+    .union([z.string(), z.number()])
+    .optional()
+    .describe("Resolve version that must import it, e.g. '19.1' — stamps ProjectVersion down from the template's Resolve-21 capture. Omit for 21+ hosts."),
+});
+
+/** Rewrite version stamps across every XML entry of a JSZip; returns patch counts. */
+async function applyVersionStamps(zip, targetPV, appVer) {
+  const out = new JSZip();
+  let elementPatches = 0;
+  let stampPatches = 0;
+  const jobs = [];
+  zip.forEach((path, e) => {
+    if (e.dir) return;
+    jobs.push(
+      (async () => {
+        if (!path.endsWith('.xml')) {
+          out.file(path, await e.async('nodebuffer'));
+          return;
+        }
+        let xml = await e.async('string');
+        xml = xml.replace(/<ProjectVersion>\d+<\/ProjectVersion>/g, () => {
+          elementPatches += 1;
+          return `<ProjectVersion>${targetPV}</ProjectVersion>`;
+        });
+        xml = xml.replace(/DbAppVer="[^"]*" DbPrjVer="[^"]*"/g, () => {
+          stampPatches += 1;
+          return `DbAppVer="${appVer}" DbPrjVer="${targetPV}"`;
+        });
+        out.file(path, xml);
+      })(),
+    );
+  });
+  await Promise.all(jobs);
+  return { out, elementPatches, stampPatches };
+}
 const injectIntoDrpSchema = z.object({
   drtPath: z.string().describe('Source .drt'),
   drpPath: z.string().describe('Target.drp to inject into'),
@@ -93,7 +135,7 @@ function requirePathArg(args, key, action) {
 export const drtTool = {
   name: 'drt',
   description:
-    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
+    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: assemble (spec → IMPORTABLE native-schema .drt via template-spliced real structures; pass targetAppVersion e.g. \'19.1\' for pre-21 hosts), parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
   async handler({ action, args }) {
     if (action === 'parse') {
       const p = parseSchema.parse(requirePathArg(args, 'drtPath', 'parse'));
@@ -148,6 +190,55 @@ export const drtTool = {
       await fs.writeFile(p.outputPath, outBuf);
       return { outputPath: p.outputPath, bytes: outBuf.length, seqContainersInjected: injected, projectFolder };
     }
+    if (action === 'assemble') {
+      const p = assembleSchema.parse(args);
+      // Native-schema authoring: template-spliced real Resolve structures
+      // (drp-format assembleTimeline), which ImportTimelineFromFile accepts —
+      // unlike drt.author's flat template. Measured live on Studio 19.1.3.7:
+      // assembled + stamped to the host's ProjectVersion imports with every
+      // element intact.
+      const { assembleTimeline } = drp();
+      // The template GENERATION must match the target host: a Resolve-21
+      // template stamped down imports on 19 but renders BLACK (measured) —
+      // the stamp clears the gate, not the blob semantics.
+      const spec = { ...p.spec };
+      if (spec.templateVersion === undefined && p.targetAppVersion !== undefined) {
+        spec.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;
+      }
+      const { buffer, timelineName, startFrame, mediaDescriptor } = await assembleTimeline(spec);
+      let outBuf = buffer;
+      let stamped = null;
+      if (p.targetAppVersion !== undefined) {
+        const targetPV = resolveTargetProjectVersion({ targetAppVersion: p.targetAppVersion });
+        const appVer = `${p.targetAppVersion}${'.0'.repeat(Math.max(0, 4 - String(p.targetAppVersion).split('.').length))}`;
+        const zip = await JSZip.loadAsync(buffer);
+        const { out, elementPatches, stampPatches } = await applyVersionStamps(zip, targetPV, appVer);
+        outBuf = await out.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+        stamped = { targetProjectVersion: targetPV, elementPatches, stampPatches };
+      }
+      await fs.writeFile(p.outputPath, outBuf);
+      return {
+        outputPath: p.outputPath,
+        bytes: outBuf.length,
+        timelineName,
+        startFrame,
+        stamped,
+        templateVersion: spec.templateVersion ?? 21,
+        mediaDescriptor: mediaDescriptor ?? 'none',
+        ...(mediaDescriptor === 'repoint-fallback'
+          ? {
+              warning:
+                'No native media template cached for this file — the archive imports and reads back ' +
+                'correctly but its media may not RENDER (black frames / "Full resolution media not ' +
+                'found"). Run media_pool.capture_media_template(media_path) once with Resolve open, ' +
+                'then re-assemble for a render-verified transplant.',
+            }
+          : {}),
+        note:
+          'Import with timeline.import_timeline_checked — the imported timeline is named after the FILE. ' +
+          'On a host older than Resolve 21, pass targetAppVersion or the version gate refuses the archive.',
+      };
+    }
     if (action === 'extract_from_drp') {
       const p = extractFromDrpSchema.parse(args);
       const drpZip = await JSZip.loadAsync(await fs.readFile(p.drpPath));
@@ -156,16 +247,37 @@ export const drtTool = {
       if (idx >= seqEntries.length) {
         return { error: `timelineIndex ${idx} out of range (${seqEntries.length} SeqContainers)` };
       }
-      const xml = await drpZip.file(seqEntries[idx]).async('string');
+      // The importable-.drt recipe, measured by bisection on Studio 19.1.3.7:
+      // a .drt IS a .drp that ImportTimelineFromFile accepts. project.xml and
+      // MediaPool/ are REQUIRED (the Sm2Sequence/Sm2Timeline objects live in
+      // MpFolder.xml); the SeqContainer must keep its ORIGINAL uuid path —
+      // renaming it imports an EMPTY timeline with no error; Gallery.xml is
+      // droppable. Other timelines' MpFolder blocks must go too, or each
+      // arrives as a ghost empty timeline (matched via the container tracks'
+      // <Sequence> DbId, which appears inside exactly one Sm2MpTimelineClip).
+      const keepEntry = seqEntries[idx];
+      const keepXml = await drpZip.file(keepEntry).async('string');
+      const keepSeqIds = [...keepXml.matchAll(/<Sequence>([0-9a-f-]{36})<\/Sequence>/g)].map((m) => m[1]);
       const out = new JSZip();
-      out.file('Primary1/SeqContainer1.xml', xml);
-      // ImportTimelineFromFile refuses a .drt without project.xml (measured
-      // by bisection on Studio 19.1.3.7), so carry the source's over.
-      const projectEntry = Object.keys(drpZip.files).find(
-        (n) => n === 'project.xml' || n.endsWith('/project.xml'),
-      );
-      if (projectEntry) {
-        out.file('project.xml', await drpZip.file(projectEntry).async('string'));
+      let droppedTimelines = 0;
+      for (const name of Object.keys(drpZip.files)) {
+        const entry = drpZip.files[name];
+        if (entry.dir) continue;
+        if (name === 'Gallery.xml') continue;
+        const isSeq = seqEntries.includes(name);
+        if (isSeq && name !== keepEntry) continue;
+        let content = await entry.async(name.endsWith('.xml') ? 'string' : 'nodebuffer');
+        if (name.endsWith('MpFolder.xml') && seqEntries.length > 1) {
+          content = content.replace(
+            /<Element>\s*<Sm2MpTimelineClip DbId="[^"]+">(?:(?!<\/Sm2MpTimelineClip>)[\s\S])*?<\/Sm2MpTimelineClip>\s*<\/Element>/g,
+            (block) => {
+              if (keepSeqIds.some((id) => block.includes(id))) return block;
+              droppedTimelines += 1;
+              return '';
+            },
+          );
+        }
+        out.file(name, content);
       }
       out.file(
         'metadata.json',
@@ -173,7 +285,8 @@ export const drtTool = {
           {
             source: 'extract_from_drp',
             sourceDrp: p.drpPath,
-            sourceSeqContainer: seqEntries[idx],
+            sourceSeqContainer: keepEntry,
+            droppedTimelines,
             exportedFrom: 'davinci-resolve-advanced-mcp drt.extract_from_drp',
           },
           null,
@@ -182,7 +295,13 @@ export const drtTool = {
       );
       const outBuf = await out.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
       await fs.writeFile(p.outputPath, outBuf);
-      return { outputPath: p.outputPath, bytes: outBuf.length, sourceSeqContainer: seqEntries[idx] };
+      return {
+        outputPath: p.outputPath,
+        bytes: outBuf.length,
+        sourceSeqContainer: keepEntry,
+        droppedTimelines,
+        note: 'The imported timeline is named after the FILE. Source must be a SAVED project export — ExportProject snapshots the saved DB state, so unsaved edits are absent.',
+      };
     }
     if (action === 'downgrade') {
       const p = downgradeSchema.parse(args);

package/resolve-advanced/server/tools/project_db.mjs

@@ -19,7 +19,17 @@
 
 import { z } from 'zod';
 import { createRequire } from 'node:module';
-import { resolveDbPath, openGuarded, backup, requireClosed } from '../db-patch.mjs';
+import { resolveDbPath as _resolveDbPathRaw, responsiveRoots, openGuarded, backup, requireClosed } from '../db-patch.mjs';
+
+// projectName discovery walks library roots that macOS can render UNRESPONSIVE
+// (measured: a hung Lite sandbox container froze every lookup). Probe the
+// roots with a deadline first and search only the ones that answer; the
+// not-found error then names any skipped root.
+async function resolveDbPath(p) {
+  if (p.projectDb || !p.projectName) return _resolveDbPathRaw(p);
+  const { roots, skipped } = await responsiveRoots();
+  return _resolveDbPathRaw({ ...p, roots, skippedRoots: skipped });
+}
 
 const require = createRequire(import.meta.url);
 
@@ -96,7 +106,7 @@ export const projectDbTool = {
   async handler({ action, args }) {
     if (action === 'list_folders') {
       const p = listFoldersSchema.parse(args);
-      const db = openGuarded(resolveDbPath(p), { table: 'Sm2MpFolder', column: 'Name' });
+      const db = openGuarded(await resolveDbPath(p), { table: 'Sm2MpFolder', column: 'Name' });
       try {
         return { folders: db.prepare('SELECT Name, ColorTag FROM Sm2MpFolder ORDER BY Name').all() };
       } finally {
@@ -106,7 +116,7 @@ export const projectDbTool = {
     if (action === 'rename_folder') {
       const p = renameFolderSchema.parse(args);
       requireClosed(p);
-      const dbPath = resolveDbPath(p);
+      const dbPath = await resolveDbPath(p);
       const bak = backup(dbPath);
       const db = openGuarded(dbPath, { writable: true, table: 'Sm2MpFolder', column: 'Name' });
       try {
@@ -121,7 +131,7 @@ export const projectDbTool = {
     if (action === 'set_folder_color') {
       const p = folderColorSchema.parse(args);
       requireClosed(p);
-      const dbPath = resolveDbPath(p);
+      const dbPath = await resolveDbPath(p);
       const bak = backup(dbPath);
       const db = openGuarded(dbPath, { writable: true, table: 'Sm2MpFolder', column: 'ColorTag' });
       try {
@@ -135,7 +145,7 @@ export const projectDbTool = {
     }
     if (action === 'list_clips') {
       const p = listClipsSchema.parse(args);
-      const db = openGuarded(resolveDbPath(p), { table: 'Sm2MpMedia', column: 'MarkIn' });
+      const db = openGuarded(await resolveDbPath(p), { table: 'Sm2MpMedia', column: 'MarkIn' });
       try {
         return { clips: db.prepare('SELECT Name, MarkIn, MarkOut FROM Sm2MpMedia ORDER BY Name LIMIT 500').all() };
       } finally {
@@ -146,7 +156,7 @@ export const projectDbTool = {
       const p = clipMarksSchema.parse(args);
       requireClosed(p);
       if (p.markIn == null && p.markOut == null) throw new Error('provide markIn and/or markOut');
-      const dbPath = resolveDbPath(p);
+      const dbPath = await resolveDbPath(p);
       const bak = backup(dbPath);
       const db = openGuarded(dbPath, { writable: true, table: 'Sm2MpMedia', column: 'MarkIn' });
       try {
@@ -163,7 +173,7 @@ export const projectDbTool = {
       const p = relayoutSchema.parse(args);
       const layout = require('../../vendor/drx-codec/node-layout.js');
       const layoutOpts = { originX: p.originX, originY: p.originY, spacingX: p.spacingX };
-      const dbPath = resolveDbPath(p);
+      const dbPath = await resolveDbPath(p);
       const write = !p.dryRun;
       if (write) requireClosed(p);
       const bak = write ? backup(dbPath) : null;
@@ -228,7 +238,7 @@ export const projectDbTool = {
     if (action === 'list_subtitle_styles') {
       const p = listSubtitleStylesSchema.parse(args);
       const style = require('../../vendor/drp-format/subtitle-style.js');
-      const db = openGuarded(resolveDbPath(p), { table: 'Sm2TiTrack', column: 'FieldsBlob' });
+      const db = openGuarded(await resolveDbPath(p), { table: 'Sm2TiTrack', column: 'FieldsBlob' });
       try {
         const counts = new Map();
         const tracks = [];
@@ -281,7 +291,7 @@ export const projectDbTool = {
 
       const write = !p.dryRun;
       if (write) requireClosed(p);
-      const dbPath = resolveDbPath(p);
+      const dbPath = await resolveDbPath(p);
       const bak = write ? backup(dbPath) : null;
       const db = openGuarded(dbPath, { writable: write, table: 'Sm2TiTrack', column: 'FieldsBlob' });
       try {

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -21,18 +21,59 @@
  * @module drp-format/assemble-timeline
  */
 
-const { createEmptyProject } = require('./author-project');
+const { createEmptyProject, addMediaClip, DEFAULT_START_FRAME } = require('./author-project');
+const { loadMediaTemplate, transplantMediaElement } = require('./media-template-cache');
+const JSZip = require('jszip');
+const { cutSourceIntoClips } = require('./cut-media');
 const { placeFusionTitle } = require('./place-fusion-title');
 const { placeGenerator } = require('./place-generator');
 const { placeTransition } = require('./place-transition');
 
 async function assembleTimeline(spec = {}) {
-  const { timelineName, elements = [], transitions = [] } = spec;
+  const { timelineName, elements = [], transitions = [], media, templateVersion } = spec;
   if (!Array.isArray(elements)) throw new TypeError('assembleTimeline: elements must be an array');
   if (!Array.isArray(transitions)) throw new TypeError('assembleTimeline: transitions must be an array');
 
-  const { buffer: base, timelineName: tlName, startFrame } = await createEmptyProject({ timelineName });
-  let buffer = base;
+  let base;
+  if (media) {
+    // Media authoring: ONE source file, cut into N placements — the template
+    // media pool holds one media entry, so multi-source is refused honestly
+    // rather than half-built.
+    if (Array.isArray(media)) {
+      throw new TypeError('assembleTimeline: media must be a single {mediaFilePath, spec, cuts} object — multi-source authoring is not supported yet');
+    }
+    const { mediaFilePath, spec: mediaSpec, cuts } = media;
+    base = await addMediaClip({ mediaFile: mediaFilePath, spec: mediaSpec, timelineName, templateVersion });
+    base.startFrame = DEFAULT_START_FRAME;
+    if (Array.isArray(cuts) && cuts.length) {
+      // Placement guards, loudly: clips before the timeline origin are
+      // DROPPED by Resolve on import with no error, and a source range past
+      // the media's end reads back as a truncated clip.
+      cuts.forEach((cut, i) => {
+        if (cut.startFrame < DEFAULT_START_FRAME) {
+          throw new RangeError(
+            `assembleTimeline: media.cuts[${i}].startFrame ${cut.startFrame} is before the timeline origin ${DEFAULT_START_FRAME} — Resolve silently drops it on import`,
+          );
+        }
+        if (mediaSpec && Number.isFinite(mediaSpec.frameCount) && Number.isFinite(mediaSpec.fps)) {
+          // srcIn/duration are TIMELINE frames (24fps template); the media's
+          // extent converts: frameCount / mediaFps × 24.
+          const maxTimelineFrames = Math.floor((mediaSpec.frameCount / mediaSpec.fps) * 24);
+          if ((cut.srcIn ?? 0) + cut.durationFrames > maxTimelineFrames) {
+            throw new RangeError(
+              `assembleTimeline: media.cuts[${i}] reads past the media's end — (srcIn ?? 0) + durationFrames exceeds ${maxTimelineFrames} timeline frames (media ${mediaSpec.frameCount} frames @ ${mediaSpec.fps} fps on the 24fps template timeline)`,
+            );
+          }
+        }
+      });
+      const cutRes = await cutSourceIntoClips(base.buffer, { cuts });
+      base.buffer = cutRes.buffer;
+    }
+  } else {
+    base = await createEmptyProject({ timelineName, templateVersion });
+  }
+  const { buffer: baseBuffer, timelineName: tlName, startFrame } = base;
+  let buffer = baseBuffer;
 
   for (const [i, el] of elements.entries()) {
     if (!el || typeof el !== 'object') throw new TypeError(`assembleTimeline: elements[${i}] must be an object`);
@@ -59,7 +100,32 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
-  return { buffer, timelineName: tlName, startFrame };
+  // Native-descriptor transplant: when a live-captured media template exists
+  // for this file, swap the pool media element and rewire MediaRefs — the
+  // only measured way an authored timeline's media actually RENDERS (the
+  // repoint fallback imports and reads back fine but the render engine
+  // refuses or paints black; see media-template-cache).
+  let mediaDescriptor = 'none';
+  if (media && media.mediaFilePath) {
+    const cached = loadMediaTemplate(media.mediaFilePath);
+    if (cached) {
+      const zip = await JSZip.loadAsync(buffer);
+      const mpPath = 'MediaPool/Master/MpFolder.xml';
+      const seqNames = Object.keys(zip.files).filter((n) => /SeqContainer\/.+\.xml$/.test(n) || /\/SeqContainer\d*\.xml$/.test(n));
+      const mpXml = await zip.file(mpPath).async('string');
+      const seqXmls = [];
+      for (const n of seqNames) seqXmls.push(await zip.file(n).async('string'));
+      const res = transplantMediaElement(mpXml, seqXmls, cached);
+      zip.file(mpPath, res.mpXml);
+      seqNames.forEach((n, i) => zip.file(n, res.seqXmls[i]));
+      buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+      mediaDescriptor = 'native-transplant';
+    } else {
+      mediaDescriptor = 'repoint-fallback';
+    }
+  }
+
+  return { buffer, timelineName: tlName, startFrame, mediaDescriptor };
 }
 
 module.exports = { assembleTimeline };