first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/ui/react/react-audio/src/hooks/use-parameter/use-parameter.md
+++ b/docs/ui/react/react-audio/src/hooks/use-parameter/use-parameter.md
@@ -0,0 +1,98 @@
+# `hooks/use-parameter`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`useParameter(plugin, paramId)` is the canonical read/write hook for
+a single declared parameter on any `AudioFxPlugin`. It returns the
+parameter's current value (sampled at frame rate) and three
+write-paths: an immediate `set`, a `curve` for ramps/automation, and
+a `scheduleAt` for transport-anchored value changes.
+
+The hook throws `ReactAudioError(REACT_AUDIO.UNKNOWN_PARAMETER)`
+synchronously on first render if the `paramId` is not declared in
+the plugin's `parameterIndex` — so a typo fails fast in the render
+tree rather than silently dropping writes.
+
+## Features
+
+- Frame-rate sampled `value` (60 Hz default, configurable via
+  provider `sampleRateHz`).
+- `set(v)` → `plugin.setParameter(paramId, v)`.
+- `curve(c)` → `plugin.setParameterCurve(paramId, c)`.
+- `scheduleAt(v, t)` → `plugin.setParameterAt(paramId, v, t)`.
+- Throws `REACT_AUDIO.UNKNOWN_PARAMETER` on first render for an
+  unknown `paramId`, carrying the available ids in `context`.
+- SSR-consistent snapshots (both `getSnapshot` and
+  `getServerSnapshot` read `plugin.getParameter(paramId)`).
+
+## Usage: Basic
+
+```tsx
+import { useParameter } from "@suaveplan/react-audio";
+
+function GainKnob({ plugin }: { plugin: AudioFxPlugin }) {
+    const { value, set } = useParameter(plugin, "gain");
+    return (
+        <input
+            type="range"
+            min={0}
+            max={1}
+            step={0.01}
+            value={value}
+            onChange={(e) => set(Number(e.currentTarget.value))}
+        />
+    );
+}
+```
+
+## Usage: Advanced
+
+```tsx
+import { useParameter } from "@suaveplan/react-audio";
+
+function Sweep({ plugin }: { plugin: AudioFxPlugin }) {
+    const { curve, scheduleAt } = useParameter(plugin, "cutoff");
+    return (
+        <>
+            <button
+                type="button"
+                onClick={() =>
+                    curve({
+                        kind: "linear",
+                        startValue: 200,
+                        endValue: 8000,
+                        duration: 4,
+                    })
+                }
+            >
+                Linear sweep
+            </button>
+            <button type="button" onClick={() => scheduleAt(440, 2)}>
+                Set to 440 at t=2s
+            </button>
+        </>
+    );
+}
+```
+
+## API Reference
+
+- `useParameter(plugin, paramId): { value, set, curve, scheduleAt }`.
+
+## Implementation Notes
+
+Parameter automation can change values per audio block (~689 Hz at
+128/88.2k); the React commit cycle cannot run at that rate. The hook
+samples the live value at `sampleRateHz` (60 Hz default) via a
+`useSyncExternalStore` subscription whose subscribe path schedules a
+`setInterval` and getSnapshot path reads `plugin.getParameter(paramId)`.
+`setInterval` is used rather than `requestAnimationFrame` so the
+sampling behaves deterministically in tests (happy-dom RAF is
+synchronous-per-microtask which makes the per-frame-cap test
+impossible). The unknown-param check runs on every render —
+parameter indices are immutable on a typical plugin so the lookup is
+O(1) and the throw site is the same.