@map-audio/pam-mcp-server 1.21.0 → 1.25.0

package/dist/fingerprint.js

@@ -0,0 +1,240 @@
+// Preset fingerprinting — the shared algorithm behind the corpus index
+// (scripts/derive-corpus-fingerprints.ts) and the preset_novelty tool.
+//
+// WHY: nothing in the design pipeline ever compared a new preset against the
+// ones already shipped, so every session started from the same prior and landed
+// on the same centroid preset. A fingerprint plus a distance makes "does this
+// already exist?" a number instead of a judgement call.
+//
+// The dimensions are deliberately structural rather than acoustic — they read
+// straight off preset state, so novelty can be scored with no render, no audio
+// and no plugin connection.
+const asArray = (v) => {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            return Array.isArray(p) ? p : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+};
+const asRecord = (v) => {
+    if (typeof v === "string") {
+        try {
+            const p = JSON.parse(v);
+            return p && typeof p === "object" ? p : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return v && typeof v === "object" ? v : {};
+};
+/** Strip take numbers, bpm tags and separators so "Kick_03_120bpm" and
+ *  "kick-05" read as the same source. Two presets built from the same folder
+ *  should look similar even when the exact files differ. */
+const normalizeSource = (path) => path
+    .split(/[\\/]/)
+    .pop()
+    .replace(/\.[a-z0-9]+$/i, "")
+    .toLowerCase()
+    .replace(/\d+\s*bpm/g, "")
+    .replace(/[\d_\-\s]+/g, "")
+    .slice(0, 24);
+/** Param suffix from a modulation link's target, so cell3_filterCutoff and
+ *  cell7_filterCutoff count as the same kind of move. */
+const targetFamily = (paramId) => typeof paramId === "string" ? paramId.replace(/^cell\d+_/, "").replace(/^macro_/, "macro:") : null;
+export function buildFingerprint(state, defaults, effectNames, name = "candidate") {
+    const params = new Set();
+    const fx = new Set();
+    const chains = new Set();
+    const groove = [];
+    const pitch = new Set();
+    const engines = new Set();
+    let cells = 0;
+    for (let c = 1; c <= 8; c += 1) {
+        const seq = asArray(state[`cell${c}_midiSequence`]);
+        if (seq.length === 0)
+            continue;
+        cells += 1;
+        // The per-effect enable flags are state-only — they are NOT manifest
+        // parameters, so they never reach the defaults map below and have to be
+        // read directly. Missing this silently produced an empty fx set on every
+        // preset in the corpus index.
+        for (const slug of effectNames) {
+            if (state[`cell${c}_${slug}Enabled`])
+                fx.add(slug);
+        }
+        for (const [key, value] of Object.entries(state)) {
+            if (!key.startsWith(`cell${c}_`) || typeof value !== "number")
+                continue;
+            const suffix = key.slice(`cell${c}_`.length);
+            const def = defaults[suffix];
+            // A param at its default was never a decision. Only moved params
+            // describe the preset.
+            if (def === undefined || value === def)
+                continue;
+            params.add(suffix);
+        }
+        const order = asArray(state[`cell${c}_effectOrder`]).filter((s) => typeof s === "string");
+        if (order.length)
+            chains.add(order.join(">"));
+        // Onsets quantized to 16ths of a bar. `time` is in beats, so ×4 is a 16th
+        // grid; folding mod 16 compares the groove rather than the bar count.
+        const steps = new Set();
+        for (const ev of seq) {
+            const t = ev.time;
+            if (typeof t === "number")
+                steps.add(Math.round(t * 4) % 16);
+        }
+        if (steps.size)
+            groove.push(`c${c}:${[...steps].sort((a, b) => a - b).join(",")}`);
+        const ps = state[`cell${c}_pitchShift`];
+        if (typeof ps === "number" && ps !== 0)
+            pitch.add(ps);
+        const ar = state[`cell${c}_arpeg`];
+        if (typeof ar === "number" && ar !== 0)
+            pitch.add(ar);
+        for (const ev of asArray(state[`cell${c}_pitchSequence`])) {
+            const v = ev.value;
+            if (typeof v === "number" && v !== 0)
+                pitch.add(v);
+        }
+        const eng = state[`cell${c}_synthEngine`];
+        if (typeof eng === "number" && eng > 0)
+            engines.add(eng);
+    }
+    const modTargets = new Set();
+    const countLinks = (key) => {
+        const links = asArray(state[key]);
+        for (const l of links) {
+            const fam = targetFamily(l.paramId);
+            if (fam)
+                modTargets.add(fam);
+        }
+        return links.length;
+    };
+    const sources = new Set();
+    const cellMap = asRecord(state.cells);
+    for (const entry of Object.values(cellMap)) {
+        const fp = entry.filePath;
+        if (typeof fp === "string" && fp.length > 2)
+            sources.add(normalizeSource(fp));
+    }
+    const bpmRaw = asRecord(state.transport).bpm ?? state.bpm;
+    return {
+        name,
+        bpm: typeof bpmRaw === "number" ? bpmRaw : 0,
+        cells,
+        params: [...params].sort(),
+        fx: [...fx].sort(),
+        chains: [...chains].sort(),
+        mod: {
+            lfo: countLinks("lfos"),
+            env: countLinks("envelopes"),
+            vary: countLinks("vary"),
+            seq: countLinks("paramSeqs"),
+            targets: [...modTargets].sort(),
+        },
+        groove: groove.sort(),
+        pitch: [...pitch].sort((a, b) => a - b),
+        sources: [...sources].sort(),
+        engines: [...engines].sort((a, b) => a - b),
+    };
+}
+const jaccard = (a, b) => {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const setB = new Set(b);
+    let shared = 0;
+    for (const x of new Set(a))
+        if (setB.has(x))
+            shared += 1;
+    const union = new Set([...a, ...b]).size;
+    return union === 0 ? 1 : shared / union;
+};
+/** Groove similarity ignores which cell a rhythm sat on — the same pattern
+ *  moved from cell 3 to cell 5 is still the same pattern. */
+const grooveSimilarity = (a, b) => jaccard(a.map((g) => g.split(":")[1] ?? ""), b.map((g) => g.split(":")[1] ?? ""));
+const modSimilarity = (a, b) => {
+    const density = (m) => m.lfo + m.env + m.vary + m.seq;
+    const da = density(a);
+    const db = density(b);
+    const scale = Math.max(da, db) || 1;
+    const densityMatch = 1 - Math.abs(da - db) / scale;
+    // What is modulated matters more than how much of it there is.
+    return 0.35 * densityMatch + 0.65 * jaccard(a.targets, b.targets);
+};
+/** Dimension weights. Groove and params dominate because they are what a
+ *  listener names first when two presets "sound the same". */
+const WEIGHTS = { params: 0.24, groove: 0.24, mod: 0.18, sources: 0.16, fx: 0.08, chains: 0.05, pitch: 0.05 };
+export function similarity(a, b) {
+    const byDimension = {
+        params: jaccard(a.params, b.params),
+        groove: grooveSimilarity(a.groove, b.groove),
+        mod: modSimilarity(a.mod, b.mod),
+        sources: jaccard(a.sources, b.sources),
+        fx: jaccard(a.fx, b.fx),
+        chains: jaccard(a.chains, b.chains),
+        pitch: jaccard(a.pitch.map(String), b.pitch.map(String)),
+    };
+    let overall = 0;
+    for (const [dim, w] of Object.entries(WEIGHTS)) {
+        overall += w * byDimension[dim];
+    }
+    return { overall, byDimension };
+}
+/** Score a candidate against a corpus. novelty = 1 - closest match, so 0 means
+ *  "this already exists" and 1 means "nothing like it has shipped". */
+export function scoreNovelty(candidate, corpus, topN = 5, baseline) {
+    const scored = corpus
+        .map((other) => ({ other, sim: similarity(candidate, other) }))
+        .sort((x, y) => y.sim.overall - x.sim.overall)
+        .slice(0, topN);
+    const nearest = scored.map(({ other, sim }) => ({
+        name: other.name,
+        similarity: Math.round(sim.overall * 1000) / 1000,
+        // Dimensions where the candidate is essentially a copy. These are the
+        // actionable part of the report — they name what to change.
+        duplicatedDimensions: Object.entries(sim.byDimension)
+            .filter(([, v]) => v >= 0.7)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k, v]) => `${k} ${Math.round(v * 100)}%`),
+    }));
+    const top = scored[0]?.sim.overall ?? 0;
+    const novelty = Math.round((1 - top) * 1000) / 1000;
+    let verdict;
+    let percentileVsCorpus = null;
+    if (baseline) {
+        // Linear interpolation across the three known percentiles is enough for a
+        // verdict — this is a calibration aid, not a statistic.
+        if (novelty <= baseline.p10)
+            percentileVsCorpus = Math.max(0, Math.round((10 * novelty) / baseline.p10));
+        else if (novelty <= baseline.p50)
+            percentileVsCorpus = Math.round(10 + (40 * (novelty - baseline.p10)) / (baseline.p50 - baseline.p10));
+        else if (novelty <= baseline.p90)
+            percentileVsCorpus = Math.round(50 + (40 * (novelty - baseline.p50)) / (baseline.p90 - baseline.p50));
+        else
+            percentileVsCorpus = Math.min(100, Math.round(90 + (10 * (novelty - baseline.p90)) / (1 - baseline.p90)));
+        verdict =
+            novelty < baseline.floor
+                ? `More derivative than ANY pair in the shipped corpus (the closest shipped pair scores ${baseline.floor}). Redesign the duplicated dimensions before saving.`
+                : novelty < baseline.p10
+                    ? "More derivative than 90% of shipped presets. Change at least one duplicated dimension."
+                    : novelty < baseline.p50
+                        ? "Below the corpus median for distinctness. Acceptable, but the duplicated dimensions are where it blends in."
+                        : novelty < baseline.p90
+                            ? "Distinct at or above the corpus median."
+                            : "More distinct than 90% of shipped presets.";
+    }
+    else {
+        verdict = `Nearest-neighbour similarity ${Math.round(top * 100)}%. No corpus baseline supplied, so this number is only comparable against other runs.`;
+    }
+    return { novelty, percentileVsCorpus, nearest, verdict };
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/generated/variationSnapshot.d.ts

@@ -1,6 +1,10 @@
 export interface VariationSnapshotContract {
     /** Session keys a variation must not carry (shared/variationSessionKeys.json). */
     sessionKeys: readonly string[];
+    /** The in-flight dispatch flags (StateShape's Transient group). A stored one
+     *  is read back as an instruction — a slot carrying `__fadeMs__` crossfades
+     *  the next load at the fade the FILE holds, not the one the loader asked for. */
+    transientKeys: readonly string[];
     /** Visual audio-react paramIds — they persist ACROSS variations, so they are
      *  stripped from every snapshot rather than captured per slot. */
     visualParamIds: readonly string[];
@@ -23,9 +27,9 @@ export declare function reconcileLfoGeneratorEnabledState(snapshot: Record<strin
 /**
  * Shape a variation snapshot from plugin state.
  *
- * Order matters and is part of the contract: strip session keys, drop the
- * active-preset path, strip visual params, narrow for FX products, then
- * reconcile the LFO generator flags LAST — the reconcile reads `lfos`, which
- * the earlier steps may have removed.
+ * Order matters and is part of the contract: strip session keys and the
+ * transient dispatch flags, drop the active-preset path, strip visual params,
+ * narrow for FX products, then reconcile the LFO generator flags LAST — the
+ * reconcile reads `lfos`, which the earlier steps may have removed.
  */
 export declare function buildVariationSnapshotBase(state: Record<string, unknown>, contract: VariationSnapshotContract, options?: VariationSnapshotOptions): Record<string, unknown>;

package/dist/generated/variationSnapshot.js

@@ -42,15 +42,17 @@ export function reconcileLfoGeneratorEnabledState(snapshot, lfoGeneratorCount) {
 /**
  * Shape a variation snapshot from plugin state.
  *
- * Order matters and is part of the contract: strip session keys, drop the
- * active-preset path, strip visual params, narrow for FX products, then
- * reconcile the LFO generator flags LAST — the reconcile reads `lfos`, which
- * the earlier steps may have removed.
+ * Order matters and is part of the contract: strip session keys and the
+ * transient dispatch flags, drop the active-preset path, strip visual params,
+ * narrow for FX products, then reconcile the LFO generator flags LAST — the
+ * reconcile reads `lfos`, which the earlier steps may have removed.
  */
 export function buildVariationSnapshotBase(state, contract, options = {}) {
     const snapshot = { ...state };
     for (const key of contract.sessionKeys)
         delete snapshot[key];
+    for (const key of contract.transientKeys)
+        delete snapshot[key];
     delete snapshot.activePresetPath;
     for (const paramId of contract.visualParamIds)
         delete snapshot[paramId];

package/dist/generated/variationSnapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"variationSnapshot.js","sourceRoot":"","sources":["../../src/generated/variationSnapshot.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,+DAA+D;AAC/D,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,8DAA8D;AAuB9D;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC,CAC/C,QAAiC,EACjC,iBAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAM;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAiB,CAAA;IAEvC,KAAK,IAAI,cAAc,GAAG,CAAC,EAAE,cAAc,IAAI,iBAAiB,EAAE,cAAc,EAAE,EAAE,CAAC;QACnF,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAC/B,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,EAAE,iBAAiB,KAAK,cAAc;YACzC,CAAC,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC;YACzB,OAAO,GAAG,EAAE,OAAO,KAAK,QAAQ;YAChC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CACzB,CAAA;QACD,QAAQ,CAAC,MAAM,cAAc,UAAU,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAA8B,EAC9B,QAAmC,EACnC,UAAoC,EAAE;IAEtC,MAAM,QAAQ,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAA;IAEtD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC5D,OAAO,QAAQ,CAAC,gBAAgB,CAAA;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;IACvE,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAA;IAE7C,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC"}
+{"version":3,"file":"variationSnapshot.js","sourceRoot":"","sources":["../../src/generated/variationSnapshot.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,+DAA+D;AAC/D,sDAAsD;AACtD,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,8DAA8D;AA2B9D;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC,CAC/C,QAAiC,EACjC,iBAAyB;IAEzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAM;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAiB,CAAA;IAEvC,KAAK,IAAI,cAAc,GAAG,CAAC,EAAE,cAAc,IAAI,iBAAiB,EAAE,cAAc,EAAE,EAAE,CAAC;QACnF,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAC/B,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,EAAE,iBAAiB,KAAK,cAAc;YACzC,CAAC,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC;YACzB,OAAO,GAAG,EAAE,OAAO,KAAK,QAAQ;YAChC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CACzB,CAAA;QACD,QAAQ,CAAC,MAAM,cAAc,UAAU,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAA8B,EAC9B,QAAmC,EACnC,UAAoC,EAAE;IAEtC,MAAM,QAAQ,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAA;IAEtD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC5D,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,aAAa;QAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC9D,OAAO,QAAQ,CAAC,gBAAgB,CAAA;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAA;IACvE,IAAI,OAAO,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAA;IAE7C,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACvE,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/generativePlayerPresets.json

@@ -0,0 +1,70 @@
+{
+  "_doc": "Curated per-player starting points for the generative Players — the 'one-click start' rung of the type -> preset -> dice -> knobs ladder (docs/research/2026-08-05_generative-players-research.md §16, transferable principles 3 and 6). Keyed by the player id in shared/generativePlayers.json; each entry is a complete snapshot of that player's performance axes and character slots: `density` and `mutate` are raw 0..1, and `p` holds one value per slot in P1..Pn order. UI-ONLY — the C++ core never reads this file, and no preset id is persisted anywhere: applying one writes plain cell-config values through setCellPlayer, so a preset may be renamed, re-voiced or dropped without touching a single saved project. What IS frozen is the meaning of what it writes: `p[i]` is that player's slot i in shared/generativePlayers.json, so re-voicing a preset is free while pointing it at a different slot is not. A DETENTED slot's value must be exactly i/(steps-1) — the long decimals here are that quotient, not a rounded taste; type 0.667 for a 4-position slot and the knob, the menu and the C++ stepIndex helper stop agreeing on which position it is (interface/test/generativePlayerPresets.test.ts pins it). A player may carry fewer `p` entries than it has slots (the rest fall back to the roster default), never more.",
+  "version": 1,
+  "presets": {
+    "1": [
+      { "name": "Bossa Five", "density": 0.3125, "mutate": 0, "p": [0, 0.3, 0.4, 0] },
+      { "name": "Offbeats", "density": 0.5, "mutate": 0, "p": [0.06666666666666667, 0.5, 0.5, 0] },
+      { "name": "Rolling Hat", "density": 0.6875, "mutate": 0, "p": [0, 0.18, 0.25, 0] },
+      { "name": "XOR Weave", "density": 0.4375, "mutate": 0, "p": [0, 0.45, 0.6, 0.6666666666666666] },
+      { "name": "Punch Gaps", "density": 0.75, "mutate": 0, "p": [0.26666666666666666, 0.15, 0.8, 1] }
+    ],
+    "2": [
+      { "name": "Sparse Trap", "density": 0.38, "mutate": 0, "p": [0, 0.15, 0.35, 0.5] },
+      { "name": "Rolling Drill", "density": 0.62, "mutate": 0.08, "p": [0.16666666666666666, 0.45, 0.55, 0.6] },
+      { "name": "Busy Boom Bap", "density": 0.58, "mutate": 0.12, "p": [0.3333333333333333, 0.7, 0.1, 0.6] },
+      { "name": "DnB Break", "density": 0.66, "mutate": 0.15, "p": [0.5, 0.55, 0.2, 0.5] },
+      { "name": "Techno Lock", "density": 0.55, "mutate": 0, "p": [0.8333333333333334, 0, 0, 0.5] },
+      { "name": "IDM Skitter", "density": 0.72, "mutate": 0.35, "p": [1, 0.75, 0.5, 0.25] }
+    ],
+    "3": [
+      { "name": "Short Loop", "density": 0.7, "mutate": 0, "p": [0.2222222222222222, 0.15, 0.5, 0, 0] },
+      { "name": "Long Drift", "density": 0.6, "mutate": 0.22, "p": [0.7777777777777778, 0.45, 0.5, 0.2, 0] },
+      { "name": "Inverted Loop", "density": 0.65, "mutate": 1, "p": [0.5555555555555556, 0.3, 0.55, 0.1, 0] },
+      { "name": "Acid Slide", "density": 0.85, "mutate": 0.08, "p": [0.3333333333333333, 0.2, 0.35, 0.75, 0] },
+      { "name": "Quartal Pad", "density": 0.4, "mutate": 0.12, "p": [0.6666666666666666, 0.7, 0.85, 0.6, 1] }
+    ],
+    "4": [
+      { "name": "Tiny Steps", "density": 0.75, "mutate": 0.3, "p": [0.1, 0.7, 0.15, 0.15, 0] },
+      { "name": "Wide Wander", "density": 0.6, "mutate": 0.3, "p": [0.85, 0.2, 0.2, 0.8, 0] },
+      { "name": "Root Anchor", "density": 0.8, "mutate": 0, "p": [0.35, 1, 0.1, 0.25, 0] },
+      { "name": "Sparse Triads", "density": 0.7, "mutate": 0.3, "p": [0.3, 0.55, 0.6, 0.35, 0.6] },
+      { "name": "Fifths Roam", "density": 0.55, "mutate": 0.3, "p": [0.55, 0.35, 0.3, 0.55, 0.4] }
+    ],
+    "5": [
+      { "name": "Echo the Clip", "density": 0.7, "mutate": 0, "p": [0.95, 0, 0.2, 0.2, 0] },
+      { "name": "Loose Jam", "density": 0.65, "mutate": 0.3, "p": [0.6, 0.75, 0.25, 0.4, 0] },
+      { "name": "Free Improv", "density": 0.6, "mutate": 0.3, "p": [0.25, 1, 0.3, 0.7, 0] },
+      { "name": "Wide Sevenths", "density": 0.5, "mutate": 0.3, "p": [0.75, 0.5, 0.35, 1, 0.8] },
+      { "name": "Tight Comp", "density": 0.85, "mutate": 0.3, "p": [0.85, 0.25, 0.1, 0, 0.2] }
+    ],
+    "6": [
+      { "name": "Bare Bones", "density": 0.3, "mutate": 0, "p": [0, 0, 0, 0.5] },
+      { "name": "Backbeat Fills", "density": 0.45, "mutate": 0.1, "p": [0.3333333333333333, 0.6, 0.35, 0.5] },
+      { "name": "Offbeat Buzz", "density": 0.4, "mutate": 0.15, "p": [0.6666666666666666, 0.3, 0.8, 0.15] },
+      { "name": "Machine Gun", "density": 0.7, "mutate": 0.2, "p": [1, 0.85, 0.9, 0.85] },
+      { "name": "Drag Flams", "density": 0.55, "mutate": 0.25, "p": [0, 0.2, 0.45, 0.95] }
+    ],
+    "7": [
+      { "name": "Five Slide", "density": 0.6, "mutate": 0, "p": [0.25, 0.25, 1, 0] },
+      { "name": "Static Seven", "density": 0.43, "mutate": 0, "p": [0.75, 0, 0, 0] },
+      { "name": "Nine Drift", "density": 0.55, "mutate": 0, "p": [1, 0.75, 0.3333333333333333, 1] },
+      { "name": "Triple Pulse", "density": 0.67, "mutate": 0, "p": [0, 0.25, 0.6666666666666666, 0] },
+      { "name": "Six Interlock", "density": 0.5, "mutate": 0, "p": [0.5, 0.5, 0.3333333333333333, 1] }
+    ],
+    "8": [
+      { "name": "Up Two Oct", "density": 0.9, "mutate": 0, "p": [0, 0, 0.3333333333333333, 0.3, 0] },
+      { "name": "Andalusian", "density": 0.75, "mutate": 0.15, "p": [0.6666666666666666, 1, 0.6666666666666666, 0.45, 0] },
+      { "name": "Converge Slow", "density": 0.45, "mutate": 0.15, "p": [1, 0.6666666666666666, 0.3333333333333333, 0.8, 0] },
+      { "name": "Wide Descent", "density": 0.85, "mutate": 0, "p": [0.3333333333333333, 0.3333333333333333, 1, 0.25, 0] },
+      { "name": "Chord Stabs", "density": 0.35, "mutate": 0.15, "p": [0, 0.6666666666666666, 0, 0.15, 0.8] }
+    ],
+    "9": [
+      { "name": "As Written", "density": 0.5, "mutate": 0, "p": [0.5, 0.35] },
+      { "name": "Thinned", "density": 0.3, "mutate": 0, "p": [0.75, 0.2] },
+      { "name": "Filled In", "density": 0.72, "mutate": 0, "p": [0.35, 0.5] },
+      { "name": "Breathing", "density": 0.5, "mutate": 0.35, "p": [0.5, 0.4] },
+      { "name": "Skeleton", "density": 0.16, "mutate": 0.12, "p": [0.9, 0.85] }
+    ]
+  }
+}

package/dist/generativePlayers.json

@@ -0,0 +1,134 @@
+{
+  "_doc": "SINGLE REGISTRY for the generative Players (docs/plans/GENERATIVE_PLAYERS.md §8). One entry per player id; id 0 is Off and has no entry. Consumed by build.js (codegens modules/player/GenerativePlayerSpec.generated.h and gates manifest.generativePatterns) and by interface/src/utils/generativePlayers.ts via the @shared import. IDS ARE APPEND-ONLY and a shipped id's P-slot meanings are frozen: cells[id].playerType persists in every preset and variation, and playerP1..P5 are raw 0..1 knob positions whose meaning comes from this file alone. A player may GROW a slot (the melodic four grew Chord): a new slot's default must be the value that reproduces the pre-slot output, since a preset saved before it existed carries no field. `tag` (drum|melodic|both) drives the UI grouping and the mono-cell hint; `replay` marks the three players whose state is derived by bounded deterministic replay (GenerativePlayerCore::chainStateAtCycle) rather than a closed form. `slots` holds 1..5 P-knob descriptors in P1..P5 order — a player with fewer slots leaves the remaining playerP* fields inert. `steps`/`stepLabels` turn a slot into a detented selector (stepLabels.length must equal steps); everything else is a continuous 0..1 knob. A continuous slot may carry `hint` (one plain sentence the knob's tooltip prints — detented slots self-describe through their labels) and `center: true` (the value is bipolar around 0.5 and prints signed, like KIT's Feel). `defaults.mutate` is 0 for the players where a repeating loop is the point and small where evolution is. `doc` is the ENGINEERING note (algorithm, prior art, hardware lineage) and never reaches the UI; `blurb` is the user-facing one-liner the roster prints, so it carries no filenames, no maths notation and no third-party product names.",
+  "version": 1,
+  "players": {
+    "1": {
+      "name": "EUCLID",
+      "tag": "drum",
+      "replay": false,
+      "doc": "Clough-Douthett closed-form maximally-even E(k,n) with rotation; k from DENSITY over the pattern's 16ths. P4 layers a second pulse generator combined by a boolean op (the Digitakt II dual-Euclid trick). Closed-form and seed-independent while MUTATE is locked, so ROTATION stays absolute and the named repertoire is reachable at known positions. The default density is E(7,16) - the Samba necklace - rather than the k=8 midpoint, which is periodic (gcd 8) and degenerates to a plain straight-eighths grid.",
+      "blurb": "Spreads hits as evenly as it can across the bar. Density sets how many, Rotate slides them, Layer adds a second pulse.",
+      "defaults": { "density": 0.44, "mutate": 0.0 },
+      "slots": [
+        { "label": "Rotate", "default": 0.0, "steps": 16 },
+        { "label": "Gate", "default": 0.35, "hint": "Note length, as a share of the step" },
+        { "label": "Accent", "default": 0.5, "hint": "How many of the hits play accented" },
+        { "label": "Layer", "default": 0.0, "steps": 4, "stepLabels": ["Off", "OR", "XOR", "SUB"] }
+      ]
+    },
+    "2": {
+      "name": "KIT",
+      "tag": "drum",
+      "replay": false,
+      "doc": "Genre-prior threshold masking from RandomizerPatternPriors.h for the cell's default role, played live: onset probability x metric weight, velocity from the prior's mean, ghosts as low-velocity prob steps, ratchets on the retrigger fields.",
+      "blurb": "Plays this cell's drum role in the feel of a genre. Ghost notes and ratchets fill the gaps between the main hits.",
+      "defaults": { "density": 0.5, "mutate": 0.0 },
+      "slots": [
+        { "label": "Genre", "default": 0.0, "steps": 7, "stepLabels": ["Trap", "Drill", "Boom Bap", "DnB", "House", "Techno", "IDM"] },
+        { "label": "Ghosts", "default": 0.3, "hint": "How many quiet extra hits fill the gaps" },
+        { "label": "Ratchet", "default": 0.15, "hint": "How often a hit becomes a short double burst" },
+        { "label": "Feel", "default": 0.5, "center": true, "hint": "Drag behind or push ahead of the beat — the centre is straight" }
+      ]
+    },
+    "3": {
+      "name": "TURING",
+      "tag": "melodic",
+      "replay": true,
+      "doc": "Looping shift register over the hardware's musical length set, one full rotation per cycle; MUTATE is the bit-flip probability (full mutate = the Mobius double-length inverted loop). Pitch comes from LSB-in/MSB-out bit weighting mapped into the cell scale.",
+      "blurb": "A looping bit pattern read out as a melody. Mutate flips bits, so the loop drifts a little further every time round.",
+      "defaults": { "density": 0.6, "mutate": 0.15 },
+      "slots": [
+        { "label": "Length", "default": 0.4444444444444444, "steps": 10, "stepLabels": ["2", "3", "4", "5", "6", "8", "12", "16", "24", "32"] },
+        { "label": "Range", "default": 0.35, "hint": "Pitch range, up to four octaves" },
+        { "label": "Gate", "default": 0.5, "hint": "Which notes survive low density — full favours the strong beats" },
+        { "label": "Slide", "default": 0.0, "hint": "How often a note holds legato into the next" },
+        { "label": "Chord", "default": 0.0, "steps": 6, "stepLabels": ["Off", "Oct", "5th", "Triad", "7th", "Quartal"] }
+      ]
+    },
+    "4": {
+      "name": "WALK",
+      "tag": "melodic",
+      "replay": true,
+      "doc": "Bounded drunk walk over scale degrees: weighted interval table (seconds/thirds dominant), gravity toward the root, leap-then-step-back voice leading, rests from (1-DENSITY).",
+      "blurb": "Wanders up and down the scale in small steps. Gravity pulls it back toward the root, and low density turns steps into rests.",
+      "defaults": { "density": 0.6, "mutate": 0.3 },
+      "slots": [
+        { "label": "Step", "default": 0.4, "hint": "Interval size, small steps to wide leaps" },
+        { "label": "Gravity", "default": 0.5, "hint": "Pull toward the root; high keeps it close to home" },
+        { "label": "Rests", "default": 0.25, "hint": "How often a step becomes a rest" },
+        { "label": "Range", "default": 0.4, "hint": "How far above and below the root it can wander" },
+        { "label": "Chord", "default": 0.0, "steps": 6, "stepLabels": ["Off", "Oct", "5th", "Triad", "7th", "Quartal"] }
+      ]
+    },
+    "5": {
+      "name": "MARKOV",
+      "tag": "melodic",
+      "replay": true,
+      "doc": "Order-1 chain over scale-degree intervals learned from the cell's own drawn pattern, blended toward the metric-hierarchy prior when the clip is thin. P2 is the temperature (argmax replay to uniform).",
+      "blurb": "Learns from the pattern you drew and improvises around it. Fidelity holds the line, Temp loosens it.",
+      "defaults": { "density": 0.6, "mutate": 0.3 },
+      "slots": [
+        { "label": "Fidelity", "default": 0.7, "hint": "How closely it follows the pattern it learnt" },
+        { "label": "Freedom", "default": 0.5, "steps": 5, "stepLabels": ["Lock", "Tight", "As Learnt", "Loose", "Free"] },
+        { "label": "Rests", "default": 0.25, "hint": "How often a step becomes a rest" },
+        { "label": "Range", "default": 0.4, "hint": "Octave span of the improvisation" },
+        { "label": "Chord", "default": 0.0, "steps": 6, "stepLabels": ["Off", "Oct", "5th", "Triad", "7th", "Quartal"] }
+      ]
+    },
+    "6": {
+      "name": "RATCHET",
+      "tag": "drum",
+      "replay": false,
+      "doc": "Sparse archetype skeleton grown by threshold masking, plus per-cycle fills and retrigger bursts baked from the cycle hash. Emits the grid an Elektron-style player freezes into.",
+      "blurb": "A sparse skeleton with fills and retrigger bursts. Every cycle puts them somewhere new.",
+      "defaults": { "density": 0.45, "mutate": 0.1 },
+      "slots": [
+        { "label": "Skeleton", "default": 0.0, "steps": 4, "stepLabels": ["Downbeat", "Backbeat", "Offbeat", "Rolling"] },
+        { "label": "Fills", "default": 0.25, "hint": "How often a cycle grows a fill" },
+        { "label": "Ratchet", "default": 0.3, "hint": "How often a hit becomes a retrigger burst" },
+        { "label": "Ramp", "default": 0.5, "hint": "Burst speed, and how hard the repeats hit" }
+      ]
+    },
+    "7": {
+      "name": "PHASE",
+      "tag": "both",
+      "replay": false,
+      "doc": "A sub-loop of L steps tiled against the pattern window and rotated by a fixed number of steps per cycle (discrete Reich phasing - loop-safe and bounce-exact, unlike continuous drift).",
+      "blurb": "A short loop of odd length that slides against the bar. The two pull apart, then meet up again.",
+      "defaults": { "density": 0.5, "mutate": 0.0 },
+      "slots": [
+        { "label": "Loop", "default": 0.0, "steps": 5, "stepLabels": ["3", "5", "6", "7", "9"] },
+        { "label": "Drift", "default": 0.25, "steps": 5, "stepLabels": ["0", "1", "2", "3", "4"] },
+        { "label": "Accent", "default": 0.3333333333333333, "steps": 4, "stepLabels": ["1", "2", "3", "4"] },
+        { "label": "Alternate", "default": 0.0, "steps": 2, "stepLabels": ["Off", "On"] }
+      ]
+    },
+    "8": {
+      "name": "RIFF",
+      "tag": "melodic",
+      "replay": false,
+      "doc": "Scale-degree arp automaton: a chord-tone pool cycling through a short progression per cycle, traversed by shape over an octave span, with skips from (1-DENSITY).",
+      "blurb": "Arpeggios over a short chord progression. Shape picks the path up and down, Octaves sets the range.",
+      "defaults": { "density": 0.7, "mutate": 0.15 },
+      "slots": [
+        { "label": "Shape", "default": 0.0, "steps": 4, "stepLabels": ["Up", "Down", "Orbit", "Converge"] },
+        { "label": "Prog", "default": 0.0, "steps": 4, "stepLabels": ["Static", "i-VI", "i-iv-V", "i-VII-VI-V"] },
+        { "label": "Octaves", "default": 0.3333333333333333, "steps": 4, "stepLabels": ["1", "2", "3", "4"] },
+        { "label": "Gate", "default": 0.4, "hint": "Note length, as a share of the step" },
+        { "label": "Chord", "default": 0.0, "steps": 6, "stepLabels": ["Off", "Oct", "5th", "Triad", "7th", "Quartal"] }
+      ]
+    },
+    "9": {
+      "name": "MASK",
+      "tag": "both",
+      "replay": false,
+      "doc": "The cell's own drawn pattern, morphed. Per-step weights seeded from the clip (velocity on their notes, metric hierarchy on their rests) under one monotone threshold whose CENTER DETENT reproduces the clip exactly; MUTATE is a per-cycle latched perturbation depth.",
+      "blurb": "Your drawn pattern, thinned out or filled in. The centre of Density plays it back exactly as written.",
+      "defaults": { "density": 0.5, "mutate": 0.0 },
+      "slots": [
+        { "label": "Accent", "default": 0.5, "hint": "How far the off-beats duck under the strong beats" },
+        { "label": "Gate", "default": 0.35, "hint": "Note length, as a share of the step" }
+      ]
+    }
+  }
+}