first commit

docs/media/audio/audio-engine-browser/src/adapter/adapter-introspection.md

@@ -0,0 +1,87 @@
+# `adapter-introspection`
+
+## Purpose
+
+`adapter-introspection` is a small support module that holds the
+`BrowserTimelineAdapter` operations that would otherwise push the
+adapter class file over its 300-line budget: FX plugin hosting and the
+project-level bus registry declarations. Each function is a thin
+delegator — the adapter still owns the lifecycle invariants
+(`assertReady`, `requireTrack`) and delegates the work here.
+
+The module is consumed directly by `browser-adapter.ts` rather than
+re-exported from the package barrel. Consumers do not call into it
+themselves — they go through the adapter's public methods.
+
+## Features
+
+- `hostFxOnTrack(rec, plugin, context, worklets, graph)` adds the
+  plugin to the track's `PluginChain`, materialises the render node
+  via `createFxNode`, and registers the node under
+  `<trackId>:fx:<pluginId>`.
+- `declareBusPublish` / `declareBusSubscribe` thin wrappers around
+  `BusOrchestrator`.
+- `busRegistry`, `processOrder` read accessors.
+- Owns the `audio_engine_browser_nodes_created_total` counter
+  increment under `kind=fx`.
+
+## Usage: Basic Example
+
+```ts
+import { hostFxOnTrack } from "@suaveplan/audio-engine-browser/adapter/adapter-introspection";
+
+await hostFxOnTrack(rec, plugin, context, worklets, graph);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    busRegistry,
+    declareBusPublish,
+    declareBusSubscribe,
+    processOrder,
+} from "@suaveplan/audio-engine-browser/adapter/adapter-introspection";
+
+declareBusPublish(orch, "kick", "kick-bus", 2);
+declareBusSubscribe(orch, "bass", "kick-bus");
+
+const order = processOrder(orch, ["kick", "bass"]);
+const registry = busRegistry(orch);
+```
+
+## API Reference
+
+### `hostFxOnTrack(rec, plugin, context, worklets, graph) → Promise<void>`
+
+Adds the plugin to the chain, calls `createFxNode` to pick the render
+path, and registers the resulting node in `graph`.
+
+### `declareBusPublish(orch, trackId, bus, channels) → void`
+
+Delegates to `BusOrchestrator.declarePublish`.
+
+### `declareBusSubscribe(orch, trackId, bus) → void`
+
+Delegates to `BusOrchestrator.declareSubscribe`.
+
+### `busRegistry(orch) → BusRegistry`
+
+Returns the orchestrator's underlying `BusRegistry`.
+
+### `processOrder(orch, trackIds) → ReadonlyArray<string>`
+
+Returns the topological order of `trackIds`.
+
+## Implementation Notes
+
+- The OTel counter is module-scoped so each `BrowserTimelineAdapter`
+  instance records into the same series; consumers wanting per-adapter
+  cardinality should add their own attribute on the calling side.
+- `hostFxOnTrack` does not catch errors from `createFxNode` — those
+  propagate so the adapter raises the right
+  `AUDIO_ENGINE_BROWSER.WORKLET_LOAD_FAILED` code with the original
+  cause attached.
+- These helpers are intentionally not exported from the package barrel
+  because they take internal types (`TrackRecord`, `BusOrchestrator`)
+  whose shape should not be part of the public surface.