@orbat-mapper/tactical-draw 0.2.0-alpha.21 → 0.2.0-alpha.23

package/dist/index.mjs

@@ -298,21 +298,24 @@ function resolveGroundTextSizePixels(textSizeMeters, resolution, text) {
 }
 //#endregion
 //#region src/gestures/hit-test.ts
-/** Squared distance from `pixel` to the segment p1→p2 in pixel space, or null if either endpoint fails to project or the segment has zero length. */
-function pixelDistanceToSegment(pixel, p1, p2, toPixel) {
-	const a = toPixel(p1);
-	const b = toPixel(p2);
-	if (!a || !b) return null;
+/** Clamped parameter t ∈ [0, 1] of `pixel` projected onto the segment a→b in pixel space, or null for a zero-length segment. */
+function clampedSegmentParameter(pixel, a, b) {
 	const dx = b[0] - a[0];
 	const dy = b[1] - a[1];
 	const lengthSq = dx * dx + dy * dy;
 	if (lengthSq === 0) return null;
-	let t = ((pixel[0] - a[0]) * dx + (pixel[1] - a[1]) * dy) / lengthSq;
-	t = Math.max(0, Math.min(1, t));
-	const cx = a[0] + t * dx;
-	const cy = a[1] + t * dy;
-	const ddx = pixel[0] - cx;
-	const ddy = pixel[1] - cy;
+	const t = ((pixel[0] - a[0]) * dx + (pixel[1] - a[1]) * dy) / lengthSq;
+	return Math.max(0, Math.min(1, t));
+}
+/** Distance from `pixel` to the segment p1→p2 in pixel space, or null if either endpoint fails to project or the segment has zero length. */
+function pixelDistanceToSegment(pixel, p1, p2, toPixel) {
+	const a = toPixel(p1);
+	const b = toPixel(p2);
+	if (!a || !b) return null;
+	const t = clampedSegmentParameter(pixel, a, b);
+	if (t === null) return null;
+	const ddx = pixel[0] - (a[0] + t * (b[0] - a[0]));
+	const ddy = pixel[1] - (a[1] + t * (b[1] - a[1]));
 	return Math.sqrt(ddx * ddx + ddy * ddy);
 }
 /** Even-odd point-in-ring test in pixel space. */
@@ -1013,6 +1016,188 @@ function buildGuideFeatures(points, isAreaKind, trailingFixedSlots = 0) {
 	return features;
 }
 //#endregion
+//#region src/tactical-draw/snapping.ts
+/** Resolve a draw-interaction map event through `snap`, falling back to the event coordinate. */
+function snappedDrawPosition(snap, event) {
+	return snap?.({
+		coordinate: event.coordinate,
+		pixel: event.pixel,
+		interaction: "draw",
+		originalEvent: event.originalEvent
+	})?.coordinate ?? event.coordinate;
+}
+const DEFAULT_TOLERANCE_PIXELS = 12;
+function graphicCandidates(graphics) {
+	const candidates = [];
+	for (const graphic of graphics) {
+		if (isPointSymbol(graphic)) {
+			candidates.push({
+				id: `${graphic.id}:anchor`,
+				coordinate: graphic.position,
+				kind: "anchor",
+				graphicId: graphic.id
+			});
+			continue;
+		}
+		graphic.controlPoints.forEach((coordinate, controlPointIndex) => {
+			candidates.push({
+				id: `${graphic.id}:control-point:${controlPointIndex}`,
+				coordinate,
+				kind: "control-point",
+				graphicId: graphic.id,
+				controlPointIndex
+			});
+		});
+	}
+	return candidates;
+}
+function isSelfCandidate(candidate, request) {
+	if (request.graphicId === void 0 || candidate.graphicId !== request.graphicId) return false;
+	if (request.interaction === "reshape" && request.controlPointIndex !== void 0) return candidate.controlPointIndex === void 0 || candidate.controlPointIndex === request.controlPointIndex;
+	return true;
+}
+function isLabelFeature(feature) {
+	const properties = feature.properties;
+	return properties?.part === "label" || typeof properties?.labelPlacementKey === "string" || typeof properties?.text === "string";
+}
+function collectGeometryPaths(geometry, featureId, graphicId, out) {
+	const add = (positions, suffix) => {
+		if (positions.length > 0) out.push({
+			id: `${featureId}:${suffix}`,
+			graphicId,
+			positions
+		});
+	};
+	switch (geometry.type) {
+		case "LineString":
+			add(geometry.coordinates, "line");
+			break;
+		case "MultiLineString":
+			geometry.coordinates.forEach((line, index) => add(line, `line:${index}`));
+			break;
+		case "Polygon":
+			geometry.coordinates.forEach((ring, index) => add(ring, `ring:${index}`));
+			break;
+		case "MultiPolygon":
+			geometry.coordinates.forEach((polygon, polygonIndex) => polygon.forEach((ring, ringIndex) => add(ring, `ring:${polygonIndex}:${ringIndex}`)));
+			break;
+		case "GeometryCollection":
+			geometry.geometries.forEach((child, index) => collectGeometryPaths(child, `${featureId}:geometry:${index}`, graphicId, out));
+			break;
+		case "Point":
+		case "MultiPoint": break;
+	}
+}
+function indexGeometryFeatures(features) {
+	const paths = [];
+	features.forEach((feature, index) => {
+		if (!feature.geometry || isLabelFeature(feature)) return;
+		const graphicId = tryControlMeasureIdFromFeature(feature);
+		if (!graphicId) return;
+		const featureId = typeof feature.id === "string" ? feature.id : `${graphicId}:feature:${index}`;
+		collectGeometryPaths(feature.geometry, featureId, graphicId, paths);
+	});
+	return paths;
+}
+function interpolatePosition(a, b, t) {
+	const dimensions = Math.min(a.length, b.length);
+	const position = [];
+	for (let index = 0; index < dimensions; index += 1) position.push(a[index] + (b[index] - a[index]) * t);
+	return position;
+}
+function generatedGeometryCandidates(adapter, paths, request, options) {
+	const resolved = options === true ? {} : options;
+	const edges = resolved.edges ?? true;
+	const vertices = resolved.vertices ?? false;
+	const candidates = [];
+	for (const path of paths) {
+		if (vertices) path.positions.forEach((coordinate, index) => {
+			candidates.push({
+				id: `${path.id}:vertex:${index}`,
+				coordinate,
+				kind: "graphic-vertex",
+				graphicId: path.graphicId
+			});
+		});
+		if (!edges) continue;
+		for (let index = 1; index < path.positions.length; index += 1) {
+			const a = path.positions[index - 1];
+			const b = path.positions[index];
+			const aPixel = adapter.getPixelFromCoordinate(a);
+			const bPixel = adapter.getPixelFromCoordinate(b);
+			if (!aPixel || !bPixel) continue;
+			const t = clampedSegmentParameter(request.pixel, aPixel, bPixel) ?? 0;
+			candidates.push({
+				id: `${path.id}:edge:${index - 1}`,
+				coordinate: interpolatePosition(a, b, t),
+				kind: "graphic-edge",
+				graphicId: path.graphicId
+			});
+		}
+	}
+	return candidates;
+}
+function createSnapResolver(adapter, getGraphics, getGeometryFeatures, getOptions) {
+	let indexedGraphics;
+	let indexedCandidates = [];
+	let indexedFeatures;
+	let indexedGeometryPaths = [];
+	const builtInCandidates = () => {
+		const graphics = getGraphics();
+		if (graphics !== indexedGraphics) {
+			indexedGraphics = graphics;
+			indexedCandidates = graphicCandidates(graphics);
+		}
+		return indexedCandidates;
+	};
+	const geometryPaths = () => {
+		const features = getGeometryFeatures();
+		if (features !== indexedFeatures) {
+			indexedFeatures = features;
+			indexedGeometryPaths = indexGeometryFeatures(features);
+		}
+		return indexedGeometryPaths;
+	};
+	return (request) => {
+		const options = getOptions();
+		const clear = () => options?.onSnap?.(null);
+		if (!options?.enabled || options.bypass?.(request.originalEvent)) {
+			clear();
+			return null;
+		}
+		const tolerance = options.tolerancePixels ?? DEFAULT_TOLERANCE_PIXELS;
+		if (!Number.isFinite(tolerance) || tolerance < 0) {
+			clear();
+			return null;
+		}
+		const candidateLists = [];
+		if (options.sources?.graphics !== false) candidateLists.push(builtInCandidates());
+		const graphicGeometry = options.sources?.graphicGeometry;
+		if (graphicGeometry) candidateLists.push(generatedGeometryCandidates(adapter, geometryPaths(), request, graphicGeometry));
+		const external = options.sources?.external?.(request);
+		if (external) candidateLists.push(external);
+		let best = null;
+		for (const list of candidateLists) for (const candidate of list) {
+			if (isSelfCandidate(candidate, request)) continue;
+			const pixel = adapter.getPixelFromCoordinate(candidate.coordinate);
+			if (!pixel) continue;
+			const distancePixels = Math.hypot(pixel[0] - request.pixel[0], pixel[1] - request.pixel[1]);
+			if (distancePixels > tolerance) continue;
+			const priority = candidate.priority ?? 0;
+			const bestPriority = best?.candidate.priority ?? 0;
+			if (best && (distancePixels > best.distancePixels || distancePixels === best.distancePixels && priority <= bestPriority)) continue;
+			best = {
+				coordinate: [...candidate.coordinate],
+				pixel: [...pixel],
+				candidate,
+				distancePixels
+			};
+		}
+		options.onSnap?.(best);
+		return best;
+	};
+}
+//#endregion
 //#region src/tactical-draw/draw-controller.ts
 const PREVIEW_CM_ID$1 = "__td_preview__";
 const PREVIEW_CURSOR$1 = "crosshair";
@@ -1030,7 +1215,7 @@ const PREVIEW_CURSOR$1 = "crosshair";
 * kinds need no host UI.
 */
 function runFixedLengthDraw(options) {
-	const { adapter, kind, previewLayer, guideLayer, graphicsStyle, generateId, signal, measureOptions, measureStyle, measureProperties, measureTextAmplifiers, guide: guideOpt, sizeAnchor, onSettled } = options;
+	const { adapter, kind, previewLayer, guideLayer, graphicsStyle, generateId, signal, measureOptions, measureStyle, measureProperties, measureTextAmplifiers, guide: guideOpt, sizeAnchor, onSettled, snap } = options;
 	const metadata = getControlMeasureMetadata(kind);
 	const rule = metadata.rule;
 	const min = metadata.minCoordinates;
@@ -1048,7 +1233,7 @@ function runFixedLengthDraw(options) {
 	const savedCursor = "";
 	const handleClick = (event) => {
 		if (ctx.settled) return;
-		committed.push(event.coordinate);
+		committed.push(snappedDrawPosition(snap, event));
 		rubberBand = void 0;
 		if (committed.length >= required) {
 			ctx.commit(buildSnapshot);
@@ -1059,7 +1244,7 @@ function runFixedLengthDraw(options) {
 	const handlePointerMove = (event) => {
 		if (ctx.settled) return;
 		if (committed.length === 0) return;
-		rubberBand = event.coordinate;
+		rubberBand = snappedDrawPosition(snap, event);
 		renderPreview();
 	};
 	function renderPreview() {
@@ -1285,7 +1470,7 @@ const PREVIEW_CURSOR = "crosshair";
 * added point again" as additional gesture-level commit triggers.
 */
 function runVariableLengthDraw(options) {
-	const { adapter, kind, previewLayer, guideLayer, graphicsStyle, generateId, signal, onSession, seed, measureOptions, measureStyle, measureProperties, measureTextAmplifiers, guide: guideOpt, sizeAnchor, onSettled } = options;
+	const { adapter, kind, previewLayer, guideLayer, graphicsStyle, generateId, signal, onSession, seed, measureOptions, measureStyle, measureProperties, measureTextAmplifiers, guide: guideOpt, sizeAnchor, onSettled, snap } = options;
 	const metadata = getControlMeasureMetadata(kind);
 	if (typeof metadata.minCoordinates !== "number") throw new Error(`runVariableLengthDraw: kind "${kind}" has no minCoordinates metadata`);
 	const min = metadata.minCoordinates;
@@ -1392,7 +1577,7 @@ function runVariableLengthDraw(options) {
 	}
 	const handleClick = (event) => {
 		if (ctx.settled) return;
-		const pos = roundControlPoint(event.coordinate);
+		const pos = roundControlPoint(snappedDrawPosition(snap, event));
 		const lastSpineIdx = committed.length - 1 - trailingFixed;
 		const finishIndices = closedRing && lastSpineIdx > 0 ? [lastSpineIdx, 0] : [lastSpineIdx];
 		for (let i = 0; i < committed.length; i++) if (positionsEqual(pos, committed[i])) {
@@ -1433,7 +1618,7 @@ function runVariableLengthDraw(options) {
 	const handlePointerMove = (event) => {
 		if (ctx.settled) return;
 		if (committed.length === 0) return;
-		rubberBand = event.coordinate;
+		rubberBand = snappedDrawPosition(snap, event);
 		renderPreview();
 	};
 	function renderPreview() {
@@ -1693,6 +1878,19 @@ function pickHandle(handles, pixel, tolerance, toPixel) {
 	}
 	return null;
 }
+//#endregion
+//#region src/tactical-draw/rotation.ts
+/** Excalidraw-style rotation increment used while Shift is held. */
+const CONSTRAINED_ROTATION_STEP = Math.PI / 12;
+/** Normalize radians to the canonical clockwise [0, 2π) range. */
+function normalizeRotation(angle) {
+	const turn = Math.PI * 2;
+	return (angle % turn + turn) % turn;
+}
+/** Snap an absolute rotation angle to the nearest 15-degree increment. */
+function constrainRotation(angle) {
+	return Math.round(angle / CONSTRAINED_ROTATION_STEP) * CONSTRAINED_ROTATION_STEP;
+}
 function rotate(x, y, angle) {
 	const cos = Math.cos(angle);
 	const sin = Math.sin(angle);
@@ -1956,8 +2154,9 @@ function beginBoxDrag(args) {
 		const pivotPixel = box.center;
 		const pivot = fromPixel(pivotPixel);
 		const startAngle = Math.atan2(downPixel[1] - pivotPixel[1], downPixel[0] - pivotPixel[0]);
-		const move = (pixel) => {
-			const angle = Math.atan2(pixel[1] - pivotPixel[1], pixel[0] - pivotPixel[0]) - startAngle;
+		const move = (pixel, modifiers) => {
+			const rawAngle = Math.atan2(pixel[1] - pivotPixel[1], pixel[0] - pivotPixel[0]) - startAngle;
+			const angle = modifiers?.constrainRotation ? constrainRotation(box.angle + rawAngle) - box.angle : rawAngle;
 			return {
 				points: rotatePointsAround(preDragPoints, pivot, pivotPixel, angle, projection),
 				box: {
@@ -1971,7 +2170,7 @@ function beginBoxDrag(args) {
 		return {
 			kind,
 			move,
-			end: (pixel) => move(pixel).points
+			end: (pixel, modifiers) => move(pixel, modifiers).points
 		};
 	}
 	const origin = fromPixel(downPixel);
@@ -2035,6 +2234,102 @@ const BEGIN_DRAG_FOR_TEST = Symbol("EditSession.beginDragForTest");
 */
 const END_DRAG_FOR_TEST = Symbol("EditSession.endDragForTest");
 //#endregion
+//#region src/tactical-draw/session-history.ts
+/** @internal Controller-owned history stack. */
+function createSessionHistory(options) {
+	const limit = Math.max(1, options.limit ?? 100);
+	let entries = [{ value: options.clone(options.initial) }];
+	let index = 0;
+	let settled = false;
+	const listeners = /* @__PURE__ */ new Set();
+	function currentState() {
+		if (settled) return {
+			canUndo: false,
+			canRedo: false
+		};
+		return {
+			canUndo: index > 0,
+			canRedo: index < entries.length - 1,
+			...index > 0 && entries[index]?.label ? { undoLabel: entries[index].label } : {},
+			...index < entries.length - 1 && entries[index + 1]?.label ? { redoLabel: entries[index + 1].label } : {}
+		};
+	}
+	function notify() {
+		const state = currentState();
+		const errors = [];
+		for (const listener of [...listeners]) try {
+			listener(state);
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "SessionHistory subscriber errors");
+	}
+	function move(nextIndex, source) {
+		if (settled || nextIndex < 0 || nextIndex >= entries.length) return false;
+		const from = options.clone(entries[index].value);
+		const to = options.clone(entries[nextIndex].value);
+		try {
+			if (!options.apply(from, to, source)) return false;
+		} catch (error) {
+			if (!options.isCurrent?.(to)) throw error;
+			index = nextIndex;
+			try {
+				notify();
+			} catch (notifyError) {
+				throw new AggregateError([error, notifyError], "SessionHistory undo/redo errors");
+			}
+			throw error;
+		}
+		index = nextIndex;
+		notify();
+		return true;
+	}
+	return {
+		get state() {
+			return currentState();
+		},
+		undo() {
+			return move(index - 1, "undo");
+		},
+		redo() {
+			return move(index + 1, "redo");
+		},
+		subscribe(listener) {
+			listener(currentState());
+			if (settled) return () => {};
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		record(value, label) {
+			if (settled || options.equals(entries[index].value, value)) return false;
+			entries.splice(index + 1);
+			entries.push({
+				value,
+				label
+			});
+			if (entries.length > limit + 1) entries.shift();
+			index = entries.length - 1;
+			notify();
+			return true;
+		},
+		reset(value) {
+			if (settled) return;
+			entries = [{ value: options.clone(value) }];
+			index = 0;
+			notify();
+		},
+		settle() {
+			if (settled) return;
+			settled = true;
+			entries = [];
+			index = 0;
+			notify();
+			listeners.clear();
+		}
+	};
+}
+//#endregion
 //#region src/tactical-draw/box-features.ts
 /**
 * Rendering helpers shared by the single-measure edit controller
@@ -2325,7 +2620,7 @@ function mergeAmplifierPlacementField(existing, incoming) {
 *  - close / abort / signal / preempt / destroy paths
 */
 function runEdit(opts) {
-	const { adapter, measure, graphicsLayer, previewLayer, guideLayer, handlesLayer, graphicsStyle, signal, closeOnClickAway = true, modes: initialModes, interactionStyle, onSession, handleIdPrefix, guide: guideOpt, restoreOriginalToGraphics, wasOnGraphicsLayer, onSettled, onClickAwayGraphicsPick } = opts;
+	const { adapter, measure, graphicsLayer, previewLayer, guideLayer, handlesLayer, graphicsStyle, signal, closeOnClickAway = true, modes: initialModes, interactionStyle, onSession, handleIdPrefix, guide: guideOpt, restoreOriginalToGraphics, wasOnGraphicsLayer, onSettled, onClickAwayGraphicsPick, snap } = opts;
 	const renderOpts = graphicsStyle ? { graphicsStyle } : void 0;
 	let sizeAnchor = opts.sizeAnchor ?? "ground";
 	const metadata = getControlMeasureMetadata(measure.kind);
@@ -2386,6 +2681,28 @@ function runEdit(opts) {
 	* persisted on the measure; a fresh edit always starts back at `0`.
 	*/
 	let boxAngle = 0;
+	function captureHistory() {
+		return {
+			points: workingPoints.map((point) => [...point]),
+			options: { ...workingOptions ?? {} },
+			style: currentStyle ? { ...currentStyle } : void 0,
+			textAmplifiers: workingTextAmplifiers ? { ...workingTextAmplifiers } : void 0,
+			amplifierPlacements: snapshotAmplifierPlacements(),
+			sizeAnchor,
+			nonGeometryDirty,
+			boxAngle
+		};
+	}
+	function restoreHistory(value) {
+		replaceWorkingPoints(value.points);
+		replaceWorkingOptions(value.options);
+		currentStyle = value.style ? { ...value.style } : void 0;
+		workingTextAmplifiers = value.textAmplifiers ? { ...value.textAmplifiers } : void 0;
+		workingAmplifierPlacements = value.amplifierPlacements ? structuredClone(value.amplifierPlacements) : void 0;
+		sizeAnchor = value.sizeAnchor;
+		nonGeometryDirty = value.nonGeometryDirty;
+		boxAngle = value.boxAngle;
+	}
 	/**
 	* The transform box fitted around the *rendered* working-copy geometry
 	* (pixel space), or `null` when nothing projected this frame. Re-fitted
@@ -2612,12 +2929,13 @@ function runEdit(opts) {
 	*  - Reject restores the working state to the pre-gesture snapshot and
 	*    recomputes `dirty`. Close/abort settle the session as normal.
 	*/
-	function emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, previousSizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements) {
+	function emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, previousSizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, source = "gesture", historyLabel = "Edit", previousBoxAngle = boxAngle) {
 		if (ctx.settled) return;
 		let rejectRequested = false;
 		let closeRequested = false;
 		let abortRequested = false;
 		const event = {
+			source,
 			graphic: currentRendered,
 			previous: previousRendered,
 			session,
@@ -2646,11 +2964,13 @@ function runEdit(opts) {
 			sizeAnchor = previousSizeAnchor;
 			workingTextAmplifiers = previousTextAmplifiers;
 			workingAmplifierPlacements = previousAmplifierPlacements;
+			boxAngle = previousBoxAngle;
 			nonGeometryDirty = previousNonGeometryDirty;
 			renderPreview();
 			renderHandlesLayer();
 			recomputeDirty();
 		}
+		if (!ctx.settled && !rejectRequested && (source === "gesture" || source === "programmatic")) history.record(captureHistory(), historyLabel);
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, "EditSession.onChange listener errors");
 	}
@@ -2664,7 +2984,7 @@ function runEdit(opts) {
 	* queued during the drag are applied after the listener emission (so the
 	* post-gesture render reflects the requested mode set).
 	*/
-	function commitGesture(nextPoints, preGestureOptions, nextAmplifierPlacements) {
+	function commitGesture(nextPoints, preGestureOptions, nextAmplifierPlacements, preGestureBoxAngle = boxAngle) {
 		if (ctx.settled) return;
 		const previousPoints = workingPoints.map((p) => [...p]);
 		const previousOptions = { ...preGestureOptions ?? workingOptions ?? {} };
@@ -2691,7 +3011,7 @@ function runEdit(opts) {
 		recomputeDirty();
 		dragInFlight = false;
 		drainPendingModes();
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, "gesture", "Edit", preGestureBoxAngle);
 	}
 	function setOptions(partial) {
 		if (ctx.settled) return;
@@ -2706,6 +3026,7 @@ function runEdit(opts) {
 			...workingOptions ?? {},
 			...partial ?? {}
 		});
+		if (JSON.stringify(workingOptions) === JSON.stringify(previousOptions)) return;
 		let currentRendered;
 		try {
 			currentRendered = rebuildRendered();
@@ -2716,7 +3037,7 @@ function runEdit(opts) {
 		renderPreview();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, "programmatic", "Change options");
 	}
 	function setStyle(partial) {
 		if (ctx.settled) return;
@@ -2731,6 +3052,7 @@ function runEdit(opts) {
 			...currentStyle ?? {},
 			...partial
 		};
+		if (JSON.stringify(currentStyle) === JSON.stringify(previousStyle)) return;
 		let currentRendered;
 		try {
 			currentRendered = rebuildRendered();
@@ -2741,7 +3063,7 @@ function runEdit(opts) {
 		renderPreview();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, "programmatic", "Change style");
 	}
 	/**
 	* Shallow-merge into the live working text amplifiers. Mirrors
@@ -2776,6 +3098,7 @@ function runEdit(opts) {
 			if (value !== void 0 && value.trim() !== "") merged[canonicalKey ?? key] = value;
 		}
 		workingTextAmplifiers = Object.keys(merged).length > 0 ? merged : void 0;
+		if (JSON.stringify(workingTextAmplifiers) === JSON.stringify(previousTextAmplifiers)) return;
 		let currentRendered;
 		try {
 			currentRendered = rebuildRendered();
@@ -2786,9 +3109,9 @@ function runEdit(opts) {
 		renderPreview();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, "programmatic", "Change text");
 	}
-	function setAmplifierPlacements(partial) {
+	function setAmplifierPlacements(partial, source = "programmatic", historyLabel = "Move label") {
 		if (ctx.settled) return;
 		const previousPoints = workingPoints.map((p) => [...p]);
 		const previousOptions = { ...workingOptions ?? {} };
@@ -2808,11 +3131,12 @@ function runEdit(opts) {
 			else next[field] = merged;
 		}
 		workingAmplifierPlacements = Object.keys(next).length > 0 ? next : void 0;
+		if (JSON.stringify(workingAmplifierPlacements) === JSON.stringify(previousAmplifierPlacements)) return;
 		const currentRendered = rebuildRendered();
 		renderPreview();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, sizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, source, historyLabel);
 	}
 	/**
 	* Flip the size anchor for the measure under edit (ADR-0020). Re-renders the
@@ -2835,7 +3159,7 @@ function runEdit(opts) {
 		const currentRendered = rebuildRendered();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, previousSizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements);
+		emitChange(previousRendered, previousPoints, previousOptions, previousStyle, previousNonGeometryDirty, previousSizeAnchor, currentRendered, previousTextAmplifiers, previousAmplifierPlacements, "programmatic", "Change size anchor");
 	}
 	/** Apply a translate gesture by shifting every working point by `delta`. */
 	function commitTranslate(delta) {
@@ -2864,7 +3188,7 @@ function runEdit(opts) {
 		const pivot = box ? driver.fromPixel(box.center) : computeBoundingBoxCenter(workingPoints);
 		if (!pivot) return;
 		boxAngle += angle;
-		commitGesture(rotatePointsAround(workingPoints, pivot, pivotPixel, angle, dragProjection), preFreezeOptions);
+		commitGesture(rotatePointsAround(workingPoints, pivot, pivotPixel, angle, dragProjection), preFreezeOptions, void 0, boxAngle - angle);
 	}
 	function modesEqual(a, b) {
 		if (a.length !== b.length) return false;
@@ -2883,7 +3207,32 @@ function runEdit(opts) {
 		pendingModes = null;
 		applyModes(next);
 	}
+	const history = createSessionHistory({
+		initial: captureHistory(),
+		clone: (value) => ({
+			points: value.points.map((point) => [...point]),
+			options: { ...value.options ?? {} },
+			style: value.style ? { ...value.style } : void 0,
+			textAmplifiers: value.textAmplifiers ? { ...value.textAmplifiers } : void 0,
+			amplifierPlacements: value.amplifierPlacements ? structuredClone(value.amplifierPlacements) : void 0,
+			sizeAnchor: value.sizeAnchor,
+			nonGeometryDirty: value.nonGeometryDirty,
+			boxAngle: value.boxAngle
+		}),
+		equals: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+		isCurrent: (value) => JSON.stringify(captureHistory()) === JSON.stringify(value),
+		apply(from, to, source) {
+			const previousRendered = rebuildRendered();
+			restoreHistory(to);
+			renderPreview();
+			renderHandlesLayer();
+			recomputeDirty();
+			emitChange(previousRendered, from.points, from.options, from.style, from.nonGeometryDirty, from.sizeAnchor, rebuildRendered(), from.textAmplifiers, from.amplifierPlacements, source, "Edit", from.boxAngle);
+			return !ctx.settled && JSON.stringify(captureHistory()) === JSON.stringify(to);
+		}
+	});
 	const session = {
+		history,
 		graphic: measure,
 		get workingGraphic() {
 			return cloneControlMeasure({
@@ -2943,6 +3292,7 @@ function runEdit(opts) {
 			const current = session.workingGraphic;
 			const next = updater(current);
 			if (next.id !== measure.id || next.kind !== measure.kind) throw new TypeError("updateGraphic must preserve control-measure id and kind");
+			if (JSON.stringify(next) === JSON.stringify(current)) return;
 			renderMeasureForAdapter(adapter, next, renderOpts);
 			workingPoints.splice(0, workingPoints.length, ...next.controlPoints.map((point) => [...point]));
 			workingOptions = { ...next.options ?? {} };
@@ -2953,7 +3303,7 @@ function runEdit(opts) {
 			renderPreview();
 			renderHandlesLayer();
 			recomputeDirty();
-			emitChange(previous, previous.graphic.controlPoints.map((point) => [...point]), previous.graphic.options, previous.graphic.style, previousNonGeometryDirty, previousSizeAnchor, rebuildRendered(), previous.graphic.textAmplifiers, previous.graphic.amplifierPlacements);
+			emitChange(previous, previous.graphic.controlPoints.map((point) => [...point]), previous.graphic.options, previous.graphic.style, previousNonGeometryDirty, previousSizeAnchor, rebuildRendered(), previous.graphic.textAmplifiers, previous.graphic.amplifierPlacements, "programmatic", "Update graphic");
 		},
 		setOptions(partial) {
 			setOptions(partial);
@@ -3004,6 +3354,38 @@ function runEdit(opts) {
 		}
 	};
 	let activeDrag = null;
+	function snappedPixel(pixel, info, interaction, controlPointIndex) {
+		if (!snap) return pixel;
+		return snap({
+			coordinate: driver.fromPixel(pixel),
+			pixel,
+			interaction,
+			graphicId: measure.id,
+			controlPointIndex,
+			originalEvent: info?.native
+		})?.pixel ?? pixel;
+	}
+	function translatedBoxPixel(pixel, info, drag) {
+		if (!snap || drag.fsm.kind !== "body") return pixel;
+		const first = drag.preDragPoints[0];
+		if (!first) return pixel;
+		const cursor = driver.fromPixel(pixel);
+		const origin = driver.fromPixel(drag.downPixel);
+		const anchor = [...first];
+		anchor[0] = first[0] + cursor[0] - origin[0];
+		anchor[1] = first[1] + cursor[1] - origin[1];
+		const anchorPixel = driver.toPixel(anchor);
+		if (!anchorPixel) return pixel;
+		const result = snap({
+			coordinate: anchor,
+			pixel: anchorPixel,
+			interaction: "translate",
+			graphicId: measure.id,
+			originalEvent: info?.native
+		});
+		if (!result) return pixel;
+		return [pixel[0] + result.pixel[0] - anchorPixel[0], pixel[1] + result.pixel[1] - anchorPixel[1]];
+	}
 	/**
 	* A live label *move* drag: direct label grab, the floating grip, or a body
 	* grab inside the selected label's transform box (ADR-0017 box machinery
@@ -3205,7 +3587,8 @@ function runEdit(opts) {
 			});
 			activeDrag = {
 				fsm,
-				preDragPoints
+				preDragPoints,
+				controlPointIndex: hit.kind === "midpoint" ? hit.index + 1 : hit.index
 			};
 			if (fsm.kind === "midpoint") {
 				workingPoints.splice(0, workingPoints.length, ...initialPoints);
@@ -3250,17 +3633,19 @@ function runEdit(opts) {
 			}
 		}
 	};
-	function paintDragSnapshot(pixel) {
+	function paintDragSnapshot(pixel, info) {
 		if (!activeDrag) return;
-		const snapshot = activeDrag.fsm.move(pixel);
+		const resolvedPixel = snappedPixel(pixel, info, "reshape", activeDrag.controlPointIndex);
+		const snapshot = activeDrag.fsm.move(resolvedPixel);
 		workingPoints.splice(0, workingPoints.length, ...snapshot.points);
 		renderPreview();
 		renderHandlesLayer();
 		recomputeDirty();
 	}
-	function paintBoxDragSnapshot(pixel) {
+	function paintBoxDragSnapshot(pixel, info, constrainRotation = false) {
 		if (!activeBoxDrag) return;
-		const snapshot = activeBoxDrag.fsm.move(pixel);
+		const resolvedPixel = translatedBoxPixel(pixel, info, activeBoxDrag);
+		const snapshot = activeBoxDrag.fsm.move(resolvedPixel, { constrainRotation });
 		activeBoxDrag.lastSnapshot = snapshot;
 		workingPoints.splice(0, workingPoints.length, ...snapshot.points);
 		workingAmplifierPlacements = transformAmplifierPlacements(activeBoxDrag.preDragAmplifierPlacements, activeBoxDrag.preDragBox, snapshot.box, driver);
@@ -3268,7 +3653,7 @@ function runEdit(opts) {
 		renderHandlesLayer();
 		recomputeDirty();
 	}
-	const onDriverMove = (pixel) => {
+	const onDriverMove = (pixel, info) => {
 		if (ctx.settled) return;
 		if (activeLabelRotateDrag) {
 			const drag = activeLabelRotateDrag;
@@ -3303,8 +3688,8 @@ function runEdit(opts) {
 			};
 			renderPreview();
 			renderHandlesLayer();
-		} else if (activeDrag) paintDragSnapshot(pixel);
-		else if (activeBoxDrag) paintBoxDragSnapshot(pixel);
+		} else if (activeDrag) paintDragSnapshot(pixel, info);
+		else if (activeBoxDrag) paintBoxDragSnapshot(pixel, info, info?.shiftKey);
 	};
 	/** Reset drag-in-flight bookkeeping shared by every "gesture ended" path. */
 	function endDragBookkeeping() {
@@ -3312,7 +3697,7 @@ function runEdit(opts) {
 		dragInFlight = false;
 		drainPendingModes();
 	}
-	const onDriverUp = (pixel) => {
+	const onDriverUp = (pixel, info) => {
 		if (activeLabelRotateDrag) {
 			const drag = activeLabelRotateDrag;
 			activeLabelRotateDrag = null;
@@ -3321,7 +3706,7 @@ function runEdit(opts) {
 			if (Math.hypot(pixel[0] - drag.downPixel[0], pixel[1] - drag.downPixel[1]) > CLICK_SLOP_PX$3) {
 				const delta = pointerAngleAround(pixel, drag.anchorPixel) - drag.startPointerAngle;
 				const rotation = drag.startRotation - delta;
-				setAmplifierPlacements({ [drag.key]: { rotation } });
+				setAmplifierPlacements({ [drag.key]: { rotation } }, "gesture", "Rotate label");
 			} else {
 				renderPreview();
 				renderHandlesLayer();
@@ -3335,7 +3720,7 @@ function runEdit(opts) {
 			const position = labelAnchorFromPointer(pixel, grabOffset);
 			workingAmplifierPlacements = previous;
 			endDragBookkeeping();
-			if (position && Math.hypot(pixel[0] - downPixel[0], pixel[1] - downPixel[1]) > CLICK_SLOP_PX$3) setAmplifierPlacements({ [field]: position });
+			if (position && Math.hypot(pixel[0] - downPixel[0], pixel[1] - downPixel[1]) > CLICK_SLOP_PX$3) setAmplifierPlacements({ [field]: position }, "gesture", "Move label");
 			else {
 				selectedLabelKey = selectedLabelKey === field ? null : field;
 				renderPreview();
@@ -3351,10 +3736,10 @@ function runEdit(opts) {
 				driver.setDragPanEnabled(true);
 				return;
 			}
-			const { fsm, preDragPoints } = activeDrag;
+			const { fsm, preDragPoints, controlPointIndex } = activeDrag;
 			activeDrag = null;
 			driver.setDragPanEnabled(true);
-			const next = fsm.end(pixel);
+			const next = fsm.end(snappedPixel(pixel, info, "reshape", controlPointIndex));
 			replaceWorkingPoints(preDragPoints);
 			commitGesture(next);
 			return;
@@ -3380,11 +3765,16 @@ function runEdit(opts) {
 				bodyClickPending = true;
 				return;
 			}
-			const finalSnapshot = fsm.move(pixel);
+			const finalPixel = translatedBoxPixel(pixel, info, {
+				fsm,
+				preDragPoints,
+				downPixel
+			});
+			const finalSnapshot = fsm.move(finalPixel, { constrainRotation: info?.shiftKey });
 			replaceWorkingPoints(preDragPoints);
 			workingAmplifierPlacements = preDragAmplifierPlacements;
 			if (fsm.kind === "rotate") boxAngle += finalSnapshot.box.angle - preDragBox.angle;
-			commitGesture(finalSnapshot.points, preDragOptions, transformAmplifierPlacements(preDragAmplifierPlacements, preDragBox, finalSnapshot.box, driver));
+			commitGesture(finalSnapshot.points, preDragOptions, transformAmplifierPlacements(preDragAmplifierPlacements, preDragBox, finalSnapshot.box, driver), preDragBox.angle);
 			return;
 		}
 	};
@@ -3435,8 +3825,12 @@ function runEdit(opts) {
 		],
 		onViewChange: rescaleOnViewChange,
 		onSettled: (settlement) => {
-			if (onSettled) onSettled();
-			settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			try {
+				history.settle();
+			} finally {
+				if (onSettled) onSettled();
+				settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			}
 		},
 		attach(c) {
 			ctx = c;
@@ -3641,6 +4035,25 @@ function runGroupTransform(opts) {
 	const settleEmitter = createSettleEmitter("TransformSession.onSettled listener errors");
 	/** Session-scoped box rotation (ADR-0017 decision #2), shared by the whole group. */
 	let boxAngle = 0;
+	function captureHistory() {
+		return {
+			ids: members.map((member) => member.measure.id),
+			points: clonePointsByMember(),
+			amplifierPlacements: cloneAmplifierPlacementsByMember(),
+			optionsOverrides: cloneOptionsOverrideByMember(),
+			sizeAnchor,
+			nonGeometryDirty,
+			boxAngle
+		};
+	}
+	function restoreHistory(value) {
+		restorePointsByMember(value.points);
+		applyAmplifierPlacementsByMember(value.amplifierPlacements.map((placements) => placements ? structuredClone(placements) : void 0));
+		applyOptionsOverrides(value.optionsOverrides);
+		sizeAnchor = value.sizeAnchor;
+		nonGeometryDirty = value.nonGeometryDirty;
+		boxAngle = value.boxAngle;
+	}
 	/** The group box fitted over every member's rendered geometry, or `null` when nothing projects this frame. */
 	let groupBox = null;
 	let ctx;
@@ -3817,12 +4230,13 @@ function runGroupTransform(opts) {
 	* instance to all listeners in order, deferred `reject`/`close`/`abort`
 	* (close/abort override reject), exception collection with `AggregateError`.
 	*/
-	function emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, previousSizeAnchor, previousNonGeometryDirty, previousOptionsOverrideByMember, currentRendered) {
+	function emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, previousSizeAnchor, previousNonGeometryDirty, previousOptionsOverrideByMember, currentRendered, source = "gesture", historyLabel = "Transform", previousBoxAngle = boxAngle) {
 		if (ctx.settled) return;
 		let rejectRequested = false;
 		let closeRequested = false;
 		let abortRequested = false;
 		const event = {
+			source,
 			graphics: currentRendered,
 			previous: previousRendered,
 			session,
@@ -3851,10 +4265,12 @@ function runGroupTransform(opts) {
 			sizeAnchor = previousSizeAnchor;
 			nonGeometryDirty = previousNonGeometryDirty;
 			applyOptionsOverrides(previousOptionsOverrideByMember);
+			boxAngle = previousBoxAngle;
 			renderAllPreviews();
 			renderHandlesLayer();
 			recomputeDirty();
 		}
+		if (!ctx.settled && !rejectRequested && members === membersAtEmission && (source === "gesture" || source === "programmatic")) history.record(captureHistory(), historyLabel);
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, "TransformSession.onChange listener errors");
 	}
@@ -3880,7 +4296,7 @@ function runGroupTransform(opts) {
 		}
 		return snapshots;
 	}
-	function commitGesture(nextConcatPoints, preGestureOptionsOverrideByMember, nextAmplifierPlacementsByMember) {
+	function commitGesture(nextConcatPoints, preGestureOptionsOverrideByMember, nextAmplifierPlacementsByMember, preGestureBoxAngle = boxAngle) {
 		if (ctx.settled) return;
 		const previousPointsByMember = clonePointsByMember();
 		const previousAmplifierPlacementsByMember = cloneAmplifierPlacementsByMember();
@@ -3901,7 +4317,7 @@ function runGroupTransform(opts) {
 		renderHandlesLayer();
 		recomputeDirty();
 		dragInFlight = false;
-		emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, sizeAnchor, nonGeometryDirty, previousOptionsOverrideByMember, currentRendered);
+		emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, sizeAnchor, nonGeometryDirty, previousOptionsOverrideByMember, currentRendered, "gesture", "Transform", preGestureBoxAngle);
 	}
 	function setSizeAnchor(next) {
 		if (ctx.settled || sizeAnchor === next) return;
@@ -3915,7 +4331,7 @@ function runGroupTransform(opts) {
 		const currentRendered = rebuildRenderedAll();
 		nonGeometryDirty = true;
 		dirty = true;
-		emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, previousSizeAnchor, previousNonGeometryDirty, previousOptionsOverrideByMember, currentRendered);
+		emitChange(previousRendered, previousPointsByMember, previousAmplifierPlacementsByMember, previousSizeAnchor, previousNonGeometryDirty, previousOptionsOverrideByMember, currentRendered, "programmatic", "Change size anchor");
 	}
 	/**
 	* Cancel an in-flight box drag without committing it: restore the pre-drag
@@ -3962,13 +4378,42 @@ function runGroupTransform(opts) {
 		renderAllPreviews();
 		renderHandlesLayer();
 		recomputeDirty();
-		if (removedSnapshots.length > 0) commitEmitter.emit(removedSnapshots);
+		const notificationErrors = [];
+		try {
+			history.reset(captureHistory());
+		} catch (error) {
+			notificationErrors.push(error);
+		}
+		if (removedSnapshots.length > 0) try {
+			commitEmitter.emit(removedSnapshots);
+		} catch (error) {
+			notificationErrors.push(error);
+		}
+		if (notificationErrors.length === 1) throw notificationErrors[0];
+		if (notificationErrors.length > 1) throw new AggregateError(notificationErrors, "TransformSession.setGraphics notification errors");
 		return removedSnapshots;
 	}
 	function close() {
 		return commitClose();
 	}
+	const history = createSessionHistory({
+		initial: captureHistory(),
+		clone: (value) => structuredClone(value),
+		equals: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+		isCurrent: (value) => JSON.stringify(captureHistory()) === JSON.stringify(value),
+		apply(from, to, source) {
+			if (JSON.stringify(from.ids) !== JSON.stringify(to.ids)) return false;
+			const previousRendered = rebuildRenderedAll();
+			restoreHistory(to);
+			renderAllPreviews();
+			renderHandlesLayer();
+			recomputeDirty();
+			emitChange(previousRendered, from.points, from.amplifierPlacements, from.sizeAnchor, from.nonGeometryDirty, from.optionsOverrides, rebuildRenderedAll(), source, "Transform", from.boxAngle);
+			return !ctx.settled && JSON.stringify(captureHistory()) === JSON.stringify(to);
+		}
+	});
 	const session = {
+		history,
 		get graphics() {
 			return members.map((m) => m.measure);
 		},
@@ -4044,9 +4489,9 @@ function runGroupTransform(opts) {
 		dragInFlight = true;
 		driver.setDragPanEnabled(false);
 	};
-	function paintBoxDragSnapshot(pixel) {
+	function paintBoxDragSnapshot(pixel, constrainRotation = false) {
 		if (!activeBoxDrag) return;
-		const snapshot = activeBoxDrag.fsm.move(pixel);
+		const snapshot = activeBoxDrag.fsm.move(pixel, { constrainRotation });
 		activeBoxDrag.lastSnapshot = snapshot;
 		applyConcatenatedPoints(snapshot.points);
 		applyAmplifierPlacementsByMember(activeBoxDrag.preDragAmplifierPlacementsByMember.map((placements) => transformAmplifierPlacements(placements, activeBoxDrag.preDragBox, snapshot.box, driver)));
@@ -4054,11 +4499,11 @@ function runGroupTransform(opts) {
 		renderHandlesLayer();
 		recomputeDirty();
 	}
-	const onDriverMove = (pixel) => {
+	const onDriverMove = (pixel, info) => {
 		if (ctx.settled) return;
-		if (activeBoxDrag) paintBoxDragSnapshot(pixel);
+		if (activeBoxDrag) paintBoxDragSnapshot(pixel, info?.shiftKey);
 	};
-	const onDriverUp = (pixel) => {
+	const onDriverUp = (pixel, info) => {
 		if (!activeBoxDrag) return;
 		if (ctx.settled) {
 			activeBoxDrag = null;
@@ -4080,11 +4525,11 @@ function runGroupTransform(opts) {
 			bodyClickPending = true;
 			return;
 		}
-		const finalSnapshot = fsm.move(pixel);
+		const finalSnapshot = fsm.move(pixel, { constrainRotation: info?.shiftKey });
 		applyConcatenatedPoints(preDragPoints);
 		applyAmplifierPlacementsByMember(preDragAmplifierPlacementsByMember);
 		if (fsm.kind === "rotate") boxAngle += finalSnapshot.box.angle - preDragBox.angle;
-		commitGesture(finalSnapshot.points, preDragOptionsOverrideByMember, preDragAmplifierPlacementsByMember.map((placements) => transformAmplifierPlacements(placements, preDragBox, finalSnapshot.box, driver)));
+		commitGesture(finalSnapshot.points, preDragOptionsOverrideByMember, preDragAmplifierPlacementsByMember.map((placements) => transformAmplifierPlacements(placements, preDragBox, finalSnapshot.box, driver)), preDragBox.angle);
 	};
 	let pickPreview;
 	let pickHandles;
@@ -4130,8 +4575,12 @@ function runGroupTransform(opts) {
 		layers: [previewLayer, handlesLayer],
 		onViewChange: rescaleOnViewChange,
 		onSettled: (settlement) => {
-			if (onSettled) onSettled();
-			if (settlement.status === "rejected") settleEmitter.emit(settleReasonFromError(settlement.error));
+			try {
+				history.settle();
+			} finally {
+				if (onSettled) onSettled();
+				if (settlement.status === "rejected") settleEmitter.emit(settleReasonFromError(settlement.error));
+			}
 		},
 		attach(c) {
 			ctx = c;
@@ -4245,13 +4694,6 @@ function pointSymbolFeature(symbol, render, resolution) {
 	};
 }
 //#endregion
-//#region src/tactical-draw/rotation.ts
-/** Normalize radians to the canonical clockwise [0, 2π) range. */
-function normalizeRotation(angle) {
-	const turn = Math.PI * 2;
-	return (angle % turn + turn) % turn;
-}
-//#endregion
 //#region src/tactical-draw/graphic-transform-controller.ts
 const HIT_TOLERANCE_PX$1 = 12;
 const CLICK_SLOP_PX$1 = 3;
@@ -4272,13 +4714,22 @@ function runGraphicTransform(opts) {
 	const commitEmitter = createCommitEmitter("GraphicTransformSession.onCommit listener errors");
 	const settleEmitter = createSettleEmitter("GraphicTransformSession.onSettled listener errors");
 	const renderOpts = graphicsStyle ? { graphicsStyle } : void 0;
-	const snapshots = () => working.map((graphic) => isPointSymbol(graphic) ? {
+	const snapshotsFor = (source) => source.map((graphic) => isPointSymbol(graphic) ? {
 		graphic: clonePointSymbol(graphic),
 		render: capability.render(graphic)
 	} : {
 		graphic: cloneControlMeasure(graphic),
 		render: renderMeasureForAdapter(adapter, graphic, renderOpts)
 	});
+	const snapshots = () => snapshotsFor(working);
+	const captureHistory = () => ({
+		working: working.map(cloneGraphic),
+		boxAngle
+	});
+	const cloneHistory = (value) => ({
+		working: value.working.map(cloneGraphic),
+		boxAngle: value.boxAngle
+	});
 	function renderAll() {
 		if (ctx.settled) return;
 		const features = [];
@@ -4345,12 +4796,14 @@ function runGraphicTransform(opts) {
 			return next;
 		});
 	}
-	function emit(previous, previousGraphics) {
+	function emit(previousState, source) {
+		const previous = snapshotsFor(previousState.working);
 		const current = snapshots();
 		let reject = false;
 		let close = false;
 		let abort = false;
 		const event = {
+			source,
 			graphics: current,
 			previous,
 			session,
@@ -4367,14 +4820,30 @@ function runGraphicTransform(opts) {
 		if (abort) ctx.fail(new TacticalDrawAbortError("session"));
 		else if (close) ctx.commit(snapshots);
 		else if (reject && !ctx.settled) {
-			working = previousGraphics.map(cloneGraphic);
+			working = previousState.working.map(cloneGraphic);
+			boxAngle = previousState.boxAngle;
 			dirty = JSON.stringify(working) !== JSON.stringify(original);
 			renderAll();
 		}
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, "GraphicTransformSession.onChange errors");
-	}
+		return !ctx.settled && !reject;
+	}
+	const history = createSessionHistory({
+		initial: captureHistory(),
+		clone: cloneHistory,
+		equals: (a, b) => a.boxAngle === b.boxAngle && JSON.stringify(a.working) === JSON.stringify(b.working),
+		isCurrent: (value) => boxAngle === value.boxAngle && JSON.stringify(working) === JSON.stringify(value.working),
+		apply(from, to, source) {
+			working = to.working.map(cloneGraphic);
+			boxAngle = to.boxAngle;
+			dirty = JSON.stringify(working) !== JSON.stringify(original);
+			renderAll();
+			return emit(from, source);
+		}
+	});
 	const session = {
+		history,
 		get graphics() {
 			return original.map(cloneGraphic);
 		},
@@ -4421,9 +4890,9 @@ function runGraphicTransform(opts) {
 		};
 		driver.setDragPanEnabled(false);
 	};
-	const dragResult = (pixel) => {
+	const dragResult = (pixel, constrainRotation = false) => {
 		if (!drag) return null;
-		const result = drag.fsm.move(pixel);
+		const result = drag.fsm.move(pixel, { constrainRotation });
 		const scale = drag.fsm.kind === "scale" ? Math.max(result.box.halfWidth / drag.startBox.halfWidth, result.box.halfHeight / drag.startBox.halfHeight) : 1;
 		const rotation = drag.fsm.kind === "rotate" ? result.box.angle - drag.startBox.angle : 0;
 		return {
@@ -4431,18 +4900,18 @@ function runGraphicTransform(opts) {
 			graphics: applyPoints(drag.start, result.points, scale, rotation)
 		};
 	};
-	const onMove = (pixel) => {
+	const onMove = (pixel, info) => {
 		const active = drag;
-		const next = dragResult(pixel);
+		const next = dragResult(pixel, info?.shiftKey);
 		if (!active || !next) return;
 		working = next.graphics;
 		active.liveBox = next.result.box;
 		renderAll();
 	};
-	const onUp = (pixel) => {
+	const onUp = (pixel, info) => {
 		if (!drag) return;
 		const active = drag;
-		const next = dragResult(pixel);
+		const next = dragResult(pixel, info?.shiftKey);
 		drag = null;
 		suppressClickAway = true;
 		driver.setDragPanEnabled(true);
@@ -4452,13 +4921,15 @@ function runGraphicTransform(opts) {
 			renderAll();
 			return;
 		}
-		const previous = snapshots();
-		const previousGraphics = working.map(cloneGraphic);
+		const previousState = captureHistory();
 		working = next.graphics;
 		if (active.fsm.kind === "rotate") boxAngle += next.result.box.angle - active.startBox.angle;
 		dirty = JSON.stringify(working) !== JSON.stringify(original);
 		renderAll();
-		emit(previous, previousGraphics);
+		if (emit(previousState, "gesture")) {
+			const label = `${active.fsm.kind[0].toUpperCase()}${active.fsm.kind.slice(1)}`;
+			history.record(captureHistory(), label);
+		}
 	};
 	let previewPick;
 	let handlesPick;
@@ -4481,8 +4952,12 @@ function runGraphicTransform(opts) {
 		layers: [previewLayer, handlesLayer],
 		onViewChange: renderAll,
 		onSettled(settlement) {
-			onSettled?.();
-			settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			try {
+				history.settle();
+			} finally {
+				onSettled?.();
+				settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			}
 		},
 		attach(interaction) {
 			ctx = interaction;
@@ -4548,7 +5023,7 @@ var PointSymbolCapabilityRequiredError = class extends Error {
 //#region src/tactical-draw/point-symbol-draw-controller.ts
 const PREVIEW_ID = "__td_point_symbol_preview__";
 function runPointSymbolDraw(options) {
-	const { adapter, capability, draft, previewLayer, generateId, signal, onSettled } = options;
+	const { adapter, capability, draft, previewLayer, generateId, signal, onSettled, snap } = options;
 	let latestPosition = draft.position;
 	let ctx;
 	const savedCursor = "";
@@ -4568,13 +5043,13 @@ function runPointSymbolDraw(options) {
 		ctx.writeLayer(previewLayer, [plan.feature]);
 	};
 	const handlePointerMove = (event) => {
-		latestPosition = event.coordinate;
+		latestPosition = snappedDrawPosition(snap, event);
 		renderPreview();
 	};
 	const handleClick = (event) => {
-		latestPosition = event.coordinate;
+		latestPosition = snappedDrawPosition(snap, event);
 		ctx.commit(() => {
-			const graphic = build(draft.id ?? generateId(), event.coordinate);
+			const graphic = build(draft.id ?? generateId(), latestPosition);
 			return {
 				graphic: clonePointSymbol(graphic),
 				render: capability.render(graphic)
@@ -4621,7 +5096,7 @@ function symbolBox(adapter, capability, symbol, padding = 0) {
 	};
 }
 function runPointSymbolEdit(opts) {
-	const { adapter, capability, symbol, graphicsLayer, previewLayer, handlesLayer, signal, closeOnClickAway = true, interactionStyle, onSession, handleIdPrefix, restoreOriginalToGraphics, wasOnGraphicsLayer, onSettled, onClickAwayGraphicsPick } = opts;
+	const { adapter, capability, symbol, graphicsLayer, previewLayer, handlesLayer, signal, closeOnClickAway = true, interactionStyle, onSession, handleIdPrefix, restoreOriginalToGraphics, wasOnGraphicsLayer, onSettled, onClickAwayGraphicsPick, snap } = opts;
 	let modes = normalisePointModes(opts.modes);
 	let working = clonePointSymbol(symbol);
 	let dirty = false;
@@ -4632,6 +5107,8 @@ function runPointSymbolEdit(opts) {
 	const listeners = /* @__PURE__ */ new Set();
 	const commitEmitter = createCommitEmitter("GraphicEditSession.onCommit listener errors");
 	const settleEmitter = createSettleEmitter("GraphicEditSession.onSettled listener errors");
+	const captureHistory = () => ({ working: clonePointSymbol(working) });
+	const cloneHistory = (value) => ({ working: clonePointSymbol(value.working) });
 	const snapshot = () => ({
 		graphic: clonePointSymbol(working),
 		render: capability.render(working)
@@ -4649,15 +5126,17 @@ function runPointSymbolEdit(opts) {
 		}
 		ctx.writeLayer(handlesLayer, handles);
 	};
-	const apply = (next, previous = snapshot()) => {
-		working = clonePointSymbol(next);
-		dirty = JSON.stringify(working) !== JSON.stringify(symbol);
-		render();
+	const emitChange = (previousState, source) => {
+		const previous = {
+			graphic: clonePointSymbol(previousState.working),
+			render: capability.render(previousState.working)
+		};
 		const current = snapshot();
 		let reject = false;
 		let close = false;
 		let abort = false;
 		const event = {
+			source,
 			graphic: current,
 			previous,
 			session,
@@ -4680,14 +5159,35 @@ function runPointSymbolEdit(opts) {
 		if (abort) ctx.fail(new TacticalDrawAbortError("session"));
 		else if (close) ctx.commit(snapshot);
 		else if (reject && !ctx.settled) {
-			working = clonePointSymbol(previous.graphic);
+			working = clonePointSymbol(previousState.working);
 			dirty = JSON.stringify(working) !== JSON.stringify(symbol);
 			render();
 		}
 		if (errors.length === 1) throw errors[0];
 		if (errors.length > 1) throw new AggregateError(errors, "GraphicEditSession.onChange errors");
+		return !ctx.settled && !reject;
+	};
+	const history = createSessionHistory({
+		initial: captureHistory(),
+		clone: cloneHistory,
+		equals: (a, b) => JSON.stringify(a.working) === JSON.stringify(b.working),
+		isCurrent: (value) => JSON.stringify(working) === JSON.stringify(value.working),
+		apply(from, to, source) {
+			working = clonePointSymbol(to.working);
+			dirty = JSON.stringify(working) !== JSON.stringify(symbol);
+			render();
+			return emitChange(from, source);
+		}
+	});
+	const apply = (next, source = "programmatic", label = "Update graphic") => {
+		const previousState = captureHistory();
+		working = clonePointSymbol(next);
+		dirty = JSON.stringify(working) !== JSON.stringify(symbol);
+		render();
+		if (emitChange(previousState, source)) history.record(captureHistory(), label);
 	};
 	const session = {
+		history,
 		graphic: clonePointSymbol(symbol),
 		get workingGraphic() {
 			return clonePointSymbol(working);
@@ -4711,11 +5211,10 @@ function runPointSymbolEdit(opts) {
 		},
 		updateGraphic(updater) {
 			if (ctx.settled) return;
-			const previous = snapshot();
 			const next = updater(clonePointSymbol(working));
 			if (next.kind !== "point-symbol" || next.id !== symbol.id) throw new TypeError("updateGraphic must preserve point-symbol kind and id");
 			capability.render(next);
-			apply(next, previous);
+			apply(next, "programmatic", "Update graphic");
 		},
 		onChange(listener) {
 			if (ctx.settled) return () => {};
@@ -4747,27 +5246,38 @@ function runPointSymbolEdit(opts) {
 		};
 		driver.setDragPanEnabled(false);
 	};
-	const transformed = (pixel) => {
+	const transformed = (pixel, info) => {
 		if (!drag) return null;
 		const next = clonePointSymbol(drag.start);
-		if (drag.kind === "body") next.position = driver.fromPixel([drag.anchor[0] + pixel[0] - drag.down[0], drag.anchor[1] + pixel[1] - drag.down[1]]);
-		else if (drag.kind === "rotate") next.rotation = normalizeRotation(drag.start.rotation + pointerAngle(pixel, drag.anchor) - drag.startPointerAngle);
-		else {
+		if (drag.kind === "body") {
+			const unsnappedPosition = driver.fromPixel([drag.anchor[0] + pixel[0] - drag.down[0], drag.anchor[1] + pixel[1] - drag.down[1]]);
+			const anchorPixel = driver.toPixel(unsnappedPosition) ?? pixel;
+			next.position = (snap?.({
+				coordinate: unsnappedPosition,
+				pixel: anchorPixel,
+				interaction: "translate",
+				graphicId: symbol.id,
+				originalEvent: info?.native
+			}))?.coordinate ?? unsnappedPosition;
+		} else if (drag.kind === "rotate") {
+			const rotation = drag.start.rotation + pointerAngle(pixel, drag.anchor) - drag.startPointerAngle;
+			next.rotation = normalizeRotation(info?.shiftKey ? constrainRotation(rotation) : rotation);
+		} else {
 			const distance = Math.hypot(pixel[0] - drag.anchor[0], pixel[1] - drag.anchor[1]);
 			next.size.value = Math.max(.1, drag.start.size.value * (distance / drag.startDistance));
 		}
 		return next;
 	};
-	const onMove = (pixel) => {
-		const next = transformed(pixel);
+	const onMove = (pixel, info) => {
+		const next = transformed(pixel, info);
 		if (!next) return;
 		working = next;
 		render();
 	};
-	const onUp = (pixel) => {
+	const onUp = (pixel, info) => {
 		if (!drag) return;
 		const currentDrag = drag;
-		const next = transformed(pixel);
+		const next = transformed(pixel, info);
 		drag = null;
 		suppressClickAway = true;
 		driver.setDragPanEnabled(true);
@@ -4777,7 +5287,7 @@ function runPointSymbolEdit(opts) {
 			render();
 			return;
 		}
-		apply(next);
+		apply(next, "gesture", `${currentDrag.kind[0].toUpperCase()}${currentDrag.kind.slice(1)}`);
 	};
 	let previewPick;
 	let handlesPick;
@@ -4803,8 +5313,12 @@ function runPointSymbolEdit(opts) {
 		layers: [previewLayer, handlesLayer],
 		onViewChange: render,
 		onSettled(settlement) {
-			onSettled?.();
-			settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			try {
+				history.settle();
+			} finally {
+				onSettled?.();
+				settleFromInteraction(settlement, commitEmitter, settleEmitter);
+			}
 		},
 		attach(interaction) {
 			ctx = interaction;
@@ -4860,6 +5374,8 @@ var TacticalDraw = class {
 	defaultInteractionStyle;
 	generateId;
 	pointSymbols;
+	snappingOptions;
+	resolveSnap;
 	destroyed = false;
 	hasRendered = false;
 	activeInteraction = new ActiveInteractionTracker();
@@ -4910,12 +5426,15 @@ var TacticalDraw = class {
 	* surrounding collection state.
 	*/
 	lastRenderedMeasures = [];
+	snapGeometryFeatures = [];
 	constructor(adapter, options) {
 		this.adapter = adapter;
 		this.graphicsStyle = resolveStyleHints(BUILT_IN_GRAPHICS_STYLE, options?.graphicsStyle, void 0);
 		this.defaultInteractionStyle = options?.interactionStyle;
 		this.generateId = options?.generateId ?? (() => `td-${++this.idCounter}`);
 		this.pointSymbols = options?.pointSymbols;
+		this.snappingOptions = options?.snapping;
+		this.resolveSnap = createSnapResolver(adapter, () => this.lastRenderedMeasures, () => this.snapGeometryFeatures, () => this.snappingOptions);
 		const owned = /* @__PURE__ */ new Set();
 		const provided = options?.layers ?? {};
 		this.graphicsLayer = resolveSlot(adapter, provided.graphics, owned);
@@ -4929,6 +5448,16 @@ var TacticalDraw = class {
 		this.adapter.setLayerStyle(this.guideLayer, guideToStyleOptions(this.baseGuideStyle()));
 		this.adapter.onViewChange(this.handleViewChange);
 	}
+	/** Replace snapping configuration without recreating the map adapter or façade. */
+	setSnappingOptions(options) {
+		this.assertAlive();
+		this.clearSnapResult();
+		this.snappingOptions = options;
+	}
+	/** Clear transient host affordances when snapping or its interaction ends. */
+	clearSnapResult() {
+		this.snappingOptions?.onSnap?.(null);
+	}
 	/**
 	* Render `measures` into features and write them to the graphics layer.
 	* Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
@@ -4951,6 +5480,7 @@ var TacticalDraw = class {
 		}
 		this.adapter.reconcileLayerIconResources(this.graphicsLayer, [...resources.values()]);
 		this.adapter.updateLayerFeatures(this.graphicsLayer, features);
+		this.snapGeometryFeatures = features;
 	}
 	/**
 	* Re-render the graphics layer on a view (zoom) change so pixel-denominated
@@ -5111,6 +5641,7 @@ var TacticalDraw = class {
 		};
 		const onSettled = () => {
 			clearSlot();
+			this.clearSnapResult();
 			if (extraSettle) extraSettle();
 		};
 		this.activeInteraction.begin();
@@ -5164,7 +5695,8 @@ var TacticalDraw = class {
 				previewLayer: this.previewLayer,
 				generateId: this.generateId,
 				signal: options?.signal,
-				onSettled
+				onSettled,
+				snap: this.resolveSnap
 			}), null);
 		}
 		const measureDraft = draft;
@@ -5196,7 +5728,8 @@ var TacticalDraw = class {
 			measureTextAmplifiers: measureDraft.textAmplifiers,
 			guide: options?.guide,
 			sizeAnchor: options?.sizeAnchor,
-			onSettled
+			onSettled,
+			snap: this.resolveSnap
 		}) : runVariableLengthDraw({
 			adapter: this.adapter,
 			kind,
@@ -5213,7 +5746,8 @@ var TacticalDraw = class {
 			measureTextAmplifiers: measureDraft.textAmplifiers,
 			guide: options?.guide,
 			sizeAnchor: options?.sizeAnchor,
-			onSettled
+			onSettled,
+			snap: this.resolveSnap
 		}), null, extraSettle);
 	}
 	edit(measure, options) {
@@ -5242,7 +5776,8 @@ var TacticalDraw = class {
 				restoreOriginalToGraphics,
 				wasOnGraphicsLayer,
 				onSettled,
-				onClickAwayGraphicsPick: (event) => this.dispatchHostPick(this.graphicsLayer, event)
+				onClickAwayGraphicsPick: (event) => this.dispatchHostPick(this.graphicsLayer, event),
+				snap: this.resolveSnap
 			}), (handle) => {
 				this.activeEdit = handle;
 				return () => {
@@ -5282,7 +5817,8 @@ var TacticalDraw = class {
 			restoreOriginalToGraphics,
 			wasOnGraphicsLayer,
 			onSettled,
-			onClickAwayGraphicsPick
+			onClickAwayGraphicsPick,
+			snap: this.resolveSnap
 		}), (handle) => {
 			this.activeEdit = handle;
 			return () => {