@xsynaptic/sonic-ui 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @xsynaptic/sonic-ui
 
+## 0.19.0
+
+### Minor Changes
+
+- - Shared tokens, each unset or at today's value: `--sonic-press-duration` (60ms) and `--sonic-fade-duration` (120ms) time a cap's press and every fade; `--sonic-shade` (black) and `--sonic-shine` (white) are the poles the light mixes a surface towards.
+  - `--sonic-legend-font-size` sets the text of a button, a segmented option, a switch and a toggle. `--sonic-radius` sets the outer corner of a button, a segmented control, a number box, a screen, a slider's cap, a wave strip, a waveform, a spectrum, an envelope and an XY pad. A control's own `-font-ratio` or `-radius-ratio` still wins, and under the shared radius a button's face follows its corner.
+  - Waveform and wave strip: the inset ratio now defaults to 0, so the wave fills its glass; set `--sonic-waveform-inset-ratio: 0.06` or `--sonic-wavestrip-inset-ratio: 0.1` for the inset each had. The slate, amber, ivory and lime skins keep the wave strip's 0.1, which holds its markers clear of the well's shadow.
+  - Spectrum and wave strip: the canvas is rounded to the glass, so a large radius no longer leaves corners poking out.
+  - A cast shadow or highlight now computes to `color(srgb …)` where it was `rgba()`; nothing drawn changes.
+  - In development a control warns about a box property on its host, a padding zeroed by an unlayered rule, and a missing `material/scale.css` or `material/bracket.css`. The README has the recipe for layering a reset.
+- - A waveform or a wave strip now shows, reads and speaks a clock when no formatter is set: `1:23` in the readout and the typed entry, and a duration in the nearest `lang` for assistive technology. Setting `formatValue`, `parseValue` or `formatSpokenValue` replaces that part.
+  - `formatClock` and `parseClock` are exported, so your own time text can match. A negative time is written with `−` (U+2212), not the ASCII hyphen; `parseClock` reads either.
+  - `fullScale` is optional on `peaks` and follows the array when unset.
+  - `./dat` is removed. Pass `peaks` as `{ pairsPerSecond, samples }`, where the first is a header's `sampleRate / samplesPerPixel`.
+
+## 0.18.0
+
+### Minor Changes
+
+- - Button: an icon keeps its `viewBox` proportions at `--sonic-button-icon-ratio` of the button's height, and the button widens to fit it, never under `--sonic-button-aspect-ratio`; at 0 the button is as wide as its icon. Breaking for an icon wider than it is tall, which was shrunk into a square.
+  - Waveform: a dimmed marker's label dims by opacity, so `renderLabel` children with their own colour dim too, as does the label's scrim. Drop any rule that dimmed them by hand.
+
+### Patch Changes
+
+- Internals restructured into smaller modules; no change to the public surface.
+- Switch and toggle internals restructured around position indices; no change to the public surface.
+- The types say the unit or the contract on the properties whose type alone does not, such as a meter's `level` and a waveform's `zoom`.
+
 ## 0.17.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,14 @@ Native custom elements for audio interfaces. Each control renders in the light D
 
 Early and unstable: any 0.x release may break the API.
 
+This README holds what the package's own files do not say. For the rest, read the package:
+
+- Properties and methods: `dist/dev/elements/<control>.d.ts`. Every attribute has a property of the same name in camel case.
+- Tokens and their defaults: `dist/styles/<control>.css` and `dist/styles/material/`, where each token is read as `var(--sonic-…, default)`.
+- Working markup for every control: `playground/src/components/specimens/` in the repository.
+
+## Setup
+
 ```sh
 pnpm add @xsynaptic/sonic-ui
 ```
@@ -20,12 +28,121 @@ import '@xsynaptic/sonic-ui/define';
 ```
 
 ```html
-<sonic-dial aria-label="Cutoff" value="40"></sonic-dial>
+<body class="sonic-skin-slate">
+	<sonic-dial aria-label="Cutoff" value="40"></sonic-dial>
+</body>
 ```
 
-A display takes its signal as data: `spectrum.analyser = node`, or `spectrum.push(frame)`.
+- Every sheet sits in the `sonic` layer, so declare it below the layer your own rules live in.
+- A rule outside any layer beats every layered one, so an unlayered reset (`* { margin: 0; padding: 0 }`, a zeroed `border`, a bare `button`) strips padding, borders, type sizes and colours from the controls. Import a reset you do not own into a layer declared before `sonic`:
+
+  ```css
+  @layer base, sonic, components;
+
+  @import 'reset.css' layer(base);
+  ```
+
+- A skin sheet does nothing until its class, `sonic-skin-<name>`, is on an ancestor of the controls. The skins are `slate`, `amber`, `ivory`, `lime` and `flat`; a wrapper with another skin's class reskins what is inside it. With no skin a control is bare: no cap and no well, drawn in the text colour around it.
+- `./define` registers every control. `./define/<control>` registers one, and `.` exports the classes and registers nothing.
+- Under a bundler that sets the `development` condition, as Vite's dev server does, the controls warn in the console about a missing sheet, a padding lost to an unlayered rule, a box property set on a host, a child they do not use and a binding that found nothing. Read the console before debugging.
+
+## What every control shares
+
+- The host is `display: contents` and the control is an element inside it. A width, margin or transform on the host does nothing: size a control with its token (`--sonic-dial-size`, `--sonic-slider-length`), which can be set on the host or any ancestor, and place it with its parent's layout.
+- Name every control with `aria-label` or `aria-labelledby` on the host, or with a `<label>` for a form-associated one; the control moves the name onto its focusable part.
+- A boolean attribute is on when present, whatever its value, so `pressed="false"` latches a button. From a framework pass `undefined`, never `false`.
+- A control uses only the children it documents below, and adds one child of its own. Under a hydrating framework, register the definitions once hydration is done (in React, from an effect), so the added child is no mismatch.
+- Events bubble and carry no detail: read the property when one fires. A control knows nothing about playback, so wire `input` and `change` to your own state and write `value` back.
+- Buttons, value controls, the segmented control, the switch, the toggle and the XY pad are form-associated: give one a `name` and it submits, resets and restores with its form.
+- States a control sets itself are custom states on the host, selected with `:state()`: `dragging`, `cancelling`, `editing`, `revealed`, `springing`, `modulated`, `pressed`, `held`, `ladder`, `empty` and `pending`.
+
+## Value controls
+
+The dial, the slider, the number box and both wave controls hold one number, from `min` (0) to `max` (100) in steps of `step` (1).
+
+- `input` fires as the value moves and `change` once when a gesture ends, however it ends.
+- A drag owns the value: a write to `value` during one is dropped, so a seek bar fed by `timeupdate` needs no guard of its own.
+- A double press, or Enter, opens typed entry. `double-press="reset"` makes it go back to `default` instead. Cmd-click on Apple platforms, Ctrl-click elsewhere, and Delete reset whichever is chosen, once `default` is set.
+- `formatValue` and `parseValue` are properties holding functions. What the first writes, the second has to read, or typed entry opens on text it cannot take; `formatEntry` covers the case where it cannot.
+- The readout bubble is opt-in, with `readout`. Assistive technology hears the value without it; `formatSpokenValue` words it.
+- `taper="log"` gives even octaves on a range above zero, and `midpoint` bends a range that starts at zero. On a tapered control the arrow keys move by travel; `key-step` makes them move by value.
+- `positions` is a property holding the numbers a stepped control stops at, spaced evenly whatever their values; their labels come from `formatValue`.
+- `modulationValue` is a property only, meant to be written every frame. It moves the light and fires nothing.
+- To take a key from a control, call `preventDefault()` in a capture listener.
+
+## Press controls
+
+A button's children are its legend, an icon or a label, always an element. They are copied into the cap, so the copy has none of your listeners and any id in it is prefixed; keep them static. A child with `data-sonic-when="pressed"` or `"released"` shows only in that state.
+
+```html
+<sonic-button aria-label="Loop" latching>
+	<span class="sonic-led"></span>
+	<svg aria-hidden="true">…</svg>
+</sonic-button>
+```
+
+- A plain button fires `click`. `latching` makes it stay pressed, with `pressed` and a `change` event; `momentary` makes it pressed for as long as it is held, and acts on the press, not the release.
+- `soft-disabled` stops presses but keeps the tab stop, for a button that would otherwise lose focus when it disables itself. `busy` leaves it pressable.
+- The segmented control, the switch and the toggle take one child per position, each with `data-sonic-value`, and hold the chosen one in `value`. They fire `change` only. A switch or a toggle with no children is on or off, held in `checked`.
+- On a position child, `data-sonic-disabled` locks it, `data-sonic-momentary` makes an end position spring back, and on a toggle `data-sonic-lit` lights the well there (`ok`, `warning` or `danger` for the colour). A lock stops the user, not your code: a `value` written to a disabled position is chosen.
+
+```html
+<sonic-segmented aria-label="Filter" value="lp">
+	<span data-sonic-value="lp">LP</span>
+	<span data-sonic-value="bp">BP</span>
+	<span data-sonic-value="hp">HP</span>
+</sonic-segmented>
+```
+
+## Parts that are only a class
+
+The LED, the panel, the ring and the screen have no behaviour, so they are classes on your own elements and need no registration.
+
+- `<span class="sonic-led">` is unlit until it carries `data-sonic-lit`, whose value picks the colour: empty, `idle`, `ok`, `warning` or `danger`. Inside a latching button or a toggle's cap it lights with the control.
+- `class="sonic-ring"` draws a lit arc around its one child, from `--sonic-ring-from` to `--sonic-ring-to`, each 0 to 1. Give it your own `role="progressbar"`.
+- `class="sonic-screen"` is a pane of glass for your own text or canvas, and `class="sonic-panel"` groups controls under a `sonic-panel-title`.
+
+## Displays
+
+A display takes its signal as data and never opens an `AudioContext`.
+
+- `<sonic-meter>`: write `level`, a linear peak amplitude, as often as you have one; the meter converts to decibels and applies its `ballistics`. Write `value` instead to show a number in the meter's own units exactly as given. `segments` turns the bar into a ladder. It fires nothing and has no role: read `peak`, call `resetPeak()`, and announce numbers yourself.
+- `<sonic-spectrum>`: set `analyser` to an `AnalyserNode`, or call `push(decibels)` with a `Float32Array` holding one level per bin and set `sample-rate`.
+
+## Controls that drive other controls
+
+- `<sonic-split>` wraps value controls and keeps their values adding up to `total`. `mode` chooses who gives way (`proportional`, `equal` or `cascade`), and `data-sonic-locked` on a member holds it still. The others move a microtask after the one the user moved, so its `input` arrives first.
+- `<sonic-envelope>` has no value and no events. Each of its attributes (`delay`, `attack`, `hold`, `decay`, `sustain`, `release`, and `attack-curve`, `decay-curve`, `release-curve`) names the id of a dial, a slider or a number box; dragging a handle turns that control, which fires its own `input`. Stages share the width equally, whatever their times.
+- `<sonic-xy>` holds `x` and `y`, each with its own `x-min`, `x-max`, `x-step` and so on, and submits them as `name.x` and `name.y`.
+- `envelopeCurve` and `crossfadeGains` are exported so your DSP computes what the control draws.
+
+## Wave controls
+
+`<sonic-wavestrip>` is the overview of a track, scrubbed to seek; `<sonic-waveform>` is the close-up that scrolls under a fixed playhead. Both are value controls in seconds that take their data as properties (`peaks`, `markers`); the types list the rest. `peaks` is `{ pairsPerSecond, samples }`, and the full scale follows the array unless `fullScale` is set.
+
+A wave control shows and reads a clock (`1:23`, typed or drawn) and speaks a duration in the language around it, the nearest `lang`. Setting `formatValue`, `parseValue` or `formatSpokenValue` replaces that part; `formatClock` and `parseClock` are the same pair, exported so your own time text matches.
+
+Their events bubble and carry no detail, so read the property when one fires: `revealed` on `sonic-reveal`, `currentMarker` on `sonic-marker`, and the strip's `hoverValue` on `sonic-hover`, which `clientXOf(value)` turns into a viewport x.
+
+The strip draws one part per marker inside `.sonic-wavestrip-markers`, in `start` order: a `.sonic-wavestrip-marker` dot, or a `.sonic-wavestrip-region` when the marker has an `end`. Marker labels are hidden from assistive technology; fold `currentMarker` into `formatSpokenValue` to have one spoken.
+
+The waveform parks the current marker's label in its corner and fades it after the next marker crosses the playhead, never before: `--sonic-waveform-label-fade-start` (0) and `--sonic-waveform-label-fade-end` (1) run from that crossing, 0, to the next label reaching the park, 1.
+
+The waveform calls `requestPeaks(fromSeconds, toSeconds)` as its window moves, often every frame, so return at once for a span already loaded or on its way. Return a promise, or several, and the waveform repaints as each settles; an `async` function is the wrong shape, since it hands back a new settled promise each call. `pending` is yours to keep: list the spans being fetched, and clear each as it lands.
+
+With `zoomable`, a ctrl or cmd wheel, a pinch and the `+` and `-` keys set the waveform's `zoom` and fire `sonic-zoom`; a write to `zoom` fires nothing.
+
+With `fill` a control takes its container's height and its ratios follow. `--sonic-wavestrip-marker-size`, `--sonic-wavestrip-groove-size` and `--sonic-waveform-label-font-size` hold an absolute length instead.
+
+## Skinning
 
-Under a hydrating framework, register the definitions once hydration is done (in React, from an effect); a control owns one child of its host and uses only the children it documents.
+A skin is one rule that sets tokens on a class; copy `dist/skins/flat.css` to start one. Tokens, hook classes (`.sonic-dial`, `.sonic-wavestrip-marker`), `data-sonic-*` attributes and states are the public surface. Anything starting `--_sonic-` is private and changes without notice.
+
+- Set tokens, not rules on hook classes. If a look needs a hook-class rule, a token is missing.
+- Most geometry tokens end in `-ratio` and are a unitless share of the control's size, so one size token scales the whole control.
+- A length token takes any CSS length except a percentage. For a fluid size use container units.
+- `--sonic-relief` runs from 0, flat, to 1, and scales every bevel and shadow at once. `--sonic-light-tilt` turns the one light they all follow.
+- `--sonic-target-size` widens the region that takes a press past the control's box. It is unset by default.
 
 ## Loading less
 
@@ -58,20 +175,6 @@ Under a hydrating framework, register the definitions once hydration is done (in
 | `wavestrip.css` | core, cap, glass, pane, well, readout, value    |
 | `xy.css`        | core, cap, glass, pane, well, readout, bracket  |
 
-An LED inside a control also needs `led.css`, and a button inside a ring needs `button.css`. The development build warns about a missing sheet.
-
-## Wave controls
-
-`<sonic-wavestrip>` is the overview of a track, scrubbed to seek; `<sonic-waveform>` is the close-up that scrolls under a fixed playhead. Both are value controls in seconds that take their data as properties (`peaks`, `markers`); the types list the rest.
-
-Their events bubble and carry no detail, so read the property when one fires: `revealed` on `sonic-reveal`, `currentMarker` on `sonic-marker`, and the strip's `hoverValue` on `sonic-hover`, which `clientXOf(value)` turns into a viewport x.
-
-The strip draws one part per marker inside `.sonic-wavestrip-markers`, in `start` order: a `.sonic-wavestrip-marker` dot, or a `.sonic-wavestrip-region` when the marker has an `end`. Marker labels are hidden from assistive technology; fold `currentMarker` into `formatSpokenValue` to have one spoken.
-
-The waveform calls `requestPeaks(fromSeconds, toSeconds)` as its window moves, often every frame, so return at once for a span already loaded or on its way. Return a promise, or several, and the waveform repaints as each settles; an `async` function is the wrong shape, since it hands back a new settled promise each call. `pending` is yours to keep: list the spans being fetched, and clear each as it lands.
-
-With `zoomable`, a ctrl or cmd wheel, a pinch and the `+` and `-` keys set the waveform's `zoom` and fire `sonic-zoom`; a write to `zoom` fires nothing.
-
-With `fill` a control takes its container's height and its ratios follow. `--sonic-wavestrip-marker-size`, `--sonic-wavestrip-groove-size` and `--sonic-waveform-label-font-size` hold an absolute length instead.
+An LED inside a control also needs `led.css`, and a button inside a ring needs `button.css`.
 
-Targets current Chrome and Edge, Safari 26 and Firefox 147. MIT licensed.
+Targets current Chrome and Edge, Safari 26 and Firefox 147. No control mirrors for right-to-left. MIT licensed.

package/dist/default/elements/button.js

@@ -54,6 +54,7 @@ var SonicButton = class extends SonicFormElement {
 	set latching(isLatching) {
 		this.reflect("latching", isLatching);
 	}
+	/** Shows the legend child whose `data-sonic-when` has this name */
 	get legend() {
 		return this.getAttribute("legend") ?? void 0;
 	}
@@ -80,6 +81,7 @@ var SonicButton = class extends SonicFormElement {
 	set softDisabled(isSoftDisabled) {
 		this.reflect("soft-disabled", isSoftDisabled);
 	}
+	/** Submitted with the form while a latching button is pressed */
 	get value() {
 		return this.getAttribute("value") ?? "on";
 	}
@@ -114,11 +116,6 @@ var SonicButton = class extends SonicFormElement {
 			}
 		}, signal);
 		this.render();
-		this.checkStyles(button, "button.css", [
-			"cap",
-			"well",
-			"keycap"
-		]);
 		button.addEventListener("click", (event) => {
 			if (this.#isSoftDisabled()) {
 				event.preventDefault();

package/dist/default/elements/dial.js

@@ -37,12 +37,14 @@ var SonicDial = class extends SonicValueElement {
 	set endless(isEndless) {
 		this.reflect("endless", isEndless);
 	}
+	/** How far a modulation source can push the value, in value units; signed */
 	get modulation() {
 		return this.numberAttribute("modulation", 0);
 	}
 	set modulation(amount) {
 		this.reflect("modulation", amount);
 	}
+	/** Where the value is right now with modulation applied; a property only, cheap to write every frame, fires nothing */
 	get modulationValue() {
 		return this.#modulation.value();
 	}
@@ -64,13 +66,6 @@ var SonicDial = class extends SonicValueElement {
 			marks: requireChild(dial, ".sonic-dial-scale", HTMLDivElement)
 		}, signal);
 		this.render();
-		this.checkStyles(dial, "dial.css", [
-			"cap",
-			"readout",
-			"value",
-			["glass", ".sonic-dial-readout"],
-			["arc", ".sonic-dial-ring"]
-		]);
 		this.bindGestures(dial, signal, () => ({
 			position: (event) => -event.clientY,
 			travelPx: this.travelPx(dial, "--_sonic-dial-travel")

package/dist/default/elements/display-element.js

@@ -1,6 +1,5 @@
 import { SonicElement } from "./sonic-element.js";
 import { bindSurface } from "../lib/canvas-surface.js";
-import { bindFill } from "../lib/fill-watch.js";
 
 //#region src/elements/display-element.ts
 var SonicDisplayElement = class extends SonicElement {
@@ -38,17 +37,17 @@ var SonicDisplayElement = class extends SonicElement {
 	#analyser;
 	#buffer = /* @__PURE__ */ new Float32Array(0);
 	#surface;
-	#syncFill;
 	attributeChangedCallback(name) {
-		if (name === "fill") this.#syncFill?.(this.fill);
+		if (name === "fill") this.#surface?.setFill(this.fill);
 		this.#surface?.invalidate();
 	}
 	connectedCallback() {
 		this.upgradeProperties("analyser", "fill", "max", "min");
 		super.connectedCallback();
 	}
-	push(frame) {
-		this.receive(frame);
+	/** One level per bin, as `AnalyserNode.getFloatFrequencyData` fills it */
+	push(decibels) {
+		this.receive(decibels);
 		this.#surface?.requestFrame();
 	}
 	repaint() {
@@ -60,19 +59,17 @@ var SonicDisplayElement = class extends SonicElement {
 		this.#surface = bindSurface({
 			canvas: this.canvas,
 			colours: this.colours,
+			fill: {
+				control,
+				sizeProperty: this.sizeProperty
+			},
 			numbers: this.numbers,
 			paint: (context, frame) => {
 				this.#paint(context, frame);
 			},
 			signal
 		});
-		this.checkStyles(control, this.sheet, [
-			"glass",
-			"pane",
-			"well"
-		]);
-		this.#syncFill = bindFill(control, this.sizeProperty, signal);
-		this.#syncFill(this.fill);
+		this.#surface.setFill(this.fill);
 	}
 	surface() {
 		return this.#surface;

package/dist/default/elements/envelope.js

@@ -1,13 +1,11 @@
 import { writeAttribute } from "../lib/write-attribute.js";
 import { SonicElement } from "./sonic-element.js";
 import { requireChild, template } from "../lib/render.js";
-import { bindDrag } from "../lib/pointer-drag.js";
 import { Readout } from "./readout.js";
-import { ReadoutClaim, revealDelay } from "./readout-claim.js";
-import { dragThresholdPx } from "../lib/drag-step.js";
+import { ReadoutClaim } from "./readout-claim.js";
 import { SonicValueElement, linkValue } from "./value-element.js";
+import { bindFieldGesture } from "./field-gesture.js";
 import { adsrPath, adsrShape, adsrStages, timeStages } from "../lib/adsr-shape.js";
-import { pointerMove, pointerPosition, startFieldDrag, stepFieldDrag } from "../lib/field.js";
 
 //#region src/elements/envelope.ts
 const curveStages = [
@@ -22,12 +20,6 @@ const bindable = [
 	"release-curve"
 ];
 const bindableNames = new Set(bindable);
-function flip(point, isFlipped) {
-	return isFlipped ? {
-		...point,
-		y: -point.y
-	} : point;
-}
 function isParent(node) {
 	return "querySelector" in node;
 }
@@ -104,7 +96,7 @@ var SonicEnvelope = class extends SonicElement {
 		this.reflect("hold", id);
 	}
 	get pointerType() {
-		return this.#pointerType;
+		return this.#gesture?.pointerType();
 	}
 	get readout() {
 		return this.hasAttribute("readout");
@@ -139,13 +131,12 @@ var SonicEnvelope = class extends SonicElement {
 	#curveHandles = stageParts(this.#envelope, "sonic-envelope-curve", curveStages);
 	#fill = requireChild(this.#envelope, ".sonic-envelope-fill", SVGElement);
 	#floor = requireChild(this.#envelope, ".sonic-envelope-floor", SVGElement);
+	#gesture;
 	#graph = requireChild(this.#envelope, ".sonic-envelope-graph", SVGElement);
 	#handles = stageParts(this.#envelope, "sonic-envelope-handle", timeStages);
 	#held;
 	#isDriving = false;
 	#line = requireChild(this.#envelope, ".sonic-envelope-line", SVGElement);
-	#pointerDrag;
-	#pointerType;
 	#readout = new Readout(requireChild(this.#envelope, ".sonic-envelope-readout", HTMLDivElement));
 	#shape = adsrShape({});
 	#signal;
@@ -154,7 +145,7 @@ var SonicEnvelope = class extends SonicElement {
 	attributeChangedCallback(name) {
 		if (!this.#signal) return;
 		if (name === "disabled") {
-			this.#pointerDrag?.end();
+			this.#gesture?.end();
 			this.#draw();
 			return;
 		}
@@ -170,12 +161,6 @@ var SonicEnvelope = class extends SonicElement {
 		this.#signal = signal;
 		this.keepControl(envelope, signal);
 		this.#bind();
-		this.checkStyles(envelope, "envelope.css", [
-			"glass",
-			"pane",
-			"well",
-			"readout"
-		]);
 		this.#bindPointer(envelope, signal);
 		signal.addEventListener("abort", () => {
 			this.#signal = void 0;
@@ -183,13 +168,13 @@ var SonicEnvelope = class extends SonicElement {
 		}, { once: true });
 	}
 	#bind() {
-		this.#pointerDrag?.end();
+		this.#gesture?.end();
 		this.#unbind();
 		for (const name of bindable) {
 			const element = this.#resolve(name);
 			if (!element) continue;
 			const link = linkValue(element);
-			const unwatch = link.watch(() => {
+			const unwatch = link.model.watch(() => {
 				if (!this.#isDriving) this.#draw();
 			});
 			this.#bindings.set(name, {
@@ -201,21 +186,23 @@ var SonicEnvelope = class extends SonicElement {
 		this.#draw();
 	}
 	#bindPointer(envelope, signal) {
-		this.#pointerDrag = bindDrag(envelope, {
-			cancel: (drag) => {
-				for (const { binding, from } of drag.drives) binding.link.input(from);
-			},
+		this.#gesture = bindFieldGesture(envelope, {
+			claim: this.#claim,
 			grab: (event) => this.#grab(event),
-			move: (drag, event) => {
-				this.#moveDrag(drag, event);
+			input: ({ drives }, next) => {
+				this.#isDriving = true;
+				for (const { axis, binding } of drives) {
+					const value = next[axis];
+					if (value !== void 0) binding.link.input(value);
+				}
+				this.#isDriving = false;
+				this.#draw();
 			},
-			release: (drag) => {
-				this.#claim.press(false);
-				for (const { binding, from } of drag.drives) {
-					if (binding.link.value() === from) continue;
+			release: ({ drives }, moved) => {
+				for (const { axis, binding } of drives) {
+					if (!moved.includes(axis)) continue;
 					binding.element.dispatchEvent(new Event("change", { bubbles: true }));
 				}
-				this.#pointerType = void 0;
 			},
 			toggle: (isDragging) => {
 				this.toggleState("dragging", isDragging);
@@ -278,57 +265,23 @@ var SonicEnvelope = class extends SonicElement {
 	#grab(event) {
 		const pressed = this.#pressed(event);
 		if (!pressed || pressed.drives.length === 0) return void 0;
-		const { drives, isFlipped, part } = pressed;
-		this.#pointerType = event.pointerType;
-		this.#claim.press(true, revealDelay(this.#envelope));
-		this.#held = part;
+		this.#held = pressed.part;
 		this.#drawBracket();
 		const box = this.#graph.getBoundingClientRect();
 		const travel = {
 			x: Math.max(1, box.width * this.#shape.share),
 			y: Math.max(1, box.height)
 		};
-		const start = (axis) => {
-			const link = drives.find((drive) => drive.axis === axis)?.binding.link;
-			if (!link) return;
-			const mapping = link.mapping();
-			const from = link.value();
-			return {
-				from,
-				mapping,
-				proportion: mapping.proportionOf(from),
-				travelPx: travel[axis]
-			};
+		const axes = {};
+		for (const { axis, binding } of pressed.drives) axes[axis] = {
+			model: binding.link.model,
+			travelPx: travel[axis]
 		};
 		return {
-			drives: drives.map((drive) => ({
-				...drive,
-				from: drive.binding.link.value()
-			})),
-			isFlipped,
-			part,
-			state: startFieldDrag({
-				position: flip(pointerPosition(event), isFlipped),
-				thresholdPx: dragThresholdPx(event.pointerType),
-				x: start("x"),
-				y: start("y")
-			})
+			...pressed,
+			axes
 		};
 	}
-	#moveDrag(drag, event) {
-		const mappings = {};
-		for (const { axis, binding } of drag.drives) mappings[axis] = binding.link.mapping();
-		const step = stepFieldDrag(mappings, drag.state, flip(pointerMove(event), drag.isFlipped));
-		drag.state = step.state;
-		if (step.state.isEngaged) this.#claim.reveal("drag");
-		this.#isDriving = true;
-		for (const { axis, binding } of drag.drives) {
-			const next = step[axis];
-			if (next !== void 0) binding.link.input(next);
-		}
-		this.#isDriving = false;
-		this.#draw();
-	}
 	#pressed(event) {
 		const part = event.target instanceof Element ? event.target.closest(".sonic-envelope-handle, .sonic-envelope-curve") : void 0;
 		const stage = part?.dataset.sonicStage;
@@ -344,10 +297,10 @@ var SonicEnvelope = class extends SonicElement {
 		const proportions = {};
 		const curves = {};
 		for (const stage of adsrStages) {
-			const link = this.#bindings.get(stage)?.link;
-			proportions[stage] = link?.mapping().proportionOf(link.value());
+			const model = this.#bindings.get(stage)?.link.model;
+			proportions[stage] = model?.mapping().proportionOf(model.value);
 		}
-		for (const stage of curveStages) curves[stage] = this.#bindings.get(`${stage}-curve`)?.link.value();
+		for (const stage of curveStages) curves[stage] = this.#bindings.get(`${stage}-curve`)?.link.model.value;
 		return adsrShape(proportions, curves);
 	}
 	#rebindOnce(key, arrives) {
@@ -359,7 +312,7 @@ var SonicEnvelope = class extends SonicElement {
 		});
 	}
 	#renderReadout() {
-		const drag = this.#pointerDrag?.current();
+		const drag = this.#gesture?.current();
 		if (!drag) {
 			this.#readout.close();
 			return;

package/dist/default/elements/field-gesture.js

@@ -0,0 +1,81 @@
+import { bindDrag } from "../lib/pointer-drag.js";
+import { revealDelay } from "./readout-claim.js";
+import { dragThresholdPx } from "../lib/drag-step.js";
+import { pointerMove, pointerPosition, startFieldDrag, stepFieldDrag } from "../lib/field.js";
+
+//#region src/elements/field-gesture.ts
+const fieldAxes = ["x", "y"];
+function flip(point, hold) {
+	return hold.isFlipped === true ? {
+		...point,
+		y: -point.y
+	} : point;
+}
+function startAxis(hold) {
+	if (!hold) return;
+	const { model, travelPx } = hold;
+	const mapping = model.mapping();
+	const from = model.value;
+	return {
+		from,
+		mapping,
+		proportion: hold.proportion ?? mapping.proportionOf(from),
+		travelPx
+	};
+}
+function bindFieldGesture(target, options, signal) {
+	const { claim } = options;
+	let pointerType;
+	const drag = bindDrag(target, {
+		cancel: ({ from, hold }) => {
+			options.input(hold, from);
+		},
+		grab: (event) => {
+			pointerType = event.pointerType;
+			const hold = options.grab(event);
+			if (!hold) {
+				pointerType = void 0;
+				return;
+			}
+			const { x, y } = hold.axes;
+			claim.press(true, revealDelay(target));
+			return {
+				from: {
+					x: x?.from ?? x?.model.value,
+					y: y?.from ?? y?.model.value
+				},
+				hold,
+				state: startFieldDrag({
+					position: flip(pointerPosition(event), hold),
+					thresholdPx: dragThresholdPx(event.pointerType),
+					x: startAxis(x),
+					y: startAxis(y)
+				})
+			};
+		},
+		move: (held, event) => {
+			const { axes } = held.hold;
+			const step = stepFieldDrag({
+				x: axes.x?.model.mapping(),
+				y: axes.y?.model.mapping()
+			}, held.state, flip(pointerMove(event), held.hold));
+			held.state = step.state;
+			if (step.state.isEngaged) claim.reveal("drag");
+			options.input(held.hold, step);
+		},
+		release: ({ from, hold }) => {
+			claim.press(false);
+			options.release(hold, fieldAxes.filter((axis) => hold.axes[axis]?.model.value !== from[axis]));
+			pointerType = void 0;
+		},
+		toggle: options.toggle
+	}, signal);
+	return {
+		current: () => drag.current()?.hold,
+		end: drag.end,
+		pointerType: () => pointerType
+	};
+}
+
+//#endregion
+export { bindFieldGesture };

package/dist/default/elements/meter.js

@@ -49,6 +49,7 @@ var SonicMeter = class extends SonicElement {
 	set ballistics(mode) {
 		this.reflect("ballistics", mode);
 	}
+	/** Linear peak amplitude, 1 at full scale; the meter converts to decibels and applies its ballistics */
 	get level() {
 		return this.#level;
 	}
@@ -90,15 +91,18 @@ var SonicMeter = class extends SonicElement {
 	set origin(value) {
 		this.reflect("origin", value);
 	}
+	/** Highest level since `resetPeak()`; `-Infinity` before any signal */
 	get peak() {
 		return this.#peak;
 	}
+	/** Ladder thresholds, one per segment; unset draws a bar */
 	get segments() {
 		return parseNumberList(this.getAttribute("segments"));
 	}
 	set segments(thresholds) {
 		this.reflect("segments", thresholds?.join(" "));
 	}
+	/** A reading in the meter's own units, drawn as given with no ballistics; takes over from `level` while set */
 	get value() {
 		return this.optionalNumberAttribute("value");
 	}
@@ -138,7 +142,6 @@ var SonicMeter = class extends SonicElement {
 		this.#renderSegments();
 		this.#render(now);
 		this.#schedule(now);
-		this.checkStyles(this.#meter, "meter.css", ["lens", "groove"]);
 		signal.addEventListener("abort", () => {
 			if (this.#frame !== void 0) cancelAnimationFrame(this.#frame);
 			this.#frame = void 0;

package/dist/default/elements/number.js

@@ -32,13 +32,6 @@ var SonicNumber = class extends SonicValueElement {
 		const number = this.#number;
 		this.keepControl(number, signal);
 		this.render();
-		this.checkStyles(number, "number.css", [
-			"cap",
-			"glass",
-			"pane",
-			"well",
-			"value"
-		]);
 		this.bindGestures(number, signal, () => ({
 			position: (event) => -event.clientY,
 			travelPx: this.travelPx(number, "--_sonic-number-travel")