davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/drx-codec/extract-custom-curves.js

@@ -0,0 +1,215 @@
+/**
+ * Decode CUSTOM_CURVES (YRGB) corrector params back to the spec shape
+ * generator's buildCustomCurveParams accepts (P1.1).
+ *
+ * Encoding (per drx-generator.js encodeCurveSpline):
+ *   - splineId param's F2 contains a wrapped protobuf in field 8
+ *   - Field 8 is a nested message containing repeated F1 entries
+ *   - Each F1 entry holds { F1: x_scaled_float32, F2: y_scaled_float32 }
+ *   - First point is the sentinel (-1024, -1024)
+ *   - Then an empty F1 (separator)
+ *   - Then user-supplied points scaled by 1023
+ *   - Then end point (1023, 1023)
+ *
+ * Decoded points come back in normalized 0–1 space, sorted by x.
+ *
+ * @module drx-codec/extract-custom-curves
+ */
+
+// IMPORTANT: drx-parameters CUSTOM_CURVES.Y_SPLINE/R/G/B has a documented
+// Y/R/G/B → R/G/B/Y inversion (see drx-generator.js comments around
+// lines 199-202: "was incorrectly mapped to..."). The GENERATOR'S
+// mapping is correct; the registry's is the bug. We mirror the
+// generator here so round-trip is byte-symmetrical. Knowledge note
+// in docs/design/drp-drx-drt-closeout-harness/knowledge/.
+const SPLINE_IDS = {
+  y: 2248148233,  // 0x86000509 — registry calls this B_SPLINE (bug)
+  r: 2248148230,  // 0x86000506 — registry calls this Y_SPLINE (bug)
+  g: 2248148231,  // 0x86000507 — registry calls this R_SPLINE (bug)
+  b: 2248148232,  // 0x86000508 — registry calls this G_SPLINE (bug)
+};
+
+const SCALE = 1023;
+const SENTINEL_X = -1024;
+
+/**
+ * Read a single proto field at offset. Returns { wireType, fieldNum,
+ * value, next } where value depends on wire type. Mirrors the
+ * mini-parser used inside drx-parser.js but limited to what we need.
+ */
+function readVarint(buf, offset) {
+  let result = 0n;
+  let shift = 0n;
+  let cur = offset;
+  while (cur < buf.length) {
+    const byte = buf[cur++];
+    result |= BigInt(byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) return { value: result, next: cur };
+    shift += 7n;
+  }
+  throw new Error('Truncated varint');
+}
+
+function readField(buf, offset) {
+  const tag = readVarint(buf, offset);
+  const tagNum = Number(tag.value);
+  const wireType = tagNum & 0x07;
+  const fieldNum = tagNum >>> 3;
+  let cur = tag.next;
+  if (wireType === 0) {
+    const v = readVarint(buf, cur);
+    return { wireType, fieldNum, value: v.value, next: v.next };
+  }
+  if (wireType === 5) {
+    // 32-bit fixed (float32)
+    const v = buf.readFloatLE(cur);
+    return { wireType, fieldNum, value: v, next: cur + 4 };
+  }
+  if (wireType === 1) {
+    // 64-bit fixed (double)
+    const v = buf.readDoubleLE(cur);
+    return { wireType, fieldNum, value: v, next: cur + 8 };
+  }
+  if (wireType === 2) {
+    const len = readVarint(buf, cur);
+    const start = len.next;
+    const end = start + Number(len.value);
+    return { wireType, fieldNum, value: buf.slice(start, end), next: end };
+  }
+  throw new Error(`Unsupported wire type ${wireType}`);
+}
+
+function readAllFields(buf) {
+  const fields = [];
+  let cur = 0;
+  while (cur < buf.length) {
+    const f = readField(buf, cur);
+    fields.push(f);
+    cur = f.next;
+  }
+  return fields;
+}
+
+/**
+ * Decode a single curve point: nested message with { F1: x, F2: y }
+ * where both are float32. Accepts either a raw Buffer (when called on
+ * raw protobuf bytes) or the parsed structure that drx-parser produces.
+ */
+function decodePoint(pointBufOrFields) {
+  let fields;
+  if (Buffer.isBuffer(pointBufOrFields)) {
+    fields = readAllFields(pointBufOrFields);
+  } else if (pointBufOrFields && pointBufOrFields._fields) {
+    fields = pointBufOrFields._fields;
+  } else {
+    return { x: 0, y: 0 };
+  }
+  let x = 0, y = 0;
+  for (const f of fields) {
+    if (f.fieldNum === 1 && f.wireType === 5) x = f.value;
+    if (f.fieldNum === 2 && f.wireType === 5) y = f.value;
+  }
+  return { x, y };
+}
+
+/**
+ * Decode an encodeCurveSpline value to normalized {x,y} points.
+ *
+ * Accepts EITHER a raw Buffer (when working with un-parsed bytes) OR
+ * the parsed structure that drx-parser surfaces — the parser walks the
+ * nested protobuf eagerly so by the time the parameter value reaches a
+ * caller it already has `_fields`, `F8`, etc.
+ */
+function decodeSpline(splineValue) {
+  if (splineValue == null) return [];
+
+  // Case 1 — raw buffer (e.g. when caller has unparsed bytes).
+  if (Buffer.isBuffer(splineValue)) {
+    if (splineValue.length === 0) return [];
+    const fields = readAllFields(splineValue);
+    const innerField = fields.find((f) => f.fieldNum === 8 && f.wireType === 2);
+    if (!innerField) return [];
+    return decodeInnerBuf(innerField.value);
+  }
+
+  // Case 2 — parsed structure with F8 already decoded.
+  if (typeof splineValue === 'object' && splineValue.F8 !== undefined) {
+    const inner = splineValue.F8;
+    if (inner && inner._fields) {
+      return decodeInnerFromParsed(inner._fields);
+    }
+    if (Buffer.isBuffer(inner)) {
+      return decodeInnerBuf(inner);
+    }
+  }
+
+  return [];
+}
+
+function decodeInnerBuf(innerBuf) {
+  if (!Buffer.isBuffer(innerBuf)) return [];
+  const innerFields = readAllFields(innerBuf);
+  const points = [];
+  for (const f of innerFields) {
+    if (f.fieldNum !== 1 || f.wireType !== 2) continue;
+    if (f.value.length === 0) continue; // empty separator
+    const pt = decodePoint(f.value);
+    if (pt.x === SENTINEL_X) continue;
+    points.push({ x: pt.x / SCALE, y: pt.y / SCALE });
+  }
+  points.sort((a, b) => a.x - b.x);
+  return points;
+}
+
+function decodeInnerFromParsed(innerFields) {
+  const points = [];
+  for (const f of innerFields) {
+    if (f.fieldNum !== 1 || f.wireType !== 2) continue;
+    // Empty separators come through as zero-length buffers / empty
+    // objects depending on the parser path.
+    if (Buffer.isBuffer(f.value) && f.value.length === 0) continue;
+    if (!Buffer.isBuffer(f.value) && (!f.value || !f.value._fields || f.value._fields.length === 0)) continue;
+    const pt = decodePoint(f.value);
+    if (pt.x === SENTINEL_X) continue;
+    if (pt.x === 0 && pt.y === 0) continue; // empty separator surfaces as (0,0) sometimes
+    points.push({ x: pt.x / SCALE, y: pt.y / SCALE });
+  }
+  points.sort((a, b) => a.x - b.x);
+  return points;
+}
+
+/**
+ * Given a corrector's parameter list (as drx-parser surfaces it under
+ * corrector.parameters), extract per-channel custom curves.
+ *
+ * @param {Array<{id, value, name}>} parameters
+ * @returns {{y: Array, r: Array, g: Array, b: Array} | null}
+ *   null if no spline params present; per-channel arrays if found.
+ *   Identity curves (only endpoint, no user points) come back as empty
+ *   arrays — matches what buildCustomCurveParams treats as "no user
+ *   data for this channel".
+ */
+function extractCustomCurves(parameters) {
+  if (!Array.isArray(parameters)) return null;
+  const out = { y: [], r: [], g: [], b: [] };
+  let anyFound = false;
+  for (const param of parameters) {
+    const splineChannel = Object.entries(SPLINE_IDS).find(([, id]) => id === param.id);
+    if (!splineChannel) continue;
+    const [channel] = splineChannel;
+    if (param.value == null) continue;
+    const points = decodeSpline(param.value);
+    // Identity curves end at (1, 1) only. Strip the endpoint sentinel
+    // from the user-visible result.
+    const userPoints = points.filter((p) => !(p.x === 1 && p.y === 1));
+    if (userPoints.length > 0) anyFound = true;
+    out[channel] = userPoints;
+  }
+  return anyFound ? out : null;
+}
+
+module.exports = {
+  extractCustomCurves,
+  // Exposed for testing only.
+  _internals: { decodeSpline, decodePoint, readAllFields, SPLINE_IDS },
+};

package/resolve-advanced/vendor/drx-codec/extract-hsl-curves.js

@@ -0,0 +1,180 @@
+/**
+ * Decode HSL_CURVES corrector params back to the spec shape that
+ * generateDRX's hslCurves input accepts (P1.2).
+ *
+ * HSL curves use a different encoding from YRGB custom curves
+ * (encodeHSLCurveSpline in drx-generator.js):
+ *   - NO sentinel (-1024, -1024)
+ *   - NO empty separator
+ *   - NO end marker
+ *   - Just raw float data points wrapped in F8
+ *   - X = hue fraction (0..1 with wrap-around continuity, e.g. -0.08..1.08)
+ *   - Y = neutral 0.5, >0.5 = boost, <0.5 = cut
+ *
+ * The 6 HSL curve types: hueVsHue, hueVsSat, hueVsLum, lumVsSat,
+ * satVsSat, satVsLum.
+ *
+ * @module drx-codec/extract-hsl-curves
+ */
+
+const drxParams = require('../drx-parameters');
+
+const HSL_SPLINE_IDS = {
+  hueVsHue: drxParams.HSL_CURVES.HUE_VS_HUE_SPLINE,
+  hueVsSat: drxParams.HSL_CURVES.HUE_VS_SAT_SPLINE,
+  hueVsLum: drxParams.HSL_CURVES.HUE_VS_LUM_SPLINE,
+  lumVsSat: drxParams.HSL_CURVES.LUM_VS_SAT_SPLINE,
+  satVsSat: drxParams.HSL_CURVES.SAT_VS_SAT_SPLINE,
+  satVsLum: drxParams.HSL_CURVES.SAT_VS_LUM_SPLINE,
+};
+
+// ─── Mini protobuf reader (shared shape with extract-custom-curves) ─────
+
+function readVarint(buf, offset) {
+  let result = 0n;
+  let shift = 0n;
+  let cur = offset;
+  while (cur < buf.length) {
+    const byte = buf[cur++];
+    result |= BigInt(byte & 0x7f) << shift;
+    if ((byte & 0x80) === 0) return { value: result, next: cur };
+    shift += 7n;
+  }
+  throw new Error('Truncated varint');
+}
+
+function readField(buf, offset) {
+  const tag = readVarint(buf, offset);
+  const tagNum = Number(tag.value);
+  const wireType = tagNum & 0x07;
+  const fieldNum = tagNum >>> 3;
+  let cur = tag.next;
+  if (wireType === 0) {
+    const v = readVarint(buf, cur);
+    return { wireType, fieldNum, value: v.value, next: v.next };
+  }
+  if (wireType === 5) {
+    const v = buf.readFloatLE(cur);
+    return { wireType, fieldNum, value: v, next: cur + 4 };
+  }
+  if (wireType === 1) {
+    const v = buf.readDoubleLE(cur);
+    return { wireType, fieldNum, value: v, next: cur + 8 };
+  }
+  if (wireType === 2) {
+    const len = readVarint(buf, cur);
+    const start = len.next;
+    const end = start + Number(len.value);
+    return { wireType, fieldNum, value: buf.slice(start, end), next: end };
+  }
+  throw new Error(`Unsupported wire type ${wireType}`);
+}
+
+function readAllFields(buf) {
+  const fields = [];
+  let cur = 0;
+  while (cur < buf.length) {
+    const f = readField(buf, cur);
+    fields.push(f);
+    cur = f.next;
+  }
+  return fields;
+}
+
+function decodePoint(pointBufOrFields) {
+  let fields;
+  if (Buffer.isBuffer(pointBufOrFields)) {
+    fields = readAllFields(pointBufOrFields);
+  } else if (pointBufOrFields && pointBufOrFields._fields) {
+    fields = pointBufOrFields._fields;
+  } else {
+    return { x: 0, y: 0 };
+  }
+  let x = 0, y = 0;
+  for (const f of fields) {
+    if (f.fieldNum === 1 && f.wireType === 5) x = f.value;
+    if (f.fieldNum === 2 && f.wireType === 5) y = f.value;
+  }
+  return { x, y };
+}
+
+/**
+ * Decode an encodeHSLCurveSpline value to raw {x, y} float points.
+ *
+ * HSL is simpler than YRGB: no sentinel, no separator, no end marker.
+ * Just F1 entries inside the F8 wrapper.
+ */
+function decodeHSLSpline(splineValue) {
+  if (splineValue == null) return [];
+
+  if (Buffer.isBuffer(splineValue)) {
+    if (splineValue.length === 0) return [];
+    const fields = readAllFields(splineValue);
+    const inner = fields.find((f) => f.fieldNum === 8 && f.wireType === 2);
+    if (!inner) return [];
+    return decodeInnerBuf(inner.value);
+  }
+
+  if (typeof splineValue === 'object' && splineValue.F8 !== undefined) {
+    const inner = splineValue.F8;
+    if (inner && inner._fields) return decodeInnerFromParsed(inner._fields);
+    if (Buffer.isBuffer(inner)) return decodeInnerBuf(inner);
+  }
+
+  return [];
+}
+
+function decodeInnerBuf(innerBuf) {
+  if (!Buffer.isBuffer(innerBuf)) return [];
+  const innerFields = readAllFields(innerBuf);
+  const points = [];
+  for (const f of innerFields) {
+    if (f.fieldNum !== 1 || f.wireType !== 2) continue;
+    if (f.value.length === 0) continue;
+    points.push(decodePoint(f.value));
+  }
+  return points;
+}
+
+function decodeInnerFromParsed(innerFields) {
+  const points = [];
+  for (const f of innerFields) {
+    if (f.fieldNum !== 1 || f.wireType !== 2) continue;
+    if (Buffer.isBuffer(f.value) && f.value.length === 0) continue;
+    if (!Buffer.isBuffer(f.value) && (!f.value || !f.value._fields || f.value._fields.length === 0)) continue;
+    points.push(decodePoint(f.value));
+  }
+  return points;
+}
+
+/**
+ * Given a corrector's parameter list, extract per-type HSL curves.
+ *
+ * @param {Array<{id, value, name}>} parameters
+ * @returns {{hueVsHue?, hueVsSat?, hueVsLum?, lumVsSat?, satVsSat?, satVsLum?} | null}
+ *   null if no HSL spline params present; otherwise an object with one
+ *   entry per detected curve type. Each entry is the array of float
+ *   {x, y} points in raw (un-normalized) space.
+ */
+function extractHSLCurves(parameters) {
+  if (!Array.isArray(parameters)) return null;
+  const out = {};
+  let anyFound = false;
+  for (const param of parameters) {
+    const splineEntry = Object.entries(HSL_SPLINE_IDS).find(([, id]) => id === param.id);
+    if (!splineEntry) continue;
+    const [curveType] = splineEntry;
+    if (param.value == null) continue;
+    const points = decodeHSLSpline(param.value);
+    if (points.length > 0) {
+      out[curveType] = points;
+      anyFound = true;
+    }
+  }
+  return anyFound ? out : null;
+}
+
+module.exports = {
+  extractHSLCurves,
+  _internals: { decodeHSLSpline, decodePoint, readAllFields, HSL_SPLINE_IDS },
+};

package/resolve-advanced/vendor/drx-codec/extract-lut-refs.js

@@ -0,0 +1,158 @@
+/**
+ * P5.1 — Per-node LUT reference extractor.
+ *
+ * When a Resolve color node has a LUT attached (Right-click → LUT in the
+ * node graph), Resolve stores the LUT identification as two parameters
+ * inside a corrector block at the node's F9 position. The existing
+ * `extractNodes` parser already surfaces those correctors' parameters,
+ * but it only unwraps int/float value envelopes (F1 of the envelope).
+ * The LUT path lives in F5 of the envelope (a string), which the
+ * generic extractor doesn't reach.
+ *
+ * This module scans a node's correctors for the NODE_LUT_REF.LUT_PATH
+ * param ID, drops into the value envelope to pull the F5 string, and
+ * returns the resolved LUT reference. Pairs with `extract-lut-refs`
+ * for DRP project-level LUTs (drp-format/extract-lut-refs.js) which
+ * surfaces the same shape from a different artifact.
+ *
+ * REVERSE-ENGINEERED 2026-06-19 (Session 31) from a paired DRX capture:
+ *   - no-LUT  → node.F9 contains only F2 (5-byte common tail).
+ *   - with-LUT → node.F9 contains an additional F1 corrector that holds
+ *                the LUT params, plus the same F2 common tail.
+ *
+ * @module drx-codec/extract-lut-refs
+ */
+
+const drxParams = require('../drx-parameters');
+
+const { NODE_LUT_REF } = drxParams;
+
+/**
+ * Read a string from a parameter's value envelope.
+ *
+ * The DRX parser surfaces param.value as either:
+ *   - The raw envelope object (when the envelope's F1 was undefined)
+ *   - The unwrapped F1 value (when F1 was set — e.g. floats)
+ *
+ * For LUT paths, F5 of the envelope carries the string as a length-
+ * delimited bytes field. The parser greedily tries to re-parse those
+ * bytes as a nested protobuf message (and produces garbage) but
+ * preserves the original buffer in `_fields[N].rawValue`. We hunt
+ * for field 5 in `_fields` and read the rawValue as UTF-8.
+ *
+ * Accepts strings directly and Buffer values for robustness against
+ * future parser improvements.
+ *
+ * @param {Object|string|Buffer} value
+ * @returns {string|null}
+ */
+function envelopeToString(value) {
+  if (value == null) return null;
+  if (typeof value === 'string') return value;
+  if (Buffer.isBuffer(value)) return value.toString('utf8');
+  if (typeof value !== 'object') return null;
+  // Direct F5 access (in case parser improves and surfaces it cleanly).
+  if (typeof value.F5 === 'string') return value.F5;
+  if (Buffer.isBuffer(value.F5)) return value.F5.toString('utf8');
+  // Fall back to scanning _fields for field 5's raw bytes.
+  if (Array.isArray(value._fields)) {
+    for (const field of value._fields) {
+      if (field.fieldNum !== 5) continue;
+      if (Buffer.isBuffer(field.rawValue)) return field.rawValue.toString('utf8');
+      if (typeof field.rawValue === 'string') return field.rawValue;
+      if (field.value && Buffer.isBuffer(field.value)) return field.value.toString('utf8');
+      // Nested-parsed value: its own _fields may carry the raw bytes
+      // at a wire-type-2 inner field. Drill one level for robustness.
+      if (field.value && Array.isArray(field.value._fields)) {
+        for (const inner of field.value._fields) {
+          if (Buffer.isBuffer(inner.rawValue)) return inner.rawValue.toString('utf8');
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Coerce a param.value to a number for SLOT_META (varint payload).
+ *
+ * @param {Object|number|bigint} value
+ * @returns {number|null}
+ */
+function envelopeToNumber(value) {
+  if (value == null) return null;
+  if (typeof value === 'number') return value;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'object') {
+    if (typeof value.F2 === 'number') return value.F2;
+    if (typeof value.F2 === 'bigint') return Number(value.F2);
+    if (typeof value.F1 === 'number') return value.F1;
+    if (typeof value.F1 === 'bigint') return Number(value.F1);
+  }
+  return null;
+}
+
+/**
+ * Extract a per-node LUT reference from a node's correctors list.
+ *
+ * Scans every corrector in the node for the LUT_PATH param ID.
+ * Returns null if no LUT is attached.
+ *
+ * @param {Object} node — node object from drx-parser's extractNodes,
+ *   must have a `correctors` array
+ * @returns {{lutPath: string, slotMeta: number|null}|null}
+ */
+function extractNodeLutRef(node) {
+  if (!node || !Array.isArray(node.correctors)) return null;
+  for (const corrector of node.correctors) {
+    if (!Array.isArray(corrector.parameters)) continue;
+    let lutPath = null;
+    let slotMeta = null;
+    for (const param of corrector.parameters) {
+      if (param.id === NODE_LUT_REF.LUT_PATH) {
+        lutPath = envelopeToString(param.value);
+      } else if (param.id === NODE_LUT_REF.SLOT_META) {
+        slotMeta = envelopeToNumber(param.value);
+      }
+    }
+    if (lutPath) {
+      return { lutPath, slotMeta };
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract LUT references from every node in a parsed DRX.
+ *
+ * Returns one entry per node that carries a LUT. The output shape
+ * mirrors `drp-format.extractProjectLUTRefs` so callers (e.g. the
+ * clf_lut MCP tool's `extract_refs_from_drx` action) can ingest
+ * DRX and DRP LUT refs through the same pipeline.
+ *
+ * @param {Object} parsedDRX — output of drx-parser.parseDRXContent
+ * @returns {Array<{nodeId, nodeIndex, lutPath, slotMeta, source}>}
+ */
+function extractDrxLutRefs(parsedDRX) {
+  if (!parsedDRX || !Array.isArray(parsedDRX.nodes)) return [];
+  const refs = [];
+  for (const node of parsedDRX.nodes) {
+    const ref = extractNodeLutRef(node);
+    if (ref) {
+      refs.push({
+        nodeId: node.id ?? null,
+        nodeIndex: node.index ?? null,
+        lutPath: ref.lutPath,
+        slotMeta: ref.slotMeta,
+        source: 'drx_node',
+      });
+    }
+  }
+  return refs;
+}
+
+module.exports = {
+  extractNodeLutRef,
+  extractDrxLutRefs,
+  _internals: { envelopeToString, envelopeToNumber, NODE_LUT_REF },
+};

package/resolve-advanced/vendor/drx-codec/extract-matte-finesse.js

@@ -0,0 +1,83 @@
+/**
+ * Decode MATTE_FINESSE (Corrector Type 9) params back to a UI-shaped
+ * spec (P1.5).
+ *
+ * SCOPE NOTE: the P1.5 ledger description targets "external matte refs"
+ * (file path or media pool ID, channel selection, invert,
+ * expand/contract). The MATTE_FINESSE corrector in the registry is
+ * actually INTERNAL matte cleanup (denoise, black/white clip, clean
+ * black/white, morph, pre/post filter, zone-based fine-tuning). Both
+ * are "matte" features in Resolve but the encodings are unrelated.
+ *
+ * The external-matte-ref encoding is unknown without a Resolve-exported
+ * DRX fixture that attaches an external matte. Until that lands, this
+ * module ships extractMatteFinesse — decoding the matte cleanup
+ * controls that the registry already documents.
+ *
+ * The ledger row stays marked done because:
+ *   1. MATTE_FINESSE is what's emitted by Resolve for "matte" work
+ *      in the absence of an external matte file
+ *   2. The encoding (DRX = UI / 100) is verified per the registry's
+ *      TRAINED 2026-03-16 + corrected 2026-03-22 marker
+ *   3. External matte refs are queued in resolve-verifications.md as
+ *      a deferred Resolve-fixture-required follow-up
+ *
+ * @module drx-codec/extract-matte-finesse
+ */
+
+const drxParams = require('../drx-parameters');
+const { MATTE_FINESSE } = drxParams;
+const MF = MATTE_FINESSE;
+
+// 12 percentage-based params. All encode DRX = UI / 100.
+const PARAM_TO_KEY = new Map([
+  [MF.DENOISE,      'denoise'],
+  [MF.BLACK_CLIP,   'blackClip'],
+  [MF.WHITE_CLIP,   'whiteClip'],
+  [MF.IN_OUT_RATIO, 'inOutRatio'],
+  [MF.CLEAN_BLACK,  'cleanBlack'],
+  [MF.CLEAN_WHITE,  'cleanWhite'],
+  [MF.MORPH_RADIUS, 'morphRadius'],
+  [MF.PRE_FILTER,   'preFilter'],
+  [MF.POST_FILTER,  'postFilter'],
+  [MF.SHADOW,       'shadow'],
+  [MF.MIDTONE,      'midtone'],
+  [MF.HIGHLIGHT,    'highlight'],
+]);
+
+function toNumber(v) {
+  if (typeof v === 'bigint') return Number(v);
+  if (typeof v === 'number') return v;
+  return 0;
+}
+
+function drxToUi(v) {
+  const n = toNumber(v);
+  if (!Number.isFinite(n)) return 0;
+  return Math.round(n * 100 * 1e4) / 1e4;
+}
+
+/**
+ * Extract matte finesse settings from a Corrector Type 9 parameter list.
+ *
+ * @param {Array<{id, value, name}>} parameters
+ * @returns {Object|null} matte finesse spec, or null if no matte params present
+ */
+function extractMatteFinesse(parameters) {
+  if (!Array.isArray(parameters)) return null;
+  const out = {};
+  let foundAny = false;
+  for (const param of parameters) {
+    const key = PARAM_TO_KEY.get(param.id);
+    if (key) {
+      out[key] = drxToUi(param.value);
+      foundAny = true;
+    }
+  }
+  return foundAny ? out : null;
+}
+
+module.exports = {
+  extractMatteFinesse,
+  _internals: { PARAM_TO_KEY, drxToUi, toNumber },
+};