Initial Commit

packages/ui/react/react-audio/src/components/premium-player/premium-player.md

@@ -0,0 +1,88 @@
+# `<PremiumPlayer>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<PremiumPlayer>` is the full-featured media-player surface — a
+composition of `<AudioPlayer>`, `<AudioVisualizer>`, and
+`<MasterMeter>` arranged as a single instrument panel. It is intended
+for hero player surfaces (landing pages, profile pages, demo apps)
+that want the whole monitoring suite without forcing consumers to
+wire three components by hand.
+
+Every behavioural guarantee of the underlying components applies:
+the player polls plugin state, the visualiser reads block samples
+from the named bus, and the meter computes peak / RMS / hold envelope
+on every UI tick. None of the three sub-components share state; they
+compose by sitting in the same DOM section.
+
+## Features
+
+- Bundles `<AudioPlayer>` + `<AudioVisualizer>` + `<MasterMeter>`.
+- Routes a single `busName` to both the visualiser and the meter so
+  they show the same source.
+- Forwards `src` to the player for auto-load on mount.
+- Adds the `.rax-premium-player` class for theming.
+
+## Usage: Basic Example
+
+```tsx
+import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
+import { AudioProvider, PremiumPlayer } from "@suaveplan/react-audio";
+
+const plugin = new AudioPlayerPlugin({});
+
+export function Hero() {
+    return (
+        <AudioProvider>
+            <PremiumPlayer plugin={plugin} src="https://cdn/hero.wav" />
+        </AudioProvider>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { AudioPlayerPlugin } from "@suaveplan/audio-fx-plugin-audio-player";
+import { AudioProvider, PremiumPlayer } from "@suaveplan/react-audio";
+
+const plugin = new AudioPlayerPlugin({});
+
+export function AuxBusPlayer() {
+    return (
+        <AudioProvider>
+            <PremiumPlayer
+                plugin={plugin}
+                src="https://cdn/aux.wav"
+                busName="auxA"
+                className="aux-hero"
+            />
+        </AudioProvider>
+    );
+}
+```
+
+## API Reference
+
+| Prop        | Type                | Default     | Notes                                              |
+| ----------- | ------------------- | ----------- | -------------------------------------------------- |
+| `plugin`    | `AudioPlayerPlugin` | —           | Required.                                          |
+| `src`       | `string \| undef`   | —           | Forwarded to `<AudioPlayer>` for auto-load.        |
+| `busName`   | `string \| undef`   | `"master"`  | Routed to the visualiser and meter.                |
+| `className` | `string \| undef`   | —           | Forwarded; merged with `rax-premium-player`.       |
+
+## Implementation Notes
+
+The composition only forwards the `busName` to the visualiser + meter
+when one is supplied — otherwise the sub-components fall back to
+their own `"master"` defaults, which keeps the API surface honest
+about what we are choosing for the user. The player sub-component
+also receives the `src` only when it is defined, so the auto-load
+effect inside `<AudioPlayer>` doesn't run with `undefined` and trip a
+guard. There is no separate state in this component; it is pure
+composition. New monitoring sub-components (e.g. spectrum analysers,
+oscilloscope) can be added inline without changing the prop signature.