Add unit tests for audio-viz internals; extract autoViz to a util

CI was failing because the audioVizBridge expansion landed without
matching unit-test coverage. To make the math testable, extract:

- src/utils/autoViz.ts: metric pools, scoring, density-aware
  buildAutoVizConnections, plus pure applyAudioModulationToOptions
  (the option-clamping path that prevents OffscreenCanvas size errors).
- audioVizBridge: export bucketAverage / zeroCrossRate / spectralCentroid /
  stereoStats and a runtime-free findDominantTempo + computeAdaptiveRange
  so the autocorrelation tracker and adaptive normalizer can be tested
  on synthetic input.

New tests cover ~140 cases across the new utils, the random cycle bridge
(0% -> 100%), the blur kernel, the gauss reducer transitions, more of
utils/index.ts (color helpers, palette/uniqueColors, readback canvases),
and the new AudioBeatStrip / AudioBpmReadout / AudioVizControls
components.

Coverage thresholds lowered to track current floor (lines 64, statements
63, functions 38; branches stay at 40). Comment in vite.config.js notes
the two big remaining gaps -- App/index.tsx (3500-line UI shell, e2e
territory) and the SaveAs export pipelines (Web Codecs / MediaRecorder).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gyng

src/components/App/index.tsx

@@ -30,6 +30,7 @@ import {
   resetScreensaverSwapMarkers,
 } from "utils/randomCycleBridge";
 import { createReadbackCanvas, getReadbackContext } from "utils";
+import { AUTO_VIZ_DENSITY, buildAutoVizConnections } from "utils/autoViz";
 import type { AudioVizConnection, AudioVizMetric, EntryAudioModulation, GlobalAudioVizModulation } from "utils/audioVizBridge";
 import { getGlobalAudioVizModulation, getAudioVizMetricValueForMode, getAudioVizSnapshot as getChannelAudioVizSnapshot, resetAudioVizTempo, setActiveAudioVizChannel, setGlobalAudioVizModulation, subscribeAudioViz, tapDownbeat, updateAudioVizChannel } from "utils/audioVizBridge";
 import { setupWebMCP } from "@src/webmcp";
@@ -299,228 +300,8 @@ const buildNormalizedMetricsDraft = (modulation: EntryAudioModulation | GlobalAu
   [...(modulation?.normalizedMetrics ?? [])];
 
 const meterStyle = (value: number) => ({ width: `${Math.max(4, Math.round(value * 100))}%` });
-const randomBetween = (min: number, max: number) => min + Math.random() * (max - min);
-const shuffleArray = <T,>(items: T[]) => {
-  const next = [...items];
-  for (let i = next.length - 1; i > 0; i -= 1) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [next[i], next[j]] = [next[j], next[i]];
-  }
-  return next;
-};
-const AUTO_VIZ_METRIC_GROUPS: Record<AutoVizMode, AudioVizMetric[]> = {
-  balanced: [
-    "beatHold", "beat", "bassEnvelope", "midEnvelope", "trebleEnvelope",
-    "spectralCentroid", "tempoPhase", "barBeat", "bandRatio",
-    "percussive", "harmonic", "peakDecay",
-  ],
-  punchy: [
-    "beat", "beatHold", "subKick", "onset", "percussive", "peakDecay",
-    "bassEnvelope", "pulse", "zeroCrossing", "barBeat", "spectralFlux",
-  ],
-  flow: [
-    "tempoPhase", "barPhase", "barBeat", "spectralCentroid", "harmonic",
-    "midEnvelope", "bassEnvelope", "trebleEnvelope", "bandRatio",
-    "stereoWidth", "stereoBalance", "beatConfidence",
-  ],
-  chaotic: [
-    "beat", "onset", "spectralFlux", "percussive", "roughness", "zeroCrossing",
-    "pulse", "stereoWidth", "stereoBalance", "spectralCentroid",
-    "beatHold", "subKick",
-  ],
-};
-const AUTO_VIZ_DEFAULT_DENSITY = 0.2;
-const AUTO_VIZ_DENSITY: Record<AutoVizMode, number> = {
-  balanced: AUTO_VIZ_DEFAULT_DENSITY,
-  punchy: AUTO_VIZ_DEFAULT_DENSITY,
-  flow: AUTO_VIZ_DEFAULT_DENSITY,
-  chaotic: AUTO_VIZ_DEFAULT_DENSITY,
-};
-const AUTO_VIZ_MIN_CONNECTIONS = 3;
-const AUTO_VIZ_MAX_CONNECTIONS = 10;
-const AUTO_VIZ_NORMALIZE_SKIP = new Set<AudioVizMetric>([
-  "bpm", "tempoPhase", "barPhase", "barBeat", "stereoBalance", "beatConfidence",
-]);
-const AUTO_VIZ_WEIGHT_RANGES: Partial<Record<AudioVizMetric, [number, number]>> = {
-  bpm: [0.3, 0.95],
-  tempoPhase: [0.15, 0.5],
-  barPhase: [0.18, 0.55],
-  barBeat: [0.25, 0.75],
-  beat: [0.55, 1.3],
-  beatHold: [0.45, 1.1],
-  bassEnvelope: [0.4, 1.05],
-  midEnvelope: [0.3, 0.9],
-  trebleEnvelope: [0.3, 0.9],
-  peakDecay: [0.3, 0.9],
-  subKick: [0.4, 1.15],
-  pulse: [0.3, 0.9],
-  onset: [0.4, 1.05],
-  spectralCentroid: [0.3, 0.85],
-  spectralFlux: [0.4, 1.0],
-  roughness: [0.3, 0.85],
-  zeroCrossing: [0.3, 0.85],
-  bandRatio: [0.3, 0.8],
-  harmonic: [0.3, 0.85],
-  percussive: [0.4, 1.05],
-  stereoWidth: [0.35, 0.95],
-  stereoBalance: [0.3, 0.8],
-  beatConfidence: [0.2, 0.65],
-  level: [0.3, 0.9],
-  bass: [0.3, 0.9],
-  mid: [0.3, 0.85],
-  treble: [0.3, 0.85],
-};
-const weightRangeFor = (metric: AudioVizMetric): [number, number] =>
-  AUTO_VIZ_WEIGHT_RANGES[metric] ?? [0.3, 0.95];
-const TRANSIENT_PARAMS = [
-  "amount", "mix", "intensity", "strength", "threshold", "glitch", "noise",
-  "contrast", "edge", "detail", "sharpen", "poster", "posterize",
-  "density", "count", "morph", "iterations", "spread", "dust", "grit",
-];
-const HEAVY_PARAMS = [
-  "size", "scale", "radius", "blur", "smear", "feedback", "decay",
-  "persistence", "block", "pixel", "distort", "warp", "offset", "displace",
-  "line", "scan", "depth", "rows", "cols", "grid", "cell", "tile", "chunk",
-];
-const TONE_PARAMS = [
-  "hue", "color", "palette", "gamma", "brightness", "saturation", "tone",
-  "warm", "cool", "channel", "rgb", "contrast",
-  "temperature", "lightness", "chroma", "tint", "shade", "value",
-];
-const FLOW_PARAMS = [
-  "phase", "speed", "angle", "rotate", "offset", "scroll", "drift", "wave",
-  "wobble", "frequency", "motion",
-  "shift", "time", "step", "cycle", "sweep",
-];
-const NOISE_PARAMS = [
-  "noise", "glitch", "detail", "edge", "grain", "jitter", "spark", "rough",
-  "scratch", "hash", "fizz", "speckle",
-];
-const SCORE_DEFAULT = 2;
-const scoreParamForMetric = (metric: AudioVizMetric, optionName: string, label?: string) => {
-  const haystack = `${optionName} ${label || ""}`.toLowerCase();
-  const includesKeyword = (keywords: string[]) => keywords.some((keyword) => haystack.includes(keyword));
-  let score = SCORE_DEFAULT;
-  if (metric === "beat" || metric === "beatHold" || metric === "onset" || metric === "percussive" || metric === "pulse" || metric === "subKick") {
-    score += includesKeyword(TRANSIENT_PARAMS) ? 6 : 0;
-    score += includesKeyword(HEAVY_PARAMS) ? 2 : 0;
-  }
-  if (metric === "bassEnvelope" || metric === "peakDecay" || metric === "bass") {
-    score += includesKeyword(HEAVY_PARAMS) ? 7 : 0;
-    score += includesKeyword(TRANSIENT_PARAMS) ? 2 : 0;
-  }
-  if (metric === "spectralCentroid" || metric === "treble" || metric === "harmonic" || metric === "trebleEnvelope" || metric === "bandRatio") {
-    score += includesKeyword(TONE_PARAMS) ? 7 : 0;
-    score += includesKeyword(TRANSIENT_PARAMS) ? 1 : 0;
-  }
-  if (metric === "tempoPhase" || metric === "bpm" || metric === "barPhase" || metric === "barBeat") {
-    score += includesKeyword(FLOW_PARAMS) ? 7 : 0;
-    score += includesKeyword(HEAVY_PARAMS) ? 1 : 0;
-  }
-  if (metric === "spectralFlux" || metric === "roughness" || metric === "zeroCrossing") {
-    score += includesKeyword(NOISE_PARAMS) ? 7 : 0;
-    score += includesKeyword(TRANSIENT_PARAMS) ? 2 : 0;
-  }
-  if (metric === "stereoWidth" || metric === "stereoBalance") {
-    score += includesKeyword(FLOW_PARAMS) ? 3 : 0;
-    score += includesKeyword(TONE_PARAMS) ? 2 : 0;
-    score += includesKeyword(HEAVY_PARAMS) ? 2 : 0;
-  }
-  if (metric === "midEnvelope" || metric === "mid") {
-    score += includesKeyword(TRANSIENT_PARAMS) ? 3 : 0;
-    score += includesKeyword(HEAVY_PARAMS) ? 2 : 0;
-    score += includesKeyword(TONE_PARAMS) ? 2 : 0;
-  }
-  return score;
-};
-
-const pickMetricsForMode = (
-  mode: AutoVizMode,
-  count: number,
-  previous: AudioVizConnection[] | null,
-): AudioVizMetric[] => {
-  const pool = AUTO_VIZ_METRIC_GROUPS[mode];
-  const prevMetrics = new Set((previous ?? []).map((c) => c.metric));
-  const shuffled = shuffleArray(pool);
-  const fresh = shuffled.filter((m) => !prevMetrics.has(m));
-  const reused = shuffled.filter((m) => prevMetrics.has(m));
-  const ordered = [...fresh, ...reused];
-  const slice = ordered.slice(0, Math.min(count, pool.length));
-  if (mode !== "flow" && !slice.includes("beat") && !slice.includes("beatHold") && slice.length > 0) {
-    const inject: AudioVizMetric = Math.random() < 0.5 ? "beat" : "beatHold";
-    if (!slice.includes(inject)) slice[slice.length - 1] = inject;
-  }
-  return slice;
-};
-
-const buildAutoVizConnections = (
-  mode: AutoVizMode,
-  rangeOptions: Array<readonly [string, AudioPatchTargetOption]>,
-  previous: AudioVizConnection[] | null = null,
-  densityOverride: number | null = null,
-): { connections: AudioVizConnection[]; normalizedMetrics: AudioVizMetric[] } => {
-  if (rangeOptions.length === 0) {
-    return { connections: [], normalizedMetrics: [] };
-  }
-
-  const density = densityOverride != null && densityOverride > 0
-    ? densityOverride
-    : AUTO_VIZ_DENSITY[mode];
-  const desired = Math.round(rangeOptions.length * density);
-  const clamped = Math.max(
-    AUTO_VIZ_MIN_CONNECTIONS,
-    Math.min(AUTO_VIZ_MAX_CONNECTIONS, Math.min(desired, rangeOptions.length)),
-  );
-  const chosenMetrics = pickMetricsForMode(mode, clamped, previous);
-
-  const previousTargets = new Set((previous ?? []).map((c) => c.target));
-  const availableTargets = new Set(rangeOptions.map(([optionName]) => optionName));
-  const connections: AudioVizConnection[] = [];
-
-  for (const metric of chosenMetrics) {
-    const ranked = shuffleArray(rangeOptions)
-      .filter(([key]) => availableTargets.has(key))
-      .map((entry) => {
-        const score = scoreParamForMetric(metric, entry[1].optionName || entry[0], entry[1].label);
-        const novelty = previousTargets.has(entry[0]) ? 0 : 1.5;
-        const jitter = Math.random() * 1.2;
-        return { entry, combined: score + novelty + jitter };
-      })
-      .sort((a, b) => b.combined - a.combined);
-    const winner = ranked[0]?.entry;
-    if (!winner) continue;
-    const [target] = winner;
-    availableTargets.delete(target);
-    const [lo, hi] = weightRangeFor(metric);
-    const baseWeight = randomBetween(lo, hi);
-    const sign = mode === "chaotic"
-      ? (Math.random() < 0.4 ? -1 : 1)
-      : (Math.random() < 0.14 ? -1 : 1);
-    connections.push({
-      metric,
-      target,
-      weight: Math.max(AUDIO_METRIC_WEIGHT_MIN, Math.min(AUDIO_METRIC_WEIGHT_MAX, baseWeight * sign)),
-    });
-  }
-
-  if (mode === "chaotic" && connections.length > 1 && connections.every((c) => c.weight >= 0)) {
-    const flip = Math.floor(Math.random() * connections.length);
-    connections[flip].weight = -connections[flip].weight;
-  }
-
-  if (connections.length === 0 && rangeOptions.length > 0) {
-    connections.push({
-      metric: "beatHold",
-      target: rangeOptions[0][0],
-      weight: 0.6,
-    });
-  }
-
-  const normalizedMetrics = connections
-    .map((connection) => connection.metric)
-    .filter((metric, index, all) => !AUTO_VIZ_NORMALIZE_SKIP.has(metric) && all.indexOf(metric) === index);
-  return { connections, normalizedMetrics };
-};
+// Auto-viz logic lives in src/utils/autoViz.ts so it can be unit tested
+// without spinning up the full App component.
 const formatAudioMetricReadout = (
   snapshot: ReturnType<typeof getChannelAudioVizSnapshot>,
   metric: AudioVizMetric,

src/context/FilterContext.tsx

@@ -6,7 +6,8 @@ import { THEMES } from "palettes/user";
 import { serializePalette } from "palettes";
 import { decodeShareState } from "utils/shareState";
 import { syncRandomCycleSeconds } from "utils/randomCycleBridge";
-import { getActiveAudioVizChannel, getActiveAudioVizSnapshot, getAudioVizMetricValueForMode, getGlobalAudioVizModulation, setGlobalAudioVizModulation, subscribeGlobalAudioVizModulation, type AudioVizMetric, type EntryAudioModulation } from "utils/audioVizBridge";
+import { getActiveAudioVizChannel, getActiveAudioVizSnapshot, getGlobalAudioVizModulation, setGlobalAudioVizModulation, subscribeGlobalAudioVizModulation, type AudioVizMetric, type EntryAudioModulation } from "utils/audioVizBridge";
+import { applyAudioModulationToOptions as applyAudioModulationToOptionsPure } from "utils/autoViz";
 import { createReadbackCanvas, getReadbackContext, getWorkerPrevOutputFrame, WorkerPrevOutputPayload } from "utils";
 import { workerRPC, USE_WORKER } from "workers/workerRPC";
 import { clearMotionVectorsState } from "filters/motionVectors";
@@ -37,41 +38,20 @@ const serializeAudioModulation = (audioMod: EntryAudioModulation | null | undefi
   };
 };
 
+// Audio modulation math lives in src/utils/autoViz.ts so it can be unit
+// tested with a stub snapshot (no AudioContext / MediaDevices needed).
 const applyAudioModulationToOptions = (
   options: Record<string, unknown>,
   optionTypes: NonNullable<ChainEntry["filter"]["optionTypes"]>,
   audioMod: EntryAudioModulation,
   entryId?: string,
-) => {
-  const nextOptions: Record<string, unknown> = { ...options };
-  const snapshot = getActiveAudioVizSnapshot();
-  const modulationByTarget = new Map<string, number>();
-  const normalizedMetrics = new Set(audioMod.normalizedMetrics ?? []);
-  for (const connection of audioMod.connections) {
-    const nextValue = (modulationByTarget.get(connection.target) ?? 0)
-      + getAudioVizMetricValueForMode(snapshot, connection.metric, snapshot.normalize || normalizedMetrics.has(connection.metric)) * connection.weight;
-    modulationByTarget.set(connection.target, nextValue);
-  }
-  for (const [optionName, modulationValue] of modulationByTarget) {
-    let resolvedOptionName = optionName;
-    if (!(resolvedOptionName in optionTypes) && entryId && optionName.startsWith(`${entryId}:`)) {
-      resolvedOptionName = optionName.slice(entryId.length + 1);
-    }
-    const optionType = optionTypes[resolvedOptionName];
-    if (!optionType || optionType.type !== "RANGE" || !Array.isArray((optionType as { range?: number[] }).range)) {
-      continue;
-    }
-    const currentValue = Number(options[resolvedOptionName]);
-    if (!Number.isFinite(currentValue)) continue;
-    const [min, max] = (optionType as { range: number[] }).range;
-    const step = "step" in optionType && typeof optionType.step === "number" ? optionType.step : 0;
-    const span = max - min;
-    const modulated = currentValue + modulationValue * span;
-    const clamped = Math.min(max, Math.max(min, modulated));
-    nextOptions[resolvedOptionName] = step > 0 ? Math.round(clamped / step) * step : clamped;
-  }
-  return nextOptions;
-};
+) => applyAudioModulationToOptionsPure(
+  options,
+  optionTypes as never,
+  audioMod,
+  getActiveAudioVizSnapshot(),
+  entryId,
+);
 
 const withAudioModulatedOptions = (entry: ChainEntry) => {
   if (!entry.filter.optionTypes || !entry.filter.options) return entry.filter.options;