first commit

docs/media/audio/audio-engine-browser/src/adapter/standardized-audio-context-bridge.md

@@ -0,0 +1,81 @@
+# `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.