@vsreact/core 0.0.14 → 0.0.16

package/README.md

@@ -0,0 +1,98 @@
+# @vsreact/core
+
+**Write React. Ship native VST.**
+
+VSReacT is a React renderer for JUCE audio plugins — your UI runs in
+QuickJS inside the plugin, lays out with Yoga, and paints with
+`juce::Graphics`. No webview, no browser, no Electron. Real threads,
+real automation gestures, hot reload in your DAW.
+
+```tsx
+import { render, View, Text, ParamKnob } from "@vsreact/core";
+
+function App() {
+  return (
+    <View className="w-full h-full items-center justify-center gap-5">
+      <Text className="text-text text-[15] font-bold tracking-widest">MY PLUGIN</Text>
+      <View className="flex-row gap-10">
+        <ParamKnob paramId="gain" size={88} />
+        <ParamKnob paramId="pan" size={88} bipolar />
+      </View>
+    </View>
+  );
+}
+
+render(<App />);
+```
+
+That's a working plugin UI: knobs bound to APVTS parameters, drag /
+wheel / double-click-reset, automation-safe begin/set/end gestures.
+
+## Install
+
+```sh
+bun add @vsreact/core     # or npm / yarn / pnpm
+```
+
+The native side is a JUCE module fetched with CMake — see the
+[installation guide](https://vsreact.n9records.com/docs/installation).
+
+## What's in the box
+
+**Parameter controls** — `Knob`, `Slider`, `Toggle`, `XYPad`,
+`Segmented`, `Select`, `NumberBox`, `Checkbox`, `RadioGroup`,
+`HardwareKnob`, `MacroPad`, `Crossfader` — each with a `Param*` twin
+that binds to a host parameter in one line, and `GenericEditor`, the
+one-line editor for your whole parameter list.
+
+**Synth & performance** — `PianoKeyboard` (glissando, held notes),
+`StepSequencer`, `ADSREnvelope` (four-corner editor), `PitchBend`,
+`ModWheel`, `EQCurve` (real RBJ biquad response with draggable band
+nodes).
+
+**Meters & visualizers** — `Meter` (peak-hold, hot zone, reverse for
+gain reduction), `RingMeter`, `Bars`, `Waveform`, `PulseOrb`.
+
+**Structure & feedback** — `Tabs`, `Disclosure`, `Button`, `Tooltip`,
+`Modal`, `ProgressBar` (determinate + indeterminate), `Spinner`.
+
+**Hooks** — `useParameter`, `useParameterList`, `useNativeEvent`,
+`useNativeValue`, `useSpring`, `useTween`, `usePeakHold`,
+`useRollingBuffer`, `useDebounced`, `useThrottled`, `useInterval`,
+`useHover`, `useToggle`, `usePrevious`, `useLayoutRect`, `useOverlay`.
+
+**Utilities** — a Tailwind-subset `className` engine with theme
+tokens, `cx`, value formatters (`formatDb`, `formatHz`, `formatMs`,
+`formatPercent`, `formatSemitones`, `midiNoteName`, `midiNoteToHz`),
+and the pure math behind the components (`adsrLevelAt`,
+`biquadMagnitudeDb`, `eqResponseDb`, `snapToStep`, `mapRange`).
+
+## How it works
+
+```
+React (QuickJS) ──mutations──▶ C++ shadow tree ──Yoga──▶ juce::Graphics
+      ▲                                                        │
+      └────────────── events, parameters, native calls ────────┘
+```
+
+Your bundle runs in QuickJS with a custom react-reconciler that
+streams JSON mutations to a C++ shadow tree. Yoga computes layout,
+JUCE paints, and input events flow back. Parameters ride
+`vsreact::ParameterBridge`; anything else rides `native.call()` /
+`useNativeEvent`.
+
+- **Hot reload**: point the native side at your bundle file and it
+  reloads on save — inside the DAW.
+- **Automation-safe**: every control opens proper begin/set/end
+  gestures.
+- **No webview**: the UI is painted by the same process and toolkit as
+  the rest of your plugin.
+
+## Docs
+
+- Site & component gallery: <https://vsreact.n9records.com/components>
+- Quick start: <https://vsreact.n9records.com/docs/quick-start>
+- Full docs: <https://vsreact.n9records.com/docs>
+- Analytics add-on: [`@vsreact/posthog`](https://www.npmjs.com/package/@vsreact/posthog)
+
+MIT © N9 Records Technologies

package/dist/components.d.ts

@@ -1,7 +1,9 @@
 export { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, ParamSelect, dragToValue, } from "./controls";
 export type { KnobProps, SliderProps, ToggleProps, XYPadProps, SegmentedProps, SelectProps, GenericEditorProps, ParamKnobProps, ParamSliderProps, ParamToggleProps, ParamXYPadProps, ParamSegmentedProps, ParamSelectProps, } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
-export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, RingMeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { EQCurve } from "./eq";
+export type { EQCurveProps, EQBand, FilterType } from "./eq";
 export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
 export type { BarsProps, WaveformProps } from "./visualizers";
 export { Button } from "./button";

package/dist/components.js

@@ -6,7 +6,8 @@
 // and as the boundary line if the component kit ever becomes its own
 // package.
 export { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, ParamSelect, dragToValue, } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export { EQCurve } from "./eq";
 export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
 export { Button } from "./button";
 export { Tooltip, Modal } from "./popover";

package/dist/controls.d.ts

@@ -85,6 +85,9 @@ export declare function Toggle({ on, label, offLabel, onLabel, size, disabled, t
 export interface ParamToggleProps {
     paramId: string;
     label?: string;
+    /** Hardware-style side captions, forwarded to Toggle. */
+    offLabel?: string;
+    onLabel?: string;
     size?: number;
     trackColor?: string;
     onColor?: string;

package/dist/eq.d.ts

@@ -0,0 +1,40 @@
+export type FilterType = "peak" | "lowshelf" | "highshelf" | "lowpass" | "highpass" | "bandpass" | "notch";
+export interface EQBand {
+    type: FilterType;
+    /** Center/corner frequency in Hz (20..20000). */
+    freq: number;
+    /** Boost/cut in dB (peak & shelves). Default 0. */
+    gainDb?: number;
+    /** Resonance. Default 0.71. */
+    q?: number;
+}
+/** RBJ cookbook biquad magnitude at `atHz`, in dB. */
+export declare function biquadMagnitudeDb(band: EQBand, atHz: number, sampleRate?: number): number;
+/** The summed response of all bands at `atHz`, in dB. */
+export declare function eqResponseDb(bands: EQBand[], atHz: number, sampleRate?: number): number;
+/** 0..1 position ↔ 20..20k Hz on a log scale. */
+export declare const eqXToHz: (x01: number) => number;
+export declare const eqHzToX: (hz: number) => number;
+export interface EQCurveProps {
+    bands: EQBand[];
+    width?: number;
+    height?: number;
+    /** Vertical range: ±dbRange dB. Default 18. */
+    dbRange?: number;
+    /** Fill resolution. Default 48 columns. */
+    columns?: number;
+    disabled?: boolean;
+    trackColor?: string;
+    /** The response fill. */
+    color?: string;
+    handleColor?: string;
+    label?: string;
+    /** A node was dragged (freq/gain) or wheeled (q). */
+    onChange?: (index: number, band: EQBand) => void;
+    onBegin?: (index: number) => void;
+    onEnd?: (index: number) => void;
+}
+/** The EQ display every plugin wants: the real summed biquad response,
+    with one draggable node per band (x = freq on a log scale, y = gain)
+    and the wheel adjusting Q. */
+export declare function EQCurve({ bands, width, height, dbRange, columns, disabled, trackColor, color, handleColor, label, onChange, onBegin, onEnd, }: EQCurveProps): import("react").JSX.Element;

package/dist/eq.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The EQ curve — a real biquad response display with draggable band
+// nodes. Views only: the response is a center-anchored column fill
+// (boost up, cut down), one node per band; drag moves freq/gain, the
+// wheel adjusts Q. RBJ cookbook math, exported pure for reuse.
+import { useRef } from "react";
+import { View, Text } from "./primitives";
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/** RBJ cookbook biquad magnitude at `atHz`, in dB. */
+export function biquadMagnitudeDb(band, atHz, sampleRate = 48000) {
+    const { type, freq } = band;
+    const gainDb = band.gainDb ?? 0;
+    const q = Math.max(0.05, band.q ?? 0.71);
+    const A = Math.pow(10, gainDb / 40);
+    const w0 = (2 * Math.PI * clamp(freq, 1, sampleRate / 2 - 1)) / sampleRate;
+    const cos = Math.cos(w0);
+    const sin = Math.sin(w0);
+    const alpha = sin / (2 * q);
+    const rootA2Alpha = 2 * Math.sqrt(A) * alpha;
+    let b0, b1, b2, a0, a1, a2;
+    switch (type) {
+        case "peak":
+            b0 = 1 + alpha * A;
+            b1 = -2 * cos;
+            b2 = 1 - alpha * A;
+            a0 = 1 + alpha / A;
+            a1 = -2 * cos;
+            a2 = 1 - alpha / A;
+            break;
+        case "lowpass":
+            b0 = (1 - cos) / 2;
+            b1 = 1 - cos;
+            b2 = (1 - cos) / 2;
+            a0 = 1 + alpha;
+            a1 = -2 * cos;
+            a2 = 1 - alpha;
+            break;
+        case "highpass":
+            b0 = (1 + cos) / 2;
+            b1 = -(1 + cos);
+            b2 = (1 + cos) / 2;
+            a0 = 1 + alpha;
+            a1 = -2 * cos;
+            a2 = 1 - alpha;
+            break;
+        case "bandpass":
+            b0 = alpha;
+            b1 = 0;
+            b2 = -alpha;
+            a0 = 1 + alpha;
+            a1 = -2 * cos;
+            a2 = 1 - alpha;
+            break;
+        case "notch":
+            b0 = 1;
+            b1 = -2 * cos;
+            b2 = 1;
+            a0 = 1 + alpha;
+            a1 = -2 * cos;
+            a2 = 1 - alpha;
+            break;
+        case "lowshelf":
+            b0 = A * (A + 1 - (A - 1) * cos + rootA2Alpha);
+            b1 = 2 * A * (A - 1 - (A + 1) * cos);
+            b2 = A * (A + 1 - (A - 1) * cos - rootA2Alpha);
+            a0 = A + 1 + (A - 1) * cos + rootA2Alpha;
+            a1 = -2 * (A - 1 + (A + 1) * cos);
+            a2 = A + 1 + (A - 1) * cos - rootA2Alpha;
+            break;
+        case "highshelf":
+            b0 = A * (A + 1 + (A - 1) * cos + rootA2Alpha);
+            b1 = -2 * A * (A - 1 + (A + 1) * cos);
+            b2 = A * (A + 1 + (A - 1) * cos - rootA2Alpha);
+            a0 = A + 1 - (A - 1) * cos + rootA2Alpha;
+            a1 = 2 * (A - 1 - (A + 1) * cos);
+            a2 = A + 1 - (A - 1) * cos - rootA2Alpha;
+            break;
+    }
+    const w = (2 * Math.PI * clamp(atHz, 1, sampleRate / 2 - 1)) / sampleRate;
+    const cw = Math.cos(w);
+    const c2w = Math.cos(2 * w);
+    const num = b0 * b0 + b1 * b1 + b2 * b2 + 2 * (b0 * b1 + b1 * b2) * cw + 2 * b0 * b2 * c2w;
+    const den = a0 * a0 + a1 * a1 + a2 * a2 + 2 * (a0 * a1 + a1 * a2) * cw + 2 * a0 * a2 * c2w;
+    return 10 * Math.log10(Math.max(1e-12, num / Math.max(1e-12, den)));
+}
+/** The summed response of all bands at `atHz`, in dB. */
+export function eqResponseDb(bands, atHz, sampleRate = 48000) {
+    let db = 0;
+    for (const band of bands)
+        db += biquadMagnitudeDb(band, atHz, sampleRate);
+    return db;
+}
+const FREQ_MIN = 20;
+const FREQ_MAX = 20000;
+const logSpan = Math.log(FREQ_MAX / FREQ_MIN);
+/** 0..1 position ↔ 20..20k Hz on a log scale. */
+export const eqXToHz = (x01) => FREQ_MIN * Math.exp(clamp(x01, 0, 1) * logSpan);
+export const eqHzToX = (hz) => Math.log(clamp(hz, FREQ_MIN, FREQ_MAX) / FREQ_MIN) / logSpan;
+/** The EQ display every plugin wants: the real summed biquad response,
+    with one draggable node per band (x = freq on a log scale, y = gain)
+    and the wheel adjusting Q. */
+export function EQCurve({ bands, width = 220, height = 96, dbRange = 18, columns = 48, disabled, trackColor = "#141714", color = "#C6F13560", handleColor = "#ECF2E8", label, onChange, onBegin, onEnd, }) {
+    const start = useRef({ freq: 1000, gainDb: 0 });
+    const mid = height / 2;
+    const HANDLE = 18;
+    const yOfDb = (db) => mid - (clamp(db, -dbRange, dbRange) / dbRange) * (mid - 4);
+    const node = (band, index) => {
+        const x = eqHzToX(band.freq) * width;
+        const y = yOfDb(band.gainDb ?? 0);
+        const handlers = disabled
+            ? {}
+            : {
+                onDragStart: () => {
+                    start.current = { freq: band.freq, gainDb: band.gainDb ?? 0 };
+                    onBegin?.(index);
+                },
+                onDrag: (e) => {
+                    const x01 = clamp(eqHzToX(start.current.freq) + e.dx / width, 0, 1);
+                    onChange?.(index, {
+                        ...band,
+                        freq: Math.round(eqXToHz(x01)),
+                        gainDb: clamp(start.current.gainDb - (e.dy / (mid - 4)) * dbRange, -dbRange, dbRange),
+                    });
+                },
+                onDragEnd: () => onEnd?.(index),
+                onWheel: (e) => {
+                    const q = Math.max(0.05, band.q ?? 0.71);
+                    onBegin?.(index);
+                    onChange?.(index, { ...band, q: clamp(q * Math.exp(e.dy * 1.4), 0.1, 18) });
+                    onEnd?.(index);
+                },
+            };
+        return (_jsx(View, { className: `absolute items-center justify-center ${disabled ? "" : "cursor-pointer"}`, style: { left: x - HANDLE / 2, top: y - HANDLE / 2, width: HANDLE, height: HANDLE }, ...handlers, children: _jsx(View, { className: "rounded-full border", style: { width: 10, height: 10, backgroundColor: handleColor, borderColor: "#00000088" } }) }, index));
+    };
+    const body = (_jsxs(View, { className: `relative rounded overflow-hidden ${disabled ? "opacity-40" : ""}`, style: { width, height, backgroundColor: trackColor }, children: [_jsx(View, { className: "absolute left-0 right-0 h-[1]", style: { top: mid, backgroundColor: "#FFFFFF24" } }), Array.from({ length: columns }, (_, i) => {
+                const hz = eqXToHz((i + 0.5) / columns);
+                const db = eqResponseDb(bands, hz);
+                const columnHeight = Math.abs(yOfDb(db) - mid);
+                return (_jsx(View, { className: "absolute", style: {
+                        left: (i / columns) * width + 0.5,
+                        width: width / columns - 1,
+                        top: db >= 0 ? mid - columnHeight : mid,
+                        height: Math.max(1, columnHeight),
+                        backgroundColor: color,
+                    } }, i));
+            }), bands.map(node)] }));
+    if (label === undefined)
+        return body;
+    return (_jsxs(View, { className: "items-center gap-2", children: [body, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import "./runtime";
 import "./bridge";
+/** The SDK version — stamp it on support dumps and analytics. */
+export declare const VERSION = "0.0.16";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export type { CommonProps, TextProps, ImageProps, TextInputProps, NativeViewProps, } from "./primitives";
 export { render, unmount } from "./render";
@@ -22,8 +24,10 @@ export { useParameter, useParameterList } from "./parameters";
 export type { ParameterState, ParameterHandle, ParameterInfo } from "./parameters";
 export { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, ParamSelect, dragToValue, } from "./controls";
 export type { KnobProps, SliderProps, ToggleProps, XYPadProps, SegmentedProps, SelectProps, GenericEditorProps, ParamKnobProps, ParamSliderProps, ParamToggleProps, ParamXYPadProps, ParamSegmentedProps, ParamSelectProps, } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
-export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, RingMeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { EQCurve, biquadMagnitudeDb, eqResponseDb, eqXToHz, eqHzToX } from "./eq";
+export type { EQCurveProps, EQBand, FilterType } from "./eq";
 export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRadioGroup, snapToStep, } from "./fields";
 export type { NumberBoxProps, CheckboxProps, RadioGroupProps, ParamNumberBoxProps, ParamCheckboxProps, ParamRadioGroupProps, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";

package/dist/index.js

@@ -2,6 +2,8 @@
 // timer/console/microtask shims react depends on inside QuickJS.
 import "./runtime";
 import "./bridge";
+/** The SDK version — stamp it on support dumps and analytics. */
+export const VERSION = "0.0.16";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
@@ -15,7 +17,8 @@ export { cx } from "./cx";
 export { useTween, useSpring, springStep, lerp, Easing } from "./animation";
 export { useParameter, useParameterList } from "./parameters";
 export { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, ParamSelect, dragToValue, } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export { EQCurve, biquadMagnitudeDb, eqResponseDb, eqXToHz, eqHzToX } from "./eq";
 export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRadioGroup, snapToStep, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";
 export { PianoKeyboard } from "./keyboard";

package/dist/meter.d.ts

@@ -38,3 +38,21 @@ export interface MeterProps {
 }
 /** A natively painted level meter with hot zone + peak hold. */
 export declare function Meter({ value, length, thickness, horizontal, reverse, peak, holdMs, decayPerSecond, hotFrom, trackColor, color, hotColor, label, }: MeterProps): import("react").JSX.Element;
+export interface RingMeterProps {
+    /** Level 0..1. */
+    value: number;
+    /** Diameter. Default 64. */
+    size?: number;
+    thickness?: number;
+    /** Where the arc turns hot, 0..1. Default 0.85; 1 disables. */
+    hotFrom?: number;
+    trackColor?: string;
+    color?: string;
+    hotColor?: string;
+    /** Center readout. Default: none. */
+    format?: (value: number) => string;
+    label?: string;
+}
+/** A circular level meter on the native arc keys — channel-strip level
+    rings, macro amounts, gain-reduction dials. */
+export declare function RingMeter({ value, size, thickness, hotFrom, trackColor, color, hotColor, format, label, }: RingMeterProps): import("react").JSX.Element;

package/dist/meter.js

@@ -54,3 +54,32 @@ export function Meter({ value, length = 120, thickness = 10, horizontal, reverse
         return bar;
     return (_jsxs(View, { className: "items-center gap-2", children: [bar, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
 }
+/** A circular level meter on the native arc keys — channel-strip level
+    rings, macro amounts, gain-reduction dials. */
+export function RingMeter({ value, size = 64, thickness, hotFrom = 0.85, trackColor = "#FFFFFF14", color = "#C6F135", hotColor = "#FF4545", format, label, }) {
+    const level = clamp01(value);
+    const hot = clamp01(hotFrom);
+    const arcThickness = thickness ?? Math.max(3, size * 0.09);
+    const START = -135;
+    const SWEEP = 270;
+    const ring = (_jsxs(View, { className: "relative items-center justify-center", style: { width: size, height: size }, children: [_jsx(View, { className: "absolute inset-0", style: {
+                    arcTrackColor: trackColor,
+                    arcColor: color,
+                    arcStart: START,
+                    arcEnd: START + SWEEP,
+                    arcValueStart: START,
+                    arcValueEnd: START + SWEEP * Math.min(level, hot),
+                    arcThickness,
+                } }), level > hot ? (_jsx(View, { className: "absolute inset-0", style: {
+                    arcTrackColor: "#00000000",
+                    arcColor: hotColor,
+                    arcStart: START,
+                    arcEnd: START + SWEEP,
+                    arcValueStart: START + SWEEP * hot,
+                    arcValueEnd: START + SWEEP * level,
+                    arcThickness,
+                } })) : null, format !== undefined ? (_jsx(Text, { className: "text-[11] font-bold", style: { color: level > hot ? hotColor : color }, children: format(level) })) : null] }));
+    if (label === undefined)
+        return ring;
+    return (_jsxs(View, { className: "items-center gap-2", children: [ring, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsreact/core",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Write React. Ship native VST. A React renderer for JUCE audio plugins — QuickJS + Yoga + juce::Graphics, no webview.",
   "keywords": [
     "react",

package/src/components.ts

@@ -37,8 +37,10 @@ export type {
   ParamSegmentedProps,
   ParamSelectProps,
 } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
-export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, RingMeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { EQCurve } from "./eq";
+export type { EQCurveProps, EQBand, FilterType } from "./eq";
 export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
 export type { BarsProps, WaveformProps } from "./visualizers";
 export { Button } from "./button";

package/src/controls.tsx

@@ -388,6 +388,9 @@ export function Toggle({
 export interface ParamToggleProps {
   paramId: string;
   label?: string;
+  /** Hardware-style side captions, forwarded to Toggle. */
+  offLabel?: string;
+  onLabel?: string;
   size?: number;
   trackColor?: string;
   onColor?: string;

package/src/eq.test.tsx

@@ -0,0 +1,127 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+const batches: unknown[][][] = [];
+
+(globalThis as Record<string, any>).__vsreact_flush = (json: string) => {
+  batches.push(JSON.parse(json));
+};
+(globalThis as Record<string, any>).__vsreact_nativeCall = () => "null";
+
+import {
+  render,
+  unmount,
+  EQCurve,
+  RingMeter,
+  biquadMagnitudeDb,
+  eqResponseDb,
+  eqXToHz,
+  eqHzToX,
+  type EQBand,
+} from "./index";
+
+const allOps = () => batches.flat();
+const opsNamed = (name: string) => allOps().filter((op: any) => op[0] === name);
+const dispatch = (msg: unknown) =>
+  (globalThis as Record<string, any>).__vsreact_dispatch(JSON.stringify(msg));
+
+const nodesWithListener = (type: string): number[] => {
+  const seen = new Set<number>();
+  for (const op of opsNamed("setProps") as any[]) {
+    if (op[2]?.listeners?.includes(type)) seen.add(op[1]);
+  }
+  return [...seen];
+};
+
+beforeEach(() => {
+  unmount();
+  batches.length = 0;
+});
+
+describe("biquad math", () => {
+  test("a peak band boosts by its gain at the center frequency", () => {
+    const band: EQBand = { type: "peak", freq: 1000, gainDb: 6, q: 1 };
+    expect(biquadMagnitudeDb(band, 1000)).toBeCloseTo(6, 1);
+    expect(Math.abs(biquadMagnitudeDb(band, 40))).toBeLessThan(0.5); // far away ≈ flat
+  });
+
+  test("zero gain is flat; a lowpass rolls off the highs", () => {
+    expect(biquadMagnitudeDb({ type: "peak", freq: 1000, gainDb: 0, q: 1 }, 500)).toBeCloseTo(0, 3);
+
+    const lp: EQBand = { type: "lowpass", freq: 1000, q: 0.71 };
+    expect(biquadMagnitudeDb(lp, 100)).toBeCloseTo(0, 1);
+    expect(biquadMagnitudeDb(lp, 10000)).toBeLessThan(-30);
+  });
+
+  test("eqResponseDb sums bands; the log scale maps both ways", () => {
+    const bands: EQBand[] = [
+      { type: "peak", freq: 1000, gainDb: 6, q: 1 },
+      { type: "peak", freq: 1000, gainDb: -2, q: 1 },
+    ];
+    expect(eqResponseDb(bands, 1000)).toBeCloseTo(4, 1);
+
+    expect(eqXToHz(0)).toBeCloseTo(20);
+    expect(eqXToHz(1)).toBeCloseTo(20000);
+    expect(eqHzToX(eqXToHz(0.5))).toBeCloseTo(0.5);
+  });
+});
+
+describe("EQCurve", () => {
+  const bands: EQBand[] = [
+    { type: "lowshelf", freq: 120, gainDb: 3, q: 0.71 },
+    { type: "peak", freq: 1800, gainDb: -4, q: 1.2 },
+  ];
+
+  test("dragging a node reports new freq and gain", () => {
+    const seen: Array<[number, EQBand]> = [];
+    render(
+      <EQCurve bands={bands} width={200} height={100} dbRange={18} onChange={(i, b) => seen.push([i, b])} />,
+    );
+
+    const nodes = nodesWithListener("drag");
+    expect(nodes).toHaveLength(2);
+
+    dispatch({ kind: "event", nodeId: nodes[1], type: "dragstart", payload: { dx: 0, dy: 0 } });
+    dispatch({ kind: "event", nodeId: nodes[1], type: "drag", payload: { dx: 0, dy: -23 } });
+
+    const [index, band] = seen.at(-1)!;
+    expect(index).toBe(1);
+    expect(band.freq).toBe(1800); // no horizontal movement
+    // dy -23 over (mid-4)=46 → +9 dB from -4 → +5
+    expect(band.gainDb).toBeCloseTo(5, 1);
+  });
+
+  test("the wheel adjusts Q inside a begin/end pair", () => {
+    const seen: EQBand[] = [];
+    const gestures: string[] = [];
+    render(
+      <EQCurve
+        bands={bands}
+        onChange={(_i, b) => seen.push(b)}
+        onBegin={() => gestures.push("begin")}
+        onEnd={() => gestures.push("end")}
+      />,
+    );
+
+    const nodes = nodesWithListener("wheel");
+    dispatch({ kind: "event", nodeId: nodes[0], type: "wheel", payload: { dy: 0.1 } });
+
+    expect(seen.at(-1)?.q).toBeCloseTo(0.71 * Math.exp(0.14), 3);
+    expect(gestures).toEqual(["begin", "end"]);
+  });
+});
+
+describe("RingMeter", () => {
+  test("the value arc sweeps to the level; hot overlay appears above hotFrom", () => {
+    render(<RingMeter value={0.95} hotFrom={0.85} />);
+
+    const arcs = (opsNamed("setProps") as any[])
+      .map((op) => op[2]?.style)
+      .filter((s) => s && typeof s.arcValueEnd === "number");
+    expect(arcs.length).toBeGreaterThanOrEqual(2);
+
+    const base = arcs.find((s) => s.arcValueEnd === -135 + 270 * 0.85);
+    const hot = arcs.find((s) => Math.abs(s.arcValueEnd - (-135 + 270 * 0.95)) < 0.001);
+    expect(base).toBeDefined();
+    expect(hot).toBeDefined();
+  });
+});

package/src/eq.tsx

@@ -0,0 +1,231 @@
+// The EQ curve — a real biquad response display with draggable band
+// nodes. Views only: the response is a center-anchored column fill
+// (boost up, cut down), one node per band; drag moves freq/gain, the
+// wheel adjusts Q. RBJ cookbook math, exported pure for reuse.
+
+import { useRef } from "react";
+import { View, Text } from "./primitives";
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+export type FilterType =
+  | "peak"
+  | "lowshelf"
+  | "highshelf"
+  | "lowpass"
+  | "highpass"
+  | "bandpass"
+  | "notch";
+
+export interface EQBand {
+  type: FilterType;
+  /** Center/corner frequency in Hz (20..20000). */
+  freq: number;
+  /** Boost/cut in dB (peak & shelves). Default 0. */
+  gainDb?: number;
+  /** Resonance. Default 0.71. */
+  q?: number;
+}
+
+/** RBJ cookbook biquad magnitude at `atHz`, in dB. */
+export function biquadMagnitudeDb(band: EQBand, atHz: number, sampleRate = 48000): number {
+  const { type, freq } = band;
+  const gainDb = band.gainDb ?? 0;
+  const q = Math.max(0.05, band.q ?? 0.71);
+
+  const A = Math.pow(10, gainDb / 40);
+  const w0 = (2 * Math.PI * clamp(freq, 1, sampleRate / 2 - 1)) / sampleRate;
+  const cos = Math.cos(w0);
+  const sin = Math.sin(w0);
+  const alpha = sin / (2 * q);
+  const rootA2Alpha = 2 * Math.sqrt(A) * alpha;
+
+  let b0: number, b1: number, b2: number, a0: number, a1: number, a2: number;
+  switch (type) {
+    case "peak":
+      b0 = 1 + alpha * A; b1 = -2 * cos; b2 = 1 - alpha * A;
+      a0 = 1 + alpha / A; a1 = -2 * cos; a2 = 1 - alpha / A;
+      break;
+    case "lowpass":
+      b0 = (1 - cos) / 2; b1 = 1 - cos; b2 = (1 - cos) / 2;
+      a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
+      break;
+    case "highpass":
+      b0 = (1 + cos) / 2; b1 = -(1 + cos); b2 = (1 + cos) / 2;
+      a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
+      break;
+    case "bandpass":
+      b0 = alpha; b1 = 0; b2 = -alpha;
+      a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
+      break;
+    case "notch":
+      b0 = 1; b1 = -2 * cos; b2 = 1;
+      a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
+      break;
+    case "lowshelf":
+      b0 = A * (A + 1 - (A - 1) * cos + rootA2Alpha);
+      b1 = 2 * A * (A - 1 - (A + 1) * cos);
+      b2 = A * (A + 1 - (A - 1) * cos - rootA2Alpha);
+      a0 = A + 1 + (A - 1) * cos + rootA2Alpha;
+      a1 = -2 * (A - 1 + (A + 1) * cos);
+      a2 = A + 1 + (A - 1) * cos - rootA2Alpha;
+      break;
+    case "highshelf":
+      b0 = A * (A + 1 + (A - 1) * cos + rootA2Alpha);
+      b1 = -2 * A * (A - 1 + (A + 1) * cos);
+      b2 = A * (A + 1 + (A - 1) * cos - rootA2Alpha);
+      a0 = A + 1 - (A - 1) * cos + rootA2Alpha;
+      a1 = 2 * (A - 1 - (A + 1) * cos);
+      a2 = A + 1 - (A - 1) * cos - rootA2Alpha;
+      break;
+  }
+
+  const w = (2 * Math.PI * clamp(atHz, 1, sampleRate / 2 - 1)) / sampleRate;
+  const cw = Math.cos(w);
+  const c2w = Math.cos(2 * w);
+  const num = b0 * b0 + b1 * b1 + b2 * b2 + 2 * (b0 * b1 + b1 * b2) * cw + 2 * b0 * b2 * c2w;
+  const den = a0 * a0 + a1 * a1 + a2 * a2 + 2 * (a0 * a1 + a1 * a2) * cw + 2 * a0 * a2 * c2w;
+  return 10 * Math.log10(Math.max(1e-12, num / Math.max(1e-12, den)));
+}
+
+/** The summed response of all bands at `atHz`, in dB. */
+export function eqResponseDb(bands: EQBand[], atHz: number, sampleRate = 48000): number {
+  let db = 0;
+  for (const band of bands) db += biquadMagnitudeDb(band, atHz, sampleRate);
+  return db;
+}
+
+const FREQ_MIN = 20;
+const FREQ_MAX = 20000;
+const logSpan = Math.log(FREQ_MAX / FREQ_MIN);
+
+/** 0..1 position ↔ 20..20k Hz on a log scale. */
+export const eqXToHz = (x01: number) => FREQ_MIN * Math.exp(clamp(x01, 0, 1) * logSpan);
+export const eqHzToX = (hz: number) => Math.log(clamp(hz, FREQ_MIN, FREQ_MAX) / FREQ_MIN) / logSpan;
+
+export interface EQCurveProps {
+  bands: EQBand[];
+  width?: number;
+  height?: number;
+  /** Vertical range: ±dbRange dB. Default 18. */
+  dbRange?: number;
+  /** Fill resolution. Default 48 columns. */
+  columns?: number;
+  disabled?: boolean;
+  trackColor?: string;
+  /** The response fill. */
+  color?: string;
+  handleColor?: string;
+  label?: string;
+  /** A node was dragged (freq/gain) or wheeled (q). */
+  onChange?: (index: number, band: EQBand) => void;
+  onBegin?: (index: number) => void;
+  onEnd?: (index: number) => void;
+}
+
+/** The EQ display every plugin wants: the real summed biquad response,
+    with one draggable node per band (x = freq on a log scale, y = gain)
+    and the wheel adjusting Q. */
+export function EQCurve({
+  bands,
+  width = 220,
+  height = 96,
+  dbRange = 18,
+  columns = 48,
+  disabled,
+  trackColor = "#141714",
+  color = "#C6F13560",
+  handleColor = "#ECF2E8",
+  label,
+  onChange,
+  onBegin,
+  onEnd,
+}: EQCurveProps) {
+  const start = useRef<{ freq: number; gainDb: number }>({ freq: 1000, gainDb: 0 });
+  const mid = height / 2;
+  const HANDLE = 18;
+
+  const yOfDb = (db: number) => mid - (clamp(db, -dbRange, dbRange) / dbRange) * (mid - 4);
+
+  const node = (band: EQBand, index: number) => {
+    const x = eqHzToX(band.freq) * width;
+    const y = yOfDb(band.gainDb ?? 0);
+    const handlers = disabled
+      ? {}
+      : {
+          onDragStart: () => {
+            start.current = { freq: band.freq, gainDb: band.gainDb ?? 0 };
+            onBegin?.(index);
+          },
+          onDrag: (e: { dx: number; dy: number }) => {
+            const x01 = clamp(eqHzToX(start.current.freq) + e.dx / width, 0, 1);
+            onChange?.(index, {
+              ...band,
+              freq: Math.round(eqXToHz(x01)),
+              gainDb: clamp(start.current.gainDb - (e.dy / (mid - 4)) * dbRange, -dbRange, dbRange),
+            });
+          },
+          onDragEnd: () => onEnd?.(index),
+          onWheel: (e: { dy: number }) => {
+            const q = Math.max(0.05, band.q ?? 0.71);
+            onBegin?.(index);
+            onChange?.(index, { ...band, q: clamp(q * Math.exp(e.dy * 1.4), 0.1, 18) });
+            onEnd?.(index);
+          },
+        };
+
+    return (
+      <View
+        key={index}
+        className={`absolute items-center justify-center ${disabled ? "" : "cursor-pointer"}`}
+        style={{ left: x - HANDLE / 2, top: y - HANDLE / 2, width: HANDLE, height: HANDLE }}
+        {...handlers}
+      >
+        <View
+          className="rounded-full border"
+          style={{ width: 10, height: 10, backgroundColor: handleColor, borderColor: "#00000088" }}
+        />
+      </View>
+    );
+  };
+
+  const body = (
+    <View
+      className={`relative rounded overflow-hidden ${disabled ? "opacity-40" : ""}`}
+      style={{ width, height, backgroundColor: trackColor }}
+    >
+      <View
+        className="absolute left-0 right-0 h-[1]"
+        style={{ top: mid, backgroundColor: "#FFFFFF24" }}
+      />
+      {Array.from({ length: columns }, (_, i) => {
+        const hz = eqXToHz((i + 0.5) / columns);
+        const db = eqResponseDb(bands, hz);
+        const columnHeight = Math.abs(yOfDb(db) - mid);
+        return (
+          <View
+            key={i}
+            className="absolute"
+            style={{
+              left: (i / columns) * width + 0.5,
+              width: width / columns - 1,
+              top: db >= 0 ? mid - columnHeight : mid,
+              height: Math.max(1, columnHeight),
+              backgroundColor: color,
+            }}
+          />
+        );
+      })}
+      {bands.map(node)}
+    </View>
+  );
+
+  if (label === undefined) return body;
+
+  return (
+    <View className="items-center gap-2">
+      {body}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}

package/src/index.ts

@@ -3,6 +3,9 @@
 import "./runtime";
 import "./bridge";
 
+/** The SDK version — stamp it on support dumps and analytics. */
+export const VERSION = "0.0.16";
+
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export type {
   CommonProps,
@@ -70,8 +73,10 @@ export type {
   ParamSegmentedProps,
   ParamSelectProps,
 } from "./controls";
-export { Meter, usePeakHold, peakHoldStep } from "./meter";
-export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { Meter, RingMeter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, RingMeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export { EQCurve, biquadMagnitudeDb, eqResponseDb, eqXToHz, eqHzToX } from "./eq";
+export type { EQCurveProps, EQBand, FilterType } from "./eq";
 export {
   NumberBox,
   Checkbox,

package/src/meter.tsx

@@ -177,3 +177,84 @@ export function Meter({
     </View>
   );
 }
+
+export interface RingMeterProps {
+  /** Level 0..1. */
+  value: number;
+  /** Diameter. Default 64. */
+  size?: number;
+  thickness?: number;
+  /** Where the arc turns hot, 0..1. Default 0.85; 1 disables. */
+  hotFrom?: number;
+  trackColor?: string;
+  color?: string;
+  hotColor?: string;
+  /** Center readout. Default: none. */
+  format?: (value: number) => string;
+  label?: string;
+}
+
+/** A circular level meter on the native arc keys — channel-strip level
+    rings, macro amounts, gain-reduction dials. */
+export function RingMeter({
+  value,
+  size = 64,
+  thickness,
+  hotFrom = 0.85,
+  trackColor = "#FFFFFF14",
+  color = "#C6F135",
+  hotColor = "#FF4545",
+  format,
+  label,
+}: RingMeterProps) {
+  const level = clamp01(value);
+  const hot = clamp01(hotFrom);
+  const arcThickness = thickness ?? Math.max(3, size * 0.09);
+  const START = -135;
+  const SWEEP = 270;
+
+  const ring = (
+    <View className="relative items-center justify-center" style={{ width: size, height: size }}>
+      <View
+        className="absolute inset-0"
+        style={{
+          arcTrackColor: trackColor,
+          arcColor: color,
+          arcStart: START,
+          arcEnd: START + SWEEP,
+          arcValueStart: START,
+          arcValueEnd: START + SWEEP * Math.min(level, hot),
+          arcThickness,
+        }}
+      />
+      {level > hot ? (
+        <View
+          className="absolute inset-0"
+          style={{
+            arcTrackColor: "#00000000",
+            arcColor: hotColor,
+            arcStart: START,
+            arcEnd: START + SWEEP,
+            arcValueStart: START + SWEEP * hot,
+            arcValueEnd: START + SWEEP * level,
+            arcThickness,
+          }}
+        />
+      ) : null}
+      {format !== undefined ? (
+        <Text className="text-[11] font-bold" style={{ color: level > hot ? hotColor : color }}>
+          {format(level)}
+        </Text>
+      ) : null}
+    </View>
+  );
+
+  if (label === undefined) return ring;
+
+  return (
+    <View className="items-center gap-2">
+      {ring}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}

package/src/perform.test.tsx

@@ -10,6 +10,7 @@ const batches: unknown[][][] = [];
 import {
   render,
   unmount,
+  VERSION,
   PianoKeyboard,
   StepSequencer,
   ProgressBar,
@@ -41,6 +42,12 @@ beforeEach(() => {
   batches.length = 0;
 });
 
+describe("VERSION", () => {
+  test("matches the package version", () => {
+    expect(VERSION).toBe(require("../package.json").version);
+  });
+});
+
 describe("format", () => {
   test("formatDb signs and floors", () => {
     expect(formatDb(6)).toBe("+6.0 dB");