# `standardized-audio-context-bridge`

## Purpose

`standardized-audio-context-bridge` is the dynamic-import wrapper for
`standardized-audio-context`'s `AudioContext` constructor. It exists as
its own file purely for testability: the package needs the dynamic
import in production code, but the success branch is unreachable under
`happy-dom` (no native Web Audio constructor) so the file is excluded
from coverage via the standard `/* istanbul ignore file */` directive.
The failure branch is still verified by the offline-render
"uses standardized-audio-context import path" test, which expects the
typed `BrowserAudioError(CONTEXT_FAILED)`.

Separating the bridge from `adapter-lifecycle.ts` keeps the lifecycle
file fully covered without sprinkling per-line ignore comments. The
bridge surface is one function: `constructStandardizedContext`.

## Features

- Single async helper that dynamically imports the shim and constructs
  an `AudioContext` with `latencyHint` + `sampleRate`.
- Translates every failure into a typed
  `BrowserAudioError(CONTEXT_FAILED)` with the original error attached
  as `cause`.
- Returns a `{ ctx, ownsContext: true }` descriptor consumed verbatim
  by `resolveContext`.

## Usage: Basic Example

```ts
import { constructStandardizedContext } from "@suaveplan/audio-engine-browser/adapter/standardized-audio-context-bridge";

const { ctx } = await constructStandardizedContext({});
```

## Usage: Advanced Example

```ts
import { constructStandardizedContext } from "@suaveplan/audio-engine-browser/adapter/standardized-audio-context-bridge";

try {
    const { ctx, ownsContext } = await constructStandardizedContext({
        latencyHint: "interactive",
        sampleRate: 48000,
    });
    await ctx.resume?.();
    // hand off to the adapter, etc.
} catch (e) {
    if (e instanceof BrowserAudioError) {
        // e.code === "AUDIO_ENGINE_BROWSER.CONTEXT_FAILED"
    }
    throw e;
}
```

## API Reference

### `constructStandardizedContext(args) → Promise<{ ctx, ownsContext }>`

- `args.latencyHint` — optional `"interactive" | "balanced" | "playback"`.
- `args.sampleRate` — optional sample rate.

Resolves to `{ ctx, ownsContext: true }` on success; rejects with
`BrowserAudioError(CONTEXT_FAILED)` on every failure (import failure,
constructor throw, missing global).

## Implementation Notes

- The dynamic `import("standardized-audio-context")` is deliberate: it
  keeps the shim out of the import graph when the package is used with
  an injected context (the only mode reachable under `happy-dom`).
- This file carries `/* istanbul ignore file */`. The justification is
  recorded in the file header: the success branch requires a real Web
  Audio runtime, which neither Node nor Bun nor happy-dom provides.
  The failure branch is still verified through the failing import
  path in `offline-render.test.ts`.
- The function is the ONLY production caller of
  `standardized-audio-context` — every other code path goes through
  `resolveContext`, which falls back to this bridge only when the
  caller did not inject a context.