@map-audio/pam-mcp-server 1.12.0 → 1.18.1

package/dist/mixAssist.js

@@ -0,0 +1,647 @@
+// GENERATED FILE — do not edit by hand.
+// Vendored from shared/mixAssist/ (server rootDir cannot import outside src/;
+// the fgemma-format.ts precedent). Regenerate with:
+//   node scripts/sync-mixassist.mjs
+// Parity is pinned by interface/test/mixAssistServerParity.test.ts.
+/* eslint-disable */
+// ===== shared/mixAssist/targets.ts =====
+// Mix Assist rule constants. Every clamp/threshold the engine applies lives
+// here so calibration against the factory corpus is a constants-only change.
+// The -lite rules descend from the QMUL cross-adaptive school (Ward partial
+// loudness, Ma DRC regressions, Hafezi masking cuts) — see
+// docs/plans/AUTOMIX_RESEARCH.md §3.1.
+// --- balance (fader) stage ---
+export const MAX_FADER_MOVE_DB = 12; // AUTOMIX_RESEARCH §5 clamp
+export const FADER_EPSILON_DB = 0.3; // no balance pass when every move sits inside this dead-zone
+export const FADER_COMPENSATION_EPSILON_DB = 0.05; // retain 0.1 dB companion moves that preserve bus power
+export const MIN_STEM_LUFS = -50; // quieter stems read as "not sounding" — skipped
+// Ward-lite: dB of effective loudness a fully-masked cell loses (its measured
+// LUFS overstates how loud it reads inside the mix).
+export const MASK_PENALTY_DB_PER_UNIT = 3;
+// Offsets are RELATIVE (the bus normalization cancels any uniform shift).
+// kick sits ABOVE the stem power mean: PAM's genre corpus (techno/house/dnb/
+// trap/boom_bap/drill) mixes kick-forward, and an equal-loudness target that
+// pulls a deliberately hot kick down to the mean reads as the assistant
+// "killing the kick" — especially live, where AUTO feeds this solve into the
+// signed rider every second.
+export const ROLE_OFFSETS_DB = { kick: 2, drums: 0, bass: 0, melodic: -2, ambient: -5 };
+// Fader floor: -60 is the true-mute sentinel (dsp/modules/sampler.ts) — never
+// propose at or below it.
+export const FADER_FLOOR_DB = -59;
+export const FADER_CEIL_DB = 12;
+// --- role classification ---
+export const BASS_LOW_FRACTION = 0.5; // lowFraction() above this = low-dominant
+// Low-dominant cells need a lower onset gate than the generic drum rule: a
+// four-on-the-floor kick is 1.5-2 onsets/sec, and half-time/boom-bap kick
+// patterns sit at 0.5-0.9 (onsetDensity divides by the WHOLE capture, silence
+// included). The crest gate (plr > CREST_ENGAGE_DB) is what separates a kick
+// from a sustained bass; this floor only rejects one-shot rumbles.
+export const LOW_TRANSIENT_ONSET_DENSITY = 0.5;
+// Classifier crest gate for the kick path — deliberately LOWER than the DYN
+// stage's CREST_ENGAGE_DB: a heavily compressed/clipped kick reads PLR 10-13
+// and must still classify as a kick (offset + EQ guard) while staying
+// comp-ineligible (DYN keeps its own 14 dB gate). Sustained basslines read
+// PLR ~6-9 and stay bass.
+export const DRUMS_CREST_MIN_DB = 10;
+export const DRUMS_ONSET_DENSITY = 3; // onsets/sec at or above = drums
+export const AMBIENT_ONSET_DENSITY = 0.3; // at or below (with low crest) = ambient
+export const AMBIENT_MAX_PLR = 8;
+// --- pan stage ---
+export const PAN_EPSILON = 0.05;
+export const MAX_PAN_SPREAD = 0.35; // symmetric spread target
+export const PAN_CENTER_GUARD = 0.15; // cells already panned wider are left alone
+export const BASS_RECENTER_CORR_LOW = 0.7; // master corrLow below this recenters bass
+// --- masking / EQ stage ---
+export const MASKING_PAIR_THRESHOLD = 0.5; // overlap below this never triggers moves
+export const MAX_EQ_CUT_DB = 3; // Hafezi bound
+export const MAX_EQ_LOW_CUT_DB = 1.5; // preserve low-end weight on non-bass maskers
+export const MAX_EQ_CUTS = 2;
+export const EQ_EPSILON_DB = 0.3;
+// --- dynamics (comp) stage ---
+export const CREST_ENGAGE_DB = 14; // plr above this makes a cell comp-eligible
+export const COMP_RATIO_MIN = 1.5;
+export const COMP_RATIO_MAX = 4;
+export const COMP_EPSILON = 0.05;
+// onset density that saturates the percussivity weighting
+export const PERCUSSIVITY_FULL_ONSET_DENSITY = 8;
+// Param defaults for the propose() epsilon gate when `current` lacks a key
+// (values from build.js's manifest defaults).
+export const MIX_PARAM_DEFAULTS = {
+    volume: 0,
+    pan: 0,
+    eqLowGain: 0,
+    eqMidGain: 0,
+    eqHighGain: 0,
+    compressorThreshold: 0,
+    compressorRatioAmount: 2,
+    compressorAttack: 0.5,
+    compressorRelease: 200,
+    compressorRatio: 0, // legacy-mislabelled MAKEUP gain, dB (see build.js)
+};
+export function mixParamDefault(key) {
+    const suffix = key.replace(/^cell\d+_/, '');
+    return MIX_PARAM_DEFAULTS[suffix] ?? 0;
+}
+// ===== shared/mixAssist/bark.ts =====
+// Bark band model — the TS mirror of modules/analysis/BarkScale.h. The 26
+// edge literals MUST match the C++ table verbatim; parity is pinned by
+// interface/test/mixAssistBark.test.ts (and the C++ [mixassist] suite pins
+// the same table's behavior). Change both together or neither.
+export const BARK_BAND_COUNT = 25;
+export const BARK_BAND_EDGES_HZ = [
+    20.0, 100.0, 200.0, 300.0, 400.0, 510.0, 630.0, 770.0, 920.0, 1080.0, 1270.0,
+    1480.0, 1720.0, 2000.0, 2320.0, 2700.0, 3150.0, 3700.0, 4400.0, 5300.0,
+    6400.0, 7700.0, 9500.0, 12000.0, 15500.0, 20000.0,
+];
+export function bandForFrequency(hz) {
+    if (hz <= BARK_BAND_EDGES_HZ[0])
+        return 0;
+    for (let b = 0; b < BARK_BAND_COUNT; b++) {
+        if (hz < BARK_BAND_EDGES_HZ[b + 1])
+            return b;
+    }
+    return BARK_BAND_COUNT - 1;
+}
+// Geometric mean of the band edges — the log-domain center.
+export function barkBandCenterHz(band) {
+    const b = Math.max(0, Math.min(BARK_BAND_COUNT - 1, band));
+    return Math.sqrt(BARK_BAND_EDGES_HZ[b] * BARK_BAND_EDGES_HZ[b + 1]);
+}
+export const dbToPower = (db) => Math.pow(10, db / 10);
+// Power-weighted spectral centroid over band centers, Hz. 0 when silent.
+export function barkCentroidHz(barkDb) {
+    let power = 0;
+    let weighted = 0;
+    for (let b = 0; b < Math.min(barkDb.length, BARK_BAND_COUNT); b++) {
+        const p = dbToPower(barkDb[b]);
+        power += p;
+        weighted += p * barkBandCenterHz(b);
+    }
+    return power > 0 ? weighted / power : 0;
+}
+// Fraction of LINEAR power in bands wholly below `belowHz`. 0 when silent.
+export function lowFraction(barkDb, belowHz = 200) {
+    let total = 0;
+    let low = 0;
+    for (let b = 0; b < Math.min(barkDb.length, BARK_BAND_COUNT); b++) {
+        const p = dbToPower(barkDb[b]);
+        total += p;
+        if (BARK_BAND_EDGES_HZ[b + 1] <= belowHz)
+            low += p;
+    }
+    return total > 0 ? low / total : 0;
+}
+// ===== shared/mixAssist/masking.ts =====
+// Cross-cell Bark-band masking overlap (AutoMix M1). Deliberately simple:
+// textbook objective masking models track perceived masking poorly (Hafezi &
+// Reiss, JAES 2015) — a bounded band-overlap fraction works better as a rule
+// input than a psychoacoustic model.
+// Fraction of A's energy that B overlaps: sum_b min(Pa, Pb) / sum_b Pa.
+// Asymmetric (a quiet cell under a loud one reads ~1; the loud one reads
+// less). 0 when A is silent.
+export function maskingOverlap(aDb, bDb) {
+    let sumA = 0;
+    let shared = 0;
+    const n = Math.min(aDb.length, bDb.length, BARK_BAND_COUNT);
+    for (let b = 0; b < n; b++) {
+        const pa = dbToPower(aDb[b]);
+        const pb = dbToPower(bDb[b]);
+        sumA += pa;
+        shared += Math.min(pa, pb);
+    }
+    return sumA > 0 ? shared / sumA : 0;
+}
+// M[i][j] = fraction of cell i's energy overlapped by cell j. Diagonal 0.
+export function maskingMatrix(barkDbByCell) {
+    const n = barkDbByCell.length;
+    const m = [];
+    for (let i = 0; i < n; i++) {
+        m.push(new Array(n).fill(0));
+        for (let j = 0; j < n; j++) {
+            if (i !== j)
+                m[i][j] = maskingOverlap(barkDbByCell[i], barkDbByCell[j]);
+        }
+    }
+    return m;
+}
+// Region carrying the largest shared power between two stems, split at
+// 300 Hz / 5 kHz — the mixer 3-band EQ's split, so a cut lands on the right
+// knob. Band membership by log-center.
+export function dominantOverlapRegion(aDb, bDb) {
+    const shared = { low: 0, mid: 0, high: 0 };
+    const n = Math.min(aDb.length, bDb.length, BARK_BAND_COUNT);
+    for (let b = 0; b < n; b++) {
+        const center = barkBandCenterHz(b);
+        const region = center < 300 ? 'low' : center >= 5000 ? 'high' : 'mid';
+        shared[region] += Math.min(dbToPower(aDb[b]), dbToPower(bDb[b]));
+    }
+    if (shared.low >= shared.mid && shared.low >= shared.high)
+        return 'low';
+    if (shared.high >= shared.mid)
+        return 'high';
+    return 'mid';
+}
+// ===== shared/mixAssist/parse.ts =====
+const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+function parseStem(raw) {
+    // Number.isFinite per band: one NaN/Infinity entry would silently poison the
+    // masking matrix (dbToPower propagates it through every overlap sum).
+    const bark = Array.isArray(raw.bark) && raw.bark.every((b) => typeof b === 'number' && Number.isFinite(b))
+        ? raw.bark
+        : null;
+    if (!bark)
+        return null;
+    return {
+        lufsI: num(raw.i),
+        lufsS: num(raw.s),
+        lufsRoll: num(raw.roll),
+        lra: num(raw.lra),
+        truePeakDb: num(raw.tp),
+        samplePeakDb: num(raw.sp),
+        psr: num(raw.psr),
+        plr: num(raw.plr),
+        corr: num(raw.corr),
+        corrLow: num(raw.corrLow),
+        onsets: num(raw.onsets) ?? 0,
+        onsetDensity: num(raw.onsetDensity) ?? 0,
+        seconds: num(raw.secs) ?? 0,
+        barkDb: bark,
+    };
+}
+// Maps the native analyzeMixStems payload (short keys, sentinel fields
+// dropped) into the shared MixAnalysis shape. Returns null on anything
+// malformed — callers treat that as "no analysis".
+export function parseMixAnalysisPayload(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const o = raw;
+    if (!Array.isArray(o.cells) || typeof o.master !== 'object' || o.master === null)
+        return null;
+    const cells = [];
+    for (const c of o.cells) {
+        if (typeof c !== 'object' || c === null)
+            return null;
+        const stem = parseStem(c);
+        const cellId = num(c.cellId);
+        if (!stem || cellId === undefined)
+            return null;
+        cells.push({ cellId, ...stem });
+    }
+    const master = parseStem(o.master);
+    if (!master)
+        return null;
+    return {
+        epoch: num(o.epoch) ?? 0,
+        live: o.live === true,
+        sampleRate: num(o.sampleRate) ?? 48000,
+        durationSeconds: num(o.durationSeconds) ?? 0,
+        bpm: num(o.bpm) ?? 120,
+        cells,
+        master,
+    };
+}
+// The Knob.tsx mod-badge idiom: envelopes/vary/paramSeqs match by paramId;
+// LFO and macro links count only when enabled. Macro exclusions are per cell.
+export function paramIsModulated(lists, paramId) {
+    if (lists.envelopes?.some((e) => e?.paramId === paramId))
+        return true;
+    if (lists.lfos?.some((l) => l?.paramId === paramId && (l.enabled === 1 || l.enabled === true)))
+        return true;
+    if (lists.vary?.some((v) => v?.paramId === paramId))
+        return true;
+    if (lists.paramSeqs?.some((p) => p?.paramId === paramId))
+        return true;
+    const match = paramId.match(/^cell(\d+)_(.+)$/);
+    if (!match)
+        return false;
+    const cellId = Number(match[1]);
+    const macroId = `macro_${match[2]}`;
+    const macro = lists.macros?.find((m) => m.paramId === macroId && (m.enabled === 1 || m.enabled === true));
+    return macro !== undefined && Number(macro[`exclude_cell${cellId}`] ?? 0) <= 0.5;
+}
+const numOr = (v, d) => typeof v === 'number' && Number.isFinite(v) ? v : d;
+const EQ_SUFFIXES = ['eqLowGain', 'eqMidGain', 'eqHighGain'];
+const COMP_SUFFIXES = [
+    'compressorThreshold',
+    'compressorRatioAmount',
+    'compressorAttack',
+    'compressorRelease',
+    'compressorRatio', // legacy-mislabelled MAKEUP gain (see build.js)
+];
+export const MIX_CURRENT_SUFFIXES = [
+    'volume',
+    'pan',
+    ...EQ_SUFFIXES,
+    ...COMP_SUFFIXES,
+];
+export function buildMixMeasurementFromState(analysis, flatState, mods = {}, options = {}) {
+    const cells = analysis.cells.map((a) => {
+        const id = a.cellId;
+        const k = (suffix) => flatState[`cell${id}_${suffix}`];
+        const context = {
+            cellId: id,
+            // Cached analysis may outlive its source; callers with live state supply
+            // the current presence check, while headless callers retain legacy true.
+            hasSource: options.hasSource?.(id) ?? true,
+            muted: numOr(k('mute'), 0) > 0.5,
+            soloed: numOr(k('solo'), 0) > 0.5,
+            volume: numOr(k('volume'), 0),
+            pan: numOr(k('pan'), 0),
+            eqLowGain: numOr(k('eqLowGain'), 0),
+            eqMidGain: numOr(k('eqMidGain'), 0),
+            eqHighGain: numOr(k('eqHighGain'), 0),
+            eqEnabled: numOr(k('eqEnabled'), 0) > 0.5,
+            compressorEnabled: numOr(k('compressorEnabled'), 0) > 0.5,
+            compressorThreshold: numOr(k('compressorThreshold'), 0),
+            compressorRatioAmount: numOr(k('compressorRatioAmount'), 2),
+            compressorAttack: numOr(k('compressorAttack'), 0.5),
+            compressorRelease: numOr(k('compressorRelease'), 200),
+            volumeModulated: paramIsModulated(mods, `cell${id}_volume`),
+            panModulated: paramIsModulated(mods, `cell${id}_pan`),
+            eqModulated: EQ_SUFFIXES.some((s) => paramIsModulated(mods, `cell${id}_${s}`)),
+            compModulated: COMP_SUFFIXES.some((s) => paramIsModulated(mods, `cell${id}_${s}`)),
+        };
+        return { analysis: a, context };
+    });
+    return {
+        cells,
+        masterLufsI: analysis.master.lufsI,
+        masterCorrLow: analysis.master.corrLow,
+        epoch: analysis.epoch,
+    };
+}
+// The `current` record suggestMix diffs proposals against — every actuator key
+// of every analyzed cell, read from the same flat state.
+export function currentFlatFromState(analysis, flatState) {
+    const current = {};
+    for (const c of analysis.cells) {
+        for (const suffix of MIX_CURRENT_SUFFIXES) {
+            const key = `cell${c.cellId}_${suffix}`;
+            const v = flatState[key];
+            if (typeof v === 'number' && Number.isFinite(v))
+                current[key] = v;
+        }
+    }
+    return current;
+}
+// ===== shared/mixAssist/engine.ts =====
+// Mix Assist rule engine (AutoMix M2). Pure and deterministic — no stores, no
+// clock, no RNG. Mirrors shared/masterAssistant/engine.ts's contract: moves
+// carry ABSOLUTE target values, only keys that differ from `current` beyond an
+// epsilon are emitted (the idempotence contract), and every guard leaves a
+// guardsHit note instead of failing silently.
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const round1 = (v) => Math.round(v * 10) / 10;
+const round2 = (v) => Math.round(v * 100) / 100;
+export function isLowDominant(a) {
+    return lowFraction(a.barkDb) > BASS_LOW_FRACTION;
+}
+export function classifyCellRole(a) {
+    const lowDominant = isLowDominant(a);
+    // DRUMS_CREST_MIN_DB, not CREST_ENGAGE_DB: a compressed/clipped kick reads
+    // PLR 10-13 and must still take the kick path (offset + EQ guard) while
+    // staying out of the DYN stage, which keeps its own 14 dB gate.
+    const kickCrest = (a.plr ?? 0) > DRUMS_CREST_MIN_DB;
+    if (lowDominant && kickCrest && a.onsetDensity >= LOW_TRANSIENT_ONSET_DENSITY)
+        return 'kick';
+    if (lowDominant)
+        return 'bass';
+    if (a.onsetDensity >= DRUMS_ONSET_DENSITY)
+        return 'drums';
+    if (a.onsetDensity <= AMBIENT_ONSET_DENSITY && (a.plr ?? 0) < AMBIENT_MAX_PLR)
+        return 'ambient';
+    return 'melodic';
+}
+// Shift all deltas by one common offset so the summed bus power is preserved:
+// offset = 10log10(sum 10^((L+d)/10) / sum 10^(L/10)); subtracting it from
+// every delta lands the post-move sum exactly on the pre-move sum. Uniform
+// role offsets therefore cancel — only RELATIVE differences move faders.
+export function normalizeMovesToBus(deltasDb, lufs) {
+    let before = 0;
+    let after = 0;
+    for (let i = 0; i < deltasDb.length; i++) {
+        before += Math.pow(10, lufs[i] / 10);
+        after += Math.pow(10, (lufs[i] + deltasDb[i]) / 10);
+    }
+    if (before <= 0 || after <= 0)
+        return deltasDb.slice();
+    const offset = 10 * Math.log10(after / before);
+    return deltasDb.map((d) => d - offset);
+}
+export function normalizeMovesToBusBounded(rawDeltasDb, lufs, currentVolumes) {
+    if (rawDeltasDb.length === 0)
+        return [];
+    const powers = lufs.map((l) => Math.pow(10, l / 10));
+    const before = powers.reduce((sum, power) => sum + power, 0);
+    if (before <= 0)
+        return rawDeltasDb.slice();
+    const lower = currentVolumes.map((v) => Math.max(-MAX_FADER_MOVE_DB, FADER_FLOOR_DB - v));
+    const upper = currentVolumes.map((v) => Math.min(MAX_FADER_MOVE_DB, FADER_CEIL_DB - v));
+    const deltasAt = (offset) => rawDeltasDb.map((d, i) => clamp(d - offset, lower[i], upper[i]));
+    const errorAt = (offset) => {
+        const deltas = deltasAt(offset);
+        let after = 0;
+        for (let i = 0; i < deltas.length; i++)
+            after += powers[i] * Math.pow(10, deltas[i] / 10);
+        return after - before;
+    };
+    let lo = -120;
+    let hi = 120;
+    for (let iteration = 0; iteration < 80; iteration++) {
+        const mid = 0.5 * (lo + hi);
+        if (errorAt(mid) > 0)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return deltasAt(0.5 * (lo + hi));
+}
+export function suggestMix(m, options, current = {}) {
+    const moves = [];
+    const guardsHit = [];
+    const flat = {};
+    const scope = new Set(options.scopes);
+    const cur = (key) => current[key] ?? mixParamDefault(key);
+    const propose = (cellId, key, value, why, epsilon) => {
+        if (Math.abs(value - cur(key)) > epsilon) {
+            moves.push({ key, value, why, cellId });
+            flat[key] = value;
+        }
+    };
+    // ---- eligibility -------------------------------------------------------
+    const anySolo = m.cells.some((c) => c.context.soloed);
+    const sorted = [...m.cells].sort((a, b) => a.context.cellId - b.context.cellId);
+    const participants = [];
+    for (const cell of sorted) {
+        const ctx = cell.context;
+        if (!ctx.hasSource || ctx.muted)
+            continue;
+        if (anySolo && !ctx.soloed)
+            continue;
+        const lufs = cell.analysis.lufsI ?? cell.analysis.lufsS;
+        if (lufs === undefined || lufs <= MIN_STEM_LUFS)
+            continue;
+        participants.push({
+            cell,
+            lufs,
+            effectiveLufs: lufs,
+            maskedFraction: 0,
+            role: classifyCellRole(cell.analysis),
+            lowDominant: isLowDominant(cell.analysis),
+            index: participants.length,
+        });
+    }
+    if (participants.length < 2) {
+        return {
+            moves: [],
+            guardsHit: [],
+            flat: {},
+            summary: 'Nothing to balance — fewer than two sounding cells',
+        };
+    }
+    // ---- masking matrix (Ward-lite partial-loudness correction) ------------
+    const matrix = maskingMatrix(participants.map((p) => p.cell.analysis.barkDb));
+    for (const p of participants) {
+        let masked = 0;
+        for (const q of participants) {
+            if (q.index !== p.index)
+                masked = Math.max(masked, matrix[p.index][q.index]);
+        }
+        p.maskedFraction = masked;
+        p.effectiveLufs = p.lufs - MASK_PENALTY_DB_PER_UNIT * masked;
+    }
+    // ---- BAL: partial-loudness fader balance --------------------------------
+    if (scope.has('balance')) {
+        // Loudness-power mean of the masking-corrected levels.
+        let meanPower = 0;
+        for (const p of participants)
+            meanPower += Math.pow(10, p.effectiveLufs / 10);
+        const ref = 10 * Math.log10(meanPower / participants.length);
+        const rawDeltas = participants.map((p) => ref + ROLE_OFFSETS_DB[p.role] - p.effectiveLufs);
+        // Guarded cells hold still. The bounded solve preserves the movable subset's
+        // power while respecting both the per-pass move cap and remaining fader travel.
+        const movable = participants.map((p) => !p.cell.context.volumeModulated);
+        const movableParticipants = participants.filter((_, i) => movable[i]);
+        const movableRawDeltas = rawDeltas.filter((_, i) => movable[i]);
+        const movableLufs = movableParticipants.map((p) => p.lufs);
+        const unconstrainedDeltas = normalizeMovesToBus(movableRawDeltas, movableLufs);
+        const movableDeltas = normalizeMovesToBusBounded(movableRawDeltas, movableLufs, movableParticipants.map((p) => cur(`cell${p.cell.context.cellId}_volume`)));
+        const hasPrimaryMove = movableDeltas.some((d) => Math.abs(d) > FADER_EPSILON_DB);
+        const balanceEpsilon = hasPrimaryMove ? FADER_COMPENSATION_EPSILON_DB : FADER_EPSILON_DB;
+        let mi = 0;
+        for (let i = 0; i < participants.length; i++) {
+            const p = participants[i];
+            const id = p.cell.context.cellId;
+            if (!movable[i]) {
+                guardsHit.push(`cell ${id} volume is modulated — left alone`);
+                continue;
+            }
+            const moveIndex = mi++;
+            const d = movableDeltas[moveIndex];
+            if (Math.abs(d - unconstrainedDeltas[moveIndex]) > FADER_EPSILON_DB)
+                guardsHit.push(`cell ${id} balance move limited by fader range`);
+            const key = `cell${id}_volume`;
+            const value = round1(cur(key) + d);
+            const direction = d >= 0 ? 'up' : 'down';
+            const excess = rawDeltas[i];
+            propose(cellId(p), key, value, `cell ${id} sits ${round1(Math.abs(excess))} dB ${excess < 0 ? 'above' : 'below'} the balance — ${direction} ${round1(Math.abs(d))} dB`, balanceEpsilon);
+        }
+    }
+    // ---- PAN: spread the worst-masked non-bass pair -------------------------
+    if (scope.has('pan')) {
+        const loudest = participants.reduce((a, b) => (b.effectiveLufs > a.effectiveLufs ? b : a));
+        let best = null;
+        for (let i = 0; i < participants.length; i++) {
+            for (let j = i + 1; j < participants.length; j++) {
+                const a = participants[i];
+                const b = participants[j];
+                if (a.lowDominant || b.lowDominant)
+                    continue;
+                if (a === loudest || b === loudest)
+                    continue;
+                const actx = a.cell.context;
+                const bctx = b.cell.context;
+                if (Math.abs(actx.pan) >= PAN_CENTER_GUARD || Math.abs(bctx.pan) >= PAN_CENTER_GUARD)
+                    continue;
+                if (actx.panModulated || bctx.panModulated)
+                    continue;
+                const overlap = Math.min(matrix[a.index][b.index], matrix[b.index][a.index]);
+                if (overlap < MASKING_PAIR_THRESHOLD)
+                    continue;
+                if (dominantOverlapRegion(a.cell.analysis.barkDb, b.cell.analysis.barkDb) === 'low')
+                    continue;
+                if (!best || overlap > best.overlap)
+                    best = { a, b, overlap };
+            }
+        }
+        if (best) {
+            const idA = best.a.cell.context.cellId;
+            const idB = best.b.cell.context.cellId;
+            const why = `cells ${idA} and ${idB} share ${Math.round(best.overlap * 100)}% of their spectrum — pan apart`;
+            propose(idA, `cell${idA}_pan`, -MAX_PAN_SPREAD, why, PAN_EPSILON);
+            propose(idB, `cell${idB}_pan`, MAX_PAN_SPREAD, why, PAN_EPSILON);
+        }
+        // Bass recenter, only when the master's low band actually reads unstable.
+        if (m.masterCorrLow !== undefined && m.masterCorrLow < BASS_RECENTER_CORR_LOW) {
+            for (const p of participants) {
+                const ctx = p.cell.context;
+                if (!p.lowDominant || Math.abs(ctx.pan) <= PAN_CENTER_GUARD || ctx.panModulated)
+                    continue;
+                propose(ctx.cellId, `cell${ctx.cellId}_pan`, 0, `bass cancels in mono (correlation ${round2(m.masterCorrLow)}) — center it`, PAN_EPSILON);
+            }
+        }
+    }
+    // ---- EQ: bounded masking cuts on the masker's mixer 3-band --------------
+    if (scope.has('eq')) {
+        const candidates = [];
+        for (let i = 0; i < participants.length; i++) {
+            for (let j = i + 1; j < participants.length; j++) {
+                const a = participants[i];
+                const b = participants[j];
+                const overlap = Math.max(matrix[a.index][b.index], matrix[b.index][a.index]);
+                if (overlap < MASKING_PAIR_THRESHOLD)
+                    continue;
+                const masker = a.effectiveLufs >= b.effectiveLufs ? a : b;
+                const masked = masker === a ? b : a;
+                candidates.push({ masked, masker, overlap });
+            }
+        }
+        candidates.sort((x, y) => y.overlap - x.overlap);
+        const usedMaskers = new Set();
+        let cuts = 0;
+        for (const c of candidates) {
+            if (cuts >= MAX_EQ_CUTS)
+                break;
+            const maskerCtx = c.masker.cell.context;
+            const id = maskerCtx.cellId;
+            if (usedMaskers.has(id))
+                continue;
+            if (maskerCtx.eqModulated) {
+                guardsHit.push(`cell ${id} mixer EQ is modulated — no masking cut`);
+                continue;
+            }
+            const region = dominantOverlapRegion(c.masked.cell.analysis.barkDb, c.masker.cell.analysis.barkDb);
+            // Never carve the fundamental of a low-dominant source. Kick and bass
+            // conflicts belong to balance or sidechain, not a broad static low cut.
+            // Non-low-dominant sources can still be trimmed gently when their low
+            // spill masks another cell.
+            if (region === 'low' && c.masker.lowDominant) {
+                guardsHit.push(`cell ${id} is low-dominant — its low band is left alone`);
+                continue;
+            }
+            const band = region === 'low' ? 'eqLowGain' : region === 'high' ? 'eqHighGain' : 'eqMidGain';
+            const key = `cell${id}_${band}`;
+            const maxCutDb = region === 'low' ? MAX_EQ_LOW_CUT_DB : MAX_EQ_CUT_DB;
+            const cutDb = Math.min(maxCutDb, 6 * c.overlap - 2);
+            if (cutDb <= EQ_EPSILON_DB)
+                continue;
+            const value = round1(cur(key) - cutDb);
+            propose(id, key, value, `cell ${id} covers cell ${c.masked.cell.context.cellId} in the ${region} band — cut ${round1(cutDb)} dB`, EQ_EPSILON_DB);
+            if (flat[key] !== undefined && !maskerCtx.eqEnabled) {
+                flat[`cell${id}_eqEnabled`] = 1;
+                guardsHit.push(`cell ${id} mixer EQ enabled for the cut`);
+            }
+            usedMaskers.add(id);
+            cuts++;
+        }
+    }
+    // ---- DYN: Ma-lite comp settings on crest-heavy percussive cells ---------
+    if (scope.has('dynamics')) {
+        for (const p of participants) {
+            const ctx = p.cell.context;
+            const a = p.cell.analysis;
+            const id = ctx.cellId;
+            if (a.plr === undefined || a.plr <= CREST_ENGAGE_DB)
+                continue;
+            if (p.role !== 'drums' && p.role !== 'melodic' && p.role !== 'kick')
+                continue;
+            if (ctx.compModulated) {
+                guardsHit.push(`cell ${id} compressor is modulated — left alone`);
+                continue;
+            }
+            if (ctx.compressorEnabled) {
+                guardsHit.push(`cell ${id} compressor is already set up — left alone`);
+                continue;
+            }
+            const wp = Math.min(1, a.onsetDensity / PERCUSSIVITY_FULL_ONSET_DENSITY);
+            const ratio = round2(clamp(1.5 + 2.5 * wp, COMP_RATIO_MIN, COMP_RATIO_MAX));
+            // Stems are measured POST-fader but the compressor sits PRE-fader in the
+            // cell FX chain — divide the fader out (rideProfile.ts does the same for
+            // the rider's shares) or a trimmed cell gets a threshold too deep by its
+            // fader offset and over-compresses.
+            const stemLufs = (a.lufsS ?? a.lufsI ?? -20) - ctx.volume;
+            const threshold = round1(clamp(stemLufs + 6, -40, -3));
+            const attack = round2(clamp(2 + 25 * (1 - wp), 2, 30));
+            const release = round1(clamp(50 + 250 * (1 - wp), 50, 300));
+            // Half-compensate the peak gain reduction on the legacy-mislabelled
+            // MAKEUP key (`compressorRatio`, dB — see build.js). Without it the
+            // auto-enabled comp quietly lowers the cell and BAL, which ran on the
+            // pre-comp measurement, never sees the loss.
+            const peak = stemLufs + a.plr;
+            const makeup = round1(clamp((peak - threshold) * (1 - 1 / ratio) * 0.5, 0, 20));
+            const why = `cell ${id} spikes ${round1(a.plr)} dB over its loudness — soften the peaks`;
+            propose(id, `cell${id}_compressorThreshold`, threshold, why, COMP_EPSILON);
+            propose(id, `cell${id}_compressorRatioAmount`, ratio, why, COMP_EPSILON);
+            propose(id, `cell${id}_compressorAttack`, attack, why, COMP_EPSILON);
+            propose(id, `cell${id}_compressorRelease`, release, why, COMP_EPSILON);
+            propose(id, `cell${id}_compressorRatio`, makeup, why, COMP_EPSILON);
+            if (moves.some((mv) => mv.cellId === id && mv.key.startsWith(`cell${id}_compressor`))) {
+                flat[`cell${id}_compressorEnabled`] = 1;
+                guardsHit.push(`cell ${id} compressor enabled`);
+            }
+        }
+    }
+    if (moves.length === 0) {
+        return {
+            moves,
+            guardsHit,
+            flat: {},
+            summary: 'Mix reads balanced — nothing to move',
+        };
+    }
+    return { moves, guardsHit, flat };
+}
+function cellId(p) {
+    return p.cell.context.cellId;
+}
+//# sourceMappingURL=mixAssist.js.map