@vsreact/core 0.0.10 → 0.0.12

package/build.ts

@@ -1,24 +1,24 @@
-// Bundles a VSReacT app entry into a single QuickJS-ready IIFE.
-//   bun run build.ts [entry] [outfile]
-export {};
-
-const entry = process.argv[2] ?? "demo/main.tsx";
-const outfile = process.argv[3] ?? "demo/build/main.js";
-
-const result = await Bun.build({
-  entrypoints: [entry],
-  target: "browser",
-  format: "iife",
-  minify: false,
-  define: {
-    "process.env.NODE_ENV": '"production"',
-  },
-});
-
-if (!result.success) {
-  for (const log of result.logs) console.error(log);
-  process.exit(1);
-}
-
-await Bun.write(outfile, await result.outputs[0].text());
-console.log(`built ${entry} -> ${outfile}`);
+// Bundles a VSReacT app entry into a single QuickJS-ready IIFE.
+//   bun run build.ts [entry] [outfile]
+export {};
+
+const entry = process.argv[2] ?? "demo/main.tsx";
+const outfile = process.argv[3] ?? "demo/build/main.js";
+
+const result = await Bun.build({
+  entrypoints: [entry],
+  target: "browser",
+  format: "iife",
+  minify: false,
+  define: {
+    "process.env.NODE_ENV": '"production"',
+  },
+});
+
+if (!result.success) {
+  for (const log of result.logs) console.error(log);
+  process.exit(1);
+}
+
+await Bun.write(outfile, await result.outputs[0].text());
+console.log(`built ${entry} -> ${outfile}`);

package/dist/components.d.ts

@@ -12,3 +12,9 @@ export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRa
 export type { NumberBoxProps, CheckboxProps, RadioGroupProps, ParamNumberBoxProps, ParamCheckboxProps, ParamRadioGroupProps, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";
 export type { ProgressBarProps, SpinnerProps } from "./feedback";
+export { PianoKeyboard } from "./keyboard";
+export type { PianoKeyboardProps } from "./keyboard";
+export { StepSequencer } from "./sequencer";
+export type { StepSequencerProps } from "./sequencer";
+export { MacroPad, ParamMacroPad, HardwareKnob, ParamHardwareKnob, Crossfader, ParamCrossfader, PulseOrb, } from "./specialty";
+export type { MacroPadProps, ParamMacroPadProps, HardwareKnobProps, ParamHardwareKnobProps, CrossfaderProps, ParamCrossfaderProps, PulseOrbProps, } from "./specialty";

package/dist/components.js

@@ -12,3 +12,6 @@ export { Button } from "./button";
 export { Tooltip, Modal } from "./popover";
 export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRadioGroup, snapToStep, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";
+export { PianoKeyboard } from "./keyboard";
+export { StepSequencer } from "./sequencer";
+export { MacroPad, ParamMacroPad, HardwareKnob, ParamHardwareKnob, Crossfader, ParamCrossfader, PulseOrb, } from "./specialty";

package/dist/controls.d.ts

@@ -40,6 +40,8 @@ export interface SliderProps {
     height?: number;
     /** Vertical fader — drag up for more, fill rises from the bottom. */
     vertical?: boolean;
+    /** Flat hardware-style bar thumb instead of the dot. */
+    barThumb?: boolean;
     label?: string;
     disabled?: boolean;
     /** Double-click resets to this (DAW convention). */
@@ -52,7 +54,7 @@ export interface SliderProps {
     onBegin?: () => void;
     onEnd?: () => void;
 }
-export declare function Slider({ value, width, height, vertical, label, disabled, defaultValue, wheelSensitivity, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
+export declare function Slider({ value, width, height, vertical, barThumb, label, disabled, defaultValue, wheelSensitivity, trackColor, valueColor, onChange, onBegin, onEnd, }: SliderProps): import("react").JSX.Element;
 export interface ParamSliderProps {
     paramId: string;
     label?: string;
@@ -67,6 +69,9 @@ export declare function ParamSlider({ paramId, label, ...rest }: ParamSliderProp
 export interface ToggleProps {
     on: boolean;
     label?: string;
+    /** Side captions, hardware style: <Toggle offLabel="OFF" onLabel="ON" />. */
+    offLabel?: string;
+    onLabel?: string;
     /** Track height; width is 1.8×. Default 22. */
     size?: number;
     disabled?: boolean;
@@ -76,7 +81,7 @@ export interface ToggleProps {
     onChange: (on: boolean) => void;
 }
 /** A switch with a spring-animated thumb — bypass, on/off, A/B. */
-export declare function Toggle({ on, label, size, disabled, trackColor, onColor, thumbColor, onChange, }: ToggleProps): import("react").JSX.Element;
+export declare function Toggle({ on, label, offLabel, onLabel, size, disabled, trackColor, onColor, thumbColor, onChange, }: ToggleProps): import("react").JSX.Element;
 export interface ParamToggleProps {
     paramId: string;
     label?: string;

package/dist/controls.js

@@ -50,7 +50,7 @@ export function ParamKnob({ paramId, label, ...rest }) {
     const param = useParameter(paramId);
     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, defaultValue, wheelSensitivity = 0.4, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
+export function Slider({ value, width = 160, height = 160, vertical, barThumb, label, disabled, defaultValue, wheelSensitivity = 0.4, trackColor = "#2A2F27", valueColor = "#C6F135", onChange, onBegin, onEnd, }) {
     const startValue = useRef(0);
     const clamped = clamp01(value);
     const onDragStart = disabled
@@ -70,9 +70,9 @@ export function Slider({ value, width = 160, height = 160, vertical, label, disa
         ? 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, 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: "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 } }), barThumb ? (_jsx(View, { className: "absolute w-[18] h-[5] rounded-[2] left-0", style: { top: (1 - clamped) * (height - 5), 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, 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] }));
+    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 } }), barThumb ? (_jsx(View, { className: "absolute w-[5] h-[18] rounded-[2] top-0", style: { left: clamped * (width - 5), 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 — double-click resets to the
     host's default, the wheel nudges, gestures stay automation-safe. */
@@ -81,18 +81,18 @@ export function ParamSlider({ paramId, label, ...rest }) {
     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, }) {
+export function Toggle({ on, label, offLabel, onLabel, size = 22, disabled, trackColor = "#2A2F27", onColor = "#C6F135", thumbColor = "#F4F4F5", onChange, }) {
     const t = useSpring(on ? 1 : 0, { stiffness: 300, damping: 28 });
     const trackWidth = Math.round(size * 1.8);
     const thumb = size - 6;
     const travel = trackWidth - thumb - 6;
-    return (_jsxs(View, { className: "items-center gap-2", children: [_jsx(View, { className: `relative rounded-full ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width: trackWidth, height: size, backgroundColor: on ? onColor : trackColor }, onClick: disabled ? undefined : () => onChange(!on), children: _jsx(View, { className: "absolute rounded-full", style: {
-                        width: thumb,
-                        height: thumb,
-                        top: 3,
-                        left: 3 + clamp01(t) * travel,
-                        backgroundColor: thumbColor,
-                    } }) }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
+    return (_jsxs(View, { className: "items-center gap-2", children: [_jsxs(View, { className: "flex-row items-center gap-2", children: [offLabel !== undefined ? (_jsx(Text, { className: "text-[9] font-bold tracking-widest", style: { color: on ? "#6f6e66" : "#ECF2E8" }, children: offLabel })) : null, _jsx(View, { className: `relative rounded-full ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width: trackWidth, height: size, backgroundColor: on ? onColor : trackColor }, onClick: disabled ? undefined : () => onChange(!on), children: _jsx(View, { className: "absolute rounded-full", style: {
+                                width: thumb,
+                                height: thumb,
+                                top: 3,
+                                left: 3 + clamp01(t) * travel,
+                                backgroundColor: thumbColor,
+                            } }) }), onLabel !== undefined ? (_jsx(Text, { className: "text-[9] font-bold tracking-widest", style: { color: on ? "#ECF2E8" : "#6f6e66" }, children: onLabel })) : null] }), label !== undefined ? (_jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })) : null] }));
 }
 /** A Toggle bound to a bool-style APVTS parameter (on = value ≥ 0.5). */
 export function ParamToggle({ paramId, label, ...rest }) {

package/dist/feedback.d.ts

@@ -5,12 +5,15 @@ export interface ProgressBarProps {
     height?: number;
     /** Renders "42%" alongside the bar. Default false. */
     showPercent?: boolean;
+    /** Unknown duration — a segment sweeps the track and `value` is
+        ignored. Default false. */
+    indeterminate?: boolean;
     trackColor?: string;
     color?: string;
     label?: string;
 }
 /** A determinate progress bar — downloads, renders, analysis passes. */
-export declare function ProgressBar({ value, width, height, showPercent, trackColor, color, label, }: ProgressBarProps): import("react").JSX.Element;
+export declare function ProgressBar({ value, width, height, showPercent, indeterminate, trackColor, color, label, }: ProgressBarProps): import("react").JSX.Element;
 export interface SpinnerProps {
     /** Diameter. Default 28. */
     size?: number;

package/dist/feedback.js

@@ -6,9 +6,19 @@ import { View, Text } from "./primitives";
 import { useInterval } from "./hooks";
 const clamp01 = (v) => Math.min(1, Math.max(0, v));
 /** A determinate progress bar — downloads, renders, analysis passes. */
-export function ProgressBar({ value, width = 200, height = 8, showPercent = false, trackColor = "#2A2F27", color = "#C6F135", label, }) {
+export function ProgressBar({ value, width = 200, height = 8, showPercent = false, indeterminate = false, trackColor = "#2A2F27", color = "#C6F135", label, }) {
     const level = clamp01(value);
-    const bar = (_jsxs(View, { className: "flex-row items-center gap-3", children: [_jsx(View, { className: "rounded-full overflow-hidden", style: { width, height, backgroundColor: trackColor }, children: _jsx(View, { className: "rounded-full", style: { width: level * width, height, backgroundColor: color } }) }), showPercent ? (_jsx(Text, { className: "text-faint text-[11] font-bold", style: { width: 34 }, children: `${Math.round(level * 100)}%` })) : null] }));
+    // The indeterminate sweep: a 30%-width segment marching left → right.
+    const [sweep, setSweep] = useState(0);
+    useInterval(() => setSweep((t) => (t + 0.018) % 1), indeterminate ? 16 : null);
+    const segment = width * 0.3;
+    const bar = (_jsxs(View, { className: "flex-row items-center gap-3", children: [_jsx(View, { className: "rounded-full overflow-hidden relative", style: { width, height, backgroundColor: trackColor }, children: indeterminate ? (_jsx(View, { className: "rounded-full absolute", style: {
+                        left: sweep * (width + segment) - segment,
+                        top: 0,
+                        width: segment,
+                        height,
+                        backgroundColor: color,
+                    } })) : (_jsx(View, { className: "rounded-full", style: { width: level * width, height, backgroundColor: color } })) }), showPercent && !indeterminate ? (_jsx(Text, { className: "text-faint text-[11] font-bold", style: { width: 34 }, children: `${Math.round(level * 100)}%` })) : null] }));
     if (label === undefined)
         return bar;
     return (_jsxs(View, { className: "items-center gap-2", children: [bar, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));

package/dist/format.d.ts

@@ -0,0 +1,16 @@
+/** Linear interpolation of `value` from [inMin, inMax] to [outMin, outMax].
+    `clampOut` pins the result inside the output range. */
+export declare function mapRange(value: number, inMin: number, inMax: number, outMin: number, outMax: number, clampOut?: boolean): number;
+/** Decibels with an explicit sign: "+6.0 dB", "0.0 dB", "-12.5 dB".
+    -Infinity (a gain fader on the floor) reads "-inf dB". */
+export declare function formatDb(db: number, decimals?: number): string;
+/** Frequency with automatic kHz: "440 Hz", "1.2 kHz". */
+export declare function formatHz(hz: number, decimals?: number): string;
+/** Time with automatic seconds: "350 ms", "1.25 s". */
+export declare function formatMs(ms: number, decimals?: number): string;
+/** A 0..1 value as "42%". */
+export declare function formatPercent(value01: number, decimals?: number): string;
+/** Semitones with an explicit sign: "+7 st", "0 st", "-12 st". */
+export declare function formatSemitones(semitones: number, decimals?: number): string;
+/** A MIDI note number as scientific pitch: 60 → "C4", 69 → "A4". */
+export declare function midiNoteName(note: number): string;

package/dist/format.js

@@ -0,0 +1,50 @@
+// Value formatting for parameter readouts — the strings DAW users
+// expect next to a knob. Pure functions; pair them with NumberBox's
+// `format` prop or any Text.
+const trim = (value, decimals) => String(parseFloat(value.toFixed(decimals)));
+/** Linear interpolation of `value` from [inMin, inMax] to [outMin, outMax].
+    `clampOut` pins the result inside the output range. */
+export function mapRange(value, inMin, inMax, outMin, outMax, clampOut = false) {
+    const t = inMax === inMin ? 0 : (value - inMin) / (inMax - inMin);
+    const out = outMin + t * (outMax - outMin);
+    if (!clampOut)
+        return out;
+    const lo = Math.min(outMin, outMax);
+    const hi = Math.max(outMin, outMax);
+    return Math.min(hi, Math.max(lo, out));
+}
+/** Decibels with an explicit sign: "+6.0 dB", "0.0 dB", "-12.5 dB".
+    -Infinity (a gain fader on the floor) reads "-inf dB". */
+export function formatDb(db, decimals = 1) {
+    if (db === Number.NEGATIVE_INFINITY)
+        return "-inf dB";
+    const text = db.toFixed(decimals);
+    return `${db > 0 && !text.startsWith("+") ? "+" : ""}${text} dB`;
+}
+/** Frequency with automatic kHz: "440 Hz", "1.2 kHz". */
+export function formatHz(hz, decimals = 1) {
+    if (Math.abs(hz) >= 1000)
+        return `${trim(hz / 1000, Math.max(decimals, 1))} kHz`;
+    return `${trim(hz, decimals)} Hz`;
+}
+/** Time with automatic seconds: "350 ms", "1.25 s". */
+export function formatMs(ms, decimals = 0) {
+    if (Math.abs(ms) >= 1000)
+        return `${trim(ms / 1000, Math.max(decimals, 2))} s`;
+    return `${trim(ms, decimals)} ms`;
+}
+/** A 0..1 value as "42%". */
+export function formatPercent(value01, decimals = 0) {
+    return `${trim(value01 * 100, decimals)}%`;
+}
+/** Semitones with an explicit sign: "+7 st", "0 st", "-12 st". */
+export function formatSemitones(semitones, decimals = 0) {
+    const text = trim(semitones, decimals);
+    return `${semitones > 0 && !text.startsWith("+") ? "+" : ""}${text} st`;
+}
+const NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+/** A MIDI note number as scientific pitch: 60 → "C4", 69 → "A4". */
+export function midiNoteName(note) {
+    const n = Math.round(note);
+    return `${NOTE_NAMES[((n % 12) + 12) % 12]}${Math.floor(n / 12) - 1}`;
+}

package/dist/index.d.ts

@@ -28,4 +28,11 @@ export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRa
 export type { NumberBoxProps, CheckboxProps, RadioGroupProps, ParamNumberBoxProps, ParamCheckboxProps, ParamRadioGroupProps, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";
 export type { ProgressBarProps, SpinnerProps } from "./feedback";
+export { PianoKeyboard } from "./keyboard";
+export type { PianoKeyboardProps } from "./keyboard";
+export { StepSequencer } from "./sequencer";
+export type { StepSequencerProps } from "./sequencer";
+export { mapRange, formatDb, formatHz, formatMs, formatPercent, formatSemitones, midiNoteName, } from "./format";
+export { MacroPad, ParamMacroPad, HardwareKnob, ParamHardwareKnob, Crossfader, ParamCrossfader, PulseOrb, } from "./specialty";
+export type { MacroPadProps, ParamMacroPadProps, HardwareKnobProps, ParamHardwareKnobProps, CrossfaderProps, ParamCrossfaderProps, PulseOrbProps, } from "./specialty";
 export type { DragEventPayload, LayoutRect, WheelEventPayload } from "./primitives";

package/dist/index.js

@@ -18,3 +18,7 @@ export { Knob, Slider, Toggle, XYPad, Segmented, Select, GenericEditor, ParamKno
 export { Meter, usePeakHold, peakHoldStep } from "./meter";
 export { NumberBox, Checkbox, RadioGroup, ParamNumberBox, ParamCheckbox, ParamRadioGroup, snapToStep, } from "./fields";
 export { ProgressBar, Spinner } from "./feedback";
+export { PianoKeyboard } from "./keyboard";
+export { StepSequencer } from "./sequencer";
+export { mapRange, formatDb, formatHz, formatMs, formatPercent, formatSemitones, midiNoteName, } from "./format";
+export { MacroPad, ParamMacroPad, HardwareKnob, ParamHardwareKnob, Crossfader, ParamCrossfader, PulseOrb, } from "./specialty";

package/dist/keyboard.d.ts

@@ -0,0 +1,23 @@
+export interface PianoKeyboardProps {
+    /** MIDI note of the leftmost key (snapped down to a white key).
+        Default 48 (C3). */
+    startNote?: number;
+    /** Whole octaves; the keyboard ends on the top C. Default 2. */
+    octaves?: number;
+    /** Width of one white key. Default 24. */
+    whiteKeyWidth?: number;
+    /** White-key height; blacks are 60% of it. Default 96. */
+    height?: number;
+    /** Externally-held notes (host MIDI in) — painted active. */
+    heldNotes?: number[];
+    /** Prints "C3" on each C. Default true. */
+    showOctaveLabels?: boolean;
+    disabled?: boolean;
+    whiteColor?: string;
+    blackColor?: string;
+    activeColor?: string;
+    borderColor?: string;
+    onNoteOn?: (note: number) => void;
+    onNoteOff?: (note: number) => void;
+}
+export declare function PianoKeyboard({ startNote, octaves, whiteKeyWidth, height, heldNotes, showOctaveLabels, disabled, whiteColor, blackColor, activeColor, borderColor, onNoteOn, onNoteOff, }: PianoKeyboardProps): import("react").JSX.Element;

package/dist/keyboard.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The playable piano keyboard — preview a patch without touching the
+// host. Views only (white row + absolutely-positioned blacks); press
+// for note-on, release for note-off, drag across keys for glissando.
+import { useRef, useState } from "react";
+import { View, Text } from "./primitives";
+import { midiNoteName } from "./format";
+const BLACK_SEMIS = new Set([1, 3, 6, 8, 10]);
+const isBlack = (note) => BLACK_SEMIS.has(((note % 12) + 12) % 12);
+export function PianoKeyboard({ startNote = 48, octaves = 2, whiteKeyWidth = 24, height = 96, heldNotes, showOctaveLabels = true, disabled, whiteColor = "#ECF2E8", blackColor = "#17191C", activeColor = "#C6F135", borderColor = "#00000066", onNoteOn, onNoteOff, }) {
+    const [pressed, setPressed] = useState(null);
+    const active = useRef(null);
+    // Snap the start onto a white key so the layout math stays honest.
+    let base = Math.round(startNote);
+    while (isBlack(base))
+        base += 1;
+    const whiteCount = Math.max(1, Math.round(octaves)) * 7 + 1;
+    const blackWidth = whiteKeyWidth * 0.62;
+    const blackHeight = height * 0.6;
+    const whites = [];
+    const blacks = [];
+    for (let note = base; whites.length < whiteCount; note++) {
+        if (isBlack(note)) {
+            blacks.push({ note, left: whites.length * whiteKeyWidth - blackWidth / 2 });
+        }
+        else {
+            whites.push(note);
+        }
+    }
+    const press = (note) => {
+        if (active.current === note)
+            return;
+        if (active.current !== null)
+            onNoteOff?.(active.current);
+        active.current = note;
+        setPressed(note);
+        onNoteOn?.(note);
+    };
+    const release = () => {
+        if (active.current === null)
+            return;
+        onNoteOff?.(active.current);
+        active.current = null;
+        setPressed(null);
+    };
+    /** The key under an approximate pointer position (glissando). */
+    const noteAt = (x, y) => {
+        if (y <= blackHeight) {
+            for (const black of blacks) {
+                if (x >= black.left && x <= black.left + blackWidth)
+                    return black.note;
+            }
+        }
+        const index = Math.min(whiteCount - 1, Math.max(0, Math.floor(x / whiteKeyWidth)));
+        return whites[index];
+    };
+    const isActive = (note) => pressed === note || (heldNotes !== undefined && heldNotes.includes(note));
+    const keyHandlers = (note, centerX, centerY) => disabled
+        ? {}
+        : {
+            onMouseDown: () => press(note),
+            onMouseUp: release,
+            onDrag: (e) => press(noteAt(centerX + e.dx, centerY + e.dy)),
+            onDragEnd: release,
+        };
+    return (_jsxs(View, { className: `flex-row relative ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width: whiteCount * whiteKeyWidth, height }, children: [whites.map((note, i) => (_jsx(View, { className: "border rounded-b-[3] justify-end items-center pb-1", style: {
+                    width: whiteKeyWidth,
+                    height,
+                    backgroundColor: isActive(note) ? activeColor : whiteColor,
+                    borderColor,
+                }, ...keyHandlers(note, (i + 0.5) * whiteKeyWidth, height * 0.8), children: showOctaveLabels && ((note % 12) + 12) % 12 === 0 ? (_jsx(Text, { className: "text-[8] font-bold", style: { color: "#00000088" }, children: midiNoteName(note) })) : null }, note))), blacks.map((black) => (_jsx(View, { className: "absolute border rounded-b-[3]", style: {
+                    left: black.left,
+                    top: 0,
+                    width: blackWidth,
+                    height: blackHeight,
+                    backgroundColor: isActive(black.note) ? activeColor : blackColor,
+                    borderColor,
+                }, ...keyHandlers(black.note, black.left + blackWidth / 2, blackHeight / 2) }, black.note)))] }));
+}

package/dist/sequencer.d.ts

@@ -0,0 +1,23 @@
+export interface StepSequencerProps {
+    /** rows × steps. `pattern[row][step]` true = lit. */
+    pattern: boolean[][];
+    /** The column currently playing — painted with a bright ring. */
+    playhead?: number;
+    /** Printed left of each row ("KICK", "SNARE"…). */
+    rowLabels?: string[];
+    /** Cell edge length. Default 20. */
+    cellSize?: number;
+    /** Space between cells. Default 5. */
+    gap?: number;
+    /** Downbeat tint every N steps. Default 4; 0 disables. */
+    groupEvery?: number;
+    disabled?: boolean;
+    cellColor?: string;
+    /** Downbeat cells (step 0, 4, 8…) when unlit. */
+    downbeatColor?: string;
+    activeColor?: string;
+    playheadColor?: string;
+    labelColor?: string;
+    onToggle: (row: number, step: number, next: boolean) => void;
+}
+export declare function StepSequencer({ pattern, playhead, rowLabels, cellSize, gap, groupEvery, disabled, cellColor, downbeatColor, activeColor, playheadColor, labelColor, onToggle, }: StepSequencerProps): import("react").JSX.Element;

package/dist/sequencer.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The step sequencer grid — rows of cells you click on and off, with a
+// playhead column the host drives. Patterns live in the app's state;
+// the component is fully controlled.
+import { View, Text } from "./primitives";
+export function StepSequencer({ pattern, playhead, rowLabels, cellSize = 20, gap = 5, groupEvery = 4, disabled, cellColor = "#242922", downbeatColor = "#2E342B", activeColor = "#C6F135", playheadColor = "#ECF2E8", labelColor = "#a1a1aa", onToggle, }) {
+    const labelWidth = rowLabels !== undefined && rowLabels.length > 0
+        ? Math.max(...rowLabels.map((label) => label.length)) * 7 + 10
+        : 0;
+    return (_jsx(View, { className: disabled ? "opacity-40" : "", style: { rowGap: gap }, children: pattern.map((row, r) => (_jsxs(View, { className: "flex-row items-center", style: { columnGap: gap }, children: [labelWidth > 0 ? (_jsx(Text, { className: "text-[10] font-bold tracking-widest", style: { width: labelWidth, color: labelColor }, children: rowLabels?.[r] ?? "" })) : null, row.map((lit, s) => (_jsx(View, { className: `rounded-[4] border ${disabled ? "" : "cursor-pointer"}`, style: {
+                        width: cellSize,
+                        height: cellSize,
+                        backgroundColor: lit
+                            ? activeColor
+                            : groupEvery > 0 && s % groupEvery === 0
+                                ? downbeatColor
+                                : cellColor,
+                        borderColor: s === playhead ? playheadColor : "#00000055",
+                    }, onClick: disabled ? undefined : () => onToggle(r, s, !lit) }, s)))] }, r))) }));
+}

package/dist/specialty.d.ts

@@ -0,0 +1,109 @@
+export interface MacroPadProps {
+    /** Normalized 0..1. */
+    x: number;
+    /** Normalized 0..1 — 1 is the top. */
+    y: number;
+    /** Diameter. Default 220. */
+    size?: number;
+    labelX?: string;
+    labelY?: string;
+    disabled?: boolean;
+    /** Concentric ring count. Default 9. */
+    rings?: number;
+    /** Freeze the ring motion (reduced-motion, screenshots). */
+    animate?: boolean;
+    color?: string;
+    trackColor?: string;
+    onChange: (x: number, y: number) => void;
+    onBegin?: () => void;
+    onEnd?: () => void;
+}
+/** The centerpiece macro control: a circular 2D pad whose concentric
+    rings breathe with the values — x spreads them, y drives their
+    intensity. One drag, two parameters, instrument-grade presence. */
+export declare function MacroPad({ x, y, size, labelX, labelY, disabled, rings, animate, color, trackColor, onChange, onBegin, onEnd, }: MacroPadProps): import("react").JSX.Element;
+export interface ParamMacroPadProps {
+    paramX: string;
+    paramY: string;
+    size?: number;
+    labelX?: string;
+    labelY?: string;
+    rings?: number;
+    animate?: boolean;
+    color?: string;
+    trackColor?: string;
+}
+/** A MacroPad driving two host parameters — labels default to their
+    names. */
+export declare function ParamMacroPad({ paramX, paramY, labelX, labelY, ...rest }: ParamMacroPadProps): import("react").JSX.Element;
+export interface HardwareKnobProps {
+    value: number;
+    size?: number;
+    label?: string;
+    text?: string;
+    disabled?: boolean;
+    defaultValue?: number;
+    wheelSensitivity?: number;
+    capColor?: string;
+    pointerColor?: string;
+    tickColor?: string;
+    onChange: (value: number) => void;
+    onBegin?: () => void;
+    onEnd?: () => void;
+}
+/** The skeuomorphic knob: a dark hardware cap with a glowing pointer
+    notch at the rim and a faint tick track — the audio-ui.com look,
+    painted natively. */
+export declare function HardwareKnob({ value, size, label, text, disabled, defaultValue, wheelSensitivity, capColor, pointerColor, tickColor, onChange, onBegin, onEnd, }: HardwareKnobProps): import("react").JSX.Element;
+export interface ParamHardwareKnobProps {
+    paramId: string;
+    size?: number;
+    label?: string;
+    capColor?: string;
+    pointerColor?: string;
+    tickColor?: string;
+    wheelSensitivity?: number;
+}
+/** A HardwareKnob bound to a host parameter. */
+export declare function ParamHardwareKnob({ paramId, label, ...rest }: ParamHardwareKnobProps): import("react").JSX.Element;
+export interface CrossfaderProps {
+    /** 0 = fully start-side (dry), 1 = fully end-side (wet). */
+    value: number;
+    width?: number;
+    height?: number;
+    labelStart?: string;
+    labelEnd?: string;
+    disabled?: boolean;
+    trackColor?: string;
+    handleColor?: string;
+    textColor?: string;
+    onChange: (value: number) => void;
+    onBegin?: () => void;
+    onEnd?: () => void;
+}
+/** The DRY/WET strip: a wide track with a grippy rectangular handle. */
+export declare function Crossfader({ value, width, height, labelStart, labelEnd, disabled, trackColor, handleColor, textColor, onChange, onBegin, onEnd, }: CrossfaderProps): import("react").JSX.Element;
+export interface ParamCrossfaderProps {
+    paramId: string;
+    width?: number;
+    height?: number;
+    labelStart?: string;
+    labelEnd?: string;
+    trackColor?: string;
+    handleColor?: string;
+}
+/** A Crossfader bound to a host parameter — the classic mix control. */
+export declare function ParamCrossfader({ paramId, ...rest }: ParamCrossfaderProps): import("react").JSX.Element;
+export interface PulseOrbProps {
+    /** Level 0..1 — drives ring intensity and core glow. */
+    value: number;
+    size?: number;
+    color?: string;
+    /** Echo ring count. Default 4. */
+    rings?: number;
+    /** Freeze the motion. */
+    animate?: boolean;
+}
+/** A value-reactive orb: a glowing core emitting echo rings — visual
+    feedback for levels, activity, or just presence. */
+export declare function PulseOrb({ value, size, color, rings, animate, }: PulseOrbProps): import("react").JSX.Element;