@tremolo-ui/dom 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -2,9 +2,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _tremolo_ui_functions = require("@tremolo-ui/functions");
 //#region src/canvas/context.ts
 /**
-* The properties of a 2D context that survive `save()` / `restore()`, and so
-* are what has to be carried across a resize by hand: setting `canvas.width`
-* resets the context to its defaults.
+* The assignable parts of a 2D context's drawing state. They have to be
+* carried across a resize by hand because setting `canvas.width` resets the
+* context to its defaults. The transform and line dash are handled separately
+* by {@link DrawingContext} because they are exposed through methods.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
 */
@@ -22,24 +23,37 @@ const drawingState = [
 	"shadowBlur",
 	"shadowColor",
 	"globalCompositeOperation",
+	"filter",
 	"font",
+	"fontKerning",
+	"fontStretch",
+	"fontVariantCaps",
 	"textAlign",
 	"textBaseline",
 	"direction",
-	"imageSmoothingEnabled"
+	"letterSpacing",
+	"textRendering",
+	"wordSpacing",
+	"imageSmoothingEnabled",
+	"imageSmoothingQuality"
 ];
 function isDrawingState(value) {
-	return typeof value == "string" && drawingState.includes(value);
+	return typeof value === "string" && drawingState.includes(value);
 }
 /** Copy the drawing state off a context, to put back after a resize. */
 function readDrawingState(context) {
 	const state = {};
 	for (const property of drawingState) state[property] = context[property];
+	state.lineDash = context.getLineDash();
+	state.transform = context.getTransform();
 	return state;
 }
 /** Put a state read by {@link readDrawingState} back onto a context. */
-function writeDrawingState(context, state) {
+function writeDrawingState(context, state, transformScale = 1) {
 	for (const property of drawingState) context[property] = state[property];
+	context.setLineDash(state.lineDash);
+	const { a, b, c, d, e, f } = state.transform;
+	context.setTransform(a * transformScale, b * transformScale, c * transformScale, d * transformScale, e * transformScale, f * transformScale);
 }
 /**
 * Give the canvas a backing store of `width * dpr` by `height * dpr` device
@@ -72,12 +86,13 @@ function createAnimationCanvas(canvas, options) {
 	const context2d = canvas.getContext("2d", opts.contextAttributes);
 	if (!context2d) throw new Error("createAnimationCanvas: cannot get a 2d context");
 	const context = context2d;
-	const relativeSize = opts.relativeSize ?? false;
+	const resizable = opts.resizable ?? false;
 	/** Off-document canvas holding the drawing while the real one is resized. */
 	let memo = null;
 	let memoContext = null;
 	let width = 0;
 	let height = 0;
+	let appliedDpr = 0;
 	/** Whether a size has been applied, so a frame can be drawn. */
 	let sized = false;
 	let initialized = false;
@@ -95,17 +110,16 @@ function createAnimationCanvas(canvas, options) {
 	* the copy neither scales nor resamples.
 	*/
 	function takeSnapshot() {
-		if (!(opts.reduceFlickering ?? true)) return null;
+		if (!(opts.reduceFlickering ?? true)) return false;
 		if (!memo) {
 			memo = globalThis.document?.createElement("canvas") ?? null;
 			memoContext = memo?.getContext("2d", opts.contextAttributes) ?? null;
 		}
-		if (!memo || !memoContext) return null;
-		const state = readDrawingState(context);
+		if (!memo || !memoContext) return false;
 		memo.width = canvas.width;
 		memo.height = canvas.height;
 		if (canvas.width > 0 && canvas.height > 0) memoContext.drawImage(canvas, 0, 0);
-		return state;
+		return true;
 	}
 	/**
 	* Put the snapshot back, given the size in CSS pixels it was taken at.
@@ -115,25 +129,32 @@ function createAnimationCanvas(canvas, options) {
 	* stays put that is a 1:1 copy of device pixels, and when it changes the
 	* snapshot is rescaled once, from its full resolution.
 	*/
-	function restoreSnapshot(state, previousWidth, previousHeight) {
-		if (!state || !memo || !memoContext) return;
+	function restoreSnapshot(hasSnapshot, previousWidth, previousHeight) {
+		if (!hasSnapshot || !memo) return;
 		if (memo.width <= 0 || memo.height <= 0) return;
-		writeDrawingState(context, state);
 		context.drawImage(memo, 0, 0, previousWidth, previousHeight);
 	}
 	function applySize(w, h) {
 		const dpr = devicePixelRatio();
 		const previousWidth = width;
 		const previousHeight = height;
-		const state = takeSnapshot();
+		const previousDpr = appliedDpr;
+		const state = sized ? readDrawingState(context) : null;
+		const hasSnapshot = sized && takeSnapshot();
 		applyDevicePixelRatio(canvas, context, w, h, dpr);
 		width = w;
 		height = h;
+		appliedDpr = dpr;
 		sized = true;
-		restoreSnapshot(state, previousWidth, previousHeight);
+		restoreSnapshot(hasSnapshot, previousWidth, previousHeight);
+		if (state) writeDrawingState(context, state, dpr / previousDpr);
 	}
-	function drawFrame() {
+	function applyDevicePixelRatioIfNeeded() {
+		if (sized && devicePixelRatio() !== appliedDpr) applySize(width, height);
+	}
+	function drawFrame(timestamp = performance.now()) {
 		if (!sized) return;
+		applyDevicePixelRatioIfNeeded();
 		if (!initialized) {
 			initialized = true;
 			opts.init?.(context, {
@@ -141,41 +162,40 @@ function createAnimationCanvas(canvas, options) {
 				height
 			});
 		}
-		const now = performance.now();
-		const deltaTime = now - previousTime;
-		previousTime = now;
+		const deltaTime = timestamp - previousTime;
+		previousTime = timestamp;
 		count += 1;
 		opts.draw(context, {
 			width,
 			height,
 			count,
 			deltaTime,
-			elapsedTime: now - startTime,
-			fps: 1e3 / deltaTime
+			elapsedTime: timestamp - startTime,
+			fps: deltaTime > 0 ? 1e3 / deltaTime : 0
 		});
 	}
-	function tick() {
+	function tick(timestamp) {
 		frameId = requestAnimationFrame(tick);
-		drawFrame();
+		drawFrame(timestamp);
 	}
 	function startLoop() {
-		if (frameId != null) return;
+		if (frameId !== null) return;
 		previousTime = performance.now();
 		frameId = requestAnimationFrame(tick);
 	}
 	function stopLoop() {
-		if (frameId == null) return;
+		if (frameId === null) return;
 		cancelAnimationFrame(frameId);
 		frameId = null;
 	}
 	let observer = null;
-	if (relativeSize) {
+	if (resizable) {
 		const parent = canvas.parentElement;
-		if (!parent) throw new Error("createAnimationCanvas: relativeSize needs the canvas to have a parent element");
+		if (!parent) throw new Error("createAnimationCanvas: resizable needs the canvas to have a parent element");
 		observer = new ResizeObserver((entries) => {
 			for (const entry of entries) {
 				const { width: w, height: h } = entry.contentRect;
-				applySize(w, h);
+				if (w !== width || h !== height || devicePixelRatio() !== appliedDpr) applySize(w, h);
 				if (!(opts.animate ?? true)) drawFrame();
 			}
 		});
@@ -192,13 +212,14 @@ function createAnimationCanvas(canvas, options) {
 			opts = {
 				...opts,
 				...next,
-				relativeSize,
+				resizable,
 				contextAttributes: opts.contextAttributes
 			};
-			if (!relativeSize) {
+			if (!resizable) {
 				const { width: w = 100, height: h = 100 } = opts.size ?? {};
-				if (w != width || h != height) applySize(w, h);
+				if (w !== width || h !== height) applySize(w, h);
 			}
+			applyDevicePixelRatioIfNeeded();
 			const animating = opts.animate ?? true;
 			if (animating && !wasAnimating) startLoop();
 			if (!animating && wasAnimating) stopLoop();
@@ -215,16 +236,296 @@ function createAnimationCanvas(canvas, options) {
 	};
 }
 //#endregion
+//#region src/file/accept.ts
+/**
+* Does a file satisfy an `accept` attribute?
+*
+* `accept` is written the way the HTML attribute is: a comma separated list of
+* extensions (`.wav`), MIME types (`audio/wav`) and type groups (`audio/*`).
+* Anything that matches one entry is accepted, and an empty or missing
+* `accept` takes everything.
+*
+* **The browser's own `accept` is only a hint to the file picker.** A person
+* can switch it to "All Files", drag a file in, or pick one the picker was
+* never asked about, so what arrives still has to be checked.
+*
+* A rule that cannot be decided is not treated as a rejection: with no `name`,
+* an extension rule says nothing either way, and `accept=".wav"` reports a
+* match rather than refusing a file it has not seen the name of. The name is
+* there by the time the file is dropped, which is when the answer counts.
+*/
+function matchesAccept(candidate, accept) {
+	const rules = (accept ?? "").split(",").map((rule) => rule.trim().toLowerCase()).filter(Boolean);
+	if (rules.length === 0) return true;
+	const name = candidate.name?.toLowerCase();
+	const type = candidate.type.toLowerCase();
+	let undecided = false;
+	for (const rule of rules) if (rule.startsWith(".")) {
+		if (name === void 0) undecided = true;
+		else if (name.endsWith(rule)) return true;
+	} else if (rule.endsWith("/*")) {
+		if (type.startsWith(rule.slice(0, -1))) return true;
+	} else if (type === rule) return true;
+	return undecided;
+}
+//#endregion
+//#region src/file/drop-zone.ts
+/**
+* Take files dropped onto an element.
+*
+* ```ts
+* const zone = createDropZone(element, {
+*   accept: 'audio/*',
+*   onDrop: (files) => load(files[0]),
+* })
+* ```
+*
+* The element needs no attribute of its own: a drop target is made by
+* cancelling `dragover`, which this does.
+*/
+function createDropZone(element, options = {}) {
+	let opts = options;
+	let state = {
+		over: false,
+		invalid: false
+	};
+	/**
+	* `dragenter` and `dragleave` fire for descendants too, so moving between
+	* two children of the zone leaves before it enters. Counting the pairs is
+	* what keeps the state from flickering off in the middle of the element.
+	*/
+	let depth = 0;
+	function setState(next) {
+		if (next.over === state.over && next.invalid === state.invalid) return;
+		state = next;
+		opts.onStateChange?.(state);
+	}
+	function carriesFiles(transfer) {
+		return !!transfer?.types.includes("Files");
+	}
+	/** Whether anything being dragged could still be accepted. */
+	function anyAcceptable(transfer) {
+		const items = Array.from(transfer?.items ?? []).filter((item) => item.kind === "file");
+		if (items.length === 0) return true;
+		return items.some((item) => matchesAccept({ type: item.type }, opts.accept));
+	}
+	function onDragEnter(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		depth += 1;
+		setState({
+			over: true,
+			invalid: !anyAcceptable(event.dataTransfer)
+		});
+	}
+	function onDragOver(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		if (event.dataTransfer) event.dataTransfer.dropEffect = opts.disabled || state.invalid ? "none" : "copy";
+		if (!state.over) {
+			depth = Math.max(depth, 1);
+			setState({
+				over: true,
+				invalid: !anyAcceptable(event.dataTransfer)
+			});
+		}
+	}
+	function onDragLeave(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		depth = Math.max(0, depth - 1);
+		if (depth === 0) setState({
+			over: false,
+			invalid: false
+		});
+	}
+	function onDrop(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		depth = 0;
+		setState({
+			over: false,
+			invalid: false
+		});
+		if (opts.disabled) return;
+		const dropped = Array.from(event.dataTransfer?.files ?? []);
+		const accepted = [];
+		const rejected = [];
+		for (const file of dropped) if (matchesAccept(file, opts.accept)) accepted.push(file);
+		else rejected.push(file);
+		if (rejected.length > 0) opts.onReject?.(rejected, event);
+		const taken = opts.multiple ? accepted : accepted.slice(0, 1);
+		if (taken.length > 0) opts.onDrop?.(taken, event);
+	}
+	/**
+	* A drag that ends anywhere else — dropped on another element, cancelled
+	* with Esc, taken out of the window — sends no `dragleave` here, and the
+	* element would stay marked as a drop target for good.
+	*/
+	function onDragEndAnywhere() {
+		depth = 0;
+		setState({
+			over: false,
+			invalid: false
+		});
+	}
+	const handlers = {
+		dragenter: onDragEnter,
+		dragover: onDragOver,
+		dragleave: onDragLeave,
+		drop: onDrop
+	};
+	for (const [type, handler] of Object.entries(handlers)) element.addEventListener(type, handler);
+	const doc = element.ownerDocument;
+	doc?.addEventListener("dragend", onDragEndAnywhere);
+	doc?.addEventListener("drop", onDragEndAnywhere);
+	return {
+		get state() {
+			return state;
+		},
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		destroy: () => {
+			for (const [type, handler] of Object.entries(handlers)) element.removeEventListener(type, handler);
+			doc?.removeEventListener("dragend", onDragEndAnywhere);
+			doc?.removeEventListener("drop", onDragEndAnywhere);
+		}
+	};
+}
+//#endregion
+//#region src/input/modifiers.ts
+/**
+* Checked in this order, and the first one that is both held and configured
+* wins. Fixing an order is what keeps two modifiers held at once from
+* behaving differently between browsers.
+*/
+const MODIFIER_ORDER = [
+	"meta",
+	"ctrl",
+	"alt",
+	"shift"
+];
+const MODIFIER_FLAG = {
+	meta: "metaKey",
+	ctrl: "ctrlKey",
+	alt: "altKey",
+	shift: "shiftKey"
+};
+/**
+* A map is the only form with a `default` key, which is what tells it apart
+* from a bare setting. Tuples are arrays, so they never match.
+*/
+function isModifierMap(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "default" in value;
+}
+/**
+* Pick the setting that applies, given the modifier keys being held.
+*
+* @example
+* selectModifier({ default: 1, shift: 0.1 }, event)
+*/
+function selectModifier(options, modifiers) {
+	if (!isModifierMap(options)) return {
+		value: options,
+		modifier: null
+	};
+	if (modifiers) for (const modifier of MODIFIER_ORDER) {
+		const value = options[modifier];
+		if (value !== void 0 && modifiers[MODIFIER_FLAG[modifier]]) return {
+			value,
+			modifier
+		};
+	}
+	return {
+		value: options.default,
+		modifier: null
+	};
+}
+/**
+* Turn every entry of a setting into another kind of setting, keeping which
+* modifier each belongs to.
+*
+* A drag sensitivity is a number and a keyboard amount is a tuple, but the two
+* describe the same thing from the caller's side. This carries one over to the
+* other so that a component can hand a sensitivity to {@link applyDelta}
+* without unpicking the modifier map itself — which matters, since naming a
+* modifier is also what takes `step` out of the pipeline.
+*
+* @example
+* mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
+* // { default: ['raw', 1], shift: ['raw', 0.1] }
+*/
+function mapModifier(options, fn) {
+	if (!isModifierMap(options)) return fn(options);
+	const mapped = { default: fn(options.default) };
+	for (const modifier of MODIFIER_ORDER) {
+		const value = options[modifier];
+		if (value !== void 0) mapped[modifier] = fn(value);
+	}
+	return mapped;
+}
+//#endregion
+//#region src/input/apply-delta.ts
+/**
+* Move a value by an amount of input, as reported by a wheel or an arrow key.
+*
+* The pipeline matches {@link createDragValue}: scale, then step, then clamp.
+* Which key or which sign of `deltaY` counts as which direction is left to the
+* caller, since it differs per component.
+*
+* @param direction which way, and how many times, to apply the option. The
+* size of one step is `option[1]`, so this is normally `1` or `-1`.
+*
+* @param modifiers the event, for `options` that name a modifier key. See
+* {@link selectModifier}.
+*
+* @example
+* // ArrowDown on a slider whose keyboard option is ['raw', 1]
+* applyDelta(value, -1, keyboard, { min, max, step, scale })
+*
+* @example
+* // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
+* applyDelta(value, -1, keyboard, range, event)
+*/
+function applyDelta(value, direction, options, { min, max, step, scale = _tremolo_ui_functions.linearScale }, modifiers) {
+	if (min >= max) throw new RangeError("requirements: min < max");
+	if (step !== void 0 && (!Number.isFinite(step) || step <= 0)) throw new RangeError("applyDelta step: requirements: finite and greater than 0");
+	const { value: [mode, amount], modifier } = selectModifier(options, modifiers);
+	const x = direction * amount;
+	const next = mode === "normalized" ? scale.denormalize(scale.normalize(value, min, max) + x, min, max) : value + x;
+	const quantum = modifier === null ? step : void 0;
+	const stepped = quantum !== void 0 ? (0, _tremolo_ui_functions.stepValue)(next, quantum) : next;
+	return (0, _tremolo_ui_functions.clamp)((0, _tremolo_ui_functions.toPrecision)(stepped), min, max);
+}
+//#endregion
 //#region src/midi/access.ts
 /** @private */
 const PERMISSION_DENIED = "PERMISSION_DENIED";
 /** @private */
 const NOT_SUPPORTED = "NOT_SUPPORTED";
+/** @private */
+const UNAVAILABLE = "UNAVAILABLE";
 const INITIAL_STATE = {
 	midiAccess: null,
-	error: null
+	error: null,
+	inputs: []
 };
 /**
+* Which of our errors a rejected `requestMIDIAccess()` amounts to.
+*
+* The spec names the reasons, and they need telling apart: a user who said no
+* can say yes on a second ask, while a browser without the API never will.
+*/
+function toError(reason) {
+	const name = typeof reason === "object" && reason !== null && "name" in reason ? String(reason.name) : "";
+	if (name === "SecurityError" || name === "NotAllowedError") return PERMISSION_DENIED;
+	if (name === "NotSupportedError" || name === "TypeError") return NOT_SUPPORTED;
+	return UNAVAILABLE;
+}
+/**
 * Request MIDI access in the browser.
 *
 * The returned instance holds the state and notifies subscribers when it changes,
@@ -233,13 +534,31 @@ const INITIAL_STATE = {
 function createMIDIAccess() {
 	let state = INITIAL_STATE;
 	let destroyed = false;
+	let access = null;
+	let requestGeneration = 0;
 	const listeners = /* @__PURE__ */ new Set();
 	function setState(next) {
 		state = next;
 		for (const listener of listeners) listener();
 	}
-	function request() {
+	/**
+	* A new array every time, so that `useSyncExternalStore` and its equivalents
+	* see the change. The identity of the state object is what they compare.
+	*/
+	function readInputs() {
+		return access ? [...access.inputs.values()] : [];
+	}
+	function handleStateChange(event) {
+		if (destroyed || !access) return;
+		if (event && event.port?.type === "output") return;
+		setState({
+			...state,
+			inputs: readInputs()
+		});
+	}
+	function request(options = {}) {
 		if (destroyed) return;
+		const generation = ++requestGeneration;
 		if (typeof navigator === "undefined" || !navigator.requestMIDIAccess) {
 			setState({
 				...state,
@@ -247,17 +566,21 @@ function createMIDIAccess() {
 			});
 			return;
 		}
-		navigator.requestMIDIAccess().then((access) => {
-			if (destroyed) return;
+		navigator.requestMIDIAccess({ sysex: options.sysex ?? false }).then((granted) => {
+			if (destroyed || generation !== requestGeneration) return;
+			access?.removeEventListener("statechange", handleStateChange);
+			access = granted;
+			granted.addEventListener("statechange", handleStateChange);
 			setState({
-				midiAccess: access,
-				error: null
+				midiAccess: granted,
+				error: null,
+				inputs: readInputs()
 			});
-		}).catch(() => {
-			if (destroyed) return;
+		}, (reason) => {
+			if (destroyed || generation !== requestGeneration) return;
 			setState({
 				...state,
-				error: PERMISSION_DENIED
+				error: toError(reason)
 			});
 		});
 	}
@@ -273,6 +596,9 @@ function createMIDIAccess() {
 		},
 		destroy: () => {
 			destroyed = true;
+			requestGeneration += 1;
+			access?.removeEventListener("statechange", handleStateChange);
+			access = null;
 			listeners.clear();
 		}
 	};
@@ -282,35 +608,217 @@ function createMIDIAccess() {
 /**
 * Listen to raw `midimessage` events on every input of a MIDIAccess.
 *
+* The set of inputs is followed rather than sampled: MIDIAccess fires
+* `statechange` when a device is plugged in or unplugged, and the listeners
+* move with it. A keyboard connected after access was granted works without
+* the caller having to rebuild anything.
+*
 * Use this when you need more detail than {@link createMIDIInput} provides.
 */
 function createMIDIMessage(midiAccess, onMIDIMessage) {
-	if (!midiAccess) return { destroy: () => {} };
-	const inputs = [...midiAccess.inputs.values()];
-	for (const input of inputs) input.addEventListener("midimessage", onMIDIMessage);
-	return { destroy: () => {
-		for (const input of inputs) input.removeEventListener("midimessage", onMIDIMessage);
-	} };
+	let handler = onMIDIMessage;
+	/** Inputs this instance currently listens on. */
+	const attached = /* @__PURE__ */ new Set();
+	const listener = (event) => handler(event);
+	function sync() {
+		if (!midiAccess) return;
+		const connected = new Set(midiAccess.inputs.values());
+		for (const input of connected) {
+			if (attached.has(input)) continue;
+			input.addEventListener("midimessage", listener);
+			attached.add(input);
+		}
+		for (const input of [...attached]) {
+			if (connected.has(input)) continue;
+			input.removeEventListener("midimessage", listener);
+			attached.delete(input);
+		}
+	}
+	sync();
+	midiAccess?.addEventListener("statechange", sync);
+	return {
+		update: (next) => {
+			handler = next;
+		},
+		destroy: () => {
+			midiAccess?.removeEventListener("statechange", sync);
+			for (const input of attached) input.removeEventListener("midimessage", listener);
+			attached.clear();
+		}
+	};
 }
 //#endregion
 //#region src/midi/input.ts
-const MIDI_EVENT_TO_NUMBER = {
-	NOTE_ON: 144,
+/** Status byte of each channel message, with the channel nibble cleared. */
+const STATUS = {
 	NOTE_OFF: 128,
+	NOTE_ON: 144,
+	AFTERTOUCH: 160,
+	CONTROL_CHANGE: 176,
+	PROGRAM_CHANGE: 192,
+	CHANNEL_PRESSURE: 208,
 	PITCH_BEND: 224
 };
 /**
-* Handle note on/off and pitch bend events. To be used with {@link createMIDIAccess}.
-* Internally uses {@link createMIDIMessage}.
+* Centre of the 14-bit pitch bend range: no bend.
+*
+* The range is not symmetric — 0 is 8192 below centre and 16383 is 8191 above
+* — so a wheel at rest reports exactly this rather than half of the maximum.
 */
-function createMIDIInput(midiAccess, { onNoteOnEvent, onNoteOffEvent, onPitchBendEvent }) {
-	return createMIDIMessage(midiAccess, (event) => {
-		if (!event.data) return;
-		const kind = event.data[0] & 240;
-		if (kind == MIDI_EVENT_TO_NUMBER.NOTE_OFF || kind == MIDI_EVENT_TO_NUMBER.NOTE_ON && event.data[2] == 0) onNoteOffEvent?.(event.data[1]);
-		else if (kind == MIDI_EVENT_TO_NUMBER.NOTE_ON) onNoteOnEvent?.(event.data[1], event.data[2]);
-		else if (kind == MIDI_EVENT_TO_NUMBER.PITCH_BEND) onPitchBendEvent?.(event.data[1], event.data[2]);
-	});
+const PITCH_BEND_CENTER = 8192;
+/**
+* Handle the channel voice messages of every connected input. To be used with
+* {@link createMIDIAccess}. Internally uses {@link createMIDIMessage}, so
+* devices plugged in later are picked up.
+*
+* System messages (clock, sysex, and the rest of `0xf0`-`0xff`) are not
+* decoded here; reach for {@link createMIDIMessage} for those.
+*/
+function createMIDIInput(midiAccess, handlers) {
+	let current = handlers;
+	return {
+		update: (next) => {
+			current = next;
+		},
+		destroy: createMIDIMessage(midiAccess, (event) => {
+			if (!event.data || event.data.length === 0) return;
+			const status = event.data[0];
+			if (status >= 240) return;
+			const kind = status & 240;
+			const channel = status & 15;
+			const first = event.data[1] ?? 0;
+			const second = event.data[2] ?? 0;
+			switch (kind) {
+				case STATUS.NOTE_OFF:
+					current.onNoteOffEvent?.(first, channel);
+					break;
+				case STATUS.NOTE_ON:
+					if (second === 0) current.onNoteOffEvent?.(first, channel);
+					else current.onNoteOnEvent?.(first, second, channel);
+					break;
+				case STATUS.AFTERTOUCH:
+					current.onAftertouchEvent?.(first, second, channel);
+					break;
+				case STATUS.CONTROL_CHANGE:
+					current.onControlChangeEvent?.(first, second, channel);
+					break;
+				case STATUS.PROGRAM_CHANGE:
+					current.onProgramChangeEvent?.(first, channel);
+					break;
+				case STATUS.CHANNEL_PRESSURE:
+					current.onChannelPressureEvent?.(first, channel);
+					break;
+				case STATUS.PITCH_BEND: current.onPitchBendEvent?.(second << 7 | first, channel);
+			}
+		}).destroy
+	};
+}
+//#endregion
+//#region src/piano/layout.ts
+/**
+* `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
+*/
+function getNoteRangeArray(noteRange) {
+	return Array.from({ length: noteRange.last - noteRange.first + 1 }, (_, i) => i + noteRange.first);
+}
+const DEFAULT_KEY_GAP = 1;
+const DEFAULT_BLACK_KEY_WIDTH_RATIO = .65;
+const DEFAULT_BLACK_KEY_HEIGHT_RATIO = .6;
+/**
+* How many white keys sit at or before each pitch class, counting from C.
+*
+* A black key shares the number of the white key to its left plus one, which
+* puts it on the boundary between the two; {@link notePosition} then shifts it
+* back by half its width to centre it there.
+*/
+const whiteKeysBefore = {
+	C: 0,
+	"C#": 1,
+	D: 1,
+	"D#": 2,
+	E: 2,
+	F: 3,
+	"F#": 4,
+	G: 4,
+	"G#": 5,
+	A: 5,
+	"A#": 6,
+	B: 6
+};
+/** Width of a black key in pixels. */
+function blackKeyWidth(layout) {
+	return layout.whiteKeyWidth * (layout.blackKeyWidthRatio ?? DEFAULT_BLACK_KEY_WIDTH_RATIO);
+}
+function rawNotePosition(note, layout) {
+	const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
+	const target = (0, _tremolo_ui_functions.noteKey)(note);
+	const first = (0, _tremolo_ui_functions.noteKey)(layout.noteRange.first);
+	const octave = Math.floor((note - layout.noteRange.first) / 12);
+	const octaveOffset = _tremolo_ui_functions.noteKeys.indexOf(first) > _tremolo_ui_functions.noteKeys.indexOf(target) ? 1 : 0;
+	const whiteKeysIn = whiteKeysBefore[target] - whiteKeysBefore[first] + (octave + octaveOffset) * 7;
+	return (0, _tremolo_ui_functions.isBlackKey)(note) ? whiteKeysIn * slot - blackKeyWidth(layout) / 2 : whiteKeysIn * slot;
+}
+function pianoBounds(layout) {
+	const notes = getNoteRangeArray(layout.noteRange);
+	if (notes.length === 0) return {
+		left: 0,
+		right: 0
+	};
+	let left = Infinity;
+	let right = -Infinity;
+	const whiteWidth = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
+	for (const note of notes) {
+		const noteLeft = rawNotePosition(note, layout);
+		const width = (0, _tremolo_ui_functions.isBlackKey)(note) ? blackKeyWidth(layout) : whiteWidth;
+		left = Math.min(left, noteLeft);
+		right = Math.max(right, noteLeft + width);
+	}
+	return {
+		left,
+		right
+	};
+}
+/** Width of the whole keyboard in pixels. */
+function pianoWidth(layout) {
+	const { left, right } = pianoBounds(layout);
+	return right - left;
+}
+/**
+* Offset of the left edge of a key from the left edge of the keyboard, in
+* pixels.
+*
+* Notes outside `noteRange` are placed too, so the value is negative below
+* `noteRange.first`.
+*/
+function notePosition(note, layout) {
+	return rawNotePosition(note, layout) - pianoBounds(layout).left;
+}
+/**
+* The note drawn at a point, or null where there is none.
+*
+* Black keys are tested first, so they win where they overlap a white one. A
+* white key covers its gap as well as its width, so the whole width of the
+* keyboard belongs to some key and a click cannot fall between two.
+*
+* @param x offset from the left edge of the keyboard, in pixels
+* @param y offset from its top edge, in pixels
+* @param height height of the keyboard, in pixels
+*/
+function noteAt(x, y, height, layout) {
+	if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null;
+	const notes = getNoteRangeArray(layout.noteRange);
+	if (y < height * (layout.blackKeyHeightRatio ?? DEFAULT_BLACK_KEY_HEIGHT_RATIO)) for (const note of notes) {
+		if ((0, _tremolo_ui_functions.isWhiteKey)(note)) continue;
+		const left = notePosition(note, layout);
+		if (left <= x && x < left + blackKeyWidth(layout)) return note;
+	}
+	const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
+	for (const note of notes) {
+		if ((0, _tremolo_ui_functions.isBlackKey)(note)) continue;
+		const left = notePosition(note, layout);
+		if (left <= x && x < left + slot) return note;
+	}
+	return null;
 }
 //#endregion
 //#region src/pointer/drag.ts
@@ -327,6 +835,7 @@ const MANAGED_STYLES = [
 	["-webkit-user-select", "none"],
 	["-webkit-touch-callout", "none"]
 ];
+const managedStyleStates = /* @__PURE__ */ new WeakMap();
 /**
 * Track a pointer drag on an element.
 *
@@ -343,10 +852,24 @@ function createDrag(element, options = {}) {
 	const multiPointer = options.multiPointer ?? false;
 	const capture = element;
 	const style = element.style;
-	const previousStyles = /* @__PURE__ */ new Map();
-	if (style) for (const [property, value] of MANAGED_STYLES) {
-		previousStyles.set(property, style.getPropertyValue(property));
-		style.setProperty(property, value);
+	let managedStyles = managedStyleStates.get(element);
+	if (style) {
+		if (managedStyles) managedStyles.count += 1;
+		else {
+			const previous = /* @__PURE__ */ new Map();
+			for (const [property, value] of MANAGED_STYLES) {
+				previous.set(property, {
+					value: style.getPropertyValue(property),
+					priority: style.getPropertyPriority(property)
+				});
+				style.setProperty(property, value);
+			}
+			managedStyles = {
+				count: 1,
+				previous
+			};
+			managedStyleStates.set(element, managedStyles);
+		}
 	}
 	const pointers = /* @__PURE__ */ new Map();
 	/**
@@ -356,10 +879,14 @@ function createDrag(element, options = {}) {
 	*/
 	const targets = /* @__PURE__ */ new Map();
 	let previousCursor;
+	/** The pointer that asked for the lock, while it is still down. */
+	let lockedPointerId = null;
+	let lockRequest = 0;
+	let destroyed = false;
 	function state(event, pointer, deltaX, deltaY) {
 		return {
-			x: event.screenX - pointer.startX,
-			y: event.screenY - pointer.startY,
+			x: pointer.lockBaseX !== void 0 ? pointer.lockBaseX + pointer.lockMoveX : event.screenX - pointer.startX,
+			y: pointer.lockBaseY !== void 0 ? pointer.lockBaseY + pointer.lockMoveY : event.screenY - pointer.startY,
 			deltaX,
 			deltaY,
 			clientX: event.clientX,
@@ -382,6 +909,7 @@ function createDrag(element, options = {}) {
 			target.addEventListener("pointermove", handlePointerMove);
 			target.addEventListener("pointerup", handlePointerUp);
 			target.addEventListener("pointercancel", handlePointerUp);
+			if (target === element) target.addEventListener("lostpointercapture", handleLostPointerCapture);
 		}
 		targets.set(target, count + 1);
 	}
@@ -394,13 +922,16 @@ function createDrag(element, options = {}) {
 		target.removeEventListener("pointermove", handlePointerMove);
 		target.removeEventListener("pointerup", handlePointerUp);
 		target.removeEventListener("pointercancel", handlePointerUp);
+		if (target === element) target.removeEventListener("lostpointercapture", handleLostPointerCapture);
 		targets.delete(target);
 	}
 	function handlePointerDown(event) {
 		const pointerEvent = event;
+		if (pointerEvent.button !== 0) return;
 		const pointerId = pointerEvent.pointerId;
 		if (pointers.has(pointerId)) return;
 		if (!multiPointer && pointers.size > 0) return;
+		if (opts.shouldStart && !opts.shouldStart(pointerEvent)) return;
 		const isFirst = pointers.size === 0;
 		if (isFirst && opts.cursor && style) {
 			previousCursor = style.cursor;
@@ -413,39 +944,86 @@ function createDrag(element, options = {}) {
 			startX: pointerEvent.screenX,
 			startY: pointerEvent.screenY,
 			lastX: pointerEvent.screenX,
-			lastY: pointerEvent.screenY
+			lastY: pointerEvent.screenY,
+			lockMoveX: 0,
+			lockMoveY: 0,
+			lastEvent: pointerEvent
 		};
 		pointers.set(pointerId, pointer);
 		retainTarget(moveTarget);
 		if (isFirst) globalThis.document?.addEventListener("selectstart", preventSelectStart);
+		if (isFirst && opts.pointerLock) {
+			const requestId = ++lockRequest;
+			lockedPointerId = pointerId;
+			globalThis.document?.addEventListener("pointerlockchange", handleLockChange);
+			try {
+				(capture.requestPointerLock?.())?.then?.(() => {
+					if (requestId === lockRequest && (!pointers.has(pointerId) || destroyed) && globalThis.document?.pointerLockElement === element) globalThis.document.exitPointerLock?.();
+				}, () => {});
+			} catch {}
+		}
 		opts.onDragStart?.(state(pointerEvent, pointer, 0, 0));
 	}
 	function handlePointerMove(event) {
 		const pointerEvent = event;
 		const pointer = pointers.get(pointerEvent.pointerId);
 		if (!pointer) return;
-		const deltaX = pointerEvent.screenX - pointer.lastX;
-		const deltaY = pointerEvent.screenY - pointer.lastY;
+		const locked = pointer.lockBaseX !== void 0;
+		const deltaX = locked ? pointerEvent.movementX ?? 0 : pointerEvent.screenX - pointer.lastX;
+		const deltaY = locked ? pointerEvent.movementY ?? 0 : pointerEvent.screenY - pointer.lastY;
 		const threshold = opts.threshold ?? 0;
 		if (Math.abs(deltaX) < threshold && Math.abs(deltaY) < threshold) return;
 		pointer.lastX = pointerEvent.screenX;
 		pointer.lastY = pointerEvent.screenY;
+		pointer.lastEvent = pointerEvent;
+		if (locked) {
+			pointer.lockMoveX += deltaX;
+			pointer.lockMoveY += deltaY;
+		}
 		opts.onDrag?.(state(pointerEvent, pointer, deltaX, deltaY));
 	}
+	function handleLockChange() {
+		if (lockedPointerId === null) return;
+		const pointer = pointers.get(lockedPointerId);
+		if (!pointer) return;
+		if (globalThis.document?.pointerLockElement === element) {
+			pointer.lockBaseX = pointer.lastX - pointer.startX;
+			pointer.lockBaseY = pointer.lastY - pointer.startY;
+			pointer.lockMoveX = 0;
+			pointer.lockMoveY = 0;
+			return;
+		}
+		if (pointer.lockBaseX === void 0) return;
+		finishDrag(lockedPointerId);
+	}
 	function handlePointerUp(event) {
 		const pointerEvent = event;
-		const pointer = pointers.get(pointerEvent.pointerId);
+		finishDrag(pointerEvent.pointerId, pointerEvent);
+	}
+	function handleLostPointerCapture(event) {
+		finishDrag(event.pointerId);
+	}
+	function finishDrag(pointerId, event) {
+		const pointer = pointers.get(pointerId);
 		if (!pointer) return;
-		const finalState = state(pointerEvent, pointer, pointerEvent.screenX - pointer.lastX, pointerEvent.screenY - pointer.lastY);
-		stopTracking(pointerEvent.pointerId);
+		const finalState = event ? state(event, pointer, event.screenX - pointer.lastX, event.screenY - pointer.lastY) : state(pointer.lastEvent, pointer, 0, 0);
+		stopTracking(pointerId);
 		opts.onDragEnd?.(finalState);
 	}
 	function stopTracking(pointerId) {
 		const pointer = pointers.get(pointerId);
 		if (!pointer) return;
-		capture.releasePointerCapture?.(pointerId);
-		releaseTarget(pointer.moveTarget);
 		pointers.delete(pointerId);
+		releaseTarget(pointer.moveTarget);
+		try {
+			if (capture.hasPointerCapture?.(pointerId) === true) capture.releasePointerCapture?.(pointerId);
+		} catch {}
+		if (lockedPointerId === pointerId) {
+			lockedPointerId = null;
+			const document = globalThis.document;
+			document?.removeEventListener("pointerlockchange", handleLockChange);
+			if (document?.pointerLockElement === element) document.exitPointerLock?.();
+		}
 		if (pointers.size > 0) return;
 		globalThis.document?.removeEventListener("selectstart", preventSelectStart);
 		if (previousCursor !== void 0 && style) {
@@ -463,18 +1041,23 @@ function createDrag(element, options = {}) {
 			};
 		},
 		destroy: () => {
-			for (const pointerId of [...pointers.keys()]) stopTracking(pointerId);
+			if (destroyed) return;
+			destroyed = true;
 			element.removeEventListener("pointerdown", handlePointerDown);
-			if (style) for (const [property] of MANAGED_STYLES) {
-				const previous = previousStyles.get(property);
-				if (previous) style.setProperty(property, previous);
-				else style.removeProperty(property);
+			for (const pointerId of [...pointers.keys()]) finishDrag(pointerId);
+			if (style && managedStyles && --managedStyles.count === 0) {
+				for (const [property] of MANAGED_STYLES) {
+					const previous = managedStyles.previous.get(property);
+					if (previous?.value) style.setProperty(property, previous.value, previous.priority);
+					else style.removeProperty(property);
+				}
+				managedStyleStates.delete(element);
 			}
 		}
 	};
 }
 //#endregion
-//#region src/piano/input.ts
+//#region src/piano/index.ts
 const DEFAULT_SOURCE = "api";
 /**
 * Drive a piano keyboard with pointers, and own what is sounding.
@@ -496,17 +1079,19 @@ function createPianoInput(element, options) {
 		return [...held.keys()].sort((a, b) => a - b);
 	}
 	function noteOn(note, { source = DEFAULT_SOURCE, velocity } = {}) {
+		if (!Number.isInteger(note) || note < 0 || note > 127) throw new RangeError("note: requirements: an integer from 0 to 127");
 		if (note > (opts.midiMax ?? 127)) return;
 		const sources = held.get(note);
 		if (sources) {
 			sources.add(source);
 			return;
 		}
-		held.set(note, new Set([source]));
+		held.set(note, /* @__PURE__ */ new Set([source]));
 		opts.onPlayNote?.(note, velocity);
 		opts.onActiveNotesChange?.(activeNotes());
 	}
 	function noteOff(note, { source = DEFAULT_SOURCE } = {}) {
+		if (!Number.isInteger(note) || note < 0 || note > 127) throw new RangeError("note: requirements: an integer from 0 to 127");
 		const sources = held.get(note);
 		if (!sources) return;
 		sources.delete(source);
@@ -518,7 +1103,7 @@ function createPianoInput(element, options) {
 	/** The note under a pointer, or null where the pointer is off the keys. */
 	function noteUnder(clientX, clientY) {
 		const { left, top, height } = element.getBoundingClientRect();
-		return (0, _tremolo_ui_functions.noteAt)(clientX - left, clientY - top, height, opts.layout);
+		return noteAt(clientX - left, clientY - top, height, opts.layout);
 	}
 	/** Move a pointer onto a note, releasing whatever it held before. */
 	function movePointer(pointerId, note) {
@@ -526,7 +1111,7 @@ function createPianoInput(element, options) {
 		const previous = pointerNotes.get(pointerId);
 		if (previous === note) return;
 		if (previous !== void 0) noteOff(previous, { source });
-		if (note === null) pointerNotes.delete(pointerId);
+		if (note === null || note > (opts.midiMax ?? 127)) pointerNotes.delete(pointerId);
 		else {
 			pointerNotes.set(pointerId, note);
 			noteOn(note, { source });
@@ -547,18 +1132,28 @@ function createPianoInput(element, options) {
 				...opts,
 				...next
 			};
+			const midiMax = opts.midiMax ?? 127;
+			const stoppedNotes = activeNotes().filter((note) => note > midiMax);
+			if (stoppedNotes.length === 0) return;
+			for (const note of stoppedNotes) {
+				held.delete(note);
+				opts.onStopNote?.(note);
+			}
+			for (const [pointerId, note] of pointerNotes) if (note > midiMax) pointerNotes.delete(pointerId);
+			opts.onActiveNotesChange?.(activeNotes());
 		},
 		noteOn,
 		noteOff,
 		activeNotes,
 		destroy: () => {
 			drag.destroy();
-			for (const note of activeNotes()) {
+			const notes = activeNotes();
+			for (const note of notes) {
 				held.delete(note);
 				opts.onStopNote?.(note);
 			}
 			pointerNotes.clear();
-			opts.onActiveNotesChange?.([]);
+			if (notes.length > 0) opts.onActiveNotesChange?.([]);
 		}
 	};
 }
@@ -581,7 +1176,7 @@ function toXY(value) {
 	return isPair(value) ? [value[0], value[1]] : [value, value];
 }
 //#endregion
-//#region src/pointer/dragValue.ts
+//#region src/pointer/drag-value.ts
 /**
 * Map the pointer onto the bounding rect of an element: the value *is* the
 * position pointed at, so the middle of the element is 0.5.
@@ -589,16 +1184,43 @@ function toXY(value) {
 * The element is read on every event, so it may be mounted after the drag is
 * set up and may change size while a drag is in progress.
 */
-function elementMapping(getElement) {
+function elementMapping(getElement, { sensitivity } = {}) {
+	/** The reported position when the sensitivity last changed. */
+	let origin = [0, 0];
+	/** The raw position at that same moment. */
+	let anchor = [0, 0];
+	/** The previous event, so a sensitivity change can be dated back to it. */
+	let previous = [0, 0];
+	let factor = 1;
 	function positionIn(state) {
 		const element = getElement();
 		if (!element) return null;
 		const { left, top, right, bottom } = element.getBoundingClientRect();
 		return [right > left ? (0, _tremolo_ui_functions.normalizeValue)(state.clientX, left, right) : 0, bottom > top ? (0, _tremolo_ui_functions.normalizeValue)(state.clientY, top, bottom) : 0];
 	}
+	const reported = (raw, at) => [origin[0] + (raw[0] - anchor[0]) * at, origin[1] + (raw[1] - anchor[1]) * at];
 	return {
-		start: positionIn,
-		move: positionIn
+		start: (state) => {
+			const raw = positionIn(state);
+			if (!raw) return null;
+			origin = raw;
+			anchor = raw;
+			previous = raw;
+			factor = sensitivity ? sensitivity(state) : 1;
+			return raw;
+		},
+		move: (state) => {
+			const raw = positionIn(state);
+			if (!raw) return null;
+			const next = sensitivity ? sensitivity(state) : 1;
+			if (next !== factor) {
+				origin = reported(previous, factor);
+				anchor = previous;
+				factor = next;
+			}
+			previous = raw;
+			return reported(raw, factor);
+		}
 	};
 }
 /**
@@ -606,15 +1228,33 @@ function elementMapping(getElement) {
 * distance dragged. The pointer position itself carries no meaning, so the
 * value can be adjusted from anywhere on the screen.
 */
-function relativeMapping({ pixelRange = 100 } = {}) {
-	const [rangeX, rangeY] = toXY(pixelRange);
+function relativeMapping({ pixelRange = 100, sensitivity } = {}) {
+	const [baseX, baseY] = toXY(pixelRange);
 	let origin = [0, 0];
+	/** Where the current sensitivity took over, in drag coordinates. */
+	let anchor = [0, 0];
+	/** The previous event, so a sensitivity change can be dated back to it. */
+	let previous = [0, 0];
+	let factor = 1;
+	const travelled = (to, at) => [baseX === 0 ? origin[0] : origin[0] + (to[0] - anchor[0]) * at / baseX, baseY === 0 ? origin[1] : origin[1] + (to[1] - anchor[1]) * at / baseY];
 	return {
-		start: (_state, context) => {
+		start: (state, context) => {
 			origin = context.position();
+			anchor = [0, 0];
+			previous = [0, 0];
+			factor = sensitivity ? sensitivity(state) : 1;
 			return origin;
 		},
-		move: (state) => [origin[0] + state.x / rangeX, origin[1] + state.y / rangeY]
+		move: (state) => {
+			const next = sensitivity ? sensitivity(state) : 1;
+			if (next !== factor) {
+				origin = travelled(previous, factor);
+				anchor = previous;
+				factor = next;
+			}
+			previous = [state.x, state.y];
+			return travelled([state.x, state.y], factor);
+		}
 	};
 }
 /**
@@ -627,12 +1267,14 @@ function relativeMapping({ pixelRange = 100 } = {}) {
 function createDragValue(element, options) {
 	let opts = options;
 	let lastValue = [0, 0];
+	let active = false;
 	const axes = () => toXY(opts.axis);
 	function valueOf(position) {
 		return axes().map((axis, i) => {
 			const p = axis.reverse ? 1 - position[i] : position[i];
 			const value = (axis.scale ?? _tremolo_ui_functions.linearScale).denormalize(p, axis.min, axis.max);
-			return (0, _tremolo_ui_functions.clamp)(axis.step ? (0, _tremolo_ui_functions.stepValue)(value, axis.step) : value, axis.min, axis.max);
+			const stepped = axis.step ? (0, _tremolo_ui_functions.stepValue)(value, axis.step) : value;
+			return (0, _tremolo_ui_functions.clamp)((0, _tremolo_ui_functions.toPrecision)(stepped), axis.min, axis.max);
 		});
 	}
 	const context = { position: () => {
@@ -647,21 +1289,35 @@ function createDragValue(element, options) {
 	const drag = createDrag(element, {
 		threshold: opts.threshold,
 		cursor: opts.cursor,
+		pointerLock: opts.pointerLock,
+		shouldStart: (event) => opts.shouldStart?.(event) ?? true,
 		onDragStart: (state) => {
 			const position = opts.mapping.start(state, context);
-			if (position) {
-				lastValue = valueOf(position);
-				if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state);
-			}
+			if (!position) return;
+			active = true;
+			lastValue = valueOf(position);
+			if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state);
 			opts.onDragStart?.(lastValue, state);
 		},
 		onDrag: (state) => {
+			if (!active) return;
 			const position = opts.mapping.move(state, context);
 			if (!position) return;
 			lastValue = valueOf(position);
 			opts.onChange?.(lastValue, state);
 		},
-		onDragEnd: (state) => opts.onDragEnd?.(lastValue, state)
+		onDragEnd: (state) => {
+			if (!active) return;
+			if (state.event.type === "pointerup" && (state.deltaX !== 0 || state.deltaY !== 0)) {
+				const position = opts.mapping.move(state, context);
+				if (position) {
+					lastValue = valueOf(position);
+					opts.onChange?.(lastValue, state);
+				}
+			}
+			active = false;
+			opts.onDragEnd?.(lastValue, state);
+		}
 	});
 	return {
 		update: (next) => {
@@ -672,7 +1328,8 @@ function createDragValue(element, options) {
 			};
 			drag.update({
 				threshold: opts.threshold,
-				cursor: opts.cursor
+				cursor: opts.cursor,
+				pointerLock: opts.pointerLock
 			});
 		},
 		destroy: () => drag.destroy()
@@ -687,14 +1344,17 @@ function createDragValue(element, options) {
 * `preventDefault()` to stop the page from scrolling.
 */
 function createWheel(element, onWheel, options = {}) {
-	let opts = options;
+	let opts = {
+		...options,
+		onWheel
+	};
 	function hasFocus() {
 		const active = element.ownerDocument?.activeElement;
 		return !!active && element.contains(active);
 	}
 	const handler = (event) => {
 		if (opts.requireFocus && !hasFocus()) return;
-		onWheel(event);
+		opts.onWheel?.(event);
 	};
 	element.addEventListener("wheel", handler, { passive: false });
 	return {
@@ -710,20 +1370,101 @@ function createWheel(element, onWheel, options = {}) {
 	};
 }
 //#endregion
+//#region src/selection/box.ts
+function rectOf(from, to) {
+	return {
+		x: Math.min(from[0], to[0]),
+		y: Math.min(from[1], to[1]),
+		width: Math.abs(to[0] - from[0]),
+		height: Math.abs(to[1] - from[1])
+	};
+}
+/** Whether the box covers the point, edges included. */
+function selectionBoxCovers(box, [x, y]) {
+	return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
+}
+/**
+* Selecting by dragging a box over a set of items.
+*
+* The drag itself is not here: the caller owns the pointer, and reports where
+* it went in the same 0..1 space the items are given in.
+*/
+function createSelectionBox(options) {
+	let opts = options;
+	let drag = null;
+	let box = null;
+	function setBox(next) {
+		box = next;
+		opts.onBoxChange?.(next);
+	}
+	function apply(rect, base) {
+		const inside = [];
+		for (const [id, at] of opts.items()) if (selectionBoxCovers(rect, at) && !base.includes(id)) inside.push(id);
+		opts.onSelectionChange?.([...base, ...inside]);
+	}
+	return {
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		begin: (at, { additive = false, selection = [] } = {}) => {
+			drag = {
+				from: at,
+				base: additive ? [...selection] : []
+			};
+			setBox(rectOf(at, at));
+			if (!additive) opts.onSelectionChange?.([]);
+		},
+		move: (to) => {
+			if (!drag) return;
+			const rect = rectOf(drag.from, to);
+			setBox(rect);
+			apply(rect, drag.base);
+		},
+		end: () => {
+			const running = drag !== null;
+			drag = null;
+			if (box !== null) setBox(null);
+			return running;
+		},
+		box: () => box,
+		destroy: () => {
+			drag = null;
+			box = null;
+		}
+	};
+}
+//#endregion
 exports.NOT_SUPPORTED = NOT_SUPPORTED;
 exports.PERMISSION_DENIED = PERMISSION_DENIED;
+exports.PITCH_BEND_CENTER = PITCH_BEND_CENTER;
+exports.UNAVAILABLE = UNAVAILABLE;
+exports.applyDelta = applyDelta;
+exports.blackKeyWidth = blackKeyWidth;
 exports.createAnimationCanvas = createAnimationCanvas;
 exports.createDrag = createDrag;
 exports.createDragValue = createDragValue;
+exports.createDropZone = createDropZone;
 exports.createMIDIAccess = createMIDIAccess;
 exports.createMIDIInput = createMIDIInput;
 exports.createMIDIMessage = createMIDIMessage;
 exports.createPianoInput = createPianoInput;
+exports.createSelectionBox = createSelectionBox;
 exports.createWheel = createWheel;
 exports.drawingState = drawingState;
 exports.elementMapping = elementMapping;
+exports.getNoteRangeArray = getNoteRangeArray;
 exports.isDrawingState = isDrawingState;
+exports.mapModifier = mapModifier;
+exports.matchesAccept = matchesAccept;
+exports.noteAt = noteAt;
+exports.notePosition = notePosition;
+exports.pianoWidth = pianoWidth;
 exports.relativeMapping = relativeMapping;
+exports.selectModifier = selectModifier;
+exports.selectionBoxCovers = selectionBoxCovers;
 exports.toXY = toXY;
 
 //# sourceMappingURL=index.cjs.map