@classytic/labs 0.6.0 → 0.7.0

package/dist/kit/scene/graph.mjs

@@ -1,15 +1,17 @@
 'use client';
 
+import { textWidth } from "../figure/text-metrics.mjs";
 import { FigText, wrapText } from "../figure/text.mjs";
+import { SCENE } from "./tokens.mjs";
 import { HUE, STROKE, alpha } from "../figure/figure.mjs";
 import { snapTo } from "../snap.mjs";
 import { GripDot, GripSlider } from "../figure/grip.mjs";
+import { Leader } from "../figure/reading.mjs";
+import { DASH } from "../figure/lines.mjs";
 import { Cluster } from "../layout.mjs";
-import { SCENE } from "./tokens.mjs";
-import "../figure/index.mjs";
 import { useId } from "react";
-import { niceStep } from "@classytic/stage";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { niceStep } from "@classytic/stage/primitives";
 
 //#region src/kit/scene/graph.tsx
 /**
@@ -30,6 +32,18 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 * Everything is drawn in picture units from the one `SceneGraph`, so a lane can never drift off
 * its axis and a tick label always names a value the graph reaches.
 */
+/** Graph captions, readouts and guess names are label-role text as written. */
+const captionWidth = (text) => textWidth(text, {
+	role: "label",
+	caps: false
+});
+/** The same proportional line layout for axis captions and their reserved figure space. */
+function graphAxisLabelLines(label, width) {
+	return width ? wrapText(label, width, undefined, {
+		breakLongWords: true,
+		measureWidth: captionWidth
+	}) : [label];
+}
 const r2 = (n) => Math.round(n * 100) / 100;
 /** Round the top of a range up to a whole tick, so the last gridline is the edge of the plot. */
 function niceMax(value, target = 5) {
@@ -187,7 +201,7 @@ function GraphPanel({ graph, xLabel, yLabel, xLabelOffset = 28, xTickOffset = 15
 			drawAxis: axes === "boundary",
 			tickLabel: yTickLabel
 		}) : null,
-		(xLabelWidth ? wrapText(xLabel, xLabelWidth, 13.5, { breakLongWords: true }) : [xLabel]).map((line, i) => /* @__PURE__ */ jsx(FigText, {
+		graphAxisLabelLines(xLabel, xLabelWidth).map((line, i) => /* @__PURE__ */ jsx(FigText, {
 			x: right + 12,
 			y: bottom + xLabelOffset + i * 18,
 			anchor: "end",
@@ -243,7 +257,7 @@ function GraphFrequencyAxis({ graph, categorical = true, label, labelOffset = 18
 				stroke: HUE.ink,
 				strokeWidth: STROKE.line
 			}) : null,
-			label ? (labelWidth ? wrapText(label, labelWidth, 13.5, { breakLongWords: true }) : [label]).map((line, i) => /* @__PURE__ */ jsx(FigText, {
+			label ? graphAxisLabelLines(label, labelWidth).map((line, i) => /* @__PURE__ */ jsx(FigText, {
 				x: left,
 				y: top - labelOffset + i * 18,
 				anchor: labelAnchor,
@@ -356,6 +370,67 @@ function GraphEvent({ graph, x, y, to, tone = "good" }) {
 		strokeWidth: STROKE.line
 	})] });
 }
+/** A passive reading attached to a plotted observation. Values are supplied by the model;
+* only the label reflows to stay inside the plot. Render after GraphPanel so it is not clipped. */
+function GraphReadout({ graph, x, y, text }) {
+	const px = graph.X(x), py = graph.Y(y), { box } = graph;
+	if (!text.trim() || !Number.isFinite(px) || !Number.isFinite(py) || px < box.x || px > box.x + box.w || py < box.y || py > box.y + box.h) return null;
+	const lines = wrapText(text, box.w - 24, 8, {
+		measureWidth: captionWidth,
+		breakLongWords: true
+	});
+	const width = Math.min(box.w - 8, Math.max(...lines.map(captionWidth)) + 16);
+	const height = lines.length * 17 + 12;
+	const preferredLeft = px + width + 20 <= box.x + box.w ? px + 16 : px - width - 16;
+	const preferredTop = py - height - 16 >= box.y + 4 ? py - height - 16 : py + 16;
+	const left = Math.max(box.x + 4, Math.min(preferredLeft, box.x + box.w - width - 4));
+	const top = Math.max(box.y + 4, Math.min(preferredTop, box.y + box.h - height - 4));
+	return /* @__PURE__ */ jsxs("g", {
+		"data-part": "graph-readout",
+		pointerEvents: "none",
+		children: [
+			/* @__PURE__ */ jsx(Leader, {
+				from: {
+					x: px,
+					y: py
+				},
+				to: {
+					x: Math.max(left, Math.min(px, left + width)),
+					y: top + height
+				},
+				dash: DASH.dot
+			}),
+			/* @__PURE__ */ jsx("rect", {
+				"data-part": "graph-readout-label",
+				x: r2(left),
+				y: r2(top),
+				width: r2(width),
+				height,
+				rx: 5,
+				fill: SCENE.label.paper,
+				stroke: alpha(HUE.ink, 20),
+				strokeWidth: STROKE.hair
+			}),
+			lines.map((line, i) => /* @__PURE__ */ jsx(FigText, {
+				x: r2(left + 8),
+				y: r2(top + 18 + i * 17),
+				size: "label",
+				color: SCENE.label.ink,
+				caps: false,
+				children: line
+			}, i)),
+			/* @__PURE__ */ jsx("circle", {
+				"data-part": "graph-readout-point",
+				cx: r2(px),
+				cy: r2(py),
+				r: 4,
+				fill: HUE[1],
+				stroke: HUE.paper,
+				strokeWidth: STROKE.hair
+			})
+		]
+	});
+}
 /** A reading in the plot's quiet top-left corner (where a rising line never is). */
 function GraphNote({ graph, line = 0, tone, corner = "top-left", children }) {
 	const y = corner === "top-left" ? graph.box.y + 13 + line * 15 : graph.box.y + graph.box.h - 6 - line * 15;
@@ -443,9 +518,10 @@ function GraphLanes({ graph, lanes, width = 28, pad }) {
 	}) });
 }
 /** A guess dragged along one axis: a dashed line across the graph and a grip on it. */
-function GuessMarker({ graph, guess }) {
+function GuessMarker({ graph, guess, control }) {
 	const onX = guess.axis === "x";
-	const [cx, cy] = onX ? [graph.X(guess.value), graph.Y(guess.at)] : [graph.X(guess.at), graph.Y(guess.value)];
+	const value = control?.value ?? guess.value;
+	const [cx, cy] = onX ? [graph.X(value), graph.Y(guess.at)] : [graph.X(guess.at), graph.Y(value)];
 	const line = onX ? /* @__PURE__ */ jsx("line", {
 		x1: cx,
 		y1: graph.box.y,
@@ -468,15 +544,28 @@ function GuessMarker({ graph, guess }) {
 		children: [
 			line,
 			/* @__PURE__ */ jsx(FigText, {
-				x: onX && cx + 10 + guess.label.length * 6 > graph.box.x + graph.box.w ? cx - 10 : cx + 10,
+				x: onX && cx + 10 + captionWidth(guess.label) > graph.box.x + graph.box.w ? cx - 10 : cx + 10,
 				y: cy - 12,
-				anchor: onX && cx + 10 + guess.label.length * 6 > graph.box.x + graph.box.w ? "end" : "start",
+				anchor: onX && cx + 10 + captionWidth(guess.label) > graph.box.x + graph.box.w ? "end" : "start",
 				size: "label",
 				tone: "warn",
+				halo: true,
 				caps: false,
 				children: guess.label
 			}),
-			guess.onValue ? /* @__PURE__ */ jsx(GripSlider, {
+			control && !control.hidden ? /* @__PURE__ */ jsx(GripSlider, {
+				cx,
+				cy,
+				r: 12,
+				axis: guess.axis,
+				control,
+				toValue: (point) => onX ? graph.xAt(point.x) : graph.yAt(point.y),
+				children: /* @__PURE__ */ jsx(GripDot, {
+					cx,
+					cy,
+					r: 7
+				})
+			}) : !control && guess.onValue ? /* @__PURE__ */ jsx(GripSlider, {
 				cx,
 				cy,
 				r: 12,
@@ -508,4 +597,4 @@ function GuessMarker({ graph, guess }) {
 }
 
 //#endregion
-export { GraphBarMark, GraphEvent, GraphFrequencyAxis, GraphLanes, GraphLegend, GraphNote, GraphPanel, GraphSpan, GraphTie, GuessMarker, niceMax, sceneGraph };
+export { GraphBarMark, GraphEvent, GraphFrequencyAxis, GraphLanes, GraphLegend, GraphNote, GraphPanel, GraphReadout, GraphSpan, GraphTie, GuessMarker, graphAxisLabelLines, niceMax, sceneGraph };

package/dist/kit/scene/index.mjs

@@ -1,16 +1,25 @@
+import { ACCENT, HATCH, MOTION, SCENE, SCI, rampOf } from "./tokens.mjs";
+import { Bench, LabelChip } from "./workbench.mjs";
 import { STORY_FRAME, useScene, useSceneTime } from "./context.mjs";
+import { ELEVATION, Emitter, FINISHES, Glint, Grounding, LIGHT } from "./materials.mjs";
+import { KnobCap, ScaleArc, TICK, scalePoint } from "./objects/knob.mjs";
+import { Knob, PLASTIC, STEEL, Solid, Sphere } from "./objects/block.mjs";
+import { AirTrack, BenchPulley, ForceMeter, Launcher, LightGate, MetreRule, Slope, SlottedMass, Spring, Trolley, forceMeterHook, launcherMuzzle, slopePoint, trackTop } from "./objects/mechanics.mjs";
 import { Scene, SceneCanvas } from "./scene.mjs";
-import { ACCENT, MOTION, SCENE } from "./tokens.mjs";
-import { Bench, LabelChip } from "./workbench.mjs";
-import { ContactShadow, Display, Knob, PLASTIC, STEEL, Solid, Sphere, Tag } from "./objects/block.mjs";
-import { Ground, Post, Rail, Shadow, Sky } from "./scenery.mjs";
+import { Loupe, loupeMap, loupeTangents } from "./loupe.mjs";
+import { Cutaway, SectionHatch, cutRegion } from "./cutaway.mjs";
+import { EXPLODE_FEEL, EXPLODE_LABEL_FADE, Explode, ExplodePart, explodeLabelReveal, explodeOffset } from "./explode.mjs";
+import { LIQUID } from "./objects/liquid.mjs";
+import { BrickStack, CentreOfMass, Chain, DimensionLine, Reservoir } from "./objects/energy.mjs";
+import { Compare, changedMarks, compareLayout, compareLegendRows, compareScale } from "./compare.mjs";
+import { Ground, Post, Rail, Sky } from "./scenery.mjs";
 import { Detector, Lever, leverFraction, leverTip } from "./objects/instruments.mjs";
-import { Micrometer, MicrometerScales, ReadingCallout, VernierCaliper, VernierScales, micrometerGeometry, vernierGeometry } from "./objects/gauges.mjs";
+import { Micrometer, MicrometerScales, VernierCaliper, VernierScales, micrometerGeometry, vernierGeometry } from "./objects/gauges.mjs";
 import { useLightAge } from "./behavior.mjs";
 import { Train } from "./objects/train.mjs";
 import { Car } from "./objects/car.mjs";
 import { TOP_VEHICLE_SIZE, TopVehicle } from "./objects/top-vehicle.mjs";
-import { GraphEvent, GraphLanes, GraphLegend, GraphNote, GraphPanel, GraphSpan, GraphTie, GuessMarker, niceMax, sceneGraph } from "./graph.mjs";
+import { GraphEvent, GraphLanes, GraphLegend, GraphNote, GraphPanel, GraphReadout, GraphSpan, GraphTie, GuessMarker, niceMax, sceneGraph } from "./graph.mjs";
 import { TopRiver, riverFlowTransform } from "./river.mjs";
 import { ReachCircle, VectorArrow, VectorPanel, vectorFrame } from "./vectors.mjs";
 import { Passenger, Person, personHand } from "./objects/person.mjs";
@@ -19,8 +28,6 @@ import { Roller, setRollerTurn } from "./objects/roller.mjs";
 import { Parachute } from "./objects/parachute.mjs";
 import { FORCE, ForceArrow } from "./objects/forces.mjs";
 import { Damper, FrictionMeter, Thread, Wheel } from "./objects/mechanisms.mjs";
-import { LIQUID } from "./objects/liquid.mjs";
-import { BrickStack, CentreOfMass, Chain, DimensionLine, Reservoir } from "./objects/energy.mjs";
 import { Dial, dialAngle, dialPoint, dialValueAt } from "./objects/dial.mjs";
 import { BathroomScale, Lift, liftFloor, scaleTop } from "./objects/lift.mjs";
 import { Clock } from "./objects/clock.mjs";
@@ -29,7 +36,6 @@ import { LightClock, lightClockFaces } from "./objects/light-clock.mjs";
 import { Balance } from "./objects/balance.mjs";
 import { Lamp, PowerSupply, VacuumTube, XraySource, lensAt, tubeElectrodes, xrayExitX } from "./objects/bench.mjs";
 import { Strike } from "./objects/strike.mjs";
-import { AirTrack, BenchPulley, ForceMeter, Launcher, LightGate, MetreRule, Slope, SlottedMass, Spring, Trolley, forceMeterHook, launcherMuzzle, slopePoint, trackTop } from "./objects/mechanics.mjs";
 import { HangingRule, Pendulum, Stopwatch, bobCentre } from "./objects/pendulum.mjs";
 import { RetortStand, standPivot } from "./objects/stand.mjs";
 import { Electromagnet, Eye, HeatWisps } from "./objects/observer.mjs";
@@ -47,4 +53,4 @@ import { IlluminatedObject, LensHolder, OpticalCarriage, OpticalRail, Projection
 import { LaserEmitterGlyph, OpticalReceiver, PlaneMirror } from "./objects/optical-signal.mjs";
 import { Cannon, CoconutPalm } from "./objects/projectiles.mjs";
 
-export { ACCENT, AirTrack, Balance, Barrier, BathroomScale, Bench, BenchPulley, BrickStack, CHARGE_TONE, Cannon, Car, Chain, Clock, CoconutPalm, ContactShadow, Crest, Detector, Dial, DimensionLine, Display, Electromagnet, Equipotential, Eye, FORCE, Fan, FieldRays, ForceArrow, FrictionMeter, GraphEvent, GraphLanes, GraphNote, GraphPanel, GraphSpan, GraphTie, Ground, GuessMarker, HangingRule, HeatWisps, IlluminatedObject, Knob, LIQUID, LabelChip, Lamp, LaserEmitterGlyph, Leaf, LensHolder, Lever, Lift, LightClock, LightGate, MOTION, MetreRule, Micrometer, MicrometerScales, OpticalCarriage, OpticalRail, OpticalReceiver, PLASTIC, Parachute, ParticleRow, Passenger, Pendulum, Person, Piston, PistonCylinder, PlaneMirror, PointCharge, PointDipper, Post, PowerSupply, ProjectionScreen, Rail, ReachCircle, ReadingCallout, ReplayGrip, Reservoir, RetortStand, Rocket, Roller, RopeEnd, RopeMark, SCENE, STEEL, STORY_FRAME, Scene, SceneCanvas, Shadow, SignedBars, Sky, Slope, SlottedMass, Solid, Spacecraft, SpectrumStrip, Sphere, Spring, Stopwatch, StraightDipper, Strike, SuspensionAssembly, TOP_VEHICLE_SIZE, Tag, TankWater, Thermometer, Thread, TopRiver, TopVehicle, Train, Trolley, VacuumTube, VectorArrow, VectorPanel, VernierCaliper, VernierScales, Vibrator, WaveMedium, XraySource, bobCentre, dialPoint, dialValueAt, heatTone, lensAt, leverFraction, leverTip, liftFloor, lightClockFaces, micrometerGeometry, niceMax, personHand, pistonHandleY, riverFlowTransform, scaleTop, sceneGraph, setRocketState, setRollerTurn, slopePoint, standPivot, suspensionGeometry, thermometerLevelY, trackTop, tubeElectrodes, useLightAge, vectorFrame, vernierGeometry, xrayExitX };
+export { ACCENT, Ground, Grounding, Knob, LaserEmitterGlyph, OpticalReceiver, Person, SCENE, STEEL, STORY_FRAME, SceneCanvas, Solid, Train, dialAngle, dialPoint, useScene };

package/dist/kit/scene/loupe.mjs

@@ -0,0 +1,252 @@
+'use client';
+
+import { FigText } from "../figure/text.mjs";
+import { SCENE } from "./tokens.mjs";
+import { HUE, STROKE } from "../figure/figure.mjs";
+import { usePointerDrag } from "../figure/grip-pointer.mjs";
+import { Glint } from "./materials.mjs";
+import { DASH } from "../figure/lines.mjs";
+import { useId } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/scene/loupe.tsx
+/**
+* Loupe: a circular magnified view of one spot of the picture, beside it.
+*
+* Teardown's "macro on the part that matters", taken as an instrument: a ring on the object marks
+* what is inspected, two tangent lines carry the eye out to the lens, and the lens shows that spot
+* larger. The lens can show two things, together or alone:
+*
+*   subject   the SAME scene content, magnified. The part to inspect is drawn once inside a group
+*             carrying `useLoupeSubject()`'s id, and the lens repeats it with an SVG `<use>` under a
+*             clip and a scale. Nothing is drawn twice in React, ids inside it are not duplicated,
+*             and a part a frame painter moves through refs moves in the lens too.
+*   children  what is really there at that scale (the domains in an iron bar, the ions in a melt),
+*             drawn in LENS coordinates (the lens centre is (cx, cy)) and clipped to it. The model
+*             decides it; the loupe only frames it.
+*
+* A `scale` bar says how far a length in the lens is on the object. `onAt` makes the ring a grip:
+* drag it (the shared pointer lifecycle, one move per frame) or move it with the arrow keys.
+*
+* The lens is equipment: a steel rim, a lit inner edge and one glint on the upper-left shoulder. It
+* never draws a caption; what the lens shows is said by the scene's one label for it, outside.
+*/
+const r2 = (n) => Math.round(n * 100) / 100;
+/** A scoped id for the group a loupe magnifies. */
+function useLoupeSubject() {
+	return `loupe-subject-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+/**
+* The outer common tangents of the ring and the lens: two segments, each from the ring to the lens.
+* Empty when one circle holds the other (no tangent line exists).
+*/
+function loupeTangents(at, r, lens) {
+	const dx = lens.cx - at.x;
+	const dy = lens.cy - at.y;
+	const d = Math.hypot(dx, dy);
+	if (d <= Math.abs(lens.r - r) + 1e-6) return [];
+	const theta = Math.atan2(dy, dx);
+	const alpha = Math.acos((r - lens.r) / d);
+	return [theta + alpha, theta - alpha].map((a) => {
+		const c = Math.cos(a);
+		const s = Math.sin(a);
+		return [{
+			x: r2(at.x + r * c),
+			y: r2(at.y + r * s)
+		}, {
+			x: r2(lens.cx + lens.r * c),
+			y: r2(lens.cy + lens.r * s)
+		}];
+	});
+}
+/** The magnification, and the map from a point on the object to the same point in the lens. */
+function loupeMap(at, r, lens) {
+	const zoom = lens.r / r;
+	return {
+		zoom,
+		toLens: (p) => ({
+			x: r2(lens.cx + (p.x - at.x) * zoom),
+			y: r2(lens.cy + (p.y - at.y) * zoom)
+		})
+	};
+}
+function Loupe({ at, r, lens, subject, ground = SCENE.label.paper, scale, leaders = true, ring = true, onAt, step = 4, label, children }) {
+	const clip = `loupe-clip-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+	const { zoom } = loupeMap(at, r, lens);
+	const tangents = leaders ? loupeTangents(at, r, lens) : [];
+	const drag = usePointerDrag({
+		locate: (event) => {
+			const m = event.currentTarget.getScreenCTM?.();
+			if (!m) return null;
+			const p = new DOMPoint(event.clientX, event.clientY).matrixTransform(m.inverse());
+			return {
+				x: r2(p.x),
+				y: r2(p.y)
+			};
+		},
+		move: (p) => onAt?.(p),
+		position: (p) => p,
+		disabled: !onAt
+	});
+	const keys = (event) => {
+		if (!onAt) return;
+		const d = {
+			ArrowLeft: [-1, 0],
+			ArrowRight: [1, 0],
+			ArrowUp: [0, -1],
+			ArrowDown: [0, 1]
+		}[event.key];
+		if (!d) return;
+		event.preventDefault();
+		onAt({
+			x: r2(at.x + d[0] * step),
+			y: r2(at.y + d[1] * step)
+		});
+	};
+	const bar = scale ? Math.min(scale.units * zoom, lens.r * 1.1) : 0;
+	const barY = lens.cy + lens.r * .66;
+	return /* @__PURE__ */ jsxs("g", {
+		"data-part": "loupe",
+		"data-zoom": r2(zoom),
+		children: [
+			tangents.map(([a, b], i) => /* @__PURE__ */ jsx("line", {
+				x1: a.x,
+				y1: a.y,
+				x2: b.x,
+				y2: b.y,
+				stroke: HUE.soft,
+				strokeWidth: STROKE.hair,
+				strokeDasharray: DASH.dot,
+				strokeLinecap: "round",
+				"data-part": "loupe-leader"
+			}, i)),
+			/* @__PURE__ */ jsx("circle", {
+				cx: lens.cx,
+				cy: lens.cy,
+				r: lens.r,
+				fill: ground
+			}),
+			/* @__PURE__ */ jsx("clipPath", {
+				id: clip,
+				children: /* @__PURE__ */ jsx("circle", {
+					cx: lens.cx,
+					cy: lens.cy,
+					r: r2(lens.r - 1)
+				})
+			}),
+			/* @__PURE__ */ jsxs("g", {
+				clipPath: `url(#${clip})`,
+				"data-part": "loupe-view",
+				children: [subject ? /* @__PURE__ */ jsx("g", {
+					transform: `translate(${r2(lens.cx)} ${r2(lens.cy)}) scale(${r2(zoom)}) translate(${r2(-at.x)} ${r2(-at.y)})`,
+					children: /* @__PURE__ */ jsx("use", { href: `#${subject}` })
+				}) : null, children]
+			}),
+			scale ? /* @__PURE__ */ jsxs("g", {
+				"data-part": "loupe-scale",
+				pointerEvents: "none",
+				children: [
+					/* @__PURE__ */ jsx("rect", {
+						x: r2(lens.cx - bar / 2 - 6),
+						y: r2(barY - 15),
+						width: r2(bar + 12),
+						height: 22,
+						rx: 4,
+						fill: SCENE.label.paper,
+						opacity: .86
+					}),
+					/* @__PURE__ */ jsx("path", {
+						d: `M${r2(lens.cx - bar / 2)} ${r2(barY - 3)}v6M${r2(lens.cx - bar / 2)} ${r2(barY)}H${r2(lens.cx + bar / 2)}M${r2(lens.cx + bar / 2)} ${r2(barY - 3)}v6`,
+						stroke: SCENE.label.ink,
+						strokeWidth: STROKE.line,
+						fill: "none"
+					}),
+					/* @__PURE__ */ jsx(FigText, {
+						x: lens.cx,
+						y: r2(barY - 5),
+						anchor: "middle",
+						size: "note",
+						caps: false,
+						color: SCENE.label.ink,
+						children: scale.label
+					})
+				]
+			}) : null,
+			/* @__PURE__ */ jsx("circle", {
+				cx: lens.cx,
+				cy: lens.cy,
+				r: lens.r,
+				fill: "none",
+				stroke: SCENE.steel.deep,
+				strokeWidth: STROKE.edge + 1.5
+			}),
+			/* @__PURE__ */ jsx("circle", {
+				cx: lens.cx,
+				cy: lens.cy,
+				r: lens.r,
+				fill: "none",
+				stroke: SCENE.steel.base,
+				strokeWidth: STROKE.edge
+			}),
+			/* @__PURE__ */ jsx("circle", {
+				cx: lens.cx,
+				cy: lens.cy,
+				r: r2(lens.r - 2.2),
+				fill: "none",
+				stroke: SCENE.steel.lit,
+				strokeWidth: STROKE.hair,
+				opacity: .8
+			}),
+			/* @__PURE__ */ jsx(Glint, {
+				kind: "arc",
+				cx: lens.cx,
+				cy: lens.cy,
+				r: lens.r,
+				strength: "soft"
+			}),
+			ring ? /* @__PURE__ */ jsxs("g", {
+				"data-part": "loupe-target",
+				...onAt ? {
+					role: "slider",
+					tabIndex: 0,
+					"aria-label": label ?? "Move the lens",
+					"aria-valuetext": `${r2(at.x)}, ${r2(at.y)}`,
+					onKeyDown: keys,
+					style: {
+						cursor: drag.dragging ? "grabbing" : "grab",
+						touchAction: "none"
+					},
+					...drag.handlers
+				} : { pointerEvents: "none" },
+				children: [
+					onAt ? /* @__PURE__ */ jsx("circle", {
+						cx: at.x,
+						cy: at.y,
+						r: Math.max(r, 22),
+						fill: "transparent"
+					}) : null,
+					/* @__PURE__ */ jsx("circle", {
+						cx: at.x,
+						cy: at.y,
+						r,
+						fill: "none",
+						stroke: SCENE.label.paper,
+						strokeWidth: STROKE.edge,
+						opacity: .8
+					}),
+					/* @__PURE__ */ jsx("circle", {
+						cx: at.x,
+						cy: at.y,
+						r,
+						fill: "none",
+						stroke: SCENE.steel.deep,
+						strokeWidth: STROKE.line
+					})
+				]
+			}) : null
+		]
+	});
+}
+
+//#endregion
+export { Loupe, loupeMap, loupeTangents };

package/dist/kit/scene/materials.d.mts

@@ -0,0 +1,132 @@
+import { ReactNode } from "react";
+//#region src/kit/scene/materials.d.ts
+/** The one key light, from the upper left. Every shadow and highlight in the kit follows it. */
+export declare const LIGHT: {
+  /** Where a shadow falls, per unit lifted: down and a little to the right. */
+  readonly shadow: {
+    readonly dx: 0.35;
+    readonly dy: 1;
+  };
+  /** Where a highlight sits on a round body, as a fraction of its radius: up and to the left. */
+  readonly glint: {
+    readonly x: -0.36;
+    readonly y: -0.38;
+  };
+};
+/**
+ * How far an object stands off the surface it casts on, as a `Grounding` `lift` (0..1). `rest` sits
+ * on it, `raised` is a key or a plate standing proud, `lifted` is picked up, `held` is mid-drag.
+ */
+export declare const ELEVATION: {
+  readonly rest: 0;
+  readonly raised: 0.2;
+  readonly lifted: 0.55;
+  readonly held: 0.85;
+};
+type ElevationName = keyof typeof ELEVATION;
+/**
+ * The soft shadow an object casts where it meets its surface, centred under it at (cx, y).
+ *
+ * Three nested ellipses in the physical shadow ink (`SCENE.shadow`, dark in both themes): a dense
+ * core where the object touches, a body, and a wide penumbra. `lift` (0..1, see `ELEVATION`) raises
+ * the object: the core and body shrink and fade, the penumbra spreads, and the whole shadow slides
+ * away from the upper-left light, so a lifted or dragged object visibly leaves the surface.
+ */
+export declare function Grounding({ cx, y, rx, ry, lift }: {
+  cx: number;
+  y: number;
+  /** Half the width of the footprint at rest. */
+  rx: number;
+  /** Half the depth of the footprint; defaults to a flat floor ellipse. */
+  ry?: number;
+  /** 0 on the surface, 1 high above it. */
+  lift?: number;
+}): ReactNode;
+export type GlintStrength = 'hard' | 'soft';
+export type GlintProps =
+/** A curved highlight on a round body (a globe, a ball, a dome), on its upper-left shoulder. */
+{
+  kind: 'arc';
+  cx: number;
+  cy: number;
+  r: number;
+  strength?: GlintStrength;
+} |
+/** A point highlight (a bead, a knob cap, a droplet). */
+{
+  kind: 'dot';
+  cx: number;
+  cy: number;
+  r: number;
+  strength?: GlintStrength;
+} |
+/** A straight highlight down a lit wall or along a lit edge (glass, a rod, a glossy panel). */
+{
+  kind: 'streak';
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+  width?: number;
+  strength?: GlintStrength;
+};
+/**
+ * The highlight where the key light reflects. Drawn in the pinned highlight (`SCENE.spec`), a warm
+ * white in both themes: never page paper, which is near black in dark mode and would draw a dark
+ * scratch. Restrained by design: one glint per object, on the side facing the light.
+ */
+export declare function Glint(props: GlintProps): ReactNode;
+export type EmitterKind = 'incandescent' | 'led' | 'flame' | 'heat';
+/**
+ * Light given off, added to the scene: a radial gradient bounded to the emitter's own circle (or
+ * ellipse), strongest at the source and gone at its edge. On a dark page it adds to what is behind
+ * it (`.lab-emitter`, figure.css); on a light page it is a plain tint, because white paper cannot
+ * get brighter. The colour is physical (`SCI`), never the host's warning colour:
+ *
+ *   incandescent  a filament or a glowing solid: ember at low power, white heat at full
+ *   flame         a warm flame's halo
+ *   heat          the warm bloom over a hot plate (pass `ry` for a flat one)
+ *   led           its own `color`
+ *
+ * Draws nothing at zero intensity.
+ */
+export declare function Emitter({ cx, cy, r, ry, intensity, kind, color }: {
+  cx: number;
+  cy: number;
+  /** The reach of the light: the gradient ends here. */
+  r: number;
+  ry?: number;
+  /** 0..1, how bright. */
+  intensity?: number;
+  kind?: EmitterKind;
+  /** The light's colour for an `led` (or to override a kind). */
+  color?: string;
+}): ReactNode;
+/**
+ * The surface finishes `Solid` draws, from dullest to brightest, then the two glasses: `glass` is
+ * clear, `amber-glass` the brown glass of a light-sensitive reagent bottle (pinned in both themes).
+ */
+export declare const FINISHES: readonly ["matte", "satin", "brushed", "gloss", "glass", "amber-glass"];
+export type Finish = (typeof FINISHES)[number];
+/** The grain's opacity steps: each tone is drawn as one path per step, so a face costs six paths. */
+declare const GRAIN_STEPS: readonly [0.35, 0.6, 1];
+/**
+ * Brushed-metal grain over a face (x, y, w, h, corner radius r): many fine parallel strokes along
+ * `axis` ('x' runs them left to right), of varied length and strength, some catching the light
+ * (`lit`) and some in the groove (`deep`). Returned as path data per tone and opacity step
+ * (`GRAIN_STEPS`), so the caller draws at most six paths whatever the face's size. Strokes stay
+ * inside the rounded rectangle, so no clip path is needed. Deterministic from the geometry, with
+ * coordinates at 2 dp, so server and client agree.
+ */
+declare function brushedGrain(face: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  r?: number;
+}, axis: 'x' | 'y', pitch?: number): {
+  lit: string[];
+  deep: string[];
+};
+//#endregion
+export {};