vizcore 0.1.0 → 1.1.0

data/frontend/index.html

@@ -51,6 +51,8 @@
       background: var(--panel-bg);
       backdrop-filter: blur(6px);
       min-width: 18rem;
+      max-height: calc(100vh - 2rem);
+      overflow-y: auto;
     }
 
     .hud h1 {
@@ -122,9 +124,334 @@
       opacity: 0.6;
       cursor: not-allowed;
     }
+
+    .live-controls {
+      margin-top: 0.5rem;
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 0.35rem;
+    }
+
+    .live-controls button {
+      margin-top: 0;
+      padding: 0.42rem 0.5rem;
+      font-weight: 700;
+      text-transform: uppercase;
+    }
+
+    .live-controls button.is-active {
+      border-color: rgba(248, 250, 252, 0.52);
+      color: #fff7ed;
+    }
+
+    #blackout-toggle.is-active {
+      background: rgba(127, 29, 29, 0.78);
+    }
+
+    #freeze-toggle.is-active {
+      background: rgba(133, 77, 14, 0.78);
+    }
+
+    .hud .live-controls__status {
+      grid-column: 1 / -1;
+      margin-top: 0;
+      color: #d9e8ff;
+      font-variant-numeric: tabular-nums;
+    }
+
+    .hud .performance-monitor {
+      margin-top: 0.45rem;
+      padding-top: 0.45rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.16);
+      color: #a8d8ff;
+      font-variant-numeric: tabular-nums;
+      line-height: 1.35;
+    }
+
+    .reactivity-controls {
+      margin-top: 0.55rem;
+      padding-top: 0.55rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.16);
+    }
+
+    .reactivity-actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.45rem;
+      margin-top: 0.45rem;
+    }
+
+    .reactivity-actions button,
+    .midi-learn button {
+      border: 1px solid rgba(148, 163, 184, 0.28);
+      border-radius: 6px;
+      background: rgba(15, 23, 42, 0.68);
+      color: #d9e8ff;
+      cursor: pointer;
+      font: inherit;
+      padding: 0.28rem 0.62rem;
+    }
+
+    .reactivity-actions button:hover,
+    .midi-learn button:hover {
+      border-color: rgba(130, 255, 196, 0.55);
+      color: #d9ffe8;
+    }
+
+    .midi-learn {
+      margin-top: 0.55rem;
+      padding-top: 0.55rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.16);
+    }
+
+    .midi-learn__actions {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 0.35rem;
+      margin-top: 0.4rem;
+    }
+
+    .midi-learn button {
+      margin-top: 0;
+      width: 100%;
+      font-size: 0.76rem;
+    }
+
+    .audio-inspector {
+      margin-top: 0.55rem;
+      padding-top: 0.55rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.16);
+    }
+
+    .audio-inspector__header,
+    .audio-meter {
+      display: grid;
+      grid-template-columns: 3.25rem minmax(7rem, 1fr) 3.25rem;
+      align-items: center;
+      gap: 0.45rem;
+    }
+
+    .audio-inspector__header {
+      margin-bottom: 0.35rem;
+      color: #d9e8ff;
+      font-size: 0.72rem;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    .audio-inspector__header span:last-child {
+      grid-column: 2 / 4;
+      justify-self: end;
+      color: var(--muted);
+      font-weight: 500;
+      letter-spacing: 0;
+      text-transform: none;
+    }
+
+    .audio-meter {
+      margin-top: 0.24rem;
+      color: #aebfda;
+      font-size: 0.72rem;
+      font-variant-numeric: tabular-nums;
+    }
+
+    .meter-track {
+      position: relative;
+      height: 0.34rem;
+      overflow: hidden;
+      border-radius: 999px;
+      background: rgba(148, 163, 184, 0.16);
+    }
+
+    .meter-fill {
+      position: absolute;
+      inset: 0;
+      border-radius: inherit;
+      transform: scaleX(var(--meter-value, 0));
+      transform-origin: left center;
+      transition: transform 90ms linear;
+      background: linear-gradient(90deg, #65ffb0, #38bdf8 58%, #f472b6);
+    }
+
+    .fft-preview {
+      display: grid;
+      grid-template-columns: repeat(16, minmax(0, 1fr));
+      align-items: end;
+      gap: 0.12rem;
+      height: 2.45rem;
+      margin-top: 0.48rem;
+      padding: 0.18rem 0;
+    }
+
+    .fft-bar {
+      height: 100%;
+      min-width: 2px;
+      border-radius: 2px 2px 0 0;
+      transform: scaleY(var(--bin-value, 0));
+      transform-origin: bottom center;
+      transition: transform 90ms linear;
+      background: linear-gradient(180deg, #f8fafc, #38bdf8 45%, #65ffb0);
+      opacity: 0.9;
+    }
+
+    .shader-error {
+      position: absolute;
+      right: 1rem;
+      top: 1rem;
+      width: min(26rem, calc(100vw - 2rem));
+      max-height: calc(100vh - 2rem);
+      overflow: auto;
+      padding: 0.75rem;
+      border: 1px solid rgba(248, 113, 113, 0.45);
+      border-radius: 0.5rem;
+      background: rgba(20, 6, 10, 0.86);
+      box-shadow: 0 18px 48px rgba(0, 0, 0, 0.34);
+      color: #fee2e2;
+      backdrop-filter: blur(8px);
+    }
+
+    .shader-error[hidden] {
+      display: none;
+    }
+
+    .shader-error__header {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      align-items: center;
+      gap: 0.6rem;
+      margin-bottom: 0.45rem;
+    }
+
+    .shader-error h2 {
+      margin: 0;
+      overflow-wrap: anywhere;
+      color: #fecaca;
+      font-size: 0.88rem;
+      letter-spacing: 0;
+    }
+
+    .shader-error button {
+      min-width: 4rem;
+      border: 1px solid rgba(254, 202, 202, 0.4);
+      border-radius: 0.45rem;
+      padding: 0.32rem 0.52rem;
+      background: rgba(127, 29, 29, 0.5);
+      color: #fff1f2;
+      cursor: pointer;
+    }
+
+    .shader-error pre {
+      margin: 0;
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+      color: #fed7aa;
+      font: 0.76rem/1.45 "SFMono-Regular", Consolas, monospace;
+    }
+
+    body.is-projector {
+      background: #000;
+      cursor: none;
+    }
+
+    body.is-projector .hud,
+    body.is-projector .shader-error {
+      display: none;
+    }
+
+    .reactivity-controls label,
+    .shader-param-controls label {
+      display: grid;
+      grid-template-columns: minmax(5.5rem, 0.8fr) minmax(8rem, 1.2fr) minmax(2.8rem, 0.35fr);
+      align-items: center;
+      gap: 0.5rem;
+      margin-top: 0.3rem;
+      font-size: 0.78rem;
+      color: #c9d9ee;
+    }
+
+    .reactivity-controls label {
+      grid-template-columns: minmax(5.5rem, 0.8fr) minmax(8rem, 1.2fr);
+    }
+
+    .reactivity-controls input[type="range"],
+    .shader-param-controls input[type="range"] {
+      width: 100%;
+    }
+
+    .reactivity-controls p,
+    .shader-param-controls p {
+      margin-top: 0.45rem;
+      line-height: 1.35;
+    }
+
+    .shader-param-controls {
+      margin-top: 0.55rem;
+      padding-top: 0.55rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.16);
+    }
+
+    .shader-param-controls[hidden] {
+      display: none;
+    }
+
+    .shader-param-controls__title {
+      color: #d9e8ff;
+      font-size: 0.72rem;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    .shader-param-controls output {
+      color: #a8d8ff;
+      font-variant-numeric: tabular-nums;
+      text-align: right;
+    }
+
+    .shader-param-controls details {
+      margin-top: 0.35rem;
+      padding-top: 0.3rem;
+      border-top: 1px solid rgba(153, 195, 255, 0.12);
+    }
+
+    .shader-param-controls summary {
+      cursor: pointer;
+      color: #d9e8ff;
+      font-size: 0.78rem;
+      font-weight: 700;
+    }
+
+    .shader-param-controls select,
+    .shader-param-controls input[type="color"] {
+      width: 100%;
+      min-height: 1.65rem;
+      border: 1px solid rgba(153, 195, 255, 0.28);
+      border-radius: 0.35rem;
+      background: rgba(2, 6, 14, 0.72);
+      color: var(--fg);
+    }
+
+    @media (max-width: 520px) {
+      .hud {
+        right: 1rem;
+        min-width: 0;
+      }
+
+      .audio-inspector__header,
+      .audio-meter {
+        grid-template-columns: 2.75rem minmax(5rem, 1fr) 2.9rem;
+      }
+
+      .shader-error {
+        left: 1rem;
+        top: auto;
+        bottom: 1rem;
+      }
+    }
   </style>
 </head>
-<body>
+<body data-projector-mode="false" data-display-mode="auto">
   <div id="app">
     <canvas id="vizcore-canvas"></canvas>
     <section class="hud" aria-live="polite">
@@ -135,14 +462,179 @@
       <p id="frame-status">Amplitude: 0.0000</p>
       <p id="bpm-status" class="is-accent">BPM: --</p>
       <p id="beat-status">Beat: off | Count: 0</p>
+      <div class="live-controls" aria-label="Live emergency controls">
+        <button id="blackout-toggle" type="button" aria-pressed="false">Blackout</button>
+        <button id="freeze-toggle" type="button" aria-pressed="false">Freeze</button>
+        <p id="live-control-status" class="live-controls__status">Live: output</p>
+      </div>
+      <p id="performance-monitor" class="performance-monitor">Perf: -- FPS | Frame -- | WS -- | RTT -- | Clock -- | Drop 0 | Audio -- | Shader -- | Reconnect 0</p>
+      <div class="audio-inspector" aria-label="Audio inspector">
+        <div class="audio-inspector__header">
+          <span>Audio</span>
+          <span id="inspector-peak">Peak: --</span>
+        </div>
+        <div class="audio-meter">
+          <span>amp</span>
+          <span class="meter-track"><span id="inspector-amplitude-fill" class="meter-fill"></span></span>
+          <span id="inspector-amplitude-value">0.000</span>
+        </div>
+        <div class="audio-meter">
+          <span>sub</span>
+          <span class="meter-track"><span id="inspector-band-sub-fill" class="meter-fill"></span></span>
+          <span id="inspector-band-sub-value">0.00</span>
+        </div>
+        <div class="audio-meter">
+          <span>low</span>
+          <span class="meter-track"><span id="inspector-band-low-fill" class="meter-fill"></span></span>
+          <span id="inspector-band-low-value">0.00</span>
+        </div>
+        <div class="audio-meter">
+          <span>mid</span>
+          <span class="meter-track"><span id="inspector-band-mid-fill" class="meter-fill"></span></span>
+          <span id="inspector-band-mid-value">0.00</span>
+        </div>
+        <div class="audio-meter">
+          <span>high</span>
+          <span class="meter-track"><span id="inspector-band-high-fill" class="meter-fill"></span></span>
+          <span id="inspector-band-high-value">0.00</span>
+        </div>
+        <div id="fft-preview" class="fft-preview" aria-label="FFT preview"></div>
+      </div>
       <p id="audio-source-status">Audio Source: unknown</p>
       <p id="audio-track-status">Track: none</p>
       <p id="audio-playback-status">Playback: unavailable</p>
+      <div class="reactivity-controls" aria-label="Visual reactivity controls">
+        <label>Visual Gain <input id="visual-gain-control" type="range" min="1" max="8" step="0.1" value="2.5" /></label>
+        <label>Bass Boost <input id="bass-boost-control" type="range" min="0" max="4" step="0.1" value="1.4" /></label>
+        <label>Smoothing <input id="smoothing-control" type="range" min="0" max="0.9" step="0.05" value="0.25" /></label>
+        <label>Beat Hold <input id="beat-hold-control" type="range" min="50" max="400" step="10" value="180" /></label>
+        <label>Wobble <input id="wobble-control" type="range" min="0.25" max="3" step="0.05" value="1" /></label>
+        <div class="reactivity-actions" aria-label="Reactivity preset controls">
+          <button id="reactivity-save" type="button">Save</button>
+          <button id="reactivity-load" type="button">Load</button>
+          <button id="reactivity-project-save" type="button" hidden>Save Project</button>
+          <button id="reactivity-export" type="button">Export</button>
+          <button id="reactivity-import" type="button">Import</button>
+        </div>
+        <p id="reactivity-status">Visual Gain: 2.5x | Bass: 1.4x | Smooth: 0.25 | Beat Hold: 180ms | Wobble: 1.00x</p>
+      </div>
+      <div class="midi-learn" aria-label="MIDI learn controls">
+        <p id="midi-learn-status">MIDI Learn: idle | Bindings: 0</p>
+        <div class="midi-learn__actions">
+          <button type="button" data-midi-learn-action="current-scene">Learn Scene</button>
+          <button type="button" data-midi-learn-action="blackout">Learn Blackout</button>
+          <button type="button" data-midi-learn-action="freeze">Learn Freeze</button>
+          <button type="button" data-midi-learn-action="visual:visualGain">Learn Gain</button>
+          <button type="button" data-midi-learn-action="visual:bassBoost">Learn Bass</button>
+          <button type="button" data-midi-learn-action="visual:wobbleAmount">Learn Wobble</button>
+        </div>
+      </div>
+      <div id="shader-param-controls" class="shader-param-controls" hidden aria-label="Shader parameter controls"></div>
+      <div id="shape-editor-controls" class="shader-param-controls" hidden aria-label="Shape editor controls"></div>
+      <div id="custom-shape-param-controls" class="shader-param-controls" hidden aria-label="Custom shape parameter controls"></div>
+      <div id="mapping-target-selector" class="shader-param-controls" hidden aria-label="Mapping target selector"></div>
       <div id="scene-switcher" class="scene-switcher" hidden aria-label="Scene switcher"></div>
       <button id="audio-toggle" type="button" hidden>Play Audio</button>
     </section>
+    <section id="shader-error-overlay" class="shader-error" aria-live="assertive" hidden>
+      <div class="shader-error__header">
+        <h2 id="shader-error-title">Shader Error</h2>
+        <button id="shader-error-close" type="button">Close</button>
+      </div>
+      <pre id="shader-error-message"></pre>
+    </section>
   </div>
 
-  <script type="module" src="/src/main.js"></script>
+  <script>
+    window.__vizcoreMainStarted = false;
+    (function () {
+      var protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+      var websocketUrl = protocol + "//" + window.location.host + "/ws";
+      var fallbackTimer = window.setTimeout(function () {
+        if (window.__vizcoreMainStarted) return;
+
+        var wsStatus = document.getElementById("ws-status");
+        var sceneStatus = document.getElementById("scene-status");
+        var frameStatus = document.getElementById("frame-status");
+        var bpmStatus = document.getElementById("bpm-status");
+        var beatStatus = document.getElementById("beat-status");
+        var audioSourceStatus = document.getElementById("audio-source-status");
+        var peakStatus = document.getElementById("inspector-peak");
+        var ampValue = document.getElementById("inspector-amplitude-value");
+        var ampFill = document.getElementById("inspector-amplitude-fill");
+        var bands = ["sub", "low", "mid", "high"];
+
+        function setText(element, text) {
+          if (element) element.textContent = text;
+        }
+
+        function setMeter(id, value) {
+          var fill = document.getElementById("inspector-band-" + id + "-fill");
+          var label = document.getElementById("inspector-band-" + id + "-value");
+          if (fill) fill.style.setProperty("--meter-value", value.toFixed(4));
+          if (label) label.textContent = value.toFixed(2);
+        }
+
+        setText(wsStatus, "WebSocket: fallback connecting (" + websocketUrl + ")");
+        window.fetch("/runtime", { cache: "no-store" })
+          .then(function (response) { return response.ok ? response.json() : null; })
+          .then(function (runtime) {
+            if (runtime && audioSourceStatus) {
+              audioSourceStatus.textContent = "Audio Source: " + runtime.audio_source;
+            }
+          })
+          .catch(function () {});
+
+        var socket = new WebSocket(websocketUrl);
+        socket.addEventListener("open", function () {
+          setText(wsStatus, "WebSocket: fallback connected (" + websocketUrl + ")");
+        });
+        socket.addEventListener("error", function () {
+          setText(wsStatus, "WebSocket: fallback error (" + websocketUrl + ")");
+        });
+        socket.addEventListener("close", function () {
+          setText(wsStatus, "WebSocket: fallback closed (" + websocketUrl + ")");
+        });
+        socket.addEventListener("message", function (event) {
+          var message;
+          try {
+            message = JSON.parse(event.data);
+          } catch (_error) {
+            return;
+          }
+          if (!message || message.type !== "audio_frame" || !message.payload) return;
+
+          var payload = message.payload;
+          var audio = payload.audio || {};
+          var scene = payload.scene || {};
+          var amplitude = Math.max(0, Math.min(1, Number(audio.amplitude || 0)));
+          var bpm = Number(audio.bpm || 0);
+          var beat = !!audio.beat;
+          var beatCount = Math.max(0, Number(audio.beat_count || 0) || 0);
+
+          setText(sceneStatus, "Scene: " + (scene.name || "unknown"));
+          setText(frameStatus, "Amplitude: " + amplitude.toFixed(4));
+          setText(bpmStatus, "BPM: " + (bpm > 0 ? bpm.toFixed(1) : "--"));
+          setText(beatStatus, "Beat: " + (beat ? "ON" : "off") + " | Count: " + beatCount);
+          if (ampValue) ampValue.textContent = amplitude.toFixed(3);
+          if (ampFill) ampFill.style.setProperty("--meter-value", amplitude.toFixed(4));
+          if (peakStatus) {
+            var peak = Number(audio.peak_frequency || 0);
+            peakStatus.textContent = peak > 0 ? "Peak: " + Math.round(peak) + " Hz" : "Peak: --";
+          }
+
+          var audioBands = audio.bands || {};
+          bands.forEach(function (key) {
+            setMeter(key, Math.max(0, Math.min(1, Number(audioBands[key] || 0))));
+          });
+        });
+      }, 1200);
+
+      window.addEventListener("beforeunload", function () {
+        window.clearTimeout(fallbackTimer);
+      });
+    })();
+  </script>
+  <script type="module" src="/src/main.js?v=20260516d"></script>
 </body>
 </html>

data/frontend/src/audio-inspector.js

@@ -0,0 +1,40 @@
+export const BAND_KEYS = ["sub", "low", "mid", "high"];
+export const DEFAULT_FFT_BINS = 16;
+
+export const buildAudioInspectorState = (audio, fftBins = DEFAULT_FFT_BINS) => {
+  const bands = BAND_KEYS.reduce((result, key) => {
+    result[key] = clamp01(audio?.bands?.[key]);
+    return result;
+  }, {});
+
+  return {
+    amplitude: clamp01(audio?.amplitude),
+    bands,
+    fft: normalizeFft(audio?.fft, fftBins),
+    bpm: Number(audio?.bpm || 0),
+    beat: !!audio?.beat,
+    beatPulse: clamp01(audio?.beat_pulse),
+    peakFrequency: Math.max(0, Number(audio?.peak_frequency || 0) || 0),
+  };
+};
+
+export const formatMeterValue = (value, digits = 2) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return Number(0).toFixed(digits);
+  }
+  return numeric.toFixed(digits);
+};
+
+const normalizeFft = (value, size) => {
+  const input = Array.isArray(value) || ArrayBuffer.isView(value) ? Array.from(value) : [];
+  return Array.from({ length: size }, (_entry, index) => clamp01(input[index]));
+};
+
+const clamp01 = (value) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return 0;
+  }
+  return Math.min(Math.max(numeric, 0), 1);
+};

data/frontend/src/custom-shape-param-controls.js

@@ -0,0 +1,106 @@
+export const customShapeParamControlEntries = (layers, overrides = {}) => {
+  const entries = [];
+  const layerList = Array.isArray(layers) ? layers : [];
+
+  layerList.forEach((layer, layerIndex) => {
+    const controls = Array.isArray(layer?.params?.custom_shape_controls) ? layer.params.custom_shape_controls : [];
+    if (!controls.length) return;
+
+    const layerKey = layerControlKey(layer, layerIndex);
+    const layerName = String(layer?.name || `layer_${layerIndex + 1}`);
+    controls.forEach((control, controlIndex) => {
+      const customShapeIndex = finiteIndex(control?.index, controlIndex);
+      const customShapeName = String(control?.name || `custom_shape_${customShapeIndex + 1}`);
+      const params = control?.params && typeof control.params === "object" ? control.params : {};
+      const schemaByName = paramSchemaByName(control?.param_schema);
+      const paramNames = [...new Set([...Object.keys(schemaByName), ...Object.keys(params)])].sort();
+
+      paramNames.forEach((paramName) => {
+        const schema = schemaByName[paramName] || {};
+        const baseValue = finiteNumber(params[paramName], finiteNumber(schema.default, 0));
+        const min = finiteNumber(schema.min, Math.min(0, baseValue));
+        const fallbackMax = Math.max(min + 1, Math.abs(baseValue) * 2, 1);
+        const max = Math.max(min, finiteNumber(schema.max, fallbackMax));
+        const step = positiveNumber(schema.step, Math.max((max - min) / 100, 0.01));
+        const value = finiteNumber(overrides?.[layerKey]?.[customShapeIndex]?.[paramName], baseValue);
+
+        entries.push({
+          key: `${layerKey}:custom_shapes.${customShapeIndex}.params.${paramName}`,
+          layerKey,
+          layerName,
+          customShapeIndex,
+          customShapeName,
+          paramName,
+          label: `${layerName}.${customShapeName}.${paramName}`,
+          target: `custom_shapes.${customShapeIndex}.params.${paramName}`,
+          min,
+          max,
+          step,
+          value: clamp(value, min, max),
+        });
+      });
+    });
+  });
+
+  return entries;
+};
+
+export const pruneCustomShapeParamOverrides = (overrides = {}, entries = []) => {
+  const validKeys = new Set(entries.map((entry) => `${entry.layerKey}:${entry.customShapeIndex}:${entry.paramName}`));
+  const next = {};
+
+  Object.entries(overrides || {}).forEach(([layerKey, controls]) => {
+    if (!controls || typeof controls !== "object") return;
+
+    Object.entries(controls).forEach(([customShapeIndex, params]) => {
+      if (!params || typeof params !== "object") return;
+
+      Object.entries(params).forEach(([paramName, value]) => {
+        if (!validKeys.has(`${layerKey}:${customShapeIndex}:${paramName}`) || !Number.isFinite(Number(value))) return;
+
+        next[layerKey] ||= {};
+        next[layerKey][customShapeIndex] ||= {};
+        next[layerKey][customShapeIndex][paramName] = Number(value);
+      });
+    });
+  });
+
+  return next;
+};
+
+export const customShapeParamMessage = (entry, value) => ({
+  layer: entry.layerName,
+  custom_shape_index: entry.customShapeIndex,
+  param: entry.paramName,
+  value: clamp(finiteNumber(value, entry.value), entry.min, entry.max),
+});
+
+const layerControlKey = (layer, index) => `${index}:${String(layer?.name || "layer")}`;
+
+const paramSchemaByName = (schema) => {
+  const output = {};
+  (Array.isArray(schema) ? schema : []).forEach((entry) => {
+    const name = String(entry?.name || "").trim();
+    if (!name) return;
+
+    output[name] = entry;
+  });
+  return output;
+};
+
+const finiteIndex = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isInteger(numeric) && numeric >= 0 ? numeric : fallback;
+};
+
+const finiteNumber = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+
+const positiveNumber = (value, fallback) => {
+  const numeric = finiteNumber(value, fallback);
+  return numeric > 0 ? numeric : fallback;
+};
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);