first commit

docs/ui/react/react-audio/src/hooks/use-audio-engine/use-audio-engine.md

@@ -0,0 +1,73 @@
+# `hooks/use-audio-engine`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`useAudioEngine()` returns the full resolved `ProviderState` bundle —
+the adapter, the `TimelineEngine`, the `Transport`, the
+`ProviderBusRegistry`, the `PluginRegistry`, the consumer-supplied
+preset store (or `undefined`), and the configured `sampleRateHz`.
+It throws `REACT_AUDIO.NO_PROVIDER` outside the provider and
+`REACT_AUDIO.PROVIDER_PENDING` during the async init window. It is
+the escape hatch for code that needs the entire bundle at once;
+prefer the narrower hooks (`useTransport`, `useTimeline`, …) when
+you only need one entity, as they minimise re-render scope.
+
+## Features
+
+- Returns `ProviderState` — a readonly bundle.
+- Throws `REACT_AUDIO.NO_PROVIDER` outside `<AudioProvider>`.
+- Throws `REACT_AUDIO.PROVIDER_PENDING` while engine init is in
+  flight.
+- Stable reference across re-renders within a single ready phase.
+
+## Usage: Basic
+
+```tsx
+import { useAudioEngine } from "@suaveplan/react-audio";
+
+function Diagnostics() {
+    const { engine, transport, sampleRateHz } = useAudioEngine();
+    return (
+        <pre>
+            engine.lookAhead = {engine.lookAhead}; transport.state ={" "}
+            {transport.state}; ui-sampleRate = {sampleRateHz} Hz
+        </pre>
+    );
+}
+```
+
+## Usage: Advanced
+
+```tsx
+import { useAudioEngine } from "@suaveplan/react-audio";
+
+function useRegisterPlugin(): (type: string, factory: () => AudioFxPlugin) => void {
+    const { registry } = useAudioEngine();
+    return (type, factory) => registry.register(type, factory);
+}
+```
+
+## API Reference
+
+- `useAudioEngine(): ProviderState`.
+
+## Implementation Notes
+
+The hook delegates to `useProviderStateOrThrow`, which performs the
+two structured-error checks. The returned `ProviderState` is the
+frozen object the provider published — consumers can stash it in a
+ref without cloning. Identity is stable across renders within a
+single ready phase; if the provider remounts (Strict Mode or genuine
+remount) the bundle's identity changes, which is the correct cue for
+downstream `useEffect`s keyed on `engine`/`transport` to re-bind.
+Prefer the focused hooks (`useTransport`, `useTimeline`, …) for the
+common case of "I only need one entity"; the broader bundle returned
+here triggers re-renders only when the provider itself re-publishes
+state (the focused hooks emit narrower subscriptions). Consumers
+that want to forward the engine bundle into child components without
+re-render bloat should destructure here, then memoise the
+sub-references they pass downstream.