@vsreact/core 0.0.11 → 0.0.13

package/src/sequencer.tsx

@@ -0,0 +1,83 @@
+// 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 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 function StepSequencer({
+  pattern,
+  playhead,
+  rowLabels,
+  cellSize = 20,
+  gap = 5,
+  groupEvery = 4,
+  disabled,
+  cellColor = "#242922",
+  downbeatColor = "#2E342B",
+  activeColor = "#C6F135",
+  playheadColor = "#ECF2E8",
+  labelColor = "#a1a1aa",
+  onToggle,
+}: StepSequencerProps) {
+  const labelWidth =
+    rowLabels !== undefined && rowLabels.length > 0
+      ? Math.max(...rowLabels.map((label) => label.length)) * 7 + 10
+      : 0;
+
+  return (
+    <View className={disabled ? "opacity-40" : ""} style={{ rowGap: gap }}>
+      {pattern.map((row, r) => (
+        <View key={r} className="flex-row items-center" style={{ columnGap: gap }}>
+          {labelWidth > 0 ? (
+            <Text
+              className="text-[10] font-bold tracking-widest"
+              style={{ width: labelWidth, color: labelColor }}
+            >
+              {rowLabels?.[r] ?? ""}
+            </Text>
+          ) : null}
+          {row.map((lit, s) => (
+            <View
+              key={s}
+              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)}
+            />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/synth.test.tsx

@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+const batches: unknown[][][] = [];
+const nativeCalls: Array<{ name: string; args: any }> = [];
+let paramGetResult: any = { value: 0.5, text: "0.5", name: "Mod", label: "" };
+
+(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 args = JSON.parse(argsJson);
+  nativeCalls.push({ name, args });
+  if (name === "param:get") return JSON.stringify(paramGetResult);
+  return "null";
+};
+
+import {
+  render,
+  unmount,
+  ADSREnvelope,
+  ModWheel,
+  ParamModWheel,
+  PitchBend,
+  adsrLevelAt,
+  midiNoteToHz,
+  hzToMidiNote,
+} from "./index";
+
+const allOps = () => batches.flat();
+const opsNamed = (name: string) => allOps().filter((op: any) => op[0] === name);
+const dispatch = (msg: unknown) =>
+  (globalThis as Record<string, any>).__vsreact_dispatch(JSON.stringify(msg));
+
+const nodesWithListener = (type: string): number[] => {
+  const seen = new Set<number>();
+  for (const op of opsNamed("setProps") as any[]) {
+    if (op[2]?.listeners?.includes(type)) seen.add(op[1]);
+  }
+  return [...seen];
+};
+
+beforeEach(() => {
+  unmount();
+  batches.length = 0;
+  nativeCalls.length = 0;
+  paramGetResult = { value: 0.5, text: "0.5", name: "Mod", label: "" };
+});
+
+describe("pitch math", () => {
+  test("midiNoteToHz and hzToMidiNote agree at the anchors", () => {
+    expect(midiNoteToHz(69)).toBe(440);
+    expect(midiNoteToHz(57)).toBeCloseTo(220);
+    expect(midiNoteToHz(60)).toBeCloseTo(261.626, 2);
+    expect(hzToMidiNote(440)).toBe(69);
+    expect(hzToMidiNote(262)).toBe(60);
+  });
+});
+
+describe("adsrLevelAt", () => {
+  // width 100, segW 27
+  test("traces the four stages", () => {
+    const at = (x: number) => adsrLevelAt(x, 100, 0.5, 0.5, 0.5, 0.5);
+    expect(at(0)).toBe(0);
+    expect(at(13.5)).toBeCloseTo(1); // attack peak at 0.5*27
+    expect(at(27)).toBeCloseTo(0.5); // decay bottom
+    expect(at(50)).toBe(0.5); // sustain plateau
+    expect(at(100)).toBeCloseTo(0); // release floor
+  });
+
+  test("zero attack jumps straight to the peak", () => {
+    expect(adsrLevelAt(0, 100, 0, 0.5, 0.5, 0.5)).toBe(1);
+  });
+});
+
+describe("ADSREnvelope", () => {
+  test("dragging the attack handle reports a new attack", () => {
+    const seen: Array<[string, number]> = [];
+    render(
+      <ADSREnvelope
+        attack={0.5}
+        decay={0.5}
+        sustain={0.5}
+        release={0.5}
+        width={200}
+        onChange={(k, v) => seen.push([k, v])}
+      />,
+    );
+
+    // Handles render in order: attack, decay/sustain, release.
+    const handles = nodesWithListener("drag");
+    expect(handles).toHaveLength(3);
+
+    dispatch({ kind: "event", nodeId: handles[0], type: "dragstart", payload: { dx: 0, dy: 0 } });
+    dispatch({ kind: "event", nodeId: handles[0], type: "drag", payload: { dx: 27, dy: 0 } });
+    // segW = 200*0.27 = 54; +27px = +0.5 → clamped at 1
+    expect(seen.at(-1)).toEqual(["attack", 1]);
+  });
+
+  test("the corner handle drives decay and sustain together", () => {
+    const seen: Array<[string, number]> = [];
+    const begins: string[] = [];
+    render(
+      <ADSREnvelope
+        attack={0.5}
+        decay={0.5}
+        sustain={0.5}
+        release={0.5}
+        width={200}
+        height={104}
+        onChange={(k, v) => seen.push([k, v])}
+        onBegin={(k) => begins.push(k)}
+      />,
+    );
+
+    const handles = nodesWithListener("drag");
+    dispatch({ kind: "event", nodeId: handles[1], type: "dragstart", payload: { dx: 0, dy: 0 } });
+    expect(begins).toEqual(["decay", "sustain"]);
+
+    dispatch({ kind: "event", nodeId: handles[1], type: "drag", payload: { dx: -27, dy: -48 } });
+    const decay = seen.find(([k]) => k === "decay");
+    const sustain = seen.find(([k]) => k === "sustain");
+    expect(decay?.[1]).toBeCloseTo(0); // -27/54 from 0.5
+    expect(sustain?.[1]).toBeCloseTo(1); // -48/(104-8) up from 0.5
+  });
+});
+
+describe("ModWheel", () => {
+  test("dragging up raises the value from its start", () => {
+    const seen: number[] = [];
+    render(<ModWheel value={0.5} height={120} onChange={(v) => seen.push(v)} />);
+
+    const id = nodesWithListener("drag")[0];
+    dispatch({ kind: "event", nodeId: id, type: "dragstart", payload: { dx: 0, dy: 0 } });
+    dispatch({ kind: "event", nodeId: id, type: "drag", payload: { dx: 0, dy: -50 } });
+    expect(seen.at(-1)).toBeCloseTo(1); // 0.5 + 50/100
+  });
+
+  test("ParamModWheel opens a gesture and writes the parameter", () => {
+    render(<ParamModWheel paramId="mod" />);
+
+    const id = nodesWithListener("drag")[0];
+    dispatch({ kind: "event", nodeId: id, type: "dragstart", payload: { dx: 0, dy: 0 } });
+    dispatch({ kind: "event", nodeId: id, type: "drag", payload: { dx: 0, dy: 30 } });
+    dispatch({ kind: "event", nodeId: id, type: "dragend", payload: { dx: 0, dy: 30 } });
+
+    const names = nativeCalls.map((c) => c.name);
+    expect(names).toContain("param:begin");
+    expect(names).toContain("param:set");
+    expect(names).toContain("param:end");
+  });
+});
+
+describe("PitchBend", () => {
+  test("drag bends, release springs back toward center", async () => {
+    const seen: number[] = [];
+    render(<PitchBend height={120} onChange={(v) => seen.push(v)} />);
+
+    const id = nodesWithListener("drag")[0];
+    dispatch({ kind: "event", nodeId: id, type: "dragstart", payload: { dx: 0, dy: 0 } });
+    dispatch({ kind: "event", nodeId: id, type: "drag", payload: { dx: 0, dy: -30 } });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(seen.at(-1)).toBeCloseTo(0.5); // 30/(120/2)
+
+    dispatch({ kind: "event", nodeId: id, type: "dragend", payload: { dx: 0, dy: -30 } });
+    await new Promise((r) => setTimeout(r, 400));
+    expect(seen.at(-1)).toBe(0); // spring settled at dead center
+  });
+});

package/src/synth.tsx

@@ -0,0 +1,370 @@
+// 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: number) => Math.min(1, Math.max(0, v));
+
+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 function adsrLevelAt(
+  x: number,
+  width: number,
+  attack: number,
+  decay: number,
+  sustain: number,
+  release: number,
+): number {
+  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,
+}: ADSREnvelopeProps) {
+  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: ADSRKey[], move: (dx: number, dy: number) => void) =>
+    disabled
+      ? {}
+      : {
+          onDragStart: () => {
+            start.current = { attack: a, decay: d, sustain: s, release: r };
+            for (const key of keys) onBegin?.(key);
+          },
+          onDrag: (e: { dx: number; dy: number }) => move(e.dx, e.dy),
+          onDragEnd: () => {
+            for (const key of keys) onEnd?.(key);
+          },
+        };
+
+  const dot = (left: number, top: number, keys: ADSRKey[], move: (dx: number, dy: number) => void) => (
+    <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)}
+    >
+      <View
+        className="rounded-full border"
+        style={{ width: 9, height: 9, backgroundColor: handleColor, borderColor: "#00000088" }}
+      />
+    </View>
+  );
+
+  const body = (
+    <View
+      className={`relative rounded overflow-hidden ${disabled ? "opacity-40" : ""}`}
+      style={{ width, height, backgroundColor: trackColor }}
+    >
+      <View className="absolute inset-0 flex-row items-end px-[1]" style={{ columnGap: 1 }}>
+        {Array.from({ length: columns }, (_, i) => {
+          const level = adsrLevelAt(((i + 0.5) / columns) * width, width, a, d, s, r);
+          return (
+            <View
+              key={i}
+              className="flex-1 rounded-[1]"
+              style={{ height: Math.max(1, level * (height - 4)), backgroundColor: color }}
+            />
+          );
+        })}
+      </View>
+      {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)),
+      )}
+    </View>
+  );
+
+  if (label === undefined) return body;
+
+  return (
+    <View className="items-center gap-2">
+      {body}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}
+
+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 function ParamADSREnvelope({
+  attackId,
+  decayId,
+  sustainId,
+  releaseId,
+  ...visual
+}: ParamADSREnvelopeProps) {
+  const params = {
+    attack: useParameter(attackId),
+    decay: useParameter(decayId),
+    sustain: useParameter(sustainId),
+    release: useParameter(releaseId),
+  };
+
+  return (
+    <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}
+    />
+  );
+}
+
+/* ── wheels ─────────────────────────────────────────────────────────── */
+
+interface WheelSkin {
+  width?: number;
+  height?: number;
+  disabled?: boolean;
+  trackColor?: string;
+  thumbColor?: string;
+  accentColor?: string;
+  label?: string;
+}
+
+function WheelChrome({
+  value01,
+  width = 34,
+  height = 110,
+  disabled,
+  trackColor = "#141714",
+  thumbColor = "#3A4038",
+  accentColor = "#C6F135",
+  label,
+  centerMark,
+  handlers,
+}: WheelSkin & {
+  /** Thumb position, 0 (bottom) .. 1 (top). */
+  value01: number;
+  centerMark?: boolean;
+  handlers: Record<string, unknown>;
+}) {
+  const THUMB = 16;
+  const travel = height - 4 - THUMB;
+
+  const wheel = (
+    <View
+      className={`relative rounded-lg border overflow-hidden ${disabled ? "opacity-40" : "cursor-pointer"}`}
+      style={{ width, height, backgroundColor: trackColor, borderColor: "#00000066" }}
+      {...handlers}
+    >
+      {centerMark ? (
+        <View
+          className="absolute left-0 right-0 h-[1]"
+          style={{ top: height / 2, backgroundColor: "#FFFFFF2E" }}
+        />
+      ) : null}
+      <View
+        className="absolute left-[2] right-[2] rounded"
+        style={{ top: 2 + (1 - clamp01(value01)) * travel, height: THUMB, backgroundColor: thumbColor }}
+      >
+        <View
+          className="absolute left-[2] right-[2] rounded-full"
+          style={{ top: THUMB / 2 - 1.25, height: 2.5, backgroundColor: accentColor }}
+        />
+      </View>
+    </View>
+  );
+
+  if (label === undefined) return wheel;
+
+  return (
+    <View className="items-center gap-2">
+      {wheel}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}
+
+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 function PitchBend({ onChange, springBack = true, ...skin }: PitchBendProps) {
+  const [drag, setDrag] = useState<number | null>(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: { dy: number }) =>
+          setDrag(Math.min(1, Math.max(-1, startValue.current - e.dy / (height / 2)))),
+        onDragEnd: () => setDrag(null),
+      };
+
+  return <WheelChrome value01={(value + 1) / 2} centerMark handlers={handlers} {...skin} />;
+}
+
+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 function ModWheel({ value, onChange, onBegin, onEnd, ...skin }: ModWheelProps) {
+  const startValue = useRef(0);
+  const height = skin.height ?? 110;
+
+  const handlers = skin.disabled
+    ? {}
+    : {
+        onDragStart: () => {
+          startValue.current = clamp01(value);
+          onBegin?.();
+        },
+        onDrag: (e: { dy: number }) => onChange(clamp01(startValue.current - e.dy / (height - 20))),
+        onDragEnd: () => onEnd?.(),
+      };
+
+  return <WheelChrome value01={clamp01(value)} handlers={handlers} {...skin} />;
+}
+
+export interface ParamModWheelProps extends WheelSkin {
+  paramId: string;
+}
+
+/** A ModWheel bound to a host parameter. */
+export function ParamModWheel({ paramId, ...skin }: ParamModWheelProps) {
+  const param = useParameter(paramId);
+
+  return (
+    <ModWheel
+      value={param.value}
+      onChange={param.set}
+      onBegin={param.begin}
+      onEnd={param.end}
+      label={skin.label ?? param.name.toUpperCase()}
+      {...skin}
+    />
+  );
+}
+
+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 function ParamPitchBend({ paramId, ...skin }: ParamPitchBendProps) {
+  const param = useParameter(paramId);
+  const active = useRef(false);
+
+  return (
+    <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}
+    />
+  );
+}