@vsreact/core 0.0.2 → 0.0.4

package/dist/animation.d.ts

@@ -17,3 +17,22 @@ export interface TweenOptions {
 /** Eased progress 0→1 that starts when the component mounts. */
 export declare function useTween({ duration, delay, easing, onComplete }: TweenOptions): number;
 export declare function lerp(from: number, to: number, t: number): number;
+export interface SpringOptions {
+    /** Spring constant — higher snaps faster. Default 170. */
+    stiffness?: number;
+    /** Velocity drag — higher settles with less bounce. Default 24. */
+    damping?: number;
+    mass?: number;
+    /** Distance from target below which the spring snaps and stops. */
+    restDelta?: number;
+}
+/** One semi-implicit Euler integration step; exported for tests and for
+    driving springs from your own loops. Returns [position, velocity]. */
+export declare function springStep(position: number, velocity: number, target: number, { stiffness, damping, mass }: SpringOptions, dtMs: number): [number, number];
+/**
+ * A value that springs toward `target` whenever it changes — for
+ * interactive motion where a fixed-duration tween feels wrong (toggle
+ * thumbs, drawers, meters chasing levels). Runs on the host timer like
+ * useTween; starts at rest on the initial target.
+ */
+export declare function useSpring(target: number, options?: SpringOptions): number;

package/dist/animation.js

@@ -45,3 +45,46 @@ export function useTween({ duration, delay = 0, easing = Easing.outCubic, onComp
 export function lerp(from, to, t) {
     return from + (to - from) * t;
 }
+/** One semi-implicit Euler integration step; exported for tests and for
+    driving springs from your own loops. Returns [position, velocity]. */
+export function springStep(position, velocity, target, { stiffness = 170, damping = 24, mass = 1 }, dtMs) {
+    const dt = dtMs / 1000;
+    const acceleration = (-stiffness * (position - target) - damping * velocity) / mass;
+    const v = velocity + acceleration * dt;
+    return [position + v * dt, v];
+}
+/**
+ * A value that springs toward `target` whenever it changes — for
+ * interactive motion where a fixed-duration tween feels wrong (toggle
+ * thumbs, drawers, meters chasing levels). Runs on the host timer like
+ * useTween; starts at rest on the initial target.
+ */
+export function useSpring(target, options = {}) {
+    const [value, setValue] = useState(target);
+    const state = useRef({ position: target, velocity: 0 });
+    const targetRef = useRef(target);
+    targetRef.current = target;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    useEffect(() => {
+        const restDelta = optionsRef.current.restDelta ?? 0.001;
+        if (Math.abs(state.current.position - targetRef.current) <= restDelta &&
+            Math.abs(state.current.velocity) <= restDelta) {
+            return;
+        }
+        const id = setInterval(() => {
+            const s = state.current;
+            const [p, v] = springStep(s.position, s.velocity, targetRef.current, optionsRef.current, FRAME_MS);
+            s.position = p;
+            s.velocity = v;
+            if (Math.abs(p - targetRef.current) <= restDelta && Math.abs(v) <= restDelta) {
+                s.position = targetRef.current;
+                s.velocity = 0;
+                clearInterval(id);
+            }
+            setValue(s.position);
+        }, FRAME_MS);
+        return () => clearInterval(id);
+    }, [target]);
+    return value;
+}

package/dist/controls.d.ts

@@ -24,7 +24,12 @@ export interface ParamKnobProps {
 export declare function ParamKnob({ paramId, label, size, trackColor, valueColor }: ParamKnobProps): import("react").JSX.Element;
 export interface SliderProps {
     value: number;
+    /** Track length when horizontal (default 160). */
     width?: number;
+    /** Track length when vertical (default 160). */
+    height?: number;
+    /** Vertical fader — drag up for more, fill rises from the bottom. */
+    vertical?: boolean;
     label?: string;
     disabled?: boolean;
     trackColor?: string;
@@ -33,11 +38,100 @@ export interface SliderProps {
     onBegin?: () => void;
     onEnd?: () => void;
 }
-export declare function Slider({ value, width, label, disabled, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
+export declare function Slider({ value, width, height, vertical, label, disabled, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
 export interface ParamSliderProps {
     paramId: string;
     label?: string;
     width?: number;
+    height?: number;
+    vertical?: boolean;
 }
 /** A Slider bound to an APVTS parameter (via ParameterBridge). */
-export declare function ParamSlider({ paramId, label, width }: ParamSliderProps): import("react").JSX.Element;
+export declare function ParamSlider({ paramId, label, width, height, vertical }: ParamSliderProps): import("react").JSX.Element;
+export interface ToggleProps {
+    on: boolean;
+    label?: string;
+    /** Track height; width is 1.8×. Default 22. */
+    size?: number;
+    disabled?: boolean;
+    trackColor?: string;
+    onColor?: string;
+    thumbColor?: string;
+    onChange: (on: boolean) => void;
+}
+/** A switch with a spring-animated thumb — bypass, on/off, A/B. */
+export declare function Toggle({ on, label, size, disabled, trackColor, onColor, thumbColor, onChange, }: ToggleProps): import("react").JSX.Element;
+export interface ParamToggleProps {
+    paramId: string;
+    label?: string;
+    size?: number;
+    trackColor?: string;
+    onColor?: string;
+    thumbColor?: string;
+}
+/** A Toggle bound to a bool-style APVTS parameter (on = value ≥ 0.5). */
+export declare function ParamToggle({ paramId, label, ...rest }: ParamToggleProps): import("react").JSX.Element;
+export interface XYPadProps {
+    /** Normalized 0..1. */
+    x: number;
+    /** Normalized 0..1 — 1 is the TOP of the pad (drag up for more). */
+    y: number;
+    width?: number;
+    height?: number;
+    label?: string;
+    disabled?: boolean;
+    trackColor?: string;
+    valueColor?: string;
+    onChange: (x: number, y: number) => void;
+    onBegin?: () => void;
+    onEnd?: () => void;
+}
+/** A 2D drag pad with crosshair — filter cutoff/resonance, pan/depth… */
+export declare function XYPad({ x, y, width, height, label, disabled, trackColor, valueColor, onChange, onBegin, onEnd, }: XYPadProps): import("react").JSX.Element;
+export interface ParamXYPadProps {
+    paramX: string;
+    paramY: string;
+    width?: number;
+    height?: number;
+    label?: string;
+    trackColor?: string;
+    valueColor?: string;
+}
+/** An XYPad driving two APVTS parameters at once. */
+export declare function ParamXYPad({ paramX, paramY, label, ...rest }: ParamXYPadProps): import("react").JSX.Element;
+export interface SegmentedProps {
+    options: string[];
+    index: number;
+    label?: string;
+    disabled?: boolean;
+    trackColor?: string;
+    activeColor?: string;
+    textColor?: string;
+    activeTextColor?: string;
+    onChange: (index: number) => void;
+}
+/** A row of exclusive options — oscillator shapes, filter modes, A/B/C. */
+export declare function Segmented({ options, index, label, disabled, trackColor, activeColor, textColor, activeTextColor, onChange, }: SegmentedProps): import("react").JSX.Element;
+export interface ParamSegmentedProps {
+    paramId: string;
+    options: string[];
+    label?: string;
+    trackColor?: string;
+    activeColor?: string;
+    textColor?: string;
+    activeTextColor?: string;
+}
+/** A Segmented bound to a choice-style APVTS parameter: the normalized
+    value maps to an option index (index / (count − 1)). */
+export declare function ParamSegmented({ paramId, options, label, ...rest }: ParamSegmentedProps): import("react").JSX.Element;
+export interface GenericEditorProps {
+    /** Knobs per row. Default 4. */
+    columns?: number;
+    /** Knob diameter. Default 72. */
+    size?: number;
+    trackColor?: string;
+    valueColor?: string;
+}
+/** The zero-effort editor: one knob per APVTS parameter, laid out in
+    rows. `render(<GenericEditor />)` is a complete, working plugin UI. */
+export declare function GenericEditor({ columns, size, trackColor, valueColor }: GenericEditorProps): import("react").JSX.Element;

package/dist/controls.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// Knob and Slider — the classic VST controls, drawn by the VSReacT painter
-// (arc styles) and driven by drag gestures.
+// The built-in VST controls — knobs, sliders, toggles, XY pads, segmented
+// switches — drawn by the VSReacT painter and driven by drag gestures.
+// Each has a Param* variant bound to an APVTS parameter.
 import { useRef } from "react";
 import { View, Text } from "./primitives";
-import { useParameter } from "./parameters";
+import { useParameter, useParameterList } from "./parameters";
+import { useSpring } from "./animation";
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
 /** Vertical-drag-to-value mapping shared by Knob (and tested in isolation). */
 export function dragToValue(startValue, dy, sensitivity = 0.005) {
-    return Math.min(1, Math.max(0, startValue - dy * sensitivity));
+    return clamp01(startValue - dy * sensitivity);
 }
 const ARC_START = -135;
 const ARC_END = 135;
@@ -33,20 +36,104 @@ export function ParamKnob({ paramId, label, size, trackColor, valueColor }) {
     const param = useParameter(paramId);
     return (_jsx(Knob, { value: param.value, text: param.text, label: label ?? param.name.toUpperCase(), size: size, trackColor: trackColor, valueColor: valueColor, onChange: param.set, onBegin: param.begin, onEnd: param.end }));
 }
-export function Slider({ value, width = 160, label, disabled, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
+export function Slider({ value, width = 160, height = 160, vertical, label, disabled, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
     const startValue = useRef(0);
-    const clamped = Math.min(1, Math.max(0, value));
-    return (_jsxs(View, { className: "gap-2", children: [_jsxs(View, { className: `h-[18] justify-center relative ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width }, onDragStart: disabled
+    const clamped = clamp01(value);
+    const onDragStart = disabled
+        ? undefined
+        : () => {
+            startValue.current = clamped;
+            onBegin?.();
+        };
+    const onDragEnd = disabled ? undefined : () => onEnd?.();
+    if (vertical) {
+        return (_jsxs(View, { className: "items-center gap-2", children: [_jsxs(View, { className: `w-[18] relative ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { height }, onDragStart: onDragStart, onDrag: disabled ? undefined : (e) => onChange(clamp01(startValue.current - e.dy / height)), onDragEnd: onDragEnd, children: [_jsx(View, { className: "absolute w-[4] rounded-full left-[7] top-0 bottom-0", style: { backgroundColor: trackColor } }), _jsx(View, { className: "absolute w-[4] rounded-full left-[7] bottom-0", style: { height: clamped * height, backgroundColor: valueColor } }), _jsx(View, { className: "absolute w-[12] h-[12] rounded-full left-[3]", style: { top: (1 - clamped) * (height - 12), backgroundColor: valueColor } })] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+    }
+    return (_jsxs(View, { className: "gap-2", children: [_jsxs(View, { className: `h-[18] justify-center relative ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width }, onDragStart: onDragStart, onDrag: disabled ? undefined : (e) => onChange(clamp01(startValue.current + e.dx / width)), onDragEnd: onDragEnd, children: [_jsx(View, { className: "h-[4] rounded-full", style: { backgroundColor: trackColor } }), _jsx(View, { className: "absolute h-[4] rounded-full top-[7]", style: { width: clamped * width, backgroundColor: valueColor } }), _jsx(View, { className: "absolute w-[12] h-[12] rounded-full top-[3]", style: { left: clamped * (width - 12), backgroundColor: valueColor } })] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+}
+/** A Slider bound to an APVTS parameter (via ParameterBridge). */
+export function ParamSlider({ paramId, label, width, height, vertical }) {
+    const param = useParameter(paramId);
+    return (_jsx(Slider, { value: param.value, label: label ?? param.name.toUpperCase(), width: width, height: height, vertical: vertical, onChange: param.set, onBegin: param.begin, onEnd: param.end }));
+}
+/** A switch with a spring-animated thumb — bypass, on/off, A/B. */
+export function Toggle({ on, label, size = 22, disabled, trackColor = "#2A2F27", onColor = "#C6F135", thumbColor = "#F4F4F5", onChange, }) {
+    const t = useSpring(on ? 1 : 0, { stiffness: 300, damping: 28 });
+    const trackWidth = Math.round(size * 1.8);
+    const thumb = size - 6;
+    const travel = trackWidth - thumb - 6;
+    return (_jsxs(View, { className: "items-center gap-2", children: [_jsx(View, { className: `relative rounded-full ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width: trackWidth, height: size, backgroundColor: on ? onColor : trackColor }, onClick: disabled ? undefined : () => onChange(!on), children: _jsx(View, { className: "absolute rounded-full", style: {
+                        width: thumb,
+                        height: thumb,
+                        top: 3,
+                        left: 3 + clamp01(t) * travel,
+                        backgroundColor: thumbColor,
+                    } }) }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+}
+/** A Toggle bound to a bool-style APVTS parameter (on = value ≥ 0.5). */
+export function ParamToggle({ paramId, label, ...rest }) {
+    const param = useParameter(paramId);
+    return (_jsx(Toggle, { on: param.value >= 0.5, label: label ?? param.name.toUpperCase(), onChange: (next) => {
+            param.begin();
+            param.set(next ? 1 : 0);
+            param.end();
+        }, ...rest }));
+}
+/** A 2D drag pad with crosshair — filter cutoff/resonance, pan/depth… */
+export function XYPad({ x, y, width = 160, height = 160, label, disabled, trackColor = "#161B17", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
+    const start = useRef({ x: 0, y: 0 });
+    const cxv = clamp01(x);
+    const cyv = clamp01(y);
+    const thumb = 14;
+    const tx = cxv * (width - thumb);
+    const ty = (1 - cyv) * (height - thumb);
+    return (_jsxs(View, { className: "items-center gap-2", children: [_jsxs(View, { className: `relative rounded-lg overflow-hidden border ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width, height, backgroundColor: trackColor, borderColor: "#00000055" }, onDragStart: disabled
                     ? undefined
                     : () => {
-                        startValue.current = clamped;
+                        start.current = { x: cxv, y: cyv };
                         onBegin?.();
                     }, onDrag: disabled
                     ? undefined
-                    : (e) => onChange(Math.min(1, Math.max(0, startValue.current + e.dx / width))), onDragEnd: disabled ? undefined : () => onEnd?.(), children: [_jsx(View, { className: "h-[4] rounded-full", style: { backgroundColor: trackColor } }), _jsx(View, { className: "absolute h-[4] rounded-full top-[7]", style: { width: clamped * width, backgroundColor: valueColor } }), _jsx(View, { className: "absolute w-[12] h-[12] rounded-full top-[3]", style: { left: clamped * (width - 12), backgroundColor: valueColor } })] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+                    : (e) => onChange(clamp01(start.current.x + e.dx / width), clamp01(start.current.y - e.dy / height)), onDragEnd: disabled ? undefined : () => onEnd?.(), children: [_jsx(View, { className: "absolute left-0 right-0 h-[1]", style: { top: ty + thumb / 2, backgroundColor: valueColor, opacity: 0.35 } }), _jsx(View, { className: "absolute top-0 bottom-0 w-[1]", style: { left: tx + thumb / 2, backgroundColor: valueColor, opacity: 0.35 } }), _jsx(View, { className: "absolute rounded-full", style: { width: thumb, height: thumb, left: tx, top: ty, backgroundColor: valueColor } })] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
 }
-/** A Slider bound to an APVTS parameter (via ParameterBridge). */
-export function ParamSlider({ paramId, label, width }) {
+/** An XYPad driving two APVTS parameters at once. */
+export function ParamXYPad({ paramX, paramY, label, ...rest }) {
+    const px = useParameter(paramX);
+    const py = useParameter(paramY);
+    return (_jsx(XYPad, { x: px.value, y: py.value, label: label ?? `${px.name} / ${py.name}`.toUpperCase(), onChange: (nx, ny) => {
+            px.set(nx);
+            py.set(ny);
+        }, onBegin: () => {
+            px.begin();
+            py.begin();
+        }, onEnd: () => {
+            px.end();
+            py.end();
+        }, ...rest }));
+}
+/** A row of exclusive options — oscillator shapes, filter modes, A/B/C. */
+export function Segmented({ options, index, label, disabled, trackColor = "#2A2F27", activeColor = "#C6F135", textColor = "#a1a1aa", activeTextColor = "#09090b", onChange, }) {
+    const current = Math.min(options.length - 1, Math.max(0, index));
+    return (_jsxs(View, { className: "items-center gap-2", children: [_jsx(View, { className: `flex-row rounded-lg p-[3] gap-[3] ${disabled ? "opacity-40" : ""}`, style: { backgroundColor: trackColor }, children: options.map((option, i) => (_jsx(View, { className: `px-3 py-[6] rounded-md ${disabled ? "" : "cursor-pointer"}`, style: { backgroundColor: i === current ? activeColor : "#00000000" }, onClick: disabled ? undefined : () => onChange(i), children: _jsx(Text, { className: "text-[11] font-bold tracking-wide", style: { color: i === current ? activeTextColor : textColor }, children: option }) }, `${option}-${i}`))) }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+}
+/** A Segmented bound to a choice-style APVTS parameter: the normalized
+    value maps to an option index (index / (count − 1)). */
+export function ParamSegmented({ paramId, options, label, ...rest }) {
     const param = useParameter(paramId);
-    return (_jsx(Slider, { value: param.value, label: label ?? param.name.toUpperCase(), width: width, onChange: param.set, onBegin: param.begin, onEnd: param.end }));
+    const count = Math.max(1, options.length);
+    const index = Math.round(param.value * (count - 1));
+    return (_jsx(Segmented, { options: options, index: index, label: label ?? param.name.toUpperCase(), onChange: (i) => {
+            param.begin();
+            param.set(count <= 1 ? 0 : i / (count - 1));
+            param.end();
+        }, ...rest }));
+}
+/** The zero-effort editor: one knob per APVTS parameter, laid out in
+    rows. `render(<GenericEditor />)` is a complete, working plugin UI. */
+export function GenericEditor({ columns = 4, size = 72, trackColor, valueColor }) {
+    const params = useParameterList();
+    const rows = [];
+    for (let i = 0; i < params.length; i += Math.max(1, columns))
+        rows.push(params.slice(i, i + Math.max(1, columns)));
+    return (_jsx(View, { className: "flex-1 flex-col items-center justify-center gap-6 p-4", children: rows.map((row, index) => (_jsx(View, { className: "flex-row gap-7", children: row.map((param) => (_jsx(ParamKnob, { paramId: param.id, size: size, trackColor: trackColor, valueColor: valueColor }, param.id))) }, index))) }));
 }

package/dist/cx.d.ts

@@ -0,0 +1,6 @@
+export type ClassValue = string | number | null | false | undefined | ClassValue[] | Record<string, unknown>;
+/**
+ * `cx("flex", active && "bg-red-500", { "opacity-40": disabled })`
+ * → `"flex bg-red-500 opacity-40"`.
+ */
+export declare function cx(...inputs: ClassValue[]): string;

package/dist/cx.js

@@ -0,0 +1,26 @@
+// cx — compose conditional className strings (a tiny clsx).
+/**
+ * `cx("flex", active && "bg-red-500", { "opacity-40": disabled })`
+ * → `"flex bg-red-500 opacity-40"`.
+ */
+export function cx(...inputs) {
+    const out = [];
+    for (const input of inputs) {
+        if (!input && input !== 0)
+            continue;
+        if (typeof input === "string" || typeof input === "number") {
+            out.push(String(input));
+        }
+        else if (Array.isArray(input)) {
+            const nested = cx(...input);
+            if (nested)
+                out.push(nested);
+        }
+        else if (typeof input === "object") {
+            for (const [key, value] of Object.entries(input))
+                if (value)
+                    out.push(key);
+        }
+    }
+    return out.join(" ");
+}

package/dist/hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
+ * of the component. The handler can close over fresh state — it is kept
+ * current without resubscribing.
+ *
+ *   useNativeEvent("download:progress", (p) => setProgress(p.ratio));
+ */
+export declare function useNativeEvent(name: string, handler: (payload: any) => void): void;
+/**
+ * The value, but only after it has stopped changing for `delayMs` —
+ * classic input debouncing for expensive native calls:
+ *
+ *   const query = useDebounced(text, 250);
+ *   useEffect(() => { native.call("library:search", { query }); }, [query]);
+ */
+export declare function useDebounced<T>(value: T, delayMs: number): T;

package/dist/hooks.js

@@ -0,0 +1,30 @@
+// Convenience hooks over the native bridge.
+import { useEffect, useRef, useState } from "react";
+import { native } from "./native";
+/**
+ * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
+ * of the component. The handler can close over fresh state — it is kept
+ * current without resubscribing.
+ *
+ *   useNativeEvent("download:progress", (p) => setProgress(p.ratio));
+ */
+export function useNativeEvent(name, handler) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => native.on(name, (payload) => handlerRef.current(payload)), [name]);
+}
+/**
+ * The value, but only after it has stopped changing for `delayMs` —
+ * classic input debouncing for expensive native calls:
+ *
+ *   const query = useDebounced(text, 250);
+ *   useEffect(() => { native.call("library:search", { query }); }, [query]);
+ */
+export function useDebounced(value, delayMs) {
+    const [debounced, setDebounced] = useState(value);
+    useEffect(() => {
+        const id = setTimeout(() => setDebounced(value), delayMs);
+        return () => clearTimeout(id);
+    }, [value, delayMs]);
+    return debounced;
+}

package/dist/index.d.ts

@@ -4,12 +4,17 @@ export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export type { CommonProps, TextProps, ImageProps, TextInputProps, NativeViewProps, } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
+export { useNativeEvent, useDebounced } from "./hooks";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
-export { useTween, lerp, Easing } from "./animation";
-export type { TweenOptions, EasingFn } from "./animation";
-export { useParameter } from "./parameters";
-export type { ParameterState, ParameterHandle } from "./parameters";
-export { Knob, Slider, ParamKnob, ParamSlider, dragToValue } from "./controls";
-export type { KnobProps, SliderProps, ParamKnobProps, ParamSliderProps } from "./controls";
+export { cx } from "./cx";
+export type { ClassValue } from "./cx";
+export { useTween, useSpring, springStep, lerp, Easing } from "./animation";
+export type { TweenOptions, SpringOptions, EasingFn } from "./animation";
+export { useParameter, useParameterList } from "./parameters";
+export type { ParameterState, ParameterHandle, ParameterInfo } from "./parameters";
+export { Knob, Slider, Toggle, XYPad, Segmented, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, dragToValue, } from "./controls";
+export type { KnobProps, SliderProps, ToggleProps, XYPadProps, SegmentedProps, GenericEditorProps, ParamKnobProps, ParamSliderProps, ParamToggleProps, ParamXYPadProps, ParamSegmentedProps, } from "./controls";
+export { Meter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
 export type { DragEventPayload } from "./primitives";

package/dist/index.js

@@ -1,11 +1,14 @@
-// vsreact public API. runtime must load first — it installs the
+// @vsreact/core public API. runtime must load first — it installs the
 // timer/console/microtask shims react depends on inside QuickJS.
 import "./runtime";
 import "./bridge";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
+export { useNativeEvent, useDebounced } from "./hooks";
 export { configureTheme, tw } from "./tw";
-export { useTween, lerp, Easing } from "./animation";
-export { useParameter } from "./parameters";
-export { Knob, Slider, ParamKnob, ParamSlider, dragToValue } from "./controls";
+export { cx } from "./cx";
+export { useTween, useSpring, springStep, lerp, Easing } from "./animation";
+export { useParameter, useParameterList } from "./parameters";
+export { Knob, Slider, Toggle, XYPad, Segmented, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, dragToValue, } from "./controls";
+export { Meter, usePeakHold, peakHoldStep } from "./meter";

package/dist/meter.d.ts

@@ -0,0 +1,37 @@
+export interface PeakHoldOptions {
+    /** How long a peak is held before it starts falling. Default 600ms. */
+    holdMs?: number;
+    /** Fall rate once the hold expires, in value/second. Default 1.5. */
+    decayPerSecond?: number;
+}
+export interface PeakHoldState {
+    peak: number;
+    heldForMs: number;
+}
+/** One peak-hold step (pure, testable): new peaks latch instantly and
+    reset the hold timer; after holdMs the peak decays toward the value. */
+export declare function peakHoldStep(state: PeakHoldState, value: number, dtMs: number, { holdMs, decayPerSecond }?: PeakHoldOptions): PeakHoldState;
+/** The held peak for a live value — drives the Meter's peak line. */
+export declare function usePeakHold(value: number, options?: PeakHoldOptions): number;
+export interface MeterProps {
+    /** Level 0..1. */
+    value: number;
+    /** Long-axis length. Default 120. */
+    length?: number;
+    /** Short-axis thickness. Default 10. */
+    thickness?: number;
+    /** Horizontal bar instead of the vertical default. */
+    horizontal?: boolean;
+    /** Show the peak-hold line. Default true. */
+    peak?: boolean;
+    holdMs?: number;
+    decayPerSecond?: number;
+    /** Where the fill turns hot, 0..1. Default 0.85. */
+    hotFrom?: number;
+    trackColor?: string;
+    color?: string;
+    hotColor?: string;
+    label?: string;
+}
+/** A natively painted level meter with hot zone + peak hold. */
+export declare function Meter({ value, length, thickness, horizontal, peak, holdMs, decayPerSecond, hotFrom, trackColor, color, hotColor, label, }: MeterProps): import("react").JSX.Element;

package/dist/meter.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Meter — the level meter every plugin needs: painted bar with a hot zone
+// and a peak-hold line that holds, then falls. Feed it any 0..1 value
+// (typically pushed from C++ via useNativeEvent).
+import { useEffect, useRef, useState } from "react";
+import { View, Text } from "./primitives";
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/** One peak-hold step (pure, testable): new peaks latch instantly and
+    reset the hold timer; after holdMs the peak decays toward the value. */
+export function peakHoldStep(state, value, dtMs, { holdMs = 600, decayPerSecond = 1.5 } = {}) {
+    if (value >= state.peak)
+        return { peak: value, heldForMs: 0 };
+    const heldForMs = state.heldForMs + dtMs;
+    if (heldForMs < holdMs)
+        return { peak: state.peak, heldForMs };
+    return { peak: Math.max(value, state.peak - decayPerSecond * (dtMs / 1000)), heldForMs };
+}
+const FRAME_MS = 33; // meters read fine at ~30fps
+/** The held peak for a live value — drives the Meter's peak line. */
+export function usePeakHold(value, options = {}) {
+    const [peak, setPeak] = useState(value);
+    const state = useRef({ peak: value, heldForMs: 0 });
+    const valueRef = useRef(value);
+    valueRef.current = value;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    useEffect(() => {
+        const id = setInterval(() => {
+            state.current = peakHoldStep(state.current, valueRef.current, FRAME_MS, optionsRef.current);
+            setPeak(state.current.peak);
+        }, FRAME_MS);
+        return () => clearInterval(id);
+    }, []);
+    return Math.max(peak, value);
+}
+/** A natively painted level meter with hot zone + peak hold. */
+export function Meter({ value, length = 120, thickness = 10, horizontal, peak = true, holdMs, decayPerSecond, hotFrom = 0.85, trackColor = "#141714", color = "#C6F135", hotColor = "#FF4545", label, }) {
+    const level = clamp01(value);
+    const held = usePeakHold(level, { holdMs, decayPerSecond });
+    const hot = clamp01(hotFrom);
+    const fill = Math.min(level, hot) * length;
+    const hotFill = level > hot ? (level - hot) * length : 0;
+    const peakAt = clamp01(held) * length;
+    const bar = horizontal ? (_jsxs(View, { className: "relative rounded overflow-hidden", style: { width: length, height: thickness, backgroundColor: trackColor }, children: [_jsx(View, { className: "absolute left-0 top-0 bottom-0", style: { width: fill, backgroundColor: color } }), hotFill > 0 ? (_jsx(View, { className: "absolute top-0 bottom-0", style: { left: hot * length, width: hotFill, backgroundColor: hotColor } })) : null, peak && peakAt > 2 ? (_jsx(View, { className: "absolute top-0 bottom-0 w-[2]", style: { left: peakAt - 2, backgroundColor: held >= hot ? hotColor : color } })) : null] })) : (_jsxs(View, { className: "relative rounded overflow-hidden", style: { width: thickness, height: length, backgroundColor: trackColor }, children: [_jsx(View, { className: "absolute bottom-0 left-0 right-0", style: { height: fill, backgroundColor: color } }), hotFill > 0 ? (_jsx(View, { className: "absolute left-0 right-0", style: { bottom: hot * length, height: hotFill, backgroundColor: hotColor } })) : null, peak && peakAt > 2 ? (_jsx(View, { className: "absolute left-0 right-0 h-[2]", style: { bottom: peakAt - 2, backgroundColor: held >= hot ? hotColor : color } })) : null] }));
+    if (label === undefined)
+        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 })] }));
+}

package/dist/parameters.d.ts

@@ -9,4 +9,18 @@ export interface ParameterHandle extends ParameterState {
     begin: () => void;
     end: () => void;
 }
+export interface ParameterInfo {
+    id: string;
+    name: string;
+    label: string;
+    /** Normalized 0..1 snapshot at mount — use useParameter(id) for live values. */
+    value: number;
+    text: string;
+}
+/**
+ * Enumerates every APVTS parameter (via param:list) once at mount — the
+ * host's parameter set is fixed for the plugin's lifetime. Powers
+ * <GenericEditor/> and any auto-generated UI.
+ */
+export declare function useParameterList(): ParameterInfo[];
 export declare function useParameter(id: string): ParameterHandle;

package/dist/parameters.js

@@ -2,6 +2,26 @@
 // parameter through vsreact::ParameterBridge. Values are normalized 0..1.
 import { useCallback, useEffect, useState } from "react";
 import { native } from "./native";
+/**
+ * Enumerates every APVTS parameter (via param:list) once at mount — the
+ * host's parameter set is fixed for the plugin's lifetime. Powers
+ * <GenericEditor/> and any auto-generated UI.
+ */
+export function useParameterList() {
+    const [list] = useState(() => {
+        const result = native.call("param:list");
+        if (!Array.isArray(result))
+            return [];
+        return result.map((entry) => ({
+            id: String(entry?.id ?? ""),
+            name: String(entry?.name ?? entry?.id ?? ""),
+            label: String(entry?.label ?? ""),
+            value: Number(entry?.value ?? 0),
+            text: String(entry?.text ?? ""),
+        }));
+    });
+    return list;
+}
 export function useParameter(id) {
     const [state, setState] = useState(() => {
         const initial = native.call("param:get", { id });