@orbat-mapper/tactical-draw 0.2.0-alpha.9 → 0.2.1

package/dist/index.d.mts

@@ -1,248 +1,8 @@
-import { ControlMeasure, ControlMeasureKind, ControlMeasureSnapshot, ControlMeasureStyle } from "@orbat-mapper/control-measures";
+import { S as PointerEventInfo, _ as fillPatternImageDimension, a as MapAdapter, b as EditPointerDriver, c as MapEventHandler, d as PickOptions, f as PixelCoordinate, g as HatchPattern, h as HATCH_PATTERNS, i as LayerId, l as PickEvent, m as TextStyleOptions, n as HandleStyle, o as MapCursor, p as StyleOptions, r as IconResource, s as MapEvent, t as FeatureGroup, u as PickHandler, v as fillPatternImageId, x as PointerCallback, y as makeFillPatternImage } from "./map-adapter-84irgVJR.mjs";
+import { AmplifierPlacement, AmplifierPlacements, ControlMeasure, ControlMeasureKind, ControlMeasureRender, ControlMeasureStyle, TextAmplifiers } from "@orbat-mapper/control-measures";
 import { Feature, Position } from "geojson";
 
-//#region src/gestures/types.d.ts
-interface PointerEventInfo {
-  /** Per-event hit-tolerance override (e.g. larger for touch). */
-  hitTolerance?: number;
-  /**
-   * Whether the Alt/Option modifier was held for this pointer event. The edit
-   * controller reads this on pointer-down to turn a vertex hit into a delete
-   * (the GIS-standard Alt+click-to-delete gesture) instead of a drag. Only the
-   * mouse paths populate it; touch leaves it `undefined`.
-   */
-  altKey?: boolean;
-  /** Engine-native event, for drivers that need to call preventDefault etc. */
-  native?: unknown;
-}
-interface PointerCallback {
-  (pixel: PixelCoordinate, info?: PointerEventInfo): void;
-}
-/**
- * Engine-agnostic pointer driver consumed by `TacticalDraw`'s edit controller.
- * The controller owns handle rendering and hit-tests handles in lonLat space;
- * the driver only carries raw pointer events, drag-pan toggle, and pixel
- * projection.
- */
-interface EditPointerDriver {
-  onPointerDown(cb: PointerCallback): () => void;
-  onPointerMove(cb: PointerCallback): () => void;
-  onPointerUp(cb: PointerCallback): () => void;
-  setDragPanEnabled(enabled: boolean): void;
-  toPixel(lonLat: Position): PixelCoordinate | null;
-  fromPixel(pixel: PixelCoordinate): Position;
-  /** Idempotent. */
-  dispose(): void;
-}
-//#endregion
-//#region src/map-adapter.d.ts
-type PixelCoordinate = [number, number];
-type MapCursor = "" | "default" | "crosshair" | "grab" | "grabbing" | "pointer";
-interface MapEvent {
-  type: string;
-  coordinate: Position;
-  pixel: PixelCoordinate;
-  originalEvent: unknown;
-}
-type MapEventHandler = (event: MapEvent) => void;
-interface StyleOptions {
-  strokeColor?: string;
-  strokeWidth?: number;
-  strokeDash?: number[];
-  fillColor?: string;
-  pointFillColor?: string;
-  pointRadius?: number;
-  text?: TextStyleOptions;
-}
-interface TextStyleOptions {
-  text?: string;
-  labelProperty?: string;
-  font?: string;
-  fillColor?: string;
-  strokeColor?: string;
-  strokeWidth?: number;
-  rotation?: number;
-}
-/**
- * Per-feature style for edit handles (vertex / midpoint / translate / rotate).
- * The producer (`TacticalDraw`) rides this on `properties.style`; the adapter
- * reads it back when rendering the handle, so it is part of the adapter
- * contract rather than the tactical-draw authoring surface. `pointRadius` is a
- * UI affordance not present on `ControlMeasureStyle`. See ADR-0006.
- */
-interface HandleStyle {
-  strokeColor?: string;
-  strokeWidth?: number;
-  strokeDash?: readonly number[];
-  fillColor?: string;
-  pointRadius?: number;
-}
-type LayerId = string;
-/**
- * Click-style hit event delivered by {@link MapAdapter.onPick}.
- *
- * `id` is the control measure id, already split off the feature id by the
- * adapter (see `controlMeasureIdFromFeature`).
- *
- * `originalEvent` is whatever the engine surfaces — OpenLayers normalises to
- * `PointerEvent`, MapLibre delivers `MouseEvent`, Leaflet delivers
- * `MouseEvent | TouchEvent`. Do not narrow to `PointerEvent` at the consumer.
- */
-interface PickEvent {
-  id: string;
-  feature: Feature;
-  pixel: PixelCoordinate;
-  coordinate: Position;
-  originalEvent: MouseEvent | PointerEvent | TouchEvent;
-}
-type PickHandler = (event: PickEvent) => void;
-interface PickOptions {
-  signal?: AbortSignal;
-}
-interface MapAdapter {
-  /**
-   * Add a vector layer to the map.
-   * @returns unique layer ID
-   */
-  addVectorLayer(options?: {
-    style?: StyleOptions;
-  }): LayerId;
-  /**
-   * Remove a layer from the map.
-   */
-  removeLayer(layerId: LayerId): void;
-  /**
-   * Set the style for a specific layer.
-   */
-  setLayerStyle(layerId: LayerId, style: StyleOptions): void;
-  /**
-   * Set features on a vector layer.
-   * Features should be standard GeoJSON Features.
-   */
-  setLayerFeatures(layerId: LayerId, features: Feature[]): void;
-  /**
-   * Clear all features from a layer.
-   */
-  clearLayer(layerId: LayerId): void;
-  /**
-   * Reconcile features on a layer against the incoming set, keyed by `id`.
-   *
-   * Semantics:
-   *  - features with an `id` that already exists are updated in place;
-   *  - features with a fresh `id` are added;
-   *  - features in the layer whose `id` is missing from the incoming set are
-   *    removed.
-   *
-   * Features must carry a stable `id`. Use this when you can compute the
-   * complete desired state of a layer in one go; for partial removals use
-   * {@link removeFeatures}.
-   */
-  updateLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
-  /**
-   * Remove features by `id` from a layer. Ids that are not present are
-   * silently ignored.
-   */
-  removeFeatures(layerId: LayerId, ids: readonly string[]): void;
-  /**
-   * Subscribe to click-style "pick" events for a specific layer. Basemap and
-   * other-layer clicks never fire the handler.
-   *
-   * For control-measure features, adapters must set `PickEvent.id` to the
-   * originating control-measure id (not the rendered part's feature id).
-   * Features that do not satisfy the control-measure feature-id contract must
-   * be ignored rather than dispatched.
-   *
-   * Bound to the engine's tap-suppressing click event (OL `singleclick`,
-   * MapLibre `click`, Leaflet `click`) so the handler does not fire at the
-   * end of a pan or pinch-zoom gesture.
-   *
-   * Hit tolerance is pointer-type aware: 4 px for mouse/pen, 12 px for touch.
-   *
-   * Returns an unsubscribe function. The returned function and the optional
-   * `signal` are both honoured; either teardown path stops further events,
-   * and both are idempotent.
-   */
-  onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
-  /**
-   * Map Event Listeners
-   *
-   * Ordering contract: a `"click"` handler and the `onPick` handlers for the
-   * same user click MUST observe the pick first — adapters deliver picks and
-   * `"click"` from the same underlying engine event, in registration order.
-   * The draw/edit controllers register their pick subscriptions before their
-   * click handler and read the stashed pick inside it (click-away close /
-   * close-then-pick re-dispatch); an adapter that fires `"click"` from an
-   * earlier engine event than its picks breaks that contract (e.g. OL
-   * `click` vs `singleclick`).
-   */
-  on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
-  off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
-  /**
-   * Projection / Coordinate Utilities
-   */
-  toLonLat(coordinate: number[]): Position;
-  fromLonLat(position: Position): number[];
-  getPixelFromCoordinate(position: Position): PixelCoordinate | null;
-  /**
-   * Get current viewport size in CSS pixels.
-   */
-  getViewportSize(): {
-    width: number;
-    height: number;
-  };
-  /**
-   * Pan the map by pixel delta.
-   * Positive delta means desired on-screen feature shift (right/down).
-   */
-  panByPixels(delta: PixelCoordinate, options?: {
-    durationMs?: number;
-  }): void;
-  /**
-   * Set the map viewport cursor. Pass an empty string to restore engine default styling.
-   */
-  setCursor(cursor: MapCursor): void;
-  /**
-   * Toggle the engine's native double-click-to-zoom gesture. `TacticalDraw`
-   * disables this for the lifetime of a variable-length draw so the commit
-   * `dblclick` doesn't also zoom the map.
-   */
-  setDoubleClickZoomEnabled(enabled: boolean): void;
-  /**
-   * Get current view resolution (meters per pixel at center or generally).
-   * returns undefined if not supported or not ready.
-   */
-  getResolution(): number | undefined;
-  /**
-   * Get current map zoom level
-   */
-  getZoom(): number | undefined;
-  /**
-   * Listen for view changes (zoom/resolution)
-   */
-  onViewChange(handler: () => void): void;
-  offViewChange(handler: () => void): void;
-  /**
-   * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
-   * controller. The controller subscribes to pointer events on the returned
-   * driver to wire handle drags (vertex / midpoint / translate / rotate).
-   */
-  createEditPointerDriver(): EditPointerDriver;
-  /**
-   * Release all adapter-owned map resources. Adapters must not be used after
-   * destruction.
-   */
-  destroy(): void;
-}
-//#endregion
 //#region src/base-map-adapter.d.ts
-interface FeatureOps {
-  adds: Feature[];
-  updates: Feature[];
-  /** Features whose id was absent from the incoming set. */
-  removes?: Feature[];
-  full: Feature[];
-  replace?: boolean;
-}
 type NormalizedEventHandler = (lonLat: Position, pixel: PixelCoordinate, originalEvent: unknown) => void;
 interface NativeEventEntry<TEventToken> {
   type: string;
@@ -252,10 +12,8 @@ interface NativeEventEntry<TEventToken> {
  * Abstract base class shared by all `MapAdapter` implementations.
  *
  * Owns shared bookkeeping (layer registry, feature cache, event-token
- * tracking) and orchestrates the public methods over a small
- * protected primitive surface that subclasses implement. See
- * `docs/adr/0001-map-adapter-base-class.md` for the rationale, in particular
- * around the `applyFeatureOps` primitive shape.
+ * tracking) and orchestrates the public methods over a small protected
+ * grouped desired-state primitive that subclasses implement.
  */
 declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> implements MapAdapter {
   protected layers: Map<string, TLayerHandle>;
@@ -263,6 +21,9 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
   protected viewChangeTokens: Map<() => void, TViewToken>;
   protected featureCache: Map<string, Feature<import("geojson").Geometry, import("geojson").GeoJsonProperties>[]>;
   protected featuresChangedListeners: Map<string, Set<(features: Feature[]) => void>>;
+  protected iconResources: Map<string, IconResource>;
+  private featureGroupState;
+  private layerIconResourceIds;
   private layerCounter;
   private destroyed;
   protected nextLayerId(): LayerId;
@@ -270,12 +31,9 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
     style?: StyleOptions;
   }): LayerId;
   removeLayer(layerId: LayerId): void;
-  setLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
-  updateLayerFeatures(layerId: LayerId, features: readonly Feature[]): void;
-  removeFeatures(layerId: LayerId, ids: readonly string[]): void;
+  setLayerFeatureGroups(layerId: LayerId, groups: readonly FeatureGroup[]): void;
   abstract onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
   abstract createEditPointerDriver(): EditPointerDriver;
-  clearLayer(layerId: LayerId): void;
   on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
   off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
   onViewChange(handler: () => void): void;
@@ -284,9 +42,15 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
   protected emitLayerFeaturesChanged(layerId: LayerId, features: Feature[]): void;
   protected onLayerFeaturesChanged(layerId: LayerId, listener: (features: Feature[]) => void): () => void;
   protected destroyEngineResources(): void;
+  protected applyIconResources(resources: readonly IconResource[]): void;
+  protected getIconResource(id: string): IconResource | undefined;
+  protected getFeatureGroupOrder(layerId: LayerId, featureId: string | number | undefined): number | undefined;
+  protected removeIconResource(id: string): void;
+  private pruneIconResources;
   protected abstract createLayer(layerId: LayerId, style?: StyleOptions): TLayerHandle;
   protected abstract destroyLayer(handle: TLayerHandle): void;
-  protected abstract applyFeatureOps(layerId: LayerId, ops: FeatureOps): void;
+  /** Apply one validated, complete grouped desired state. */
+  protected abstract applyFeatureGroups(layerId: LayerId, groups: readonly FeatureGroup[]): void;
   protected abstract attachNativeEvent(type: "click" | "pointermove" | "dblclick", onEvent: NormalizedEventHandler): NativeEventEntry<TEventToken>;
   protected abstract detachNativeEvent(entry: NativeEventEntry<TEventToken>): void;
   protected abstract attachViewChange(handler: () => void): TViewToken;
@@ -306,9 +70,17 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
   abstract setDoubleClickZoomEnabled(enabled: boolean): void;
   abstract getResolution(): number | undefined;
   abstract getZoom(): number | undefined;
+  /**
+   * Default for engines/views that don't rotate (Leaflet). Rotating engines
+   * (MapLibre, OpenLayers) override this.
+   */
+  getBearing(): number;
+  getLayerFeatures(layerId: LayerId): readonly Feature[];
 }
 //#endregion
 //#region src/pick-utils.d.ts
+type PickPointerType = "mouse" | "pen" | "touch";
+declare function pickPointerType(originalEvent: unknown): PickPointerType;
 declare function pickHitTolerance(originalEvent: unknown): number;
 declare function tryControlMeasureIdFromFeature(feature: Feature): string | null;
 /**
@@ -319,6 +91,126 @@ declare function tryControlMeasureIdFromFeature(feature: Feature): string | null
  */
 declare function bindAbortable(signal: AbortSignal | undefined, attach: () => () => void): () => void;
 //#endregion
+//#region src/pick-candidates.d.ts
+interface ScreenBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+interface RotatedScreenBounds {
+  center: PixelCoordinate;
+  halfWidth: number;
+  halfHeight: number;
+  angle: number;
+}
+type LabelExtent = ScreenBounds | RotatedScreenBounds;
+interface ResolvedPickPresentation {
+  stroke?: {
+    color?: string;
+    width?: number;
+    dash?: readonly number[];
+  };
+  fill?: {
+    color?: string;
+    pattern?: string;
+    opacity: number;
+  };
+  point?: {
+    fillColor?: string;
+    radius?: number;
+  };
+  text?: TextStyleOptions;
+}
+type PickCandidateHitKind = "native" | "point" | "line" | "polygon-boundary" | "polygon-interior" | "icon" | "label";
+interface PickCandidateHit {
+  kind: PickCandidateHitKind;
+  /** CSS-pixel distance to the visible mark, or null when only the engine knows the hit. */
+  distance: number | null;
+}
+/**
+ * Engine-neutral description of one rendered part eligible at a pointer location.
+ * This is deliberately richer than PickEvent but remains adapter-author plumbing:
+ * ordered candidates are not exposed by the public picking event.
+ */
+interface PickCandidate {
+  feature: Feature;
+  graphicId: string | null;
+  renderedPartId: string | number | null;
+  hit: PickCandidateHit;
+  viewport: ScreenBounds;
+  presentation: ResolvedPickPresentation;
+  visualOrder: number;
+  /** Lower values mean a visually higher atomic feature group. */
+  featureGroupOrder?: number;
+  iconFootprint?: readonly PixelCoordinate[];
+  labelExtent?: LabelExtent;
+}
+/** A rendered part supplied by an adapter or TacticalDraw for shared evaluation. */
+interface PickCandidateInput {
+  feature: Feature;
+  /**
+   * Lower values mean visually topmost. Suppliers must normalize their
+   * native ordering to topmost-first before calling into evaluation.
+   */
+  visualOrder: number;
+  /**
+   * Authoritative bottom-to-top group order normalized to lower = visually
+   * higher. Unlike `visualOrder`, native engine query order cannot override it.
+   */
+  featureGroupOrder?: number;
+  /** The engine already reported this part as hit; retained as a fallback for engine-only marks. */
+  nativeHit?: boolean;
+  icon?: IconResource;
+  labelExtent?: LabelExtent;
+  presentation?: ResolvedPickPresentation;
+  layerStyle?: StyleOptions;
+}
+/**
+ * The `visualOrder` for the feature at `index` of a render-ordered
+ * (bottom-first) list of `total` features: reversing the index makes the
+ * topmost-rendered feature the lowest, and therefore winning, order.
+ */
+declare function renderOrderToVisualOrder(index: number, total: number): number;
+interface MergedPickFeature {
+  feature: Feature;
+  visualOrder: number;
+  nativeHit: boolean;
+}
+/**
+ * Preserve native visual ordering/hit evidence while keeping cached source
+ * geometry authoritative. Native polygon geometry may be tile-clipped and
+ * therefore contain artificial edges that are not part of the graphic.
+ *
+ * Normalizes to the shared `visualOrder` contract (lower = visually
+ * topmost): native hits already arrive topmost-first from the engines and
+ * keep that order at the front. Cached-only features (not among the native
+ * hits) are appended after them, in reverse cache order — cache arrays are
+ * render order (bottom-first), so reversing yields topmost-first — with
+ * `visualOrder` numbering continuing on from the native section.
+ */
+declare function mergeNativeAndCachedPickFeatures(nativeFeatures: readonly Feature[], cachedFeatures: readonly Feature[]): MergedPickFeature[];
+interface PickEvaluationContext {
+  pixel: PixelCoordinate;
+  tolerance: number;
+  pointerType?: PickPointerType;
+  toPixel: (position: Position) => PixelCoordinate | null;
+  viewport: ScreenBounds;
+  bearing?: number;
+}
+/**
+ * Evaluate every relevant rendered part in screen space, then return the
+ * primary candidate under the visible-intent ranking policy: direct visible
+ * marks (strokes, points, icons, labels) outrank visibly filled interiors,
+ * which outrank inferred outline-only reach; competing direct marks rank by
+ * screen-space distance; visual topmost order is only the final tie-break.
+ * See `rankPickCandidates` for the full ordered list — that ordering stays
+ * internal adapter-author plumbing; the public pick event exposes only this
+ * primary candidate.
+ */
+declare function evaluatePickCandidates(inputs: readonly PickCandidateInput[], context: PickEvaluationContext): PickCandidate | null;
+declare function resolvePickPresentation(feature: Feature, layerStyle?: StyleOptions): ResolvedPickPresentation;
+//#endregion
 //#region src/feature-style.d.ts
 /**
  * Coerce a raw `properties.style` value into a `HandleStyle` for the
@@ -326,6 +218,61 @@ declare function bindAbortable(signal: AbortSignal | undefined, attach: () => ()
  * when missing or shaped wrong so callers fall through to the layer style.
  */
 declare function coerceHandleStyle(raw: unknown): HandleStyle | undefined;
+/** Default lower edge of the ground-anchored label clamp band (ADR-0028). */
+declare const DEFAULT_TEXT_SIZE_MIN_PIXELS = 8;
+/** Default upper edge of the ground-anchored label clamp band (ADR-0028). */
+declare const DEFAULT_TEXT_SIZE_MAX_PIXELS = 24;
+/**
+ * Rendered pixel size of a ground-anchored label (ADR-0028):
+ * `textSizeMeters / resolution`, clamped to the layer's text-style band.
+ * Within the band the text scales with its graphic; past either edge it pins
+ * to the bound, so zooming out never yields unreadable smudges and zooming in
+ * never yields screen-covering text. Shared by the adapters that resolve text
+ * size in code (OpenLayers, Leaflet); the MapLibre adapter evaluates the same
+ * clamp inside its per-zoom-stop style expression.
+ */
+declare function resolveGroundTextSizePixels(textSizeMeters: number, resolution: number, text?: Pick<TextStyleOptions, "textSizeMinPixels" | "textSizeMaxPixels">): number;
+/**
+ * The size properties a Text graphic's feature carries (see `text.ts` /
+ * `FeaturePartProps`). Mutually exclusive size anchors: `textSizePixels`
+ * (screen-anchored) or `textSizeMeters` (ground-anchored). `textMaxSizePixels`
+ * is the ADR-0037 hide threshold; the min/max band fields are the amplifier
+ * -label clamp bounds, applied only when no max-size threshold is present.
+ */
+interface TextSizeProps {
+  textSizeMeters?: number;
+  textSizePixels?: number;
+  textMaxSizePixels?: number;
+  textSizeMinPixels?: number;
+  textSizeMaxPixels?: number;
+}
+/**
+ * Resolve a Text graphic's on-screen size in pixels, honoring the
+ * `textMaxSizePixels` hide threshold (ADR-0037). Returns `null` — the "hidden"
+ * signal — when the graphic should render no text this frame; adapters emit no
+ * text style for a `null`. Distinct from [[resolveGroundTextSizePixels]], which
+ * keeps the 8–24 px clamp band for amplifier labels: this helper is the Text
+ * graphic's own sizing rule.
+ *
+ *  - screen-anchored (`textSizePixels`): the fixed pixel size, never scaled or
+ *    hidden by zoom.
+ *  - ground-anchored (`textSizeMeters`) with a `textMaxSizePixels` threshold:
+ *    *unclamped* `meters / resolution` (the 8–24 band does NOT apply), hidden
+ *    (`null`) once that exceeds the threshold — text shrinks freely zooming out
+ *    and vanishes rather than clamps zooming in.
+ *  - ground-anchored without a threshold: falls back to the clamped band.
+ *  - no usable size or resolution: `null`.
+ */
+declare function resolveTextSizePixels(props: TextSizeProps, resolution: number): number | null;
+/** Fallback halo color when a `textHalo` feature carries no `textHaloColor`. */
+declare const TEXT_HALO_COLOR = "#ffffff";
+/**
+ * Outward depth (px) of a `textHalo` halo from the glyph edge, scaled to font
+ * size. This is the halo's *outward* reach, not a stroke width — a canvas
+ * stroke straddles the glyph edge (half in, half out), so a caller drawing
+ * one must double this value to get the same visible depth.
+ */
+declare function resolveTextHaloWidth(textSizePixels?: number): number;
 //#endregion
 //#region src/gestures/hit-test.d.ts
 type ToPixel = (lonLat: Position) => PixelCoordinate | null;
@@ -340,7 +287,14 @@ type ToPixel = (lonLat: Position) => PixelCoordinate | null;
  *
  * Returns the first matching feature in iteration order, or null.
  */
-declare function hitTestFeature(pixel: PixelCoordinate, features: Feature[], hitTolerance: number, toPixel: ToPixel): Feature | null;
+declare function hitTestFeature(pixel: PixelCoordinate, features: readonly Feature[], hitTolerance: number, toPixel: ToPixel): Feature | null;
+/**
+ * Test a rendered icon-backed Point feature against its actual pixel footprint.
+ * The feature carries the adapter-neutral `iconScale` / `iconRotation` values
+ * emitted by TacticalDraw; `resource.anchor` is the placement anchor within the
+ * unscaled SVG viewport. A positive tolerance pads all four sides.
+ */
+declare function hitTestIconFeature(pixel: PixelCoordinate, feature: Feature, resource: IconResource, hitTolerance: number, toPixel: ToPixel, bearing?: number): boolean;
 //#endregion
 //#region src/gestures/hit-tolerance.d.ts
 declare const TOUCH_HIT_TOLERANCE_PX = 22;
@@ -375,6 +329,104 @@ declare class PointerCallbackHub {
   clear(): void;
 }
 //#endregion
+//#region src/point-symbol.d.ts
+type PointSymbolSize = {
+  value: number;
+  unit: "pixels";
+} | {
+  value: number;
+  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. */
+  direction?: number;
+}
+interface PointSymbolColors {
+  fill?: string;
+  frame?: string;
+  icon?: string;
+  info?: string;
+  outline?: string;
+}
+interface PointSymbolStyle {
+  colors?: PointSymbolColors;
+  monoColor?: string;
+  opacity?: number;
+  outlineWidth?: number;
+  fill?: boolean;
+  frame?: boolean;
+  icon?: boolean;
+}
+interface PointSymbol {
+  id: string;
+  kind: "point-symbol";
+  sidc: string;
+  position: Position;
+  /** Normalized radians clockwise from geographic north. */
+  rotation: number;
+  /** Milsymbol's octagon-based L dimension. */
+  size: PointSymbolSize;
+  textAmplifiers?: TextAmplifiers;
+  graphicModifiers?: PointSymbolGraphicModifiers;
+  style?: PointSymbolStyle;
+  rendererOptions?: {
+    milsymbol?: Record<string, unknown>;
+  };
+  properties?: Record<string, unknown>;
+  schemaVersion?: 1;
+}
+interface PointSymbolAnchor {
+  x: number;
+  y: number;
+}
+/** Canonical-size, renderer-neutral point-symbol output. */
+interface PointSymbolRender {
+  /** Content-derived identity for adapter-wide native-resource reuse. */
+  resourceId: string;
+  svg: string;
+  /** Renderer-space octagon size used to interpret persisted symbol size. */
+  octagonSize: number;
+  width: number;
+  height: number;
+  anchor: PointSymbolAnchor;
+  octagonAnchor: PointSymbolAnchor;
+  valid: boolean;
+  validation?: unknown;
+}
+interface PointSymbolCapability {
+  readonly defaultSize: PointSymbolSize;
+  readonly defaultRotation: number;
+  render(symbol: PointSymbol): PointSymbolRender;
+  invalidate(): void;
+  /**
+   * Monotonic counter that increments on each `invalidate()` call. Consumers
+   * (e.g. a render cache keyed on graphic snapshot identity) may read this to
+   * detect that previously rendered point-symbol output is stale even though
+   * the graphic snapshot itself is unchanged. Optional — when absent,
+   * invalidation cannot be detected by cache layers, so they must not attempt
+   * to key on it.
+   */
+  readonly generation?: number;
+}
+declare function isPointSymbol(graphic: unknown): graphic is PointSymbol;
+declare function clonePointSymbol(symbol: PointSymbol): PointSymbol;
+/**
+ * Replace a point-symbol size value as a user-driven resize. Ground-size display
+ * bounds scale with the value so they continue to constrain zoom changes rather
+ * than preventing the resize itself.
+ */
+declare function resizePointSymbolSize(size: PointSymbolSize, value: number): PointSymbolSize;
+//#endregion
+//#region src/graphic.d.ts
+type Graphic = ControlMeasure | PointSymbol;
+type GraphicRender = ControlMeasureRender | PointSymbolRender;
+interface GraphicSnapshot<G extends Graphic = Graphic> {
+  graphic: G;
+  render: G extends PointSymbol ? PointSymbolRender : ControlMeasureRender;
+}
+//#endregion
 //#region src/tactical-draw/abort.d.ts
 /**
  * AbortPlumbing for the TacticalDraw façade.
@@ -425,6 +477,7 @@ interface CombinedAbort {
 declare function combineWithHostSignal(hostSignal?: AbortSignal): CombinedAbort;
 //#endregion
 //#region src/tactical-draw/measure-options.d.ts
+declare const DEFAULT_LABEL_SIZE_PIXELS = 14;
 /**
  * Where a control measure's size is anchored (ADR-0020). `ground` (the
  * default) means a meter size fixed to the terrain — static, never re-rendered
@@ -466,9 +519,20 @@ interface InteractionStyle {
   guide?: GuideStyle;
   vertexHandle?: HandleStyle;
   midpointHandle?: HandleStyle;
+  /** Visible grab target for a draggable rendered text label. */
+  labelHandle?: HandleStyle;
   scaleHandle?: HandleStyle;
   rotateHandle?: HandleStyle;
   boxOutline?: GuideStyle;
+  /**
+   * Line style for the passive, non-interactive selection highlight rendered
+   * by {@link TacticalDraw.setHighlightedGraphics}. A dashed, muted variant of
+   * `boxOutline` so a locked/highlighted selection reads as visually distinct
+   * from an active edit's oriented transform box. Delivered per-feature via
+   * `properties.style` on the highlight outline `LineString`, resolved through
+   * the same built-in → façade → per-call slot system as every other field.
+   */
+  highlightOutline?: GuideStyle;
   /**
    * Pixel padding added on every side of the fitted transform box
    * (`fitTransformBox`, ADR-0017) so the box doesn't tightly hug the rendered
@@ -483,12 +547,68 @@ interface InteractionStyle {
  * `reshape` renders vertex/midpoint handles; `transform` renders the oriented
  * selection box (4 corner scale handles + a rotate grip + drag-anywhere
  * body translate) via `transform-box.ts`. The two can be combined freely —
- * single-measure edits show both by default. `delete` is an explicit
+ * single-measure edits show both by default. `labeldrag` enables dragging
+ * rendered text labels. `delete` is an explicit
  * destructive mode: it renders the vertex handles (so they can be tapped to
  * remove) but no midpoints or box, and the edit controller deletes the tapped
  * vertex instead of dragging it.
  */
-type EditMode = "reshape" | "transform" | "delete";
+type EditMode = "reshape" | "transform" | "labeldrag" | "delete";
+//#endregion
+//#region src/tactical-draw/session-events.d.ts
+/** A gesture's phase within a stream of {@link TransientChangeEvent}s. */
+type TransientPhase = "start" | "move" | "end";
+/**
+ * An in-flight mutation of a graphic's working geometry during a gesture —
+ * streamed continuously while the gesture runs (`EditSession.onTransientChange`
+ * / `DrawSession.onTransientChange`), distinct from the once-per-completed-
+ * gesture `onChange`. Hosts use it for live feedback, e.g. a radius readout
+ * while dragging a circle handle.
+ */
+interface TransientChangeEvent {
+  /** Gesture phase. `end` fires exactly once per started gesture — on commit AND on cancel/abort. */
+  readonly phase: TransientPhase;
+  /** The full working control points at this instant (lon/lat). Fresh array per emission. */
+  readonly points: readonly Position[];
+  /**
+   * Index of the live point in `points` — the dragged vertex in edit, the
+   * rubber-band point in draw — or `null` when the whole geometry moves at
+   * once (box translate / rotate / scale).
+   */
+  readonly pointIndex: number | null;
+}
+/**
+ * The reason a session (`TransformSession`, `EditSession`, or `DrawSession`)
+ * settled, delivered to that session's `onSettled` handler (#191 / #194 /
+ * #197). `"close"` covers every commit path of the owning session —
+ * `TransformSession.close()` / `EditSession.close()` / `DrawSession.commit()`,
+ * a click-away close, a gesture commit (dblclick, a second click/tap on the
+ * finishing vertex, a click on another graphics-layer measure), or
+ * `TransformSession.setGraphics([])`. `"error"` is the commit-time snapshot
+ * build throwing (the outer promise rejects with that error, not a
+ * `TacticalDrawAbortError`). The remaining values replay
+ * `TacticalDrawAbortError.reason` verbatim: `"escape"`, `"signal"`,
+ * `"session"` (`session.abort()` / `event.abort()`), `"preempted"`,
+ * `"destroyed"`, and `"removed"` (edit / transform only — a measure dropped
+ * from `td.render()`'s measure set).
+ */
+type SettleReason = "close" | "error" | TacticalDrawAbortReason;
+//#endregion
+//#region src/tactical-draw/session-history.d.ts
+type SessionChangeSource = "gesture" | "undo" | "redo" | "programmatic";
+interface SessionHistoryState {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel?: string;
+  readonly redoLabel?: string;
+}
+interface SessionHistory {
+  /** Current availability and optional labels. Each session retains at most 100 completed steps. */
+  readonly state: SessionHistoryState;
+  undo(): boolean;
+  redo(): boolean;
+  subscribe(listener: (state: SessionHistoryState) => void): () => void;
+}
 //#endregion
 //#region src/tactical-draw/edit-session.d.ts
 /**
@@ -497,17 +617,39 @@ type EditMode = "reshape" | "transform" | "delete";
  *
  * `measure` is the immutable edit-start input. `controlPoints` is live working
  * state. After the session settles (`close` / `abort`), every method is a
- * silent no-op.
+ * silent no-op (except [[onSettled]] — late registration still delivers,
+ * asynchronously).
  */
 interface EditSession {
+  /** Undo/redo for completed mutations within this live session. */
+  readonly history: SessionHistory;
   /** Immutable edit-start input. */
-  readonly measure: ControlMeasure;
+  readonly graphic: ControlMeasure;
+  /**
+   * Live complete working graphic. Copy on read. `properties` (host-owned
+   * metadata, e.g. `standardIdentity`/`colorMode`) is session-owned like every
+   * other working field: it starts at the edit-start value, is replaced
+   * wholesale by [[updateGraphic]], survives every subsequent gesture/setter
+   * call and in-session undo/redo, and is rolled back by `event.reject()`
+   * (issue #354). Absent when the edit-start measure carried none and
+   * [[updateGraphic]] has not set any since.
+   */
+  readonly workingGraphic: ControlMeasure;
   /** Live working state. Copy on read. */
   readonly controlPoints: readonly Position[];
   /** Live working options. Copy on read. */
   readonly options: ControlMeasure["options"];
   /** Live working style. Copy on read. */
   readonly style: ControlMeasureStyle | undefined;
+  /**
+   * Live working text amplifiers (MIL-STD-2525E Appendix L Table L-II). Copy
+   * on read. `undefined` when the edit-start measure carried none and none
+   * have been set since. Keys are stored as given — canonicalisation to
+   * doctrinal field codes happens in the core render seam, not here.
+   */
+  readonly textAmplifiers: TextAmplifiers | undefined;
+  /** Live user-adjusted anchors for individually rendered text amplifiers. */
+  readonly amplifierPlacements: AmplifierPlacements | undefined;
   /** `true` after the first working-copy mutation; back to `false` within tolerance. */
   readonly dirty: boolean;
   readonly modes: readonly EditMode[];
@@ -518,12 +660,12 @@ interface EditSession {
    */
   readonly sizeAnchor: SizeAnchor;
   /**
-   * Commit: returns the `ControlMeasureSnapshot` of the current working state
+   * Commit: returns the `GraphicSnapshot<ControlMeasure>` of the current working state
    * and resolves the outer `edit` promise with the same value (the same
    * reference — no double-bake of ground-anchored sizes). Returns `undefined`
    * after the session has settled (idempotent no-op).
    */
-  close(): ControlMeasureSnapshot | undefined;
+  close(): GraphicSnapshot<ControlMeasure> | undefined;
   /** Reject the outer `edit` promise with reason `"session"`. */
   abort(): void;
   /**
@@ -534,6 +676,8 @@ interface EditSession {
    * is rejected with `TypeError`.
    */
   setModes(modes: readonly EditMode[]): void;
+  /** Atomically replace the live working graphic while preserving id and kind. */
+  updateGraphic(updater: (graphic: ControlMeasure) => ControlMeasure): void;
   /** Shallow-merge per-measure generator options into the live working copy. */
   setOptions(partial: ControlMeasure["options"]): void;
   /**
@@ -541,10 +685,36 @@ interface EditSession {
    * and on `close()`. A no-op for measures with no pixel-denominated size. The
    * in-flight preview is unaffected (it renders from the working options), so a
    * screen-locked symbol stays screen-locked until commit.
-   */
-  setSizeAnchor(anchor: SizeAnchor): void;
+   *
+   * `options` shallow-merges a size-option patch in the *same* mutation, as
+   * [[setOptions]] would. Changing a measure's size mode means moving its value
+   * between the pixel and meter halves of a size pair *and* re-anchoring, and
+   * the halves are only meaningful together: options carrying a pixel size
+   * under a `"ground"` anchor bake that size away on commit, so a host that
+   * emitted the two as separate mutations would leave an undo step parked on a
+   * state whose committed size mode contradicts its own options. Passed here
+   * they are one change event and one history entry, which undo cannot land
+   * inside.
+   */
+  setSizeAnchor(anchor: SizeAnchor, options?: ControlMeasure["options"]): void;
   /** Shallow-merge per-measure style into the live working copy. */
   setStyle(partial: ControlMeasureStyle): void;
+  /**
+   * Shallow-merge into the live working text amplifiers. A value of
+   * `undefined` or an empty/whitespace-only string deletes that key; the
+   * working record collapses back to `undefined` once it holds no keys. A
+   * silent no-op after the session has settled (like [[setOptions]]).
+   */
+  setTextAmplifiers(partial: Record<string, string | undefined>): void;
+  /**
+   * Merge field-keyed label overrides (position and/or rotation). The merge is
+   * **field-wise per key**: a bare `Position` value means `{ position }`;
+   * fields absent from the incoming value (e.g. `rotation` when only
+   * `position` is supplied) are preserved from the existing entry; an
+   * explicit `undefined` value deletes the key entirely — a full reset to the
+   * doctrinal placement (both position and rotation).
+   */
+  setAmplifierPlacements(partial: Record<string, AmplifierPlacement | undefined>): void;
   /**
    * Subscribe to working-copy changes. The listener receives an
    * [[EditChangeEvent]] for each completed gesture (drag end, insert/delete
@@ -557,6 +727,69 @@ interface EditSession {
    * have run.
    */
   onChange(listener: (event: EditChangeEvent) => void): () => void;
+  /**
+   * Subscribe to the committed snapshot — the single delivery channel for the
+   * `GraphicSnapshot<ControlMeasure>` this session ever commits (#197, mirroring
+   * `TransformSession.onCommit` #191). Fires exactly once, synchronously from
+   * within the [[close]] call that produced it (`session.close()`,
+   * `event.close()` from [[onChange]], a click-away close, or a click on
+   * another graphics-layer measure), with the same reference [[close]]
+   * returns and the outer `edit` promise resolves with. Never fires on abort.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onCommit(handler: (snapshot: GraphicSnapshot<ControlMeasure>) => void): () => void;
+  /**
+   * Subscribe to the session's settlement — the lifecycle complement of
+   * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
+   * the session is *over* and why (#197, mirroring
+   * `TransformSession.onSettled` #194). Fires exactly once, when the session
+   * settles by any path, commit or abort, with a `SettleReason`.
+   *
+   * - On the commit path it fires **after** [[onCommit]]'s emission, so a
+   *   listener that clears selection state observes a document that already
+   *   contains the committed snapshot.
+   * - On every path it fires **after** the facade has already cleared
+   *   `td.activeSession` — so fold-then-render works from inside the handler.
+   * - `reason` distinguishes commit from abort but is deliberately coarse —
+   *   no payload; the snapshot was already delivered through [[onCommit]].
+   *
+   * Registering after the session has already settled is **not** a no-op
+   * (unlike [[onChange]] / [[onCommit]]): the handler is invoked
+   * asynchronously (on a microtask) exactly once with the settle reason;
+   * unsubscribing before that microtask runs cancels the delivery.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]] / [[onCommit]]. Returns an unsubscribe function.
+   */
+  onSettled(handler: (reason: SettleReason) => void): () => void;
+  /**
+   * Subscribe to the continuous stream of in-flight geometry mutations —
+   * vertex/midpoint drags and box scale/rotate/translate gestures — fired
+   * throughout the gesture rather than once at its end (contrast
+   * [[onChange]]). `start` fires at gesture begin, `move` on every pointer
+   * tick, and `end` fires exactly once when the gesture finishes by any
+   * path: commit, a click-slop no-op (a box body click that never becomes a
+   * drag), or session abort/teardown mid-drag. `end` fires **before** the
+   * gesture's [[onChange]] emission (and, on the commit path, before
+   * [[onCommit]]/[[onSettled]] too), so a listener observing both channels
+   * sees the transient stream close first.
+   *
+   * Label-placement drags (`labeldrag` mode) do not fire this — they move
+   * amplifier placements, not control points.
+   *
+   * Listener exceptions are collected; after every listener has run, they
+   * are rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onTransientChange(listener: (event: TransientChangeEvent) => void): () => void;
 }
 /**
  * Delivered to `EditSession.onChange` listeners once per completed gesture.
@@ -567,10 +800,12 @@ interface EditSession {
  * observe partial state. See PRD #40 user-stories 23–24.
  */
 interface EditChangeEvent {
+  /** How this working-copy transition was initiated. */
+  readonly source: SessionChangeSource;
   /** Working state after the completed gesture. */
-  readonly measure: ControlMeasureSnapshot;
+  readonly graphic: GraphicSnapshot<ControlMeasure>;
   /** State immediately before this gesture. */
-  readonly previous: ControlMeasureSnapshot;
+  readonly previous: GraphicSnapshot<ControlMeasure>;
   /** The session the event belongs to. */
   readonly session: EditSession;
   /**
@@ -585,95 +820,157 @@ interface EditChangeEvent {
   abort(): void;
 }
 //#endregion
+//#region src/tactical-draw/graphic-edit-session.d.ts
+interface GraphicEditChangeEvent<G extends Graphic = Graphic> {
+  readonly source: SessionChangeSource;
+  readonly graphic: GraphicSnapshot<G>;
+  readonly previous: GraphicSnapshot<G>;
+  readonly session: GraphicEditSession<G>;
+  reject(): void;
+  close(): void;
+  abort(): void;
+}
+/** Common selection/editing contract shared by control measures and point symbols. */
+interface GraphicEditSession<G extends Graphic = Graphic> {
+  readonly history: SessionHistory;
+  /** Immutable edit-start input. */
+  readonly graphic: G;
+  /** Live working graphic. Copy on read. */
+  readonly workingGraphic: G;
+  readonly dirty: boolean;
+  readonly modes: readonly EditMode[];
+  close(): GraphicSnapshot<G> | undefined;
+  abort(): void;
+  setModes(modes: readonly EditMode[]): void;
+  /** Atomically replace any part of the live working graphic. */
+  updateGraphic(updater: (graphic: G) => G): void;
+  onChange(listener: (event: GraphicEditChangeEvent<G>) => void): () => void;
+  onCommit(handler: (snapshot: GraphicSnapshot<G>) => void): () => void;
+  onSettled(handler: (reason: SettleReason) => void): () => void;
+}
+//#endregion
 //#region src/tactical-draw/transform-session.d.ts
 /**
- * Surface delivered via `td.editMany(measures, opts).onSession` and
+ * Surface delivered via `td.editMany(graphics, opts).onSession` and
  * synchronously available from `td.activeTransformSession` while the group
  * transform is live. The group sibling of `EditSession` (`edit-session.ts`):
  * no reshape, no per-measure `setOptions`/`setStyle` — only the shared
  * transform box's corner-scale / rotate / body-translate gestures, applied to
  * every member at once. See the Phase 3 ("Multi-select") slice of ADR-0017.
  *
- * The member set is mutable via [[setMembers]] (#187): members can join or
- * leave a live session without a session boundary. Because membership changes
- * over the session's lifetime, snapshot arrays are keyed by **measure id**, not
- * by index — a snapshot's identity is `snapshot.measure.id`. `measures` is a
- * live view of the current members' join-time inputs; a `TransformChangeEvent`'s
- * arrays are index-aligned with `session.measures` *as of that emission*. After
- * the session settles (`close` / `abort` / an emptying `setMembers`), every
- * method is a silent no-op.
+ * Typed on `Graphic` (ADR-0032): a member is either a `ControlMeasure` or a
+ * point symbol, and the two coexist in one session. Hosts narrow with
+ * `isPointSymbol`. `controlPointsFor` is a control-measure accessor and returns
+ * `undefined` for a point-symbol id.
+ *
+ * The member set is mutable via [[setGraphics]] (#187): members can join or
+ * leave a live session without a session boundary — point symbols exactly like
+ * measures. Because membership changes over the session's lifetime, snapshot
+ * arrays are keyed by **graphic id**, not by index — a snapshot's identity is
+ * `snapshot.graphic.id`. `graphics` is a live view of the current members'
+ * join-time inputs; a `TransformChangeEvent`'s arrays are index-aligned with
+ * `session.graphics` *as of that emission*. After the session settles (`close`
+ * / `abort` / an emptying `setGraphics`), every method is a silent no-op
+ * (except [[onSettled]] — late registration still delivers, asynchronously).
  */
 interface TransformSession {
+  /** Undo/redo for completed gestures within the current membership baseline. */
+  readonly history: SessionHistory;
   /**
-   * Live view of the current members' join-time input measures — a fresh array
-   * on each read, in current membership order. Grows/shrinks as [[setMembers]]
+   * Live view of the current members' join-time input graphics — a fresh array
+   * on each read, in current membership order. Grows/shrinks as [[setGraphics]]
    * adds or removes members. Not stable across membership changes: key
-   * snapshots by `snapshot.measure.id` rather than relying on index alignment.
+   * snapshots by `snapshot.graphic.id` rather than relying on index alignment.
+   */
+  readonly graphics: readonly Graphic[];
+  /**
+   * Live view of the current members' working graphics — a fresh array on each
+   * read, in current membership order, reflecting every gesture applied so far.
+   * Measures carry their working control points (and any transform-frozen
+   * options); point symbols carry their working position, size value, and
+   * rotation. Copy on read.
    */
-  readonly measures: readonly ControlMeasure[];
+  readonly workingGraphics: readonly Graphic[];
   /**
-   * Live working control points for the member whose id is `measureId`, or
-   * `undefined` when no member carries that id. Copy on read.
+   * Live working control points for the control-measure member whose id is
+   * `graphicId`, or `undefined` when no such member carries that id — including
+   * when `graphicId` names a point symbol (which has no control points; read
+   * its working `position` from [[workingGraphics]] instead). Copy on read.
    */
-  controlPointsFor(measureId: string): readonly Position[] | undefined;
-  /** `true` when any member's working points differ from its edit-start input beyond tolerance. */
+  controlPointsFor(graphicId: string): readonly Position[] | undefined;
+  /** `true` when any member's working state differs from its edit-start input beyond tolerance. */
   readonly dirty: boolean;
   /**
-   * Live size anchor, applied group-wide (ADR-0020). `"ground"` bakes each
-   * member's pixel size to meters on commit; `"screen"` keeps it zoom-aware.
+   * Live size anchor, applied group-wide to the **control-measure** members
+   * only (ADR-0020). `"ground"` bakes each measure's pixel size to meters on
+   * commit; `"screen"` keeps it zoom-aware. A point symbol's persisted
+   * pixel/meter size is its own anchor and is never rewritten by this setting.
    * Initialised from `EditManyOptions.sizeAnchor` and mutated by [[setSizeAnchor]].
    */
   readonly sizeAnchor: SizeAnchor;
-  /** Switch the group's size anchor (ADR-0020). Takes effect on the next emitted snapshot and on `close()`. */
+  /**
+   * Switch the group's size anchor (ADR-0020) for its control-measure members.
+   * Takes effect on the next emitted snapshot and on `close()`. Point-symbol
+   * members are unaffected.
+   */
   setSizeAnchor(anchor: SizeAnchor): void;
   /**
    * Replace the member set in place — the primitive behind shift-click toggle,
    * marquee replace, and single-edit → group folding, without tearing the
-   * session down (#187). Members are matched to the current set by measure id:
+   * session down (#187). Members (measures and point symbols alike) are matched
+   * to the current set by graphic id:
    *
    * - **Retained** members (id in both the current and next sets) carry their
-   *   current working state forward; the passed measure object is ignored for
+   *   current working state forward; the passed graphic object is ignored for
    *   them. Their `dirty` baseline stays their original join-time input, so a
    *   session that has already moved things stays dirty across the call.
    * - **Removed** members (id in the current set, absent from the next) are
    *   committed at their current working state.
    * - **Added** members (id only in the next set) join at their passed input
-   *   state; if currently on the graphics layer they are lifted off it exactly
-   *   like initial members.
+   *   state and use their host-provided Graphic-stack slot when present.
    *
    * The transform box re-derives from the next member set at the session's
    * current box angle. Session-scoped state (`sizeAnchor`, box angle,
    * non-geometry dirty) is unchanged.
    *
+   * Calling this establishes a new session-history baseline: both undo and
+   * redo are cleared after retained members carry their working state
+   * forward. Membership changes and already-emitted exit snapshots are not
+   * undoable within the live session.
+   *
    * **Return value** — the committed exit snapshots of the members removed *by
-   * this call*, built exactly like [[close]]'s snapshots (pixel size baked to
-   * ground unless `sizeAnchor` is `"screen"`, then cloned and rendered); an
-   * empty array when nothing was removed. The outer `editMany` promise resolves
-   * with the snapshots of the members in the set **at close time only**.
-   * Removed members are NOT written back to the graphics layer by the
-   * controller — the host folds the returned snapshots into its document and
-   * calls `td.render()`, the same contract as [[close]]. A removed member's
-   * exit snapshot is also delivered through [[onCommit]] — the recommended
-   * channel, since it covers this return value and the close-time promise
-   * resolution through a single subscription. Returns `undefined` (a silent
-   * no-op) after the session has settled.
+   * this call*, built exactly like [[close]]'s snapshots (a measure's pixel
+   * size baked to ground unless `sizeAnchor` is `"screen"`, a point symbol's
+   * size left untouched, then cloned and rendered); an empty array when nothing
+   * was removed. The outer `editMany` promise resolves with the snapshots of
+   * the members in the set **at close time only**. Removed members are NOT
+   * retained in its Graphic-stack slot until the host acknowledges it by
+   * folding the returned snapshot into its document and calling `td.render()`,
+   * the same contract as [[close]]. A removed member's exit snapshot is also
+   * delivered through [[onCommit]] — the recommended channel, since it covers
+   * this return value and the close-time promise resolution through a single
+   * subscription.
+   * Returns `undefined` (a silent no-op) after the session has settled.
    *
-   * `setMembers([])` on a live session delegates to [[close]]: it commits every
+   * `setGraphics([])` on a live session delegates to [[close]]: it commits every
    * current member, resolves the promise with their snapshots, and returns that
-   * same array. Duplicate ids in `measures` throw `TypeError` synchronously,
-   * without mutating session state.
-   */
-  setMembers(measures: readonly ControlMeasure[]): ControlMeasureSnapshot[] | undefined;
-  /**
-   * Commit: returns the members' `ControlMeasureSnapshot[]` (the members in the
-   * set at close time) and resolves the outer `editMany` promise with the same
-   * value (the same reference — no double-bake of ground-anchored sizes). A
-   * member removed mid-session via [[setMembers]] is not included here; its exit
-   * snapshot was returned from that `setMembers` call (and delivered to
+   * same array. Duplicate ids in `graphics` throw `TypeError` synchronously,
+   * without mutating session state. A point-symbol member entering a session
+   * whose controller was created without a point-symbol capability throws
+   * `PointSymbolCapabilityRequiredError` synchronously, also without mutating
+   * session state.
+   */
+  setGraphics(graphics: readonly Graphic[]): GraphicSnapshot[] | undefined;
+  /**
+   * Commit: returns the members' `GraphicSnapshot[]` (the members in the set at
+   * close time) and resolves the outer `editMany` promise with the same value
+   * (the same reference — no double-bake of ground-anchored measure sizes). A
+   * member removed mid-session via [[setGraphics]] is not included here; its exit
+   * snapshot was returned from that `setGraphics` call (and delivered to
    * [[onCommit]] at that time). Returns `undefined` after the session has
    * settled (idempotent no-op).
    */
-  close(): ControlMeasureSnapshot[] | undefined;
+  close(): GraphicSnapshot[] | undefined;
   /** Reject the outer `editMany` promise with reason `"session"`. */
   abort(): void;
   /**
@@ -691,21 +988,22 @@ interface TransformSession {
   onChange(listener: (event: TransformChangeEvent) => void): () => void;
   /**
    * Subscribe to committed exit-snapshot batches — the single delivery channel
-   * for every `ControlMeasureSnapshot[]` this session ever commits (#191). Fires
+   * for every `GraphicSnapshot[]` this session ever commits (#191). Fires
    * exactly once per batch:
    *
-   * - The members [[setMembers]] removes, but only when that call actually
+   * - The members [[setGraphics]] removes, but only when that call actually
    *   removed at least one member.
-   * - The close-time members on any commit path: [[close]], `setMembers([])`,
+   * - The close-time members on any commit path: [[close]], `setGraphics([])`,
    *   a click-away close, or `TransformChangeEvent.close()`.
    *
-   * Never fires on an abort/reject path. Fires synchronously from within the
-   * `setMembers`/`close` call that produced the batch, before that call
+   * Never fires on an abort/reject path — pair it with [[onSettled]] to also
+   * observe abort settles. Fires synchronously from within the
+   * `setGraphics`/`close` call that produced the batch, before that call
    * returns, and the array delivered here is the same reference that call
    * returns (and, for the close batch, the same reference the `editMany`
    * promise resolves with). This is the recommended single fold path for exit
    * state — subscribe once in `onSession` and every committed snapshot, from
-   * either delivery site, arrives here exactly once; the `setMembers` return
+   * either delivery site, arrives here exactly once; the `setGraphics` return
    * value and the promise resolution are unchanged and remain valid for
    * backward compatibility.
    *
@@ -715,30 +1013,57 @@ interface TransformSession {
    * session has settled returns a no-op unsubscribe and the listener never
    * fires.
    */
-  onCommit(handler: (snapshots: ControlMeasureSnapshot[]) => void): () => void;
+  onCommit(handler: (snapshots: GraphicSnapshot[]) => void): () => void;
+  /**
+   * Subscribe to the session's settlement — the lifecycle complement of
+   * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
+   * the session is *over* and why (#194). Fires exactly once, when the
+   * session settles by any path, commit or abort, with a [[SettleReason]].
+   *
+   * - On commit paths it fires **after** the close batch's `onCommit`
+   *   emission, so a listener that clears selection state observes a document
+   *   that already contains the exit snapshots.
+   * - On every path it fires **after** the facade has already cleared its
+   *   slot — `td.activeTransformSession` is `null`, so fold-then-render works
+   *   from inside the handler.
+   * - `reason` distinguishes commit from abort but is deliberately coarse —
+   *   no payload; snapshots were already delivered through [[onCommit]].
+   *
+   * Registering after the session has already settled is **not** a no-op
+   * (unlike [[onChange]] / [[onCommit]]): the handler is invoked
+   * asynchronously (on a microtask) exactly once with the settle reason;
+   * unsubscribing before that microtask runs cancels the delivery.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]] / [[onCommit]]. Returns an unsubscribe function.
+   */
+  onSettled(handler: (reason: SettleReason) => void): () => void;
 }
 /**
  * Delivered to `TransformSession.onChange` listeners once per completed group
- * gesture. Both `measures` and `previous` are index-aligned with
- * `session.measures` *as of this emission*. Key by `measure.id` rather than
- * relying on index alignment across emissions. A `setMembers` call from within
+ * gesture. Both `graphics` and `previous` are index-aligned with
+ * `session.graphics` *as of this emission*. Key by `graphic.id` rather than
+ * relying on index alignment across emissions. A `setGraphics` call from within
  * a listener takes effect immediately and supersedes this emission's
  * `reject()` (the rollback baseline no longer matches the member set);
  * `close()` and `abort()` still apply, against the new membership. See
  * `EditChangeEvent` for the identical emission contract this mirrors.
  */
 interface TransformChangeEvent {
-  /** Working state after the completed gesture, index-aligned with `session.measures` as of this emission. */
-  readonly measures: ControlMeasureSnapshot[];
-  /** State immediately before this gesture, index-aligned with `session.measures` as of this emission. */
-  readonly previous: ControlMeasureSnapshot[];
+  /** How this working-copy transition was initiated. */
+  readonly source: SessionChangeSource;
+  /** Working state after the completed gesture, index-aligned with `session.graphics` as of this emission. */
+  readonly graphics: GraphicSnapshot[];
+  /** State immediately before this gesture, index-aligned with `session.graphics` as of this emission. */
+  readonly previous: GraphicSnapshot[];
   /** The session the event belongs to. */
   readonly session: TransformSession;
   /**
    * Roll every member's working preview back to `previous` after all
    * listeners have run. Multiple calls collapse to a single rollback.
    * Overridden by `close()` or `abort()` if either is also called during this
-   * emission, and dropped if a listener called `session.setMembers` (the
+   * emission, and dropped if a listener called `session.setGraphics` (the
    * rollback baseline no longer matches the member set).
    */
   reject(): void;
@@ -754,7 +1079,8 @@ interface TransformChangeEvent {
  * kinds. Also available from `td.activeSession` while the draw is live.
  *
  * After the draw has settled — either via `commit()` returning `true` or
- * `abort()` resolving — every method is a silent no-op.
+ * `abort()` resolving — every method is a silent no-op (except [[onSettled]]
+ * — late registration still delivers, asynchronously).
  */
 interface DrawSession {
   /** Live snapshot of the committed control points. Copy on read. */
@@ -776,8 +1102,117 @@ interface DrawSession {
    * are collected and rethrown after all listeners run.
    */
   onChange(listener: (session: DrawSession) => void): () => void;
+  /**
+   * Subscribe to the committed snapshot — the single delivery channel for the
+   * `GraphicSnapshot<ControlMeasure>` this session ever commits (#197, mirroring
+   * `TransformSession.onCommit` #191). Fires exactly once, synchronously from
+   * within the commit that produced it (`session.commit()`, dblclick, or a
+   * second click/tap on the finishing vertex), with the same reference the
+   * outer `draw` promise resolves with — the committed snapshot, not just the
+   * measure. Never fires on abort.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onCommit(handler: (snapshot: GraphicSnapshot<ControlMeasure>) => void): () => void;
+  /**
+   * Subscribe to the session's settlement — the lifecycle complement of
+   * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
+   * the session is *over* and why (#197, mirroring
+   * `TransformSession.onSettled` #194). Fires exactly once, when the session
+   * settles by any path, commit or abort, with a `SettleReason`.
+   *
+   * - On the commit path it fires **after** [[onCommit]]'s emission.
+   * - On every path it fires **after** the facade has already cleared
+   *   `td.activeSession` — so fold-then-render works from inside the handler.
+   * - `reason` distinguishes commit from abort but is deliberately coarse —
+   *   no payload; the snapshot was already delivered through [[onCommit]].
+   *
+   * Registering after the session has already settled is **not** a no-op
+   * (unlike [[onChange]] / [[onCommit]]): the handler is invoked
+   * asynchronously (on a microtask) exactly once with the settle reason;
+   * unsubscribing before that microtask runs cancels the delivery.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]] / [[onCommit]]. Returns an unsubscribe function.
+   */
+  onSettled(handler: (reason: SettleReason) => void): () => void;
+  /**
+   * Subscribe to the continuous stream of rubber-band pointer ticks while the
+   * draw is live — contrast [[onChange]], which fires once per committed
+   * point. `start` fires on the first rubber-band tick, `move` on every
+   * subsequent tick; a click that commits a point does not itself emit — the
+   * next rubber-band tick after it does. `end` fires exactly once, when the
+   * session settles (commit or abort).
+   *
+   * `points` is the committed points with the live rubber-band point spliced
+   * in at its insertion index; `pointIndex` is that index.
+   *
+   * Listener exceptions are collected; after every listener has run, they
+   * are rethrown (one if single, `AggregateError` otherwise) — mirrors
+   * [[onChange]]. Returns an unsubscribe function; registering after the
+   * session has settled returns a no-op unsubscribe and the listener never
+   * fires.
+   */
+  onTransientChange(listener: (event: TransientChangeEvent) => 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
 //#region src/tactical-draw/tactical-draw.d.ts
 /**
  * Host-supplied layer slot ids. Any omitted slot is allocated by the façade and
@@ -785,12 +1220,32 @@ interface DrawSession {
  */
 interface TacticalDrawLayerOptions {
   graphics?: LayerId;
+  /**
+   * Passive selection-highlight outlines ({@link TacticalDraw.setHighlightedGraphics}).
+   * Resolved immediately above `graphics` so highlight boxes stack over base
+   * graphics but below the preview / guide / handles interaction chrome.
+   */
+  highlight?: LayerId;
   preview?: LayerId;
   guide?: LayerId;
   handles?: LayerId;
 }
+/**
+ * Result of {@link TacticalDraw.ownsInteractionAt} — which layer claimed the
+ * pixel and the feature that matched.
+ */
+interface InteractionHit {
+  /** Which TacticalDraw layer owns the pixel — topmost match wins. */
+  layer: "handles" | "preview" | "graphics";
+  /** The hit feature (do not mutate). */
+  feature: Feature;
+  /** Control-measure id when the hit feature belongs to one (graphics/preview parts). */
+  measureId?: string;
+}
 interface TacticalDrawOptions {
   layers?: TacticalDrawLayerOptions;
+  /** Optional renderer capability for first-class point symbols (ADR-0029). */
+  pointSymbols?: PointSymbolCapability;
   /**
    * Façade-level default style passed through to `renderControlMeasure` as the
    * third (lowest priority) style layer per StyleResolver (#44). Shallow-merged
@@ -811,6 +1266,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;
@@ -818,7 +1275,7 @@ interface EditOptions {
    * Called synchronously once when the edit starts, before any pointer event
    * is processed. Lets a host wire commit / cancel buttons to the active edit.
    */
-  onSession?: (session: EditSession) => void;
+  onSession?: (session: EditSession | GraphicEditSession<PointSymbol>) => void;
   /**
    * Default `true`. When `true`, a click on empty map (or on another graphics
    * layer measure) closes the active edit. Clicks on preview / handle
@@ -831,7 +1288,8 @@ interface EditOptions {
    * renders vertex / midpoint handles; `transform` renders the oriented
    * selection box — 4 corner scale handles, a rotate grip above the top edge,
    * and drag-anywhere-inside-the-box translate (ADR-0017). The two can be
-   * combined freely (the default does). `"delete"` is exclusive: it collapses
+   * combined freely (the default does). `"labeldrag"` opt-in enables repositioning
+   * rendered text labels. `"delete"` is exclusive: it collapses
    * the set to vertex-tap removal only. An unknown mode throws `TypeError`.
    */
   modes?: readonly EditMode[];
@@ -908,9 +1366,13 @@ type DrawMeasureDraft<K extends ControlMeasureKind = ControlMeasureKind> = {
 interface DrawOptions {
   signal?: AbortSignal;
   /**
-   * Called synchronously once when a variable-length draw starts, before any
-   * pointer event is processed. The session lets a host wire a Done/Cancel
-   * toolbar to the active draw. Ignored for fixed-length kinds.
+   * Called synchronously once when a draw starts, before any pointer event
+   * is processed. The session lets a host wire a Done/Cancel toolbar to the
+   * active draw and subscribe to live control-point / transient-geometry
+   * feedback. Surfaced for both variable- and fixed-length kinds — a
+   * fixed-length session auto-commits on the last required click, so its
+   * main value is `onTransientChange` (e.g. a live radius readout) and
+   * `abort()`.
    */
   onSession?: (session: DrawSession) => void;
   /**
@@ -950,6 +1412,7 @@ interface DrawOptions {
 declare class TacticalDraw {
   private readonly adapter;
   private readonly graphicsLayer;
+  private readonly highlightLayer;
   private readonly previewLayer;
   private readonly guideLayer;
   private readonly handlesLayer;
@@ -957,6 +1420,10 @@ declare class TacticalDraw {
   private readonly graphicsStyle;
   private readonly defaultInteractionStyle;
   private readonly generateId;
+  private readonly pointSymbols;
+  private snappingOptions;
+  private readonly resolveSnap;
+  private readonly graphicStack;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -971,7 +1438,7 @@ declare class TacticalDraw {
    * Tracked alongside `activeInteraction` whenever the interaction is a group
    * transform (`editMany`). The `render()` / view-change paths need every
    * member's id (to exclude all of them from reconcile) — mirrors `activeEdit`
-   * but for `TransformHandle`'s `measureIds` array.
+   * but for `TransformHandle`'s `graphicIds` array.
    */
   private activeTransform;
   /**
@@ -982,7 +1449,7 @@ declare class TacticalDraw {
    */
   private activeTransformSessionRef;
   /**
-   * Host pick handlers registered via `td.onPick` / `td.onMeasurePick`. The
+   * Host pick handlers registered via `td.onPick` / `td.onGraphicPick`. The
    * façade subscribes once to `adapter.onPick` per layer and routes events
    * through this map so that close-then-pick ordering during an active edit can
    * be enforced (issue #52).
@@ -1000,38 +1467,96 @@ declare class TacticalDraw {
   private idCounter;
   private editCounter;
   private transformCounter;
+  /** Snapshot of the host's latest authoritative Graphic membership and order. */
+  private lastRenderedMeasures;
+  private snapGeometryFeatures;
   /**
-   * Snapshot of the host's last `render()` argument. The edit slice uses it
-   * to recompute the graphics-layer state during a lift / restore — the
-   * façade owns the policy because controllers shouldn't need to know the
-   * surrounding collection state.
+   * Rendered graphics-layer groups, keyed on Graphic snapshot identity. See
+   * {@link renderGraphicGroup} for the invalidation contract; swapped for a
+   * fresh map (not cleared entry-by-entry) so stale entries are collectable.
    */
-  private lastRenderedMeasures;
-  constructor(adapter: MapAdapter, options?: TacticalDrawOptions);
+  private graphicGroupCache;
   /**
-   * Render `measures` into features and write them to the graphics layer.
-   * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
-   * resolved against the live map. Callers own any edit-exclusion policy — see
-   * `render()` (excludes the edited measure, owned by the preview layer) versus
-   * `restoreOriginalToGraphics` (no exclusion, the edit is ending).
+   * Last {@link PointSymbolCapability.generation} observed from `pointSymbols`,
+   * initialised from the capability at construction. Compared at the top of
+   * every {@link reconcileGraphicsStack} so a host calling `invalidate()` after
+   * changing renderer-global config (e.g. milsymbol options) drops the render
+   * cache even though the Graphic snapshots handed to `render()` are
+   * unchanged — otherwise the cache would keep serving pre-invalidation
+   * output and the capability would never be re-consulted. `undefined` when
+   * there is no capability, or the capability doesn't expose `generation`.
    */
-  private renderMeasuresToGraphics;
+  private lastSeenPointSymbolGeneration;
+  /**
+   * Ids of graphics currently carrying a passive selection-highlight outline
+   * ({@link setHighlightedGraphics}). Declarative set-replace, no session —
+   * re-projected on every view change and re-evaluated at the end of every
+   * `render()` so outlines track geometry, style, and dropped graphics.
+   */
+  private highlightedIds;
+  /**
+   * Whether the highlight layer currently holds any outline. Lets
+   * `renderHighlights` skip a redundant empty write on every view change /
+   * render while no highlights are set, but still emit the one clearing write
+   * that removes outlines when the set transitions to empty.
+   */
+  private hasHighlightOutlines;
+  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 one atomic Graphic group for the engine-neutral graphics stack,
+   * reusing the previous render when nothing that feeds it has changed.
+   *
+   * The cache is keyed on the Graphic snapshot's object identity: hosts hand
+   * `render()` a fresh object whenever a graphic's data changes, so a changed
+   * graphic misses by construction. (A host that mutates a Graphic in place and
+   * re-renders the same reference is outside the contract — `render()` has
+   * always been documented as taking snapshots.) Rendered output also depends
+   * on live view state and on the resolved graphics style; the style is fixed
+   * at construction, and every view change drops the whole cache. Crucially,
+   * the view cannot change during a box drag (drag-pan is disabled), so every
+   * graphic outside the selection stays a cache hit for the whole gesture and
+   * per-frame reconcile cost becomes O(selection) rather than O(document).
+   */
+  private renderGraphicGroup;
+  /**
+   * Render a Graphic group from scratch and stamp it with a fresh revision,
+   * drawn from the module-scoped {@link nextGraphicGroupRevision} counter (see
+   * its doc comment for why it isn't a per-instance field).
+   */
+  private buildGraphicGroup;
+  /**
+   * Drop every cached render. Called whenever an input shared by all graphic
+   * renders changes — the live view state, or (via {@link reconcileGraphicsStack})
+   * the point-symbol capability's `generation`.
+   */
+  private invalidateGraphicGroupCache;
+  /** Submit one complete grouped desired state for the host stack plus overrides. */
+  private reconcileGraphicsStack;
+  /** Atomically publish several live renders into their host-owned Graphic slots. */
+  private publishWorkingGraphics;
+  /** Settle several stack overrides in one graphics-layer reconciliation. */
+  private settleWorkingGraphics;
   /**
    * Re-render the graphics layer on a view (zoom) change so pixel-denominated
-   * measures rescale live. Skipped entirely when nothing rendered carries a
-   * resolution-dependent size — meter geometry is zoom-independent, so a rebuild
-   * would be wasted layer writes. During an active edit the edited measure lives
-   * on the preview layer (lifted from graphics), so it is excluded here exactly
-   * as in `render()`; the preview's own view-change subscription rescales it.
+   * and not-yet-committed label-sized measures rescale live. Skipped entirely
+   * when nothing rendered still reads live view state — meter geometry with a
+   * captured label size is zoom-independent, so a rebuild would be wasted
+   * layer writes. A single-control-measure edit publishes through the stack
+   * coordinator; point symbols and transform members already present in the
+   * host stack do the same. Graphics without a host slot remain on preview.
    */
   private readonly handleViewChange;
   /**
-   * Every measure id currently lifted onto the preview layer by an active
-   * edit or group transform — excluded from `render()` / view-change
-   * reconciliation because the preview layer (not graphics) owns their
-   * working copy. Empty while idle.
+   * Every Graphic id owned by an active interaction. Used for highlight and
+   * pick routing; not every such Graphic is excluded from stack reconciliation.
    */
   private excludedInteractionIds;
+  /** Interaction ids still rendered on the legacy preview surface. */
+  private graphicsStackExcludedIds;
   /**
    * Live member ids of the active group transform, or `undefined` when none.
    * Falls back to the session ref because `onSession` fires from inside the
@@ -1045,27 +1570,55 @@ declare class TacticalDraw {
    * Idempotent. Throws synchronously on duplicate measure ids *before*
    * mutating any layer. An empty list before any prior render is a no-op.
    *
-   * Cross-layer semantics with an active edit (issue #51):
-   *  - The measure under edit is **excluded** from the reconcile pass — the
-   *    preview layer owns its working copy and the lift on the graphics layer
-   *    must stay in place.
+   * Cross-layer semantics with an active edit:
+   *  - The stack coordinator replaces the edited Graphic's host-owned slot
+   *    with its working render; membership and order remain host-authoritative.
    *  - If the edited measure is absent from `measures`, the pending `edit`
    *    promise rejects on the **next microtask** with reason `"removed"`.
    *    `render` itself returns normally so host collection ops stay synchronous.
-   *  - If the edited measure is present and its `style` changed, the preview
-   *    picks up the new style on this render. `controlPoints` changes on the
+   *  - If the edited measure is present and its `style` changed, its working
+   *    group picks up the new style on this render. `controlPoints` changes on the
    *    edited measure are routed nowhere — the user's in-flight drag is never
-   *    yanked out from under them.
+   *    yanked out from under them. A point symbol's complete working group remains
+   *    authoritative until settle, including any changed icon resource.
    *
    * Cross-layer semantics with an active draw: `render` only touches the
    * graphics layer, so the draw's preview is undisturbed.
    *
    * Reentrancy: calling `td.render(...)` from inside `EditSession.onChange` is
-   * safe — `render` never re-enters the active edit or its preview / handle
-   * layers (the only edit-facing side effect, `notifyExternalMeasure`, is a
+   * safe — `render` never re-enters the active edit or its handle layer (the
+   * only edit-facing side effect, `notifyExternalMeasure`, is a
    * pure style replay).
    */
-  render(measures: readonly ControlMeasure[]): void;
+  render(measures: readonly Graphic[]): void;
+  /**
+   * Replace the passive selection-highlight set with `ids`. Declarative and
+   * idempotent (mirrors {@link render}): a non-interactive outline box is drawn
+   * around each still-rendered graphic on the dedicated highlight layer — no
+   * draw / edit / transform session, no promise, no pick subscription. Passing
+   * `[]` clears every highlight. Unknown ids and ids currently active in an
+   * active edit / transform session are skipped (the live session's own visuals
+   * supersede the passive outline). Hosts use it for Excalidraw-style
+   * "locked selection" chrome.
+   */
+  setHighlightedGraphics(ids: readonly string[]): void;
+  /**
+   * Project the current {@link highlightedIds} into one outline `LineString`
+   * per graphic and reconcile them onto the highlight layer. Idempotent and
+   * grouped by graphic id, so desired-state replacement removes stale outlines
+   * and an unchanged set is a cheap no-op write. Skips ids that are
+   * unknown (not in the last render) or active in an interaction session, and
+   * bails gracefully when the adapter cannot invert pixels to coordinates
+   * (`getCoordinateFromPixel` is optional in the MapAdapter ABI).
+   */
+  private renderHighlights;
+  /**
+   * Fit the passive-highlight transform box for one graphic: the point-symbol
+   * footprint for symbols, the snug text footprint for Text graphics, and the
+   * projected-geometry bounding box (at the current bearing) for every other
+   * control measure. Returns `null` when nothing projects this frame.
+   */
+  private highlightBoxForGraphic;
   /**
    * Nested-call guard + preempt, shared by `draw` and `edit`. Returns a
    * pre-rejected promise when called re-entrantly from inside another
@@ -1100,75 +1653,102 @@ declare class TacticalDraw {
    */
   private trackTransformSession;
   /**
-   * Start an interactive draw. Fixed-length kinds commit automatically on the
-   * last required click. Variable-length kinds surface a `DrawSession` via
-   * `opts.onSession` and commit on `session.commit()`, `dblclick`, or a second
-   * click on the last added control point. All paths reject with
-   * `TacticalDrawAbortError` on signal / Escape / destroy / `session.abort()`.
+   * Start an interactive draw. Both fixed- and variable-length kinds surface
+   * a `DrawSession` via `opts.onSession`. Fixed-length kinds commit
+   * automatically on the last required click; variable-length kinds commit
+   * on `session.commit()`, `dblclick`, or a second click on the last added
+   * control point. All paths reject with `TacticalDrawAbortError` on
+   * signal / Escape / destroy / `session.abort()`.
+   *
+   * `DrawSession.onCommit` is the single delivery channel for the committed
+   * snapshot and `DrawSession.onSettled` is the lifecycle signal for when the
+   * session is over and why (#197) — together they make the returned promise
+   * non-load-bearing for hosts that adopt them. `DrawSession.onTransientChange`
+   * streams live rubber-band geometry while the draw is in flight, for both
+   * kinds of session.
    */
-  draw<K extends ControlMeasureKind>(draft: DrawMeasureDraft<K>, options?: DrawOptions): Promise<ControlMeasureSnapshot<K>>;
+  draw(draft: DrawPointSymbolDraft, options?: DrawOptions): Promise<GraphicSnapshot<PointSymbol>>;
+  draw<K extends ControlMeasureKind>(draft: DrawMeasureDraft<K>, options?: DrawOptions): Promise<GraphicSnapshot<ControlMeasure<K>>>;
   /**
    * Start an interactive edit on a single control measure. Returns a Promise
-   * that resolves with a `ControlMeasureSnapshot` of the working state on
+   * that resolves with a `GraphicSnapshot<ControlMeasure>` of the working state on
    * `session.close()` and rejects with `TacticalDrawAbortError` on
    * signal / Escape / destroy / preempt / `session.abort()`.
    *
    * Default click-away (`closeOnClickAway: true`) closes the edit on a click
    * outside the preview / handle features. Hosts that own close policy pass
    * `false`.
+   *
+   * `EditSession.onCommit` is the single delivery channel for the committed
+   * snapshot and `EditSession.onSettled` is the lifecycle signal for when the
+   * session is over and why (#197) — together they make the returned promise
+   * non-load-bearing for hosts that adopt them.
    */
-  edit(measure: ControlMeasure, options?: EditOptions): Promise<ControlMeasureSnapshot>;
+  edit(graphic: PointSymbol, options?: EditOptions): Promise<GraphicSnapshot<PointSymbol>>;
+  edit(measure: ControlMeasure, options?: EditOptions): Promise<GraphicSnapshot<ControlMeasure>>;
   /**
    * Start an interactive group transform (multi-select) over `measures`
-   * (ADR-0017 "Multi-select" slice). Every member is lifted onto the shared
-   * preview layer; the box (corner scale, rotate grip, drag-anywhere body
-   * translate) applies rigidly to all of them at once. Returns a Promise that
-   * resolves with `ControlMeasureSnapshot[]` on `session.close()` and rejects
+   * (ADR-0017 "Multi-select" slice). Every host-provided member stays in its
+   * Graphic-stack slot; only a member without a host slot uses preview. The box
+   * (corner scale, rotate grip, drag-anywhere body translate) applies rigidly
+   * to all of them at once. Returns a Promise that
+   * resolves with `GraphicSnapshot<ControlMeasure>[]` on `session.close()` and rejects
    * with `TacticalDrawAbortError` on signal / Escape / destroy / preempt /
-   * `session.abort()`. Key the resolved snapshots by `snapshot.measure.id`:
-   * the member set is mutable (`session.setMembers`, #187) so snapshot arrays
+   * `session.abort()`. Key the resolved snapshots by `snapshot.graphic.id`:
+   * the member set is mutable (`session.setGraphics`, #187) so snapshot arrays
    * are id-keyed, not index-aligned with this input. The promise resolves with
    * the members in the set at close time; a member removed mid-session had its
-   * exit snapshot returned from the `setMembers` call that removed it.
+   * exit snapshot returned from the `setGraphics` call that removed it.
    *
    * `measures.length` must be >= 1; a single-element array behaves like an
    * `edit` with only `transform` mode. Throws `TypeError` synchronously (before
    * any preemption) for an empty array or duplicate ids.
    *
    * For a selection that changes over time (shift-click toggle, marquee
-   * replace), prefer [[syncTransformMembers]] over hand-rolling the
+   * replace), prefer [[syncTransformGraphics]] over hand-rolling the
    * live-session-vs-fresh-`editMany` branch, and subscribe to
-   * `TransformSession.onCommit` as the single fold path for exit snapshots.
-   */
-  editMany(measures: ControlMeasure[], options?: EditManyOptions): Promise<ControlMeasureSnapshot[]>;
-  /**
-   * One-call selection-sync: mutate the live group transform's member set in
-   * place, or start a fresh `editMany` when no transform is live (#191). This
-   * owns the "live session → `setMembers`, else → `editMany`" branch that every
-   * host otherwise hand-rolls against `activeTransformSession`.
+   * `TransformSession.onCommit` as the single fold path for exit snapshots
+   * and `TransformSession.onSettled` as the lifecycle signal for when the
+   * session is over and why.
+   */
+  editMany(measures: ControlMeasure[], options?: EditManyOptions): Promise<GraphicSnapshot<ControlMeasure>[]>;
+  editMany(graphics: Graphic[], options?: EditManyOptions): Promise<GraphicSnapshot[]>;
+  /**
+   * One-call selection-sync: mutate a live transform's member set in place, or
+   * start a fresh `editMany` when none is live (#191). Any mix of control
+   * measures and point symbols is handled by the one Graphic-typed session
+   * (ADR-0032): a point symbol joins or leaves the live session exactly like a
+   * measure via `setGraphics`, preserving box angle, size anchor, and history
+   * baseline — no preempt-and-restart. A point symbol in the selection with no
+   * point-symbol capability configured throws `PointSymbolCapabilityRequiredError`
+   * synchronously (from `setGraphics` on a live session, or from `editMany` on a
+   * fresh one).
    *
    * The facade knows session liveness synchronously — `activeTransformSessionRef`
    * is cleared inside the settle path, before control returns to host code — so
-   * unlike a host's own `activeTransformSession ? setMembers : editMany` check,
+   * unlike a host's own `activeTransformSession ? setGraphics : editMany` check,
    * this can never observe a stale ref pointing at an already-settled session.
    * The settled-race fall-through hosts had to hand-roll for that gap is owned
-   * here instead: a `setMembers` call that (implausibly) still returns
+   * here instead: a `setGraphics` call that (implausibly) still returns
    * `undefined` falls through to a fresh `editMany` rather than silently
    * dropping the selection.
    *
-   * `measures: []` closes any live session (committing every member) and is a
+   * `graphics: []` closes any live session (committing every member) and is a
    * no-op while idle. With a live session, `options` is ignored — session-scoped
    * state (`sizeAnchor`, box angle, close-on-click-away policy) is sticky per
-   * `setMembers`'s contract; `options` applies only when this call starts a
+   * `setGraphics`'s contract; `options` applies only when this call starts a
    * fresh `editMany`. Exit snapshots are delivered via the session's
-   * `onCommit` — subscribe once in `options.onSession`. The underlying
-   * `editMany` promise is owned by the facade; its abort rejections are
-   * swallowed here (non-abort errors surface as unhandled rejections). Throws
-   * `TypeError` synchronously on duplicate ids, from either path. Starting a
-   * fresh transform preempts any other in-flight draw/edit exactly like
-   * `editMany`.
-   */
-  syncTransformMembers(measures: readonly ControlMeasure[], options?: EditManyOptions): void;
+   * `onCommit` — subscribe once in `options.onSession`. Session lifecycle —
+   * including an Escape / preempt / destroy abort the host did not itself
+   * initiate — is observed via the session's `onSettled` (#194); together
+   * `onCommit` and `onSettled` make the underlying `editMany` promise
+   * irrelevant to hosts. That promise is owned by the facade; its abort
+   * rejections are swallowed here (non-abort errors surface as unhandled
+   * rejections). Throws `TypeError` synchronously on duplicate ids, from
+   * either path. Starting a fresh transform preempts any other in-flight
+   * draw/edit exactly like `editMany`.
+   */
+  syncTransformGraphics(graphics: readonly Graphic[], options?: EditManyOptions): void;
   /**
    * Subscribe to picks on committed control measures.
    *
@@ -1180,7 +1760,7 @@ declare class TacticalDraw {
    * Returns an idempotent unsubscribe function. An optional `signal` removes
    * the handler when aborted.
    */
-  onMeasurePick(handler: PickHandler, opts?: PickOptions): () => void;
+  onGraphicPick(handler: PickHandler, opts?: PickOptions): () => void;
   /**
    * Subscribe to pick events on `layerId`. Routed through the façade so the
    * close-then-pick contract (issue #52) is observable: when an active edit
@@ -1192,6 +1772,51 @@ declare class TacticalDraw {
    * Returns an unsubscribe function. Optional `signal` mirrors `adapter.onPick`.
    */
   onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
+  /**
+   * Stateless hit test answering "does TacticalDraw own the pixel at
+   * `pixel`?" — for hosts composing their own click-away / deselection logic
+   * (issue #216) alongside `TacticalDraw`'s draw/edit sessions. Today hosts
+   * hack this together from the `@internal` `layerIds` plus engine-specific
+   * layer queries; this is the supported replacement.
+   *
+   * Tests, topmost first, the three interactive layers — `handlesLayer`,
+   * then `previewLayer`, then `graphicsLayer` — against each layer's current
+   * `adapter.getLayerFeatures(...)` cache. The `guideLayer` is deliberately
+   * excluded: it is non-interactive draw-guide scaffolding, never a
+   * legitimate "owned" click target. Within each layer, candidates follow
+   * the shared visible-intent ranking (direct marks, then filled interiors,
+   * then inferred outline-only reach, distance within direct marks, then
+   * visual topmost order) — this explicit-affordance layer order is the
+   * tier above all of it.
+   *
+   * `preview` and `graphics` each get a label text-extent fallback after the
+   * geometry pass misses on that layer: for every `Point` feature carrying a
+   * string `properties.text`, the anchor is projected and
+   * `fitLabelBoxFromFeature` (shared with the edit controller's `pickLabel`,
+   * see commit f908434) estimates the rendered text's box; a pixel inside
+   * that box counts as owned even though it's off the anchor point itself.
+   * This matters most for the active preview, since a click can land
+   * anywhere across a rotated/offset label during an edit.
+   *
+   * `tolerance` defaults to `pickHitTolerance(options?.originalEvent)` —
+   * pass the host's raw click event as `originalEvent` to get the same
+   * pointer-type-aware tolerance (4px mouse/pen, 12px touch) `onPick` uses;
+   * pass an explicit `tolerance` to override it outright.
+   *
+   * `measureId` is set when the hit feature resolves to a control-measure id
+   * via `tryControlMeasureIdFromFeature` — present for graphics/preview
+   * parts, generally absent for handles.
+   *
+   * This is a pure synchronous query over adapter-cached state: it does not
+   * depend on `onPick`/`"click"` dispatch having run first, so it is safe to
+   * call from any host click handler regardless of ordering relative to
+   * TacticalDraw's own pick/click pipeline.
+   */
+  ownsInteractionAt(pixel: PixelCoordinate, options?: {
+    tolerance?: number;
+    originalEvent?: unknown;
+  }): InteractionHit | null;
+  private toInteractionHit;
   /**
    * Abort the in-flight draw or edit. The default `"session"` reason matches
    * `DrawSession.abort()` / `EditSession.abort()`.
@@ -1203,7 +1828,7 @@ declare class TacticalDraw {
    * The live variable-draw or edit session, or `null` while idle and during
    * fixed-length draws. Safe to read after `destroy()`.
    */
-  get activeSession(): DrawSession | EditSession | null;
+  get activeSession(): DrawSession | EditSession | GraphicEditSession<PointSymbol> | null;
   /**
    * The live `editMany` group-transform session, or `null` while idle (and
    * during any other interaction). Separate from `activeSession` because
@@ -1230,6 +1855,7 @@ declare class TacticalDraw {
   /** @internal — exposed for tests and future controllers. */
   get layerIds(): {
     graphics: LayerId;
+    highlight: LayerId;
     preview: LayerId;
     guide: LayerId;
     handles: LayerId;
@@ -1241,6 +1867,7 @@ declare class TacticalDraw {
    */
   private applyGuideStyle;
   private baseGuideStyle;
+  private baseHighlightStyle;
   /**
    * Resolve handle slots (plus `boxOutline`) across built-in → façade →
    * per-call with per-slot, per-property shallow merge. Explicit `undefined`
@@ -1272,6 +1899,9 @@ declare class TacticalDraw {
 declare class TacticalDrawDestroyedError extends Error {
   constructor(message?: string);
 }
+declare class PointSymbolCapabilityRequiredError extends Error {
+  constructor();
+}
 //#endregion
 //#region src/tactical-draw/transform-box.d.ts
 /**
@@ -1307,6 +1937,15 @@ interface TransformBox {
   angle: number;
 }
 //#endregion
+//#region src/tactical-draw/point-symbol-rendering.d.ts
+interface PointSymbolFootprint {
+  box: TransformBox;
+  corners: PixelCoordinate[];
+}
+declare function effectivePointSymbolPixelSize(symbol: PointSymbol, resolution: number | undefined): number;
+/** Complete rotated logical footprint for selection and transform chrome. */
+declare function pointSymbolFootprint(symbol: PointSymbol, render: PointSymbolRender, adapter: Pick<MapAdapter, "getBearing" | "getPixelFromCoordinate" | "getResolution">): PointSymbolFootprint | null;
+//#endregion
 //#region src/world-wrap.d.ts
 /**
  * Shift `lng` by whole world widths (360°) onto the copy nearest `refLng`.
@@ -1321,4 +1960,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, type DrawMeasureDraft, type DrawOptions, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type GuideStyle, type HandleStyle, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointerCallback, PointerCallbackHub, type PointerEventInfo, 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, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, ignoreAbort, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, 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 FeatureGroup, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GuideStyle, HATCH_PATTERNS, type HandleStyle, type HatchPattern, type IconResource, type InteractionHit, type InteractionStyle, type LabelExtent, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type MergedPickFeature, type NativeEventEntry, type PickCandidate, type PickCandidateHit, type PickCandidateHitKind, type PickCandidateInput, type PickEvaluationContext, type PickEvent, type PickHandler, type PickOptions, type PickPointerType, 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 ResolvedPickPresentation, type RotatedScreenBounds, type ScreenBounds, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, type StyleOptions, TEXT_HALO_COLOR, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextSizeProps, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, evaluatePickCandidates, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pickPointerType, pointSymbolFootprint, renderOrderToVisualOrder, resizePointSymbolSize, resolveGroundTextSizePixels, resolvePickPresentation, resolveTextHaloWidth, resolveTextSizePixels, tryControlMeasureIdFromFeature };