vizcore 0.1.0 → 1.0.0

data/frontend/src/main.js

@@ -1,6 +1,53 @@
+import { BAND_KEYS, DEFAULT_FFT_BINS, buildAudioInspectorState, formatMeterValue } from "./audio-inspector.js";
+import {
+  createLiveControlState,
+  isTapTempoShortcut,
+  keyboardActionForKey,
+  liveControlStatusText,
+  normalizeKeyboardMappings,
+  shortcutActionForKey,
+  shortcutSceneIndexForKey,
+  toggleLiveControl,
+} from "./live-controls.js";
+import {
+  createPerformanceMonitorState,
+  formatPerformanceMonitorText,
+  recordConnectionStatus,
+  recordLatencyProbe,
+  recordRenderFrame,
+  recordShaderCompile,
+  recordSocketFrame,
+} from "./performance-monitor.js";
+import {
+  loadMidiLearnBindings,
+  midiLearnActionLabel,
+  midiMessageActive,
+  midiMessageSignature,
+  midiMessageUnitValue,
+  midiSignatureLabel,
+  saveMidiLearnBindings,
+  upsertMidiLearnBinding,
+} from "./midi-learn.js";
+import { applyProjectorMode, resolveProjectorMode } from "./projector-mode.js";
 import { Engine } from "./renderer/engine.js";
+import { SHADER_COMPILE_EVENT } from "./renderer/shader-manager.js";
+import {
+  pruneShaderParamOverrides,
+  shaderParamControlEntries
+} from "./shader-param-controls.js";
+import { normalizeRuntimeControlPreset } from "./runtime-control-preset.js";
+import { SHADER_ERROR_EVENT, formatShaderErrorMessage, formatShaderErrorTitle } from "./shader-error-overlay.js";
+import {
+  exportVisualSettingsPreset,
+  importVisualSettingsPreset,
+  loadVisualSettingsPreset,
+  saveVisualSettingsPreset,
+  visualSettingFromUnit
+} from "./visual-settings-preset.js";
 import { WebSocketClient } from "./websocket-client.js";
 
+window.__vizcoreMainStarted = true;
+
 const canvas = document.querySelector("#vizcore-canvas");
 const wsStatusElement = document.querySelector("#ws-status");
 const sceneStatusElement = document.querySelector("#scene-status");
@@ -8,29 +55,112 @@ const transitionStatusElement = document.querySelector("#transition-status");
 const frameStatusElement = document.querySelector("#frame-status");
 const bpmStatusElement = document.querySelector("#bpm-status");
 const beatStatusElement = document.querySelector("#beat-status");
+const blackoutButton = document.querySelector("#blackout-toggle");
+const freezeButton = document.querySelector("#freeze-toggle");
+const liveControlStatusElement = document.querySelector("#live-control-status");
+const performanceMonitorElement = document.querySelector("#performance-monitor");
+const inspectorPeakElement = document.querySelector("#inspector-peak");
+const inspectorAmplitudeFill = document.querySelector("#inspector-amplitude-fill");
+const inspectorAmplitudeValue = document.querySelector("#inspector-amplitude-value");
+const inspectorBandElements = Object.fromEntries(
+  BAND_KEYS.map((key) => [
+    key,
+    {
+      fill: document.querySelector(`#inspector-band-${key}-fill`),
+      value: document.querySelector(`#inspector-band-${key}-value`)
+    }
+  ])
+);
+const fftPreviewElement = document.querySelector("#fft-preview");
 const audioSourceStatusElement = document.querySelector("#audio-source-status");
 const audioTrackStatusElement = document.querySelector("#audio-track-status");
 const audioPlaybackStatusElement = document.querySelector("#audio-playback-status");
 const sceneSwitcherElement = document.querySelector("#scene-switcher");
 const audioToggleButton = document.querySelector("#audio-toggle");
+const visualGainControl = document.querySelector("#visual-gain-control");
+const bassBoostControl = document.querySelector("#bass-boost-control");
+const smoothingControl = document.querySelector("#smoothing-control");
+const beatHoldControl = document.querySelector("#beat-hold-control");
+const wobbleControl = document.querySelector("#wobble-control");
+const reactivitySaveButton = document.querySelector("#reactivity-save");
+const reactivityLoadButton = document.querySelector("#reactivity-load");
+const reactivityProjectSaveButton = document.querySelector("#reactivity-project-save");
+const reactivityExportButton = document.querySelector("#reactivity-export");
+const reactivityImportButton = document.querySelector("#reactivity-import");
+const reactivityStatusElement = document.querySelector("#reactivity-status");
+const midiLearnStatusElement = document.querySelector("#midi-learn-status");
+const midiLearnButtons = Array.from(document.querySelectorAll("[data-midi-learn-action]"));
+const shaderParamControlsElement = document.querySelector("#shader-param-controls");
+const shaderErrorOverlay = document.querySelector("#shader-error-overlay");
+const shaderErrorTitleElement = document.querySelector("#shader-error-title");
+const shaderErrorMessageElement = document.querySelector("#shader-error-message");
+const shaderErrorCloseButton = document.querySelector("#shader-error-close");
+const LATENCY_PROBE_INTERVAL_MS = 3000;
 
-const engine = new Engine(canvas);
-engine.init();
-engine.start();
-
+const visualSettings = loadVisualSettingsPreset(browserStorage());
+let midiLearnBindings = loadMidiLearnBindings(browserStorage());
+const liveControls = createLiveControlState();
+const performanceMonitor = createPerformanceMonitorState();
+let projectorMode = resolveProjectorMode({ body: document.body, location: window.location });
 let currentSceneName = "unknown";
 let audioElement = null;
 let frameCount = 0;
 let lastConnectedAt = null;
 let lastTransportSyncAt = 0;
+let latencyProbeTimer = null;
 let beatFlashUntil = 0;
 let availableSceneNames = [];
+let keyboardMappings = [];
 let pendingSceneName = null;
 let pendingSceneRequestedAt = 0;
+let tapTempoKey = null;
+let runtimeGlobalsReceived = false;
+let runtimeControlPresetApplied = false;
+let controlPresetSaveUrl = null;
+let shaderParamOverrides = {};
+let shaderParamControlsSignature = "";
+let midiAccess = null;
+let pendingMidiLearnAction = null;
+applyProjectorMode(document.body, projectorMode);
+const engine = new Engine(canvas);
+let rendererReady = false;
+bindShaderCompileMetrics();
+try {
+  engine.init();
+  rendererReady = true;
+} catch (error) {
+  renderShaderError({
+    layer: "renderer",
+    shader: "webgl2",
+    message: error instanceof Error ? error.message : String(error)
+  });
+}
+engine.setVisualSettings(visualSettings);
+engine.setLiveControls(liveControls);
+bindLiveControls();
+bindVisualControl(visualGainControl, "visualGain");
+bindVisualControl(bassBoostControl, "bassBoost");
+bindVisualControl(smoothingControl, "smoothing");
+bindVisualControl(beatHoldControl, "beatHoldMs");
+bindVisualControl(wobbleControl, "wobbleAmount");
+bindVisualPresetControls();
+bindMidiLearnControls();
+renderLiveControlStatus();
+renderPerformanceMonitor();
+syncVisualControls();
+renderReactivityStatus();
+renderMidiLearnStatus();
+bindShaderErrorOverlay();
+const fftBars = initializeFftPreview(fftPreviewElement);
+if (rendererReady) {
+  engine.start();
+}
+startPerformanceMonitorLoop();
 
 const websocketUrl = buildWebSocketUrl();
 const client = new WebSocketClient(websocketUrl, {
   onFrame: (frame) => {
+    updatePerformanceMonitor(recordSocketFrame(performanceMonitor, frame, Date.now()));
     engine.setAudioFrame(frame);
     frameCount += 1;
     let sceneName = String(frame?.scene?.name || currentSceneName);
@@ -48,12 +178,16 @@ const client = new WebSocketClient(websocketUrl, {
     }
     const sceneChanged = sceneName !== currentSceneName;
     currentSceneName = sceneName;
+    if (sceneChanged) {
+      shaderParamControlsSignature = "";
+    }
+    updateShaderParamControls(frame?.scene?.layers);
     const amplitude = Number(frame?.audio?.amplitude || 0).toFixed(4);
     const bpm = Number(frame?.audio?.bpm || 0);
     const beat = !!frame?.audio?.beat;
     const beatCount = Math.max(0, Number(frame?.audio?.beat_count || 0) || 0);
     if (beat) {
-      beatFlashUntil = performance.now() + 180;
+      beatFlashUntil = performance.now() + visualSettings.beatHoldMs;
     }
     const beatVisible = performance.now() < beatFlashUntil;
     sceneStatusElement.textContent = `Scene: ${sceneName}`;
@@ -64,6 +198,7 @@ const client = new WebSocketClient(websocketUrl, {
     bpmStatusElement.textContent = `BPM: ${bpm > 0 ? bpm.toFixed(1) : "--"}`;
     beatStatusElement.textContent = `Beat: ${beatVisible ? "ON" : "off"} | Count: ${beatCount}`;
     beatStatusElement.classList.toggle("is-beat", beatVisible);
+    renderAudioInspector(frame?.audio);
   },
   onSceneChange: (payload) => {
     const from = String(payload?.from || "unknown");
@@ -82,13 +217,37 @@ const client = new WebSocketClient(websocketUrl, {
       currentSceneName = String(sceneName);
       sceneStatusElement.textContent = `Scene: ${currentSceneName}`;
       renderSceneButtons();
+      shaderParamControlsSignature = "";
+      updateShaderParamControls(payload?.scene?.layers);
+    }
+    if (Object.prototype.hasOwnProperty.call(payload || {}, "tap_tempo_key")) {
+      updateTapTempoKey(payload?.tap_tempo_key);
+    }
+    if (Object.prototype.hasOwnProperty.call(payload || {}, "key_mappings")) {
+      updateKeyboardMappings(payload?.key_mappings);
+    }
+    if (Object.prototype.hasOwnProperty.call(payload || {}, "globals")) {
+      runtimeGlobalsReceived = true;
+      applyRuntimeGlobals(payload?.globals);
     }
+    if (Object.prototype.hasOwnProperty.call(payload || {}, "live_controls")) {
+      applyLiveControls({
+        ...liveControls,
+        ...normalizeLiveControls(payload?.live_controls),
+      });
+    }
+  },
+  onLatencyProbe: (payload) => {
+    updatePerformanceMonitor(recordLatencyProbe(performanceMonitor, payload, Date.now()));
   },
   onStatus: (status) => {
+    updatePerformanceMonitor(recordConnectionStatus(performanceMonitor, status));
     if (status === "connected") {
       lastConnectedAt = new Date();
+      startLatencyProbeLoop();
       syncAudioTransportToServer({ force: true });
     } else {
+      stopLatencyProbeLoop();
       pendingSceneName = null;
       pendingSceneRequestedAt = 0;
       currentSceneName = "unknown";
@@ -96,7 +255,7 @@ const client = new WebSocketClient(websocketUrl, {
       renderSceneButtons();
     }
     const connectedAt = lastConnectedAt ? ` | Last connected: ${formatClock(lastConnectedAt)}` : "";
-    wsStatusElement.textContent = `WebSocket: ${status}${connectedAt}`;
+    wsStatusElement.textContent = `WebSocket: ${status} (${websocketUrl})${connectedAt}`;
   }
 });
 
@@ -121,9 +280,24 @@ async function fetchRuntime() {
 }
 
 function applyRuntime(runtime) {
+  projectorMode = resolveProjectorMode({
+    body: document.body,
+    current: projectorMode,
+    location: window.location,
+    runtime,
+  });
+  applyProjectorMode(document.body, projectorMode);
+
   const source = String(runtime?.audio_source || "unknown");
   audioSourceStatusElement.textContent = `Audio Source: ${source}`;
   updateAvailableScenes(runtime?.scene_names);
+  updateTapTempoKey(runtime?.tap_tempo_key);
+  updateKeyboardMappings(runtime?.key_mappings);
+  updateControlPresetPersistence(runtime);
+  if (!runtimeGlobalsReceived) {
+    applyRuntimeGlobals(runtime?.globals);
+  }
+  applyRuntimeControlPreset(runtime?.control_preset);
 
   const fileName = runtime?.audio_file_name;
   const fileUrl = runtime?.audio_file_url;
@@ -139,6 +313,43 @@ function applyRuntime(runtime) {
   setupAudioPlayback(fileUrl);
 }
 
+function applyRuntimeGlobals(globals) {
+  engine.setRuntimeGlobals(globals);
+}
+
+function updateControlPresetPersistence(runtime) {
+  const url = String(runtime?.control_preset_url || "").trim();
+  controlPresetSaveUrl = runtime?.control_preset_writable && url ? url : null;
+  if (reactivityProjectSaveButton) {
+    reactivityProjectSaveButton.hidden = !controlPresetSaveUrl;
+  }
+}
+
+function applyRuntimeControlPreset(value) {
+  if (runtimeControlPresetApplied) {
+    return;
+  }
+
+  const preset = normalizeRuntimeControlPreset(value);
+  let applied = false;
+  if (preset.visualSettings) {
+    const imported = importVisualSettingsPreset({ visual_settings: preset.visualSettings }, { fallback: visualSettings });
+    Object.assign(visualSettings, saveVisualSettingsPreset(browserStorage(), imported));
+    syncVisualControls();
+    engine.setVisualSettings(visualSettings);
+    renderReactivityStatus("Project preset");
+    applied = true;
+  }
+
+  if (preset.midiLearnBindings) {
+    midiLearnBindings = saveMidiLearnBindings(browserStorage(), preset.midiLearnBindings);
+    renderMidiLearnStatus();
+    applied = true;
+  }
+
+  runtimeControlPresetApplied = applied;
+}
+
 function updateAvailableScenes(sceneValues) {
   const names = normalizeSceneNames(sceneValues);
   if (!names.length) {
@@ -148,6 +359,16 @@ function updateAvailableScenes(sceneValues) {
   renderSceneButtons();
 }
 
+function updateTapTempoKey(key) {
+  const value = String(key || "").trim().toLowerCase();
+  tapTempoKey = value || null;
+}
+
+function updateKeyboardMappings(mappings) {
+  keyboardMappings = normalizeKeyboardMappings(mappings);
+  renderSceneButtons();
+}
+
 function normalizeSceneNames(sceneValues) {
   const seen = new Set();
   const names = [];
@@ -180,25 +401,247 @@ function renderSceneButtons() {
   sceneSwitcherElement.hidden = false;
   const buttons = availableSceneNames.map((sceneName) => {
     const button = document.createElement("button");
+    const shortcut = sceneShortcutFor(sceneName);
     button.type = "button";
-    button.textContent = sceneName;
+    button.textContent = shortcut ? `${sceneName} [${shortcut}]` : sceneName;
+    button.title = shortcut ? `Shortcut: ${shortcut}` : "";
     button.classList.toggle("is-active", sceneName === currentSceneName);
     button.onclick = () => {
-      if (sceneName === currentSceneName) {
-        return;
-      }
-      pendingSceneName = sceneName;
-      pendingSceneRequestedAt = performance.now();
-      currentSceneName = sceneName;
-      sceneStatusElement.textContent = `Scene: ${sceneName}`;
-      renderSceneButtons();
-      client.send("switch_scene", { scene: sceneName });
+      requestSceneSwitch(sceneName);
     };
     return button;
   });
   sceneSwitcherElement.replaceChildren(...buttons);
 }
 
+function sceneShortcutFor(sceneName) {
+  const mapping = keyboardMappings.find((entry) => (
+    entry.action?.type === "switch_scene" && entry.action.scene === sceneName
+  ));
+  return mapping?.key || "";
+}
+
+function updateShaderParamControls(layers) {
+  if (!shaderParamControlsElement) {
+    return;
+  }
+
+  const entries = shaderParamControlEntries(layers, shaderParamOverrides);
+  const signature = shaderParamControlsSignatureFor(entries);
+  if (signature === shaderParamControlsSignature) {
+    return;
+  }
+
+  shaderParamControlsSignature = signature;
+  shaderParamOverrides = pruneShaderParamOverrides(shaderParamOverrides, entries);
+  engine.setShaderParamOverrides(shaderParamOverrides);
+  renderShaderParamControls(entries);
+}
+
+function shaderParamControlsSignatureFor(entries) {
+  return entries.map((entry) => (
+    `${entry.key}:${entry.min}:${entry.max}:${entry.step}`
+  )).join("|");
+}
+
+function renderShaderParamControls(entries) {
+  if (!shaderParamControlsElement) {
+    return;
+  }
+
+  if (!entries.length) {
+    shaderParamControlsElement.hidden = true;
+    shaderParamControlsElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Shader Params";
+  const controls = entries.map((entry) => createShaderParamControl(entry));
+  shaderParamControlsElement.replaceChildren(title, ...controls);
+  shaderParamControlsElement.hidden = false;
+}
+
+function createShaderParamControl(entry) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = entry.label;
+  input.type = "range";
+  input.min = String(entry.min);
+  input.max = String(entry.max);
+  input.step = String(entry.step);
+  input.value = String(entry.value);
+  value.value = formatShaderParamValue(entry.value);
+  input.addEventListener("input", () => {
+    const numeric = Number(input.value);
+    shaderParamOverrides[entry.layerKey] ||= {};
+    shaderParamOverrides[entry.layerKey][entry.paramName] = numeric;
+    engine.setShaderParamOverrides(shaderParamOverrides);
+    value.value = formatShaderParamValue(numeric);
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function formatShaderParamValue(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return "--";
+  }
+  return Math.abs(numeric) >= 10 ? numeric.toFixed(1) : numeric.toFixed(2);
+}
+
+function requestSceneSwitch(sceneName) {
+  if (!sceneName || sceneName === currentSceneName) {
+    return;
+  }
+
+  pendingSceneName = sceneName;
+  pendingSceneRequestedAt = performance.now();
+  currentSceneName = sceneName;
+  sceneStatusElement.textContent = `Scene: ${sceneName}`;
+  renderSceneButtons();
+  client.send("switch_scene", { scene: sceneName });
+}
+
+function applyKeyboardAction(action) {
+  if (action?.type === "switch_scene") {
+    requestSceneSwitch(action.scene);
+    return;
+  }
+
+  if (action?.type === "live_control") {
+    applyLiveControls(toggleLiveControl(liveControls, action.control));
+  }
+}
+
+function startPerformanceMonitorLoop() {
+  requestAnimationFrame((time) => {
+    updatePerformanceMonitor(recordRenderFrame(performanceMonitor, time));
+    startPerformanceMonitorLoop();
+  });
+}
+
+function startLatencyProbeLoop() {
+  stopLatencyProbeLoop();
+  sendLatencyProbe();
+  latencyProbeTimer = setInterval(sendLatencyProbe, LATENCY_PROBE_INTERVAL_MS);
+}
+
+function stopLatencyProbeLoop() {
+  if (!latencyProbeTimer) {
+    return;
+  }
+
+  clearInterval(latencyProbeTimer);
+  latencyProbeTimer = null;
+}
+
+function sendLatencyProbe() {
+  client.send("latency_probe", {
+    client_sent_at_ms: Date.now()
+  });
+}
+
+function updatePerformanceMonitor(nextState) {
+  Object.assign(performanceMonitor, nextState);
+  renderPerformanceMonitor();
+}
+
+function renderPerformanceMonitor() {
+  if (!performanceMonitorElement) {
+    return;
+  }
+
+  performanceMonitorElement.textContent = formatPerformanceMonitorText(performanceMonitor);
+}
+
+function bindShaderCompileMetrics() {
+  window.addEventListener(SHADER_COMPILE_EVENT, (event) => {
+    updatePerformanceMonitor(recordShaderCompile(performanceMonitor, event.detail));
+  });
+}
+
+function bindLiveControls() {
+  bindLiveControlButton(blackoutButton, "blackout");
+  bindLiveControlButton(freezeButton, "freeze");
+  window.addEventListener("keydown", (event) => {
+    const keyboardAction = keyboardActionForKey(event, keyboardMappings);
+    if (keyboardAction) {
+      event.preventDefault();
+      applyKeyboardAction(keyboardAction);
+      return;
+    }
+
+    const action = shortcutActionForKey(event);
+    if (action) {
+      event.preventDefault();
+      applyLiveControls(toggleLiveControl(liveControls, action));
+      return;
+    }
+
+    const sceneIndex = shortcutSceneIndexForKey(event, availableSceneNames.length);
+    if (sceneIndex === null) {
+      return;
+    }
+
+    event.preventDefault();
+    requestSceneSwitch(availableSceneNames[sceneIndex]);
+  });
+
+  window.addEventListener("keydown", (event) => {
+    if (!isTapTempoShortcut(event, tapTempoKey)) {
+      return;
+    }
+
+    event.preventDefault();
+    client.send("tap_tempo", { client_tapped_at_ms: Date.now() });
+  });
+}
+
+function bindLiveControlButton(button, control) {
+  if (!button) {
+    return;
+  }
+
+  button.addEventListener("click", () => {
+    applyLiveControls(toggleLiveControl(liveControls, control));
+  });
+}
+
+function applyLiveControls(nextState) {
+  Object.assign(liveControls, nextState);
+  engine.setLiveControls(liveControls);
+  renderLiveControlStatus();
+}
+
+function normalizeLiveControls(value) {
+  const input = value && typeof value === "object" ? value : {};
+  return {
+    blackout: !!input.blackout,
+    freeze: !!input.freeze,
+  };
+}
+
+function renderLiveControlStatus() {
+  if (liveControlStatusElement) {
+    liveControlStatusElement.textContent = liveControlStatusText(liveControls);
+  }
+
+  if (blackoutButton) {
+    blackoutButton.classList.toggle("is-active", liveControls.blackout);
+    blackoutButton.setAttribute("aria-pressed", String(liveControls.blackout));
+  }
+
+  if (freezeButton) {
+    freezeButton.classList.toggle("is-active", liveControls.freeze);
+    freezeButton.setAttribute("aria-pressed", String(liveControls.freeze));
+  }
+}
+
 function setupAudioPlayback(audioUrl) {
   if (audioElement) {
     audioElement.pause();
@@ -298,6 +741,339 @@ function syncAudioTransportToServer({ force = false } = {}) {
   }
 }
 
+function bindVisualControl(control, key, parser = Number) {
+  if (!control) return;
+  control.addEventListener("input", () => {
+    visualSettings[key] = parser(control.value);
+    engine.setVisualSettings(visualSettings);
+    renderReactivityStatus();
+  });
+}
+
+function bindVisualPresetControls() {
+  if (reactivitySaveButton) {
+    reactivitySaveButton.addEventListener("click", () => {
+      Object.assign(visualSettings, saveVisualSettingsPreset(browserStorage(), visualSettings));
+      renderReactivityStatus("Saved");
+    });
+  }
+
+  if (reactivityLoadButton) {
+    reactivityLoadButton.addEventListener("click", () => {
+      Object.assign(visualSettings, loadVisualSettingsPreset(browserStorage(), { fallback: visualSettings }));
+      syncVisualControls();
+      engine.setVisualSettings(visualSettings);
+      renderReactivityStatus("Loaded");
+    });
+  }
+
+  if (reactivityProjectSaveButton) {
+    reactivityProjectSaveButton.addEventListener("click", async () => {
+      if (!controlPresetSaveUrl) {
+        renderReactivityStatus("Project save unavailable");
+        return;
+      }
+
+      const saved = await saveProjectControlPreset();
+      renderReactivityStatus(saved ? "Project saved" : "Project save failed");
+    });
+  }
+
+  if (reactivityExportButton) {
+    reactivityExportButton.addEventListener("click", async () => {
+      const payload = exportVisualSettingsPreset(visualSettings);
+      const copied = await writeClipboardText(payload);
+      if (!copied && typeof window.prompt === "function") {
+        window.prompt("Visual preset JSON", payload);
+      }
+      renderReactivityStatus(copied ? "Exported" : "Export ready");
+    });
+  }
+
+  if (reactivityImportButton) {
+    reactivityImportButton.addEventListener("click", () => {
+      if (typeof window.prompt !== "function") {
+        renderReactivityStatus("Import unavailable");
+        return;
+      }
+
+      const payload = window.prompt("Paste visual preset JSON");
+      if (!payload) {
+        renderReactivityStatus();
+        return;
+      }
+
+      Object.assign(visualSettings, importVisualSettingsPreset(payload, { fallback: visualSettings }));
+      Object.assign(visualSettings, saveVisualSettingsPreset(browserStorage(), visualSettings));
+      syncVisualControls();
+      engine.setVisualSettings(visualSettings);
+      renderReactivityStatus("Imported");
+    });
+  }
+}
+
+async function saveProjectControlPreset() {
+  try {
+    const response = await fetch(controlPresetSaveUrl, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        visual_settings: visualSettings,
+        midi_learn_bindings: midiLearnBindings,
+      }),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+function bindMidiLearnControls() {
+  midiLearnButtons.forEach((button) => {
+    button.addEventListener("click", async () => {
+      const action = midiLearnActionForButton(button);
+      if (!action) {
+        renderMidiLearnStatus("No action selected");
+        return;
+      }
+
+      const ready = await ensureMidiAccess();
+      if (!ready) {
+        renderMidiLearnStatus("Web MIDI unavailable");
+        return;
+      }
+
+      pendingMidiLearnAction = action;
+      renderMidiLearnStatus(`Move a MIDI control for ${midiLearnActionLabel(action)}`);
+    });
+  });
+}
+
+function midiLearnActionForButton(button) {
+  const action = String(button?.dataset?.midiLearnAction || "");
+  if (action === "current-scene") {
+    return currentSceneName && currentSceneName !== "unknown"
+      ? { type: "switch_scene", scene: currentSceneName }
+      : null;
+  }
+  if (action === "blackout" || action === "freeze") {
+    return { type: "live_control", control: action };
+  }
+  if (action.startsWith("visual:")) {
+    return { type: "visual_setting", key: action.slice(7) };
+  }
+  return null;
+}
+
+async function ensureMidiAccess() {
+  if (midiAccess) {
+    return true;
+  }
+
+  const requestMIDIAccess = typeof navigator === "undefined" ? null : navigator.requestMIDIAccess;
+  if (typeof requestMIDIAccess !== "function") {
+    return false;
+  }
+
+  try {
+    midiAccess = await requestMIDIAccess.call(navigator);
+    bindMidiInputs(midiAccess.inputs);
+    midiAccess.onstatechange = () => {
+      bindMidiInputs(midiAccess.inputs);
+      renderMidiLearnStatus();
+    };
+    return true;
+  } catch {
+    midiAccess = null;
+    return false;
+  }
+}
+
+function bindMidiInputs(inputs) {
+  for (const input of inputs.values()) {
+    input.onmidimessage = handleMidiMessage;
+  }
+}
+
+function handleMidiMessage(event) {
+  const signature = midiMessageSignature(event?.data);
+  if (!signature) {
+    return;
+  }
+
+  if (pendingMidiLearnAction && midiMessageActive(event?.data)) {
+    midiLearnBindings = upsertMidiLearnBinding(midiLearnBindings, signature, pendingMidiLearnAction);
+    midiLearnBindings = saveMidiLearnBindings(browserStorage(), midiLearnBindings);
+    renderMidiLearnStatus(`Learned ${midiSignatureLabel(signature)} -> ${midiLearnActionLabel(pendingMidiLearnAction)}`);
+    pendingMidiLearnAction = null;
+    return;
+  }
+
+  const action = midiLearnBindings[signature];
+  if (!action) {
+    return;
+  }
+
+  applyMidiLearnAction(action, midiMessageUnitValue(event?.data), midiMessageActive(event?.data));
+}
+
+function applyMidiLearnAction(action, unitValue, active) {
+  if (action.type === "visual_setting") {
+    visualSettings[action.key] = visualSettingFromUnit(action.key, unitValue, visualSettings[action.key]);
+    syncVisualControls();
+    engine.setVisualSettings(visualSettings);
+    renderReactivityStatus("MIDI");
+    return;
+  }
+
+  if (!active || unitValue <= 0) {
+    return;
+  }
+
+  if (action.type === "switch_scene") {
+    requestSceneSwitch(action.scene);
+    renderMidiLearnStatus(`MIDI: ${midiLearnActionLabel(action)}`);
+    return;
+  }
+
+  if (action.type === "live_control") {
+    applyLiveControls(toggleLiveControl(liveControls, action.control));
+    renderMidiLearnStatus(`MIDI: ${midiLearnActionLabel(action)}`);
+  }
+}
+
+function syncVisualControls() {
+  setControlValue(visualGainControl, visualSettings.visualGain);
+  setControlValue(bassBoostControl, visualSettings.bassBoost);
+  setControlValue(smoothingControl, visualSettings.smoothing);
+  setControlValue(beatHoldControl, visualSettings.beatHoldMs);
+  setControlValue(wobbleControl, visualSettings.wobbleAmount);
+}
+
+function setControlValue(control, value) {
+  if (control) {
+    control.value = String(value);
+  }
+}
+
+function browserStorage() {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+async function writeClipboardText(value) {
+  try {
+    const clipboard = typeof navigator === "undefined" ? null : navigator.clipboard;
+    if (!clipboard?.writeText) {
+      return false;
+    }
+    await clipboard.writeText(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function renderReactivityStatus(prefix = null) {
+  if (!reactivityStatusElement) {
+    return;
+  }
+
+  const values = [
+    `Visual Gain: ${visualSettings.visualGain.toFixed(1)}x`,
+    `Bass: ${visualSettings.bassBoost.toFixed(1)}x`,
+    `Smooth: ${visualSettings.smoothing.toFixed(2)}`,
+    `Beat Hold: ${Math.round(visualSettings.beatHoldMs)}ms`,
+    `Wobble: ${visualSettings.wobbleAmount.toFixed(2)}x`,
+  ].join(" | ");
+
+  reactivityStatusElement.textContent = prefix ? `${prefix} | ${values}` : values;
+}
+
+function renderMidiLearnStatus(prefix = null) {
+  if (!midiLearnStatusElement) {
+    return;
+  }
+
+  const bindingCount = Object.keys(midiLearnBindings).length;
+  const accessState = midiAccess ? "ready" : "idle";
+  midiLearnStatusElement.textContent = prefix || `MIDI Learn: ${accessState} | Bindings: ${bindingCount}`;
+}
+
+function bindShaderErrorOverlay() {
+  window.addEventListener(SHADER_ERROR_EVENT, (event) => {
+    renderShaderError(event.detail);
+  });
+  if (shaderErrorCloseButton) {
+    shaderErrorCloseButton.addEventListener("click", () => {
+      if (shaderErrorOverlay) {
+        shaderErrorOverlay.hidden = true;
+      }
+    });
+  }
+}
+
+function renderShaderError(detail) {
+  if (!shaderErrorOverlay || !shaderErrorTitleElement || !shaderErrorMessageElement) {
+    return;
+  }
+
+  shaderErrorTitleElement.textContent = formatShaderErrorTitle(detail);
+  shaderErrorMessageElement.textContent = formatShaderErrorMessage(detail);
+  shaderErrorOverlay.hidden = false;
+}
+
+function initializeFftPreview(container) {
+  if (!container) {
+    return [];
+  }
+
+  const bars = Array.from({ length: DEFAULT_FFT_BINS }, () => {
+    const bar = document.createElement("span");
+    bar.className = "fft-bar";
+    bar.setAttribute("aria-hidden", "true");
+    return bar;
+  });
+  container.replaceChildren(...bars);
+  return bars;
+}
+
+function renderAudioInspector(audio) {
+  const state = buildAudioInspectorState(audio);
+  setMeter(inspectorAmplitudeFill, inspectorAmplitudeValue, state.amplitude, 3);
+
+  for (const key of BAND_KEYS) {
+    const elements = inspectorBandElements[key] || {};
+    setMeter(elements.fill, elements.value, state.bands[key], 2);
+  }
+
+  state.fft.forEach((value, index) => {
+    const bar = fftBars[index];
+    if (!bar) {
+      return;
+    }
+    bar.style.setProperty("--bin-value", value.toFixed(4));
+  });
+
+  if (inspectorPeakElement) {
+    inspectorPeakElement.textContent = state.peakFrequency > 0
+      ? `Peak: ${Math.round(state.peakFrequency)} Hz`
+      : "Peak: --";
+  }
+}
+
+function setMeter(fill, valueElement, value, digits) {
+  if (fill) {
+    fill.style.setProperty("--meter-value", value.toFixed(4));
+  }
+  if (valueElement) {
+    valueElement.textContent = formatMeterValue(value, digits);
+  }
+}
+
 function buildWebSocketUrl() {
   const protocol = window.location.protocol === "https:" ? "wss" : "ws";
   return `${protocol}://${window.location.host}/ws`;