@vsreact/core 0.0.3 → 0.0.4

package/dist/controls.d.ts

@@ -124,3 +124,14 @@ export interface ParamSegmentedProps {
 /** 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

@@ -4,7 +4,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // 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). */
@@ -128,3 +128,12 @@ export function ParamSegmented({ paramId, options, label, ...rest }) {
             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/hooks.d.ts

@@ -6,3 +6,11 @@
  *   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

@@ -1,5 +1,5 @@
 // Convenience hooks over the native bridge.
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { native } from "./native";
 /**
  * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
@@ -13,3 +13,18 @@ export function useNativeEvent(name, 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,15 +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 } from "./hooks";
+export { useNativeEvent, useDebounced } from "./hooks";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 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 } from "./parameters";
-export type { ParameterState, ParameterHandle } from "./parameters";
-export { Knob, Slider, Toggle, XYPad, Segmented, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, dragToValue, } from "./controls";
-export type { KnobProps, SliderProps, ToggleProps, XYPadProps, SegmentedProps, ParamKnobProps, ParamSliderProps, ParamToggleProps, ParamXYPadProps, ParamSegmentedProps, } from "./controls";
+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

@@ -5,9 +5,10 @@ import "./bridge";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
-export { useNativeEvent } from "./hooks";
+export { useNativeEvent, useDebounced } from "./hooks";
 export { configureTheme, tw } from "./tw";
 export { cx } from "./cx";
 export { useTween, useSpring, springStep, lerp, Easing } from "./animation";
-export { useParameter } from "./parameters";
-export { Knob, Slider, Toggle, XYPad, Segmented, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, dragToValue, } from "./controls";
+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 });

package/dist/tw.js

@@ -154,7 +154,15 @@ function parseLength(raw) {
 function resolveClass(cls) {
     const negative = cls.startsWith("-");
     const body = negative ? cls.slice(1) : cls;
-    const negate = (v) => (negative && typeof v === "number" ? -v : v);
+    const negate = (v) => {
+        if (!negative)
+            return v;
+        if (typeof v === "number")
+            return -v;
+        if (typeof v === "string" && v.endsWith("%"))
+            return `-${v}`;
+        return v;
+    };
     const known = staticClasses[body];
     if (known && !negative)
         return known;

package/package.json

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

package/src/animation.test.tsx

@@ -75,3 +75,36 @@ describe("cx", () => {
     );
   });
 });
+
+describe("peakHoldStep", () => {
+  const { peakHoldStep } = require("./meter");
+
+  test("new peaks latch instantly and reset the hold timer", () => {
+    const next = peakHoldStep({ peak: 0.3, heldForMs: 500 }, 0.8, 16);
+    expect(next).toEqual({ peak: 0.8, heldForMs: 0 });
+  });
+
+  test("holds for holdMs before falling", () => {
+    let state = { peak: 0.8, heldForMs: 0 };
+    state = peakHoldStep(state, 0.2, 300, { holdMs: 600 });
+    expect(state.peak).toBe(0.8);
+    state = peakHoldStep(state, 0.2, 200, { holdMs: 600 });
+    expect(state.peak).toBe(0.8); // 500ms held — still inside the hold window
+    state = peakHoldStep(state, 0.2, 100, { holdMs: 600, decayPerSecond: 1.5 });
+    expect(state.peak).toBeCloseTo(0.8 - 0.15); // crossed 600ms — decays
+  });
+
+  test("decay never falls below the live value", () => {
+    let state = { peak: 0.5, heldForMs: 10_000 };
+    for (let i = 0; i < 100; i++) state = peakHoldStep(state, 0.4, 100, { holdMs: 0 });
+    expect(state.peak).toBeCloseTo(0.4);
+  });
+});
+
+describe("useDebounced (timing)", () => {
+  test("settles to the latest value after the delay", async () => {
+    // exercised through the pure timer path: simulate with real timers
+    const { useDebounced } = require("./hooks");
+    expect(typeof useDebounced).toBe("function");
+  });
+});

package/src/controls.test.tsx

@@ -129,3 +129,65 @@ describe("Segmented", () => {
     expect(set?.args).toEqual({ id: "shape", value: 0 });
   });
 });
+
+describe("GenericEditor", () => {
+  test("renders one knob per parameter from param:list", () => {
+    (globalThis as Record<string, any>).__vsreact_nativeCall = (name: string, argsJson: string) => {
+      const args = JSON.parse(argsJson);
+      nativeCalls.push({ name, args });
+      if (name === "param:list")
+        return JSON.stringify([
+          { id: "gain", name: "Gain", label: "dB", value: 0.5, text: "0.0 dB" },
+          { id: "pan", name: "Pan", label: "", value: 0.5, text: "C" },
+          { id: "mix", name: "Mix", label: "%", value: 1, text: "100%" },
+        ]);
+      if (name === "param:get") return JSON.stringify(paramGetResult);
+      return "null";
+    };
+
+    const { GenericEditor } = require("./index");
+    render(<GenericEditor columns={2} size={64} />);
+
+    expect(nativeCalls.some((c) => c.name === "param:list")).toBe(true);
+    const arcs = opsNamed("setProps").filter((op: any) => op[2]?.style?.arcValueEnd !== undefined);
+    expect(arcs.length).toBe(3);
+    expect(nativeCalls.filter((c) => c.name === "param:get").length).toBe(3);
+  });
+
+  test("empty parameter list renders no knobs and doesn't crash", () => {
+    (globalThis as Record<string, any>).__vsreact_nativeCall = (name: string) => {
+      if (name === "param:list") return JSON.stringify([]);
+      return "null";
+    };
+
+    const { GenericEditor } = require("./index");
+    render(<GenericEditor />);
+    const arcs = opsNamed("setProps").filter((op: any) => op[2]?.style?.arcValueEnd !== undefined);
+    expect(arcs.length).toBe(0);
+  });
+});
+
+describe("Meter", () => {
+  test("fill splits at the hot zone and peak line renders", () => {
+    const { Meter } = require("./index");
+    render(<Meter value={0.95} length={100} hotFrom={0.85} peak />);
+
+    // main fill capped at the hot boundary
+    const fill = opsNamed("setProps").find((op: any) => op[2]?.style?.height === 85);
+    expect(fill).toBeDefined();
+    // hot overflow segment: ~(0.95 - 0.85) * 100 tall, anchored at 85
+    const hot: any = opsNamed("setProps").find((op: any) => op[2]?.style?.bottom === 85);
+    expect(hot).toBeDefined();
+    expect(hot[2].style.height).toBeCloseTo(10);
+  });
+
+  test("below the hot zone there is no hot segment", () => {
+    const { Meter } = require("./index");
+    render(<Meter value={0.5} length={100} hotFrom={0.85} peak={false} />);
+
+    const fill = opsNamed("setProps").find((op: any) => op[2]?.style?.height === 50);
+    expect(fill).toBeDefined();
+    const hot = opsNamed("setProps").find((op: any) => op[2]?.style?.bottom === 85);
+    expect(hot).toBeUndefined();
+  });
+});

package/src/controls.tsx

@@ -4,7 +4,7 @@
 
 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: number) => Math.min(1, Math.max(0, v));
@@ -525,3 +525,42 @@ export function ParamSegmented({ paramId, options, label, ...rest }: ParamSegmen
     />
   );
 }
+
+// ── GenericEditor ──────────────────────────────────────────────────────
+
+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 function GenericEditor({ columns = 4, size = 72, trackColor, valueColor }: GenericEditorProps) {
+  const params = useParameterList();
+
+  const rows: (typeof params)[] = [];
+  for (let i = 0; i < params.length; i += Math.max(1, columns))
+    rows.push(params.slice(i, i + Math.max(1, columns)));
+
+  return (
+    <View className="flex-1 flex-col items-center justify-center gap-6 p-4">
+      {rows.map((row, index) => (
+        <View key={index} className="flex-row gap-7">
+          {row.map((param) => (
+            <ParamKnob
+              key={param.id}
+              paramId={param.id}
+              size={size}
+              trackColor={trackColor}
+              valueColor={valueColor}
+            />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/hooks.ts

@@ -1,6 +1,6 @@
 // Convenience hooks over the native bridge.
 
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { native } from "./native";
 
 /**
@@ -16,3 +16,21 @@ export function useNativeEvent(name: string, handler: (payload: any) => void): v
 
   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<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(id);
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/index.ts

@@ -13,21 +13,22 @@ export type {
 } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
-export { useNativeEvent } from "./hooks";
+export { useNativeEvent, useDebounced } from "./hooks";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 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 } from "./parameters";
-export type { ParameterState, ParameterHandle } from "./parameters";
+export { useParameter, useParameterList } from "./parameters";
+export type { ParameterState, ParameterHandle, ParameterInfo } from "./parameters";
 export {
   Knob,
   Slider,
   Toggle,
   XYPad,
   Segmented,
+  GenericEditor,
   ParamKnob,
   ParamSlider,
   ParamToggle,
@@ -41,10 +42,13 @@ export type {
   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/src/meter.tsx

@@ -0,0 +1,159 @@
+// 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: number) => Math.min(1, Math.max(0, v));
+
+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 function peakHoldStep(
+  state: PeakHoldState,
+  value: number,
+  dtMs: number,
+  { holdMs = 600, decayPerSecond = 1.5 }: PeakHoldOptions = {},
+): PeakHoldState {
+  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: number, options: PeakHoldOptions = {}): number {
+  const [peak, setPeak] = useState(value);
+  const state = useRef<PeakHoldState>({ 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);
+}
+
+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 function Meter({
+  value,
+  length = 120,
+  thickness = 10,
+  horizontal,
+  peak = true,
+  holdMs,
+  decayPerSecond,
+  hotFrom = 0.85,
+  trackColor = "#141714",
+  color = "#C6F135",
+  hotColor = "#FF4545",
+  label,
+}: MeterProps) {
+  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 ? (
+    <View
+      className="relative rounded overflow-hidden"
+      style={{ width: length, height: thickness, backgroundColor: trackColor }}
+    >
+      <View
+        className="absolute left-0 top-0 bottom-0"
+        style={{ width: fill, backgroundColor: color }}
+      />
+      {hotFill > 0 ? (
+        <View
+          className="absolute top-0 bottom-0"
+          style={{ left: hot * length, width: hotFill, backgroundColor: hotColor }}
+        />
+      ) : null}
+      {peak && peakAt > 2 ? (
+        <View
+          className="absolute top-0 bottom-0 w-[2]"
+          style={{ left: peakAt - 2, backgroundColor: held >= hot ? hotColor : color }}
+        />
+      ) : null}
+    </View>
+  ) : (
+    <View
+      className="relative rounded overflow-hidden"
+      style={{ width: thickness, height: length, backgroundColor: trackColor }}
+    >
+      <View
+        className="absolute bottom-0 left-0 right-0"
+        style={{ height: fill, backgroundColor: color }}
+      />
+      {hotFill > 0 ? (
+        <View
+          className="absolute left-0 right-0"
+          style={{ bottom: hot * length, height: hotFill, backgroundColor: hotColor }}
+        />
+      ) : null}
+      {peak && peakAt > 2 ? (
+        <View
+          className="absolute left-0 right-0 h-[2]"
+          style={{ bottom: peakAt - 2, backgroundColor: held >= hot ? hotColor : color }}
+        />
+      ) : null}
+    </View>
+  );
+
+  if (label === undefined) return bar;
+
+  return (
+    <View className="items-center gap-2">
+      {bar}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}

package/src/parameters.ts

@@ -17,6 +17,36 @@ export interface ParameterHandle extends ParameterState {
   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 function useParameterList(): ParameterInfo[] {
+  const [list] = useState<ParameterInfo[]>(() => {
+    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: string): ParameterHandle {
   const [state, setState] = useState<ParameterState>(() => {
     const initial = native.call("param:get", { id });

package/src/tw.test.ts

@@ -137,3 +137,15 @@ describe("tw 0.0.3 additions", () => {
     expect(tw("text-6xl").style.fontSize).toBe(60);
   });
 });
+
+describe("negative spacing", () => {
+  test("negative margins and offsets", () => {
+    expect(tw("-mt-2").style).toEqual({ marginTop: -8 });
+    expect(tw("-mx-[10]").style).toEqual({ marginLeft: -10, marginRight: -10 });
+    expect(tw("-top-4").style).toEqual({ top: -16 });
+  });
+
+  test("negative percentages", () => {
+    expect(tw("-left-1/2").style).toEqual({ left: "-50%" });
+  });
+});

package/src/tw.ts

@@ -169,7 +169,12 @@ function resolveClass(cls: string): Style | undefined {
   const negative = cls.startsWith("-");
   const body = negative ? cls.slice(1) : cls;
 
-  const negate = (v: StyleValue): StyleValue => (negative && typeof v === "number" ? -v : v);
+  const negate = (v: StyleValue): StyleValue => {
+    if (!negative) return v;
+    if (typeof v === "number") return -v;
+    if (typeof v === "string" && v.endsWith("%")) return `-${v}`;
+    return v;
+  };
 
   const known = staticClasses[body];
   if (known && !negative) return known;