suaveplan/openspec/specs/react-audio/spec.md

<!-- markdownlint-disable MD024 -->

# Capability Spec: react-audio

**Package**: `@suaveplan/react-audio`
**Status**: Phase 1 of 3 shipped (foundation: provider + hooks + stores + error codes + a11y helpers).

> This is the canonical spec. Phase 2 (`enterprise-react-audio-components`) will append component requirements; Phase 3 (`enterprise-react-audio-midi`) will append the MIDI learn-mode panel requirements. Phase 1 requirements remain unchanged across those additions.

## Requirements

### Requirement: React-tier purity — no engine, no audio context

`@suaveplan/react-audio` SHALL import zero browser-only audio APIs (`AudioContext`, `OfflineAudioContext`, `AudioNode`, `AudioWorklet`) and zero Node-only APIs (`node:fs`, `node:path`, `process`, `Buffer`). All audio surface is reached through `@suaveplan/audio-engine-browser`, `@suaveplan/audio-fx-plugin-base`, `@suaveplan/audio-timeline`, `@suaveplan/audio-transport`, and `@suaveplan/audio-controllers`. The package's runtime `dependencies` SHALL be limited to those five workspace packages plus `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry`, `zustand`, `zod`, and `tslib`. `react` SHALL be a `peerDependency` only.

#### Scenario: built dist references no audio context or Node globals

- **WHEN** the built `dist/` is grep'd
- **THEN** it MUST NOT reference `AudioContext`, `OfflineAudioContext`, `AudioNode`, `node:fs`, `node:path`, `process`, or `Buffer`

**Verified by:** `tests/purity.test.ts::"dist references no audio context or Node globals"` AND `tests/purity.test.ts::"runtime dependency set matches the allowlist"`

---

### Requirement: AudioProvider strict-mode safety

The package SHALL export an `AudioProvider` React component constructed from `AudioProviderOptions` (validated by Zod at construction). On mount, it SHALL asynchronously construct exactly one `BrowserTimelineAdapter`, one `TimelineEngine`, one `Transport`, one `DefaultBusRegistry`, and one `PluginRegistry`, await the adapter's `init()` (forwarding an `AbortSignal` cancellable on unmount), and publish the resulting state to its React context. Under React 19 Strict Mode the mount → unmount → re-mount cycle SHALL NOT produce two engines: the provider SHALL track its async construction with a cancellation flag and dispose any in-flight adapter if the effect is torn down before init resolves. On unmount the provider SHALL synchronously call `adapter.dispose()`, `transport.dispose()`, and close every active `SidechainPublisher`.

#### Scenario: strict-mode double-invoke produces exactly one engine

- **WHEN** the provider is rendered under React Strict Mode and the first effect is invoked, torn down, and re-invoked
- **THEN** exactly one `BrowserTimelineAdapter` is ever fully initialised at any time, the cancelled construction's adapter is disposed, and no `AudioContext` is leaked

#### Scenario: unmount tears down the engine

- **WHEN** the provider unmounts
- **THEN** `adapter.dispose()`, `transport.dispose()`, and `busRegistry.close()` are each called exactly once, in that order

**Verified by:** `src/provider/audio-provider.test.tsx::"strict-mode double-invoke produces exactly one engine fully initialised"` AND `src/provider/audio-provider.test.tsx::"unmount tears down adapter, transport, and bus registry exactly once"`

---

### Requirement: AudioProvider exposes engine state to consumers

The provider's React context SHALL carry `{ state: ProviderState | null, engineState, error, version }` where `state === null` during the async init window and the engine readiness state is reported via a `useEngineState(): 'pending' | 'ready' | 'error'` hook. `ProviderState` SHALL expose readonly `engine: BrowserTimelineAdapter`, `timeline: TimelineEngine`, `transport: Transport`, `buses: ProviderBusRegistry`, `chains: ChainMap`, `registry: PluginRegistry`, `presetStore: PresetStore | undefined`, `sampleRateHz: number`. Hooks SHALL throw `ReactAudioError` with code `REACT_AUDIO.NO_PROVIDER` if called outside an `AudioProvider`, and throw `ReactAudioError` with code `REACT_AUDIO.PROVIDER_PENDING` if called against a provider whose engine is still initialising AND the hook is not the `useEngineState` reader.

#### Scenario: hook outside provider throws REACT_AUDIO.NO_PROVIDER

- **WHEN** `useTransport()` is rendered without an `AudioProvider` ancestor
- **THEN** the render throws `ReactAudioError` whose `code === "REACT_AUDIO.NO_PROVIDER"`

#### Scenario: useEngineState reports pending → ready

- **WHEN** the provider mounts and async init resolves
- **THEN** `useEngineState()` first returns `'pending'`, then transitions to `'ready'` on the next React commit; consumers that gated on `state !== null` re-render once

**Verified by:** `src/hooks/use-engine-state/use-engine-state.test.tsx::"hook outside provider throws REACT_AUDIO.NO_PROVIDER"` AND `src/hooks/use-engine-state/use-engine-state.test.tsx::"reports pending then ready across the init lifecycle"`

---

### Requirement: Hook subscription model is concurrent-safe and SSR-consistent

Every hook that reflects engine state (`useTransport`, `useTransportTime`, `useEngineState`, `useTrack`, `usePluginChain`, `useChainPlugin`, `useParameter`, `usePreset`, `useChainSnapshot`, `useBus`, `useAudioFxPlugin`) SHALL use `useSyncExternalStore` for its subscription where applicable. The subscribe callback SHALL register against the source entity's own event surface (no module-level event hub). The server snapshot SHALL equal the client snapshot for the same source. Hooks SHALL NOT re-render at audio-block rate; per-block values (parameter automation, transport time) SHALL be sampled at `requestAnimationFrame`/interval rate (configurable via the provider's `sampleRateHz` option, default 60).

#### Scenario: useTransportTime samples at frame rate, not block rate

- **WHEN** transport advances and the consumer renders for 100 ms with `sampleRateHz: 60`
- **THEN** the React component using `useTransportTime` re-renders at most 7 times (60 Hz × 100 ms + 1)

#### Scenario: SSR snapshot equals first client render

- **WHEN** a component using `useParameter` is rendered to a string on the server and hydrated on the client
- **THEN** the SSR HTML and the first client render's output are byte-identical (no hydration mismatch)

**Verified by:** `src/hooks/use-transport-time/use-transport-time.test.tsx::"samples at frame rate, not audio-block rate"` AND `src/hooks/use-parameter/use-parameter.test.tsx::"SSR snapshot equals first client render"`

---

### Requirement: useParameter reads, writes, and curves through the plugin

`useParameter(plugin, paramId)` SHALL return `{ value: number, set(value): void, curve(curve): void, scheduleAt(value, transportTimeSec): void }`. `value` SHALL reflect the current parameter value, sampled at the provider's `sampleRateHz`. `set` SHALL call `plugin.setParameter(paramId, value)`. `curve` SHALL call `plugin.setParameterCurve(paramId, curve)`. `scheduleAt` SHALL call `plugin.setParameterAt(paramId, value, transportTimeSec)`. A hook for an unknown `paramId` SHALL throw `ReactAudioError` with code `REACT_AUDIO.UNKNOWN_PARAMETER` on first render.

#### Scenario: set writes through to the plugin and value updates on next sample tick

- **WHEN** a component calls `setParameter(0.5)` for a parameter whose declared range is `[0, 1]`
- **THEN** the plugin observes `getParameter(id) === 0.5` and the hook's `value` re-renders to `0.5` on the next RAF sample tick

#### Scenario: unknown parameter throws REACT_AUDIO.UNKNOWN_PARAMETER

- **WHEN** `useParameter(plugin, 'nonexistent')` renders
- **THEN** the render throws `ReactAudioError` whose `code === "REACT_AUDIO.UNKNOWN_PARAMETER"` with the offending id in `context`

**Verified by:** `src/hooks/use-parameter/use-parameter.test.tsx::"set writes through to the plugin and value updates"` AND `src/hooks/use-parameter/use-parameter.test.tsx::"unknown paramId throws REACT_AUDIO.UNKNOWN_PARAMETER"`

---

### Requirement: usePluginChain reflects chain composition and events

`usePluginChain(trackId)` SHALL return `{ chain: PluginChain, plugins: ReadonlyArray<AudioFxPlugin>, add(plugin, at?), remove(idOrIndex), move(from, to), replace(idOrIndex, plugin), bypass(idOrIndex, bypassed), snapshot(), restore(input) }`. The `plugins` array SHALL be subscribed to the chain's `plugin-added`, `plugin-removed`, `plugin-moved`, `plugin-replaced`, and `bypass-changed` events and re-render the consuming component when any fire. Subscription cleanup on unmount SHALL be exact (no leaked listeners).

#### Scenario: adding a plugin re-renders the consumer with the new list

- **WHEN** a component using `usePluginChain` calls `add(eqPlugin)` and the chain emits `plugin-added`
- **THEN** the component re-renders once with `plugins.length` increased by one and `plugins[plugins.length - 1] === eqPlugin`

#### Scenario: unmount removes every listener

- **WHEN** the component using `usePluginChain` unmounts
- **THEN** the chain's listener count for the subscribed events returns to its pre-mount baseline

**Verified by:** `src/hooks/use-plugin-chain/use-plugin-chain.test.tsx::"adding a plugin re-renders the consumer with the new list"` AND `src/hooks/use-plugin-chain/use-plugin-chain.test.tsx::"unmount removes every listener"`

---

### Requirement: Structured error codes

The package SHALL declare its codes via `defineCodes("REACT_AUDIO", [...])` from `@suaveplan/error`, producing the dotted codes `REACT_AUDIO.NO_PROVIDER`, `REACT_AUDIO.PROVIDER_PENDING`, `REACT_AUDIO.UNKNOWN_PARAMETER`, `REACT_AUDIO.PRESET_STORE_FAILED`, and `REACT_AUDIO.INVALID_OPTIONS`. The package SHALL export `ReactAudioErrorCode`, `REACT_AUDIO_ERROR_METADATA`, `registerReactAudioErrorCodes()`, and a `ReactAudioError` class extending `SuaveplanError` from `@suaveplan/error`. Every error thrown by the package SHALL be a `ReactAudioError` and carry one of these codes, `cause`, and `context`. Every registered code SHALL be reachable from a real call site exercised by tests.

#### Scenario: every registered code is thrown by a call site

- **WHEN** the test suite runs
- **THEN** each code in `REACT_AUDIO_ERROR_METADATA` is asserted thrown by at least one test

**Verified by:** `src/error-codes/error-codes.test.ts::"every REACT_AUDIO code is reachable from a call site"`

---

### Requirement: Foundation subpath exports

`package.json` SHALL declare subpath exports for every Phase-1 surface: `.` (foundation barrel covering provider + hooks + stores + error codes + a11y helpers + Phase-2 components), `./provider`, `./hooks`, `./hooks/<hook-name>` per hook, `./stores`, `./a11y`, `./error-codes`. `sideEffects` SHALL be `false`. A consumer importing `@suaveplan/react-audio/hooks/use-transport` SHALL NOT pull in the other hooks' modules beyond shared internals.

#### Scenario: every Phase-1 surface has a subpath entry

- **WHEN** the test suite inspects `package.json` exports
- **THEN** every Phase-1 surface (provider, every hook in the declared hook list, stores, a11y, error-codes) has its own `./<surface>` entry

**Verified by:** `tests/exports.test.ts::"every Phase-1 surface has a subpath export entry"`

---

### Requirement: Generic PluginSlot renders any AudioFxPlugin

The package SHALL export `<PluginSlot plugin />` that renders any `AudioFxPlugin` by:

1. reading `plugin.metadata` for the slot header (name + version + category badge),
2. iterating `plugin.parameters` (declaration order) and rendering each via a renderer chosen by the parameter's `unit` / `scale` / `min`/`max` declaration (boolean → toggle, `unit: 'db'` → log slider, `unit: 'hz'` → log knob with octave snap, `unit: 'enum'` → segmented control, default → linear slider),
3. rendering a bypass toggle wired to the chain-level bypass,
4. rendering a preset selector populated from `plugin.getPreset()` snapshots stored via the provider's preset store,
5. exposing an `advanced` toggle that reveals parameters declared with `category === 'advanced'`.

The provider's `slotRenderers` option SHALL accept `Record<string /* plugin.metadata.id */, ComponentType<PluginSlotRendererProps>>`; a registered renderer SHALL supersede the generic slot for that plugin id. Every rendered parameter control SHALL be keyboard-driven per the "Accessibility" requirement below.

#### Scenario: every parameter renders a control bound to its plugin

- **WHEN** `<PluginSlot plugin={eq}>` is rendered for an EQ with 5 parameters
- **THEN** 5 control elements are rendered, each with `role` matching its parameter type and a label equal to the parameter's `name`

#### Scenario: registered specialised renderer supersedes the generic slot

- **WHEN** the provider's `slotRenderers` maps `eq` to `<EQPanel />` and `<PluginSlot plugin={eq}>` is rendered
- **THEN** `<EQPanel />` renders in place of the generic slot

**Verified by:** `src/components/plugin-slot/plugin-slot.test.tsx::"renders one control per parameter with correct role and label"` AND `src/components/plugin-slot/plugin-slot.test.tsx::"registered specialised renderer supersedes the generic slot"`

---

### Requirement: PluginChainView drag/drop with IO validation

`<PluginChainView chain />` SHALL render the chain's plugins as a list of `<PluginSlot>`s and SHALL support drag-to-reorder (HTML5 DnD with a keyboard alternative using `Space` to pick up / `Arrow` to move / `Enter` to drop) and drop-to-insert from a plugin picker. Insertions SHALL be validated against `chain.add()` and rejections SHALL surface in a non-blocking toast with the underlying `AudioFxError`'s `code`. A keyboard "Add FX" menu SHALL list `PluginRegistry.list()` filtered by IO compatibility with the chain's current effective output channel count.

#### Scenario: drop with incompatible IO surfaces the error

- **WHEN** a user drops a 5.1-channel plugin into a 2-channel chain
- **THEN** insertion is rejected with `AudioFxError` whose `code === "AUDIO_FX.CHAIN_IO_INCOMPATIBLE"`, a toast appears with the error message, and the chain is unchanged

#### Scenario: keyboard reorder moves a slot

- **WHEN** a user focuses the third slot, presses `Space`, presses `ArrowUp`, presses `Enter`
- **THEN** `chain.move(2, 1)` was called and the slot's new index is 1

**Verified by:** `src/components/plugin-chain-view/plugin-chain-view.test.tsx::"drop with incompatible IO surfaces AUDIO_FX.CHAIN_IO_INCOMPATIBLE"` AND `src/components/plugin-chain-view/plugin-chain-view.test.tsx::"keyboard reorder moves a slot"`

---

### Requirement: Accessibility — keyboard and screen-reader

Every parameter control rendered by `<PluginSlot>` SHALL implement: `←`/`→` for fine step (1 % of declared range), `↑`/`↓` for coarse step (10 %), `PageUp`/`PageDown` for ×10 coarse, `Home`/`End` for `min`/`max`, `Enter` to type-edit a value, `Shift` multiplier ×10, `Alt` divider ÷10. Each SHALL carry `role="slider"`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` formatted with the parameter's `unit` (e.g. `"+3.5 dB"`, `"880 Hz"`, `"50 %"`). Animations SHALL respect `prefers-reduced-motion`. Focus indicators SHALL pass WCAG AAA contrast.

#### Scenario: arrow keys adjust a knob by the declared step

- **WHEN** a user focuses a parameter knob whose range is `[-24, 24]` (dB) and presses `→`
- **THEN** the parameter advances by 0.48 (1 % of 48); `aria-valuenow` and `aria-valuetext` reflect the new value

#### Scenario: aria-valuetext includes the parameter unit

- **WHEN** a user inspects the aria attributes of a frequency knob set to 880
- **THEN** `aria-valuetext === "880 Hz"`

**Verified by:** `src/components/plugin-parameter-knob/plugin-parameter-knob.test.tsx::"arrow keys adjust the knob by the declared step"` AND `src/components/plugin-parameter-knob/plugin-parameter-knob.test.tsx::"aria-valuetext includes the parameter unit"`

---

### Requirement: ChainSnapshot save / restore through PresetManager

`<PresetManager chain />` SHALL render save / load / delete controls for the chain. `Save` SHALL call `chain.snapshot()`, validate the result against the `ChainSnapshot` Zod schema (re-exported from `@suaveplan/audio-fx-plugin-base`), and persist it to the provider's preset store (default: `localStorage`-backed; consumers MAY inject a different store). `Load` SHALL call `chain.restore(snapshot, provider.registry)`. A failure SHALL surface as a toast carrying the underlying `AudioFxError`'s `code`. Cross-component subscriptions to the preset list SHALL re-render on save / delete via `useChainSnapshot(chain)`.

#### Scenario: save persists a snapshot that load round-trips

- **WHEN** a user clicks `Save`, then clears the chain by removing every plugin, then clicks the saved preset
- **THEN** the chain is restored to the saved order with the saved parameters and bypass states

#### Scenario: load failure surfaces the error

- **WHEN** a saved snapshot references a plugin type no longer in the registry
- **THEN** `restore` rejects with `AudioFxError` whose `code === "AUDIO_FX.CHAIN_SLOT_NOT_FOUND"` and a toast displays the missing pluginType

**Verified by:** `src/components/preset-manager/preset-manager.test.tsx::"save persists a snapshot that load round-trips"` AND `src/components/preset-manager/preset-manager.test.tsx::"load failure surfaces AUDIO_FX.CHAIN_SLOT_NOT_FOUND"`

---

### Requirement: Storybook coverage gate

Every exported component (including the foundation's `<AudioProvider>` once Phase 2 lands) SHALL ship at least three Storybook stories: a default (representative props), an interactive (a control that demonstrates state transitions), and an edge-case (empty / loading / error / max-state). The CI gate SHALL refuse a change that introduces a component without all three story types.

#### Scenario: every component has at least three story types

- **WHEN** `tests/exports.test.ts::"every component has default, interactive, and edge-case Storybook stories"` runs
- **THEN** for every exported component the corresponding `*.stories.tsx` file declares stories whose names match the regex `/^(Default|Interactive|Edge.*)$/`

**Verified by:** `tests/exports.test.ts::"every component has default, interactive, and edge-case Storybook stories"`

---

### Requirement: Component subpath exports

`package.json` SHALL declare `./components` (barrel of every component) AND `./components/<component-name>` for every exported component. Foundation subpath exports from Phase 1 SHALL remain. Tree-shaking SHALL keep `./hooks/use-transport` independent of any component bundle.

#### Scenario: every component subpath is declared

- **WHEN** the test suite inspects `package.json` exports
- **THEN** every shipped component has a `./components/<component-name>` entry AND `./components` is declared

**Verified by:** `tests/exports.test.ts::"every component has a subpath export entry"`

---

### Requirement: MidiControllerSetup learn-mode panel

`<MidiControllerSetup>` SHALL render the connected controllers from the provider's `MidiControllerRegistry` (sourced via `@suaveplan/audio-controllers`) and expose a learn-mode UI: the user selects a target parameter on a plugin, presses a control on the hardware, and the panel calls `bindParameter(plugin, paramId, capturedSource, { smoothingMs })` from `@suaveplan/audio-controllers`. Captured bindings SHALL be persisted via the provider's preset store (the same store used by `<PresetManager>`) and re-bound on next mount. An `Unbind` button SHALL invoke the unsubscribe function returned by `bindParameter`. The package SHALL also export the `useMidiController(controllerId)` hook returning the controller instance + a `learn(target)` method.

#### Scenario: learn captures the next CC and binds it

- **WHEN** a user selects `eq.lowShelfGain` as the target and the fake-device fixture emits `CC 1/7 = 64`
- **THEN** `bindParameter(eq, 'lowShelfGain', { type: 'cc', channel: 1, number: 7 })` is called and the panel shows the binding

#### Scenario: unbind removes the binding

- **WHEN** a user clicks `Unbind` on an active binding
- **THEN** subsequent CC events for that source no longer call `setParameter` on the plugin

#### Scenario: useMidiController hook subscribes to connection-state changes

- **WHEN** the controller transitions `disconnected → connecting → connected`
- **THEN** the component using `useMidiController(controllerId)` re-renders once per transition with the new state

**Verified by:** `src/components/midi-controller-setup/midi-controller-setup.test.tsx::"learn captures the next CC and binds it"` AND `src/components/midi-controller-setup/midi-controller-setup.test.tsx::"unbind removes the binding"` AND `src/hooks/use-midi-controller/use-midi-controller.test.tsx::"re-renders on connection-state transitions"`

---

### Requirement: Composed-plugin UI components

The package SHALL export `<TransportControls>`, `<TrackList>`, `<TrackRow>`, `<MasterMeter>`, `<Mixer>`, `<AudioVisualizer>`, `<AudioPlayer>`, `<BasicPlayer>`, `<PremiumPlayer>`, `<MicrophoneControls>`, `<GLaDOSControls>`, and `<PluginLoader>`. Each component SHALL compose against the foundation hooks (Phase 1) and the appropriate concrete plugin package: `<Mixer>` against `@suaveplan/audio-fx-plugin-mixer`, `<AudioPlayer>` family against `@suaveplan/audio-fx-plugin-audio-player`, `<MicrophoneControls>` against `@suaveplan/audio-fx-plugin-microphone`, `<GLaDOSControls>` against `@suaveplan/audio-fx-plugin-glados`. Each component SHALL satisfy the Storybook coverage gate (default + interactive + edge-case stories) and the accessibility requirement from Phase 2. Each SHALL have a `./components/<name>` subpath export.

#### Scenario: every composed-plugin component renders against a real instance

- **WHEN** a test renders `<Mixer>` with a real `MixerPlugin` from `@suaveplan/audio-fx-plugin-mixer` registered on the provider
- **THEN** the component renders strip controls bound to the real plugin's parameters; setting a strip's gain calls `mixerPlugin.setChannelGain` and the new value is reflected on the next sample tick

#### Scenario: subpath export per component

- **WHEN** a consumer imports `@suaveplan/react-audio/components/transport-controls`
- **THEN** the import resolves and pulls in only that component's bundle (verified by `tests/exports.test.ts`)

**Verified by:** `src/components/transport-controls/transport-controls.test.tsx::"renders against a real transport"` AND `src/components/track-list/track-list.test.tsx::"renders against a real TimelineEngine"` AND `src/components/mixer/mixer.test.tsx::"renders against a real MixerPlugin"` AND `src/components/audio-player/audio-player.test.tsx::"renders against a real AudioPlayerPlugin"` AND `src/components/microphone-controls/microphone-controls.test.tsx::"renders against a real MicrophonePlugin"` AND `src/components/glados-controls/glados-controls.test.tsx::"renders against a real GLaDOSPlugin"` AND `src/components/audio-visualizer/audio-visualizer.test.tsx::"renders a canvas bound to useAnalyser"` AND `src/components/master-meter/master-meter.test.tsx::"renders against a master analyser"` AND `src/components/plugin-loader/plugin-loader.test.tsx::"lists every registered plugin from PluginRegistry"` AND `tests/exports.test.ts::"every extras component has a subpath export entry"`

---

### Requirement: Main-branch parity restored

After the supplementary extras change archives, every component on `/mnt/s/web/suaveplan/packages/react/react-audio/src/components/` SHALL have a genesis equivalent exported from `@suaveplan/react-audio`. The parity test SHALL fail if any main-branch component family is missing on genesis.

#### Scenario: parity test enumerates every main-branch component family

- **WHEN** `tests/parity.test.ts::"every main-branch component family has a genesis equivalent"` runs
- **THEN** for every top-level directory under `/mnt/s/web/suaveplan/packages/react/react-audio/src/components/` (the test reads this list from a checked-in fixture so it stays runnable offline) there is a corresponding genesis component reachable via `@suaveplan/react-audio/components/<name>` (or another approved subpath listed in `tests/parity-fixture.ts`)

**Verified by:** `tests/parity.test.ts::"every main-branch component family has a genesis equivalent"`

---

### Requirement: Player-tier hooks — useAnalyser and usePlaylist

Added 2026-05-23 alongside `@suaveplan/react-audio-player`. The
package SHALL export two additional hooks needed by the
player-tier surface but generic enough to keep on the foundation:

- `useAnalyser(opts?: UseAnalyserOptions): UseAnalyserResult` —
  polls an `AnalyserNode`-shaped source (direct ref or lazy factory)
  and returns the latest byte-magnitude FFT frame plus the matching
  time-domain (waveform) frame. The hook does NOT create an
  `AudioContext` or add itself to the audio graph; consumers hand
  in an existing analyser (typically the engine's per-track
  analyser).
- `usePlaylist(items: readonly PlaylistItem[], opts?: UsePlaylistOptions): UsePlaylistResult` —
  pure (no engine) queue controller with `repeat: "off" | "all" |
  "one"`, `shuffle`, `next` / `prev` / `skipTo` / `setIndex`,
  per-shuffle history so `prev` reverses, and injectable RNG for
  deterministic tests.

Both hooks SHALL have `./hooks/use-analyser` and
`./hooks/use-playlist` subpath exports.

#### Scenario: useAnalyser polls a structural AnalyserLike

- **WHEN** `useAnalyser({ analyser: fake, intervalMs: 5 })` is rendered with a structural AnalyserNode test double
- **THEN** within the interval the hook calls `getByteFrequencyData` and `getByteTimeDomainData` and exposes the resulting buffers

#### Scenario: usePlaylist advances and wraps per repeat mode

- **WHEN** `usePlaylist(items, { initialRepeat: "all" })` is rendered with three items, `next()` is called at the last item
- **THEN** the cursor wraps to index 0

**Verified by:** `src/hooks/use-analyser/use-analyser.test.ts::"polls the explicit analyser and writes into the shared buffer"` AND `src/hooks/use-playlist/use-playlist.test.ts::"repeat=all wraps both directions"`

<!-- markdownlint-enable MD024 -->