# Inspector — Web Components API

This document is the source-reference companion to [`components.html`](./components.html). The live page imports the actual production components and has editable demonstrations. No `.stem` file or audio engine is needed to browse examples.

## Components

- `<stem-inspector-track>`
- `<stem-app-panel>`

The host application owns file I/O, codec, playback, state persistence, and other operations unless explicitly noted. Components are native Custom Elements. CSS in component Shadow DOM resolves relative to the module file. The app owns any callback-supplied state.

Primary component source: [`components/track-row.js`](./components/track-row.js).

`<stem-app-panel>` is also reusable. It uses **Light DOM**, not Shadow DOM, so host styles and ordinary HTML labels work normally. It exposes `show()` and `hide()` and sets `role="region"` by default.

## Public methods and properties

- `setTrack(track,{artworkURL,formatTime,json})`: Render codec, duration, track metadata, artwork and waveform canvas
- `waveCanvas`: Canvas element for host waveform analysis
- `waveLabel`: Text label the host updates after analysis
- `setDisabled(boolean)`: Disable available form controls

## Events and callbacks

- `No track action events`: The host supplies waveform samples; the component does not decode audio

## Example

```javascript
import './components/track-row.js';
const row = document.createElement('stem-inspector-track');
row.setTrack(track, {artworkURL:a=>getArtworkUrl(a),formatTime:t=>formatTime(t),json:o=>JSON.stringify(o,null,2)});
document.body.append(row);
// Host writes decoded peaks into row.waveCanvas and text into row.waveLabel.
```

## Testing and limitations

- Catalog data and artworks are synthetic demonstration content; they are not loaded from audio files.
- Changing a property in the catalog reconfigures or remounts the real component so modes can be inspected.
- The catalog's events log is not a replacement for host-state management.
- For production integration, always copy the **entire relevant mini-app folder** with its sibling suite dependencies rather than a partial HTML patch.

**Cross-app integration:** the shared `<stem-app-panel>` definition is guarded so multiple reference mini-app modules can be imported into one host without duplicate registration errors.
