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

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

import { hostFxOnTrack } from "@suaveplan/audio-engine-browser/adapter/adapter-introspection";

await hostFxOnTrack(rec, plugin, context, worklets, graph);

Usage: Advanced Example

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.