@orbat-mapper/tactical-draw 0.2.0-alpha.22 → 0.2.0-alpha.24

package/dist/index.d.mts

@@ -264,6 +264,12 @@ interface MapAdapter {
    */
   onViewChange(handler: () => void): void;
   offViewChange(handler: () => void): void;
+  /**
+   * The engine evaluates the meters→pixels clamp for ground-sized point
+   * symbols inside its own style layer, so meters-sized point symbols don't
+   * need view-change re-renders for size.
+   */
+  readonly scalesGroundPointSymbolsNatively?: boolean;
   /**
    * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
    * controller. The controller subscribes to pointer events on the returned
@@ -465,7 +471,9 @@ type PointSymbolSize = {
   unit: "pixels";
 } | {
   value: number;
-  unit: "meters";
+  unit: "meters"; /** Floor for the on-screen projection of the ground-based size; none when omitted. */
+  minPixels?: number; /** Cap on the on-screen projection of the ground-based size — typically the pixel size the symbol had when anchored to ground; unclamped when omitted. */
+  maxPixels?: number;
 };
 interface PointSymbolGraphicModifiers {
   /** Radians clockwise, relative to the point symbol's own orientation. */
@@ -1184,6 +1192,55 @@ interface DrawSession {
   onSettled(handler: (reason: SettleReason) => void): () => void;
 }
 //#endregion
+//#region src/tactical-draw/snapping.d.ts
+type SnapInteraction = "draw" | "reshape" | "translate" | "label-drag";
+interface SnapCandidateRequest {
+  coordinate: Position;
+  pixel: PixelCoordinate;
+  interaction: SnapInteraction;
+  graphicId?: string;
+  controlPointIndex?: number;
+  originalEvent?: unknown;
+}
+interface SnapCandidate {
+  id: string;
+  coordinate: Position;
+  kind: string;
+  graphicId?: string;
+  controlPointIndex?: number;
+  priority?: number;
+}
+type SnapCandidateProvider = (request: SnapCandidateRequest) => readonly SnapCandidate[];
+interface SnapResult {
+  coordinate: Position;
+  pixel: PixelCoordinate;
+  candidate: SnapCandidate;
+  distancePixels: number;
+}
+interface GraphicGeometrySnappingOptions {
+  /** Snap to the nearest point along generated linework and polygon boundaries. Default `true`. */
+  edges?: boolean;
+  /** Snap to generated geometry vertices. Default `false`. */
+  vertices?: boolean;
+}
+interface SnappingOptions {
+  enabled?: boolean;
+  tolerancePixels?: number;
+  sources?: {
+    graphics?: boolean;
+    /**
+     * Snap to generated control-measure geometry. `true` enables edges with
+     * vertices disabled; pass an object to select either candidate type.
+     * Text/label point features and the active graphic are excluded.
+     */
+    graphicGeometry?: boolean | GraphicGeometrySnappingOptions;
+    external?: SnapCandidateProvider;
+  };
+  bypass?: (originalEvent: unknown) => boolean;
+  /** Called for each resolution attempt; `null` clears a host-rendered indicator. */
+  onSnap?: (result: SnapResult | null) => void;
+}
+//#endregion
 //#region src/tactical-draw/point-symbol-draw-controller.d.ts
 type DrawPointSymbolDraft = Pick<PointSymbol, "kind" | "sidc"> & Partial<Omit<PointSymbol, "kind" | "sidc">>;
 //#endregion
@@ -1234,6 +1291,8 @@ interface TacticalDrawOptions {
    * the draw API itself are deferred (PRD #40 user-story-5 note).
    */
   generateId?: () => string;
+  /** Optional engine-level snapping for draw and edit interactions. */
+  snapping?: SnappingOptions;
 }
 interface EditOptions {
   signal?: AbortSignal;
@@ -1382,6 +1441,8 @@ declare class TacticalDraw {
   private readonly defaultInteractionStyle;
   private readonly generateId;
   private readonly pointSymbols;
+  private snappingOptions;
+  private readonly resolveSnap;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -1432,7 +1493,12 @@ declare class TacticalDraw {
    * surrounding collection state.
    */
   private lastRenderedMeasures;
+  private snapGeometryFeatures;
   constructor(adapter: MapAdapter, options?: TacticalDrawOptions);
+  /** Replace snapping configuration without recreating the map adapter or façade. */
+  setSnappingOptions(options?: SnappingOptions): void;
+  /** Clear transient host affordances when snapping or its interaction ends. */
+  private clearSnapResult;
   /**
    * Render `measures` into features and write them to the graphics layer.
    * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
@@ -1820,4 +1886,4 @@ declare function nearestWorldCopyLng(lng: number, refLng: number): number;
 /** `nearestWorldCopyLng` applied to a lon/lat position. */
 declare function nearestWorldCopyPosition(position: Position, refLng: number): Position;
 //#endregion
-export { BaseMapAdapter, type CombinedAbort, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicRender, type GraphicSnapshot, type GraphicTransformChangeEvent, type GraphicTransformSession, type GuideStyle, type HandleStyle, type IconResource, type InteractionHit, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resolveGroundTextSizePixels, tryControlMeasureIdFromFeature };
+export { BaseMapAdapter, type CombinedAbort, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GraphicTransformChangeEvent, type GraphicTransformSession, type GuideStyle, type HandleStyle, type IconResource, type InteractionHit, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resolveGroundTextSizePixels, tryControlMeasureIdFromFeature };

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() {
@@ -2435,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);
@@ -3169,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
@@ -3370,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);
@@ -3415,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, constrainRotation = false) {
+	function paintBoxDragSnapshot(pixel, info, constrainRotation = false) {
 		if (!activeBoxDrag) return;
-		const snapshot = activeBoxDrag.fsm.move(pixel, { constrainRotation });
+		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);
@@ -3468,8 +3688,8 @@ function runEdit(opts) {
 			};
 			renderPreview();
 			renderHandlesLayer();
-		} else if (activeDrag) paintDragSnapshot(pixel);
-		else if (activeBoxDrag) paintBoxDragSnapshot(pixel, info?.shiftKey);
+		} 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() {
@@ -3516,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;
@@ -3545,7 +3765,12 @@ function runEdit(opts) {
 				bodyClickPending = true;
 				return;
 			}
-			const finalSnapshot = fsm.move(pixel, { constrainRotation: info?.shiftKey });
+			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;
@@ -4408,7 +4633,10 @@ function runGroupTransform(opts) {
 //#region src/tactical-draw/point-symbol-rendering.ts
 function effectivePointSymbolPixelSize(symbol, resolution) {
 	if (symbol.size.unit === "pixels") return symbol.size.value;
-	return resolution !== void 0 && resolution > 0 ? symbol.size.value / resolution : symbol.size.value;
+	if (resolution === void 0 || resolution <= 0) return symbol.size.value;
+	const px = symbol.size.value / resolution;
+	const { minPixels, maxPixels } = symbol.size;
+	return Math.max(Number.isFinite(minPixels) && minPixels > 0 ? minPixels : 0, Math.min(Number.isFinite(maxPixels) && maxPixels > 0 ? maxPixels : Infinity, px));
 }
 function pointSymbolPixelScale(symbol, render, resolution) {
 	if (!Number.isFinite(render.octagonSize) || render.octagonSize <= 0) throw new TypeError("PointSymbolRender.octagonSize must be a positive finite number");
@@ -4450,6 +4678,12 @@ function renderPointSymbolForAdapter(adapter, capability, symbol) {
 	};
 }
 function pointSymbolFeature(symbol, render, resolution) {
+	const groundSizeProperties = symbol.size.unit === "meters" ? {
+		iconSizeMeters: symbol.size.value,
+		iconOctagonSize: render.octagonSize,
+		...boundProperty("iconMinPixels", symbol.size.minPixels),
+		...boundProperty("iconMaxPixels", symbol.size.maxPixels)
+	} : void 0;
 	return {
 		type: "Feature",
 		id: `${symbol.id}:point-symbol`,
@@ -4464,10 +4698,14 @@ function pointSymbolFeature(symbol, render, resolution) {
 			iconId: render.resourceId,
 			iconScale: pointSymbolPixelScale(symbol, render, resolution),
 			iconRotation: symbol.rotation,
-			iconOpacity: symbol.style?.opacity ?? 1
+			iconOpacity: symbol.style?.opacity ?? 1,
+			...groundSizeProperties
 		}
 	};
 }
+function boundProperty(key, value) {
+	return value !== void 0 && Number.isFinite(value) && value > 0 ? { [key]: value } : {};
+}
 //#endregion
 //#region src/tactical-draw/graphic-transform-controller.ts
 const HIT_TOLERANCE_PX$1 = 12;
@@ -4798,7 +5036,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 = "";
@@ -4818,13 +5056,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)
@@ -4871,7 +5109,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;
@@ -5021,13 +5259,22 @@ function runPointSymbolEdit(opts) {
 		};
 		driver.setDragPanEnabled(false);
 	};
-	const transformed = (pixel, constrainAngle = false) => {
+	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") {
+		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(constrainAngle ? constrainRotation(rotation) : rotation);
+			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));
@@ -5035,7 +5282,7 @@ function runPointSymbolEdit(opts) {
 		return next;
 	};
 	const onMove = (pixel, info) => {
-		const next = transformed(pixel, info?.shiftKey);
+		const next = transformed(pixel, info);
 		if (!next) return;
 		working = next;
 		render();
@@ -5043,7 +5290,7 @@ function runPointSymbolEdit(opts) {
 	const onUp = (pixel, info) => {
 		if (!drag) return;
 		const currentDrag = drag;
-		const next = transformed(pixel, info?.shiftKey);
+		const next = transformed(pixel, info);
 		drag = null;
 		suppressClickAway = true;
 		driver.setDragPanEnabled(true);
@@ -5140,6 +5387,8 @@ var TacticalDraw = class {
 	defaultInteractionStyle;
 	generateId;
 	pointSymbols;
+	snappingOptions;
+	resolveSnap;
 	destroyed = false;
 	hasRendered = false;
 	activeInteraction = new ActiveInteractionTracker();
@@ -5190,12 +5439,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);
@@ -5209,6 +5461,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
@@ -5231,6 +5493,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
@@ -5245,7 +5508,8 @@ var TacticalDraw = class {
 		if (this.destroyed || !this.hasRendered) return;
 		const excluded = this.excludedInteractionIds();
 		const visible = excluded.size > 0 ? this.lastRenderedMeasures.filter((m) => !excluded.has(m.id)) : this.lastRenderedMeasures;
-		if (!visible.some(graphicRendersFromViewState)) return;
+		const nativeGroundIconScaling = this.adapter.scalesGroundPointSymbolsNatively === true;
+		if (!visible.some((g) => graphicRendersFromViewState(g, nativeGroundIconScaling))) return;
 		this.renderMeasuresToGraphics(visible);
 	};
 	/**
@@ -5391,6 +5655,7 @@ var TacticalDraw = class {
 		};
 		const onSettled = () => {
 			clearSlot();
+			this.clearSnapResult();
 			if (extraSettle) extraSettle();
 		};
 		this.activeInteraction.begin();
@@ -5444,7 +5709,8 @@ var TacticalDraw = class {
 				previewLayer: this.previewLayer,
 				generateId: this.generateId,
 				signal: options?.signal,
-				onSettled
+				onSettled,
+				snap: this.resolveSnap
 			}), null);
 		}
 		const measureDraft = draft;
@@ -5476,7 +5742,8 @@ var TacticalDraw = class {
 			measureTextAmplifiers: measureDraft.textAmplifiers,
 			guide: options?.guide,
 			sizeAnchor: options?.sizeAnchor,
-			onSettled
+			onSettled,
+			snap: this.resolveSnap
 		}) : runVariableLengthDraw({
 			adapter: this.adapter,
 			kind,
@@ -5493,7 +5760,8 @@ var TacticalDraw = class {
 			measureTextAmplifiers: measureDraft.textAmplifiers,
 			guide: options?.guide,
 			sizeAnchor: options?.sizeAnchor,
-			onSettled
+			onSettled,
+			snap: this.resolveSnap
 		}), null, extraSettle);
 	}
 	edit(measure, options) {
@@ -5522,7 +5790,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 () => {
@@ -5562,7 +5831,8 @@ var TacticalDraw = class {
 			restoreOriginalToGraphics,
 			wasOnGraphicsLayer,
 			onSettled,
-			onClickAwayGraphicsPick
+			onClickAwayGraphicsPick,
+			snap: this.resolveSnap
 		}), (handle) => {
 			this.activeEdit = handle;
 			return () => {
@@ -5950,8 +6220,8 @@ var TacticalDraw = class {
 		if (this.destroyed) throw new TacticalDrawDestroyedError();
 	}
 };
-function graphicRendersFromViewState(graphic) {
-	return isPointSymbol(graphic) ? graphic.size.unit === "meters" : measureRendersFromViewState(graphic);
+function graphicRendersFromViewState(graphic, nativeGroundIconScaling) {
+	return isPointSymbol(graphic) ? graphic.size.unit === "meters" && !nativeGroundIconScaling : measureRendersFromViewState(graphic);
 }
 function normalisePointEditModes(modes) {
 	for (const mode of modes ?? ["transform"]) if (mode !== "transform" && mode !== "delete") throw new TypeError(`Point-symbol editing does not support mode "${mode}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbat-mapper/tactical-draw",
-  "version": "0.2.0-alpha.22",
+  "version": "0.2.0-alpha.24",
   "description": "Engine-agnostic draw/edit core for tactical control measures (MIL-STD-2525 / APP-6). The MapAdapter ABI and bring-your-own-engine entry point for the tactical-draw package family.",
   "license": "MIT",
   "author": "Orbat Mapper",