@vsreact/core 0.0.11 → 0.0.13

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,5 +12,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 { ADSREnvelope, ParamADSREnvelope, PitchBend, ModWheel, ParamModWheel, ParamPitchBend, } from "./synth";
+export type { ADSRKey, ADSREnvelopeProps, ParamADSREnvelopeProps, PitchBendProps, ModWheelProps, ParamModWheelProps, ParamPitchBendProps, } from "./synth";
 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,4 +12,7 @@ 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 { ADSREnvelope, ParamADSREnvelope, PitchBend, ModWheel, ParamModWheel, ParamPitchBend, } from "./synth";
 export { MacroPad, ParamMacroPad, HardwareKnob, ParamHardwareKnob, Crossfader, ParamCrossfader, PulseOrb, } from "./specialty";

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,21 @@
+/** 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;
+/** A MIDI note as a frequency (equal temperament): 69 → 440. Feed your
+    oscillator straight from PianoKeyboard's onNoteOn. */
+export declare function midiNoteToHz(note: number, a4?: number): number;
+/** The nearest MIDI note for a frequency: 440 → 69. */
+export declare function hzToMidiNote(hz: number, a4?: number): number;

package/dist/format.js

@@ -0,0 +1,59 @@
+// 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}`;
+}
+/** A MIDI note as a frequency (equal temperament): 69 → 440. Feed your
+    oscillator straight from PianoKeyboard's onNoteOn. */
+export function midiNoteToHz(note, a4 = 440) {
+    return a4 * Math.pow(2, (note - 69) / 12);
+}
+/** The nearest MIDI note for a frequency: 440 → 69. */
+export function hzToMidiNote(hz, a4 = 440) {
+    return Math.round(69 + 12 * Math.log2(hz / a4));
+}

package/dist/index.d.ts

@@ -28,6 +28,13 @@ 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 { ADSREnvelope, ParamADSREnvelope, PitchBend, ModWheel, ParamModWheel, ParamPitchBend, adsrLevelAt, } from "./synth";
+export type { ADSRKey, ADSREnvelopeProps, ParamADSREnvelopeProps, PitchBendProps, ModWheelProps, ParamModWheelProps, ParamPitchBendProps, } from "./synth";
+export { mapRange, formatDb, formatHz, formatMs, formatPercent, formatSemitones, midiNoteName, midiNoteToHz, hzToMidiNote, } 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,4 +18,8 @@ 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 { ADSREnvelope, ParamADSREnvelope, PitchBend, ModWheel, ParamModWheel, ParamPitchBend, adsrLevelAt, } from "./synth";
+export { mapRange, formatDb, formatHz, formatMs, formatPercent, formatSemitones, midiNoteName, midiNoteToHz, hzToMidiNote, } 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/synth.d.ts

@@ -0,0 +1,79 @@
+export type ADSRKey = "attack" | "decay" | "sustain" | "release";
+export interface ADSREnvelopeProps {
+    /** All 0..1: times are a fraction of each stage's max width. */
+    attack: number;
+    decay: number;
+    sustain: number;
+    release: number;
+    width?: number;
+    height?: number;
+    /** Fill resolution. Default 44 columns. */
+    columns?: number;
+    disabled?: boolean;
+    trackColor?: string;
+    /** The filled envelope body. */
+    color?: string;
+    handleColor?: string;
+    label?: string;
+    onChange: (key: ADSRKey, value: number) => void;
+    onBegin?: (key: ADSRKey) => void;
+    onEnd?: (key: ADSRKey) => void;
+}
+/** The envelope level at x, piecewise over A → D → S plateau → R. */
+export declare function adsrLevelAt(x: number, width: number, attack: number, decay: number, sustain: number, release: number): number;
+/** The classic four-corner envelope editor: drag the attack peak, the
+    decay/sustain corner (both axes), and the release corner. */
+export declare function ADSREnvelope({ attack, decay, sustain, release, width, height, columns, disabled, trackColor, color, handleColor, label, onChange, onBegin, onEnd, }: ADSREnvelopeProps): import("react").JSX.Element;
+export interface ParamADSREnvelopeProps {
+    attackId: string;
+    decayId: string;
+    sustainId: string;
+    releaseId: string;
+    width?: number;
+    height?: number;
+    color?: string;
+    label?: string;
+}
+/** An ADSREnvelope over four host parameters, gestures opened per
+    handle (the decay/sustain corner drives both together). */
+export declare function ParamADSREnvelope({ attackId, decayId, sustainId, releaseId, ...visual }: ParamADSREnvelopeProps): import("react").JSX.Element;
+interface WheelSkin {
+    width?: number;
+    height?: number;
+    disabled?: boolean;
+    trackColor?: string;
+    thumbColor?: string;
+    accentColor?: string;
+    label?: string;
+}
+export interface PitchBendProps extends WheelSkin {
+    /** Bend, −1..+1; fires continuously and again as the spring returns. */
+    onChange?: (value: number) => void;
+    /** Snap back to center on release. Default true. */
+    springBack?: boolean;
+}
+/** The pitch wheel: drag up/down from center, springs back to 0 on
+    release (momentary — it owns its own state). */
+export declare function PitchBend({ onChange, springBack, ...skin }: PitchBendProps): import("react").JSX.Element;
+export interface ModWheelProps extends WheelSkin {
+    /** 0..1, controlled — mod wheels stay where you leave them. */
+    value: number;
+    onChange: (value: number) => void;
+    onBegin?: () => void;
+    onEnd?: () => void;
+}
+/** The mod wheel: a vertical strip that holds its position. */
+export declare function ModWheel({ value, onChange, onBegin, onEnd, ...skin }: ModWheelProps): import("react").JSX.Element;
+export interface ParamModWheelProps extends WheelSkin {
+    paramId: string;
+}
+/** A ModWheel bound to a host parameter. */
+export declare function ParamModWheel({ paramId, ...skin }: ParamModWheelProps): import("react").JSX.Element;
+export interface ParamPitchBendProps extends WheelSkin {
+    /** A 0..1 host parameter with 0.5 center. */
+    paramId: string;
+}
+/** A PitchBend writing 0.5 ± bend/2 to a host parameter; release closes
+    the gesture at dead center (the visual spring is cosmetic). */
+export declare function ParamPitchBend({ paramId, ...skin }: ParamPitchBendProps): import("react").JSX.Element;
+export {};

package/dist/synth.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Synth-surface controls — the ADSR envelope editor and the pitch/mod
+// wheels. Views only: the envelope is a filled column fill (like
+// <Waveform>) with draggable corner handles riding on top.
+import { useEffect, useRef, useState } from "react";
+import { View, Text } from "./primitives";
+import { useSpring } from "./animation";
+import { useParameter } from "./parameters";
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/** The envelope level at x, piecewise over A → D → S plateau → R. */
+export function adsrLevelAt(x, width, attack, decay, sustain, release) {
+    const segW = width * 0.27;
+    const ax = attack * segW;
+    const dw = decay * segW;
+    const rw = release * segW;
+    const rx = width - rw;
+    if (x <= ax)
+        return ax === 0 ? 1 : x / ax;
+    if (x <= ax + dw)
+        return 1 - (1 - sustain) * ((x - ax) / (dw || 1));
+    if (x <= rx)
+        return sustain;
+    return rw === 0 ? 0 : Math.max(0, sustain * (1 - (x - rx) / rw));
+}
+/** The classic four-corner envelope editor: drag the attack peak, the
+    decay/sustain corner (both axes), and the release corner. */
+export function ADSREnvelope({ attack, decay, sustain, release, width = 220, height = 96, columns = 44, disabled, trackColor = "#141714", color = "#C6F13566", handleColor = "#ECF2E8", label, onChange, onBegin, onEnd, }) {
+    const start = useRef({ attack: 0, decay: 0, sustain: 0, release: 0 });
+    const a = clamp01(attack);
+    const d = clamp01(decay);
+    const s = clamp01(sustain);
+    const r = clamp01(release);
+    const segW = width * 0.27;
+    const HANDLE = 18;
+    const handleProps = (keys, move) => disabled
+        ? {}
+        : {
+            onDragStart: () => {
+                start.current = { attack: a, decay: d, sustain: s, release: r };
+                for (const key of keys)
+                    onBegin?.(key);
+            },
+            onDrag: (e) => move(e.dx, e.dy),
+            onDragEnd: () => {
+                for (const key of keys)
+                    onEnd?.(key);
+            },
+        };
+    const dot = (left, top, keys, move) => (_jsx(View, { className: `absolute items-center justify-center ${disabled ? "" : "cursor-pointer"}`, style: { left: left - HANDLE / 2, top: top - HANDLE / 2, width: HANDLE, height: HANDLE }, ...handleProps(keys, move), children: _jsx(View, { className: "rounded-full border", style: { width: 9, height: 9, backgroundColor: handleColor, borderColor: "#00000088" } }) }));
+    const body = (_jsxs(View, { className: `relative rounded overflow-hidden ${disabled ? "opacity-40" : ""}`, style: { width, height, backgroundColor: trackColor }, children: [_jsx(View, { className: "absolute inset-0 flex-row items-end px-[1]", style: { columnGap: 1 }, children: Array.from({ length: columns }, (_, i) => {
+                    const level = adsrLevelAt(((i + 0.5) / columns) * width, width, a, d, s, r);
+                    return (_jsx(View, { className: "flex-1 rounded-[1]", style: { height: Math.max(1, level * (height - 4)), backgroundColor: color } }, i));
+                }) }), dot(a * segW, 4, ["attack"], (dx) => onChange("attack", clamp01(start.current.attack + dx / segW))), dot(a * segW + d * segW, 4 + (1 - s) * (height - 8), ["decay", "sustain"], (dx, dy) => {
+                onChange("decay", clamp01(start.current.decay + dx / segW));
+                onChange("sustain", clamp01(start.current.sustain - dy / (height - 8)));
+            }), dot(width - r * segW, 4 + (1 - s) * (height - 8), ["release"], (dx) => onChange("release", clamp01(start.current.release - dx / segW)))] }));
+    if (label === undefined)
+        return body;
+    return (_jsxs(View, { className: "items-center gap-2", children: [body, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
+}
+/** An ADSREnvelope over four host parameters, gestures opened per
+    handle (the decay/sustain corner drives both together). */
+export function ParamADSREnvelope({ attackId, decayId, sustainId, releaseId, ...visual }) {
+    const params = {
+        attack: useParameter(attackId),
+        decay: useParameter(decayId),
+        sustain: useParameter(sustainId),
+        release: useParameter(releaseId),
+    };
+    return (_jsx(ADSREnvelope, { attack: params.attack.value, decay: params.decay.value, sustain: params.sustain.value, release: params.release.value, onChange: (key, value) => params[key].set(value), onBegin: (key) => params[key].begin(), onEnd: (key) => params[key].end(), ...visual }));
+}
+function WheelChrome({ value01, width = 34, height = 110, disabled, trackColor = "#141714", thumbColor = "#3A4038", accentColor = "#C6F135", label, centerMark, handlers, }) {
+    const THUMB = 16;
+    const travel = height - 4 - THUMB;
+    const wheel = (_jsxs(View, { className: `relative rounded-lg border overflow-hidden ${disabled ? "opacity-40" : "cursor-pointer"}`, style: { width, height, backgroundColor: trackColor, borderColor: "#00000066" }, ...handlers, children: [centerMark ? (_jsx(View, { className: "absolute left-0 right-0 h-[1]", style: { top: height / 2, backgroundColor: "#FFFFFF2E" } })) : null, _jsx(View, { className: "absolute left-[2] right-[2] rounded", style: { top: 2 + (1 - clamp01(value01)) * travel, height: THUMB, backgroundColor: thumbColor }, children: _jsx(View, { className: "absolute left-[2] right-[2] rounded-full", style: { top: THUMB / 2 - 1.25, height: 2.5, backgroundColor: accentColor } }) })] }));
+    if (label === undefined)
+        return wheel;
+    return (_jsxs(View, { className: "items-center gap-2", children: [wheel, _jsx(Text, { className: "text-faint text-[10] font-bold tracking-widest", children: label })] }));
+}
+/** The pitch wheel: drag up/down from center, springs back to 0 on
+    release (momentary — it owns its own state). */
+export function PitchBend({ onChange, springBack = true, ...skin }) {
+    const [drag, setDrag] = useState(null);
+    const sprung = useSpring(drag ?? 0, { stiffness: 320, damping: 24 });
+    const value = drag ?? (springBack ? sprung : 0);
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    useEffect(() => {
+        onChangeRef.current?.(value);
+    }, [value]);
+    const startValue = useRef(0);
+    const height = skin.height ?? 110;
+    const handlers = skin.disabled
+        ? {}
+        : {
+            onDragStart: () => {
+                startValue.current = drag ?? 0;
+                setDrag(startValue.current);
+            },
+            onDrag: (e) => setDrag(Math.min(1, Math.max(-1, startValue.current - e.dy / (height / 2)))),
+            onDragEnd: () => setDrag(null),
+        };
+    return _jsx(WheelChrome, { value01: (value + 1) / 2, centerMark: true, handlers: handlers, ...skin });
+}
+/** The mod wheel: a vertical strip that holds its position. */
+export function ModWheel({ value, onChange, onBegin, onEnd, ...skin }) {
+    const startValue = useRef(0);
+    const height = skin.height ?? 110;
+    const handlers = skin.disabled
+        ? {}
+        : {
+            onDragStart: () => {
+                startValue.current = clamp01(value);
+                onBegin?.();
+            },
+            onDrag: (e) => onChange(clamp01(startValue.current - e.dy / (height - 20))),
+            onDragEnd: () => onEnd?.(),
+        };
+    return _jsx(WheelChrome, { value01: clamp01(value), handlers: handlers, ...skin });
+}
+/** A ModWheel bound to a host parameter. */
+export function ParamModWheel({ paramId, ...skin }) {
+    const param = useParameter(paramId);
+    return (_jsx(ModWheel, { value: param.value, onChange: param.set, onBegin: param.begin, onEnd: param.end, label: skin.label ?? param.name.toUpperCase(), ...skin }));
+}
+/** A PitchBend writing 0.5 ± bend/2 to a host parameter; release closes
+    the gesture at dead center (the visual spring is cosmetic). */
+export function ParamPitchBend({ paramId, ...skin }) {
+    const param = useParameter(paramId);
+    const active = useRef(false);
+    return (_jsx(PitchBend, { onChange: (v) => {
+            if (v === 0 && !active.current)
+                return; // at rest (incl. mount) — nothing to write
+            if (!active.current) {
+                active.current = true;
+                param.begin();
+            }
+            param.set(0.5 + v / 2);
+            if (v === 0) {
+                active.current = false;
+                param.end();
+            }
+        }, ...skin }));
+}

package/dist/tw.js

@@ -217,6 +217,11 @@ function resolveClass(cls) {
         case "text": {
             if (rest in textSizes)
                 return { fontSize: textSizes[rest] };
+            if (rest.startsWith("[") && !rest.startsWith("[#")) {
+                const size = parseLength(rest);
+                if (typeof size === "number")
+                    return { fontSize: size };
+            }
             const color = resolveColor(rest);
             return color !== undefined ? { color } : undefined;
         }