From 505ed26f21721d0eabf81235320f997e4b7ca7ab Mon Sep 17 00:00:00 2001
From: w1n5t0n <w1n5t0n@lnfinitemonkeys.org>
Date: Tue, 24 Mar 2026 02:17:32 +0200
Subject: [PATCH] feat(shapeseq): integrate ShapeSeq into synth mode, replace
 arpeggiator

- Remove Arpeggiator import and all arp references from a-app.js
- Add ShapeSeq imports (ShapeSeqEngine, StepVisualizer, ChainBuilderUI,
  getDefaultBus) and lazy initialization on first audio start
- In synth mode: show ShapeSeq container (circular viz + chain builder),
  hide flow-field particles. Visual mode unchanged.
- Route joystick or hand tracking inputs to shapeSeq.setSequenceInputs()
  each frame; render step viz at 60fps
- Add HTML: #shapeseq-container with #shapeseq-viz canvas and
  #shapeseq-chain wrapper, sequencer transport controls (play/stop,
  tempo, step count)
- Add CSS: full-screen flex layout, viz takes upper 45%, chain builder
  scrollable below, hidden by default
- Quick play button wires to ShapeSeq start/stop instead of arp

Closes meml-6ry. This completes ShapeSeq Phase 1.
---
 playground/a-immersive.html    |  33 +++----
 playground/css/a-immersive.css |  29 ++++++
 playground/js/a-app.js         | 169 +++++++++++++++++++++++----------
 3 files changed, 161 insertions(+), 70 deletions(-)

diff --git a/playground/a-immersive.html b/playground/a-immersive.html
index 9dcf82c..ca65734 100644
--- a/playground/a-immersive.html
+++ b/playground/a-immersive.html
@@ -21,7 +21,7 @@
 
   <!-- Synth quick controls (play button + drawer, next to back button) -->
   <div class="synth-quick-controls hidden" id="synth-quick-controls">
-    <button class="play-btn" id="quick-play" title="Start audio + arpeggiator">
+    <button class="play-btn" id="quick-play" title="Start audio + sequencer">
       <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" id="quick-play-icon"><path d="M4 2l10 6-10 6z"/></svg>
     </button>
     <div class="play-drawer" id="play-drawer">
@@ -60,6 +60,12 @@
   <!-- Synth visualization canvas -->
   <canvas id="synth-vis-canvas"></canvas>
 
+  <!-- ShapeSeq UI (synth mode only) -->
+  <div class="shapeseq-container hidden" id="shapeseq-container">
+    <canvas id="shapeseq-viz"></canvas>
+    <div class="shapeseq-chain-wrap" id="shapeseq-chain"></div>
+  </div>
+
   <!-- Heatmap strip (top) -->
   <div class="heatmap-strip" id="heatmap-strip">
     <div class="heatmap-cells" id="heatmap-cells"></div>
@@ -151,29 +157,16 @@
           <input type="range" id="synth-volume" min="0" max="1" step="0.01" value="0.5">
         </div>
         <div class="synth-row">
-          <label>Arpeggiator</label>
-          <button class="action-btn" id="arp-toggle">Play</button>
-        </div>
-        <div class="synth-row">
-          <label>Progression</label>
-          <select id="arp-progression">
-            <option value="I-vi-IV-V">I-vi-IV-V</option>
-            <option value="I-IV-vi-V">I-IV-vi-V</option>
-            <option value="i-VI-III-VII">i-VI-III-VII</option>
-            <option value="I-V-vi-IV">I-V-vi-IV</option>
-          </select>
+          <label>Sequencer</label>
+          <button class="action-btn" id="seq-toggle">Play</button>
         </div>
         <div class="synth-row">
           <label>Tempo <span id="tempo-val">120</span></label>
-          <input type="range" id="arp-tempo" min="40" max="240" step="1" value="120">
+          <input type="range" id="seq-tempo" min="40" max="240" step="1" value="120">
         </div>
         <div class="synth-row">
-          <label>Octaves <span id="octaves-val">2</span></label>
-          <input type="range" id="arp-octaves" min="1" max="5" step="1" value="2">
-        </div>
-        <div class="synth-row">
-          <label>Oct Offset <span id="offset-val">0</span></label>
-          <input type="range" id="arp-offset" min="-2" max="3" step="1" value="0">
+          <label>Steps <span id="steps-val">8</span></label>
+          <input type="range" id="seq-steps" min="1" max="32" step="1" value="8">
         </div>
         <div class="synth-row" id="midi-row" style="display:none">
           <label>MIDI Input</label>
@@ -293,7 +286,7 @@
             <li><strong>Mute (M)</strong> &mdash; removes the parameter from NISPS control; its bar disappears and you get a manual value slider instead</li>
           </ul>
           <li><strong>MIDI input</strong> &mdash; connect a MIDI controller and it will be detected automatically; MIDI notes trigger the synth directly</li>
-          <li><strong>Arpeggiator</strong> &mdash; expand the bottom bar to access the built-in arpeggiator with tempo, octave range, offset, and chord progression controls; press Pause to stop it</li>
+          <li><strong>ShapeSeq</strong> &mdash; in synth mode, the sequencer UI appears: a circular step visualizer shows the current pattern; the chain builder below lets you add/remove/reorder algorithmic primitives; press Play to start the generative sequencer</li>
         </ul>
       </div>
 
diff --git a/playground/css/a-immersive.css b/playground/css/a-immersive.css
index eb6df4d..c6f2475 100644
--- a/playground/css/a-immersive.css
+++ b/playground/css/a-immersive.css
@@ -98,6 +98,35 @@ html, body {
   display: none;
 }
 
+/* ---- ShapeSeq container (synth mode) ---- */
+.shapeseq-container {
+  position: fixed;
+  inset: 0;
+  z-index: 1;
+  display: flex;
+  flex-direction: column;
+  background: #0d0d0d;
+  overflow: hidden;
+}
+
+.shapeseq-container.hidden {
+  display: none;
+}
+
+#shapeseq-viz {
+  width: 100%;
+  flex: 0 0 45%;
+  min-height: 0;
+}
+
+.shapeseq-chain-wrap {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  overflow-x: hidden;
+  -webkit-overflow-scrolling: touch;
+  padding-bottom: calc(120px + var(--safe-bottom, 0px));
+}
+
 /* ---- Glass mixin ---- */
 .glass {
   background: var(--glass-bg);
diff --git a/playground/js/a-app.js b/playground/js/a-app.js
index 5b3e67f..6806546 100644
--- a/playground/js/a-app.js
+++ b/playground/js/a-app.js
@@ -4,7 +4,10 @@
 import { WasmIML } from './nisps/nisps-wasm.js';
 import { FlowFieldVisualizer } from './ui/visualizer.js';
 import { C15Bridge } from './synth/c15-bridge.js';
-import { Arpeggiator } from './synth/arpeggiator.js';
+import { ShapeSeqEngine } from './shapeseq/sequencer.js';
+import { StepVisualizer } from './shapeseq/step-viz.js';
+import { ChainBuilderUI } from './shapeseq/chain-ui.js';
+import { getDefaultBus } from './shapeseq/event-bus.js';
 import { MIDIInput } from './synth/midi-input.js';
 import { SYNTH_PARAM_MAP, SYNTH_PARAM_NAMES, SYNTH_PARAM_COLORS, applyCurve, applyGroupOverride } from './synth/param-map.js';
 import { GamepadInput } from './ui/gamepad.js';
@@ -73,7 +76,9 @@ let handTracker = null;
 let visualizer;
 let synthVisualizer;
 let c15 = null;
-let arpeggiator = null;
+let shapeSeq = null;      // ShapeSeqEngine instance
+let stepViz = null;       // StepVisualizer
+let chainUI = null;       // ChainBuilderUI
 let midiInput = null;
 
 let outputMode = 'visual';
@@ -703,7 +708,9 @@ async function init() {
     if (el) el.textContent = msg;
   };
   c15.loadParams();
-  arpeggiator = new Arpeggiator(c15);
+
+  // ShapeSeq is initialized lazily when audio starts (needs AudioContext)
+
   midiInput = new MIDIInput(c15);
   initMIDIControls();
 
@@ -752,6 +759,7 @@ async function init() {
   wireQuickPlayControls();
   wireGroupDrawer();
   wireHelp();
+  wireShapeSeqControls();
 
   // Resize
   window.addEventListener('resize', onResize);
@@ -1301,6 +1309,7 @@ function setOutputMode(mode) {
 
   const heatmapStrip = document.getElementById('heatmap-strip');
   const synthQuickControls = document.getElementById('synth-quick-controls');
+  const shapeseqContainer = document.getElementById('shapeseq-container');
 
   if (mode === 'synth') {
     $synthPanel.classList.remove('hidden');
@@ -1309,6 +1318,16 @@ function setOutputMode(mode) {
     heatmapStrip.classList.add('hidden');
     synthQuickControls.classList.remove('hidden');
     synthVisualizer.enableInteraction(true);
+    // Show ShapeSeq UI
+    if (shapeseqContainer) shapeseqContainer.classList.remove('hidden');
+    // Resize step viz canvas to fit its container
+    if (stepViz) {
+      const vizCanvas = document.getElementById('shapeseq-viz');
+      if (vizCanvas) {
+        const rect = vizCanvas.getBoundingClientRect();
+        stepViz.resize(rect.width, rect.height);
+      }
+    }
     // Pulse play button if audio not yet started
     const qp = document.getElementById('quick-play');
     if (qp) qp.classList.toggle('audio-needs-init', !(c15 && c15.running));
@@ -1319,6 +1338,8 @@ function setOutputMode(mode) {
     heatmapStrip.classList.remove('hidden');
     synthQuickControls.classList.add('hidden');
     synthVisualizer.enableInteraction(false);
+    // Hide ShapeSeq UI
+    if (shapeseqContainer) shapeseqContainer.classList.add('hidden');
   }
 
   routeOutputs(iml.getOutputs());
@@ -1567,26 +1588,47 @@ function syncRawParamsFromOutputs(outputs) {
   });
 }
 
+// ---- ShapeSeq lazy init (needs AudioContext from C15) ----
+async function ensureShapeSeqInit() {
+  if (shapeSeq) return; // already initialized
+  if (!c15 || !c15.audioContext) return; // no audio context yet
+
+  const eventBus = getDefaultBus(c15.audioContext);
+  shapeSeq = new ShapeSeqEngine({ audioContext: c15.audioContext, eventBus, c15Bridge: c15 });
+  await shapeSeq.init();
+
+  // Wire up StepVisualizer and ChainBuilderUI now that engine exists
+  const seqVizCanvas = document.getElementById('shapeseq-viz');
+  const seqChainContainer = document.getElementById('shapeseq-chain');
+  if (seqVizCanvas && !stepViz) {
+    stepViz = new StepVisualizer({ canvas: seqVizCanvas, eventBus });
+    const rect = seqVizCanvas.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) stepViz.resize(rect.width, rect.height);
+  }
+  if (seqChainContainer && !chainUI) {
+    chainUI = new ChainBuilderUI({ container: seqChainContainer, chain: shapeSeq.getChain(), eventBus });
+  }
+
+  console.log('[NISPS] ShapeSeq initialized');
+}
+
 // ---- Synth controls ----
 function wireSynthControls() {
   const startBtn = document.getElementById('synth-start');
   const volumeSlider = document.getElementById('synth-volume');
-  const arpToggle = document.getElementById('arp-toggle');
-  const arpProgression = document.getElementById('arp-progression');
-  const arpTempo = document.getElementById('arp-tempo');
-  const arpOctaves = document.getElementById('arp-octaves');
-  const arpOffset = document.getElementById('arp-offset');
 
   startBtn.addEventListener('click', async () => {
     const quickPlay = document.getElementById('quick-play');
     if (c15.running) {
-      arpeggiator.stop();
-      arpToggle.textContent = 'Play';
+      if (shapeSeq) shapeSeq.stop();
+      const seqToggle = document.getElementById('seq-toggle');
+      if (seqToggle) seqToggle.textContent = 'Play';
       await c15.stop();
       startBtn.textContent = 'Start Audio';
       if (quickPlay) quickPlay.classList.add('audio-needs-init');
     } else {
       await c15.start();
+      await ensureShapeSeqInit();
       startBtn.textContent = 'Stop Audio';
       if (quickPlay) quickPlay.classList.remove('audio-needs-init');
       routeOutputs(iml.getOutputs());
@@ -1599,42 +1641,48 @@ function wireSynthControls() {
     if (quickVol) quickVol.value = e.target.value;
   });
 
-  arpToggle.addEventListener('click', () => {
-    if (!c15.running) return;
-    if (arpeggiator.playing) {
-      arpeggiator.stop();
-      arpToggle.textContent = 'Play';
-    } else {
-      arpeggiator.start();
-      arpToggle.textContent = 'Stop';
-    }
-  });
+}
 
-  arpProgression.addEventListener('change', (e) => {
-    arpeggiator.progression = e.target.value;
-  });
+// ---- ShapeSeq controls (bottom sheet) ----
+function wireShapeSeqControls() {
+  const seqToggle = document.getElementById('seq-toggle');
+  const seqTempo = document.getElementById('seq-tempo');
+  const seqSteps = document.getElementById('seq-steps');
 
-  arpTempo.addEventListener('input', (e) => {
-    const val = parseInt(e.target.value);
-    arpeggiator.bpm = val;
-    document.getElementById('tempo-val').textContent = val;
-    const quickBpm = document.getElementById('quick-bpm');
-    const quickBpmVal = document.getElementById('quick-bpm-val');
-    if (quickBpm) quickBpm.value = val;
-    if (quickBpmVal) quickBpmVal.textContent = val;
-  });
+  if (seqToggle) {
+    seqToggle.addEventListener('click', async () => {
+      if (!c15.running) return;
+      await ensureShapeSeqInit();
+      if (!shapeSeq) return;
+      if (shapeSeq.isPlaying) {
+        if (shapeSeq) shapeSeq.stop();
+        seqToggle.textContent = 'Play';
+      } else {
+        shapeSeq.start();
+        seqToggle.textContent = 'Stop';
+      }
+    });
+  }
 
-  arpOctaves.addEventListener('input', (e) => {
-    const val = parseInt(e.target.value);
-    arpeggiator.octaves = val;
-    document.getElementById('octaves-val').textContent = val;
-  });
+  if (seqTempo) {
+    seqTempo.addEventListener('input', (e) => {
+      const val = parseInt(e.target.value);
+      if (shapeSeq) shapeSeq.setTempo(val);
+      document.getElementById('tempo-val').textContent = val;
+      const quickBpm = document.getElementById('quick-bpm');
+      const quickBpmVal = document.getElementById('quick-bpm-val');
+      if (quickBpm) quickBpm.value = val;
+      if (quickBpmVal) quickBpmVal.textContent = val;
+    });
+  }
 
-  arpOffset.addEventListener('input', (e) => {
-    const val = parseInt(e.target.value);
-    arpeggiator.octaveOffset = val;
-    document.getElementById('offset-val').textContent = val;
-  });
+  if (seqSteps) {
+    seqSteps.addEventListener('input', (e) => {
+      const val = parseInt(e.target.value);
+      if (shapeSeq) shapeSeq.setStepCount(val);
+      document.getElementById('steps-val').textContent = val;
+    });
+  }
 }
 
 // ---- MIDI Input ----
@@ -1778,22 +1826,23 @@ function wireQuickPlayControls() {
 
   quickPlay.addEventListener('click', async () => {
     if (c15.running) {
-      arpeggiator.stop();
+      if (shapeSeq) shapeSeq.stop();
       await c15.stop();
       // Also update the bottom sheet controls
       const startBtn = document.getElementById('synth-start');
-      const arpToggle = document.getElementById('arp-toggle');
+      const seqToggle = document.getElementById('seq-toggle');
       if (startBtn) startBtn.textContent = 'Start Audio';
-      if (arpToggle) arpToggle.textContent = 'Play';
+      if (seqToggle) seqToggle.textContent = 'Play';
     } else {
       await c15.start();
-      arpeggiator.start();
+      await ensureShapeSeqInit();
+      if (shapeSeq) shapeSeq.start();
       routeOutputs(iml.getOutputs());
       // Also update the bottom sheet controls
       const startBtn = document.getElementById('synth-start');
-      const arpToggle = document.getElementById('arp-toggle');
+      const seqToggle = document.getElementById('seq-toggle');
       if (startBtn) startBtn.textContent = 'Stop Audio';
-      if (arpToggle) arpToggle.textContent = 'Stop';
+      if (seqToggle) seqToggle.textContent = 'Stop';
     }
     updatePlayIcon();
   });
@@ -1807,10 +1856,10 @@ function wireQuickPlayControls() {
 
   quickBpm.addEventListener('input', (e) => {
     const val = parseInt(e.target.value);
-    arpeggiator.bpm = val;
+    if (shapeSeq) shapeSeq.setTempo(val);
     quickBpmVal.textContent = val;
     // Sync with bottom sheet tempo slider
-    const sheetTempo = document.getElementById('arp-tempo');
+    const sheetTempo = document.getElementById('seq-tempo');
     const sheetTempoVal = document.getElementById('tempo-val');
     if (sheetTempo) sheetTempo.value = val;
     if (sheetTempoVal) sheetTempoVal.textContent = val;
@@ -2142,6 +2191,17 @@ function onResize() {
   visualizer.initParticles();
   synthVisualizer.resize();
 
+  // Resize ShapeSeq step viz if visible
+  if (stepViz && outputMode === 'synth') {
+    const vizCanvas = document.getElementById('shapeseq-viz');
+    if (vizCanvas) {
+      const rect = vizCanvas.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        stepViz.resize(rect.width, rect.height);
+      }
+    }
+  }
+
   // Resize joy-map canvas to match container
   const size = $joystickContainer.offsetWidth;
   if (size > 0) {
@@ -2175,6 +2235,15 @@ function animate() {
   if (gamepad) gamepad.poll();
   if (outputMode === 'synth') {
     synthVisualizer.draw();
+    // Route inputs to ShapeSeq and render step viz
+    if (shapeSeq && shapeSeq.isPlaying) {
+      if (inputMode === 'hands' && handTracker && handTracker.active && handTracker.features) {
+        shapeSeq.setSequenceInputs([handTracker.features[0], handTracker.features[1]]);
+      } else {
+        shapeSeq.setSequenceInputs([joyX, joyY]);
+      }
+    }
+    if (stepViz) stepViz.render();
   } else {
     visualizer.draw();
   }