@vsreact/core 0.0.15 → 0.0.17

package/README.md

@@ -0,0 +1,107 @@
+# @vsreact/core
+
+**Write React. Ship native VST.**
+
+VSReacT is a React renderer for JUCE audio plugins — your UI runs in
+QuickJS inside the plugin, lays out with Yoga, and paints with
+`juce::Graphics`. No webview, no browser, no Electron. Real threads,
+real automation gestures, hot reload in your DAW.
+
+```tsx
+import { render, View, Text, ParamKnob } from "@vsreact/core";
+
+function App() {
+  return (
+    <View className="w-full h-full items-center justify-center gap-5">
+      <Text className="text-text text-[15] font-bold tracking-widest">MY PLUGIN</Text>
+      <View className="flex-row gap-10">
+        <ParamKnob paramId="gain" size={88} />
+        <ParamKnob paramId="pan" size={88} bipolar />
+      </View>
+    </View>
+  );
+}
+
+render(<App />);
+```
+
+That's a working plugin UI: knobs bound to APVTS parameters, drag /
+wheel / double-click-reset, automation-safe begin/set/end gestures.
+
+## Install
+
+Starting fresh? The scaffolder gives you a complete plugin project —
+CMake, C++, and a React UI — in one command:
+
+```sh
+bun create vsreact my-plugin     # or: npm create vsreact@latest my-plugin
+```
+
+Adding to an existing plugin:
+
+```sh
+bun add @vsreact/core     # or npm / yarn / pnpm
+```
+
+The native side is a JUCE module fetched with CMake — see the
+[installation guide](https://vsreact.n9records.com/docs/installation).
+
+## What's in the box
+
+**Parameter controls** — `Knob`, `Slider`, `Toggle`, `XYPad`,
+`Segmented`, `Select`, `NumberBox`, `Checkbox`, `RadioGroup`,
+`HardwareKnob`, `MacroPad`, `Crossfader` — each with a `Param*` twin
+that binds to a host parameter in one line, and `GenericEditor`, the
+one-line editor for your whole parameter list.
+
+**Synth & performance** — `PianoKeyboard` (glissando, held notes),
+`StepSequencer`, `ADSREnvelope` (four-corner editor), `PitchBend`,
+`ModWheel`, `EQCurve` (real RBJ biquad response with draggable band
+nodes).
+
+**Meters & visualizers** — `Meter` (peak-hold, hot zone, reverse for
+gain reduction), `RingMeter`, `Bars`, `Waveform`, `PulseOrb`.
+
+**Structure & feedback** — `Tabs`, `Disclosure`, `Button`, `Tooltip`,
+`Modal`, `ProgressBar` (determinate + indeterminate), `Spinner`.
+
+**Hooks** — `useParameter`, `useParameterList`, `useNativeEvent`,
+`useNativeValue`, `useSpring`, `useTween`, `usePeakHold`,
+`useRollingBuffer`, `useDebounced`, `useThrottled`, `useInterval`,
+`useHover`, `useToggle`, `usePrevious`, `useLayoutRect`, `useOverlay`.
+
+**Utilities** — a Tailwind-subset `className` engine with theme
+tokens, `cx`, value formatters (`formatDb`, `formatHz`, `formatMs`,
+`formatPercent`, `formatSemitones`, `midiNoteName`, `midiNoteToHz`),
+and the pure math behind the components (`adsrLevelAt`,
+`biquadMagnitudeDb`, `eqResponseDb`, `snapToStep`, `mapRange`).
+
+## How it works
+
+```
+React (QuickJS) ──mutations──▶ C++ shadow tree ──Yoga──▶ juce::Graphics
+      ▲                                                        │
+      └────────────── events, parameters, native calls ────────┘
+```
+
+Your bundle runs in QuickJS with a custom react-reconciler that
+streams JSON mutations to a C++ shadow tree. Yoga computes layout,
+JUCE paints, and input events flow back. Parameters ride
+`vsreact::ParameterBridge`; anything else rides `native.call()` /
+`useNativeEvent`.
+
+- **Hot reload**: point the native side at your bundle file and it
+  reloads on save — inside the DAW.
+- **Automation-safe**: every control opens proper begin/set/end
+  gestures.
+- **No webview**: the UI is painted by the same process and toolkit as
+  the rest of your plugin.
+
+## Docs
+
+- Site & component gallery: <https://vsreact.n9records.com/components>
+- Quick start: <https://vsreact.n9records.com/docs/quick-start>
+- Full docs: <https://vsreact.n9records.com/docs>
+- Analytics add-on: [`@vsreact/posthog`](https://www.npmjs.com/package/@vsreact/posthog)
+
+MIT © N9 Records Technologies

package/dist/controls.d.ts

@@ -85,6 +85,9 @@ export declare function Toggle({ on, label, offLabel, onLabel, size, disabled, t
 export interface ParamToggleProps {
     paramId: string;
     label?: string;
+    /** Hardware-style side captions, forwarded to Toggle. */
+    offLabel?: string;
+    onLabel?: string;
     size?: number;
     trackColor?: string;
     onColor?: string;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import "./runtime";
 import "./bridge";
+/** The SDK version — stamp it on support dumps and analytics. */
+export declare const VERSION = "0.0.17";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export type { CommonProps, TextProps, ImageProps, TextInputProps, NativeViewProps, } from "./primitives";
 export { render, unmount } from "./render";

package/dist/index.js

@@ -2,6 +2,8 @@
 // timer/console/microtask shims react depends on inside QuickJS.
 import "./runtime";
 import "./bridge";
+/** The SDK version — stamp it on support dumps and analytics. */
+export const VERSION = "0.0.17";
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsreact/core",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Write React. Ship native VST. A React renderer for JUCE audio plugins — QuickJS + Yoga + juce::Graphics, no webview.",
   "keywords": [
     "react",

package/src/controls.tsx

@@ -388,6 +388,9 @@ export function Toggle({
 export interface ParamToggleProps {
   paramId: string;
   label?: string;
+  /** Hardware-style side captions, forwarded to Toggle. */
+  offLabel?: string;
+  onLabel?: string;
   size?: number;
   trackColor?: string;
   onColor?: string;

package/src/index.ts

@@ -3,6 +3,9 @@
 import "./runtime";
 import "./bridge";
 
+/** The SDK version — stamp it on support dumps and analytics. */
+export const VERSION = "0.0.17";
+
 export { View, Text, Image, TextInput, NativeView } from "./primitives";
 export type {
   CommonProps,

package/src/perform.test.tsx

@@ -10,6 +10,7 @@ const batches: unknown[][][] = [];
 import {
   render,
   unmount,
+  VERSION,
   PianoKeyboard,
   StepSequencer,
   ProgressBar,
@@ -41,6 +42,12 @@ beforeEach(() => {
   batches.length = 0;
 });
 
+describe("VERSION", () => {
+  test("matches the package version", () => {
+    expect(VERSION).toBe(require("../package.json").version);
+  });
+});
+
 describe("format", () => {
   test("formatDb signs and floors", () => {
     expect(formatDb(6)).toBe("+6.0 dB");