@vsreact/core 0.0.4 → 0.0.5

package/dist/controls.d.ts

@@ -135,3 +135,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) {
@@ -137,3 +139,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

@@ -20,6 +20,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,8 @@ 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 { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";
@@ -13,8 +14,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 } from "./primitives";

package/dist/index.js

@@ -5,10 +5,11 @@ 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 { 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/primitives.d.ts

@@ -8,6 +8,13 @@ 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;
+}
 export interface CommonProps {
     className?: string;
     style?: Style;
@@ -22,6 +29,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"> {
@@ -62,6 +72,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.5",
   "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",

package/src/controls.test.tsx

@@ -7,12 +7,13 @@ let paramGetResult: any = { value: 0.5, text: "0.0 dB", name: "Gain", label: "dB
 (globalThis as Record<string, any>).__vsreact_flush = (json: string) => {
   batches.push(JSON.parse(json));
 };
-(globalThis as Record<string, any>).__vsreact_nativeCall = (name: string, argsJson: string) => {
+const defaultNativeCall = (name: string, argsJson: string) => {
   const args = JSON.parse(argsJson);
   nativeCalls.push({ name, args });
   if (name === "param:get") return JSON.stringify(paramGetResult);
   return "null";
 };
+(globalThis as Record<string, any>).__vsreact_nativeCall = defaultNativeCall;
 
 import { render, unmount, Slider, Toggle, XYPad, Segmented, ParamSegmented, ParamToggle } from "./index";
 
@@ -33,6 +34,7 @@ beforeEach(() => {
   batches.length = 0;
   nativeCalls.length = 0;
   paramGetResult = { value: 0.5, text: "0.0 dB", name: "Gain", label: "dB" };
+  (globalThis as Record<string, any>).__vsreact_nativeCall = defaultNativeCall;
 });
 
 describe("vertical Slider", () => {
@@ -191,3 +193,112 @@ describe("Meter", () => {
     expect(hot).toBeUndefined();
   });
 });
+
+describe("onLayout + Select", () => {
+  /** Map child → parent from appendChild ops, to find a row by its text. */
+  const parentMap = () => {
+    const map = new Map<number, number>();
+    for (const op of allOps() as any[])
+      if (op[0] === "appendChild" || op[0] === "insertBefore") map.set(op[2], op[1]);
+    return map;
+  };
+
+  test("onLayout registers a layout listener and receives the rect", () => {
+    const seen: any[] = [];
+    render(<Slider value={0.5} onChange={() => {}} />); // warm-up unrelated tree
+    unmount();
+    batches.length = 0;
+
+    const { View: V } = require("./index");
+    render(<V onLayout={(r: any) => seen.push(r)} className="w-4" />);
+
+    const props: any = opsNamed("setProps").find((op: any) =>
+      op[2]?.listeners?.includes("layout"),
+    );
+    expect(props).toBeDefined();
+
+    dispatch({
+      kind: "event",
+      nodeId: props[1],
+      type: "layout",
+      payload: { x: 5, y: 10, width: 160, height: 32 },
+    });
+    expect(seen).toEqual([{ x: 5, y: 10, width: 160, height: 32 }]);
+  });
+
+  test("Select opens a positioned overlay menu and selects on click", async () => {
+    const { Select } = require("./index");
+    const seen: number[] = [];
+    render(
+      <Select options={["SINE", "SAW", "SQR"]} index={0} width={160} onChange={(i: number) => seen.push(i)} />,
+    );
+    await new Promise((r) => setTimeout(r, 0)); // let effects flush
+
+    // trigger has both layout + click listeners
+    const trigger: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.listeners?.includes("layout") && op[2]?.listeners?.includes("click"),
+    );
+    expect(trigger).toBeDefined();
+
+    // layout arrives, then the click opens the menu
+    dispatch({
+      kind: "event",
+      nodeId: trigger[1],
+      type: "layout",
+      payload: { x: 20, y: 40, width: 160, height: 33 },
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    dispatch({ kind: "event", nodeId: trigger[1], type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    // menu panel positioned under the trigger, same width
+    const panel: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.top === 40 + 33 + 4 && op[2]?.style?.left === 20,
+    );
+    expect(panel).toBeDefined();
+    expect(panel[2].style.width).toBe(160);
+
+    // find the "SAW" row: rawtext -> Text -> row
+    const sawText: any = allOps().find((op: any) => op[0] === "setText" && op[2] === "SAW");
+    expect(sawText).toBeDefined();
+    const parents = parentMap();
+    const rowId = parents.get(parents.get(sawText[1])!)!;
+
+    dispatch({ kind: "event", nodeId: rowId, type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(seen).toEqual([1]);
+    // menu removed after selection
+    expect(allOps().some((op: any) => op[0] === "removeChild")).toBe(true);
+  });
+
+  test("ParamSelect writes a begin/set/end gesture with the index mapping", async () => {
+    paramGetResult = { value: 0, text: "Sine", name: "Shape", label: "" };
+    const { ParamSelect } = require("./index");
+    render(<ParamSelect paramId="shape" options={["SINE", "SAW", "SQR"]} />);
+    await new Promise((r) => setTimeout(r, 0));
+
+    const trigger: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.listeners?.includes("layout") && op[2]?.listeners?.includes("click"),
+    );
+    dispatch({
+      kind: "event",
+      nodeId: trigger[1],
+      type: "layout",
+      payload: { x: 0, y: 0, width: 160, height: 33 },
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    dispatch({ kind: "event", nodeId: trigger[1], type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    const sqrText: any = allOps().find((op: any) => op[0] === "setText" && op[2] === "SQR");
+    const parents = parentMap();
+    const rowId = parents.get(parents.get(sqrText[1])!)!;
+    dispatch({ kind: "event", nodeId: rowId, type: "click" });
+
+    const set = nativeCalls.find((c) => c.name === "param:set");
+    expect(set?.args).toEqual({ id: "shape", value: 1 });
+    expect(nativeCalls.some((c) => c.name === "param:begin")).toBe(true);
+    expect(nativeCalls.some((c) => c.name === "param:end")).toBe(true);
+  });
+});

package/src/controls.tsx

@@ -2,10 +2,12 @@
 // 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: number) => Math.min(1, Math.max(0, v));
 
@@ -564,3 +566,151 @@ export function GenericEditor({ columns = 4, size = 72, trackColor, valueColor }
     </View>
   );
 }
+
+// ── Select ─────────────────────────────────────────────────────────────
+
+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;
+}
+
+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,
+}: SelectProps) {
+  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(
+      <View className="absolute inset-0" onClick={() => setOpen(false)}>
+        <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",
+          }}
+        >
+          <View className="overflow-y-scroll p-[4] gap-[2]" style={{ height: menuHeight }}>
+            {options.map((option, i) => (
+              <View
+                key={`${option}-${i}`}
+                className="px-3 py-[6] rounded cursor-pointer hover:bg-white/10"
+                style={{ backgroundColor: i === current ? activeColor : "#00000000" }}
+                onClick={() => {
+                  onChange(i);
+                  setOpen(false);
+                }}
+              >
+                <Text
+                  className="text-[12] font-medium"
+                  style={{ color: i === current ? activeTextColor : textColor }}
+                >
+                  {option}
+                </Text>
+              </View>
+            ))}
+          </View>
+        </View>
+      </View>,
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, rect, options, current, menuColor, activeColor, textColor, activeTextColor, maxMenuHeight]);
+
+  return (
+    <View className="items-center gap-2">
+      <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)}
+      >
+        <Text className="text-[12] font-medium" style={{ color: textColor }}>
+          {options[current] ?? ""}
+        </Text>
+        <Text className="text-[9]" style={{ color: textColor, opacity: 0.7 }}>
+          {open ? "▲" : "▼"}
+        </Text>
+      </View>
+      {label !== undefined ? (
+        <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+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 function ParamSelect({ paramId, options, label, ...rest }: ParamSelectProps) {
+  const param = useParameter(paramId);
+  const count = Math.max(1, options.length);
+  const index = Math.round(param.value * (count - 1));
+
+  return (
+    <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/src/hooks.ts

@@ -2,6 +2,18 @@
 
 import { useEffect, useRef, useState } from "react";
 import { native } from "./native";
+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 function useLayoutRect(): [LayoutRect | null, (rect: LayoutRect) => void] {
+  const [rect, setRect] = useState<LayoutRect | null>(null);
+  return [rect, setRect];
+}
 
 /**
  * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime

package/src/hostConfig.ts

@@ -31,6 +31,7 @@ const eventPropNames: Record<string, string> = {
   onDragStart: "dragstart",
   onDrag: "drag",
   onDragEnd: "dragend",
+  onLayout: "layout",
   onChange: "change",
   onSubmit: "submit",
   onFocus: "focus",

package/src/index.ts

@@ -13,7 +13,8 @@ export type {
 } 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 { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";
@@ -28,12 +29,14 @@ export {
   Toggle,
   XYPad,
   Segmented,
+  Select,
   GenericEditor,
   ParamKnob,
   ParamSlider,
   ParamToggle,
   ParamXYPad,
   ParamSegmented,
+  ParamSelect,
   dragToValue,
 } from "./controls";
 export type {
@@ -42,13 +45,15 @@ export type {
   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 } from "./primitives";

package/src/overlay.tsx

@@ -0,0 +1,70 @@
+// 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, type ReactNode } from "react";
+
+interface OverlayEntry {
+  key: number;
+  node: ReactNode;
+}
+
+let entries: OverlayEntry[] = [];
+const subscribers = new Set<() => void>();
+let nextOverlayKey = 1;
+
+function emit(): void {
+  for (const subscriber of subscribers) subscriber();
+}
+
+function setEntry(key: number, node: ReactNode): void {
+  entries = [...entries.filter((e) => e.key !== key), { key, node }];
+  emit();
+}
+
+function clearEntry(key: number): void {
+  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(): {
+  show: (node: ReactNode) => void;
+  hide: () => void;
+} {
+  const key = useRef(0);
+  if (key.current === 0) key.current = nextOverlayKey++;
+
+  useEffect(() => {
+    const k = key.current;
+    return () => clearEntry(k);
+  }, []);
+
+  return {
+    show: useCallback((node: ReactNode) => 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 (
+    <>
+      {list.map((entry) => (
+        <Fragment key={entry.key}>{entry.node}</Fragment>
+      ))}
+    </>
+  );
+}

package/src/primitives.tsx

@@ -10,6 +10,14 @@ export interface DragEventPayload {
   y: number;
 }
 
+/** A node's laid-out rect in root coordinates (scroll-adjusted). */
+export interface LayoutRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
 export interface CommonProps {
   className?: string;
   style?: Style;
@@ -24,6 +32,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 function View(props: CommonProps) {

package/src/render.tsx

@@ -3,12 +3,14 @@ import { LegacyRoot } from "react-reconciler/constants";
 import type { ReactNode } from "react";
 import { hostConfig } from "./hostConfig";
 import { flushOps } from "./bridge";
+import { OverlayLayer } from "./overlay";
 
 const reconciler = Reconciler(hostConfig as any);
 
 let container: ReturnType<typeof reconciler.createContainer> | null = 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: ReactNode): void {
   if (!container) {
     container = reconciler.createContainer(
@@ -23,7 +25,15 @@ export function render(element: ReactNode): void {
     );
   }
 
-  reconciler.updateContainer(element, container, null, null);
+  reconciler.updateContainer(
+    <>
+      {element}
+      <OverlayLayer />
+    </>,
+    container,
+    null,
+    null,
+  );
   flushOps();
 }