@signalsandsorcery/plugin-sdk 2.35.5 → 2.35.6

package/dist/index.js

@@ -43,6 +43,9 @@ __export(index_exports, {
   DownloadPackButton: () => DownloadPackButton,
   EMPTY_FX_DETAIL_STATE: () => EMPTY_FX_DETAIL_STATE,
   EMPTY_FX_STATE: () => EMPTY_FX_STATE,
+  ENSEMBLE_MAX_VOICES: () => ENSEMBLE_MAX_VOICES,
+  ENSEMBLE_MIN_VOICES: () => ENSEMBLE_MIN_VOICES,
+  ENSEMBLE_STYLES: () => ENSEMBLE_STYLES,
   EQUAL_POWER_GAIN: () => EQUAL_POWER_GAIN,
   FX_CATEGORIES: () => FX_CATEGORIES,
   FX_CHAIN_ORDER: () => FX_CHAIN_ORDER,
@@ -58,6 +61,7 @@ __export(index_exports, {
   ImportTrackModal: () => ImportTrackModal,
   InstrumentDrawer: () => TrackDrawer,
   LevelMeter: () => LevelMeter,
+  MIN_NOTE_DURATION_BEATS: () => MIN_NOTE_DURATION_BEATS,
   Modal: () => Modal,
   OffsetScrubber: () => OffsetScrubber,
   PLUGIN_SDK_VERSION: () => PLUGIN_SDK_VERSION,
@@ -69,6 +73,8 @@ __export(index_exports, {
   RESIZE_HANDLE_PX: () => RESIZE_HANDLE_PX,
   ROW_HEIGHT: () => ROW_HEIGHT,
   SLIDER_UNITY: () => SLIDER_UNITY,
+  STYLE_RULES: () => STYLE_RULES,
+  SUBMIT_ENSEMBLE_TOOL_NAME: () => SUBMIT_ENSEMBLE_TOOL_NAME,
   SamplePackCTACard: () => SamplePackCTACard,
   ScrollingWaveform: () => ScrollingWaveform,
   SorceryProgressBar: () => SorceryProgressBar,
@@ -81,6 +87,7 @@ __export(index_exports, {
   TransitionDesigner: () => TransitionDesigner,
   VolumeSlider: () => VolumeSlider,
   WaveformView: () => WaveformView,
+  analyzeEnsemble: () => analyzeEnsemble,
   analyzeWavPeak: () => analyzeWavPeak,
   asAudioEffect: () => asAudioEffect,
   asCrossfadeMeta: () => asCrossfadeMeta,
@@ -88,8 +95,11 @@ __export(index_exports, {
   asTransitionDesignerDraft: () => asTransitionDesignerDraft,
   buildCrossfadeInpaintPrompt: () => buildCrossfadeInpaintPrompt,
   buildCrossfadeVolumeCurves: () => buildCrossfadeVolumeCurves,
+  buildEnsembleSystemPrompt: () => buildEnsembleSystemPrompt,
   buildFadeVolumeCurve: () => buildFadeVolumeCurve,
   buildRowSlots: () => buildRowSlots,
+  buildSubmitEnsembleParameters: () => buildSubmitEnsembleParameters,
+  buildViolationRetrySuffix: () => buildViolationRetrySuffix,
   calculateTimeBasedTarget: () => calculateTimeBasedTarget,
   cellToPx: () => cellToPx,
   centerScrollTop: () => centerScrollTop,
@@ -98,15 +108,21 @@ __export(index_exports, {
   dbIdsFromKeys: () => dbIdsFromKeys,
   dbToSlider: () => dbToSlider,
   defaultFadeGesture: () => defaultFadeGesture,
+  defaultVoiceSpecs: () => defaultVoiceSpecs,
+  describeViolations: () => describeViolations,
   drawWaveform: () => drawWaveform,
+  enforceVoice: () => enforceVoice,
+  foldPitchToRegister: () => foldPitchToRegister,
   formatConcurrentTracks: () => formatConcurrentTracks,
   hashString: () => hashString,
   moveItem: () => moveItem,
+  nearestPitchWithPc: () => nearestPitchWithPc,
   newTrackState: () => newTrackState,
   normalizeSlots: () => normalizeSlots,
   padPair: () => padPair,
   padSlots: () => padSlots,
   parseCrossfadePairs: () => parseCrossfadePairs,
+  parseEnsembleArgs: () => parseEnsembleArgs,
   parseFades: () => parseFades,
   parseLLMNoteResponse: () => parseLLMNoteResponse,
   parseTrackGroups: () => parseTrackGroups,
@@ -8595,31 +8611,447 @@ function createSurgeSoundAdapter(host, overrides = {}) {
   };
 }
 
+// src/ensemble-core/voice-spec.ts
+var TOP = {
+  label: "high florid line",
+  role: "lead",
+  registerLow: 72,
+  registerHigh: 96,
+  maxNotesPerBar: 8,
+  rhythmPalette: "8ths and 16ths; melisma and short runs welcome",
+  harmonicDiscipline: "freest voice \u2014 non-chord tones as passing/neighbor tones on weak beats, resolving by step",
+  monoPreference: "high"
+};
+var COUNTER = {
+  label: "countermelody",
+  role: "strings",
+  registerLow: 65,
+  registerHigh: 86,
+  maxNotesPerBar: 6,
+  rhythmPalette: "8ths and quarters; move when the top voice rests",
+  harmonicDiscipline: "mostly chord tones; may imitate the top voice's motifs a bar later",
+  monoPreference: "high"
+};
+var INNER = {
+  label: "inner voice",
+  role: "strings",
+  registerLow: 55,
+  registerHigh: 76,
+  maxNotesPerBar: 4,
+  rhythmPalette: "quarters and halves",
+  harmonicDiscipline: "chord tones with smooth stepwise motion between them",
+  monoPreference: "high"
+};
+var INNER_2 = {
+  label: "second inner voice",
+  role: "strings",
+  registerLow: 60,
+  registerHigh: 81,
+  maxNotesPerBar: 5,
+  rhythmPalette: "quarters with occasional 8th-note motion",
+  harmonicDiscipline: "chord tones; fill gaps the other inner voice leaves",
+  monoPreference: "high"
+};
+var TENOR = {
+  label: "low counterline",
+  role: "strings",
+  registerLow: 43,
+  registerHigh: 64,
+  maxNotesPerBar: 3,
+  rhythmPalette: "quarters and halves; brief walking figures at cadences",
+  harmonicDiscipline: "roots and fifths emphasized; passing tones only between chord tones",
+  monoPreference: "low"
+};
+var BASS = {
+  label: "bassline",
+  role: "bass",
+  registerLow: 36,
+  registerHigh: 60,
+  maxNotesPerBar: 3,
+  rhythmPalette: "quarters and halves",
+  harmonicDiscipline: "chord roots and fifths; stepwise approaches into chord changes",
+  monoPreference: "low"
+};
+var SUB = {
+  label: "sub anchor",
+  role: "808s",
+  registerLow: 24,
+  registerHigh: 43,
+  maxNotesPerBar: 2,
+  rhythmPalette: "halves and whole notes; sustain into the bar",
+  harmonicDiscipline: "ROOT pitch class only \u2014 the harmonic anchor",
+  rootOnly: true,
+  monoPreference: "low"
+};
+var ENSEMBLE_MIN_VOICES = 2;
+var ENSEMBLE_MAX_VOICES = 6;
+var SPEC_TABLES = {
+  2: [TOP, BASS],
+  3: [TOP, INNER, BASS],
+  4: [TOP, COUNTER, TENOR, BASS],
+  5: [TOP, COUNTER, INNER, TENOR, SUB],
+  6: [TOP, COUNTER, INNER_2, INNER, TENOR, SUB]
+};
+function defaultVoiceSpecs(voiceCount) {
+  const n = Math.max(ENSEMBLE_MIN_VOICES, Math.min(ENSEMBLE_MAX_VOICES, Math.round(voiceCount)));
+  return SPEC_TABLES[n].map((spec, voiceIndex) => ({ ...spec, voiceIndex }));
+}
+
+// src/ensemble-core/enforce-voice.ts
+var MIN_NOTE_DURATION_BEATS = 0.0625;
+var BEATS_PER_BAR = 4;
+function foldPitchToRegister(pitch, low, high) {
+  let p = pitch;
+  while (p < low) p += 12;
+  while (p > high) p -= 12;
+  if (p < low) p = low;
+  if (p > high) p = high;
+  return p;
+}
+function nearestPitchWithPc(reference, pc, low, high) {
+  let best = null;
+  for (let p = low; p <= high; p++) {
+    if ((p % 12 + 12) % 12 !== pc) continue;
+    if (best === null || Math.abs(p - reference) < Math.abs(best - reference)) best = p;
+  }
+  return best ?? foldPitchToRegister(reference, low, high);
+}
+function snapToNearestPc(pitch, pcs) {
+  if (pcs.size === 0) return pitch;
+  for (let d = 0; d <= 6; d++) {
+    if (pcs.has(((pitch - d) % 12 + 12) % 12)) return pitch - d;
+    if (pcs.has(((pitch + d) % 12 + 12) % 12)) return pitch + d;
+  }
+  return pitch;
+}
+function enforceVoice(rawNotes, spec, opts) {
+  const repairs = [];
+  const clipEnd = opts.bars * BEATS_PER_BAR;
+  let notes = [];
+  for (const n of rawNotes) {
+    if (!Number.isFinite(n.pitch) || !Number.isFinite(n.startBeat) || !Number.isFinite(n.durationBeats)) continue;
+    if (n.startBeat >= clipEnd || n.startBeat < 0) {
+      repairs.push(`voice ${spec.voiceIndex}: dropped note outside the ${opts.bars}-bar clip (start ${n.startBeat})`);
+      continue;
+    }
+    const durationBeats = Math.max(
+      MIN_NOTE_DURATION_BEATS,
+      Math.min(n.durationBeats, clipEnd - n.startBeat)
+    );
+    notes.push({ ...n, durationBeats });
+  }
+  notes = notes.map((n) => {
+    const folded = foldPitchToRegister(Math.round(n.pitch), spec.registerLow, spec.registerHigh);
+    if (folded !== n.pitch) {
+      repairs.push(`voice ${spec.voiceIndex}: folded pitch ${n.pitch} into register ${spec.registerLow}-${spec.registerHigh} (${folded})`);
+    }
+    return { ...n, pitch: folded };
+  });
+  if (spec.rootOnly && opts.chordRootPcAtBar) {
+    notes = notes.map((n) => {
+      const bar = Math.floor(n.startBeat / BEATS_PER_BAR);
+      const rootPc = opts.chordRootPcAtBar(bar);
+      if (rootPc === null) return n;
+      const pinned = nearestPitchWithPc(n.pitch, rootPc, spec.registerLow, spec.registerHigh);
+      if (pinned !== n.pitch) {
+        repairs.push(`voice ${spec.voiceIndex}: pinned bar ${bar + 1} note to the chord root (${n.pitch} \u2192 ${pinned})`);
+      }
+      return { ...n, pitch: pinned };
+    });
+  }
+  if (opts.scalePcs && opts.scalePcs.size > 0 && !spec.rootOnly) {
+    notes = notes.map((n) => {
+      const pc = (n.pitch % 12 + 12) % 12;
+      if (opts.scalePcs.has(pc)) return n;
+      const bar = Math.floor(n.startBeat / BEATS_PER_BAR);
+      const chordPcs = opts.chordPcsAtBar?.(bar);
+      if (chordPcs?.has(pc)) return n;
+      const snapped = foldPitchToRegister(
+        snapToNearestPc(n.pitch, opts.scalePcs),
+        spec.registerLow,
+        spec.registerHigh
+      );
+      if (snapped !== n.pitch) {
+        repairs.push(`voice ${spec.voiceIndex}: snapped out-of-key pitch ${n.pitch} \u2192 ${snapped}`);
+      }
+      return { ...n, pitch: snapped };
+    });
+  }
+  notes.sort((a, b) => a.startBeat - b.startBeat || (spec.monoPreference === "high" ? b.pitch - a.pitch : a.pitch - b.pitch));
+  const mono = [];
+  for (const n of notes) {
+    const prev = mono[mono.length - 1];
+    if (prev && Math.abs(prev.startBeat - n.startBeat) < 1e-9) {
+      repairs.push(`voice ${spec.voiceIndex}: dropped simultaneous note ${n.pitch} at beat ${n.startBeat} (voice is one line)`);
+      continue;
+    }
+    if (prev && prev.startBeat + prev.durationBeats > n.startBeat) {
+      prev.durationBeats = Math.max(MIN_NOTE_DURATION_BEATS, n.startBeat - prev.startBeat);
+    }
+    mono.push({ ...n });
+  }
+  const byBar = /* @__PURE__ */ new Map();
+  for (const n of mono) {
+    const bar = Math.floor(n.startBeat / BEATS_PER_BAR);
+    const bucket = byBar.get(bar) ?? [];
+    bucket.push(n);
+    byBar.set(bar, bucket);
+  }
+  const kept = new Set(mono);
+  for (const [bar, bucket] of byBar) {
+    if (bucket.length <= spec.maxNotesPerBar) continue;
+    const strength = (n) => {
+      const beatInBar = n.startBeat - bar * BEATS_PER_BAR;
+      const onDownbeat = Math.abs(beatInBar % 1) < 1e-9 ? 1 : 0;
+      return n.durationBeats * 4 + n.velocity / 127 + onDownbeat * 2;
+    };
+    const ranked = [...bucket].sort((a, b) => strength(a) - strength(b));
+    const excess = bucket.length - spec.maxNotesPerBar;
+    for (let i = 0; i < excess; i++) {
+      kept.delete(ranked[i]);
+    }
+    repairs.push(`voice ${spec.voiceIndex}: thinned bar ${bar + 1} from ${bucket.length} to ${spec.maxNotesPerBar} notes (density cap)`);
+  }
+  return { notes: mono.filter((n) => kept.has(n)), repairs };
+}
+
+// src/ensemble-core/analyze-ensemble.ts
+var EPS = 1e-6;
+function pitchAt(voice, beat) {
+  for (const n of voice) {
+    if (n.startBeat - EPS <= beat && beat < n.startBeat + n.durationBeats - EPS) return n.pitch;
+  }
+  return null;
+}
+function onsetSet(voice) {
+  return [...new Set(voice.map((n) => Math.round(n.startBeat * 96) / 96))].sort((a, b) => a - b);
+}
+function analyzeEnsemble(voices) {
+  const pairs = [];
+  for (let i = 0; i + 1 < voices.length; i++) {
+    const upper = voices[i];
+    const lower = voices[i + 1];
+    const upperOnsets = onsetSet(upper);
+    const lowerOnsets = new Set(onsetSet(lower));
+    const shared = upperOnsets.filter((b) => lowerOnsets.has(b));
+    const onsetIndependence = upperOnsets.length === 0 ? 1 : 1 - shared.length / upperOnsets.length;
+    const motion = { contrary: 0, oblique: 0, similar: 0, parallel: 0 };
+    const parallelPerfects = [];
+    for (let s = 0; s + 1 < shared.length; s++) {
+      const [b0, b1] = [shared[s], shared[s + 1]];
+      const u0 = pitchAt(upper, b0);
+      const u1 = pitchAt(upper, b1);
+      const l0 = pitchAt(lower, b0);
+      const l1 = pitchAt(lower, b1);
+      if (u0 === null || u1 === null || l0 === null || l1 === null) continue;
+      const du = Math.sign(u1 - u0);
+      const dl = Math.sign(l1 - l0);
+      let kind;
+      if (du === 0 || dl === 0) kind = "oblique";
+      else if (du !== dl) kind = "contrary";
+      else {
+        kind = u1 - l1 === u0 - l0 ? "parallel" : "similar";
+      }
+      motion[kind] += 1;
+      if (kind === "parallel") {
+        const intervalPc = ((u1 - l1) % 12 + 12) % 12;
+        if (intervalPc === 0 || intervalPc === 7) {
+          parallelPerfects.push({ atBeat: b1, intervalPc });
+        }
+      }
+    }
+    const crossings = [];
+    for (const b of [...upperOnsets, ...onsetSet(lower)]) {
+      const u = pitchAt(upper, b);
+      const l = pitchAt(lower, b);
+      if (u !== null && l !== null && u < l) crossings.push(b);
+    }
+    pairs.push({
+      upperVoice: i,
+      onsetIndependence,
+      motion,
+      parallelPerfects,
+      crossings: [...new Set(crossings)].sort((a, b) => a - b)
+    });
+  }
+  const allOnsets = voices.map(onsetSet);
+  const union = new Set(allOnsets.flat());
+  let sharedByAll = 0;
+  for (const b of union) {
+    if (allOnsets.every((o) => o.length === 0 || o.includes(b))) sharedByAll += 1;
+  }
+  const homorhythmScore = union.size === 0 ? 0 : sharedByAll / union.size;
+  return { pairs, homorhythmScore };
+}
+function describeViolations(analysis, rules) {
+  const out = [];
+  for (const pair of analysis.pairs) {
+    const label = `between voice ${pair.upperVoice + 1} and voice ${pair.upperVoice + 2}`;
+    if (rules.forbidParallelPerfects) {
+      for (const p of pair.parallelPerfects) {
+        out.push(`Parallel ${p.intervalPc === 0 ? "octaves" : "fifths"} ${label} at beat ${p.atBeat} \u2014 approach perfect intervals by contrary or oblique motion.`);
+      }
+    }
+    if (rules.forbidVoiceCrossing && pair.crossings.length > 0) {
+      out.push(`Voice crossing ${label} at beat${pair.crossings.length > 1 ? "s" : ""} ${pair.crossings.join(", ")} \u2014 keep each voice inside its register lane.`);
+    }
+    if (pair.onsetIndependence < rules.minOnsetIndependence) {
+      out.push(`Voices ${pair.upperVoice + 1} and ${pair.upperVoice + 2} attack together too often (independence ${pair.onsetIndependence.toFixed(2)} < ${rules.minOnsetIndependence}) \u2014 stagger entrances and let one voice move while the other holds.`);
+    }
+  }
+  return out;
+}
+
+// src/ensemble-core/styles.ts
+var ENSEMBLE_STYLES = ["counterpoint", "chorale", "interlock"];
+var STYLE_RULES = {
+  counterpoint: {
+    forbidParallelPerfects: true,
+    forbidVoiceCrossing: true,
+    minOnsetIndependence: 0.35,
+    promptParagraph: "STYLE \u2014 COUNTERPOINT (modern, not strict species): independent singable lines. Favor contrary and oblique motion between neighbors; approach perfect intervals by contrary motion; imitate motifs between voices a bar apart; stagger entrances so voices converse instead of speaking at once."
+  },
+  chorale: {
+    forbidParallelPerfects: true,
+    forbidVoiceCrossing: true,
+    minOnsetIndependence: 0,
+    promptParagraph: "STYLE \u2014 CHORALE: homorhythmic block harmony. Voices move together on the same rhythm with smooth voice-leading \u2014 nearest chord tone, common tones held, no leaps larger than a fifth in inner voices."
+  },
+  interlock: {
+    forbidParallelPerfects: false,
+    forbidVoiceCrossing: false,
+    minOnsetIndependence: 0.6,
+    promptParagraph: "STYLE \u2014 INTERLOCK (minimal / systems music): short repeating cells that mesh like gears. Each voice keeps its own ostinato; onsets rarely coincide with the neighboring voice; parallel motion and doubling are welcome when the composite rhythm stays busy and even."
+  }
+};
+
+// src/ensemble-core/ensemble-schema.ts
+var SUBMIT_ENSEMBLE_TOOL_NAME = "submit_ensemble";
+function buildSubmitEnsembleParameters(voiceCount) {
+  return {
+    type: "object",
+    properties: {
+      voices: {
+        type: "array",
+        description: `Exactly ${voiceCount} voices, voiceIndex 0 (top) through ${voiceCount - 1} (bottom).`,
+        items: {
+          type: "object",
+          properties: {
+            voiceIndex: { type: "integer", description: "0 = top voice" },
+            notes: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  pitch: { type: "integer", description: "MIDI note number 0-127" },
+                  startBeat: { type: "number", description: "quarter-note beats from clip start" },
+                  durationBeats: { type: "number", description: "duration in quarter-note beats" },
+                  velocity: { type: "integer", description: "1-127" }
+                },
+                required: ["pitch", "startBeat", "durationBeats", "velocity"]
+              }
+            }
+          },
+          required: ["voiceIndex", "notes"]
+        }
+      }
+    },
+    required: ["voices"]
+  };
+}
+function parseEnsembleArgs(args, voiceCount) {
+  if (typeof args !== "object" || args === null) return null;
+  const voicesRaw = args.voices;
+  if (!Array.isArray(voicesRaw)) return null;
+  const warnings = [];
+  const voiceNotes = Array.from({ length: voiceCount }, () => []);
+  for (const v of voicesRaw) {
+    if (typeof v !== "object" || v === null) continue;
+    const idxRaw = v.voiceIndex;
+    const idx = typeof idxRaw === "number" ? Math.round(idxRaw) : NaN;
+    if (!Number.isInteger(idx) || idx < 0 || idx >= voiceCount) {
+      warnings.push(`ignored voice with out-of-range voiceIndex ${String(idxRaw)}`);
+      continue;
+    }
+    const notesRaw = v.notes;
+    if (!Array.isArray(notesRaw)) continue;
+    const notes = [];
+    let dropped = 0;
+    for (const n of notesRaw) {
+      const note = n;
+      if (typeof note?.pitch === "number" && typeof note?.startBeat === "number" && typeof note?.durationBeats === "number" && typeof note?.velocity === "number" && note.durationBeats > 0 && note.startBeat >= 0) {
+        notes.push({
+          pitch: Math.max(0, Math.min(127, Math.round(note.pitch))),
+          startBeat: note.startBeat,
+          durationBeats: note.durationBeats,
+          velocity: Math.max(1, Math.min(127, Math.round(note.velocity)))
+        });
+      } else {
+        dropped += 1;
+      }
+    }
+    if (dropped > 0) warnings.push(`voice ${idx}: dropped ${dropped} malformed note(s)`);
+    voiceNotes[idx] = notes;
+  }
+  const returned = voicesRaw.length;
+  if (returned !== voiceCount) {
+    warnings.push(`model returned ${returned} voices for a ${voiceCount}-voice ensemble`);
+  }
+  const anyNotes = voiceNotes.some((v) => v.length > 0);
+  return anyNotes ? { voiceNotes, warnings } : null;
+}
+
+// src/ensemble-core/ensemble-prompt.ts
+function voiceContractLine(spec) {
+  const root = spec.rootOnly ? " ROOT PITCH CLASS ONLY (each bar's chord root)." : "";
+  return `- Voice ${spec.voiceIndex + 1} (${spec.label}): MIDI ${spec.registerLow}-${spec.registerHigh}, max ${spec.maxNotesPerBar} notes/bar, rhythm: ${spec.rhythmPalette}. ${spec.harmonicDiscipline}.${root}`;
+}
+function buildEnsembleSystemPrompt(specs, style) {
+  const styleParagraph = STYLE_RULES[style].promptParagraph;
+  return `You are an ensemble composer. Compose ${specs.length} voices as ONE piece of music \u2014 not ${specs.length} independent parts.
+
+Submit your composition by calling the ${SUBMIT_ENSEMBLE_TOOL_NAME} tool with all ${specs.length} voices.
+
+THE ENSEMBLE RULES (most important):
+1. The voices are composed TOGETHER. They must relate: imitate and answer each other's motifs, move in contrary or oblique motion against neighbors, and stagger entrances so lines converse.
+2. Each voice is a SINGLE monophonic line \u2014 within one voice, no two notes overlap in time and no chords. Voices MAY and SHOULD overlap EACH OTHER; that overlap is the music.
+3. Complexity decreases downward: the top voice is the most active and ornamented, the bottom voice the sparsest anchor. Respect each voice's register window and notes-per-bar cap exactly.
+4. Follow the chord progression in the musical context exactly. Non-chord tones only as passing or neighbor tones on weak beats, resolving by step.
+5. Not every voice plays all the time \u2014 rests are structural. Avoid all voices attacking the same beat except at phrase boundaries.
+6. startBeat/durationBeats are in quarter-note beats from the start of the clip; fill the stated bar length, and make bar 1 land immediately (no long silent intro).
+
+${styleParagraph}
+
+PER-VOICE CONTRACTS:
+${specs.map(voiceContractLine).join("\n")}`;
+}
+function buildViolationRetrySuffix(violations) {
+  if (violations.length === 0) return "";
+  return `
+
+Your previous ensemble had these problems \u2014 fix them while keeping everything that worked:
+` + violations.map((v) => `- ${v}`).join("\n");
+}
+
 // src/constants/sdk-version.ts
-var PLUGIN_SDK_VERSION = "2.40.0";
+var PLUGIN_SDK_VERSION = "2.42.0";
 
 // src/utils/format-concurrent-tracks.ts
 function formatConcurrentTracks(ctx) {
   const tracks = ctx.concurrentTracks;
   if (!tracks || tracks.length === 0) return "";
-  const lines = [`Concurrent tracks in scene (already generated):`];
-  for (const track of tracks) {
-    const promptStr = track.prompt ? ` prompt="${escapeQuotes(track.prompt)}"` : "";
-    lines.push(`  - role=${track.role ?? "unknown"}${promptStr}`);
-    if (track.notesByChord.length === 0) {
-      lines.push(`    (no notes)`);
-    } else {
-      for (const segment of track.notesByChord) {
-        if (segment.notes.length === 0) continue;
-        lines.push(`    ${formatChordSegment(segment)}`);
-      }
-    }
-    if (track.truncated && typeof track.originalNoteCount === "number") {
-      const dropped = track.originalNoteCount - sumKeptNotes(track.notesByChord);
-      if (dropped > 0) {
-        lines.push(`    \u2026 (${dropped} more notes truncated)`);
-      }
-    }
+  const pinned = tracks.filter((t) => t.pinned);
+  const ambient = tracks.filter((t) => !t.pinned);
+  const lines = [];
+  if (pinned.length > 0) {
+    lines.push(
+      "REFERENCE TRACKS (write in counterpoint against these \u2014 interlock with their rhythm, avoid doubling their onsets, favor contrary or oblique motion):"
+    );
+    for (const track of pinned) pushTrackLines(lines, track);
+  }
+  if (ambient.length > 0) {
+    lines.push(`Concurrent tracks in scene (already generated):`);
+    for (const track of ambient) pushTrackLines(lines, track);
   }
   if (ctx.truncatedTrackCount && ctx.truncatedTrackCount > 0) {
     lines.push(
@@ -8628,6 +9060,25 @@ function formatConcurrentTracks(ctx) {
   }
   return lines.join("\n");
 }
+function pushTrackLines(lines, track) {
+  const nameStr = track.name ? ` name="${escapeQuotes(track.name)}"` : "";
+  const promptStr = track.prompt ? ` prompt="${escapeQuotes(track.prompt)}"` : "";
+  lines.push(`  - role=${track.role ?? "unknown"}${nameStr}${promptStr}`);
+  if (track.notesByChord.length === 0) {
+    lines.push(`    (no notes)`);
+  } else {
+    for (const segment of track.notesByChord) {
+      if (segment.notes.length === 0) continue;
+      lines.push(`    ${formatChordSegment(segment)}`);
+    }
+  }
+  if (track.truncated && typeof track.originalNoteCount === "number") {
+    const dropped = track.originalNoteCount - sumKeptNotes(track.notesByChord);
+    if (dropped > 0) {
+      lines.push(`    \u2026 (${dropped} more notes truncated)`);
+    }
+  }
+}
 function formatChordSegment(segment) {
   const [start, end] = segment.chordRangeQn;
   const notesJson = JSON.stringify(segment.notes.map(compactNote2));
@@ -8753,6 +9204,9 @@ function pickTopKWeighted(scored, options = {}) {
   DownloadPackButton,
   EMPTY_FX_DETAIL_STATE,
   EMPTY_FX_STATE,
+  ENSEMBLE_MAX_VOICES,
+  ENSEMBLE_MIN_VOICES,
+  ENSEMBLE_STYLES,
   EQUAL_POWER_GAIN,
   FX_CATEGORIES,
   FX_CHAIN_ORDER,
@@ -8768,6 +9222,7 @@ function pickTopKWeighted(scored, options = {}) {
   ImportTrackModal,
   InstrumentDrawer,
   LevelMeter,
+  MIN_NOTE_DURATION_BEATS,
   Modal,
   OffsetScrubber,
   PLUGIN_SDK_VERSION,
@@ -8779,6 +9234,8 @@ function pickTopKWeighted(scored, options = {}) {
   RESIZE_HANDLE_PX,
   ROW_HEIGHT,
   SLIDER_UNITY,
+  STYLE_RULES,
+  SUBMIT_ENSEMBLE_TOOL_NAME,
   SamplePackCTACard,
   ScrollingWaveform,
   SorceryProgressBar,
@@ -8791,6 +9248,7 @@ function pickTopKWeighted(scored, options = {}) {
   TransitionDesigner,
   VolumeSlider,
   WaveformView,
+  analyzeEnsemble,
   analyzeWavPeak,
   asAudioEffect,
   asCrossfadeMeta,
@@ -8798,8 +9256,11 @@ function pickTopKWeighted(scored, options = {}) {
   asTransitionDesignerDraft,
   buildCrossfadeInpaintPrompt,
   buildCrossfadeVolumeCurves,
+  buildEnsembleSystemPrompt,
   buildFadeVolumeCurve,
   buildRowSlots,
+  buildSubmitEnsembleParameters,
+  buildViolationRetrySuffix,
   calculateTimeBasedTarget,
   cellToPx,
   centerScrollTop,
@@ -8808,15 +9269,21 @@ function pickTopKWeighted(scored, options = {}) {
   dbIdsFromKeys,
   dbToSlider,
   defaultFadeGesture,
+  defaultVoiceSpecs,
+  describeViolations,
   drawWaveform,
+  enforceVoice,
+  foldPitchToRegister,
   formatConcurrentTracks,
   hashString,
   moveItem,
+  nearestPitchWithPc,
   newTrackState,
   normalizeSlots,
   padPair,
   padSlots,
   parseCrossfadePairs,
+  parseEnsembleArgs,
   parseFades,
   parseLLMNoteResponse,
   parseTrackGroups,