@vsreact/core 0.0.1

package/src/index.ts

@@ -0,0 +1,24 @@
+// vsreact public API. runtime must load first — it installs the
+// timer/console/microtask shims react depends on inside QuickJS.
+import "./runtime";
+import "./bridge";
+
+export { View, Text, Image, TextInput, NativeView } from "./primitives";
+export type {
+  CommonProps,
+  TextProps,
+  ImageProps,
+  TextInputProps,
+  NativeViewProps,
+} from "./primitives";
+export { render, unmount } from "./render";
+export { native } from "./native";
+export { configureTheme, tw } from "./tw";
+export type { Style, ResolvedClasses } from "./tw";
+export { useTween, lerp, Easing } from "./animation";
+export type { TweenOptions, EasingFn } from "./animation";
+export { useParameter } from "./parameters";
+export type { ParameterState, ParameterHandle } from "./parameters";
+export { Knob, Slider, ParamKnob, ParamSlider, dragToValue } from "./controls";
+export type { KnobProps, SliderProps, ParamKnobProps, ParamSliderProps } from "./controls";
+export type { DragEventPayload } from "./primitives";

package/src/native.ts

@@ -0,0 +1,18 @@
+// App-level messaging with the C++ host.
+
+import { addNativeListener, type EventHandler } from "./bridge";
+
+export const native = {
+  /** Synchronously invokes a C++ handler registered in RootOptions.onNativeCall. */
+  call(name: string, args?: unknown): any {
+    const fn = (globalThis as Record<string, any>).__vsreact_nativeCall;
+    if (typeof fn !== "function") return undefined;
+    const json = fn(name, JSON.stringify(args ?? null));
+    return json ? JSON.parse(json) : undefined;
+  },
+
+  /** Subscribes to events pushed from C++ via RootView::sendNativeEvent. */
+  on(name: string, cb: (payload: any) => void): () => void {
+    return addNativeListener(name, cb as EventHandler);
+  },
+};

package/src/parameters.ts

@@ -0,0 +1,60 @@
+// useParameter — two-way binding to a juce::AudioProcessorValueTreeState
+// parameter through vsreact::ParameterBridge. Values are normalized 0..1.
+
+import { useCallback, useEffect, useState } from "react";
+import { native } from "./native";
+
+export interface ParameterState {
+  value: number;
+  text: string;
+  name: string;
+  label: string;
+}
+
+export interface ParameterHandle extends ParameterState {
+  set: (normalized: number) => void;
+  begin: () => void;
+  end: () => void;
+}
+
+export function useParameter(id: string): ParameterHandle {
+  const [state, setState] = useState<ParameterState>(() => {
+    const initial = native.call("param:get", { id });
+    return initial && typeof initial.value === "number"
+      ? {
+          value: initial.value,
+          text: String(initial.text ?? ""),
+          name: String(initial.name ?? id),
+          label: String(initial.label ?? ""),
+        }
+      : { value: 0, text: "", name: id, label: "" };
+  });
+
+  useEffect(
+    () =>
+      native.on("param", (p) => {
+        if (p?.id === id)
+          setState((s) => ({ ...s, value: Number(p.value), text: String(p.text ?? "") }));
+      }),
+    [id],
+  );
+
+  const set = useCallback(
+    (normalized: number) => {
+      const value = Math.min(1, Math.max(0, normalized));
+      setState((s) => ({ ...s, value }));
+      native.call("param:set", { id, value });
+    },
+    [id],
+  );
+
+  const begin = useCallback(() => {
+    native.call("param:begin", { id });
+  }, [id]);
+
+  const end = useCallback(() => {
+    native.call("param:end", { id });
+  }, [id]);
+
+  return { ...state, set, begin, end };
+}

package/src/phase2.test.tsx

@@ -0,0 +1,100 @@
+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.0 dB", name: "Gain", label: "dB" };
+
+(globalThis as Record<string, any>).__vsreact_flush = (json: string) => {
+  batches.push(JSON.parse(json));
+};
+(globalThis as Record<string, any>).__vsreact_nativeCall = (name: string, argsJson: string) => {
+  const args = JSON.parse(argsJson);
+  nativeCalls.push({ name, args });
+  if (name === "param:get") return JSON.stringify(paramGetResult);
+  return "null";
+};
+
+import { render, unmount, View, tw, dragToValue, ParamKnob } 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));
+
+beforeEach(() => {
+  unmount();
+  batches.length = 0;
+  nativeCalls.length = 0;
+});
+
+describe("phase 2", () => {
+  test("overflow-y-scroll resolves", () => {
+    expect(tw("overflow-y-scroll").style).toEqual({ overflow: "scroll" });
+  });
+
+  test("dragToValue clamps and follows dy", () => {
+    expect(dragToValue(0.5, 0)).toBe(0.5);
+    expect(dragToValue(0.5, -40)).toBeCloseTo(0.7);
+    expect(dragToValue(0.5, 40)).toBeCloseTo(0.3);
+    expect(dragToValue(0.9, -100)).toBe(1);
+    expect(dragToValue(0.1, 100)).toBe(0);
+  });
+
+  test("drag props register listeners and receive payloads", () => {
+    const seen: any[] = [];
+
+    render(<View onDrag={(e) => seen.push(e)} className="w-4" />);
+
+    const nodeId = (opsNamed("create")[0] as any)[1];
+    const props: any = opsNamed("setProps").find((op: any) => op[1] === nodeId);
+    expect(props[2].listeners).toEqual(["drag"]);
+
+    dispatch({ kind: "event", nodeId, type: "drag", payload: { dx: 3, dy: -7, x: 10, y: 20 } });
+    expect(seen).toEqual([{ dx: 3, dy: -7, x: 10, y: 20 }]);
+  });
+
+  test("ParamKnob fetches the param, renders arc styles, and sets on drag", () => {
+    render(<ParamKnob paramId="gain" />);
+
+    expect(nativeCalls.some((c) => c.name === "param:get" && c.args.id === "gain")).toBe(true);
+
+    // The knob's arc view: find setProps carrying arcValueEnd for value 0.5 -> 0deg.
+    const arcProps: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.arcValueEnd !== undefined,
+    );
+    expect(arcProps).toBeDefined();
+    expect(arcProps[2].style.arcValueEnd).toBeCloseTo(0);
+    expect(arcProps[2].listeners).toEqual(
+      expect.arrayContaining(["dragstart", "drag", "dragend"]),
+    );
+
+    const knobId = arcProps[1];
+    batches.length = 0;
+
+    // Drag begins a gesture, moves the value, ends the gesture.
+    dispatch({ kind: "event", nodeId: knobId, type: "dragstart", payload: { dx: 0, dy: 0, x: 0, y: 0 } });
+    dispatch({ kind: "event", nodeId: knobId, type: "drag", payload: { dx: 0, dy: -40, x: 0, y: -40 } });
+    dispatch({ kind: "event", nodeId: knobId, type: "dragend", payload: { dx: 0, dy: -40, x: 0, y: -40 } });
+
+    expect(nativeCalls.some((c) => c.name === "param:begin")).toBe(true);
+    const setCall = nativeCalls.find((c) => c.name === "param:set");
+    expect(setCall?.args.value).toBeCloseTo(0.7);
+    expect(nativeCalls.some((c) => c.name === "param:end")).toBe(true);
+  });
+
+  test("param events from C++ update the knob", async () => {
+    render(<ParamKnob paramId="gain" />);
+    // Let passive effects flush so the native.on("param") subscription exists.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    batches.length = 0;
+
+    dispatch({ kind: "native", name: "param", payload: { id: "gain", value: 0.25, text: "-12 dB" } });
+
+    const arcProps: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.arcValueEnd !== undefined,
+    );
+    expect(arcProps).toBeDefined();
+    // 0.25 -> -135 + 270*0.25 = -67.5
+    expect(arcProps[2].style.arcValueEnd).toBeCloseTo(-67.5);
+  });
+});

package/src/primitives.tsx

@@ -0,0 +1,75 @@
+import { createElement, type ReactNode } from "react";
+import type { Style } from "./tw";
+
+export interface DragEventPayload {
+  /** Delta from the drag start, in root coordinates. */
+  dx: number;
+  dy: number;
+  /** Current pointer position in root coordinates. */
+  x: number;
+  y: number;
+}
+
+export interface CommonProps {
+  className?: string;
+  style?: Style;
+  children?: ReactNode;
+  /** Resets the scroll offset of an overflow-y-scroll container. */
+  scrollTop?: number;
+  onClick?: () => void;
+  onMouseEnter?: () => void;
+  onMouseLeave?: () => void;
+  onMouseDown?: () => void;
+  onMouseUp?: () => void;
+  onDragStart?: (e: DragEventPayload) => void;
+  onDrag?: (e: DragEventPayload) => void;
+  onDragEnd?: (e: DragEventPayload) => void;
+}
+
+export function View(props: CommonProps) {
+  return createElement("vs-view", props);
+}
+
+export interface TextProps extends Omit<CommonProps, "children"> {
+  children?: ReactNode; // strings/numbers (and fragments of them)
+}
+
+export function Text(props: TextProps) {
+  return createElement("vs-text", props);
+}
+
+export interface ImageProps extends CommonProps {
+  src: string;
+}
+
+export function Image(props: ImageProps) {
+  return createElement("vs-image", props);
+}
+
+export interface TextInputProps extends Omit<CommonProps, "children" | "onChange" | "onSubmit"> {
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  onChange?: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  onFocus?: () => void;
+  onBlur?: () => void;
+}
+
+export function TextInput({ onChange, onSubmit, ...rest }: TextInputProps) {
+  return createElement("vs-textinput", {
+    ...rest,
+    onChange: onChange ? (payload: any) => onChange(String(payload?.value ?? "")) : undefined,
+    onSubmit: onSubmit ? (payload: any) => onSubmit(String(payload?.value ?? "")) : undefined,
+  });
+}
+
+export interface NativeViewProps extends CommonProps {
+  /** Id of a component factory registered in the C++ NativeRegistry. */
+  nativeId: string;
+}
+
+export function NativeView(props: NativeViewProps) {
+  return createElement("vs-native", props);
+}

package/src/render.tsx

@@ -0,0 +1,37 @@
+import Reconciler from "react-reconciler";
+import { LegacyRoot } from "react-reconciler/constants";
+import type { ReactNode } from "react";
+import { hostConfig } from "./hostConfig";
+import { flushOps } from "./bridge";
+
+const reconciler = Reconciler(hostConfig as any);
+
+let container: ReturnType<typeof reconciler.createContainer> | null = null;
+
+/** Mounts (or re-renders) the app into the plugin window. */
+export function render(element: ReactNode): void {
+  if (!container) {
+    container = reconciler.createContainer(
+      {},
+      LegacyRoot,
+      null,
+      false,
+      null,
+      "vsreact",
+      (error: unknown) => console.error("[vsreact] recoverable error:", error),
+      null,
+    );
+  }
+
+  reconciler.updateContainer(element, container, null, null);
+  flushOps();
+}
+
+/** Unmounts the current app (used by hot reload teardown). */
+export function unmount(): void {
+  if (container) {
+    reconciler.updateContainer(null, container, null, null);
+    flushOps();
+    container = null;
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,89 @@
+// Environment shims for QuickJS. This module MUST be imported before react —
+// it provides the timer/console/microtask facilities react and the scheduler
+// expect. The __vsreact_* natives are registered by the C++ host; when absent
+// (e.g. under `bun test`) the shims fall back to the platform implementations.
+
+export type NativeFns = {
+  __vsreact_flush(json: string): void;
+  __vsreact_nativeCall(name: string, argsJson: string): string;
+  __vsreact_log(level: string, msg: string): void;
+  __vsreact_setTimer(id: number, ms: number): void;
+  __vsreact_clearTimer(id: number): void;
+};
+
+const g = globalThis as typeof globalThis & Partial<NativeFns> & Record<string, unknown>;
+
+export const isHosted = typeof g.__vsreact_setTimer === "function";
+
+interface TimerEntry {
+  cb: (...args: unknown[]) => void;
+  args: unknown[];
+  intervalMs?: number;
+}
+
+let nextTimerId = 1;
+const timers = new Map<number, TimerEntry>();
+
+/** Called by bridge.ts when C++ dispatches {kind:"timer",id}. */
+export function fireTimer(id: number): void {
+  const entry = timers.get(id);
+  if (!entry) return;
+
+  if (entry.intervalMs !== undefined) g.__vsreact_setTimer!(id, entry.intervalMs);
+  else timers.delete(id);
+
+  entry.cb(...entry.args);
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return `${value.message}\n${value.stack ?? ""}`;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+if (isHosted) {
+  g.setTimeout = ((cb: TimerEntry["cb"], ms = 0, ...args: unknown[]) => {
+    const id = nextTimerId++;
+    timers.set(id, { cb, args });
+    g.__vsreact_setTimer!(id, Math.max(0, ms | 0));
+    return id;
+  }) as typeof setTimeout;
+
+  g.setInterval = ((cb: TimerEntry["cb"], ms = 0, ...args: unknown[]) => {
+    const id = nextTimerId++;
+    const intervalMs = Math.max(1, ms | 0);
+    timers.set(id, { cb, args, intervalMs });
+    g.__vsreact_setTimer!(id, intervalMs);
+    return id;
+  }) as typeof setInterval;
+
+  g.clearTimeout = g.clearInterval = ((id?: number) => {
+    if (id !== undefined && timers.delete(id)) g.__vsreact_clearTimer!(id);
+  }) as typeof clearTimeout;
+
+  const makeLog =
+    (level: string) =>
+    (...args: unknown[]) =>
+      g.__vsreact_log!(level, args.map(stringify).join(" "));
+
+  g.console = {
+    log: makeLog("log"),
+    info: makeLog("info"),
+    debug: makeLog("debug"),
+    warn: makeLog("warn"),
+    error: makeLog("error"),
+  } as Console;
+
+  g.queueMicrotask ??= (cb: VoidFunction) => {
+    Promise.resolve().then(cb);
+  };
+
+  g.performance ??= { now: () => Date.now() } as Performance;
+  g.process ??= { env: { NODE_ENV: "production" } } as unknown as typeof process;
+  g.self ??= g as unknown as Window & typeof globalThis;
+  g.global ??= g;
+}

package/src/theme.ts

@@ -0,0 +1,84 @@
+export type ThemeColors = Record<string, string>;
+
+// Tailwind v3 palettes (the curated subset VSReacT ships with).
+const palettes: Record<string, Record<string, string>> = {
+  zinc: {
+    "50": "#fafafa", "100": "#f4f4f5", "200": "#e4e4e7", "300": "#d4d4d8",
+    "400": "#a1a1aa", "500": "#71717a", "600": "#52525b", "700": "#3f3f46",
+    "800": "#27272a", "900": "#18181b", "950": "#09090b",
+  },
+  neutral: {
+    "50": "#fafafa", "100": "#f5f5f5", "200": "#e5e5e5", "300": "#d4d4d4",
+    "400": "#a3a3a3", "500": "#737373", "600": "#525252", "700": "#404040",
+    "800": "#262626", "900": "#171717", "950": "#0a0a0a",
+  },
+  lime: {
+    "50": "#f7fee7", "100": "#ecfccb", "200": "#d9f99d", "300": "#bef264",
+    "400": "#a3e635", "500": "#84cc16", "600": "#65a30d", "700": "#4d7c0f",
+    "800": "#3f6212", "900": "#365314", "950": "#1a2e05",
+  },
+  red: {
+    "50": "#fef2f2", "100": "#fee2e2", "200": "#fecaca", "300": "#fca5a5",
+    "400": "#f87171", "500": "#ef4444", "600": "#dc2626", "700": "#b91c1c",
+    "800": "#991b1b", "900": "#7f1d1d", "950": "#450a0a",
+  },
+  amber: {
+    "50": "#fffbeb", "100": "#fef3c7", "200": "#fde68a", "300": "#fcd34d",
+    "400": "#fbbf24", "500": "#f59e0b", "600": "#d97706", "700": "#b45309",
+    "800": "#92400e", "900": "#78350f", "950": "#451a03",
+  },
+  emerald: {
+    "50": "#ecfdf5", "100": "#d1fae5", "200": "#a7f3d0", "300": "#6ee7b7",
+    "400": "#34d399", "500": "#10b981", "600": "#059669", "700": "#047857",
+    "800": "#065f46", "900": "#064e3b", "950": "#022c22",
+  },
+  sky: {
+    "50": "#f0f9ff", "100": "#e0f2fe", "200": "#bae6fd", "300": "#7dd3fc",
+    "400": "#38bdf8", "500": "#0ea5e9", "600": "#0284c7", "700": "#0369a1",
+    "800": "#075985", "900": "#0c4a6e", "950": "#082f49",
+  },
+};
+
+let themeColors: ThemeColors = {};
+
+export function setThemeColors(colors: ThemeColors): void {
+  themeColors = { ...themeColors };
+  for (const [name, value] of Object.entries(colors))
+    themeColors[name] = value.toLowerCase();
+}
+
+/** Resolves a color name ("zinc-900", "white", "accent", "lime-400/20",
+    "[#c6f135]") to "#rrggbb"/"#rrggbbaa", or undefined if unknown. */
+export function resolveColor(name: string): string | undefined {
+  let base = name;
+  let alpha: string | undefined;
+
+  const slash = name.lastIndexOf("/");
+  if (slash > 0) {
+    const pct = Number(name.slice(slash + 1));
+    if (Number.isFinite(pct)) {
+      base = name.slice(0, slash);
+      alpha = Math.round((pct / 100) * 255)
+        .toString(16)
+        .padStart(2, "0");
+    }
+  }
+
+  let hex: string | undefined;
+
+  if (base.startsWith("[#") && base.endsWith("]")) hex = base.slice(1, -1).toLowerCase();
+  else if (base === "white") hex = "#ffffff";
+  else if (base === "black") hex = "#000000";
+  else if (base === "transparent") hex = "#00000000";
+  else if (themeColors[base]) hex = themeColors[base];
+  else {
+    const dash = base.lastIndexOf("-");
+    if (dash > 0) {
+      const palette = palettes[base.slice(0, dash)];
+      hex = palette?.[base.slice(dash + 1)];
+    }
+  }
+
+  if (hex === undefined) return undefined;
+  return alpha !== undefined && hex.length === 7 ? hex + alpha : hex;
+}

package/src/tw.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import { configureTheme, tw } from "./tw";
+
+describe("tw resolver", () => {
+  test("layout, palette color, radius, border with opacity suffix", () => {
+    const r = tw("flex-1 flex-row bg-zinc-950 rounded-xl border border-lime-400/20 p-4");
+    expect(r.style).toEqual({
+      flex: 1,
+      flexDirection: "row",
+      backgroundColor: "#09090b",
+      borderRadius: 12,
+      borderWidth: 1,
+      borderColor: "#a3e63533",
+      padding: 16,
+    });
+    expect(r.hoverStyle).toBeUndefined();
+  });
+
+  test("hover variant routes to hoverStyle", () => {
+    const r = tw("bg-zinc-900 hover:bg-lime-300 active:bg-lime-500 focus:border-lime-400");
+    expect(r.style).toEqual({ backgroundColor: "#18181b" });
+    expect(r.hoverStyle).toEqual({ backgroundColor: "#bef264" });
+    expect(r.activeStyle).toEqual({ backgroundColor: "#84cc16" });
+    expect(r.focusStyle).toEqual({ borderColor: "#a3e635" });
+  });
+
+  test("theme tokens", () => {
+    configureTheme({ colors: { accent: "#C6F135", well: "#0C0E0C" } });
+    const r = tw("bg-well text-accent border-accent/35");
+    expect(r.style.backgroundColor).toBe("#0c0e0c");
+    expect(r.style.color).toBe("#c6f135");
+    expect(r.style.borderColor).toBe("#c6f13559");
+  });
+
+  test("arbitrary values", () => {
+    const r = tw("w-[123] h-[45%] bg-[#C6F135] p-[7]");
+    expect(r.style).toEqual({
+      width: 123,
+      height: "45%",
+      backgroundColor: "#c6f135",
+      padding: 7,
+    });
+  });
+
+  test("spacing scale, fractions, full, directional padding/margin", () => {
+    const r = tw("w-full h-1/2 px-3 py-1.5 mt-2 -mb-1 gap-2 gap-x-4");
+    expect(r.style).toEqual({
+      width: "100%",
+      height: "50%",
+      paddingLeft: 12,
+      paddingRight: 12,
+      paddingTop: 6,
+      paddingBottom: 6,
+      marginTop: 8,
+      marginBottom: -4,
+      gap: 8,
+      columnGap: 16,
+    });
+  });
+
+  test("text utilities", () => {
+    const r = tw("text-sm font-bold text-center text-zinc-400 leading-5 tracking-wide");
+    expect(r.style).toEqual({
+      fontSize: 14,
+      fontWeight: 700,
+      textAlign: "center",
+      color: "#a1a1aa",
+      lineHeight: 20,
+      letterSpacing: 0.4,
+    });
+    expect(tw("font-mono").style).toEqual({ fontFamily: "monospace" });
+  });
+
+  test("alignment, position, shadow, opacity, overflow, cursor", () => {
+    const r = tw(
+      "items-center justify-between absolute inset-0 top-2 shadow-lg opacity-50 overflow-hidden cursor-pointer",
+    );
+    expect(r.style).toEqual({
+      alignItems: "center",
+      justifyContent: "space-between",
+      position: "absolute",
+      left: 0,
+      right: 0,
+      bottom: 0,
+      top: 8,
+      shadowColor: "#00000066",
+      shadowRadius: 12,
+      shadowOffsetY: 4,
+      opacity: 0.5,
+      overflow: "hidden",
+      cursor: "pointer",
+    });
+  });
+
+  test("per-corner radius", () => {
+    const r = tw("rounded-t-lg rounded-br-full");
+    expect(r.style).toEqual({
+      borderTopLeftRadius: 8,
+      borderTopRightRadius: 8,
+      borderBottomRightRadius: 9999,
+    });
+  });
+
+  test("unknown classes are ignored", () => {
+    const r = tw("bg-zinc-900 not-a-real-class");
+    expect(r.style).toEqual({ backgroundColor: "#18181b" });
+  });
+
+  test("later classes win", () => {
+    const r = tw("bg-zinc-900 bg-zinc-800");
+    expect(r.style.backgroundColor).toBe("#27272a");
+  });
+});