first commit

docs/ui/react/react-audio/src/components/audio-visualizer/audio-visualizer.md

@@ -0,0 +1,90 @@
+# `<AudioVisualizer>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<AudioVisualizer>` is a canvas-based visualiser for a published bus.
+It subscribes through the foundation `useBus` hook (default `"master"`)
+and renders one of three modes — waveform, spectrum, or level — into a
+`<canvas>` at the configured tick rate. The component is read-only and
+allocates exactly one scratch `Float32Array` per mount so the
+per-frame path is allocation-free in steady state.
+
+The visualiser is intentionally agnostic about the source: anything
+that publishes to the named bus shows up. When no publisher exists
+the canvas paints the background only.
+
+## Features
+
+- Three modes: `"waveform"`, `"spectrum"`, `"level"`.
+- Configurable width, height, foreground colour, and background.
+- `sampleRateHz` controls the tick rate (clamped to `>= 1`).
+- `busName` selects which bus to render (default `"master"`).
+- `role="img"` + descriptive `aria-label` for screen readers.
+- Drawing primitives (`drawWaveform` / `drawSpectrum` / `drawLevel`)
+  are individually exported as `@internal` for test coverage.
+
+## Usage: Basic Example
+
+```tsx
+import { AudioProvider, AudioVisualizer } from "@suaveplan/react-audio";
+
+export function App() {
+    return (
+        <AudioProvider>
+            <AudioVisualizer />
+        </AudioProvider>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { AudioProvider, AudioVisualizer } from "@suaveplan/react-audio";
+
+export function MultiVisualizer() {
+    return (
+        <AudioProvider>
+            <AudioVisualizer mode="waveform" />
+            <AudioVisualizer mode="spectrum" busName="auxA" />
+            <AudioVisualizer
+                mode="level"
+                color="#0f0"
+                backgroundColor="#000"
+                width={128}
+                height={32}
+                sampleRateHz={120}
+            />
+        </AudioProvider>
+    );
+}
+```
+
+## API Reference
+
+| Prop              | Type                | Default     | Notes                                          |
+| ----------------- | ------------------- | ----------- | ---------------------------------------------- |
+| `className`       | `string \| undef`   | —           | Forwarded to the `<canvas>`.                   |
+| `width`           | `number \| undef`   | `320`       | Canvas pixel width.                            |
+| `height`          | `number \| undef`   | `80`        | Canvas pixel height.                           |
+| `mode`            | `VisualizerMode`    | `"waveform"`| One of the three render modes.                 |
+| `busName`         | `string \| undef`   | `"master"`  | Which bus to read.                             |
+| `sampleRateHz`    | `number \| undef`   | `60`        | Render tick rate.                              |
+| `color`           | `string \| undef`   | `"#3aa"`    | Foreground colour.                             |
+| `backgroundColor` | `string \| undef`   | `"#111"`    | Canvas background colour.                      |
+
+## Implementation Notes
+
+The effect resolves the canvas context once on mount via
+`canvas.getContext("2d")` and gracefully short-circuits when the
+context cannot be acquired (test environments without canvas support,
+or production browsers under aggressive accessibility settings). When
+the bus has no publisher the visualiser still ticks the canvas to
+keep the background paint fresh. Spectrum mode uses a naive average
+of `Math.abs` over a downsampled window rather than a real FFT — this
+is deliberate so the component has zero non-React runtime dependencies
+and remains universally portable.