@webmusic/ui

@webmusic/ui is the domain-neutral presenter layer for Score and custom interfaces: DOM presenters and semantic styling hooks with no dependency on kernel, score or audio, and no custom-element registration. Every entry below is an import path of the one package, not a separate npm package.

This page is the root reference — the entry list, the shape they share, and what the release boundary admits. Positioning and theming live on the UI Kit overview; the browse surface is the Catalog; each entry’s own State, Binding, Options, Handle, tokens and parts live on its page.

Install

npm install @webmusic/ui

It has no dependencies and no required peers. Score declares it as an optional peer: package roots and /headless entries never reach it, so a headless-only install does not pull it in.

Package subpaths

The root re-exports all twenty-five; import a subpath to keep the rest out of your bundle.

Entry	Class	What it presents
`@webmusic/ui/analysis`	Views and analysis	Score and audio analysis result views rendered from plain result objects.
`@webmusic/ui/envelope`	Parameters and modulation	Accessible ADSR editor over a structural envelope binding.
`@webmusic/ui/eq`	Parameters and modulation	Accessible graphic-EQ presenter over a structural band/response binding.
`@webmusic/ui/harmony`	Views and analysis	Flow lane, nameplate, chip strip and wheel: read-outs that show an analysis happening.
`@webmusic/ui/level-analyzer`	Views and analysis	Live RMS and sample-peak history with threshold, freeze and peak-hold controls.
`@webmusic/ui/lfo`	Parameters and modulation	Accessible LFO controls and waveform over a structural modulation binding.
`@webmusic/ui/macro`	Parameters and modulation	Macro control with target readouts, composed over the parameter rack.
`@webmusic/ui/meter`	Mixing and capture	Level/spectrum presenter and structural meter binding; pulls and `redraw()`s.
`@webmusic/ui/minimap`	Transport and navigation	DPR-aware overview canvas with an accessible viewport range brush.
`@webmusic/ui/mixer`	Mixing and capture	Master/channel fader presenter over a structural mixer binding.
`@webmusic/ui/note`	Note input	Piano/grid/chord note-surface presenter over a structural note binding.
`@webmusic/ui/oscilloscope`	Views and analysis	Trigger-aligned time-domain waveform with timebase, freeze and probe controls.
`@webmusic/ui/panel`	Layout and feedback	Semantic section panel that owns section and presenter-slot hosts.
`@webmusic/ui/parameter`	Parameters and modulation	`mountParameterRack()`, its structural binding and side-effect-free style text.
`@webmusic/ui/pitch`	Views and analysis	Keyboard, grand stave and fretboard read-outs coloured by the role each pitch is given.
`@webmusic/ui/playlist`	Transport and navigation	Transport-and-track-list presenter over a structural playlist binding.
`@webmusic/ui/recorder`	Mixing and capture	Record/playback/export presenter over a structural recorder binding.
`@webmusic/ui/stage`	Layout and feedback	Framed rendering surface whose binding paints a caller-owned view.
`@webmusic/ui/status`	Layout and feedback	Generic loading, empty and error status surface over structural state.
`@webmusic/ui/spectrum-analyzer`	Views and analysis	Log-frequency FFT plot with a probe, freeze and peak hold.
`@webmusic/ui/timeline`	Transport and navigation	Numeric ruler, regions, ranges, playhead and seek surface.
`@webmusic/ui/track-list`	Transport and navigation	Accessible named-row index with one current item.
`@webmusic/ui/transient-analyzer`	Views and analysis	Caller-supplied attack strength and hit history with sensitivity, freeze and clear actions.
`@webmusic/ui/transport`	Transport and navigation	Structural transport binding plus `mountTransport()` and its named `controls`.
`@webmusic/ui/workbench`	Layout and feedback	The shell an analysis view sits in: tabs, a stage, docks, a status bar, one clock.

@webmusic/ui (the root) is the stable aggregate of the twenty-five. Presenter styles are exported by their owning entries; there is no separate stylesheet subpath.

The shared presenter shape

Most entries export three things: a mount*() function, the structural binding interface it consumes, and the same stylesheet text the mount installs, as a side-effect-free string constant.

const handle = mountX(host, binding, options);

handle.element;   // the presenter's root node inside the host
handle.update();  // re-read binding.snapshot() and repaint
handle.destroy(); // remove nodes, listeners and the subscription

For ordinary snapshot-based mounts:

Host. host is an HTMLElement or an open ShadowRoot. The mount appends its presenter markup and normally installs its exported style text, then removes what it created on destroy. stylesheet: false skips stylesheet installation where supported.
Structural binding. The binding is a plain object the caller writes: snapshot() returns current state, commands such as setValue() or play() perform changes and may return void or a Promise, and subscribe(notify) returns an unsubscribe function. The presenter repaints from a fresh snapshot after each command settles. subscribe is optional on most bindings; TransportBinding requires it.
One presenter per host, per entry. Each module keeps a WeakMap from host to handle. Mounting the same kind of presenter on a host again destroys the previous handle first, so a host never accumulates duplicate racks or transports.
Idempotent destroy. destroy() is safe to call repeatedly; cleanup failures are collected and reported instead of thrown.
onError. Where supported, options accept onError?: (error: unknown) => void. Snapshot, command, subscription and cleanup failures handled by that presenter are routed there; entries without this option leave caller actions responsible for their own failures. Check the owning entry before relying on this callback.
DOM-safe at import. Every entry evaluates in Node/SSR: importing reads no browser global, and mounting uses host.ownerDocument — including @webmusic/ui/analysis, whose render helpers create nodes in the caller-supplied root’s owner document (createAnalysisRoot(document?) is the one place a document can be passed directly).

The following entry-specific shapes serve different lifetimes. They are not interchangeable bindings:

Entry	Difference
meter	Pulls frame data through `readLevel` or `readSpectrum`; exposes `redraw()` and optional animation.
level-analyzer	Receives action callbacks and caller-paced `update(state)` rather than a snapshot/subscription binding.
note	Uses a note-surface snapshot and optional synchronous interaction ports for note holds and release.
oscilloscope	Uses a snapshot and commands, with optional subscription; the caller supplies each sampled trace and source identity.
transient-analyzer	Accepts an `HTMLElement` and action callbacks, then caller-paced `update(state)`; it has no mount options, subscription or `onError` callback.
analysis	Renders caller-owned report output through one-shot helpers; the caller replaces/removes it and updates any retained painter or playhead.
stage	Uses `render(surface)` for retained DOM or `draw(frame)` for canvas; its surface-slider helper augments an existing element.
panel	Receives section descriptors rather than a state binding; returns stable slots whose child mounts the caller owns.

Each owning page describes its complete state, cleanup and styling contract.

Release boundary

Import presenters through the explicit subpaths above or the root barrel. The first-release UI package includes all entries listed here, including those without a current Score Element consumer. Audio and Bridge packages continue on dev; UI bindings remain independent of either domain package. Package entries and their supported features are defined by their references, not by a historical component count or the number of current Element consumers.