@classytic/labs 0.6.0 → 0.7.0

package/dist/kit/figure/grip.mjs

@@ -1,13 +1,16 @@
 'use client';
 
+import { GRIP_STRETCH, createTurnGesture, useGripBody } from "./grip-motion.mjs";
 import { useKeyScale } from "./key-scale.mjs";
+import { ROLE_SIZE, textWidth } from "./text-metrics.mjs";
 import { FigParagraph, FigText, wrapText } from "./text.mjs";
 import { HUE, STROKE } from "./figure.mjs";
 import { nextOnGrid, snapTo } from "../snap.mjs";
 import { pointBinding } from "../point-binding.mjs";
 import { useMarkDrawn } from "../../runtime/drawn-controls.mjs";
-import { createContext, use, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createContext, use, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { createPointerDrag, rubberband } from "@classytic/stage/gesture";
 
 //#region src/kit/figure/grip.tsx
 /**
@@ -15,12 +18,17 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 * cylinder's handwheel). The apparatus stays the picture; the grip only adds what a control needs:
 *
 *   - a touch target bigger than the drawn part (`hit`), so a thumb finds a small knob;
-*   - the hint every grip shares, on the part itself (styles/core.css): before first use it bobs twice
-*     and rests; on hover it lifts with a soft shadow; while dragged it lifts further. An xis adds
-*     faint chevrons for which way it moves. Nothing is drawn round the part: a ring round a trolley
-*     or a light gate read as a stray circle, not as \"you can move this\". Keyboard focus shows a thin
-*     ink ring, because focus must always be visible;
-*   - slider or button semantics, arrows and Home/End, Enter/Space, with a spoken value.
+*   - the hint every grip shares (styles/core/figure-interaction.css): an `axis` draws faint chevrons
+*     for which way the part moves, shown before first use and on hover. The part stays attached to
+*     its apparatus (no lift). Nothing is drawn round the part: a ring round a trolley or a light gate
+*     read as a stray circle, not as "you can move this". Keyboard focus shows a thin ink ring,
+*     because focus must always be visible;
+*   - direct manipulation that feels physical: the VALUE tracks the finger at once; only the drawn
+*     part's presentation offset springs (grip-motion.ts). A `turn` grip unwraps its angle move by
+*     move; a `follow` grip's part stays under the finger between stops and settles on release with
+*     the release speed; a continuous grip pulled past its range stretches a little, then springs back;
+*   - slider or button semantics, arrows and Home/End, Enter/Space, with a spoken value. A key shows
+*     the same press from Enter or Space as from a finger.
 *
 * Pointer positions arrive in the grip's OWN user space (its screen CTM inverted), so a part drawn
 * inside `translate(x y)` gets points in its own coordinates and maps them to a value itself. Place
@@ -33,8 +41,8 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 * (over the picture, so nothing shifts), and calls `onRefuse` so the host can bring the question
 * into view. A shake alone was too subtle: learners read it as "broken", not "not yet".
 *
-* Headless in spirit: nothing here draws the apparatus, and the drag logic is the part to promote
-* into `@classytic/stage/interaction` once labs moves to stage 0.7.
+* Headless in spirit: nothing here draws the apparatus. Stage's pure pointer lifecycle owns capture
+* and queued delivery; this adapter maps figure coordinates and carries model refusal feedback.
 */
 /** What a press does, and whether the key reads as pressed, for a bound press control. */
 function gripPress(control, onPress, option, cycle = false) {
@@ -150,10 +158,9 @@ function GripCue({ cx, cy, r, axis }) {
 		children: /* @__PURE__ */ jsx("path", { d: dirs.map((deg) => chevron(round2(cx + Math.cos(deg * Math.PI / 180) * d), round2(cy + Math.sin(deg * Math.PI / 180) * d), deg)).join(" ") })
 	});
 }
-function GripShape({ cx, cy, r, hit, note, noteY, axis, children }) {
+function GripShape({ cx, cy, r, hit, note, noteY, axis, body, children }) {
 	const above = cy - r - 30 > 8;
 	const by = noteY ?? (above ? cy - r - 18 : cy + r + 18);
-	const bw = note ? note.length * 7.2 + 24 : 0;
 	const { ref, scale } = useKeyScale();
 	const hitR = Math.max(hit ?? r * 1.6, 22 / Math.min(scale.x, scale.y));
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
@@ -173,6 +180,7 @@ function GripShape({ cx, cy, r, hit, note, noteY, axis, children }) {
 			r
 		}),
 		/* @__PURE__ */ jsx("g", {
+			ref: body?.ref,
 			className: "fig-grip-body",
 			children
 		}),
@@ -185,7 +193,6 @@ function GripShape({ cx, cy, r, hit, note, noteY, axis, children }) {
 		note ? /* @__PURE__ */ jsx(NoteBubble, {
 			cx,
 			y: by,
-			width: bw,
 			note
 		}) : null
 	] });
@@ -195,68 +202,123 @@ function GripShape({ cx, cy, r, hit, note, noteY, axis, children }) {
 * and the grip cannot tell from its own coordinates (a part may draw it inside a translate), so the
 * bubble measures itself against the figure's viewBox after layout and slides back inside.
 */
-function NoteBubble({ cx, y, width, note }) {
-	const ref = useRef(null);
-	const [shift, setShift] = useState(0);
+const NOTE_HEIGHT_PX = 26;
+const NOTE_GAP_PX = 9;
+const NOTE_MARGIN_PX = 8;
+function NoteBubble({ cx, y, note }) {
+	const { ref, scale } = useKeyScale();
+	const fontSize = ROLE_SIZE.note / scale.y;
+	const width = textWidth(note, {
+		role: "note",
+		size: fontSize,
+		caps: false
+	}) + 24 / scale.x;
+	const height = NOTE_HEIGHT_PX / scale.y;
+	const [shift, setShift] = useState({
+		x: 0,
+		y: 0
+	});
 	useLayoutEffect(() => {
 		const g = ref.current;
 		const svg = g?.ownerSVGElement;
-		const local = g?.getScreenCTM();
-		const root = svg?.getScreenCTM();
+		const local = g?.getScreenCTM?.();
+		const root = svg?.getScreenCTM?.();
 		if (!g || !svg || !local || !root) return;
 		const toRoot = root.inverse().multiply(local);
 		const box = svg.viewBox.baseVal;
-		const left = new DOMPoint(cx - width / 2, y).matrixTransform(toRoot).x;
-		const right = new DOMPoint(cx + width / 2, y).matrixTransform(toRoot).x;
-		const scale = (right - left) / width || 1;
-		const margin = 8;
-		const over = left < box.x + margin ? box.x + margin - left : right > box.x + box.width - margin ? box.x + box.width - margin - right : 0;
-		setShift(over / scale);
-	}, [
-		cx,
-		y,
-		width
-	]);
-	return /* @__PURE__ */ jsxs("g", {
+		const corners = [
+			[cx - width / 2, y - height / 2],
+			[cx + width / 2, y - height / 2],
+			[cx - width / 2, y + height / 2],
+			[cx + width / 2, y + height / 2]
+		].map(([x, y]) => new DOMPoint(x, y).matrixTransform(toRoot));
+		const left = Math.min(...corners.map((p) => p.x));
+		const right = Math.max(...corners.map((p) => p.x));
+		const top = Math.min(...corners.map((p) => p.y));
+		const bottom = Math.max(...corners.map((p) => p.y));
+		const marginX = NOTE_MARGIN_PX / Math.hypot(root.a, root.b);
+		const marginY = NOTE_MARGIN_PX / Math.hypot(root.c, root.d);
+		const dx = left < box.x + marginX ? box.x + marginX - left : right > box.x + box.width - marginX ? box.x + box.width - marginX - right : 0;
+		const dy = top < box.y + marginY ? box.y + marginY - top : bottom > box.y + box.height - marginY ? box.y + box.height - marginY - bottom : 0;
+		const inverse = toRoot.inverse();
+		const x = inverse.a * dx + inverse.c * dy;
+		const yShift = inverse.b * dx + inverse.d * dy;
+		if (!Number.isFinite(x) || !Number.isFinite(yShift)) return;
+		setShift((previous) => Math.abs(previous.x - x) < .001 && Math.abs(previous.y - yShift) < .001 ? previous : {
+			x,
+			y: yShift
+		});
+	});
+	return /* @__PURE__ */ jsx("g", {
 		ref,
 		className: "fig-grip-note",
 		role: "status",
 		pointerEvents: "none",
-		transform: shift ? `translate(${shift} 0)` : undefined,
-		children: [/* @__PURE__ */ jsx("rect", {
-			x: cx - width / 2,
-			y: y - 13,
-			width,
-			height: 26,
-			rx: 13,
-			fill: "var(--fig-ink)"
-		}), /* @__PURE__ */ jsx(FigText, {
-			x: cx,
-			y: y + 1,
-			size: "note",
-			tone: "inverse",
-			anchor: "middle",
-			baseline: "middle",
-			caps: false,
-			children: note
-		})]
+		children: /* @__PURE__ */ jsxs("g", {
+			transform: shift.x || shift.y ? `translate(${shift.x} ${shift.y})` : undefined,
+			children: [/* @__PURE__ */ jsx("rect", {
+				x: cx - width / 2,
+				y: y - height / 2,
+				width,
+				height,
+				rx: NOTE_HEIGHT_PX / 2 / scale.x,
+				ry: NOTE_HEIGHT_PX / 2 / scale.y,
+				fill: "var(--fig-ink)"
+			}), /* @__PURE__ */ jsx(FigText, {
+				x: cx,
+				y: y + 1 / scale.y,
+				size: "note",
+				fontSize,
+				tone: "inverse",
+				anchor: "middle",
+				baseline: "middle",
+				caps: false,
+				children: note
+			})]
+		})
 	});
 }
 /**
-* The pointer half every draggable grip shares: capture, points in the grip's own user space, and at
-* most one report per frame. `origin` is the value a drag starts from (a 2D grip passes 0 and reads
-* the start point instead).
+* The pointer half every draggable grip shares: one `createPointerDrag` lifecycle (capture, lost
+* capture, cancel, at most one report per frame, release velocity), points in the grip's own user
+* space. `origin` is the value a drag starts from (a 2D grip passes 0 and reads the start point).
 */
-function useGripPointer(onPoint, origin, grip, onRelease) {
+function useGripPointer(onPoint, origin, grip, onRelease, hidden = false, gesture = {}) {
 	const [dragging, setDragging] = useState(false);
-	const pending = useRef(null);
 	const drag = useRef(null);
-	const frame = useRef(0);
 	const onPointRef = useRef(onPoint);
-	useEffect(() => {
+	const onReleaseRef = useRef(onRelease);
+	const gestureRef = useRef(gesture);
+	const finishing = useRef(false);
+	const locked = grip.locked || hidden;
+	const lockedRef = useRef(locked);
+	useLayoutEffect(() => {
 		onPointRef.current = onPoint;
+		onReleaseRef.current = onRelease;
+		gestureRef.current = gesture;
+		lockedRef.current = locked;
 	});
-	useEffect(() => () => cancelAnimationFrame(frame.current), []);
+	const [pointer] = useState(() => createPointerDrag({
+		schedule: (callback) => requestAnimationFrame(callback),
+		cancelFrame: (frame) => cancelAnimationFrame(frame),
+		move: (point) => {
+			if (lockedRef.current || !drag.current) return;
+			onPointRef.current(point, drag.current);
+			drag.current = {
+				...drag.current,
+				last: point
+			};
+		},
+		end: () => {
+			setDragging(false);
+			if (!finishing.current) gestureRef.current.cancel?.();
+		},
+		position: (point) => point
+	}));
+	useLayoutEffect(() => {
+		if (locked) pointer.cancel();
+	}, [locked, pointer]);
+	useEffect(() => () => pointer.dispose(), [pointer]);
 	const toLocal = (event) => {
 		const matrix = event.currentTarget.getScreenCTM();
 		if (!matrix) return null;
@@ -266,64 +328,66 @@ function useGripPointer(onPoint, origin, grip, onRelease) {
 			y: p.y
 		};
 	};
-	const queue = (point) => {
-		if (!point) return;
-		pending.current = point;
-		if (frame.current) return;
-		frame.current = requestAnimationFrame(() => {
-			frame.current = 0;
-			const point = pending.current;
-			pending.current = null;
-			if (!point || !drag.current) return;
-			onPointRef.current(point, drag.current);
-			drag.current = {
-				...drag.current,
-				last: point
-			};
-		});
-	};
-	const onReleaseRef = useRef(onRelease);
-	useEffect(() => {
-		onReleaseRef.current = onRelease;
-	});
-	const end = () => {
-		if (!dragging) return;
-		cancelAnimationFrame(frame.current);
-		frame.current = 0;
-		const point = pending.current;
-		pending.current = null;
-		if (point && drag.current) onPointRef.current(point, drag.current);
-		setDragging(false);
-		onReleaseRef.current?.();
-	};
+	const cancel = (event) => pointer.cancel(event.pointerId);
 	return {
 		dragging,
 		handlers: {
 			onPointerDown: (event) => {
 				event.stopPropagation();
-				if (grip.locked) return grip.refuse();
-				event.currentTarget.setPointerCapture(event.pointerId);
-				grip.markUsed();
+				if (locked) return grip.refuse();
+				if (event.button != null && event.button !== 0) return;
 				const start = toLocal(event);
-				if (!start) return;
+				if (!start || !pointer.start(event.currentTarget, event.pointerId, start, event.timeStamp)) return;
+				grip.markUsed();
 				drag.current = {
 					start,
 					value: origin,
 					last: start
 				};
+				gestureRef.current.start?.(start);
 				setDragging(true);
 			},
 			onPointerMove: (event) => {
-				if (dragging) queue(toLocal(event));
+				if (!pointer.owns(event.pointerId) || lockedRef.current) return;
+				const point = toLocal(event);
+				if (point) pointer.queue(event.pointerId, point, event.timeStamp);
 			},
-			onPointerUp: end,
-			onPointerCancel: end
+			onPointerUp: (event) => {
+				if (lockedRef.current) return;
+				finishing.current = true;
+				let done = false;
+				try {
+					done = pointer.finish(event.pointerId);
+				} finally {
+					finishing.current = false;
+				}
+				if (!done) return;
+				const { velocity } = pointer.release();
+				const last = drag.current?.last;
+				if (last) gestureRef.current.release?.({
+					point: last,
+					velocity: {
+						x: velocity.x,
+						y: velocity.y
+					}
+				});
+				onReleaseRef.current?.();
+			},
+			onPointerCancel: cancel,
+			onLostPointerCapture: cancel
 		}
 	};
 }
 /** A grip the learner drags (a plunger, a knob). v1: pass `control` and `toValue`. */
 function GripSlider(props) {
 	const { cx, cy, r, hit, hint = "breathe", axis, onRelease, children } = props;
+	const framePosition = useRef(null);
+	useImperativeHandle(props.frameRef, () => ({ update: (x, y) => {
+		framePosition.current?.setAttribute("transform", `translate(${round2(x - cx)} ${round2(y - cy)})`);
+	} }), [cx, cy]);
+	useLayoutEffect(() => {
+		framePosition.current?.removeAttribute("transform");
+	}, [cx, cy]);
 	const source = props.control;
 	const vertical = axis === "y";
 	const focused = source?.kind === "number" && props.focus ? pointBinding(source, vertical, {}, !vertical, {
@@ -364,9 +428,112 @@ function GripSlider(props) {
 		const option = choice.options[Math.round(clamp(v, 0, max))];
 		if (option) choice.set(option.value);
 	} : number ? (v) => number.set(v) : props.onValue;
-	const onPoint = c ? (p, d) => onValue(props.toValue(p, d)) : props.onPoint;
 	const grip = useGripUse(c);
-	const { dragging, handlers } = useGripPointer(onPoint, value, grip, onRelease);
+	const turn = props.turn;
+	const follow = Boolean(props.follow);
+	const toValue = props.toValue;
+	const body = useGripBody();
+	const turning = useRef(null);
+	/** The last pointer point whose value was in range: a stretch past a limit is measured from it. */
+	const edge = useRef(null);
+	/** A follow drag: where it started, the value's base point then, and the latest pointer point. */
+	const held = useRef(null);
+	const base = useRef({
+		x: cx,
+		y: cy
+	});
+	const pendingSettle = useRef(null);
+	const followOffset = (h) => ({
+		x: axis === "y" ? 0 : h.last.x - h.start.x - (base.current.x - h.base.x),
+		y: axis === "x" ? 0 : h.last.y - h.start.y - (base.current.y - h.base.y)
+	});
+	const onPoint = (p, d) => {
+		if (turn) {
+			const gesture = turning.current;
+			if (!gesture) return;
+			const next = gesture.move(p);
+			body.set({
+				turn: next.stretch,
+				ox: turn.cx,
+				oy: turn.cy
+			});
+			onValue(c ? next.value : clamp(snapTo(next.value, step, min), min, max));
+			return;
+		}
+		if (held.current) {
+			held.current.last = p;
+			body.set(followOffset(held.current));
+		}
+		if (!c) {
+			if (!props.onPoint) throw new TypeError("GripSlider needs `turn` or `onPoint`");
+			return props.onPoint(p, d);
+		}
+		if (!toValue) throw new TypeError("A bound GripSlider needs `turn` or `toValue`");
+		const raw = toValue(p, d);
+		if (!follow && Number.isFinite(raw)) {
+			if (raw >= min && raw <= max) {
+				edge.current = p;
+				if (body.offset.x || body.offset.y) body.set({
+					x: 0,
+					y: 0
+				});
+			} else if (edge.current) {
+				body.set({
+					x: axis === "y" ? 0 : rubberband(p.x - edge.current.x, GRIP_STRETCH.travel),
+					y: axis === "x" ? 0 : rubberband(p.y - edge.current.y, GRIP_STRETCH.travel)
+				});
+			}
+		}
+		onValue(raw);
+	};
+	const { dragging, handlers } = useGripPointer(onPoint, value, grip, onRelease, Boolean(c?.hidden || choice && choice.options.length === 0), {
+		start: (p) => {
+			edge.current = p;
+			held.current = follow ? {
+				start: p,
+				base: { ...base.current },
+				last: p
+			} : null;
+			if (turn) {
+				turning.current = createTurnGesture(turn, min, max);
+				turning.current.start(p, value);
+			}
+		},
+		release: (release) => {
+			props.onDragEnd?.(release);
+			held.current = null;
+			turning.current = null;
+			pendingSettle.current = follow ? {
+				x: axis === "y" ? 0 : release.velocity.x,
+				y: axis === "x" ? 0 : release.velocity.y
+			} : {
+				x: 0,
+				y: 0
+			};
+		},
+		cancel: () => {
+			held.current = null;
+			turning.current = null;
+			body.release();
+		}
+	});
+	useLayoutEffect(() => {
+		const dx = cx - base.current.x;
+		const dy = cy - base.current.y;
+		base.current = {
+			x: cx,
+			y: cy
+		};
+		if (follow && (dx || dy)) {
+			if (held.current) body.set(followOffset(held.current));
+			else if (pendingSettle.current || body.moving) body.shift(dx, dy);
+		}
+		const settle = pendingSettle.current;
+		if (settle) {
+			pendingSettle.current = null;
+			body.release(settle);
+		}
+	});
 	if (c?.hidden || choice && choice.options.length === 0) return null;
 	const keyDown = (event) => {
 		if (onRelease && (event.key === "Enter" || event.key === " ")) {
@@ -412,15 +579,19 @@ function GripSlider(props) {
 		"data-dragging": dragging || undefined,
 		...handlers,
 		onKeyDown: keyDown,
-		children: /* @__PURE__ */ jsx(GripShape, {
-			cx,
-			cy,
-			r,
-			hit,
-			note: grip.note,
-			noteY: props.noteY,
-			axis,
-			children
+		children: /* @__PURE__ */ jsx("g", {
+			ref: framePosition,
+			children: /* @__PURE__ */ jsx(GripShape, {
+				cx,
+				cy,
+				r,
+				hit,
+				note: grip.note,
+				noteY: props.noteY,
+				axis,
+				body,
+				children
+			})
 		})
 	});
 }
@@ -491,37 +662,45 @@ function GripPad(props) {
 		setAxis("y", p.y);
 	} : c ? (p) => c.set(p) : props.onValue;
 	const onPoint = c || pair ? (p, d) => onValue(props.toPoint(p, d)) : props.onPoint;
-	const { dragging, handlers } = useGripPointer(onPoint, 0, grip);
+	const { dragging, handlers } = useGripPointer(onPoint, 0, grip, undefined, Boolean(c?.hidden || pair?.x.hidden || pair?.y.hidden));
 	if (c?.hidden || pair?.x.hidden || pair?.y.hidden) return null;
-	const keyDown = (event) => {
-		const move = {
-			ArrowRight: [step.x, 0],
-			ArrowLeft: [-step.x, 0],
-			ArrowUp: [0, step.y],
-			ArrowDown: [0, -step.y]
-		};
-		const delta = move[event.key];
-		if (!delta) return;
+	const nudgeAxis = (key, event) => {
+		const negative = [
+			"ArrowLeft",
+			"ArrowDown",
+			"PageDown"
+		].includes(event.key);
+		const supported = [
+			"ArrowLeft",
+			"ArrowRight",
+			"ArrowUp",
+			"ArrowDown",
+			"PageUp",
+			"PageDown",
+			"Home",
+			"End"
+		];
+		if (!supported.includes(event.key)) return;
 		event.preventDefault();
-		if (pair) {
-			const key = event.key === "ArrowLeft" || event.key === "ArrowRight" ? "x" : "y";
-			setAxis(key, value[key] + delta[key === "x" ? 0 : 1], true);
-			return;
-		}
+		event.stopPropagation();
+		const stride = step[key] * (event.key.startsWith("Page") || event.shiftKey ? 5 : event.altKey ? .25 : 1);
+		const next = event.key === "Home" ? bounds.min[key] : event.key === "End" ? bounds.max[key] : value[key] + (negative ? -stride : stride);
+		if (pair) return setAxis(key, next, true);
 		if (grip.locked) return grip.refuse();
 		grip.markUsed();
 		onValue({
-			x: clamp(value.x + delta[0], bounds.min.x, bounds.max.x),
-			y: clamp(value.y + delta[1], bounds.min.y, bounds.max.y)
+			...value,
+			[key]: clamp(next, bounds.min[key], bounds.max[key])
 		});
 	};
-	return /* @__PURE__ */ jsx("g", {
+	const keyDown = (event) => {
+		if (!event.key.startsWith("Arrow")) return;
+		nudgeAxis(event.key === "ArrowLeft" || event.key === "ArrowRight" ? "x" : "y", event);
+	};
+	return /* @__PURE__ */ jsxs("g", {
 		className: "fig-grip",
-		role: "slider",
-		"aria-roledescription": "position",
-		tabIndex: 0,
+		role: "group",
 		"aria-label": label,
-		"aria-valuetext": valueText,
 		...grip.attrs,
 		"data-used": grip.attrs["data-used"] || pair && (xGrip.attrs["data-used"] || yGrip.attrs["data-used"]) || undefined,
 		"data-refused": grip.attrs["data-refused"] || pair && (xGrip.attrs["data-refused"] || yGrip.attrs["data-refused"]) || undefined,
@@ -530,7 +709,31 @@ function GripPad(props) {
 		"data-dragging": dragging || undefined,
 		...handlers,
 		onKeyDown: keyDown,
-		children: /* @__PURE__ */ jsx(GripShape, {
+		children: [["x", "y"].map((key) => {
+			const axisControl = pair?.[key];
+			const axisLabel = axisControl?.label ?? `${label}: ${key}`;
+			const axisLocked = pair ? key === "x" ? xGrip.locked : yGrip.locked : grip.locked;
+			return /* @__PURE__ */ jsx("g", {
+				className: "fig-grip-axis",
+				role: "slider",
+				tabIndex: 0,
+				"aria-label": axisLabel,
+				"aria-orientation": key === "x" ? "horizontal" : "vertical",
+				"aria-valuenow": value[key],
+				"aria-valuemin": bounds.min[key],
+				"aria-valuemax": bounds.max[key],
+				"aria-valuetext": axisControl?.valueText ?? `${key} ${value[key]}; ${valueText}`,
+				"aria-disabled": axisLocked || undefined,
+				onKeyDown: (event) => nudgeAxis(key, event),
+				pointerEvents: "none",
+				children: /* @__PURE__ */ jsx("circle", {
+					className: "fig-grip-ring",
+					cx,
+					cy,
+					r: r + (key === "y" ? 3 : 0)
+				})
+			}, key);
+		}), /* @__PURE__ */ jsx(GripShape, {
 			cx,
 			cy,
 			r,
@@ -539,7 +742,7 @@ function GripPad(props) {
 			noteY: props.noteY,
 			axis,
 			children
-		})
+		})]
 	});
 }
 /** A grip the learner presses (a valve that lets a puff of gas in). */
@@ -605,7 +808,13 @@ function GripDot({ cx, cy, r = 7, color = HUE.warn }) {
 	});
 }
 /** A key's width for its text: what `GripKeyRow` gives each key, for a single key sized the same way. */
-const keyWidth = (text) => Math.max(64, Math.round(text.length * 7.2 + 28));
+const keyWidth = (text) => Math.max(64, Math.round(keyTextWidth(text) + 28));
+/** A key face's text as drawn: the label role, semibold, as written. */
+const keyTextWidth = (text) => textWidth(text, {
+	role: "label",
+	weight: "semibold",
+	caps: false
+});
 /**
 * In-picture keys in a row, each sized to its text, so a lab never lays key positions out by hand.
 * `align` says what `x` is: the row's left end (the run key sits top left in every scene), its
@@ -672,6 +881,7 @@ function GripKey({ x, y, w, h = 26, compact = false, emphasis = "secondary", tex
 	const action = gripPress(control, onPress, option, cycle);
 	const label = spoken ?? control?.label;
 	const pressed = control?.kind === "toggle" || control?.kind === "choice" ? action.pressed : shown ?? action.pressed;
+	const [keyHeld, setKeyHeld] = useState(false);
 	if (control?.hidden) return null;
 	const press = () => {
 		if (grip.locked) return grip.refuse();
@@ -688,7 +898,7 @@ function GripKey({ x, y, w, h = 26, compact = false, emphasis = "secondary", tex
 	const focusY = compact ? 3 / scale.y : 3;
 	const left = x - faceW / 2;
 	const top = y - faceH / 2;
-	const lines = wrap && typeof text === "string" ? wrapText(text, faceW - 12, 6.6) : undefined;
+	const lines = wrap && typeof text === "string" ? wrapText(text, faceW - 12, 6.6, { measureWidth: keyTextWidth }) : undefined;
 	return /* @__PURE__ */ jsxs("g", {
 		ref,
 		className: "fig-key",
@@ -702,12 +912,18 @@ function GripKey({ x, y, w, h = 26, compact = false, emphasis = "secondary", tex
 		"aria-pressed": pressed,
 		"aria-description": control?.kind === "choice" && cycle ? control.valueText : undefined,
 		...grip.attrs,
+		"data-pressing": keyHeld && !grip.locked || undefined,
 		onClick: press,
 		onKeyDown: (event) => {
 			if (event.key !== "Enter" && event.key !== " ") return;
 			event.preventDefault();
+			setKeyHeld(true);
 			press();
 		},
+		onKeyUp: (event) => {
+			if (event.key === "Enter" || event.key === " ") setKeyHeld(false);
+		},
+		onBlur: () => setKeyHeld(false),
 		children: [
 			/* @__PURE__ */ jsx("rect", {
 				"data-part": "key-hit",
@@ -735,6 +951,7 @@ function GripKey({ x, y, w, h = 26, compact = false, emphasis = "secondary", tex
 			}),
 			/* @__PURE__ */ jsxs("g", {
 				className: "fig-key-face",
+				style: keyHeld && !grip.locked ? { transform: `translateY(${depth}px)` } : undefined,
 				children: [/* @__PURE__ */ jsx("rect", {
 					className: "fig-key-cap",
 					x: left,
@@ -767,8 +984,7 @@ function GripKey({ x, y, w, h = 26, compact = false, emphasis = "secondary", tex
 			}),
 			grip.note ? /* @__PURE__ */ jsx(NoteBubble, {
 				cx: x,
-				y: top > 40 ? top - 22 : top + h + 26,
-				width: grip.note.length * 7.2 + 24,
+				y: top * scale.y > NOTE_HEIGHT_PX + NOTE_GAP_PX + NOTE_MARGIN_PX ? top - (NOTE_HEIGHT_PX / 2 + NOTE_GAP_PX) / scale.y : top + faceH + depth + (NOTE_HEIGHT_PX / 2 + NOTE_GAP_PX) / scale.y,
 				note: grip.note
 			}) : null
 		]