# `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.