vizcore 1.0.0 → 1.2.0

data/frontend/src/main.js

@@ -1,10 +1,12 @@
 import { BAND_KEYS, DEFAULT_FFT_BINS, buildAudioInspectorState, formatMeterValue } from "./audio-inspector.js";
 import {
   createLiveControlState,
+  isLiveControlEnabled,
   isTapTempoShortcut,
   keyboardActionForKey,
   liveControlStatusText,
   normalizeKeyboardMappings,
+  normalizeLiveControlPayload,
   shortcutActionForKey,
   shortcutSceneIndexForKey,
   toggleLiveControl,
@@ -15,7 +17,10 @@ import {
   recordConnectionStatus,
   recordLatencyProbe,
   recordRenderFrame,
+  recordRendererCapabilities,
+  recordRendererSafeMode,
   recordShaderCompile,
+  recordWebSocketBackpressure,
   recordSocketFrame,
 } from "./performance-monitor.js";
 import {
@@ -29,12 +34,26 @@ import {
   upsertMidiLearnBinding,
 } from "./midi-learn.js";
 import { applyProjectorMode, resolveProjectorMode } from "./projector-mode.js";
-import { Engine } from "./renderer/engine.js";
+import { Engine, RENDERER_CAPABILITIES_EVENT, RENDERER_SAFE_MODE_EVENT } from "./renderer/engine.js";
 import { SHADER_COMPILE_EVENT } from "./renderer/shader-manager.js";
+import {
+  customShapeParamControlEntries,
+  customShapeParamMessage,
+  pruneCustomShapeParamOverrides
+} from "./custom-shape-param-controls.js";
+import {
+  mappingTargetOptions,
+  mappingTargetSignature
+} from "./mapping-target-selector.js";
 import {
   pruneShaderParamOverrides,
   shaderParamControlEntries
 } from "./shader-param-controls.js";
+import {
+  normalizeShapeEditorPatch,
+  pruneShapeEditorOverrides,
+  shapeEditorEntries
+} from "./shape-editor-controls.js";
 import { normalizeRuntimeControlPreset } from "./runtime-control-preset.js";
 import { SHADER_ERROR_EVENT, formatShaderErrorMessage, formatShaderErrorTitle } from "./shader-error-overlay.js";
 import {
@@ -44,6 +63,7 @@ import {
   saveVisualSettingsPreset,
   visualSettingFromUnit
 } from "./visual-settings-preset.js";
+import { applyScenePayload, resolveScenePayload } from "./scene-patches.js";
 import { WebSocketClient } from "./websocket-client.js";
 
 window.__vizcoreMainStarted = true;
@@ -53,6 +73,7 @@ const wsStatusElement = document.querySelector("#ws-status");
 const sceneStatusElement = document.querySelector("#scene-status");
 const transitionStatusElement = document.querySelector("#transition-status");
 const frameStatusElement = document.querySelector("#frame-status");
+const runtimeErrorStatusElement = document.querySelector("#runtime-error-status");
 const bpmStatusElement = document.querySelector("#bpm-status");
 const beatStatusElement = document.querySelector("#beat-status");
 const blackoutButton = document.querySelector("#blackout-toggle");
@@ -73,6 +94,7 @@ const inspectorBandElements = Object.fromEntries(
 );
 const fftPreviewElement = document.querySelector("#fft-preview");
 const audioSourceStatusElement = document.querySelector("#audio-source-status");
+const audioHealthStatusElement = document.querySelector("#audio-health-status");
 const audioTrackStatusElement = document.querySelector("#audio-track-status");
 const audioPlaybackStatusElement = document.querySelector("#audio-playback-status");
 const sceneSwitcherElement = document.querySelector("#scene-switcher");
@@ -91,6 +113,9 @@ 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 shapeEditorControlsElement = document.querySelector("#shape-editor-controls");
+const customShapeParamControlsElement = document.querySelector("#custom-shape-param-controls");
+const mappingTargetSelectorElement = document.querySelector("#mapping-target-selector");
 const shaderErrorOverlay = document.querySelector("#shader-error-overlay");
 const shaderErrorTitleElement = document.querySelector("#shader-error-title");
 const shaderErrorMessageElement = document.querySelector("#shader-error-message");
@@ -116,15 +141,27 @@ let pendingSceneRequestedAt = 0;
 let tapTempoKey = null;
 let runtimeGlobalsReceived = false;
 let runtimeControlPresetApplied = false;
+let runtimeControlPresetSceneApplied = null;
+let runtimeControlPresetSceneOverrides = {};
+let runtimeControlPresetVisualBase = null;
+let runtimeControlPresetMidiBase = null;
 let controlPresetSaveUrl = null;
 let shaderParamOverrides = {};
+let scenePayload = null;
 let shaderParamControlsSignature = "";
+let shapeEditorOverrides = {};
+let shapeEditorControlsSignature = "";
+let customShapeParamOverrides = {};
+let customShapeParamControlsSignature = "";
+let mappingTargetSelectorSignature = "";
+let selectedMappingTarget = "";
 let midiAccess = null;
 let pendingMidiLearnAction = null;
 applyProjectorMode(document.body, projectorMode);
 const engine = new Engine(canvas);
 let rendererReady = false;
 bindShaderCompileMetrics();
+bindRendererMetrics();
 try {
   engine.init();
   rendererReady = true;
@@ -160,10 +197,26 @@ startPerformanceMonitorLoop();
 const websocketUrl = buildWebSocketUrl();
 const client = new WebSocketClient(websocketUrl, {
   onFrame: (frame) => {
+    const resolvedScene = resolveScenePayload({
+      incomingScene: frame?.scene,
+      currentScene: scenePayload,
+      frameVersion: frame?.scene_version,
+    });
+    if (resolvedScene) {
+      scenePayload = resolvedScene;
+    }
+    const normalizedFrame = {
+      ...frame,
+      scene: scenePayload
+    };
+
     updatePerformanceMonitor(recordSocketFrame(performanceMonitor, frame, Date.now()));
-    engine.setAudioFrame(frame);
+    engine.setAudioFrame(normalizedFrame);
     frameCount += 1;
-    let sceneName = String(frame?.scene?.name || currentSceneName);
+    const scene = scenePayload;
+    let sceneName = String(scene?.name || currentSceneName);
+    document.body.dataset.vizcoreFrameCount = String(frameCount);
+    document.body.dataset.vizcoreScene = sceneName;
     const now = performance.now();
     if (
       pendingSceneName &&
@@ -176,12 +229,8 @@ const client = new WebSocketClient(websocketUrl, {
       pendingSceneName = null;
       pendingSceneRequestedAt = 0;
     }
-    const sceneChanged = sceneName !== currentSceneName;
-    currentSceneName = sceneName;
-    if (sceneChanged) {
-      shaderParamControlsSignature = "";
-    }
-    updateShaderParamControls(frame?.scene?.layers);
+    applyRuntimeControlPresetForScene(sceneName);
+    updateSceneControls(scene);
     const amplitude = Number(frame?.audio?.amplitude || 0).toFixed(4);
     const bpm = Number(frame?.audio?.bpm || 0);
     const beat = !!frame?.audio?.beat;
@@ -191,9 +240,6 @@ const client = new WebSocketClient(websocketUrl, {
     }
     const beatVisible = performance.now() < beatFlashUntil;
     sceneStatusElement.textContent = `Scene: ${sceneName}`;
-    if (sceneChanged) {
-      renderSceneButtons();
-    }
     frameStatusElement.textContent = `Amplitude: ${amplitude} | Frames: ${frameCount}`;
     bpmStatusElement.textContent = `BPM: ${bpm > 0 ? bpm.toFixed(1) : "--"}`;
     beatStatusElement.textContent = `Beat: ${beatVisible ? "ON" : "off"} | Count: ${beatCount}`;
@@ -207,6 +253,7 @@ const client = new WebSocketClient(websocketUrl, {
     pendingSceneRequestedAt = 0;
     currentSceneName = to;
     sceneStatusElement.textContent = `Scene: ${to}`;
+    applyRuntimeControlPresetForScene(to, { force: true });
     transitionStatusElement.textContent = `Transition: ${from} -> ${to}`;
     renderSceneButtons();
   },
@@ -214,11 +261,9 @@ const client = new WebSocketClient(websocketUrl, {
     updateAvailableScenes(payload?.scenes);
     const sceneName = payload?.scene?.name;
     if (sceneName) {
-      currentSceneName = String(sceneName);
-      sceneStatusElement.textContent = `Scene: ${currentSceneName}`;
-      renderSceneButtons();
-      shaderParamControlsSignature = "";
-      updateShaderParamControls(payload?.scene?.layers);
+      scenePayload = applyScenePayload(payload.scene);
+      applyRuntimeControlPresetForScene(sceneName, { force: true });
+      updateSceneControls(scenePayload, { forceReset: true });
     }
     if (Object.prototype.hasOwnProperty.call(payload || {}, "tap_tempo_key")) {
       updateTapTempoKey(payload?.tap_tempo_key);
@@ -232,7 +277,6 @@ const client = new WebSocketClient(websocketUrl, {
     }
     if (Object.prototype.hasOwnProperty.call(payload || {}, "live_controls")) {
       applyLiveControls({
-        ...liveControls,
         ...normalizeLiveControls(payload?.live_controls),
       });
     }
@@ -240,12 +284,18 @@ const client = new WebSocketClient(websocketUrl, {
   onLatencyProbe: (payload) => {
     updatePerformanceMonitor(recordLatencyProbe(performanceMonitor, payload, Date.now()));
   },
+  onRuntimeError: (payload) => {
+    updateRuntimeErrorStatus(payload);
+  },
   onStatus: (status) => {
     updatePerformanceMonitor(recordConnectionStatus(performanceMonitor, status));
     if (status === "connected") {
       lastConnectedAt = new Date();
       startLatencyProbeLoop();
       syncAudioTransportToServer({ force: true });
+      if (runtimeErrorStatusElement) {
+        runtimeErrorStatusElement.textContent = "Runtime: ok";
+      }
     } else {
       stopLatencyProbeLoop();
       pendingSceneName = null;
@@ -253,9 +303,12 @@ const client = new WebSocketClient(websocketUrl, {
       currentSceneName = "unknown";
       sceneStatusElement.textContent = "Scene: unknown";
       renderSceneButtons();
+      if (runtimeErrorStatusElement) {
+        runtimeErrorStatusElement.textContent = "Runtime: disconnected";
+      }
     }
-    const connectedAt = lastConnectedAt ? ` | Last connected: ${formatClock(lastConnectedAt)}` : "";
-    wsStatusElement.textContent = `WebSocket: ${status} (${websocketUrl})${connectedAt}`;
+  const connectedAt = lastConnectedAt ? ` | Last connected: ${formatClock(lastConnectedAt)}` : "";
+  wsStatusElement.textContent = `WebSocket: ${status} (${websocketUrl})${connectedAt}`;
   }
 });
 
@@ -298,9 +351,11 @@ function applyRuntime(runtime) {
     applyRuntimeGlobals(runtime?.globals);
   }
   applyRuntimeControlPreset(runtime?.control_preset);
+  updatePerformanceMonitor(recordWebSocketBackpressure(performanceMonitor, runtime?.websocket_backpressure));
 
   const fileName = runtime?.audio_file_name;
   const fileUrl = runtime?.audio_file_url;
+  applyRuntimeAudioInputHealth(runtime?.input);
   if (!fileUrl) {
     engine.setMediaElement(null);
     audioTrackStatusElement.textContent = "Track: none";
@@ -313,6 +368,33 @@ function applyRuntime(runtime) {
   setupAudioPlayback(fileUrl);
 }
 
+function applyRuntimeAudioInputHealth(input) {
+  if (!audioHealthStatusElement) {
+    return;
+  }
+
+  const source = String(input?.source || "unknown");
+  const sampleRate = Number(input?.sample_rate);
+  const requestedSampleRate = Number(input?.requested_sample_rate);
+  const frameSize = Number(input?.frame_size);
+  const ringBuffer = input?.ring_buffer || {};
+  const overrun = Number(ringBuffer?.overrun_count || 0);
+  const underrun = Number(ringBuffer?.underrun_count || 0);
+  const sampleRateText = Number.isFinite(sampleRate) && sampleRate > 0
+    ? `${Math.round(sampleRate)}Hz`
+    : "--";
+  const requestedSampleRateText = Number.isFinite(requestedSampleRate) &&
+      requestedSampleRate > 0 &&
+      requestedSampleRate !== sampleRate
+    ? ` (${Math.round(requestedSampleRate)}Hz requested)`
+    : "";
+  const frameText = Number.isFinite(frameSize) && frameSize > 0
+    ? ` | Frame ${Math.round(frameSize)}`
+    : "";
+
+  audioHealthStatusElement.textContent = `Input: ${source} | Sample ${sampleRateText}${requestedSampleRateText} | ${frameText} | Overrun ${Math.max(0, overrun)} | Underrun ${Math.max(0, underrun)}`;
+}
+
 function applyRuntimeGlobals(globals) {
   engine.setRuntimeGlobals(globals);
 }
@@ -326,28 +408,205 @@ function updateControlPresetPersistence(runtime) {
 }
 
 function applyRuntimeControlPreset(value) {
-  if (runtimeControlPresetApplied) {
+  if (!value || 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));
+  const hasVisual = Boolean(preset.visualSettings);
+  const hasMidi = Boolean(preset.midiLearnBindings);
+  const hasSceneOverrides = preset.sceneOverrides && Object.keys(preset.sceneOverrides).length > 0;
+  if (!hasVisual && !hasMidi && !hasSceneOverrides) {
+    return;
+  }
+
+  if (hasVisual) {
+    const imported = importVisualSettingsPreset(
+      { visual_settings: preset.visualSettings },
+      { fallback: visualSettings }
+    );
+    Object.assign(visualSettings, imported);
+    runtimeControlPresetVisualBase = cloneRuntimeValue(visualSettings);
+    saveVisualSettingsPreset(browserStorage(), visualSettings);
     syncVisualControls();
     engine.setVisualSettings(visualSettings);
     renderReactivityStatus("Project preset");
-    applied = true;
+  } else {
+    runtimeControlPresetVisualBase = cloneRuntimeValue(visualSettings);
   }
 
-  if (preset.midiLearnBindings) {
-    midiLearnBindings = saveMidiLearnBindings(browserStorage(), preset.midiLearnBindings);
+  if (hasMidi) {
+    midiLearnBindings = cloneRuntimeValue(preset.midiLearnBindings);
+    runtimeControlPresetMidiBase = cloneRuntimeValue(midiLearnBindings);
+    saveMidiLearnBindings(browserStorage(), midiLearnBindings);
     renderMidiLearnStatus();
-    applied = true;
+  } else {
+    runtimeControlPresetMidiBase = cloneRuntimeValue(midiLearnBindings);
+  }
+
+  runtimeControlPresetSceneOverrides = cloneRuntimeValue(preset.sceneOverrides || {});
+  runtimeControlPresetApplied = true;
+  runtimeControlPresetSceneApplied = null;
+  applyRuntimeControlPresetForScene(currentSceneName, { force: true });
+}
+
+function applyRuntimeControlPresetForScene(sceneName, { force = false } = {}) {
+  if (!runtimeControlPresetApplied) {
+    return;
+  }
+
+  const normalizedScene = normalizeSceneName(sceneName || currentSceneName);
+  if (!force && runtimeControlPresetSceneApplied === normalizedScene) {
+    return;
+  }
+  runtimeControlPresetSceneApplied = normalizedScene;
+
+  const override = normalizeRuntimeSceneOverride(runtimeControlPresetSceneOverrides[normalizedScene]) || {};
+  const nextVisual = deriveSceneVisualSettings(runtimeControlPresetVisualBase, override.visualSettings);
+  if (nextVisual) {
+    const hasVisualChanges = hasVisualSettingsChanges(visualSettings, nextVisual);
+    if (hasVisualChanges) {
+      Object.assign(visualSettings, nextVisual);
+      syncVisualControls();
+      engine.setVisualSettings(visualSettings);
+      renderReactivityStatus("Project preset");
+    }
+  }
+
+  const nextBindings = deriveSceneMidiBindings(runtimeControlPresetMidiBase, override.midiLearnBindings);
+  if (nextBindings && hasMidiLearnBindingChanges(midiLearnBindings, nextBindings)) {
+    midiLearnBindings = nextBindings;
+    renderMidiLearnStatus();
+  }
+}
+
+function deriveSceneVisualSettings(baseSettings, sceneVisualSettings) {
+  const base = baseSettings && typeof baseSettings === "object" ? cloneRuntimeValue(baseSettings) : {};
+  if (sceneVisualSettings) {
+    return Object.assign(base, cloneRuntimeValue(sceneVisualSettings));
+  }
+  return Object.keys(base).length ? base : null;
+}
+
+function deriveSceneMidiBindings(baseBindings, sceneMidiBindings) {
+  const base = baseBindings && typeof baseBindings === "object" ? cloneRuntimeValue(baseBindings) : {};
+  if (sceneMidiBindings) {
+    return Object.assign(base, cloneRuntimeValue(sceneMidiBindings));
+  }
+  return Object.keys(base).length ? base : null;
+}
+
+function normalizeRuntimeSceneOverride(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const input = value && typeof value === "object" ? value : {};
+  const output = {};
+  const visualSettings = objectValue(input.visualSettings) || objectValue(input.visual_settings);
+  const midiLearnBindings = objectValue(input.midiLearnBindings) || objectValue(input.midi_learn_bindings);
+  if (visualSettings) {
+    output.visualSettings = visualSettings;
+  }
+  if (midiLearnBindings) {
+    output.midiLearnBindings = midiLearnBindings;
+  }
+  return Object.keys(output).length ? output : null;
+}
+
+function syncRuntimeControlPresetSceneVisualSetting(key, value) {
+  if (!runtimeControlPresetApplied) {
+    return;
+  }
+
+  const sceneName = normalizeSceneName(currentSceneName);
+  const override = runtimeControlPresetSceneOverrides[sceneName];
+  if (override && typeof override === "object") {
+    const normalizedSceneOverride = normalizeRuntimeSceneOverride(override) || {};
+    const currentOverride = cloneRuntimeValue(normalizedSceneOverride);
+    currentOverride.visualSettings ||= {};
+    currentOverride.visualSettings[key] = value;
+    runtimeControlPresetSceneOverrides[sceneName] = currentOverride;
+    applyRuntimeControlPresetForScene(sceneName, { force: true });
+    return;
+  }
+
+  runtimeControlPresetVisualBase = runtimeControlPresetVisualBase || cloneRuntimeValue(visualSettings);
+  runtimeControlPresetVisualBase[key] = value;
+}
+
+function syncRuntimeControlPresetMidiBindings(nextBindings) {
+  if (!runtimeControlPresetApplied) {
+    return;
+  }
+
+  const sceneName = normalizeSceneName(currentSceneName);
+  const normalizedBindings = objectValue(nextBindings) ? cloneRuntimeValue(nextBindings) : {};
+  const override = runtimeControlPresetSceneOverrides[sceneName];
+  if (override && typeof override === "object") {
+    const normalizedSceneOverride = normalizeRuntimeSceneOverride(override) || {};
+    const currentOverride = cloneRuntimeValue(normalizedSceneOverride);
+    currentOverride.midiLearnBindings = normalizedBindings;
+    runtimeControlPresetSceneOverrides[sceneName] = currentOverride;
+    applyRuntimeControlPresetForScene(sceneName, { force: true });
+    return;
   }
 
-  runtimeControlPresetApplied = applied;
+  runtimeControlPresetMidiBase = normalizedBindings;
+}
+
+function syncRuntimeControlPresetBaseWithRuntime(nextVisualSettings = visualSettings) {
+  if (!runtimeControlPresetApplied) {
+    return;
+  }
+
+  runtimeControlPresetVisualBase = cloneRuntimeValue(nextVisualSettings);
+}
+
+function hasVisualSettingsChanges(currentValue, nextValue) {
+  return (
+    currentValue.visualGain !== nextValue.visualGain ||
+    currentValue.bassBoost !== nextValue.bassBoost ||
+    currentValue.smoothing !== nextValue.smoothing ||
+    currentValue.beatHoldMs !== nextValue.beatHoldMs ||
+    currentValue.wobbleAmount !== nextValue.wobbleAmount
+  );
+}
+
+function hasMidiLearnBindingChanges(currentBindings, nextBindings) {
+  if (!nextBindings) {
+    return false;
+  }
+  const currentKeys = Object.keys(currentBindings || {});
+  const nextKeys = Object.keys(nextBindings);
+  if (currentKeys.length !== nextKeys.length) {
+    return true;
+  }
+  for (const signature of nextKeys) {
+    if (!Object.prototype.hasOwnProperty.call(currentBindings, signature)) {
+      return true;
+    }
+    if (JSON.stringify(currentBindings[signature]) !== JSON.stringify(nextBindings[signature])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function normalizeSceneName(sceneName) {
+  return String(sceneName || "").trim() || "unknown";
+}
+
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+function cloneRuntimeValue(value) {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+
+  return JSON.parse(JSON.stringify(value));
 }
 
 function updateAvailableScenes(sceneValues) {
@@ -369,6 +628,35 @@ function updateKeyboardMappings(mappings) {
   renderSceneButtons();
 }
 
+function updateSceneControls(scene, { forceReset = false } = {}) {
+  const sceneLayers = scene?.layers;
+  const hasLayers = Array.isArray(sceneLayers);
+  const nextSceneName = String(scene?.name || currentSceneName);
+
+  if (currentSceneName !== nextSceneName) {
+    currentSceneName = nextSceneName;
+    sceneStatusElement.textContent = `Scene: ${currentSceneName}`;
+    renderSceneButtons();
+    forceReset = true;
+  }
+
+  if (!scene) {
+    return;
+  }
+
+  if (forceReset) {
+    shaderParamControlsSignature = "";
+    shapeEditorControlsSignature = "";
+    customShapeParamControlsSignature = "";
+    mappingTargetSelectorSignature = "";
+  }
+
+  updateShaderParamControls(hasLayers ? sceneLayers : null);
+  updateShapeEditorControls(hasLayers ? sceneLayers : null);
+  updateCustomShapeParamControls(hasLayers ? sceneLayers : null);
+  updateMappingTargetSelector(hasLayers ? sceneLayers : null);
+}
+
 function normalizeSceneNames(sceneValues) {
   const seen = new Set();
   const names = [];
@@ -494,7 +782,240 @@ function formatShaderParamValue(value) {
   return Math.abs(numeric) >= 10 ? numeric.toFixed(1) : numeric.toFixed(2);
 }
 
-function requestSceneSwitch(sceneName) {
+function updateShapeEditorControls(layers) {
+  const entries = shapeEditorEntries(layers, shapeEditorOverrides);
+  const signature = shapeEditorControlsSignatureFor(entries);
+  if (signature === shapeEditorControlsSignature) {
+    return;
+  }
+
+  shapeEditorControlsSignature = signature;
+  shapeEditorOverrides = pruneShapeEditorOverrides(shapeEditorOverrides, entries);
+  engine.setShapeEditorOverrides(shapeEditorOverrides);
+  renderShapeEditorControls(entries);
+}
+
+function shapeEditorControlsSignatureFor(entries) {
+  return entries.map((entry) => (
+    `${entry.key}:${entry.kind}:${JSON.stringify(entry.values)}`
+  )).join("|");
+}
+
+function renderShapeEditorControls(entries) {
+  if (!shapeEditorControlsElement) {
+    return;
+  }
+
+  if (!entries.length) {
+    shapeEditorControlsElement.hidden = true;
+    shapeEditorControlsElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Shape Editor";
+  const controls = entries.map((entry) => createShapeEditorControl(entry));
+  shapeEditorControlsElement.replaceChildren(title, ...controls);
+  shapeEditorControlsElement.hidden = false;
+}
+
+function createShapeEditorControl(entry) {
+  const section = document.createElement("details");
+  const summary = document.createElement("summary");
+  summary.textContent = entry.label;
+  section.append(summary);
+  section.append(
+    createShapeKindControl(entry),
+    createShapeNumberControl(entry, "translateX", "Move X", -640, 640, 1),
+    createShapeNumberControl(entry, "translateY", "Move Y", -360, 360, 1),
+    createShapeNumberControl(entry, "rotate", "Rotate", -180, 180, 1),
+    createShapeNumberControl(entry, "scaleX", "Scale X", -4, 4, 0.05),
+    createShapeNumberControl(entry, "scaleY", "Scale Y", -4, 4, 0.05),
+    createShapeNumberControl(entry, "opacity", "Opacity", 0, 1, 0.05),
+    createShapeColorControl(entry, "fill", "Fill"),
+    createShapeColorControl(entry, "strokeColor", "Stroke"),
+    createShapeNumberControl(entry, "strokeWidth", "Stroke W", 0, 24, 0.5)
+  );
+  return section;
+}
+
+function createShapeKindControl(entry) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const select = document.createElement("select");
+  name.textContent = "Kind";
+  ["circle", "line", "rect", "polygon", "polyline", "path", "star"].forEach((kind) => {
+    const option = document.createElement("option");
+    option.value = kind;
+    option.textContent = kind;
+    select.append(option);
+  });
+  select.value = entry.kind;
+  select.addEventListener("change", () => {
+    writeShapeEditorOverride(entry, { ...entry.values, kind: select.value });
+  });
+  label.append(name, select);
+  return label;
+}
+
+function createShapeNumberControl(entry, key, labelText, min, max, step) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = labelText;
+  input.type = "range";
+  input.min = String(min);
+  input.max = String(max);
+  input.step = String(step);
+  input.value = String(entry.values[key]);
+  value.value = formatShaderParamValue(entry.values[key]);
+  input.addEventListener("input", () => {
+    const numeric = Number(input.value);
+    writeShapeEditorOverride(entry, { ...entry.values, [key]: numeric });
+    value.value = formatShaderParamValue(numeric);
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function createShapeColorControl(entry, key, labelText) {
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const input = document.createElement("input");
+  const value = document.createElement("output");
+  name.textContent = labelText;
+  input.type = "color";
+  input.value = entry.values[key];
+  value.value = entry.values[key];
+  input.addEventListener("input", () => {
+    writeShapeEditorOverride(entry, { ...entry.values, [key]: input.value, [`${key}Enabled`]: true });
+    value.value = input.value;
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function writeShapeEditorOverride(entry, values) {
+  shapeEditorOverrides[entry.layerKey] ||= {};
+  shapeEditorOverrides[entry.layerKey][entry.shapeIndex] = normalizeShapeEditorPatch(values);
+  engine.setShapeEditorOverrides(shapeEditorOverrides);
+}
+
+function updateCustomShapeParamControls(layers) {
+  const entries = customShapeParamControlEntries(layers, customShapeParamOverrides);
+  const signature = customShapeParamControlsSignatureFor(entries);
+  if (signature === customShapeParamControlsSignature) {
+    return;
+  }
+
+  customShapeParamControlsSignature = signature;
+  customShapeParamOverrides = pruneCustomShapeParamOverrides(customShapeParamOverrides, entries);
+  renderCustomShapeParamControls(entries);
+}
+
+function customShapeParamControlsSignatureFor(entries) {
+  return entries.map((entry) => (
+    `${entry.key}:${entry.min}:${entry.max}:${entry.step}:${entry.value}`
+  )).join("|");
+}
+
+function renderCustomShapeParamControls(entries) {
+  if (!customShapeParamControlsElement) {
+    return;
+  }
+
+  if (!entries.length) {
+    customShapeParamControlsElement.hidden = true;
+    customShapeParamControlsElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Custom Shape Params";
+  const controls = entries.map((entry) => createCustomShapeParamControl(entry));
+  customShapeParamControlsElement.replaceChildren(title, ...controls);
+  customShapeParamControlsElement.hidden = false;
+}
+
+function createCustomShapeParamControl(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);
+    customShapeParamOverrides[entry.layerKey] ||= {};
+    customShapeParamOverrides[entry.layerKey][entry.customShapeIndex] ||= {};
+    customShapeParamOverrides[entry.layerKey][entry.customShapeIndex][entry.paramName] = numeric;
+    client.send("custom_shape_param", customShapeParamMessage(entry, numeric));
+    value.value = formatShaderParamValue(numeric);
+  });
+  label.append(name, input, value);
+  return label;
+}
+
+function updateMappingTargetSelector(layers) {
+  const options = mappingTargetOptions(layers);
+  const signature = mappingTargetSignature(options);
+  if (signature === mappingTargetSelectorSignature) {
+    return;
+  }
+
+  mappingTargetSelectorSignature = signature;
+  renderMappingTargetSelector(options);
+}
+
+function renderMappingTargetSelector(options) {
+  if (!mappingTargetSelectorElement) {
+    return;
+  }
+
+  if (!options.length) {
+    selectedMappingTarget = "";
+    mappingTargetSelectorElement.hidden = true;
+    mappingTargetSelectorElement.replaceChildren();
+    return;
+  }
+
+  const title = document.createElement("p");
+  title.className = "shader-param-controls__title";
+  title.textContent = "Mapping Targets";
+  const label = document.createElement("label");
+  const name = document.createElement("span");
+  const select = document.createElement("select");
+  const output = document.createElement("output");
+  name.textContent = "Target";
+  options.forEach((option) => {
+    const item = document.createElement("option");
+    item.value = option.target;
+    item.textContent = option.label;
+    select.append(item);
+  });
+  if (!options.some((option) => option.target === selectedMappingTarget)) {
+    selectedMappingTarget = options[0].target;
+  }
+  select.value = selectedMappingTarget;
+  output.value = selectedMappingTarget;
+  select.addEventListener("change", () => {
+    selectedMappingTarget = select.value;
+    output.value = select.value;
+  });
+  label.append(name, select, output);
+  mappingTargetSelectorElement.replaceChildren(title, label);
+  mappingTargetSelectorElement.hidden = false;
+}
+
+function requestSceneSwitch(sceneName, effect = null) {
   if (!sceneName || sceneName === currentSceneName) {
     return;
   }
@@ -504,17 +1025,29 @@ function requestSceneSwitch(sceneName) {
   currentSceneName = sceneName;
   sceneStatusElement.textContent = `Scene: ${sceneName}`;
   renderSceneButtons();
-  client.send("switch_scene", { scene: sceneName });
+  const payload = { scene: sceneName };
+  const normalizedEffect = normalizeTransitionEffect(effect);
+  if (normalizedEffect) {
+    payload.effect = normalizedEffect;
+  }
+  client.send("switch_scene", payload);
 }
 
 function applyKeyboardAction(action) {
   if (action?.type === "switch_scene") {
-    requestSceneSwitch(action.scene);
+    requestSceneSwitch(action.scene, action.effect);
     return;
   }
 
   if (action?.type === "live_control") {
-    applyLiveControls(toggleLiveControl(liveControls, action.control));
+    if (Object.prototype.hasOwnProperty.call(action, "value")) {
+      applyLiveControls({
+        [action?.control]: normalizeLiveControlPayload(action),
+      });
+      return;
+    }
+
+    applyLiveControls(toggleLiveControl(liveControls, action?.control));
   }
 }
 
@@ -546,6 +1079,20 @@ function sendLatencyProbe() {
   });
 }
 
+function normalizeTransitionEffect(effect) {
+  if (!effect) {
+    return null;
+  }
+  if (typeof effect === "string" || typeof effect === "number" || typeof effect === "symbol") {
+    return String(effect);
+  }
+  if (typeof effect !== "object" || Array.isArray(effect)) {
+    return null;
+  }
+
+  return effect;
+}
+
 function updatePerformanceMonitor(nextState) {
   Object.assign(performanceMonitor, nextState);
   renderPerformanceMonitor();
@@ -565,6 +1112,15 @@ function bindShaderCompileMetrics() {
   });
 }
 
+function bindRendererMetrics() {
+  window.addEventListener(RENDERER_CAPABILITIES_EVENT, (event) => {
+    updatePerformanceMonitor(recordRendererCapabilities(performanceMonitor, event.detail));
+  });
+  window.addEventListener(RENDERER_SAFE_MODE_EVENT, (event) => {
+    updatePerformanceMonitor(recordRendererSafeMode(performanceMonitor, event.detail));
+  });
+}
+
 function bindLiveControls() {
   bindLiveControlButton(blackoutButton, "blackout");
   bindLiveControlButton(freezeButton, "freeze");
@@ -579,7 +1135,7 @@ function bindLiveControls() {
     const action = shortcutActionForKey(event);
     if (action) {
       event.preventDefault();
-      applyLiveControls(toggleLiveControl(liveControls, action));
+      applyKeyboardAction({ type: "live_control", control: action });
       return;
     }
 
@@ -613,16 +1169,54 @@ function bindLiveControlButton(button, control) {
 }
 
 function applyLiveControls(nextState) {
-  Object.assign(liveControls, nextState);
+  if (!nextState || typeof nextState !== "object") {
+    return;
+  }
+
+  const nextBlackout = mergeLiveControlState(
+    liveControls.blackout,
+    nextState.blackout
+  );
+  const nextFreeze = mergeLiveControlState(
+    liveControls.freeze,
+    nextState.freeze
+  );
+  Object.assign(liveControls, {
+    blackout: nextBlackout,
+    freeze: nextFreeze,
+  });
   engine.setLiveControls(liveControls);
   renderLiveControlStatus();
 }
 
+function mergeLiveControlState(currentState, nextState) {
+  const current = normalizeLiveControlPayload(currentState);
+  if (nextState === undefined) {
+    return current;
+  }
+  if (!nextState || typeof nextState !== "object" || Array.isArray(nextState)) {
+    return normalizeLiveControlPayload(nextState);
+  }
+
+  const normalized = normalizeLiveControlPayload(nextState);
+  const nextHasFade = Object.prototype.hasOwnProperty.call(nextState, "fade");
+  const nextHasRelease = Object.prototype.hasOwnProperty.call(nextState, "release");
+  const nextHasColor = Object.prototype.hasOwnProperty.call(nextState, "color");
+
+  return {
+    ...current,
+    ...normalized,
+    ...(nextHasFade ? { fade: normalized.fade } : {}),
+    ...(nextHasRelease ? { release: normalized.release } : {}),
+    ...(nextHasColor ? { color: normalized.color } : {}),
+  };
+}
+
 function normalizeLiveControls(value) {
   const input = value && typeof value === "object" ? value : {};
   return {
-    blackout: !!input.blackout,
-    freeze: !!input.freeze,
+    blackout: normalizeLiveControlPayload(input.blackout),
+    freeze: normalizeLiveControlPayload(input.freeze),
   };
 }
 
@@ -632,13 +1226,15 @@ function renderLiveControlStatus() {
   }
 
   if (blackoutButton) {
-    blackoutButton.classList.toggle("is-active", liveControls.blackout);
-    blackoutButton.setAttribute("aria-pressed", String(liveControls.blackout));
+    const isActive = isLiveControlEnabled(liveControls.blackout);
+    blackoutButton.classList.toggle("is-active", isActive);
+    blackoutButton.setAttribute("aria-pressed", String(isActive));
   }
 
   if (freezeButton) {
-    freezeButton.classList.toggle("is-active", liveControls.freeze);
-    freezeButton.setAttribute("aria-pressed", String(liveControls.freeze));
+    const isActive = isLiveControlEnabled(liveControls.freeze);
+    freezeButton.classList.toggle("is-active", isActive);
+    freezeButton.setAttribute("aria-pressed", String(isActive));
   }
 }
 
@@ -747,6 +1343,7 @@ function bindVisualControl(control, key, parser = Number) {
     visualSettings[key] = parser(control.value);
     engine.setVisualSettings(visualSettings);
     renderReactivityStatus();
+    syncRuntimeControlPresetSceneVisualSetting(key, visualSettings[key]);
   });
 }
 
@@ -754,6 +1351,7 @@ function bindVisualPresetControls() {
   if (reactivitySaveButton) {
     reactivitySaveButton.addEventListener("click", () => {
       Object.assign(visualSettings, saveVisualSettingsPreset(browserStorage(), visualSettings));
+      syncRuntimeControlPresetBaseWithRuntime(visualSettings);
       renderReactivityStatus("Saved");
     });
   }
@@ -763,6 +1361,7 @@ function bindVisualPresetControls() {
       Object.assign(visualSettings, loadVisualSettingsPreset(browserStorage(), { fallback: visualSettings }));
       syncVisualControls();
       engine.setVisualSettings(visualSettings);
+      syncRuntimeControlPresetBaseWithRuntime(visualSettings);
       renderReactivityStatus("Loaded");
     });
   }
@@ -807,6 +1406,7 @@ function bindVisualPresetControls() {
       Object.assign(visualSettings, saveVisualSettingsPreset(browserStorage(), visualSettings));
       syncVisualControls();
       engine.setVisualSettings(visualSettings);
+      syncRuntimeControlPresetBaseWithRuntime(visualSettings);
       renderReactivityStatus("Imported");
     });
   }
@@ -820,6 +1420,7 @@ async function saveProjectControlPreset() {
       body: JSON.stringify({
         visual_settings: visualSettings,
         midi_learn_bindings: midiLearnBindings,
+        scene_overrides: runtimeControlPresetSceneOverrides,
       }),
     });
     return response.ok;
@@ -904,6 +1505,7 @@ function handleMidiMessage(event) {
   if (pendingMidiLearnAction && midiMessageActive(event?.data)) {
     midiLearnBindings = upsertMidiLearnBinding(midiLearnBindings, signature, pendingMidiLearnAction);
     midiLearnBindings = saveMidiLearnBindings(browserStorage(), midiLearnBindings);
+    syncRuntimeControlPresetMidiBindings(midiLearnBindings);
     renderMidiLearnStatus(`Learned ${midiSignatureLabel(signature)} -> ${midiLearnActionLabel(pendingMidiLearnAction)}`);
     pendingMidiLearnAction = null;
     return;
@@ -922,6 +1524,7 @@ function applyMidiLearnAction(action, unitValue, active) {
     visualSettings[action.key] = visualSettingFromUnit(action.key, unitValue, visualSettings[action.key]);
     syncVisualControls();
     engine.setVisualSettings(visualSettings);
+    syncRuntimeControlPresetSceneVisualSetting(action.key, visualSettings[action.key]);
     renderReactivityStatus("MIDI");
     return;
   }
@@ -931,13 +1534,19 @@ function applyMidiLearnAction(action, unitValue, active) {
   }
 
   if (action.type === "switch_scene") {
-    requestSceneSwitch(action.scene);
+    requestSceneSwitch(action.scene, action.effect);
     renderMidiLearnStatus(`MIDI: ${midiLearnActionLabel(action)}`);
     return;
   }
 
   if (action.type === "live_control") {
-    applyLiveControls(toggleLiveControl(liveControls, action.control));
+    if (Object.prototype.hasOwnProperty.call(action, "value")) {
+      applyLiveControls({
+        [action.control]: normalizeLiveControlPayload(action),
+      });
+    } else {
+      applyLiveControls(toggleLiveControl(liveControls, action.control));
+    }
     renderMidiLearnStatus(`MIDI: ${midiLearnActionLabel(action)}`);
   }
 }
@@ -1006,6 +1615,7 @@ function renderMidiLearnStatus(prefix = null) {
 function bindShaderErrorOverlay() {
   window.addEventListener(SHADER_ERROR_EVENT, (event) => {
     renderShaderError(event.detail);
+    reportShaderErrorToServer(event.detail);
   });
   if (shaderErrorCloseButton) {
     shaderErrorCloseButton.addEventListener("click", () => {
@@ -1026,6 +1636,31 @@ function renderShaderError(detail) {
   shaderErrorOverlay.hidden = false;
 }
 
+function reportShaderErrorToServer(detail = {}) {
+  const source = String(detail?.source || "shader").trim() || "shader";
+  const layer = String(detail?.name || "layer").trim();
+  const shader = String(detail?.shader || "unknown").trim();
+  const event = String(detail?.event || "shader_failed").trim() || "shader_failed";
+  const phase = String(detail?.phase || "").trim();
+  const message = String(detail?.message || "").trim();
+  const fullMessage = `${layer} (${shader}) ${phase ? `[${phase}] ` : ""}${message}`;
+  client.send("client_runtime_error", {
+    source,
+    event,
+    context: "shader compile failed",
+    message: fullMessage,
+    layer,
+    shader,
+    phase
+  });
+  updateRuntimeErrorStatus({
+    source,
+    event,
+    context: "shader compile failed",
+    message: fullMessage
+  });
+}
+
 function initializeFftPreview(container) {
   if (!container) {
     return [];
@@ -1065,6 +1700,26 @@ function renderAudioInspector(audio) {
   }
 }
 
+function updateRuntimeErrorStatus(payload = {}) {
+  if (!runtimeErrorStatusElement) {
+    return;
+  }
+
+  const source = String(payload?.source || "runtime").trim();
+  const event = String(payload?.event || "").trim();
+  const context = String(payload?.context || "runtime error").trim();
+  const message = String(payload?.message || "").trim();
+  const frameId = payload?.frame_id;
+
+  const detail = [context, event].filter(Boolean).join(" / ");
+  const frameText = Number.isFinite(frameId) ? ` (frame ${frameId})` : "";
+  const text = message
+    ? `Runtime (${source}): ${detail}${frameText} | ${message}`
+    : `Runtime (${source}): ${detail}${frameText}`;
+
+  runtimeErrorStatusElement.textContent = text;
+}
+
 function setMeter(fill, valueElement, value, digits) {
   if (fill) {
     fill.style.setProperty("--meter-value", value.toFixed(4));
@@ -1076,5 +1731,8 @@ function setMeter(fill, valueElement, value, digits) {
 
 function buildWebSocketUrl() {
   const protocol = window.location.protocol === "https:" ? "wss" : "ws";
-  return `${protocol}://${window.location.host}/ws`;
+  const mode = new URLSearchParams(window.location.search || "").get("mode");
+  const normalizedMode = String(mode || "").toLowerCase();
+  const role = projectorMode || normalizedMode === "projector" ? "projector" : normalizedMode === "monitor" ? "monitor" : "control";
+  return `${protocol}://${window.location.host}/ws?role=${encodeURIComponent(role)}`;
 }