@xsynaptic/sonic-ui 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @xsynaptic/sonic-ui
 
+## 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,111 @@ 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>
+```
+
+- Every sheet sits in the `sonic` layer, so declare it below the layer your own rules live in.
+- 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 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 display takes its signal as data: `spectrum.analyser = node`, or `spectrum.push(frame)`.
+- 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. `./dat` reads an audiowaveform `.dat` file into `peaks`, and fetches nothing itself.
+
+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
+
+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.
 
-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.
+- 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 +165,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/dat.js

@@ -28,6 +28,7 @@ function readDatHeader(buffer) {
 		version
 	};
 }
+/** An inclusive byte range for a `Range` header; `undefined` when the pairs asked for are empty */
 function datByteRange(header, fromPair, toPair) {
 	const from = clamp(Math.floor(fromPair), 0, header.pairs);
 	const to = clamp(Math.ceil(toPair), from, header.pairs);

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";
 	}

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();
 	}

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,6 +59,10 @@ 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);
@@ -71,8 +74,7 @@ var SonicDisplayElement = class extends SonicElement {
 			"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;
 		}
@@ -183,13 +174,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 +192,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 +271,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 +303,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 +318,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");
 	}