davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/drp-format/__tests__/keyed-dict.test.js

@@ -0,0 +1,85 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const JSZip = require('jszip');
+const {
+  decodeKeyedDict, encodeKeyedDict, readKeyedDict, keyedDictType,
+  getKeyedValue, setKeyedValue, readAudioTracks,
+} = require('../keyed-dict');
+
+const FIXTURE = 'docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp';
+
+async function grabAll(tag) {
+  const zip = await JSZip.loadAsync(fs.readFileSync(FIXTURE));
+  const out = [];
+  for (const name of Object.keys(zip.files)) {
+    if (!name.endsWith('.xml')) continue;
+    const x = await zip.files[name].async('string');
+    const re = new RegExp(`<${tag}>([0-9a-f]+)</${tag}>`, 'g');
+    let m;
+    while ((m = re.exec(x))) out.push(m[1]);
+  }
+  return out;
+}
+
+test('decodeKeyedDict parses Geometry with typed values', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const hex = (await grabAll('Geometry'))[0];
+  const { count, entries } = decodeKeyedDict(hex);
+  assert.strictEqual(count, entries.length, 'count matches entry total');
+  const byKey = Object.fromEntries(entries.map((e) => [e.key, e]));
+  assert.strictEqual(byKey.DbType.value, 'BtGeometry');
+  // Resolution is a BYTES value [u32 0][u32 W][u32 0][u32 H] — W=352 H=262 in the canary template.
+  const res = Buffer.from(byKey.Resolution.value, 'hex');
+  assert.strictEqual(res.readUInt32BE(4), 352);
+  assert.strictEqual(res.readUInt32BE(12), 262);
+});
+
+test('decodeKeyedDict parses Time (StartFrame/NumFrames/FrameRate)', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const hex = (await grabAll('Time'))[0];
+  const byKey = Object.fromEntries(decodeKeyedDict(hex).entries.map((e) => [e.key, e]));
+  assert.strictEqual(byKey.StartFrame.value, 0);
+  assert.strictEqual(byKey.NumFrames.value, 4576);
+  assert.strictEqual(keyedDictType(hex), 'BtVideoTime');
+  // FrameRate BYTES value is [double fps LE][double 0] — 29.97 in the canary.
+  const fr = Buffer.from(byKey.FrameRate.value, 'hex');
+  assert.ok(Math.abs(fr.readDoubleLE(0) - 30000 / 1001) < 1e-6, `fps ${fr.readDoubleLE(0)}`);
+});
+
+test('encodeKeyedDict round-trips every keyed-dict blob byte-for-byte', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  // Includes the nested audio dicts (TracksBA holds a BYTES inner BtAudioTrack dict).
+  for (const tag of ['Geometry', 'Time', 'VideoMetadata', 'Proxy', 'TracksBA', 'VirtualAudioTrackBA']) {
+    for (const hex of await grabAll(tag)) {
+      const re = encodeKeyedDict(decodeKeyedDict(hex)).toString('hex');
+      assert.strictEqual(re, hex, `${tag} must round-trip exactly`);
+    }
+  }
+});
+
+test('readAudioTracks decodes BtAudioInfo config from TracksBA', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const tracks = readAudioTracks((await grabAll('TracksBA'))[0]);
+  assert.strictEqual(tracks.length, 1);
+  const tr = tracks[0];
+  assert.strictEqual(tr.sampleRate, 44100);
+  assert.strictEqual(tr.numChannels, 2);
+  assert.strictEqual(tr.codecName, 'AAC');
+  // Duration is in audio samples: 6733824 / 44100 == 152.69 s (the clip length).
+  assert.strictEqual(Math.round(Number(tr.duration) / tr.sampleRate), 153);
+});
+
+test('setKeyedValue edits a value and re-encodes', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const hex = (await grabAll('Time'))[0];
+  const edited = setKeyedValue(hex, 'NumFrames', 1234);
+  assert.strictEqual(getKeyedValue(edited, 'NumFrames'), 1234);
+  assert.strictEqual(getKeyedValue(edited, 'StartFrame'), 0, 'other keys untouched');
+});
+
+test('readKeyedDict back-compat returns [{key,value}]', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const keys = readKeyedDict((await grabAll('Time'))[0]).map((e) => e.key);
+  assert.ok(keys.includes('NumFrames'));
+});

package/resolve-advanced/vendor/drp-format/__tests__/lut-refs.test.js

@@ -0,0 +1,119 @@
+/**
+ * P5.2 — extractProjectLUTRefs unit tests.
+ *
+ * Strategy: build synthetic DRPs via buildDRP with optional LUT slots
+ * populated. Verify the extractor surfaces each slot when set, and
+ * returns empty array when none are.
+ *
+ * Real Resolve-fixture verification is deferred to the Resolve-batch
+ * session (queued in knowledge/resolve-verifications.md).
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+const drpFormat = require('..');
+
+const BASE_SPEC = {
+  projectName: 'lut-test',
+  timelines: [{
+    name: 'T1', frameRate: 24, startTimecode: '01:00:00:00', resolution: '1920x1080',
+    videoTracks: [{ clips: [{ start: 0, duration: 24, in: 0, mediaFilePath: '/m/c.mov' }] }],
+    audioTracks: [],
+  }],
+};
+
+async function buildDrpWithLuts(luts) {
+  return drpFormat.buildDRP({
+    ...BASE_SPEC,
+    projectSettings: { ...luts },
+  });
+}
+
+test('extractProjectLUTRefs: returns empty when no LUTs in project.xml', async () => {
+  const buf = await drpFormat.buildDRP(BASE_SPEC);
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  assert.deepEqual(refs, []);
+});
+
+test('extractProjectLUTRefs: surfaces a TimelineLUT path', async () => {
+  const buf = await buildDrpWithLuts({ timelineLUT: '/lut/look.cube' });
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  assert.equal(refs.length, 1);
+  assert.equal(refs[0].slot, 'TimelineLUT');
+  assert.equal(refs[0].path, '/lut/look.cube');
+});
+
+test('extractProjectLUTRefs: surfaces all four standard slots', async () => {
+  const buf = await buildDrpWithLuts({
+    inputLUT: '/lut/idt.clf',
+    outputLUT: '/lut/odt.clf',
+    timelineLUT: '/lut/look.cube',
+    monitorLUT: '/lut/monitor.cube',
+  });
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  const slots = refs.map((r) => r.slot).sort();
+  assert.deepEqual(slots, ['InputLUT', 'MonitorLUT', 'OutputLUT', 'TimelineLUT']);
+  const byTag = Object.fromEntries(refs.map((r) => [r.slot, r.path]));
+  assert.equal(byTag.InputLUT, '/lut/idt.clf');
+  assert.equal(byTag.OutputLUT, '/lut/odt.clf');
+  assert.equal(byTag.TimelineLUT, '/lut/look.cube');
+  assert.equal(byTag.MonitorLUT, '/lut/monitor.cube');
+});
+
+test('extractProjectLUTRefs: surfaces claimed color spaces alongside each LUT', async () => {
+  const buf = await buildDrpWithLuts({ timelineLUT: '/lut/look.cube' });
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  const spaces = refs[0].claimedSpaces;
+  // buildDRP defaults populate the color-space fields.
+  assert.ok(spaces.InputColorSpace);
+  assert.ok(spaces.TimelineColorSpace);
+  assert.ok(spaces.OutputColorSpace);
+});
+
+test('extractProjectLUTRefs: accepts a filesystem path', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'lut-refs-'));
+  try {
+    const drpPath = path.join(tmp, 'with-lut.drp');
+    await fs.writeFile(drpPath, await buildDrpWithLuts({ timelineLUT: '/lut/x.cube' }));
+    const refs = await drpFormat.extractProjectLUTRefs(drpPath);
+    assert.equal(refs.length, 1);
+    assert.equal(refs[0].path, '/lut/x.cube');
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('extractProjectLUTRefs: rejects bad input types', async () => {
+  await assert.rejects(() => drpFormat.extractProjectLUTRefs(null), /string path or a Buffer/);
+  await assert.rejects(() => drpFormat.extractProjectLUTRefs(42), /string path or a Buffer/);
+});
+
+test('extractProjectLUTRefs: returns [] when archive has no project.xml (DRT-like)', async () => {
+  // Build a minimal zip with no project.xml — mimics DRT layout.
+  const JSZip = require('jszip');
+  const z = new JSZip();
+  z.folder('Primary1').file('SeqContainer1.xml', '<Sm2SequenceContainer><Name>x</Name><FrameRate>0</FrameRate></Sm2SequenceContainer>');
+  const buf = await z.generateAsync({ type: 'nodebuffer' });
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  assert.deepEqual(refs, []);
+});
+
+test('extractProjectLUTRefs: ignores empty-string LUT slots', async () => {
+  // If someone manually constructed a DRP with empty LUT tags, those
+  // shouldn't count as references.
+  const buf = await buildDrpWithLuts({ timelineLUT: '' });
+  const refs = await drpFormat.extractProjectLUTRefs(buf);
+  assert.deepEqual(refs, []);
+});
+
+test('LUT_RECOGNIZED_SLOTS: exposes the slot whitelist', () => {
+  assert.ok(Array.isArray(drpFormat.LUT_RECOGNIZED_SLOTS));
+  assert.ok(drpFormat.LUT_RECOGNIZED_SLOTS.includes('TimelineLUT'));
+  assert.ok(drpFormat.LUT_RECOGNIZED_SLOTS.includes('InputLUT'));
+  assert.ok(drpFormat.LUT_RECOGNIZED_SLOTS.includes('OutputLUT'));
+  assert.ok(drpFormat.LUT_RECOGNIZED_SLOTS.includes('MonitorLUT'));
+});

package/resolve-advanced/vendor/drp-format/__tests__/media-blobs.test.js

@@ -0,0 +1,25 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const mb = require('../media-blobs');
+
+// Samples captured from real Resolve 21 exports (canary).
+test('decodeResolutionBlob matches a real sample (1920x1080)', () => {
+  assert.deepStrictEqual(mb.decodeResolutionBlob('00000000000007800000000000000438'), { width: 1920, height: 1080 });
+});
+test('decodeRateBlob: FrameRate=24, MediaFrameRate=29.97', () => {
+  assert.strictEqual(mb.decodeRateBlob('00000000000038400000000000000000'), 24);
+  assert.ok(Math.abs(mb.decodeRateBlob('286b55e253f83d400000000000000000') - 30000 / 1001) < 1e-9);
+});
+test('decodeMediaExtentsBlob: start 3600s, ~152.67s', () => {
+  const e = mb.decodeMediaExtentsBlob('000000000020ac405055555555156340');
+  assert.strictEqual(e.startSeconds, 3600);
+  assert.ok(Math.abs(e.durationSeconds - 152.666) < 0.01);
+});
+test('round-trips', () => {
+  assert.deepStrictEqual(mb.decodeResolutionBlob(mb.encodeResolutionBlob({ width: 3840, height: 2160 })), { width: 3840, height: 2160 });
+  assert.strictEqual(mb.decodeRateBlob(mb.encodeRateBlob(23.976)), 23.976);
+  const ex = { startSeconds: 3600, durationSeconds: 10.5 };
+  assert.deepStrictEqual(mb.decodeMediaExtentsBlob(mb.encodeMediaExtentsBlob(ex)), ex);
+  // encodeResolutionBlob reproduces the real 1080p sample exactly
+  assert.strictEqual(mb.encodeResolutionBlob({ width: 1920, height: 1080 }), '00000000000007800000000000000438');
+});

package/resolve-advanced/vendor/drp-format/__tests__/media-timemap.test.js

@@ -0,0 +1,119 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const JSZip = require('jszip');
+const {
+  decodeTimemap, encodeTimemap, encodeRetimedTimemap,
+  identityTimemap, buildConstantSpeedTimemap, buildTimemap,
+} = require('../media-timemap');
+
+const FIXTURE = 'docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp';
+// Live-captured retimes (Sm2TimeMap keyed-dicts) from real Resolve 21 exports.
+const RETIMED_50 = fs.readFileSync(
+  require('path').join(__dirname, 'fixtures', 'retimed-timemap-50pct.hex'), 'utf8').trim();
+// Dynamic ramp: 50% for the first segment, then a speed point, then 200%.
+const RETIMED_DYNAMIC = fs.readFileSync(
+  require('path').join(__dirname, 'fixtures', 'retimed-timemap-dynamic.hex'), 'utf8').trim();
+
+async function grab(tag) {
+  const zip = await JSZip.loadAsync(fs.readFileSync(FIXTURE));
+  for (const name of Object.keys(zip.files)) {
+    if (!name.endsWith('.xml')) continue;
+    const x = await zip.files[name].async('string');
+    const m = x.match(new RegExp(`<${tag}>([0-9a-f]+)</${tag}>`));
+    if (m) return m[1];
+  }
+  return null;
+}
+
+test('decodeTimemap reads the identity (1x) compact form', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const { form, type, seconds } = decodeTimemap(await grab('MediaTimemapBA'));
+  assert.strictEqual(form, 'identity');
+  assert.strictEqual(type, 2);
+  assert.strictEqual(seconds.length, 5);
+  // 152.6525 s * 29.97 fps == 4575 (canary clip last-frame index).
+  assert.strictEqual(Math.round(seconds[0] * (30000 / 1001)), 4575);
+  assert.strictEqual(seconds[1], 0);
+});
+
+test('encodeTimemap round-trips the identity blob byte-for-byte', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const hex = await grab('MediaTimemapBA');
+  assert.strictEqual(encodeTimemap(decodeTimemap(hex)).toString('hex'), hex);
+});
+
+test('decodeTimemap handles the degenerate (title) 9-byte form', () => {
+  const { form, type, seconds } = decodeTimemap('024013d55555555555');
+  assert.strictEqual(form, 'identity');
+  assert.strictEqual(type, 2);
+  assert.strictEqual(seconds.length, 1);
+});
+
+test('decodeTimemap reads the retimed Sm2TimeMap form + exact keyframe speed', () => {
+  const d = decodeTimemap(RETIMED_50);
+  assert.strictEqual(d.form, 'retimed');
+  // Exact speed comes from the keyframe ratio: 0.5 (the dialog input), not the
+  // frame-quantized LastValidYOffset/XMax (≈0.49996).
+  assert.strictEqual(d.speed, 0.5);
+  assert.ok(Math.abs(d.sourceDurationSec - 152.6525) < 1e-3);
+  assert.ok(Math.abs(d.recordDurationSec - 305.33) < 1e-2);
+});
+
+test('encodeRetimedTimemap round-trips the live 50% blob byte-for-byte', () => {
+  const d = decodeTimemap(RETIMED_50);
+  assert.strictEqual(encodeRetimedTimemap(d).toString('hex'), RETIMED_50);
+});
+
+test('buildConstantSpeedTimemap rebuilds the exact captured 50% blob', () => {
+  // Given Resolve's frame-quantized XMax, everything else (keyframe endpoint) is derived.
+  const built = buildConstantSpeedTimemap({
+    speed: 0.5,
+    sourceDurationSec: 152.6525,
+    recordDurationSec: 305.33006666666665,
+    uniqueId: '346625ac-b0e3-4768-8418-276483860709',
+  });
+  assert.strictEqual(built.toString('hex'), RETIMED_50);
+});
+
+test('buildConstantSpeedTimemap default (nominal XMax) decodes to the exact speed', () => {
+  const built = buildConstantSpeedTimemap({
+    speed: 0.5, sourceDurationSec: 152.6525, uniqueId: '346625ac-b0e3-4768-8418-276483860709',
+  });
+  const d = decodeTimemap(built);
+  assert.strictEqual(d.form, 'retimed');
+  assert.strictEqual(d.speed, 0.5);
+});
+
+test('decodeTimemap reads a DYNAMIC ramp: per-segment speeds 50% then 200%', () => {
+  const d = decodeTimemap(RETIMED_DYNAMIC);
+  assert.strictEqual(d.form, 'retimed');
+  assert.strictEqual(d.variable, true);
+  assert.strictEqual(d.keyframes.length, 2);
+  assert.strictEqual(d.segments.length, 2);
+  assert.ok(Math.abs(d.segments[0].speed - 0.5) < 1e-3, `seg0 ${d.segments[0].speed}`);
+  assert.ok(Math.abs(d.segments[1].speed - 2.0) < 1e-3, `seg1 ${d.segments[1].speed}`);
+});
+
+test('encodeRetimedTimemap round-trips the dynamic ramp byte-for-byte', () => {
+  const d = decodeTimemap(RETIMED_DYNAMIC);
+  assert.strictEqual(encodeRetimedTimemap(d).toString('hex'), RETIMED_DYNAMIC);
+});
+
+test('buildTimemap rebuilds the captured dynamic ramp byte-for-byte', () => {
+  const d = decodeTimemap(RETIMED_DYNAMIC);
+  const built = buildTimemap({
+    keyframes: d.keyframes,
+    sourceDurationSec: d.sourceDurationSec,
+    recordDurationSec: d.recordDurationSec,
+    uniqueId: d.entries.find((e) => e.key === 'UniqueId').value,
+  });
+  assert.strictEqual(built.toString('hex'), RETIMED_DYNAMIC);
+});
+
+test('identityTimemap builds a [02][end,0,end,0,end] map', () => {
+  const b = decodeTimemap(identityTimemap(4576, 30000 / 1001));
+  assert.strictEqual(b.form, 'identity');
+  assert.strictEqual(b.seconds.length, 5);
+  assert.strictEqual(Math.round(b.seconds[0] * (30000 / 1001)), 4575);
+});

package/resolve-advanced/vendor/drp-format/__tests__/place-fusion-title.test.js

@@ -0,0 +1,52 @@
+// Unit: placeFusionTitle drops a Fusion Title onto a chosen video track of a real .drp.
+// Verified structurally with the (reconciled) DRT parser. Live Resolve round-trip is the
+// acceptance gate, proven manually — see resolve21-schema-reconciliation.md.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('node:path');
+const fs = require('node:fs');
+const { placeFusionTitle } = require('../place-fusion-title');
+const { parseDRT } = require('../../drt-format');
+
+const FIXTURE = path.resolve(
+  __dirname,
+  '../../../docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp',
+);
+
+test('placeFusionTitle adds an empty V2 and places the title there', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+
+  const START = 90000;
+  const res = await placeFusionTitle(FIXTURE, { trackIndex: 2, startFrame: START, durationFrames: 96 });
+
+  assert.ok(Buffer.isBuffer(res.buffer), 'returns a buffer');
+  assert.strictEqual(res.trackIndex, 2);
+  assert.strictEqual(res.createdTracks, 1, 'should have created one new (V2) track');
+  assert.ok(res.videoTrackCount >= 2, 'target timeline now has >=2 video tracks');
+
+  // Parse the result and find the modified timeline by its DbId.
+  const parsed = await parseDRT(res.buffer);
+  const tl = parsed.timelines.find((t2) => t2.sequence.includes(res.timelineUuid) || true)
+    && parsed.timelines.find((t2) => (t2.videoTracks || []).length >= 2);
+  assert.ok(tl, 'a timeline with >=2 video tracks exists after placement');
+
+  const v2 = tl.videoTracks[1];
+  assert.strictEqual((v2.clips || []).length, 1, 'V2 holds exactly the placed title');
+  assert.strictEqual(v2.clips[0].start, START, 'placed clip start matches startFrame');
+  // A Fusion Title carries no MediaFilePath (empty) — distinguishes it from a media clip.
+  assert.ok(!v2.clips[0].mediaFilePath, 'title clip has no MediaFilePath');
+});
+
+test('placeFusionTitle requires startFrame', async () => {
+  await assert.rejects(() => placeFusionTitle(FIXTURE, { trackIndex: 2 }), /startFrame/);
+});
+
+test('placeFusionTitle places onto an existing track without creating one', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const res = await placeFusionTitle(FIXTURE, { trackIndex: 1, startFrame: 200000 });
+  assert.strictEqual(res.createdTracks, 0, 'V1 already exists — no track created');
+  const parsed = await parseDRT(res.buffer);
+  const tl = parsed.timelines.find((t2) => (t2.videoTracks || [])[0]?.clips?.some((c) => c.start === 200000));
+  assert.ok(tl, 'placed title found on V1 at the requested start');
+});

package/resolve-advanced/vendor/drp-format/__tests__/place-generator.test.js

@@ -0,0 +1,40 @@
+// Unit: place a built-in generator (Sm2TiGenerator) on a chosen track. Live Resolve
+// round-trip is the acceptance gate (see resolve21-schema-reconciliation.md).
+
+const test = require('node:test');
+const assert = require('node:assert');
+const { placeGenerator } = require('../place-generator');
+const { createEmptyProject } = require('../author-project');
+
+async function genOnTrack(buffer, trackIdx) {
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  for (const n of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$|SeqContainer\d*\.xml$/.test(n)) continue;
+    const x = await zip.files[n].async('string');
+    const vtv = (x.match(/<VideoTrackVec>([\s\S]*?)<\/VideoTrackVec>/) || [null, ''])[1];
+    const tracks = vtv.match(/<Element>\s*<Sm2TiTrack\b[\s\S]*?<\/Sm2TiTrack>\s*<\/Element>/g) || [];
+    return tracks[trackIdx - 1] || '';
+  }
+  return '';
+}
+
+test('placeGenerator drops a Solid Color generator on V2 from scratch', async () => {
+  const { buffer, startFrame } = await createEmptyProject({ timelineName: 'Gen' });
+  const res = await placeGenerator(buffer, { trackIndex: 2, startFrame, durationFrames: 90 });
+  assert.strictEqual(res.generatorName, 'Solid Color');
+  assert.strictEqual(res.createdTracks, 1);
+  const v2 = await genOnTrack(res.buffer, 2);
+  assert.ok(/<Sm2TiGenerator\b/.test(v2), 'V2 holds an Sm2TiGenerator');
+  assert.ok(/<PrettyType>Solid Color<\/PrettyType>/.test(v2), 'PrettyType set');
+  assert.ok(new RegExp(`<Start>${startFrame}</Start>`).test(v2), 'start set');
+  assert.ok(/<Duration>90<\/Duration>/.test(v2), 'duration set');
+});
+
+test('placeGenerator honors generatorName + requires startFrame', async () => {
+  const { buffer, startFrame } = await createEmptyProject();
+  const res = await placeGenerator(buffer, { generatorName: 'Gray Scale', trackIndex: 1, startFrame });
+  const v1 = await genOnTrack(res.buffer, 1);
+  assert.ok(/<PrettyType>Gray Scale<\/PrettyType>/.test(v1));
+  await assert.rejects(() => placeGenerator(buffer, { trackIndex: 1 }), /startFrame/);
+});

package/resolve-advanced/vendor/drp-format/__tests__/place-transition.test.js

@@ -0,0 +1,48 @@
+// Unit: insert a cross-dissolve between two abutting clips. Live Resolve round-trip is the
+// acceptance gate. Template captured from a GUI-authored Cross Dissolve in Resolve 21.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const { placeTransition } = require('../place-transition');
+
+// Two abutting Sm2TiVideoClips: c0 [0,100), c1 [100,200) — cut at 100.
+async function synth2() {
+  const JSZip = require('jszip');
+  const clip = (i) => `<Element><Sm2TiVideoClip DbId="c${i}"><FieldsBlob/><Name>c${i}</Name><Start>${i * 100}</Start><Duration>100</Duration><In/></Sm2TiVideoClip></Element>`;
+  const track = `<Element><Sm2TiTrack DbId="t"><FieldsBlob/><Type>0</Type><SubType>0</SubType><Flags>0</Flags><Sequence>s</Sequence><Items>${clip(0)}${clip(1)}</Items><FusionCompHolderItems/><UserDefinedName/><LayersVec/></Sm2TiTrack></Element>`;
+  const seq = `<?xml version="1.0"?>\n<Sm2SequenceContainer DbId="s1"><FieldsBlob/><VideoTrackVec>${track}</VideoTrackVec><AudioTrackVec/></Sm2SequenceContainer>`;
+  const z = new JSZip(); z.file('SeqContainer/s1.xml', seq); return z.generateAsync({ type: 'nodebuffer' });
+}
+
+async function vtv(buf) {
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buf);
+  const x = await zip.file('SeqContainer/s1.xml').async('string');
+  return x.match(/<VideoTrackVec>([\s\S]*?)<\/VideoTrackVec>/)[1];
+}
+
+test('placeTransition inserts an Sm2TiTransition between the two clips, centered on the cut', async () => {
+  const res = await placeTransition(await synth2(), { track: 1, atFrame: 100, durationFrames: 24 });
+  assert.strictEqual(res.start, 88, 'centered: 100 - 24/2');
+  assert.strictEqual(res.durationFrames, 24);
+  assert.ok(res.transitionDbId, 'fresh DbId assigned');
+
+  const body = await vtv(res.buffer);
+  assert.ok(/<Sm2TiTransition\b/.test(body), 'transition present');
+  assert.ok(/<PrettyType>Cross Dissolve<\/PrettyType>/.test(body), 'is a Cross Dissolve');
+  assert.ok(/<Start>88<\/Start>/.test(body) && /<Duration>24<\/Duration>/.test(body), 'start/duration set');
+  // ordering: clip c0 ... transition ... clip c1
+  const order = [...body.matchAll(/<Sm2Ti(VideoClip|Transition)\b[^>]*DbId="([^"]+)"/g)].map((m) => m[1]);
+  assert.deepStrictEqual(order, ['VideoClip', 'Transition', 'VideoClip'], 'transition sits between the clips');
+});
+
+test('placeTransition errors when no abutting boundary at atFrame', async () => {
+  const buf = await synth2();
+  await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 9999 }), /no abutting clip boundary/);
+});
+
+test('placeTransition validates args', async () => {
+  const buf = await synth2();
+  await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 100, durationFrames: 1 }), /durationFrames/);
+  await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 100, trackType: 'audio' }), /only video/);
+});

package/resolve-advanced/vendor/drp-format/__tests__/protobuf-wire.test.js

@@ -0,0 +1,64 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const JSZip = require('jszip');
+const {
+  decodeProtobuf, encodeProtobuf, decodeEffectFilters, encodeEffectFilters,
+} = require('../protobuf-wire');
+const { decodeKeyedDict, encodeKeyedDict, classifyBlob } = require('../keyed-dict');
+
+const FIXTURE = 'docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp';
+const TRANS = require('path').join(__dirname, '..', 'templates', 'transition-cross-dissolve.xml');
+
+async function grabAll(path, tag) {
+  let xmls = [];
+  if (path.endsWith('.drp')) {
+    const zip = await JSZip.loadAsync(fs.readFileSync(path));
+    for (const n of Object.keys(zip.files)) {
+      if (n.endsWith('.xml')) xmls.push(await zip.files[n].async('string'));
+    }
+  } else {
+    xmls = [fs.readFileSync(path, 'utf8')];
+  }
+  const out = [];
+  for (const x of xmls) {
+    const re = new RegExp(`<${tag}>([0-9a-f]+)</${tag}>`, 'g');
+    let m;
+    while ((m = re.exec(x))) out.push(m[1]);
+  }
+  return out;
+}
+
+test('decodeProtobuf reads Radiometry color-science fields + round-trips', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const hex = (await grabAll(FIXTURE, 'Radiometry'))[0];
+  const fields = decodeProtobuf(hex);
+  assert.ok(fields.length >= 5, 'several varint fields');
+  assert.ok(fields.every((f) => f.wire === 0), 'Radiometry is all varints');
+  assert.strictEqual(encodeProtobuf(fields).toString('hex'), hex, 'round-trip exact');
+});
+
+test('decodeEffectFilters reads the transition effect envelope + round-trips', async () => {
+  const hex = (await grabAll(TRANS, 'EffectFiltersBA'))[0];
+  const dec = decodeEffectFilters(hex);
+  assert.strictEqual(dec.hdr, 2);
+  assert.ok(dec.fields.length > 0);
+  assert.strictEqual(encodeEffectFilters(dec).toString('hex'), hex, 'envelope round-trip exact');
+});
+
+test('classifyBlob splits FieldsBlob into keyed-dict / protobuf / zstd; keyed-dicts round-trip', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip('fixture missing'); return; }
+  const all = await grabAll(FIXTURE, 'FieldsBlob');
+  const seen = new Set();
+  for (const hex of all) {
+    const cls = classifyBlob(hex);
+    seen.add(cls);
+    if (cls === 'keyed-dict') {
+      // Every keyed-dict FieldsBlob (element state + UI view-options) round-trips exactly.
+      assert.strictEqual(encodeKeyedDict(decodeKeyedDict(hex)).toString('hex'), hex);
+    }
+    // 'zstd' = compressed internal state, carried verbatim (no built-in zstd in Node).
+  }
+  assert.ok(seen.has('keyed-dict'), 'has keyed-dict FieldsBlobs');
+  assert.ok(seen.has('zstd'), 'has zstd internal-state FieldsBlobs');
+});

package/resolve-advanced/vendor/drp-format/__tests__/relink-media.test.js

@@ -0,0 +1,106 @@
+// Unit: offline media relink — rewrite the media path in the Media Pool blobs + plain text.
+// Live Resolve acceptance proven manually (lint: 0 offline; re-export blob shows the new path)
+// — see resolve21-schema-reconciliation.md.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('node:path');
+const fs = require('node:fs');
+const { relinkMedia } = require('../relink-media');
+
+const FIXTURE = path.resolve(
+  __dirname,
+  '../../../docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp',
+);
+const FROM = '/media/Sample Clip.mp4';
+
+async function videoClipBlob(buffer) {
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  const mp = await zip.file('MediaPool/Master/MpFolder.xml').async('string');
+  const m = mp.match(/<Video>\s*<BtVideoInfo\b[\s\S]*?<Clip>([0-9a-fA-F]*)<\/Clip>/);
+  return Buffer.from(m[1], 'hex');
+}
+async function timelineMediaPaths(buffer) {
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  const out = [];
+  for (const n of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$/.test(n)) continue;
+    const x = await zip.files[n].async('string');
+    for (const p of x.match(/<MediaFilePath>([^<]+)<\/MediaFilePath>/g) || []) out.push(p);
+  }
+  return out;
+}
+
+test('relinkMedia repoints the blob path AND the plain-text MediaFilePath', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const TO = '/Volumes/ARCHIVE/relinked/My Cut Final.mov'; // different dir + name + length
+
+  const res = await relinkMedia(FIXTURE, { from: FROM, to: TO });
+  assert.strictEqual(res.relinked.length, 1);
+  assert.ok(res.relinked[0].blobsEdited >= 1, 'at least the video blob edited');
+  assert.ok(res.relinked[0].textRefs >= 1, 'plain-text refs edited');
+
+  const blob = await videoClipBlob(res.buffer);
+  assert.ok(blob.includes(Buffer.from('/Volumes/ARCHIVE/relinked', 'utf8')), 'new dir in blob');
+  assert.ok(blob.includes(Buffer.from('My Cut Final.mov', 'utf8')), 'new filename in blob');
+  assert.ok(!blob.includes(Buffer.from('Sample Clip.mp4', 'utf8')), 'old filename gone from blob');
+
+  // The 4-byte BE payload-length header must stay consistent (len = blob.length - 8).
+  assert.strictEqual(blob.readUInt32BE(4), blob.length - 8, 'blob payload-length header updated');
+
+  const paths = await timelineMediaPaths(res.buffer);
+  assert.ok(paths.every((p) => p.includes(TO)), 'timeline MediaFilePath repointed');
+});
+
+test('relinkMedia supports multiple mappings', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const res = await relinkMedia(FIXTURE, {
+    mappings: [{ from: FROM, to: '/new/loc/clip-a.mov' }, { from: '/never/here.mov', to: '/x/y.mov' }],
+  });
+  assert.strictEqual(res.relinked.length, 2);
+  assert.ok(res.relinked[0].blobsEdited >= 1);
+  assert.strictEqual(res.relinked[1].blobsEdited, 0, 'absent source maps to nothing');
+});
+
+test('relinkMedia requires absolute paths', async () => {
+  await assert.rejects(() => relinkMedia(FIXTURE, { from: 'rel/a.mov', to: '/abs/b.mov' }), /absolute/);
+});
+
+test('relinkMedia requires a mapping', async () => {
+  await assert.rejects(() => relinkMedia(FIXTURE, {}), /from.*to|mappings/);
+});
+
+const { repointMedia } = require('../relink-media');
+
+test('repointMedia relinks the path AND patches resolution/frames/fps in the matching entry', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const TO = '/Volumes/ARCHIVE/new clip.mov';
+  const res = await repointMedia(FIXTURE, {
+    from: FROM, to: TO,
+    fromSpec: { width: 352, height: 262, frameCount: 4576, fps: 30000 / 1001 },
+    toSpec: { width: 1920, height: 1080, frameCount: 240, fps: 24 },
+  });
+  assert.strictEqual(res.specPatched[0].patched, true);
+
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(res.buffer);
+  const mp = await zip.file('MediaPool/Master/MpFolder.xml').async('string');
+  // entry renamed + geometry/time patched to target values
+  const entry = mp.match(/<Sm2MpVideoClip\b[\s\S]*?<\/Sm2MpVideoClip>/)[0];
+  assert.ok(entry.includes('<Name>new clip.mov</Name>'), 'entry renamed');
+  const geo = Buffer.from(entry.match(/<Geometry>([0-9a-fA-F]+)<\/Geometry>/)[1], 'hex');
+  assert.ok(geo.includes(Buffer.from([0, 0, 7, 128])), 'width 1920 (0x780) patched');
+  assert.ok(geo.includes(Buffer.from([0, 0, 4, 56])), 'height 1080 (0x438) patched');
+  assert.ok(!geo.includes(Buffer.from([0, 0, 1, 96])), 'old width 352 gone');
+  const time = Buffer.from(entry.match(/<Time>([0-9a-fA-F]+)<\/Time>/)[1], 'hex');
+  assert.ok(time.includes(Buffer.from([0, 0, 0, 240])), 'frame count 240 patched');
+});
+
+test('repointMedia without specs just relinks (no patch)', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const res = await repointMedia(FIXTURE, { from: FROM, to: '/x/y.mov' });
+  assert.strictEqual(res.specPatched[0].patched, false);
+  assert.ok(res.relinked[0].blobsEdited >= 1);
+});