@vsreact/core 0.0.6 → 0.0.8

package/dist/button.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+export interface ButtonProps {
+    label?: string;
+    children?: ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+    /** solid (default) — filled; outline — bordered; ghost — text only. */
+    variant?: "solid" | "outline" | "ghost";
+    size?: "sm" | "md" | "lg";
+    accentColor?: string;
+    /** Text color for the solid variant (default near-black). */
+    textColor?: string;
+}
+/** A pressable with sensible plugin styling — solid/outline/ghost. */
+export declare function Button({ label, children, onClick, disabled, variant, size, accentColor, textColor, }: ButtonProps): import("react").JSX.Element;

package/dist/button.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { View, Text } from "./primitives";
+import { cx } from "./cx";
+const SIZES = {
+    sm: { pad: "px-3 py-[5]", text: 11 },
+    md: { pad: "px-4 py-[8]", text: 12 },
+    lg: { pad: "px-5 py-[11]", text: 13 },
+};
+/** A pressable with sensible plugin styling — solid/outline/ghost. */
+export function Button({ label, children, onClick, disabled, variant = "solid", size = "md", accentColor = "#C6F135", textColor = "#09090b", }) {
+    const { pad, text } = SIZES[size];
+    const className = cx("flex-row items-center justify-center gap-2 rounded-lg", pad, disabled ? "opacity-40" : "cursor-pointer", !disabled && variant === "solid" && "hover:opacity-90 active:opacity-75", !disabled && variant !== "solid" && "hover:bg-white/10 active:bg-white/15", variant === "outline" && "border");
+    const style = variant === "solid"
+        ? { backgroundColor: accentColor }
+        : variant === "outline"
+            ? { borderColor: accentColor }
+            : {};
+    const color = variant === "solid" ? textColor : accentColor;
+    return (_jsxs(View, { className: className, style: style, onClick: disabled ? undefined : onClick, children: [label !== undefined ? (_jsx(Text, { className: "font-bold tracking-wide", style: { fontSize: text, color }, children: label })) : null, children] }));
+}

package/dist/components.d.ts

@@ -0,0 +1,10 @@
+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 { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
+export type { BarsProps, WaveformProps } from "./visualizers";
+export { Button } from "./button";
+export type { ButtonProps } from "./button";
+export { Tooltip, Modal } from "./popover";
+export type { TooltipProps, ModalProps } from "./popover";

package/dist/components.js

@@ -0,0 +1,12 @@
+// The component layer, importable on its own:
+//
+//   import { Knob, Select, Meter } from "@vsreact/core/components";
+//
+// Identical exports to the root — this subpath exists for readability
+// 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 { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
+export { Button } from "./button";
+export { Tooltip, Modal } from "./popover";

package/dist/hooks.d.ts

@@ -22,3 +22,21 @@ export declare function useNativeEvent(name: string, handler: (payload: any) =>
  *   useEffect(() => { native.call("library:search", { query }); }, [query]);
  */
 export declare function useDebounced<T>(value: T, delayMs: number): T;
+/** The value, updated at most once per `intervalMs` (leading + trailing). */
+export declare function useThrottled<T>(value: T, intervalMs: number): T;
+/** The value from the previous render — undefined on the first one. */
+export declare function usePrevious<T>(value: T): T | undefined;
+/** Boolean state with a stable toggle — bypass buttons, panels, A/B. */
+export declare function useToggle(initial?: boolean): [boolean, () => void, (next: boolean) => void];
+/** A declarative interval on the host scheduler; null pauses it. The
+    callback stays fresh without restarting the timer. */
+export declare function useInterval(callback: () => void, intervalMs: number | null): void;
+/** Hover state + the props that drive it:
+    `const [hovered, hoverProps] = useHover(); <View {...hoverProps}>` */
+export declare function useHover(): [
+    boolean,
+    {
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    }
+];

package/dist/hooks.js

@@ -38,3 +38,59 @@ export function useDebounced(value, delayMs) {
     }, [value, delayMs]);
     return debounced;
 }
+/** The value, updated at most once per `intervalMs` (leading + trailing). */
+export function useThrottled(value, intervalMs) {
+    const [throttled, setThrottled] = useState(value);
+    const lastRun = useRef(0);
+    useEffect(() => {
+        const now = Date.now();
+        const elapsed = now - lastRun.current;
+        if (elapsed >= intervalMs) {
+            lastRun.current = now;
+            setThrottled(value);
+            return;
+        }
+        const id = setTimeout(() => {
+            lastRun.current = Date.now();
+            setThrottled(value);
+        }, intervalMs - elapsed);
+        return () => clearTimeout(id);
+    }, [value, intervalMs]);
+    return throttled;
+}
+/** The value from the previous render — undefined on the first one. */
+export function usePrevious(value) {
+    const previous = useRef(undefined);
+    useEffect(() => {
+        previous.current = value;
+    }, [value]);
+    return previous.current;
+}
+/** Boolean state with a stable toggle — bypass buttons, panels, A/B. */
+export function useToggle(initial = false) {
+    const [on, setOn] = useState(initial);
+    const toggle = useRef(() => setOn((v) => !v)).current;
+    return [on, toggle, setOn];
+}
+/** A declarative interval on the host scheduler; null pauses it. The
+    callback stays fresh without restarting the timer. */
+export function useInterval(callback, intervalMs) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        if (intervalMs === null)
+            return;
+        const id = setInterval(() => callbackRef.current(), intervalMs);
+        return () => clearInterval(id);
+    }, [intervalMs]);
+}
+/** Hover state + the props that drive it:
+    `const [hovered, hoverProps] = useHover(); <View {...hoverProps}>` */
+export function useHover() {
+    const [hovered, setHovered] = useState(false);
+    const props = useRef({
+        onMouseEnter: () => setHovered(true),
+        onMouseLeave: () => setHovered(false),
+    }).current;
+    return [hovered, props];
+}

package/dist/index.d.ts

@@ -4,10 +4,14 @@ 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, useLayoutRect } from "./hooks";
+export { useNativeEvent, useDebounced, useThrottled, usePrevious, useToggle, useInterval, useHover, useLayoutRect, } from "./hooks";
 export { useOverlay, OverlayLayer } from "./overlay";
 export { Tooltip, Modal } from "./popover";
 export type { TooltipProps, ModalProps } from "./popover";
+export { Button } from "./button";
+export type { ButtonProps } from "./button";
+export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
+export type { BarsProps, WaveformProps } from "./visualizers";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";

package/dist/index.js

@@ -5,9 +5,11 @@ import "./bridge";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
-export { useNativeEvent, useDebounced, useLayoutRect } from "./hooks";
+export { useNativeEvent, useDebounced, useThrottled, usePrevious, useToggle, useInterval, useHover, useLayoutRect, } from "./hooks";
 export { useOverlay, OverlayLayer } from "./overlay";
 export { Tooltip, Modal } from "./popover";
+export { Button } from "./button";
+export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
 export { configureTheme, tw } from "./tw";
 export { cx } from "./cx";
 export { useTween, useSpring, springStep, lerp, Easing } from "./animation";

package/dist/visualizers.d.ts

@@ -0,0 +1,37 @@
+/** Pure rolling-window step (exported for tests): drop the oldest, push
+    the newest, pad with zeros to `length`. */
+export declare function pushRolling(previous: number[], value: number, length: number): number[];
+/** A rolling window of the last `length` values — turns a live scalar
+    (meter level, envelope) into data for <Waveform>/<Bars> history. */
+export declare function useRollingBuffer(value: number, length?: number): number[];
+export interface BarsProps {
+    /** One bar per entry, 0..1. */
+    values: number[];
+    width?: number;
+    height?: number;
+    /** Gap between bars. Default 2. */
+    gap?: number;
+    /** Bars at or above this turn hot. Default 0.85; 1 disables. */
+    hotFrom?: number;
+    trackColor?: string;
+    color?: string;
+    hotColor?: string;
+    label?: string;
+}
+/** Bottom-anchored bars — spectrum analyzers, band meters. */
+export declare function Bars({ values, width, height, gap, hotFrom, trackColor, color, hotColor, label, }: BarsProps): import("react").JSX.Element;
+export interface WaveformProps {
+    /** One bar per entry, −1..1 (or 0..1 — bars mirror around the centre). */
+    values: number[];
+    width?: number;
+    height?: number;
+    gap?: number;
+    trackColor?: string;
+    color?: string;
+    /** Draw the centre line. Default true. */
+    centerLine?: boolean;
+    centerLineColor?: string;
+    label?: string;
+}
+/** Centre-mirrored bars — waveform overviews, envelope history. */
+export declare function Waveform({ values, width, height, gap, trackColor, color, centerLine, centerLineColor, label, }: WaveformProps): import("react").JSX.Element;

package/dist/visualizers.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Audio visualizers — bar-based displays fed by arrays of values
+// (typically pushed from C++ via useNativeEvent). For audio-rate scopes,
+// host a juce::Component with <NativeView>; these cover the JS-rate
+// cases: spectrum bars, envelope history, waveform overviews.
+import { useEffect, useState } from "react";
+import { View, Text } from "./primitives";
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/** Pure rolling-window step (exported for tests): drop the oldest, push
+    the newest, pad with zeros to `length`. */
+export function pushRolling(previous, value, length) {
+    const next = previous.slice(Math.max(0, previous.length - length + 1));
+    next.push(value);
+    while (next.length < length)
+        next.unshift(0);
+    return next;
+}
+/** A rolling window of the last `length` values — turns a live scalar
+    (meter level, envelope) into data for <Waveform>/<Bars> history. */
+export function useRollingBuffer(value, length = 64) {
+    const [buffer, setBuffer] = useState(() => Array(length).fill(0));
+    useEffect(() => {
+        setBuffer((previous) => pushRolling(previous, value, length));
+    }, [value, length]);
+    return buffer;
+}
+/** Bottom-anchored bars — spectrum analyzers, band meters. */
+export function Bars({ values, width = 160, height = 60, gap = 2, hotFrom = 0.85, trackColor = "#141714", color = "#C6F135", hotColor = "#FF4545", label, }) {
+    const bars = (_jsx(View, { className: "flex-row items-end rounded overflow-hidden px-[2]", style: { width, height, backgroundColor: trackColor, columnGap: gap }, children: values.map((value, index) => {
+            const level = clamp01(value);
+            return (_jsx(View, { className: "flex-1 rounded-[1]", style: {
+                    height: Math.max(1, level * (height - 4)),
+                    backgroundColor: level >= hotFrom ? hotColor : color,
+                } }, index));
+        }) }));
+    if (label === undefined)
+        return bars;
+    return (_jsxs(View, { className: "items-center gap-2", children: [bars, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
+}
+/** Centre-mirrored bars — waveform overviews, envelope history. */
+export function Waveform({ values, width = 160, height = 60, gap = 2, trackColor = "#141714", color = "#C6F135", centerLine = true, centerLineColor = "#FFFFFF22", label, }) {
+    const wave = (_jsxs(View, { className: "relative flex-row items-center rounded overflow-hidden px-[2]", style: { width, height, backgroundColor: trackColor, columnGap: gap }, children: [centerLine ? (_jsx(View, { className: "absolute left-0 right-0 h-[1]", style: { top: height / 2, backgroundColor: centerLineColor } })) : null, values.map((value, index) => (_jsx(View, { className: "flex-1 rounded-[1]", style: {
+                    height: Math.max(1, Math.min(1, Math.abs(value)) * (height - 4)),
+                    backgroundColor: color,
+                } }, index)))] }));
+    if (label === undefined)
+        return wave;
+    return (_jsxs(View, { className: "items-center gap-2", children: [wave, _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.6",
+  "version": "0.0.8",
   "description": "Write React. Ship native VST. A React renderer for JUCE audio plugins — QuickJS + Yoga + juce::Graphics, no webview.",
   "keywords": [
     "react",
@@ -31,6 +31,12 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "bun": "./src/components.ts",
+      "import": "./dist/components.js",
+      "default": "./dist/components.js"
     }
   },
   "files": [

package/src/button.tsx

@@ -0,0 +1,68 @@
+// Button — the pressable with hover/active states baked in.
+
+import type { ReactNode } from "react";
+import { View, Text } from "./primitives";
+import { cx } from "./cx";
+import type { Style } from "./tw";
+
+export interface ButtonProps {
+  label?: string;
+  children?: ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  /** solid (default) — filled; outline — bordered; ghost — text only. */
+  variant?: "solid" | "outline" | "ghost";
+  size?: "sm" | "md" | "lg";
+  accentColor?: string;
+  /** Text color for the solid variant (default near-black). */
+  textColor?: string;
+}
+
+const SIZES = {
+  sm: { pad: "px-3 py-[5]", text: 11 },
+  md: { pad: "px-4 py-[8]", text: 12 },
+  lg: { pad: "px-5 py-[11]", text: 13 },
+} as const;
+
+/** A pressable with sensible plugin styling — solid/outline/ghost. */
+export function Button({
+  label,
+  children,
+  onClick,
+  disabled,
+  variant = "solid",
+  size = "md",
+  accentColor = "#C6F135",
+  textColor = "#09090b",
+}: ButtonProps) {
+  const { pad, text } = SIZES[size];
+
+  const className = cx(
+    "flex-row items-center justify-center gap-2 rounded-lg",
+    pad,
+    disabled ? "opacity-40" : "cursor-pointer",
+    !disabled && variant === "solid" && "hover:opacity-90 active:opacity-75",
+    !disabled && variant !== "solid" && "hover:bg-white/10 active:bg-white/15",
+    variant === "outline" && "border",
+  );
+
+  const style: Style =
+    variant === "solid"
+      ? { backgroundColor: accentColor }
+      : variant === "outline"
+        ? { borderColor: accentColor }
+        : {};
+
+  const color = variant === "solid" ? textColor : accentColor;
+
+  return (
+    <View className={className} style={style} onClick={disabled ? undefined : onClick}>
+      {label !== undefined ? (
+        <Text className="font-bold tracking-wide" style={{ fontSize: text, color }}>
+          {label}
+        </Text>
+      ) : null}
+      {children}
+    </View>
+  );
+}

package/src/components.ts

@@ -0,0 +1,47 @@
+// The component layer, importable on its own:
+//
+//   import { Knob, Select, Meter } from "@vsreact/core/components";
+//
+// Identical exports to the root — this subpath exists for readability
+// 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 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 { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
+export type { BarsProps, WaveformProps } from "./visualizers";
+export { Button } from "./button";
+export type { ButtonProps } from "./button";
+export { Tooltip, Modal } from "./popover";
+export type { TooltipProps, ModalProps } from "./popover";

package/src/controls.test.tsx

@@ -433,3 +433,112 @@ describe("Tooltip + Modal", () => {
     expect(closed).toEqual([1]);
   });
 });
+
+describe("0.0.7 — Button, visualizers, hooks", () => {
+  test("Button: click fires; disabled renders no listener; variants style", () => {
+    const { Button } = require("./index");
+    const seen: number[] = [];
+    render(<Button label="APPLY" onClick={() => seen.push(1)} accentColor="#FF2E2E" />);
+
+    dispatch({ kind: "event", nodeId: nodeWithListener("click"), type: "click" });
+    expect(seen).toEqual([1]);
+
+    // solid: filled with the accent
+    const solid: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.backgroundColor === "#FF2E2E",
+    );
+    expect(solid).toBeDefined();
+    expect(solid[2].hoverStyle).toBeDefined();
+
+    unmount();
+    batches.length = 0;
+    render(<Button label="X" disabled onClick={() => seen.push(2)} />);
+    expect(opsNamed("setProps").some((op: any) => op[2]?.listeners?.includes("click"))).toBe(false);
+
+    unmount();
+    batches.length = 0;
+    render(<Button label="Y" variant="outline" onClick={() => {}} accentColor="#FF2E2E" />);
+    const outline: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.borderColor === "#FF2E2E",
+    );
+    expect(outline).toBeDefined();
+    expect(outline[2].style.borderWidth).toBe(1);
+  });
+
+  test("Bars: one bar per value, hot bars switch color, heights scale", () => {
+    const { Bars } = require("./index");
+    render(<Bars values={[0.5, 0.9]} height={60} hotFrom={0.85} color="#AAA111" hotColor="#FF0000" />);
+
+    const bars = opsNamed("setProps").filter(
+      (op: any) => op[2]?.style?.backgroundColor === "#AAA111" || op[2]?.style?.backgroundColor === "#FF0000",
+    );
+    expect(bars.length).toBe(2);
+    const cold: any = bars.find((op: any) => op[2].style.backgroundColor === "#AAA111");
+    const hot: any = bars.find((op: any) => op[2].style.backgroundColor === "#FF0000");
+    expect(cold[2].style.height).toBeCloseTo(0.5 * 56);
+    expect(hot[2].style.height).toBeCloseTo(0.9 * 56);
+  });
+
+  test("Waveform: bars mirror around centre with |value| heights", () => {
+    const { Waveform } = require("./index");
+    render(<Waveform values={[-1, 0.5]} height={60} color="#AAA111" centerLine={false} />);
+
+    const bars = opsNamed("setProps")
+      .filter((op: any) => op[2]?.style?.backgroundColor === "#AAA111")
+      .map((op: any) => op[2].style.height);
+    expect(bars).toHaveLength(2);
+    expect(Math.max(...bars)).toBeCloseTo(56);
+    expect(Math.min(...bars)).toBeCloseTo(28);
+  });
+
+  test("pushRolling keeps a fixed window, newest last", () => {
+    const { pushRolling } = require("./index");
+    expect(pushRolling([1, 2, 3], 4, 3)).toEqual([2, 3, 4]);
+    expect(pushRolling([], 7, 3)).toEqual([0, 0, 7]);
+    expect(pushRolling([1, 2, 3, 4, 5], 6, 3)).toEqual([4, 5, 6]);
+  });
+
+  test("useToggle + useHover drive a probe component", () => {
+    const { useToggle, useHover, View: V, Text: T } = require("./index");
+
+    function Probe() {
+      const [on, toggle] = useToggle(false);
+      const [hovered, hoverProps] = useHover();
+      return (
+        <V onClick={toggle} {...hoverProps}>
+          <T>{`${on ? "ON" : "OFF"}:${hovered ? "HOV" : "OUT"}`}</T>
+        </V>
+      );
+    }
+
+    render(<Probe />);
+    const id = nodeWithListener("click");
+
+    dispatch({ kind: "event", nodeId: id, type: "click" });
+    dispatch({ kind: "event", nodeId: id, type: "mouseenter" });
+    expect(allOps().some((op: any) => op[0] === "setText" && op[2] === "ON:HOV")).toBe(true);
+
+    dispatch({ kind: "event", nodeId: id, type: "mouseleave" });
+    expect(allOps().some((op: any) => op[0] === "setText" && op[2] === "ON:OUT")).toBe(true);
+  });
+
+  test("usePrevious reports the last-render value", () => {
+    const { usePrevious, View: V, Text: T } = require("./index");
+    const values: Array<string> = [];
+
+    function Probe({ n }: { n: number }) {
+      const prev = usePrevious(n);
+      values.push(`${prev}->${n}`);
+      return (
+        <V>
+          <T>{n}</T>
+        </V>
+      );
+    }
+
+    render(<Probe n={1} />);
+    render(<Probe n={2} />);
+    expect(values[0]).toBe("undefined->1");
+    expect(values.at(-1)).toBe("1->2");
+  });
+});

package/src/hooks.ts

@@ -46,3 +46,74 @@ export function useDebounced<T>(value: T, delayMs: number): T {
 
   return debounced;
 }
+
+/** The value, updated at most once per `intervalMs` (leading + trailing). */
+export function useThrottled<T>(value: T, intervalMs: number): T {
+  const [throttled, setThrottled] = useState(value);
+  const lastRun = useRef(0);
+
+  useEffect(() => {
+    const now = Date.now();
+    const elapsed = now - lastRun.current;
+
+    if (elapsed >= intervalMs) {
+      lastRun.current = now;
+      setThrottled(value);
+      return;
+    }
+
+    const id = setTimeout(() => {
+      lastRun.current = Date.now();
+      setThrottled(value);
+    }, intervalMs - elapsed);
+    return () => clearTimeout(id);
+  }, [value, intervalMs]);
+
+  return throttled;
+}
+
+/** The value from the previous render — undefined on the first one. */
+export function usePrevious<T>(value: T): T | undefined {
+  const previous = useRef<T | undefined>(undefined);
+
+  useEffect(() => {
+    previous.current = value;
+  }, [value]);
+
+  return previous.current;
+}
+
+/** Boolean state with a stable toggle — bypass buttons, panels, A/B. */
+export function useToggle(initial = false): [boolean, () => void, (next: boolean) => void] {
+  const [on, setOn] = useState(initial);
+  const toggle = useRef(() => setOn((v) => !v)).current;
+  return [on, toggle, setOn];
+}
+
+/** A declarative interval on the host scheduler; null pauses it. The
+    callback stays fresh without restarting the timer. */
+export function useInterval(callback: () => void, intervalMs: number | null): void {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (intervalMs === null) return;
+    const id = setInterval(() => callbackRef.current(), intervalMs);
+    return () => clearInterval(id);
+  }, [intervalMs]);
+}
+
+/** Hover state + the props that drive it:
+    `const [hovered, hoverProps] = useHover(); <View {...hoverProps}>` */
+export function useHover(): [
+  boolean,
+  { onMouseEnter: () => void; onMouseLeave: () => void },
+] {
+  const [hovered, setHovered] = useState(false);
+  const props = useRef({
+    onMouseEnter: () => setHovered(true),
+    onMouseLeave: () => setHovered(false),
+  }).current;
+
+  return [hovered, props];
+}

package/src/index.ts

@@ -13,10 +13,23 @@ export type {
 } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
-export { useNativeEvent, useDebounced, useLayoutRect } from "./hooks";
+export {
+  useNativeEvent,
+  useDebounced,
+  useThrottled,
+  usePrevious,
+  useToggle,
+  useInterval,
+  useHover,
+  useLayoutRect,
+} from "./hooks";
 export { useOverlay, OverlayLayer } from "./overlay";
 export { Tooltip, Modal } from "./popover";
 export type { TooltipProps, ModalProps } from "./popover";
+export { Button } from "./button";
+export type { ButtonProps } from "./button";
+export { Bars, Waveform, useRollingBuffer, pushRolling } from "./visualizers";
+export type { BarsProps, WaveformProps } from "./visualizers";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";

package/src/visualizers.tsx

@@ -0,0 +1,148 @@
+// Audio visualizers — bar-based displays fed by arrays of values
+// (typically pushed from C++ via useNativeEvent). For audio-rate scopes,
+// host a juce::Component with <NativeView>; these cover the JS-rate
+// cases: spectrum bars, envelope history, waveform overviews.
+
+import { useEffect, useState } from "react";
+import { View, Text } from "./primitives";
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
+
+/** Pure rolling-window step (exported for tests): drop the oldest, push
+    the newest, pad with zeros to `length`. */
+export function pushRolling(previous: number[], value: number, length: number): number[] {
+  const next = previous.slice(Math.max(0, previous.length - length + 1));
+  next.push(value);
+  while (next.length < length) next.unshift(0);
+  return next;
+}
+
+/** A rolling window of the last `length` values — turns a live scalar
+    (meter level, envelope) into data for <Waveform>/<Bars> history. */
+export function useRollingBuffer(value: number, length = 64): number[] {
+  const [buffer, setBuffer] = useState<number[]>(() => Array(length).fill(0));
+
+  useEffect(() => {
+    setBuffer((previous) => pushRolling(previous, value, length));
+  }, [value, length]);
+
+  return buffer;
+}
+
+export interface BarsProps {
+  /** One bar per entry, 0..1. */
+  values: number[];
+  width?: number;
+  height?: number;
+  /** Gap between bars. Default 2. */
+  gap?: number;
+  /** Bars at or above this turn hot. Default 0.85; 1 disables. */
+  hotFrom?: number;
+  trackColor?: string;
+  color?: string;
+  hotColor?: string;
+  label?: string;
+}
+
+/** Bottom-anchored bars — spectrum analyzers, band meters. */
+export function Bars({
+  values,
+  width = 160,
+  height = 60,
+  gap = 2,
+  hotFrom = 0.85,
+  trackColor = "#141714",
+  color = "#C6F135",
+  hotColor = "#FF4545",
+  label,
+}: BarsProps) {
+  const bars = (
+    <View
+      className="flex-row items-end rounded overflow-hidden px-[2]"
+      style={{ width, height, backgroundColor: trackColor, columnGap: gap }}
+    >
+      {values.map((value, index) => {
+        const level = clamp01(value);
+        return (
+          <View
+            key={index}
+            className="flex-1 rounded-[1]"
+            style={{
+              height: Math.max(1, level * (height - 4)),
+              backgroundColor: level >= hotFrom ? hotColor : color,
+            }}
+          />
+        );
+      })}
+    </View>
+  );
+
+  if (label === undefined) return bars;
+
+  return (
+    <View className="items-center gap-2">
+      {bars}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}
+
+export interface WaveformProps {
+  /** One bar per entry, −1..1 (or 0..1 — bars mirror around the centre). */
+  values: number[];
+  width?: number;
+  height?: number;
+  gap?: number;
+  trackColor?: string;
+  color?: string;
+  /** Draw the centre line. Default true. */
+  centerLine?: boolean;
+  centerLineColor?: string;
+  label?: string;
+}
+
+/** Centre-mirrored bars — waveform overviews, envelope history. */
+export function Waveform({
+  values,
+  width = 160,
+  height = 60,
+  gap = 2,
+  trackColor = "#141714",
+  color = "#C6F135",
+  centerLine = true,
+  centerLineColor = "#FFFFFF22",
+  label,
+}: WaveformProps) {
+  const wave = (
+    <View
+      className="relative flex-row items-center rounded overflow-hidden px-[2]"
+      style={{ width, height, backgroundColor: trackColor, columnGap: gap }}
+    >
+      {centerLine ? (
+        <View
+          className="absolute left-0 right-0 h-[1]"
+          style={{ top: height / 2, backgroundColor: centerLineColor }}
+        />
+      ) : null}
+      {values.map((value, index) => (
+        <View
+          key={index}
+          className="flex-1 rounded-[1]"
+          style={{
+            height: Math.max(1, Math.min(1, Math.abs(value)) * (height - 4)),
+            backgroundColor: color,
+          }}
+        />
+      ))}
+    </View>
+  );
+
+  if (label === undefined) return wave;
+
+  return (
+    <View className="items-center gap-2">
+      {wave}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}