davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/server/grade-body-patch.mjs

@@ -0,0 +1,246 @@
+/**
+ * grade-body-patch — surgically set/clear a node's LABEL (field F6) or COLOR (field F15) inside a DRX
+ * grade Body, WITHOUT going through the lossy generator. Node convention/provenance spec (2026-06-22).
+ *
+ * Why surgical: the drx generator only re-emits primaries (functional test: it drops Color Warper /
+ * curves / windows / keyframes on re-encode). So to change a label/color we must edit the COMPRESSED
+ * Body in place: decompress → byte-copy every untouched field verbatim, splice only the F6/F15 string,
+ * fix the enclosing length prefixes → recompress. Everything other than the edited string stays
+ * byte-identical (lossless), the same philosophy as the offline-ref / reel-name DB patches.
+ *
+ * Body format: [0x81] + zstd(protobuf). Node tree: root → F1 → F7[] (nodes). Node fields: F6 = label
+ * (string), F15 = color (string "ClipColor<Name>"). Absent F6/F15 = no label / no color.
+ *
+ * patchGradeBody(bodyHex, nodeIndex, { label, color }):
+ * label/color: undefined = leave unchanged · null = clear (remove the field) · string = set.
+ * color "Blue" is written as "ClipColorBlue"; reading strips the prefix (see drx-parser node.color).
+ */
+
+import * as fzstd from 'fzstd';
+import nodeZlib from 'node:zlib';
+import zstdCodecPkg from 'zstd-codec';
+import parserPkg from '../vendor/drx-codec/drx-parser.js';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { NODE_LUT_REF } = require('../vendor/drx-parameters');
+const { ProtobufParser } = parserPkg;
+const { ZstdCodec } = zstdCodecPkg;
+
+const HAS_NATIVE_ZSTD = typeof nodeZlib.zstdCompressSync === 'function';
+
+// ── varint / field encoders ─────────────────────────────────────────────────
+function encodeVarint(n) {
+  const out = [];
+  let v = n >>> 0 === n ? n : Number(n);
+  v = Math.trunc(v);
+  do {
+    let b = v & 0x7f;
+    v = Math.floor(v / 128);
+    if (v > 0) b |= 0x80;
+    out.push(b);
+  } while (v > 0);
+  return Buffer.from(out);
+}
+function encodeLenDelimField(fieldNum, content) {
+  const tag = (fieldNum << 3) | 2;
+  return Buffer.concat([encodeVarint(tag), encodeVarint(content.length), content]);
+}
+
+// ── byte-range rebuild of a protobuf container ───────────────────────────────
+// fields = a ProtobufParser._fields array (in wire order, each with.pos relative to `content`).
+// replaceMap: Map<fieldEntry, Buffer> — emit these bytes instead of the field's original range.
+// removeFieldNums: Set<number> — drop these fields entirely. appends: extra field Buffers at the end.
+function rebuildContainer(content, fields, { replaceMap = null, removeFieldNums = null, appends = [] } = {}) {
+  const parts = [];
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i];
+    const start = f.pos;
+    const end = i + 1 < fields.length ? fields[i + 1].pos : content.length;
+    if (removeFieldNums && removeFieldNums.has(f.fieldNum)) continue;
+    if (replaceMap && replaceMap.has(f)) parts.push(replaceMap.get(f));
+    else parts.push(content.subarray(start, end));
+  }
+  for (const a of appends) parts.push(a);
+  return Buffer.concat(parts);
+}
+
+// Rebuild a node's content, inserting/replacing fields in ASCENDING field-number order. CRITICAL: Resolve
+// writes node fields sorted by field number (F1 F2 F4 F5 F6 F7 F8 F9 F10 F12 F15) and its loader reads the
+// label (F6) from its canonical slot (between F5 and F7) — appending F6 at the end means Resolve never sees
+// it. So we emit a field-number-ordered merge of the kept fields + the new ones (RE'd live 2026-06-22).
+function rebuildNodeSorted(content, fields, removeFieldNums, newFields) {
+  const items = [];
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i];
+    if (removeFieldNums.has(f.fieldNum)) continue;
+    const end = i + 1 < fields.length ? fields[i + 1].pos : content.length;
+    items.push({ fieldNum: f.fieldNum, buf: content.subarray(f.pos, end) });
+  }
+  for (const nf of newFields) items.push(nf); // {fieldNum, buf (tag+len+content)}
+  items.sort((a, b) => a.fieldNum - b.fieldNum); // stable (ES2019+) → repeats keep relative order
+  return Buffer.concat(items.map((x) => x.buf));
+}
+
+function asBuf(x) {
+  return Buffer.isBuffer(x) ? x : Buffer.from(x);
+}
+function parseContent(buf) {
+  return new ProtobufParser(buf).parse(12);
+}
+
+// ── zstd compress (native Node 22+ → zstd-codec WASM fallback, matching the generator) ──
+let _wasm = null;
+function getWasm() {
+  if (_wasm) return Promise.resolve(_wasm);
+  return new Promise((resolve) => {
+    ZstdCodec.run((z) => {
+      _wasm = new z.Simple();
+      resolve(_wasm);
+    });
+  });
+}
+async function compress(buf) {
+  if (HAS_NATIVE_ZSTD) return nodeZlib.zstdCompressSync(buf);
+  const w = await getWasm();
+  return Buffer.from(w.compress(new Uint8Array(buf)));
+}
+export function decompressBody(bodyHex) {
+  const buf = Buffer.from(bodyHex, 'hex');
+  if (buf[0] !== 0x81) throw new Error('not a DRX grade Body (missing 0x81 prefix)');
+  return Buffer.from(fzstd.decompress(new Uint8Array(buf.subarray(1))));
+}
+
+/**
+ * Set/clear a node's label (F6) and/or color (F15) in a grade Body. Returns the new Body hex.
+ * Everything except the edited string(s) is preserved byte-for-byte in the decompressed protobuf.
+ */
+export async function patchGradeBody(bodyHex, nodeIndex, { label, color } = {}) {
+  const dec = decompressBody(bodyHex);
+  const root = parseContent(dec);
+  const f1Entry = root._fields.find((f) => f.fieldNum === 1 && f.wireType === 2);
+  if (!f1Entry) throw new Error('grade Body has no F1 (node container)');
+  const f1Content = asBuf(f1Entry.rawValue);
+  const f1Parsed = parseContent(f1Content);
+  const f7Entries = f1Parsed._fields.filter((f) => f.fieldNum === 7 && f.wireType === 2);
+  if (nodeIndex < 0 || nodeIndex >= f7Entries.length) throw new Error(`node ${nodeIndex} out of range (have ${f7Entries.length})`);
+  const nodeEntry = f7Entries[nodeIndex];
+  const nodeContent = asBuf(nodeEntry.rawValue);
+  const nodeParsed = parseContent(nodeContent);
+
+  const removeFieldNums = new Set();
+  const newFields = [];
+  if (label !== undefined) {
+    removeFieldNums.add(6);
+    if (label !== null) newFields.push({ fieldNum: 6, buf: encodeLenDelimField(6, Buffer.from(String(label), 'utf8')) });
+  }
+  if (color !== undefined) {
+    removeFieldNums.add(15);
+    if (color !== null) newFields.push({ fieldNum: 15, buf: encodeLenDelimField(15, Buffer.from(`ClipColor${color}`, 'utf8')) });
+  }
+
+  // Insert F6/F15 in canonical (ascending field-number) order — Resolve's loader is position-sensitive.
+  const newNodeContent = rebuildNodeSorted(nodeContent, nodeParsed._fields, removeFieldNums, newFields);
+  const newF7 = encodeLenDelimField(7, newNodeContent);
+  const newF1Content = rebuildContainer(f1Content, f1Parsed._fields, { replaceMap: new Map([[nodeEntry, newF7]]) });
+  const newF1 = encodeLenDelimField(1, newF1Content);
+  const newRoot = rebuildContainer(dec, root._fields, { replaceMap: new Map([[f1Entry, newF1]]) });
+
+  const compressed = await compress(newRoot);
+  return '81' + Buffer.from(compressed).toString('hex');
+}
+
+// ── LUT-node WRITE path (P3, RE'd 2026-07-01 from the p5-1 fixtures) ─────────────
+// A node's F9 holds [F1 corrector?][F2 5-byte tail]. A LUT attaches an F1 corrector whose nested
+// params carry SLOT_META (varint) + LUT_PATH (F5 string). Byte-exact reconstruction of the captured
+// with-LUT fixture confirmed the encoding (see lut-apply round-trip test). Constant wire shape:
+//   corrector = F1{ 08 01, 18 01, F6{ F2{ 08 01, F3{SLOT_META param}, F3{LUT_PATH param} } } }
+//   SLOT_META param = 08 <id> 12{ 10 <slot> }        (value envelope F2 = varint slot)
+//   LUT_PATH  param = 08 <id> 12{ 2a <len> <path> }  (value envelope F5 = string)
+function buildLutCorrector(lutPath, slotMeta) {
+  const slotEnv = encodeLenDelimField(2, Buffer.concat([Buffer.from([0x10]), encodeVarint(slotMeta)]));
+  const slotParam = Buffer.concat([Buffer.from([0x08]), encodeVarint(NODE_LUT_REF.SLOT_META), slotEnv]);
+  const pathEnv = encodeLenDelimField(2, encodeLenDelimField(5, Buffer.from(lutPath, 'utf8')));
+  const pathParam = Buffer.concat([Buffer.from([0x08]), encodeVarint(NODE_LUT_REF.LUT_PATH), pathEnv]);
+  const paramsList = Buffer.concat([Buffer.from([0x08, 0x01]), encodeLenDelimField(3, slotParam), encodeLenDelimField(3, pathParam)]);
+  const f6 = encodeLenDelimField(6, encodeLenDelimField(2, paramsList));
+  const corrector = Buffer.concat([Buffer.from([0x08, 0x01, 0x18, 0x01]), f6]);
+  return encodeLenDelimField(1, corrector); // the F9-inner F1 field bytes
+}
+
+const DEFAULT_F9_TAIL = Buffer.from('12050304050612', 'hex'); // the F2 common tail all nodes carry
+
+/**
+ * Inject a per-node LUT reference (LUT_PATH + SLOT_META) into a grade Body, replacing any existing
+ * LUT corrector on that node. Returns the new Body hex. Everything else is preserved byte-for-byte.
+ * @param {string} bodyHex
+ * @param {number} nodeIndex
+ * @param {{lutPath:string, slotMeta?:number}} opts
+ */
+export async function injectNodeLut(bodyHex, nodeIndex, { lutPath, slotMeta = 6 } = {}) {
+  if (!lutPath || typeof lutPath !== 'string') throw new Error('injectNodeLut: lutPath (string) required');
+  const dec = decompressBody(bodyHex);
+  const root = parseContent(dec);
+  const f1Entry = root._fields.find((f) => f.fieldNum === 1 && f.wireType === 2);
+  if (!f1Entry) throw new Error('grade Body has no F1 (node container)');
+  const f1Content = asBuf(f1Entry.rawValue);
+  const f1Parsed = parseContent(f1Content);
+  const f7Entries = f1Parsed._fields.filter((f) => f.fieldNum === 7 && f.wireType === 2);
+  if (nodeIndex < 0 || nodeIndex >= f7Entries.length) throw new Error(`node ${nodeIndex} out of range (have ${f7Entries.length})`);
+  const nodeEntry = f7Entries[nodeIndex];
+  const nodeContent = asBuf(nodeEntry.rawValue);
+  const nodeParsed = parseContent(nodeContent);
+
+  const corrector = buildLutCorrector(lutPath, slotMeta);
+  // Keep the existing F9 TAIL (F2), drop any prior F1 LUT corrector, prepend the new one.
+  const f9Entry = nodeParsed._fields.find((f) => f.fieldNum === 9 && f.wireType === 2);
+  let tail = DEFAULT_F9_TAIL;
+  if (f9Entry) {
+    const f9Content = asBuf(f9Entry.rawValue);
+    const f9Parsed = parseContent(f9Content);
+    tail = rebuildContainer(f9Content, f9Parsed._fields, { removeFieldNums: new Set([1]) });
+  }
+  const newF9 = encodeLenDelimField(9, Buffer.concat([corrector, tail]));
+  const newNodeContent = rebuildNodeSorted(nodeContent, nodeParsed._fields, new Set([9]), [{ fieldNum: 9, buf: newF9 }]);
+  const newF7 = encodeLenDelimField(7, newNodeContent);
+  const newF1Content = rebuildContainer(f1Content, f1Parsed._fields, { replaceMap: new Map([[nodeEntry, newF7]]) });
+  const newF1 = encodeLenDelimField(1, newF1Content);
+  const newRoot = rebuildContainer(dec, root._fields, { replaceMap: new Map([[f1Entry, newF1]]) });
+  const compressed = await compress(newRoot);
+  return '81' + Buffer.from(compressed).toString('hex');
+}
+
+// Read a node's label (F6) + color (F15) straight from a Body — used for read-back verification.
+export function readNodeMeta(bodyHex, nodeIndex = 0) {
+  const dec = decompressBody(bodyHex);
+  const root = parseContent(dec);
+  const f1Entry = root._fields.find((f) => f.fieldNum === 1 && f.wireType === 2);
+  if (!f1Entry) return null;
+  const f1Parsed = parseContent(asBuf(f1Entry.rawValue));
+  const f7 = f1Parsed._fields.filter((f) => f.fieldNum === 7 && f.wireType === 2)[nodeIndex];
+  if (!f7) return null;
+  const node = parseContent(asBuf(f7.rawValue));
+  const str = (fn) => {
+    const e = node._fields.find((f) => f.fieldNum === fn && f.wireType === 2);
+    return e ? asBuf(e.rawValue).toString('utf8') : null;
+  };
+  const label = str(6);
+  const rawColor = str(15);
+  return { label: label || null, color: rawColor ? rawColor.replace(/^ClipColor/, '') : null };
+}
+
+// Exposed for tests: the field-number order of a node (must stay ascending — Resolve reads positionally).
+export function _nodeFieldOrder(bodyHex, nodeIndex = 0) {
+  const dec = decompressBody(bodyHex);
+  const root = parseContent(dec);
+  const f1 = parseContent(asBuf(root._fields.find((f) => f.fieldNum === 1 && f.wireType === 2).rawValue));
+  const node = parseContent(asBuf(f1._fields.filter((f) => f.fieldNum === 7 && f.wireType === 2)[nodeIndex].rawValue));
+  return node._fields.map((f) => f.fieldNum);
+}
+
+// Exposed for the faithful-round-trip self-test (no-op rebuild must reproduce the decompressed bytes).
+export function _noopRebuild(bodyHex) {
+  const dec = decompressBody(bodyHex);
+  const root = parseContent(dec);
+  return rebuildContainer(dec, root._fields, {});
+}

package/resolve-advanced/server/grade-transfer.mjs

@@ -0,0 +1,66 @@
+/**
+ * Lossless grade transfer — Route A copy (C3 `grade_transfer`).
+ *
+ * Carry an EXACT grade from a source onto an apply-ready .drx, WITHOUT decoding and
+ * re-encoding (decode→re-encode is lossy for OFX/ResolveFX and the uncalibrated tail).
+ * We copy the raw <Body> blob verbatim and re-wrap it in the Gallery::GyStill envelope
+ * Resolve's ApplyGradeFromDRX actually applies — so the transfer is byte-faithful.
+ *
+ * Sources:
+ * { drpPath, group, which?:'post'|'pre' } — a colour-group look from an exported .drp
+ * (the Route A workflow: read the season host look, transfer to this episode).
+ * { drxPath } | { content } — re-wrap an existing .drx's grade body.
+ *
+ * GUARD: the wrapped body is parsed and must decode to ≥1 node — a transfer that yields
+ * an empty grade is refused, not shipped (the silent-no-op bug class).
+ * LOCAL & deterministic; emits the .drx. APPLY (ApplyGradeFromDRX) is the caller's job.
+ */
+import fs from 'node:fs';
+import { readProjectXml, groupSegment, groupBodies } from './group-grade-read.mjs';
+import { drxEnvelope } from './tools/color_trace.mjs';
+import { drxTool } from './tools/drx.mjs';
+
+/** Count nodes a raw body decodes to, via the parse-safe Resolve_Color_Exchange envelope. */
+async function bodyNodeCount(bodyHex) {
+  const content = `<?xml version="1.0" encoding="UTF-8"?>\n<Resolve_Color_Exchange><Label>assert</Label><Width>1920</Width><Height>1080</Height><Body>${bodyHex}</Body></Resolve_Color_Exchange>`;
+  const r = await drxTool.handler({ action: 'parse', args: { content } });
+  return (r.nodes || []).length;
+}
+
+/**
+ * @param {{drpPath?:string, group?:string, which?:'post'|'pre', drxPath?:string, content?:string}} source
+ * @param {{outPath?:string, label?:string}} opts
+ * @returns {Promise<{outPath?:string, content:string, nodeCount:number, bodyBytes:number, label:string, source:string}>}
+ */
+export async function transferGrade(source = {}, opts = {}) {
+  let bodyHex, srcLabel, srcKind;
+  if (source.drpPath) {
+    if (!source.group) throw new Error('source.group required with drpPath');
+    const xml = readProjectXml(source.drpPath);
+    const seg = groupSegment(xml, source.group);
+    if (!seg) throw new Error(`group '${source.group}' not found in ${source.drpPath}`);
+    const bodies = groupBodies(seg);
+    if (!bodies.length) throw new Error(`group '${source.group}' has no grade <Body>`);
+    const which = source.which || 'post';
+    bodyHex = which === 'pre' ? bodies[0] : bodies[bodies.length - 1];
+    srcLabel = `${source.group} ${which}`;
+    srcKind = `drp:${source.group}:${which}`;
+  } else if (source.drxPath || source.content) {
+    const xml = source.content || fs.readFileSync(source.drxPath, 'utf8');
+    const m = xml.match(/<Body>([0-9a-fA-F]+)<\/Body>/);
+    if (!m) throw new Error('no <Body> blob in source.drx');
+    bodyHex = m[1];
+    srcLabel = source.drxPath ? source.drxPath.split('/').pop() : 'drx';
+    srcKind = `drx:${srcLabel}`;
+  } else {
+    throw new Error('provide source.drpPath+group, or source.drxPath/content');
+  }
+
+  const nodeCount = await bodyNodeCount(bodyHex);
+  if (nodeCount === 0) throw new Error(`grade_transfer refused: source '${srcKind}' decodes to 0 nodes (empty grade)`);
+
+  const label = opts.label || srcLabel;
+  const content = drxEnvelope(label, bodyHex);
+  if (opts.outPath) fs.writeFileSync(opts.outPath, content);
+  return { outPath: opts.outPath, content, nodeCount, bodyBytes: bodyHex.length / 2, label, source: srcKind };
+}

package/resolve-advanced/server/group-grade-read.mjs

@@ -0,0 +1,137 @@
+/**
+ * Color-group grade READ PATH (Route A) — decode a project's Color Group pre/post-clip
+ * grades from an exported .drp, OFFLINE, no Resolve required.
+ *
+ * Closes the gap noted in test/group-grade-calibration.test.mjs: a group's Pre/Post-Clip
+ * grade is stored as a standard DRX `<Body>` inside `project.xml`'s `<Sm2Group>` element —
+ * same format as a clip grade, so the existing drx-parser decodes it unchanged. The only
+ * missing piece was a READ PATH (locate the group bodies); this is it.
+ *
+ * Pipeline:.drp (zip) -> project.xml -> per-group <Body> (pre, post) -> drx-parser.parse
+ * -> flatten (LUT refs, HSL curves) -> DRX->UI scale -> compact per-node summary.
+ *
+ * Values for the calibrated native control set (primaries, log wheels, curves, HSL/RGB/3D
+ * qualifier ranges, windows, Color Warper, ColorSlice, HDR zones) are EXACT; OFX/long-tail
+ * IDs are raw (see parse().valueFidelity).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { drxTool } from './tools/drx.mjs';
+
+const require = createRequire(import.meta.url);
+const { extractDrxLutRefs } = require('../vendor/drx-codec/extract-lut-refs.js');
+const { extractHSLCurves } = require('../vendor/drx-codec/extract-hsl-curves.js');
+
+// DRX -> UI scaling (vendor/drx-parameters/DRX-VALUE-SCALING.md)
+export function scaleParam(name, v) {
+  if (typeof v !== 'number') return v;
+  const n = name.toLowerCase();
+  if (/saturation/.test(n)) return +(v * 100).toFixed(2); // %
+  if (/contrast/.test(n)) return +(v * 100).toFixed(2); // %
+  if (/(^|\.)lift/.test(n)) return +(v / 2).toFixed(4);
+  if (/(^|\.)gamma/.test(n)) return +(v / 4).toFixed(4);
+  if (/offset/.test(n)) return +(v * 2500).toFixed(2);
+  return +(+v).toFixed(4);
+}
+
+const IDENTITY_3X3 = '1,0,0,0,1,0,0,0,1';
+const isIdentity = (a) => Array.isArray(a) && a.length === 9 && a.join(',') === IDENTITY_3X3;
+const STRUCTURAL = /hslcurves|trackingblob|polygonshape|gradientwindow|nodelut|softmatrix|(^|\.)matrix$/i;
+
+export function readProjectXml(drpPath) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ggr-'));
+  const r = spawnSync('unzip', ['-o', drpPath, 'project.xml', '-d', tmp], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`unzip failed for ${drpPath}: ${(r.stderr || '').slice(-200)}`);
+  const xml = fs.readFileSync(path.join(tmp, 'project.xml'), 'utf8');
+  try {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+  return xml;
+}
+
+/** All color-group names present in the project (from <Sm2Group><Name>…). */
+export function listGroupNames(xml) {
+  const names = [];
+  for (const m of xml.matchAll(/<Sm2Group\b[\s\S]*?<Name>([^<]+)<\/Name>/g)) names.push(m[1]);
+  return [...new Set(names)];
+}
+
+export function groupSegment(xml, name) {
+  const j = xml.indexOf(`<Name>${name}</Name>`);
+  if (j < 0) return null;
+  const start = xml.lastIndexOf('<Sm2Group', j);
+  const end = xml.indexOf('</Sm2Group>', j);
+  if (start < 0 || end < 0) return null;
+  return xml.slice(start, end + '</Sm2Group>'.length);
+}
+
+export const groupBodies = (seg) => [...seg.matchAll(/<Body>([0-9a-fA-F]+)<\/Body>/g)].map((m) => m[1]);
+
+async function decodeBody(bodyHex, label) {
+  const content = `<?xml version="1.0" encoding="UTF-8"?>\n<Resolve_Color_Exchange><Label>${label}</Label><Width>1920</Width><Height>1080</Height><Body>${bodyHex}</Body></Resolve_Color_Exchange>`;
+  let r;
+  try {
+    r = await drxTool.handler({ action: 'parse', args: { content } });
+  } catch (e) {
+    return { error: String(e.message || e), node_count: 0, nodes: [] };
+  }
+  const lutRefs = {};
+  for (const l of extractDrxLutRefs(r) || []) lutRefs[l.nodeIndex] = l.lutPath;
+  const nodes = (r.nodes || [])
+    .map((n) => {
+      const idx = n.nodeIndex ?? n.index;
+      const all = (n.correctors || []).flatMap((c) => c.parameters || []);
+      const params = {};
+      for (const p of all) {
+        if (!p.name || /^unknown/i.test(p.name) || STRUCTURAL.test(p.name)) continue;
+        if (typeof p.value === 'object') continue;
+        if (typeof p.value === 'number' && Math.abs(p.value) < 1e-6) continue;
+        params[p.name] = scaleParam(p.name, p.value);
+      }
+      let curves;
+      try {
+        const h = extractHSLCurves(all);
+        if (h) curves = Object.keys(h);
+      } catch {
+        /* ignore */
+      }
+      const win = all.find((p) => /softmatrix|polygonshape\.matrix|gradientwindow/i.test(p.name) && !isIdentity(p.value));
+      const node = { node: idx, tools: (n.correctors || []).map((c) => c.type ?? c.correctorType) };
+      if (lutRefs[idx]) node.lut = lutRefs[idx];
+      if (Object.keys(params).length) node.params = params;
+      if (curves && curves.length) node.curves = curves;
+      if (win) node.window = true;
+      return node;
+    })
+    .filter((n) => n.params || n.lut || n.curves || n.window);
+  return { node_count: (r.nodes || []).length, valueFidelity: r.valueFidelity?.level ?? null, nodes };
+}
+
+/**
+ * Decode color-group grades from a .drp.
+ * @param {string} drpPath
+ * @param {{groups?: string[], includePreClip?: boolean}} [opts]
+ * @returns {Promise<Object>} { <group>: { pre_clip?, post_clip } }
+ */
+export async function decodeGroupGrades(drpPath, opts = {}) {
+  const xml = readProjectXml(drpPath);
+  const groups = opts.groups && opts.groups.length ? opts.groups : listGroupNames(xml);
+  const out = {};
+  for (const g of groups) {
+    const seg = groupSegment(xml, g);
+    if (!seg) {
+      out[g] = { error: 'group not found' };
+      continue;
+    }
+    const bs = groupBodies(seg); // typically [pre, post]
+    out[g] = {};
+    if (bs.length >= 2 && opts.includePreClip !== false) out[g].pre_clip = await decodeBody(bs[0], `${g} pre`);
+    if (bs.length >= 1) out[g].post_clip = await decodeBody(bs[bs.length - 1], `${g} post`);
+  }
+  return out;
+}

package/resolve-advanced/server/index.mjs

@@ -0,0 +1,105 @@
+/**
+ * davinci-resolve-advanced-mcp — MCP server (stdio).
+ *
+ * The "beyond-the-API" sibling to the live Python davinci-resolve-mcp: authors
+ * and edits DaVinci Resolve files (.drp/.drt/.drx) with no Resolve running.
+ * Runs cloud or local. Tools dispatch on an `action` enum, mirroring the
+ * Python server's shape.
+ */
+
+// CRITICAL (stdio MCP): stdout is the JSON-RPC channel — any stray write
+// corrupts the protocol. Several vendored libs (e.g. drx-generator) use
+// console.log for debug output. Redirect the stdout-bound console methods to
+// stderr BEFORE anything else loads, so vendored chatter can't break the wire.
+for (const m of ['log', 'info', 'debug']) {
+  const orig = console[m].bind(console);
+  console[m] = (...a) => {
+    try {
+      process.stderr.write(a.map(String).join(' ') + '\n');
+    } catch {
+      orig(...a);
+    }
+  };
+}
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { drpTool } from './tools/drp.mjs';
+import { drtTool } from './tools/drt.mjs';
+import { drxTool } from './tools/drx.mjs';
+import { offlineRefTool } from './tools/offline_ref.mjs';
+import { fusionTool } from './tools/fusion.mjs';
+import { audioPlanTool } from './tools/audio_plan.mjs';
+import { fairlightTool } from './tools/fairlight.mjs';
+import { audioTool } from './tools/audio.mjs';
+import { conformTool } from './tools/conform.mjs';
+import { projectDbTool } from './tools/project_db.mjs';
+import { projectReadTool } from './tools/project_read.mjs';
+import { colorTraceTool } from './tools/color_trace.mjs';
+import { capabilitiesTool } from './tools/capabilities.mjs';
+import { pipelineTool } from './tools/pipeline.mjs';
+import { deliverableTool } from './tools/deliverable.mjs';
+import { mediaTool } from './tools/media.mjs';
+import { editorialTool } from './tools/editorial.mjs';
+import { provenanceTool } from './tools/provenance.mjs';
+import { logCapabilities } from './capabilities.mjs';
+
+const TOOLS = [
+  drpTool,
+  drtTool,
+  drxTool,
+  offlineRefTool,
+  fusionTool,
+  audioPlanTool,
+  fairlightTool,
+  audioTool,
+  conformTool,
+  projectDbTool,
+  projectReadTool,
+  colorTraceTool,
+  capabilitiesTool,
+  pipelineTool,
+  deliverableTool,
+  mediaTool,
+  editorialTool,
+  provenanceTool,
+];
+const NAME = 'davinci-resolve-advanced-mcp';
+const VERSION = '0.0.0-dev';
+
+const toContent = (payload) => ({ content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] });
+const toError = (err) => ({
+  isError: true,
+  content: [{ type: 'text', text: JSON.stringify({ error: err?.message || String(err) }, null, 2) }],
+});
+
+export async function startServer() {
+  const server = new McpServer({ name: NAME, version: VERSION }, { capabilities: { tools: {} } });
+
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: {
+          action: z.string().describe('Action name within this tool'),
+          args: z.object({}).passthrough().optional().describe('Action arguments'),
+        },
+      },
+      async ({ action, args }) => {
+        try {
+          return toContent(await tool.handler({ action, args: args || {} }));
+        } catch (err) {
+          return toError(err);
+        }
+      },
+    );
+  }
+
+  await server.connect(new StdioServerTransport());
+  // stdio MCP servers must never write to stdout (it's the protocol channel).
+  process.stderr.write(`[${NAME}] ready — ${TOOLS.length} tools registered\n`);
+  logCapabilities();
+}

package/resolve-advanced/server/lib.mjs

@@ -0,0 +1,84 @@
+/**
+ * Public library surface (A0) — the importable API of the Resolve-advanced engine, so a
+ * downstream application can `import { … } from 'davinci-resolve-advanced-mcp'` instead of
+ * only spawning the stdio MCP server: downstream consumers depend on THIS upstream package.
+ * The MCP server is a thin shell over these same exports.
+ *
+ * Grouping: codec (offline .drp/.drt/.drx) · grading (deterministic compute cores) ·
+ * pipeline (DB-as-truth foundation) · tools (MCP tool handlers) · mcp (stdio server entry).
+ * Publish name/registry is a separate, parked decision — this just makes the boundary
+ * explicit and testable under the current package.
+ */
+
+// ── codec — offline DaVinci file formats (no Resolve) ──────────────────────────
+export * as codec from './libs.mjs';
+
+// ── grading — deterministic, local compute cores (the C-tier catalog) ──────────
+export { measureMeanRGB, generateAssertedGainDRX, computeLevels } from './exposure-level.mjs';
+export { isSkin, measureSkinMeanRGB, computeSkinMatch } from './skin-match.mjs';
+export { measureToneRGB, computeShotMatch } from './shot-match.mjs';
+export { measurePatchMeanRGB, computeWhiteBalanceMatch } from './white-balance-match.mjs';
+export { measureBWPoints, generateAssertedAffineDRX, computeContrastNormalize } from './contrast-normalize.mjs';
+export { measureLegal, computeGamutLegal } from './gamut-legal.mjs';
+export { scopeRead, SKIN_LINE_DEG } from './scope-read.mjs';
+export { measureMeanStd, computeMatchToReference } from './match-to-reference.mjs';
+export { measureSaturation, computeSaturationMatch } from './saturation-match.mjs';
+export { measureBlackPoint, computeBlackBalance } from './black-balance.mjs';
+export { measureLumaCDF, computeToneCurve, computeToneCurveTransfer } from './tone-curve-transfer.mjs';
+export { provenanceLabel, provenanceRecord, parseProvenanceLabel, isAutoLabel, gist, TOOL_VERSIONS } from './node-provenance.mjs';
+export { deriveIntentTags, shouldExcludeFromNeutralize, INTENT_EXCLUDE_TAGS } from './shot-intent.mjs';
+export { verifyGrade } from './verify-grade.mjs';
+export { extractFrames, probeStream, assessColorspace, resolvePosition } from './extract-frames.mjs';
+export { importCDL } from './cdl-io.mjs';
+export { transferGrade } from './grade-transfer.mjs';
+export { authorLook, carryLook } from './season-look.mjs';
+export { applyLut, extractBodyHex } from './lut-apply.mjs';
+export { injectNodeLut } from './grade-body-patch.mjs';
+export { scaleParam, listGroupNames, decodeGroupGrades, readProjectXml, groupSegment, groupBodies } from './group-grade-read.mjs';
+
+// ── pipeline — DB-as-truth foundation (canonical DB, compile, readback, runner) ─
+export * as projectDb from './project-db.mjs';
+export { deepMerge, validateResolved, resolveDeliverableInherits, compileSpecs, loadYamlDir } from './spec-compile.mjs';
+export { getByPath, recordReadback, detectDrift, reconcile, driftReport } from './readback.mjs';
+export { planRun, executeStage, runAll, approveGate, markStageApplied, rerunStage, resumeRun } from './runner.mjs';
+export { descriptorSchema, CATALOG, getDescriptor, listCatalog, STAGE_PLAN } from './tool-catalog.mjs';
+export { APPLY_CONTRACT, toApplyContract } from './runner-apply-contract.mjs';
+
+// ── tools — MCP tool handlers (programmatic dispatch: tool.handler({action, args})) ─
+export { drpTool } from './tools/drp.mjs';
+export { drtTool } from './tools/drt.mjs';
+export { drxTool } from './tools/drx.mjs';
+export { conformTool } from './tools/conform.mjs';
+export { colorTraceTool } from './tools/color_trace.mjs';
+export { offlineRefTool } from './tools/offline_ref.mjs';
+export { fusionTool } from './tools/fusion.mjs';
+export { audioTool } from './tools/audio.mjs';
+export { audioPlanTool } from './tools/audio_plan.mjs';
+export { fairlightTool } from './tools/fairlight.mjs';
+export { projectDbTool } from './tools/project_db.mjs';
+export { projectReadTool } from './tools/project_read.mjs';
+export { capabilitiesTool } from './tools/capabilities.mjs';
+export { pipelineTool } from './tools/pipeline.mjs';
+export { deliverableTool } from './tools/deliverable.mjs';
+
+// ── deliverable QC (Cluster D) — compute cores ─────────────────────────
+export { checkDeliverable, deliverableQc, loudnessQc, parseEbur128, reframeBlankingCheck, conformCompleteness, reDeliveryDiff, compareRenders } from './deliverable-qc.mjs';
+export { buildManifest, reconcileManifest, checksumFile } from './render-manifest.mjs';
+export { expandDeliverable, ENTITY_DEFAULTS } from './deliverable-entities.mjs';
+export { probeMedia, ratio } from './ffprobe-media.mjs';
+
+// ── media front-end (Cluster M) — compute cores ────────────────────────
+export { mediaTool } from './tools/media.mjs';
+export { sealFiles, verifyFiles, findDupesByHash, ingestVerify, relinkManifest, renamePlan, reelNormalize, projectHygiene, turnoverPackage } from './media-ops.mjs';
+export { mediaInventory, syncByTC, tcToFrames, framesToTc } from './media-inventory.mjs';
+
+// ── editorial integrity (Cluster E) — compute cores ────────────────────
+export { editorialTool } from './tools/editorial.mjs';
+export { parseEDL, parseOTIO, parseXMEMLEvents, parseInterchange, diffChangelist, timingGuards, conformManifest, markerRoundtrip } from './editorial.mjs';
+
+// ── provenance / audit (Cluster P) — compute cores ─────────────────────
+export { provenanceTool } from './tools/provenance.mjs';
+export { galleryLineage, makeStillLabel, validateStillLabel, gradeProvenance, cdlExport, cdlDiff, revisionHistory, episodeReport } from './provenance-audit.mjs';
+
+// ── mcp — the stdio server entry (the thin shell over the above) ───────────────
+export { startServer } from './index.mjs';