@vsreact/core 0.0.4 → 0.0.6

package/dist/controls.d.ts

@@ -6,22 +6,32 @@ export interface KnobProps {
     label?: string;
     size?: number;
     disabled?: boolean;
+    /** Double-click resets to this (DAW convention). */
+    defaultValue?: number;
+    /** Value arc sweeps from 12 o'clock instead of the left stop — for
+        centre-based parameters like pan. */
+    bipolar?: boolean;
+    /** Value change per wheel notch fraction. 0 disables. Default 0.4. */
+    wheelSensitivity?: number;
     trackColor?: string;
     valueColor?: string;
     onChange: (value: number) => void;
     onBegin?: () => void;
     onEnd?: () => void;
 }
-export declare function Knob({ value, text, label, size, disabled, trackColor, valueColor, onChange, onBegin, onEnd, }: KnobProps): import("react").JSX.Element;
+export declare function Knob({ value, text, label, size, disabled, defaultValue, bipolar, wheelSensitivity, trackColor, valueColor, onChange, onBegin, onEnd, }: KnobProps): import("react").JSX.Element;
 export interface ParamKnobProps {
     paramId: string;
     label?: string;
     size?: number;
+    bipolar?: boolean;
+    wheelSensitivity?: number;
     trackColor?: string;
     valueColor?: string;
 }
-/** A Knob bound to an APVTS parameter (via ParameterBridge). */
-export declare function ParamKnob({ paramId, label, size, trackColor, valueColor }: ParamKnobProps): import("react").JSX.Element;
+/** A Knob bound to an APVTS parameter — double-click resets to the
+    host's default, the wheel nudges, gestures stay automation-safe. */
+export declare function ParamKnob({ paramId, label, ...rest }: ParamKnobProps): import("react").JSX.Element;
 export interface SliderProps {
     value: number;
     /** Track length when horizontal (default 160). */
@@ -32,22 +42,28 @@ export interface SliderProps {
     vertical?: boolean;
     label?: string;
     disabled?: boolean;
+    /** Double-click resets to this (DAW convention). */
+    defaultValue?: number;
+    /** Value change per wheel notch fraction. 0 disables. Default 0.4. */
+    wheelSensitivity?: number;
     trackColor?: string;
     valueColor?: string;
     onChange: (value: number) => void;
     onBegin?: () => void;
     onEnd?: () => void;
 }
-export declare function Slider({ value, width, height, vertical, label, disabled, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
+export declare function Slider({ value, width, height, vertical, label, disabled, defaultValue, wheelSensitivity, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
 export interface ParamSliderProps {
     paramId: string;
     label?: string;
     width?: number;
     height?: number;
     vertical?: boolean;
+    wheelSensitivity?: number;
 }
-/** A Slider bound to an APVTS parameter (via ParameterBridge). */
-export declare function ParamSlider({ paramId, label, width, height, vertical }: ParamSliderProps): import("react").JSX.Element;
+/** A Slider bound to an APVTS parameter — double-click resets to the
+    host's default, the wheel nudges, gestures stay automation-safe. */
+export declare function ParamSlider({ paramId, label, ...rest }: ParamSliderProps): import("react").JSX.Element;
 export interface ToggleProps {
     on: boolean;
     label?: string;
@@ -135,3 +151,38 @@ export interface GenericEditorProps {
 /** 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;
+export interface SelectProps {
+    options: string[];
+    index: number;
+    /** Trigger width; the menu matches it. Default 160. */
+    width?: number;
+    label?: string;
+    disabled?: boolean;
+    trackColor?: string;
+    menuColor?: string;
+    activeColor?: string;
+    textColor?: string;
+    activeTextColor?: string;
+    /** Menu scrolls beyond this height. Default 190. */
+    maxMenuHeight?: number;
+    onChange: (index: number) => void;
+}
+/** A dropdown: the menu renders in the overlay layer, positioned under
+    the trigger via onLayout, with a click-away backdrop and a scrolling
+    option list. */
+export declare function Select({ options, index, width, label, disabled, trackColor, menuColor, activeColor, textColor, activeTextColor, maxMenuHeight, onChange, }: SelectProps): import("react").JSX.Element;
+export interface ParamSelectProps {
+    paramId: string;
+    options: string[];
+    width?: number;
+    label?: string;
+    trackColor?: string;
+    menuColor?: string;
+    activeColor?: string;
+    textColor?: string;
+    activeTextColor?: string;
+    maxMenuHeight?: number;
+}
+/** A Select bound to a choice-style APVTS parameter (same value↔index
+    mapping as ParamSegmented). */
+export declare function ParamSelect({ paramId, options, label, ...rest }: ParamSelectProps): import("react").JSX.Element;

package/dist/controls.js

@@ -2,10 +2,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // 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 { useEffect, useRef, useState } from "react";
 import { View, Text } from "./primitives";
 import { useParameter, useParameterList } from "./parameters";
 import { useSpring } from "./animation";
+import { useLayoutRect } from "./hooks";
+import { useOverlay } from "./overlay";
 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) {
@@ -13,8 +15,16 @@ export function dragToValue(startValue, dy, sensitivity = 0.005) {
 }
 const ARC_START = -135;
 const ARC_END = 135;
-export function Knob({ value, text, label, size = 64, disabled, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
+export function Knob({ value, text, label, size = 64, disabled, defaultValue, bipolar, wheelSensitivity = 0.4, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
     const startValue = useRef(0);
+    const clamped = clamp01(value);
+    const angle = ARC_START + (ARC_END - ARC_START) * clamped;
+    const center = (ARC_START + ARC_END) / 2;
+    const nudge = (target) => {
+        onBegin?.();
+        onChange(clamp01(target));
+        onEnd?.();
+    };
     return (_jsxs(View, { className: "items-center gap-2", children: [_jsx(View, { className: `items-center justify-center ${disabled ? "opacity-40" : "cursor-pointer"}`, style: {
                     width: size,
                     height: size,
@@ -22,21 +32,25 @@ export function Knob({ value, text, label, size = 64, disabled, trackColor = "#2
                     arcColor: valueColor,
                     arcStart: ARC_START,
                     arcEnd: ARC_END,
-                    arcValueEnd: ARC_START + (ARC_END - ARC_START) * Math.min(1, Math.max(0, value)),
+                    arcValueStart: bipolar ? Math.min(center, angle) : ARC_START,
+                    arcValueEnd: bipolar ? Math.max(center, angle) : angle,
                     arcThickness: Math.max(3, size * 0.08),
                 }, onDragStart: disabled
                     ? undefined
                     : () => {
-                        startValue.current = value;
+                        startValue.current = clamped;
                         onBegin?.();
-                    }, onDrag: disabled ? undefined : (e) => onChange(dragToValue(startValue.current, e.dy)), onDragEnd: disabled ? undefined : () => onEnd?.(), children: text !== undefined ? (_jsx(Text, { className: "text-text font-bold text-center", style: { fontSize: Math.max(10, size * 0.16) }, children: text })) : null }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+                    }, onDrag: disabled ? undefined : (e) => onChange(dragToValue(startValue.current, e.dy)), onDragEnd: disabled ? undefined : () => onEnd?.(), onDoubleClick: disabled || defaultValue === undefined ? undefined : () => nudge(defaultValue), onWheel: disabled || wheelSensitivity === 0
+                    ? undefined
+                    : (e) => nudge(clamped + e.dy * wheelSensitivity), children: text !== undefined ? (_jsx(Text, { className: "text-text font-bold text-center", style: { fontSize: Math.max(10, size * 0.16) }, children: text })) : null }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
 }
-/** A Knob bound to an APVTS parameter (via ParameterBridge). */
-export function ParamKnob({ paramId, label, size, trackColor, valueColor }) {
+/** A Knob bound to an APVTS parameter — double-click resets to the
+    host's default, the wheel nudges, gestures stay automation-safe. */
+export function ParamKnob({ paramId, label, ...rest }) {
     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 }));
+    return (_jsx(Knob, { value: param.value, text: param.text, label: label ?? param.name.toUpperCase(), defaultValue: param.defaultValue, onChange: param.set, onBegin: param.begin, onEnd: param.end, ...rest }));
 }
-export function Slider({ value, width = 160, height = 160, vertical, label, disabled, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
+export function Slider({ value, width = 160, height = 160, vertical, label, disabled, defaultValue, wheelSensitivity = 0.4, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
     const startValue = useRef(0);
     const clamped = clamp01(value);
     const onDragStart = disabled
@@ -46,15 +60,25 @@ export function Slider({ value, width = 160, height = 160, vertical, label, disa
             onBegin?.();
         };
     const onDragEnd = disabled ? undefined : () => onEnd?.();
+    const nudge = (target) => {
+        onBegin?.();
+        onChange(clamp01(target));
+        onEnd?.();
+    };
+    const onDoubleClick = disabled || defaultValue === undefined ? undefined : () => nudge(defaultValue);
+    const onWheel = disabled || wheelSensitivity === 0
+        ? undefined
+        : (e) => nudge(clamped + e.dy * wheelSensitivity);
     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: "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, onDoubleClick: onDoubleClick, onWheel: onWheel, 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] }));
+    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, onDoubleClick: onDoubleClick, onWheel: onWheel, 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 }) {
+/** A Slider bound to an APVTS parameter — double-click resets to the
+    host's default, the wheel nudges, gestures stay automation-safe. */
+export function ParamSlider({ paramId, label, ...rest }) {
     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 }));
+    return (_jsx(Slider, { value: param.value, label: label ?? param.name.toUpperCase(), defaultValue: param.defaultValue, onChange: param.set, onBegin: param.begin, onEnd: param.end, ...rest }));
 }
 /** 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, }) {
@@ -137,3 +161,44 @@ export function GenericEditor({ columns = 4, size = 72, trackColor, valueColor }
         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))) }));
 }
+const SELECT_ROW_HEIGHT = 30;
+/** A dropdown: the menu renders in the overlay layer, positioned under
+    the trigger via onLayout, with a click-away backdrop and a scrolling
+    option list. */
+export function Select({ options, index, width = 160, label, disabled, trackColor = "#2A2F27", menuColor = "#20241F", activeColor = "#C6F135", textColor = "#d4d4d8", activeTextColor = "#09090b", maxMenuHeight = 190, onChange, }) {
+    const [open, setOpen] = useState(false);
+    const [rect, onLayout] = useLayoutRect();
+    const overlay = useOverlay();
+    const current = Math.min(options.length - 1, Math.max(0, index));
+    useEffect(() => {
+        if (!open || rect === null) {
+            overlay.hide();
+            return;
+        }
+        const menuHeight = Math.min(options.length * SELECT_ROW_HEIGHT + 8, maxMenuHeight);
+        overlay.show(_jsx(View, { className: "absolute inset-0", onClick: () => setOpen(false), children: _jsx(View, { className: "absolute rounded-lg border shadow-lg overflow-hidden", style: {
+                    left: rect.x,
+                    top: rect.y + rect.height + 4,
+                    width: rect.width,
+                    backgroundColor: menuColor,
+                    borderColor: "#00000066",
+                }, children: _jsx(View, { className: "overflow-y-scroll p-[4] gap-[2]", style: { height: menuHeight }, children: options.map((option, i) => (_jsx(View, { className: "px-3 py-[6] rounded cursor-pointer hover:bg-white/10", style: { backgroundColor: i === current ? activeColor : "#00000000" }, onClick: () => {
+                            onChange(i);
+                            setOpen(false);
+                        }, children: _jsx(Text, { className: "text-[12] font-medium", style: { color: i === current ? activeTextColor : textColor }, children: option }) }, `${option}-${i}`))) }) }) }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, rect, options, current, menuColor, activeColor, textColor, activeTextColor, maxMenuHeight]);
+    return (_jsxs(View, { className: "items-center gap-2", children: [_jsxs(View, { className: `flex-row items-center justify-between rounded-lg border px-3 py-[8] ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width, backgroundColor: trackColor, borderColor: "#00000055" }, onLayout: onLayout, onClick: disabled ? undefined : () => setOpen((v) => !v), children: [_jsx(Text, { className: "text-[12] font-medium", style: { color: textColor }, children: options[current] ?? "" }), _jsx(Text, { className: "text-[9]", style: { color: textColor, opacity: 0.7 }, children: open ? "▲" : "▼" })] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+}
+/** A Select bound to a choice-style APVTS parameter (same value↔index
+    mapping as ParamSegmented). */
+export function ParamSelect({ paramId, options, label, ...rest }) {
+    const param = useParameter(paramId);
+    const count = Math.max(1, options.length);
+    const index = Math.round(param.value * (count - 1));
+    return (_jsx(Select, { options: options, index: index, label: label ?? param.name.toUpperCase(), onChange: (i) => {
+            param.begin();
+            param.set(count <= 1 ? 0 : i / (count - 1));
+            param.end();
+        }, ...rest }));
+}

package/dist/hooks.d.ts

@@ -1,3 +1,11 @@
+import type { LayoutRect } from "./primitives";
+/**
+ * Captures a node's root-space rect from its onLayout prop:
+ *
+ *   const [rect, onLayout] = useLayoutRect();
+ *   <View onLayout={onLayout} />   // rect updates whenever layout moves it
+ */
+export declare function useLayoutRect(): [LayoutRect | null, (rect: LayoutRect) => void];
 /**
  * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
  * of the component. The handler can close over fresh state — it is kept

package/dist/hooks.js

@@ -1,6 +1,16 @@
 // Convenience hooks over the native bridge.
 import { useEffect, useRef, useState } from "react";
 import { native } from "./native";
+/**
+ * Captures a node's root-space rect from its onLayout prop:
+ *
+ *   const [rect, onLayout] = useLayoutRect();
+ *   <View onLayout={onLayout} />   // rect updates whenever layout moves it
+ */
+export function useLayoutRect() {
+    const [rect, setRect] = useState(null);
+    return [rect, setRect];
+}
 /**
  * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
  * of the component. The handler can close over fresh state — it is kept

package/dist/hostConfig.js

@@ -13,6 +13,8 @@ const hostTypes = {
 };
 const eventPropNames = {
     onClick: "click",
+    onDoubleClick: "dblclick",
+    onWheel: "wheel",
     onMouseEnter: "mouseenter",
     onMouseLeave: "mouseleave",
     onMouseDown: "mousedown",
@@ -20,6 +22,7 @@ const eventPropNames = {
     onDragStart: "dragstart",
     onDrag: "drag",
     onDragEnd: "dragend",
+    onLayout: "layout",
     onChange: "change",
     onSubmit: "submit",
     onFocus: "focus",

package/dist/index.d.ts

@@ -4,7 +4,10 @@ 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 { useNativeEvent, useDebounced, useLayoutRect } from "./hooks";
+export { useOverlay, OverlayLayer } from "./overlay";
+export { Tooltip, Modal } from "./popover";
+export type { TooltipProps, ModalProps } from "./popover";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";
@@ -13,8 +16,8 @@ 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 { 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 type { DragEventPayload } from "./primitives";
+export type { DragEventPayload, LayoutRect, WheelEventPayload } from "./primitives";

package/dist/index.js

@@ -5,10 +5,12 @@ 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 { useNativeEvent, useDebounced, useLayoutRect } from "./hooks";
+export { useOverlay, OverlayLayer } from "./overlay";
+export { Tooltip, Modal } from "./popover";
 export { configureTheme, tw } from "./tw";
 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 { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKnob, ParamSlider, ParamToggle, ParamXYPad, ParamSegmented, ParamSelect, dragToValue, } from "./controls";
 export { Meter, usePeakHold, peakHoldStep } from "./meter";

package/dist/overlay.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+/** A per-component slot in the overlay layer. show() replaces the slot's
+    content; hide() removes it; unmounting cleans up automatically. */
+export declare function useOverlay(): {
+    show: (node: ReactNode) => void;
+    hide: () => void;
+};
+/** Mounted automatically by render() as the last sibling of your app. */
+export declare function OverlayLayer(): import("react").JSX.Element;

package/dist/overlay.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// The overlay layer — content that paints above everything else (menus,
+// tooltips, modals). render() mounts <OverlayLayer/> after your app
+// automatically, so painting order puts overlays on top and hit-testing
+// reaches them first. Position entries absolutely using rects from
+// onLayout / useLayoutRect.
+import { Fragment, useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+let entries = [];
+const subscribers = new Set();
+let nextOverlayKey = 1;
+function emit() {
+    for (const subscriber of subscribers)
+        subscriber();
+}
+function setEntry(key, node) {
+    entries = [...entries.filter((e) => e.key !== key), { key, node }];
+    emit();
+}
+function clearEntry(key) {
+    if (!entries.some((e) => e.key === key))
+        return;
+    entries = entries.filter((e) => e.key !== key);
+    emit();
+}
+/** A per-component slot in the overlay layer. show() replaces the slot's
+    content; hide() removes it; unmounting cleans up automatically. */
+export function useOverlay() {
+    const key = useRef(0);
+    if (key.current === 0)
+        key.current = nextOverlayKey++;
+    useEffect(() => {
+        const k = key.current;
+        return () => clearEntry(k);
+    }, []);
+    return {
+        show: useCallback((node) => setEntry(key.current, node), []),
+        hide: useCallback(() => clearEntry(key.current), []),
+    };
+}
+/** Mounted automatically by render() as the last sibling of your app. */
+export function OverlayLayer() {
+    const list = useSyncExternalStore((onStoreChange) => {
+        subscribers.add(onStoreChange);
+        return () => subscribers.delete(onStoreChange);
+    }, () => entries);
+    return (_jsx(_Fragment, { children: list.map((entry) => (_jsx(Fragment, { children: entry.node }, entry.key))) }));
+}

package/dist/parameters.d.ts

@@ -3,6 +3,8 @@ export interface ParameterState {
     text: string;
     name: string;
     label: string;
+    /** The host's normalized default — double-click-reset target. */
+    defaultValue: number;
 }
 export interface ParameterHandle extends ParameterState {
     set: (normalized: number) => void;
@@ -16,6 +18,7 @@ export interface ParameterInfo {
     /** Normalized 0..1 snapshot at mount — use useParameter(id) for live values. */
     value: number;
     text: string;
+    defaultValue: number;
 }
 /**
  * Enumerates every APVTS parameter (via param:list) once at mount — the

package/dist/parameters.js

@@ -18,6 +18,7 @@ export function useParameterList() {
             label: String(entry?.label ?? ""),
             value: Number(entry?.value ?? 0),
             text: String(entry?.text ?? ""),
+            defaultValue: Number(entry?.defaultValue ?? 0),
         }));
     });
     return list;
@@ -31,8 +32,9 @@ export function useParameter(id) {
                 text: String(initial.text ?? ""),
                 name: String(initial.name ?? id),
                 label: String(initial.label ?? ""),
+                defaultValue: Number(initial.defaultValue ?? 0),
             }
-            : { value: 0, text: "", name: id, label: "" };
+            : { value: 0, text: "", name: id, label: "", defaultValue: 0 };
     });
     useEffect(() => native.on("param", (p) => {
         if (p?.id === id)

package/dist/popover.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+export interface TooltipProps {
+    /** The tip text. */
+    label: string;
+    /** Hover dwell before showing. Default 450ms. */
+    delayMs?: number;
+    /** Gap between the child and the tip. Default 6. */
+    offset?: number;
+    backgroundColor?: string;
+    color?: string;
+    children: ReactNode;
+}
+/** Wraps its child; hovering it long enough shows a tip below. */
+export declare function Tooltip({ label, delayMs, offset, backgroundColor, color, children, }: TooltipProps): import("react").JSX.Element;
+export interface ModalProps {
+    open: boolean;
+    /** Backdrop click (and nothing else) calls this. */
+    onClose: () => void;
+    title?: string;
+    width?: number;
+    backgroundColor?: string;
+    backdropColor?: string;
+    children: ReactNode;
+}
+/** A centered dialog over a click-away backdrop — confirms, settings,
+    about boxes. Content is yours; the chrome is minimal. */
+export declare function Modal({ open, onClose, title, width, backgroundColor, backdropColor, children, }: ModalProps): null;

package/dist/popover.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Tooltip + Modal — the dialog kit, built on the overlay layer and
+// onLayout. Both paint above everything via useOverlay.
+import { useEffect, useRef, useState } from "react";
+import { View, Text } from "./primitives";
+import { useLayoutRect } from "./hooks";
+import { useOverlay } from "./overlay";
+/** Wraps its child; hovering it long enough shows a tip below. */
+export function Tooltip({ label, delayMs = 450, offset = 6, backgroundColor = "#20241F", color = "#d4d4d8", children, }) {
+    const [rect, onLayout] = useLayoutRect();
+    const [visible, setVisible] = useState(false);
+    const overlay = useOverlay();
+    const timer = useRef(null);
+    useEffect(() => {
+        if (!visible || rect === null) {
+            overlay.hide();
+            return;
+        }
+        overlay.show(_jsx(View, { className: "absolute rounded-md border px-2 py-[4]", style: {
+                left: rect.x,
+                top: rect.y + rect.height + offset,
+                backgroundColor,
+                borderColor: "#00000066",
+            }, children: _jsx(Text, { className: "text-[11]", style: { color }, children: label }) }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visible, rect, label, offset, backgroundColor, color]);
+    useEffect(() => () => {
+        if (timer.current !== null)
+            clearTimeout(timer.current);
+    }, []);
+    return (_jsx(View, { onLayout: onLayout, onMouseEnter: () => {
+            if (timer.current !== null)
+                clearTimeout(timer.current);
+            timer.current = setTimeout(() => setVisible(true), delayMs);
+        }, onMouseLeave: () => {
+            if (timer.current !== null)
+                clearTimeout(timer.current);
+            timer.current = null;
+            setVisible(false);
+        }, children: children }));
+}
+/** A centered dialog over a click-away backdrop — confirms, settings,
+    about boxes. Content is yours; the chrome is minimal. */
+export function Modal({ open, onClose, title, width = 320, backgroundColor = "#1C201B", backdropColor = "#000000B0", children, }) {
+    const overlay = useOverlay();
+    useEffect(() => {
+        if (!open) {
+            overlay.hide();
+            return;
+        }
+        overlay.show(_jsx(View, { className: "absolute inset-0 items-center justify-center", style: { backgroundColor: backdropColor }, onClick: onClose, children: _jsxs(View, { className: "rounded-xl border p-5 gap-3 shadow-xl", style: { width, backgroundColor, borderColor: "#00000066" }, onClick: () => { }, children: [title !== undefined ? (_jsx(Text, { className: "text-[13] font-bold tracking-wide", children: title })) : null, children] }) }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open, title, width, backgroundColor, backdropColor, children]);
+    return null;
+}

package/dist/primitives.d.ts

@@ -8,6 +8,18 @@ export interface DragEventPayload {
     x: number;
     y: number;
 }
+/** A node's laid-out rect in root coordinates (scroll-adjusted). */
+export interface LayoutRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Mouse-wheel payload. dy is JUCE's notch fraction (~0.1 per notch,
+    positive = wheel up). */
+export interface WheelEventPayload {
+    dy: number;
+}
 export interface CommonProps {
     className?: string;
     style?: Style;
@@ -15,6 +27,9 @@ export interface CommonProps {
     /** Resets the scroll offset of an overflow-y-scroll container. */
     scrollTop?: number;
     onClick?: () => void;
+    onDoubleClick?: () => void;
+    /** Wheel over this node (controls win the wheel over scroll containers). */
+    onWheel?: (e: WheelEventPayload) => void;
     onMouseEnter?: () => void;
     onMouseLeave?: () => void;
     onMouseDown?: () => void;
@@ -22,6 +37,9 @@ export interface CommonProps {
     onDragStart?: (e: DragEventPayload) => void;
     onDrag?: (e: DragEventPayload) => void;
     onDragEnd?: (e: DragEventPayload) => void;
+    /** Fires after layout whenever this node's root-space rect changes —
+        the foundation for popovers, menus, and tooltips. */
+    onLayout?: (rect: LayoutRect) => void;
 }
 export declare function View(props: CommonProps): import("react").ReactElement<CommonProps, string | import("react").JSXElementConstructor<any>>;
 export interface TextProps extends Omit<CommonProps, "children"> {
@@ -55,6 +73,8 @@ export declare function TextInput({ onChange, onSubmit, ...rest }: TextInputProp
     className?: string | undefined;
     scrollTop?: number | undefined;
     onClick?: (() => void) | undefined;
+    onDoubleClick?: (() => void) | undefined;
+    onWheel?: ((e: WheelEventPayload) => void) | undefined;
     onMouseEnter?: (() => void) | undefined;
     onMouseLeave?: (() => void) | undefined;
     onMouseDown?: (() => void) | undefined;
@@ -62,6 +82,7 @@ export declare function TextInput({ onChange, onSubmit, ...rest }: TextInputProp
     onDragStart?: ((e: DragEventPayload) => void) | undefined;
     onDrag?: ((e: DragEventPayload) => void) | undefined;
     onDragEnd?: ((e: DragEventPayload) => void) | undefined;
+    onLayout?: ((rect: LayoutRect) => void) | undefined;
 }, string | import("react").JSXElementConstructor<any>>;
 export interface NativeViewProps extends CommonProps {
     /** Id of a component factory registered in the C++ NativeRegistry. */

package/dist/render.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
-/** Mounts (or re-renders) the app into the plugin window. */
+/** Mounts (or re-renders) the app into the plugin window. The overlay
+    layer (menus, tooltips) mounts after the app so it paints on top. */
 export declare function render(element: ReactNode): void;
 /** Unmounts the current app (used by hot reload teardown). */
 export declare function unmount(): void;

package/dist/render.js

@@ -1,15 +1,18 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import Reconciler from "react-reconciler";
 import { LegacyRoot } from "react-reconciler/constants";
 import { hostConfig } from "./hostConfig";
 import { flushOps } from "./bridge";
+import { OverlayLayer } from "./overlay";
 const reconciler = Reconciler(hostConfig);
 let container = null;
-/** Mounts (or re-renders) the app into the plugin window. */
+/** Mounts (or re-renders) the app into the plugin window. The overlay
+    layer (menus, tooltips) mounts after the app so it paints on top. */
 export function render(element) {
     if (!container) {
         container = reconciler.createContainer({}, LegacyRoot, null, false, null, "vsreact", (error) => console.error("[vsreact] recoverable error:", error), null);
     }
-    reconciler.updateContainer(element, container, null, null);
+    reconciler.updateContainer(_jsxs(_Fragment, { children: [element, _jsx(OverlayLayer, {})] }), container, null, null);
     flushOps();
 }
 /** Unmounts the current app (used by hot reload teardown). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsreact/core",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Write React. Ship native VST. A React renderer for JUCE audio plugins — QuickJS + Yoga + juce::Graphics, no webview.",
   "keywords": [
     "react",
@@ -20,7 +20,7 @@
   "bugs": "https://github.com/N9RecordsTechnologiesIL/VSReacT/issues",
   "repository": {
     "type": "git",
-    "url": "https://github.com/N9RecordsTechnologiesIL/VSReacT.git",
+    "url": "git+https://github.com/N9RecordsTechnologiesIL/VSReacT.git",
     "directory": "vsreact/js"
   },
   "main": "dist/index.js",